refactor(plugin-approvals,plugin-reports): annotate enforcement onto the full ExecutionContext (#7135)

[os-help]

Fixes #7135

The services half of #7070, mirroring PR #7140 (the identity half, merged 2026-08-09). #6523 / PR #7068 converged 36 contract signatures onto the full resolveAuthzContext envelope, applying the #6206 ruling — enforcement adjudicates on the whole envelope, never a per-site subset. The implementations behind those contracts still annotated their own parameters with the six-field shape the contracts used to name, so nothing they could read had widened.

Premise re-verified on origin/main @ aeadbd6

The card's counts were measured @ 445a0c2 and the dispatching seat re-measured @ 6146b67. Both still hold at my branch point:

file	narrow-type refs before	after
packages/plugins/plugin-approvals/src/approval-service.ts	27	0
packages/plugins/plugin-reports/src/report-service.ts	14	0
packages/plugins/plugin-approvals/src/approval-node.ts	2	0

(Two doc-comment mentions of the old name survive, in prose explaining what each cast replaced.) After this PR the only remaining references repo-wide outside packages/spec are plugin-sharing/src/index.ts's re-export and a comment in plugin-sharing's pin.

What changed

• isOverrideActor() reads a declared posture. This is the load-bearing one the card names. That gate decides whether a platform or tenant admin may release a STUCK approval — one routed to an unstaffed position, which is the only in-product recovery from a permanently locked record — and it read the derived posture (ADR-0095) through an unchecked (context as any). An erasure sitting directly on an enforcement input: a mistyped rung would have compiled and silently denied every override.
• Both services' SYSTEM_CTX is typed as the envelope and passed as itself, retiring the SYSTEM_CTX as unknown as ... double casts at approval-service.ts:2773, 2813, 3259.
• The (context as any).userId / .tenantId reads in ApprovalService now read declared fields.
• OwnerContextResolver returns the envelope, which is what a scheduled report actually resolves for its owner (Security: MCP action surface must gate on ai.exposed — action bodies run trusted (unbounded RLS/FLS), so invoke-time is the only agent boundary (#2849) #2849 / Security: Reports surface ignores caller identity — cross-user/cross-tenant IDOR (read/delete any report) + scheduled reports bypass owner RLS #2980).
• 43 parameter/return positions across the three files now name ExecutionContext.

Scope held

• organizationId is untouched, per the boundary inherited from 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: it is not a field of the envelope at all, and that spelling has its own history ([#5852 契约半边] HierarchyScopeContext 未声明 organizationId / tenantId 哪个权威 —— producer 只填一个、consumer 只读另一个,两边都「符合契约」 #5858 / check:org-identifier). The four reads of it stay cast, and the asymmetry is now documented at each site — the tenantId half of each ?? chain lost its cast, the organizationId half did not, which makes visible which of the two names the contract actually knows. check:org-identifier is green.
• approval-node.ts:174 keeps a cast, and this is a correction to the card, which lists it as deletable. The literal there names organizationId, so a fresh literal in argument position is rejected by TypeScript's excess-property check against the envelope; removing the key would be the RUNTIME change 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 held out. The assertion was still improved rather than left alone: as unknown as SharingExecutionContext became a single as ExecutionContext. Dropping the second hop matters — as unknown as erases the value entirely, while a single assertion still requires the literal to be comparable to the envelope, so a userId: 42 there is once again a compile error.
• SharingExecutionContext is NOT removed, even though PR refactor(plugin-sharing,plugin-audit): annotate enforcement on the full ExecutionContext and delete the double-casts (#7136) #7140 landed first and the coordination point on the card assigns the deletion to the second lander. Per the scope ruling recorded in the claim comment: the type is DEFINED at packages/spec/src/contracts/sharing-service.ts:191, and packages/spec is single-owner. packages/spec/** and plugin-sharing/** are completely untouched here. The type-retirement follow-up is filed separately by the PM.
• No public export changes shape; check:api-surface / check:export-origins should be unaffected.

The pins, and why they exist

A re-narrowed annotation would compile, ship and pass every test in these packages — the values were always complete at runtime, so there is no compiler pressure in either direction and nothing would notice. Each package gets an exec-context-annotation.pin.ts handing each parameter a fresh literal naming envelope-only fields (posture, accessible_org_ids, org_user_ids), which excess-property checking rejects the moment a parameter narrows back, plus @ts-expect-error negatives so a parameter erased to any cannot pass either.

Pin placement was measured per package rather than assumed, and the two differ:

• plugin-approvals/tsconfig.json excludes **/*.test.ts — same as plugin-sharing, so the refactor(plugin-sharing,plugin-audit): annotate enforcement on the full ExecutionContext and delete the double-casts (#7136) #7140 reasoning transfers directly and a pin in a test file here would be a phantom check.
• plugin-reports/tsconfig.json does not exclude test files, so a pin there would in fact be type-checked. The .pin.ts convention is used anyway: it does not depend on that exclusion staying absent, it survives a vitest-only run that never type-checks, and it keeps both halves identical in shape.

Neither pin is imported by anything, so tsup (entry src/index.ts) never bundles them into dist.

Reverse verification — the predicted direction, and it held

Predicted before running: a full revert leaves the runtime suite green and turns only the pin red. That is what happened. The fix was taken out with git checkout origin/main -- ... (never git stash), pins left in place:

REVERT: plugin-reports   Test Files  2 passed (2) / Tests  54 passed (54)
REVERT: plugin-approvals Test Files 19 passed (19) / Tests 446 passed (446)
REVERT_TEST_EXIT=0

500 of 500 tests pass with the change fully reverted — confirming #7140's measurement that a green suite is not evidence for this family. Typecheck on the same reverted tree, exit 2, every error inside a pin file and none outside one:

plugin-reports   src/exec-context-annotation.pin.ts(70,50): error TS2353: Object literal may only specify known properties, and 'posture' does not exist in type 'SharingExecutionContext'.
plugin-reports   src/exec-context-annotation.pin.ts(72,38): error TS2353: ... 'org_user_ids' does not exist in type 'SharingExecutionContext'.
plugin-reports   src/exec-context-annotation.pin.ts(79,39): error TS2339: Property 'posture' does not exist on type 'SharingExecutionContext'.
plugin-approvals src/exec-context-annotation.pin.ts(66,39): error TS2353: ... 'posture' does not exist in type 'SharingExecutionContext'.
plugin-approvals src/exec-context-annotation.pin.ts(68,40): error TS2353: ... 'accessible_org_ids' does not exist in type 'SharingExecutionContext'.

Each package was also reverse-verified alone, because a parallel --workspace-concurrency=2 run can mask the second package behind the first failure. Both bite independently (6 errors in approvals, 7 in reports).

Verification

Dependency closure built first (--filter '...^...'), then:

• pnpm --filter @objectstack/plugin-approvals --filter @objectstack/plugin-reports typecheck — green (exit 0). This is what proves the pins' positives AND their @ts-expect-error negatives are all satisfied; an unsatisfied expect-error fails the build.
• pnpm --filter ... test — 19 passed (19) files / 446 passed (446) tests in approvals, 2 passed (2) / 54 passed (54) in reports.
• npx eslint packages/plugins/plugin-approvals/src packages/plugins/plugin-reports/src — clean.
• node scripts/check-org-identifier.mjs — OK (1726 author-facing source file(s), no removed session.tenantId alias).
• node scripts/check-nul-bytes.mjs — OK (scanned 6607 text file(s) ...), plus a control-byte self-scan over every touched file.

Changeset: patch on both packages, type-side only, citing the #7140 precedent.

Out of scope, filed not fixed

#7204 — executeReport() in report-service.ts rebuilds a five-field subset of the envelope before the engine read that produces the report, dropping accessible_org_ids, which packages/objectql/src/engine.ts:2181 reads by name. Under the group posture that makes a report fall back to active-org equality while the same query returns the membership union interactively. The direction is fail-toward-isolation, so it under-reports rather than leaks — a correctness bug, not a security one. Same shape as #7141 (the plugin-audit twin), different consequence; it is a runtime change and belongs to its own card.

---

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 10, 2026 2:38am

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/client-sdk.mdx (via @objectstack/plugin-reports)
• content/docs/automation/approvals.mdx (via @objectstack/plugin-approvals)
• content/docs/kernel/services-checklist.mdx (via @objectstack/plugin-approvals)
• content/docs/plugins/packages.mdx (via @objectstack/plugin-approvals, @objectstack/plugin-reports)

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

• content/docs/releases/implementation-status.mdx (via @objectstack/plugin-approvals)
• content/docs/releases/v9.mdx (via @objectstack/plugin-approvals)

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.