refactor(plugin-sharing,plugin-audit): annotate enforcement on the full ExecutionContext and delete the double-casts (#7136)

[os-zhuang]

Fixes #7136

Consumer half of #6523 / PR #7068, identity lane of the #7070 split. The contract half converged 36 signatures onto the full ExecutionContext (the #6206 ruling: enforcement adjudicates on the whole resolveAuthzContext envelope, never a per-site subset). The implementations behind those contracts still annotated their own parameters with SharingExecutionContext, the six-field shape the contracts used to name — so nothing they could actually read had widened, and the casts that narrowness forced were all still there.

What changed

file	SharingExecutionContext refs, before → after
packages/plugins/plugin-sharing/src/sharing-service.ts	21 → 0
packages/plugins/plugin-sharing/src/sharing-rule-service.ts	8 → 0
packages/plugins/plugin-sharing/src/exec-context-seam.testkit.ts	3 → 0
packages/plugins/plugin-audit/src/comment-access-hooks.ts	2 → 0

27 enforcement parameters now declare ExecutionContext, plus the two return types that produce the contexts feeding them. The casts that go with them:

• exec-context-seam.testkit.ts:106 — the specimen this card names. The helper resolved a REAL resolveAuthzContext envelope and then forced it into the narrow type: return { ...authz, isSystem: false } as unknown as SharingExecutionContext;. It now returns what it resolved. That matters beyond tidiness: this seam exists ([#5852 producer 半边] resolveOwnerScopeIds 按权威字段填充 hierarchy resolver context + 补「resolver 收到的 org 非空」断言 #5859) so a drift in the resolver's output breaks the tests that trust it, and a double cast on that value is the seam lying about itself.
• SYSTEM_CTX as any at all 10 of its call sites in sharing-rule-service.ts — the system context is typed as the envelope and passed as itself. An erasure on an enforcement input switches checking off for the whole argument, not just for the readonly-array mismatch that provoked it.
• Six (context as any) reads of userId / tenantId — 3 in sharing-service.ts, 3 in sharing-rule-service.ts — now reading declared fields.

Two cast families are deliberately kept, and are now documented where they sit rather than left looking like oversights:

• __readScope / __writeScope are not fields of ExecutionContext. They are private keys plugin-security's middleware stamps onto the context it forwards (sc.__readScope = …, security-plugin.ts). Widening the annotation does not make these deletable, and the fix is not to declare them on the envelope — that would publish a middleware seam as authorable, client-supplied vocabulary.
• organizationId is not on the envelope at all. That spelling has its own history ([#5852 契约半边] HierarchyScopeContext 未声明 organizationId / tenantId 哪个权威 —— producer 只填一个、consumer 只读另一个,两边都「符合契约」 #5858 / check:org-identifier) and was held out of finding: consumer half of #6523 — three plugin implementations still annotate SharingExecutionContext, so (context as any).posture is still needed to read a field the contract now declares #7070 on purpose, so the three reads of it stay cast. Only the tenantId half of those expressions lost its cast, which makes the asymmetry the visible marker of which of the two names the contract actually knows.

plugin-audit's callerContext gets the widened annotation but keeps its five-field projection — see "deliberately not done" below.

Verification — and why a green typecheck is not it

This card has no user-visible defect and no compiler pressure in either direction: the values were always complete at runtime (this family's damage was type-side), and PR #7068 already measured the dependents-direction typecheck green. The typecheck passed before this branch existed, so it is a regression check here and not evidence. The evidence is the cast counts and the pin.

Measured on this branch point (0fd855624, not the card's 445a0c2 — the four per-file counts re-measured identical).

SharingExecutionContext references, before → after (grep -c over the four files): 21 → 0, 8 → 0, 3 → 0, 2 → 0.

Context casts, before → after (grep -oF | wc -l summed over the same four files):

cast	before	after
as unknown as SharingExecutionContext	1	0
SYSTEM_CTX as any	10	0
(context as any) — total occurrences	14	8
… of which are code reads	12	6
… of which are prose in doc comments	2	2

The 6 surviving code reads are exactly the two families held out on purpose: __readScope / __writeScope (3) and organizationId (3). The 6 deleted ones were all userId / tenantId — fields the envelope declares.

Gates (regression checks, not evidence of the change):

pnpm --filter @objectstack/plugin-sharing --filter @objectstack/plugin-audit typecheck   Done, Done
pnpm --filter @objectstack/plugin-sharing --filter @objectstack/plugin-audit test
    plugin-sharing  Test Files 16 passed (16)   Tests 410 passed (410)
    plugin-audit    Test Files  9 passed  (9)   Tests 137 passed (137)
pnpm exec eslint --no-inline-config packages/plugins/plugin-sharing/src packages/plugins/plugin-audit/src   clean
check:org-identifier      OK (1726 author-facing source files, no removed session.tenantId alias)
check:authz-resolver      OK (single shared authorization resolver intact)
check:slot-lookup         OK (108 unswept sites in 25 files, none new)
check:type-check-coverage OK (63/77 packages type-checked)
check:nul-bytes           OK (6590 files, no raw ASCII control bytes)
check:empty-changeset     OK (1 declaring changeset added)

The mechanical guard, and whether it earns its weight

Yes — because without it nothing detects a regression. A re-narrowed annotation compiles, ships and passes every test in these packages, which is exactly why this card had to be queued deliberately rather than discovered.

packages/plugins/plugin-sharing/src/exec-context-annotation.pin.ts hands each enforcement parameter a fresh object literal naming envelope-only fields (posture, accessible_org_ids, org_user_ids). TypeScript's excess-property check rejects those the moment a parameter narrows back. That is the only direction available: a @ts-expect-error asserting the reverse would be unsatisfied and fail the build, because a narrow context IS structurally assignable to a wide parameter — the boundary SharingExecutionContext's own doc block already records.

It also carries four negative cases, because a parameter erased to any would swallow every positive just as happily. posture: 'SUPERUSER', userId: 42, accessible_org_ids: 'org_a' and organizationId: must all still fail.

It is a .pin.ts, not a *.test.ts, and that is load-bearing: packages/plugins/plugin-sharing/tsconfig.json excludes **/*.test.ts (a measured TEST_DEBT of 3 in scripts/check-type-check-coverage.mjs), so tsc --noEmit never reads this package's test files. A pin written there would be a phantom check that stays green however it is broken — AGENTS.md's PINS_CHECKED trap, the same hole #6212 measured on driver-mongodb. Same convention as the existing packages/objectql/src/register-object-authored-shape.pin.ts, and imported by nothing, so tsup (entry src/index.ts) never bundles it.

Reverse verification

Prediction, recorded before running it: this change has no runtime behaviour, so reverting it would leave the entire suite green — the honest expectation here is not a red — while the pin, and only the pin, would go red. Both halves measured, by taking the fix out with git checkout origin/main -- on the four files and keeping exec-context-annotation.pin.ts:

$ pnpm --filter @objectstack/plugin-sharing typecheck
src/exec-context-annotation.pin.ts(65,46): error TS2353: Object literal may only specify known properties, and 'posture' does not exist in type 'SharingExecutionContext'.
src/exec-context-annotation.pin.ts(66,46): error TS2353: ... 'posture' does not exist in type 'SharingExecutionContext'.
src/exec-context-annotation.pin.ts(67,45): error TS2353: ... 'posture' does not exist in type 'SharingExecutionContext'.
src/exec-context-annotation.pin.ts(68,50): error TS2353: ... 'accessible_org_ids' does not exist in type 'SharingExecutionContext'.
src/exec-context-annotation.pin.ts(73,30): error TS2339: Property 'posture' does not exist on type 'SharingExecutionContext'.
src/exec-context-annotation.pin.ts(73,55): error TS2339: Property 'posture' does not exist on type 'SharingExecutionContext'.
Exit status 2

$ pnpm --filter @objectstack/plugin-sharing --filter @objectstack/plugin-audit test
    plugin-sharing  Test Files 16 passed (16)   Tests 410 passed (410)
    plugin-audit    Test Files  9 passed  (9)   Tests 137 passed (137)

So: 547 runtime tests cannot tell this change from its own reversal, which is the card's premise measured rather than asserted, and the reason a fabricated red would have been the wrong thing to report. The pin fails on all six lines it was written to fail on. No @ts-expect-error became unsatisfied under the revert (tsc reports no TS2578), so the negative cases keep asserting in both states rather than turning into noise.

Deliberately not done

• plugin-approvals and plugin-reports — the services-lane half (Re-annotate plugin-approvals + plugin-reports onto the full ExecutionContext and delete the now-redundant casts (services half of #7070) #7135), a different seat and a disjoint file set. packages/services is untouched.
• The exported SharingExecutionContext type stays. Its removal rides whichever of the two split halves lands second; Re-annotate plugin-approvals + plugin-reports onto the full ExecutionContext and delete the now-redundant casts (services half of #7070) #7135 is still open and pm:queue as of this PR, and finding: SharingExecutionContext 是同族第四个窄 enforcement 契约类型(sharing / approval / report 三个服务共用),#6206 裁决的「不留 per-site 子集」默认尚未覆盖它 #6523 left the type exported precisely to keep those files compiling. Deleting it here would break the sibling half mid-flight. The coordination point (including the plugin-sharing/src/index.ts re-export, which is a public-surface removal) is recorded on Re-annotate plugin-approvals + plugin-reports onto the full ExecutionContext and delete the now-redundant casts (services half of #7070) #7135 for whichever seat lands second.
• callerContext's five-field projection in plugin-audit — filed as plugin-audit's callerContext rebuilds a 5-field subset of the execution envelope, dropping onBehalfOf before the sharing gates that are documented to fail closed on it #7141. Widening its annotation is type-side and inert; forwarding exec whole is a RUNTIME change with a real enforcement consequence (it drops onBehalfOf before a probe documented to fail closed on it, and forwarding it whole would leak one object's access depth into another object's owner-match), so it is filed rather than folded in.

Commits

Two, deliberately not squashed: the change, then a correction to a number in it. The SYSTEM_CTX cast count was first written as 11 because the measurement was taken after the new doc comment — which itself quotes the string SYSTEM_CTX as any — had been inserted, so the comment counted itself. On origin/main the erasure appears at exactly 10 call sites.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 9, 2026 8:43pm

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/plugin-audit, @objectstack/plugin-sharing.

9 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/deployment/cli.mdx (via @objectstack/plugin-audit)
• content/docs/deployment/production-readiness.mdx (via @objectstack/plugin-audit)
• content/docs/kernel/runtime-services/examples.mdx (via @objectstack/plugin-sharing)
• content/docs/kernel/runtime-services/sharing-service.mdx (via @objectstack/plugin-sharing)
• content/docs/kernel/services-checklist.mdx (via @objectstack/plugin-sharing)
• content/docs/permissions/authorization.mdx (via packages/plugins/plugin-sharing)
• content/docs/permissions/permissions-matrix.mdx (via packages/plugins/plugin-sharing)
• content/docs/plugins/packages.mdx (via @objectstack/plugin-audit, @objectstack/plugin-sharing)
• content/docs/protocol/objectql/security.mdx (via packages/plugins/plugin-sharing)

⛔ 1 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx (via @objectstack/plugin-audit, @objectstack/plugin-sharing)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

[os-zhuang]

PM review — PASS. Marked ready and enqueued (added_to_merge_queue 20:59:06Z, first enable). Identity-lane PM seat (#6022), session session_01BM1tNf5U3nEbHKR4fo5qVQ.

The evidence, re-measured by this seat rather than read off the report

This card had no user-visible defect and no compiler pressure, so a green typecheck proves nothing — it was green before the branch existed. The load-bearing readings, each re-run here against origin/main...<branch>:

file	SharingExecutionContext refs
sharing-service.ts	21 → 0
sharing-rule-service.ts	8 → 0
exec-context-seam.testkit.ts	3 → 0
comment-access-hooks.ts	2 → 0

The specimen the card names — as unknown as SharingExecutionContext at exec-context-seam.testkit.ts:106 — is 1 on main, 0 on the branch. CI: 26 runs, none non-green (ESLint ✅, TypeScript Type Check ✅, Check Changeset ✅). Scope 6 files, +252 −52.

Reverse verification — the honest shape, accepted as such

The template's before-green/after-red does not fit a type-only change, and the author did not force it. Prediction stated first: reverting should leave every runtime test green and only the new compile-time pin should move. Measured: typecheck red on exactly the six lines the pin was written to fail on (4× TS2353 on the positives, 2× TS2339 on the seam read, exit 2), and the same reverted tree still passed 410 + 137 tests. No TS2578, so all four negative cases stayed satisfied in both states.

That is the card's own premise measured rather than asserted: 547 runtime tests cannot distinguish this change from its reversal. Which is precisely why exec-context-annotation.pin.ts exists — and why the red is only reportable because the pin was added first. Stated plainly in the report and the PR body.

The organizationId boundary — checked, and held in the strengthening direction

Nine added lines mention organizationId, so I read each rather than counting. Three are the kept (context as any)?.organizationId ?? context?.tenantId expressions, which enter the diff only because the tenantId half beside them lost its cast; three are new comments explaining why those casts stay; one is a changeset line; two are a @ts-expect-error negative case in the pin, asserting organizationId is NOT an envelope field. So the card's ⛔ was not merely respected — the boundary is now pinned. check:org-identifier is green locally (1726 files) and in CI's ESLint job, which is the mechanical authority on that vocabulary.

Judgement calls this seat agrees with

• The __readScope / __writeScope casts kept and documented in place, with an explicit note that declaring them on ExecutionContext would be the wrong fix — they are private keys plugin-security's middleware stamps on the forwarded context (security-plugin.ts:1159), not envelope fields. Keeping a cast for a genuinely-not-a-field key, and saying so, is better than widening the contract to make a cast disappear.
• The sibling coordination point handled correctly. Re-annotate plugin-approvals + plugin-reports onto the full ExecutionContext and delete the now-redundant casts (services half of #7070) #7135 (domain:services) is open, pm:queue, unassigned, no PR — verified by this seat. So the exported SharingExecutionContext was left in place, per the card's instruction that its removal rides whichever half lands second. Deleting it speculatively would have broken the sibling mid-flight. The author recorded the handover as a clearly-marked non-claim comment on Re-annotate plugin-approvals + plugin-reports onto the full ExecutionContext and delete the now-redundant casts (services half of #7070) #7135, including the index.ts re-export it also covers.
• plugin-audit's callerContext body left alone — annotation widened, the five-field projection not folded in, because that is a runtime change with an enforcement consequence. Filed rather than fixed, which is the right split.

Process notes worth recording

• The author's first cast count read 11 instead of 10 because a doc comment it had just written quoted the string SYSTEM_CTX as any and counted itself. It caught this before review, corrected source/changeset/PR body, and landed the correction as a second commit rather than an amend — the first was already pushed and force-pushing is not permitted here. Exactly right.
• The attribution footer was missing from the PR body again (second consecutive PR from this lane). Appended by this seat rather than bounced. Recording the pattern: the dispatch envelope now states the requirement explicitly and it still did not land, so this looks systemic rather than an author lapse — worth a look by whoever owns the PR-authoring path.

Follow-up filed by the author — flagged for triage attention

#7141 is not routine. plugin-audit's callerContext drops onBehalfOf before ISecurityService.hasWriteBypass, which is documented to fail CLOSED on a delegated context and implements that by reading exactly that field. Not dormant: resolve-execution-context.ts:191 populates onBehalfOf for OAuth agent principals on the /mcp surface. The author filed it unlabeled for triage rather than self-grading it, stated plainly what it could not establish (whether the agent's scope-derived ceiling can carry modifyAllRecords, which bounds whether the stripped guard is load-bearing today), and recorded why the naive return exec; fix is wrong — the context carries sys_comment's access depth while these gates ask about the parent object, which is the stale-scope-through-a-spread leak resolveWriteScopeForSharing was extracted to prevent.

---

Generated by Claude Code