fix(sharing): 记录删除时撤销该记录的全部 sys_record_share（不分 source）+ boot 期按记录存在性的孤儿清扫 (#5103) (#5196)

* fix(sharing): revoke every share on a deleted record, not just rule grants (#5103)

A `sys_record_share` row says "principal P has level L on (object O, record
R)". Delete R and the row describes nothing — yet it stayed in the table
forever.

#4779 (PR #5102) bound an `afterDelete` for this, but inside the sharing-RULE
package, where two conditions fenced it in: it revokes only `source: 'rule'`
rows, and `bindRuleHooks` binds only on objects that appear in
`sys_sharing_rule`. So an object using nothing but MANUAL shares had no delete
hook at all, and manual share + record delete = a permanent orphan.

Harm is bounded today only because record ids are never reused — an assumption
no gate enforces. A custom primary key, an import preserving ids, or any future
recycling turns those rows into real escalation: a new record on a recycled id
inherits the dead record's recipients.

Maintainer ruling (2026-08-04, on the issue): option A. Option B (a platform
polymorphic weak-reference cascade) is a separate engine-lane design card
(#5180); when it lands these hooks collapse into it.

- `record-share-cascade.ts` binds ONE global `beforeDelete`/`afterDelete` pair
  and judges the object's sharing posture from `sharingModel` metadata PER
  DELETE. Nothing is enumerated at boot, so nothing goes stale — an object that
  gains sharing at runtime is covered on its next delete with no rebind, which
  is a stronger answer to the ruling's hot-update requirement than a metadata
  subscription would have been. Bounded row sets are revoked synchronously and
  set-based; an unbounded delete queues an object-scoped orphan sweep rather
  than the rule path's revoke-then-regrant, which is unavailable here because
  nothing can re-create a manual share. System-context deletes cascade too.
- `SharingService.sweepOrphanedRecordShares` is the record-existence twin of
  `sweepOrphanedRuleGrants` (#4433) — that one asks whether the RULE row still
  exists and therefore can never see a manual share. Runs on
  `kernel:bootstrapped`, keyset-paged with one batched existence probe per
  object per page and a scan cap that reports itself. An object whose probe
  FAILS keeps its rows: "could not ask" is not "the record is gone".
- The `beforeDelete` row-set stash moves from `rule-hooks.ts` into
  `bulk-recompute.ts` beside its resolver, so both hook packages share one
  answer per write instead of resolving the same predicate twice.

Rule recompute still never touches a manual share (#5102's pin, re-asserted in
this branch's tests). Only the record's DELETION revokes it, and only because
there is no longer anything to have access to.

Fixes #5103

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015W6nhsDrz6zWQc8je12a1t

* fix(sharing): the deferred-sweep breadcrumb is info, not warn (#5103)

The rule path warns on its unbounded branch because recipients visibly lose
access to records they still qualify for until the re-grant lands. Nothing
equivalent happens here: the sweep only removes rows whose record is gone, so
a deferred reclaim takes nothing from a surviving record and has no
user-visible consequence. A warn on every predicate delete would only erode
the level (AGENTS.md's own caution against over-applying it). The sweep still
warns when it actually revokes rows.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015W6nhsDrz6zWQc8je12a1t

* docs(sharing): record why referential cascades are already covered (#5103)

`cascadeDeleteRelations` removes a `deleteBehavior: 'cascade'` child through
the public `delete()` rather than the driver, so a detail record swept away
with its master reaches this hook like any other delete. That is the fact
behind treating `controlled_by_parent` as sharing-capable: manual grants are
refused there, but the rule evaluator can still materialise rows under system
context, and this is the path that reclaims them.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015W6nhsDrz6zWQc8je12a1t

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/record-delete-share-cascade.md

@@ -0,0 +1,57 @@
+---
+"@objectstack/plugin-sharing": patch
+---
+
+fix(sharing): deleting a record now revokes every `sys_record_share` row on it, whatever the source (#5103)
+
+A share row says "principal P has level L on (object O, record R)". Delete R and
+the row describes nothing — yet until now it stayed in the table forever.
+
+#4779 (PR #5102) bound an `afterDelete` for this, but inside the sharing-RULE
+package, where two conditions fenced it in: it revokes only `source: 'rule'`
+rows, and it binds only on objects that appear in `sys_sharing_rule`. So an
+object that uses nothing but MANUAL shares — a `sharingModel: 'private'` object
+with no rule ever configured — had no delete hook at all, and **manual share +
+record delete = a permanent orphan**.
+
+Today the harm is bounded, and only because record ids are never reused: the
+`record_id IN (…)` predicate `buildReadFilter` emits matches nothing. Nothing
+enforces that assumption. A custom primary key, an import that preserves ids, or
+any future id recycling turns every one of those rows into a real privilege
+escalation — a new record landing on a recycled id inherits the dead record's
+recipients outright. Secondarily, `sys_record_share` grew without bound and
+Setup's Record Shares list showed rows pointing at nothing.
+
+**What changed**
+
+- **A record-delete cascade on every sharing-capable object.** `plugin-sharing`
+  binds one `beforeDelete`/`afterDelete` pair with no object filter and judges
+  the object's sharing posture from its `sharingModel` metadata *per delete*.
+  Nothing is enumerated at boot, so nothing goes stale: an object that gains
+  `sharingModel` at runtime is covered on its very next delete, with no rebind.
+  Bounded deletes (a scalar id, an `$in` list, or a predicate matching at most
+  1000 rows) are revoked synchronously and set-based; an unbounded one queues an
+  object-scoped orphan sweep instead. System-context deletes cascade too.
+- **A boot-time orphan sweep keyed on record existence.** On
+  `kernel:bootstrapped`, share rows whose RECORD no longer exists are revoked —
+  historical orphans, rows a failed hook missed, and the one posture the cascade
+  deliberately skips (an unmarked system object). This is a different question
+  from the existing `sweepOrphanedRuleGrants`, which asks whether the RULE row
+  still exists and therefore can never see a manual share. Bounded per boot:
+  keyset pages, one batched existence probe per object per page, and a scan cap
+  that reports when it stopped early. An object whose existence probe FAILS has
+  its rows left in place — "could not ask" is never read as "the record is gone".
+
+**What did not change**
+
+Rule *recompute* still never touches a manual share. That boundary (#5102) is
+the point: while the record exists, a manual grant is a human decision no rule
+evaluation may overrule. Only the record's DELETION revokes it, and only because
+there is no longer anything to have access to.
+
+New exports for hosts that compose the plugin by hand:
+`bindRecordShareCascade` / `unbindRecordShareCascade`,
+`objectCanCarryRecordShares`, `SharingService.revokeSharesForDeletedRecords`,
+`SharingService.sweepOrphanedRecordShares`, and `effectiveSharingModel`. Nothing
+was removed or renamed; the standard `SharingServicePlugin` composition needs no
+changes.

packages/plugins/plugin-sharing/src/bulk-recompute.ts

@@ -194,6 +194,70 @@ export async function resolveAffectedRows(
   }
 }
 
+/**
+ * [#4779] Shared-`HookContext` key holding the row set the write is about to
+ * change, stashed by the `before` hook for the `after` hook to consume.
+ *
+ * The stash is necessary, not a convenience: an update that moves rows OUT of
+ * a rule's criteria makes them unfindable by the write's own predicate the
+ * instant it lands, and a delete removes them outright — so `afterUpdate` /
+ * `afterDelete` are structurally too late to ask "which rows was this?".
+ * `ObjectQL.update()` / `.delete()` reuse ONE `HookContext` instance across
+ * each before/after pair (they mutate `ctx.event` in place), which is the same
+ * seam `primary-bu-projection.ts`'s `__primaryBuUserId` rides on.
+ *
+ * [#5103] Lives HERE, next to the resolver, rather than in `rule-hooks.ts`
+ * where it started: two independent hook packages now need the same answer for
+ * the same write (the rule recompute, and the record-delete share cascade),
+ * and each resolving it separately would double the predicate query on every
+ * bulk write for no gain — the row set is a property of the WRITE, not of
+ * either subscriber.
+ */
+export const AFFECTED_ROWS_STASH_KEY = '__sharingAffectedRows';
+
+/**
+ * Resolve (or reuse) the row set a `before` hook's write is about to change and
+ * park it on the shared `HookContext`.
+ *
+ * **Reuse is the point.** The first plugin-sharing `before` hook to run on a
+ * write resolves; every later one reads that answer back. Recomputing would be
+ * wasteful and — worse — could disagree, because a resolve issued after an
+ * earlier hook has already changed something is answering a different question.
+ *
+ * Never throws: `resolveAffectedRows` already fails safe to `unbounded`, and
+ * this adds the belt for a genuinely unexpected throw. "Unknown" must never
+ * degrade to "no rows" — that is the direction that silently skips cleanup.
+ */
+export async function stashAffectedRows(
+  engine: RecomputeEngine | { find?: RecomputeEngine['find'] },
+  objectName: string,
+  hookCtx: any,
+  logger?: MinimalLogger,
+): Promise<AffectedRows> {
+  const already = hookCtx?.[AFFECTED_ROWS_STASH_KEY] as AffectedRows | undefined;
+  if (already) return already;
+  let resolved: AffectedRows;
+  try {
+    resolved = typeof engine?.find === 'function'
+      ? await resolveAffectedRows(engine as RecomputeEngine, objectName, hookCtx, logger)
+      : { kind: 'unbounded', reason: 'resolve-failed', detail: 'engine has no find()' };
+  } catch (err: any) {
+    resolved = { kind: 'unbounded', reason: 'resolve-failed', detail: err?.message };
+  }
+  if (hookCtx && typeof hookCtx === 'object') hookCtx[AFFECTED_ROWS_STASH_KEY] = resolved;
+  return resolved;
+}
+
+/**
+ * What an `after` hook should act on. A missing stash means no `before` hook of
+ * ours ran for this write, which is not "nothing changed" — it is "we do not
+ * know", and it reads as `unbounded` so the caller takes its safe branch.
+ */
+export function readAffectedRows(hookCtx: any): AffectedRows {
+  return (hookCtx?.[AFFECTED_ROWS_STASH_KEY] as AffectedRows | undefined)
+    ?? { kind: 'unbounded', reason: 'resolve-failed', detail: 'no before-hook stash' };
+}
+
 /**
  * The asynchronous half of the ruling: re-grant after the synchronous revoke.
  *

packages/plugins/plugin-sharing/src/index.ts

@@ -13,8 +13,11 @@ export { SysRecordShare, SysSharingRule, SysShareLink } from './objects/index.js
 export { SysBusinessUnit, SysBusinessUnitMember } from '@objectstack/platform-objects/identity';
 export {
   SharingService,
+  effectiveSharingModel,
   type SharingEngine,
   type SharingServiceOptions,
+  type OrphanShareSweepOptions,
+  type OrphanShareSweepResult,
 } from './sharing-service.js';
 export {
   SharingRuleService,
@@ -43,10 +46,21 @@ export {
   RuleRegrantQueue,
   resolveAffectedRows,
   idsFromHookInput,
+  stashAffectedRows,
+  readAffectedRows,
+  AFFECTED_ROWS_STASH_KEY,
   type AffectedRows,
   type UnboundedReason,
   type RecomputeEngine,
 } from './bulk-recompute.js';
+export {
+  bindRecordShareCascade,
+  unbindRecordShareCascade,
+  objectCanCarryRecordShares,
+  orphanShareSweepQueue,
+  RECORD_SHARE_CASCADE_PACKAGE,
+  type CascadeEngine,
+} from './record-share-cascade.js';
 export {
   parseCriteria,
   isMatchAllCriteria,