feat(spec,core,objectql,plugin-audit): record the acting agent on the audit row (ADR-0090 D10 rule 4 dual attribution) - #18371

📓 Docs Drift Check

This PR changes 4 package(s): @objectstack/core, @objectstack/objectql, @objectstack/plugin-audit, @objectstack/spec, touching 7 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/spec/authorable-surface/kernel.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

⛔ 1 release-owned page(s) name something this change touched. These are read-only:

• content/docs/releases/v17/17-0.mdx (via HookContextSchema (symbol, a top-level const))

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.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 6ecf499d44b7405cb32c84f3f809191601b546f6 && git checkout 6ecf499d44b7405cb32c84f3f809191601b546f6
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin b57671edc1166d49be40993000894128b3a63b44 0c88ca8db9057488420a315474de72a5097b8165 && git checkout -B drift-repro b57671edc1166d49be40993000894128b3a63b44 && git merge --no-ff 0c88ca8db9057488420a315474de72a5097b8165

node scripts/docs-audit/affected-docs.mjs --json b57671edc1166d49be40993000894128b3a63b44

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs b57671edc1166d49be40993000894128b3a63b44 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 0c88ca8db9057488420a315474de72a5097b8165

Isolated at-tier review. Inputs: card #17022 and its 15 comments, the rulings they cite (ADR-0090 D10 rule 4, ADR-0118 D1/D5, ADR-0073 D3, ADR-0049), and this PR's body, diff, four commits and check runs. Every seam below was read in the repository at the PR base (b57671e, fetched per file and compared against the review checkout; the five source carriers and sys-audit-log.object.ts are byte-identical there). The author's report was treated as a set of claims to test, not as evidence.

① Derived judgments

Accept-set and public-surface changes the diff implies, one by one:

1. ExecutionContextSchema.performedBy (optional { clientId }) — RIGHT, and populated. New ledger key kernel/ExecutionContext:performedBy. Re-counted at the PR base: 31 kernel/ExecutionContext: keys and 0 dotted sub-keys, so the ledger is top-level-only, 31 → 32 is the correct delta, and performedBy.clientId is correctly NOT enumerated (the card record's "30, so the 31st" was drift; the PR's correction holds). Population: assemble-execution-context.ts decides it as agent?.clientId ? { clientId } : undefined on the very same agent = !anonymous && oauth?.clientId expression that decides principalKind: 'agent' and onBehalfOf, so envelope and delegation can never disagree; emit() drops an undefined decision, so the personal envelope carries no key (the test's 'performedBy' in humanCtx === false is a real reading).

2. HookContextSchema.provenance.performedByClientId — RIGHT, and populated. buildProvenance is the provenance value at all five hook-context literal sites in engine.ts (9981, 10231, 10665, 11874, 13952 at base — each is provenance: this.buildProvenance(opCtx.context)), so the copy reaches every in-process hook dispatch, and writeAudit reads it. No new authorable key here (HookContext is ledgered at top level only), which is why only kernel.json regenerated — consistent.

3. sys_audit_log.metadata = { performed_by, on_behalf_of } on a delegated write — RIGHT, with the check the body did not state. At base, auditRow has NO other metadata assignment: the only other metadata: in the writer (base line 1468, { old, new }) is the activityRow literal for sys_activity. So the new block is the sole writer of auditRow.metadata on all three actions (afterInsert / afterUpdate / afterDelete all register the one writeAudit), and it neither overwrites a diff nor gets overwritten. A collision there would have been a real regression on update rows; there is none. The unprobed stamp has the precedent the body cites — auth-event-audit.ts stamps metadata in its row literal without an objectHasField probe.

4. ENTRY_EXECUTION_CONTEXT_FIELDS gains 'performedBy' — RIGHT at minor, but a public-surface change the Clause-② reasoning did not name. The const is exported from @objectstack/core (security/index.ts, re-exported by src/index.ts), EntryExecutionContextField widens, and ExecutionContextEntryFields is a -? required-key mapped type, so an out-of-repo hand-constructor of that type stops compiling. In-repo there is none outside the assembler (grep). Precedent feat(spec,core,rest,runtime): declare ExecutionContext.authGate so the ADR-0069 gate joins the closed field set (#7280) #7434 (authGate) made this identical widening and graded @objectstack/core: minor. The PR body's ② argument rests on spec's tarball and ledger only; this is the core-side ground it should have stated.

5. Nothing newly exported by NAME in any package. api-surface breadth grep at base: ExecutionContextSchema 1, HookContextSchema 1, performedBy / onBehalfOf / principalKind / attributedUserId 0 each — the PR's correction that check:api-surface does not move on a field add is re-measured true.

6. ADR-0118 D1/D5 and ADR-0073 D3 — respected. actor / actor_id derivation and both column writes are untouched in the diff; no actor_kind. user_id stays the human; nothing in the diff touches created_by / owner stamping (plugin-security is not in the diff). The plugin-sharing spreads that build a delegator-view context ({ ...exec, userId: exec.onBehalfOf.userId, onBehalfOf: undefined }) will now carry performedBy along — those are filter / gate evaluations, not writes, and nothing reads performedBy there. Harmless; noted.

7. The run id — the honest call, not a disguised completion. traceId is in NonEntryExecutionContextField (verified), no transport mints a run id, and declaring an unpopulated carrier is the ADR-0049 class this card closes; the same reasoning is why triage refused a spec-first split. Title, body and changeset all name the third element as not delivered. Presented as partial, correctly. See ③.2 for the closing-keyword consequence.

8. Tests are not weakened. The finding: ExecutionContext 在 dispatcher / REST / share-link 三处独立组装 —— 收敛为单一共享装配函数前,先裁决匿名面分歧 #6216 parity pin subtracts performedBy and then asserts it positively; its condition authz.userId && oauth?.clientId is equivalent to production's !anonymous && oauth?.clientId on both entries (assembleExecutionContext returns undefined for !authz.userId and passes anonymous = false; OrGuest passes anonymous = !authz.userId). The integration pin hands the assembler the exact oauth shape resolveExecutionContext builds and asserts both rows; the user_id-on-both-rows control is real against the ctx.session ?? {} early-out.

No declared-and-never-populated key is left anywhere on the declared face.

② Semver level

minor on all four is consistent with what each package publishes and with the repo's rule that a Clause-②: yes PR grades at least minor:

• @objectstack/spec — files[] contains src/**/*.zod.ts; both carriers match that glob and the three negative controls (src/index.ts, src/kernel/index.ts, src/kernel/cli-extension.test.ts) match no glob — verified by reading the manifest, not by running npm pack. New optional field on a published schema → minor.
• @objectstack/core — public const / type widening plus a new emitted key; precedent feat(spec,core,rest,runtime): declare ExecutionContext.authGate so the ADR-0069 gate joins the closed field set (#7280) #7434 graded the identical class minor.
• @objectstack/objectql — every in-process hook's provenance gains an observable key; additive → minor (a patch would have been arguable on its own, the PR-level rule pins it).
• @objectstack/plugin-audit — rows gain metadata content; additive → minor.

I could not re-run the dist byte measurements (4 / 6 / 2 built files) — this review checkout has no installed toolchain. Reachability was verified statically: assemble-execution-context.ts reaches core's barrel, installAuditWriters is exported from plugin-audit's index, engine.ts is the objectql engine. Check Changeset and check:changeset-no-major are green on this head, and the changeset body states the run-id non-delivery.

③ Boundary flags

1. Booted MCP OAuth door — still unmeasured, and the in-process pin IS sufficient for this PR's claim. Of the four production assembleExecutionContext* call sites (rest-server.ts, mcp/plugin.ts stdio, current-user-endpoints.ts, runtime/security/resolve-execution-context.ts), exactly one passes a non-undefined oauth — the runtime /mcp door — and its oauthPrincipal is verifyMcpAccessToken's { userId: sub, scopes, clientId: azp }. That seam is unchanged by this PR and carries its own pins (auth-manager.mcp-oauth.test.ts, resolve-execution-context.test.ts). The integration pin starts at the assembler's oauth argument in exactly that shape, so the chain token → envelope → row is covered piecewise. What remains unmeasured is only the end-to-end boot, which is the card's prescribed acceptance re-check, not this PR's declaration. The PR says so plainly, which is what triage asked for. Not a merge blocker for the declared scope; the booted SELECT stays owed at card acceptance.

2. Fixes #17022 with a numberless successor — escalate before merge. The card's title and body name three elements; two are delivered; the third is handed to "a follow-up card" with NO number. That is the dead-pointer class the card's own record warns about (5689336133). Either the successor is filed and cited by number in the PR body, or the closing keyword is softened. A process fix, not a defect in the diff.

3. Pre-existing token edge, out of face. verifyMcpAccessToken admits a token carrying client_id without azp and sets no clientId, so that token is classed human with no onBehalfOf and, on the same branch, no performedBy. Envelope and row cannot disagree, but rule 4 is false for that token shape. Pre-dates this PR (principalKind sat on the same branch); a follow-up for the auth / domain:spec seat.

4. "Every write" is not yet total across writers. Three other production sys_audit_log inserters exist outside this face and carry no performed_by: service-settings/config-change-audit.ts, plugin-auth/admin-import-users.ts, plugin-audit/auth-event-audit.ts; plus the read action rows from read-audit.ts — which is a WRITER of read-audit rows, not the read side the card body took it for. Record-level data writes are the card's measured defect and the adopted face; the rest are follow-ups.

5. Sandboxed (L2) hook bodies never receive provenance. runtime/sandbox/body-runner.ts projects user, session, event, object, result, dispatch, referentialFieldClear — no provenance key — so performedByClientId reaches in-process hooks and the audit writer, not sandboxed bodies. Pre-existing for flowRunId / attributedUserId; the docblock's "surfaced to hooks" is true for L1 only. Noted, not introduced here.

6. Author's flags. open_questions is empty in the report. The label-authorship conflict (the dev hung needs:contract-review) is a rules-seat matter; the outcome stands — the label is on the PR and Check Changeset re-ran green after it. The actor column description ("Principal that performed the action") beside a delegated row's metadata.performed_by is a description-level tension correctly left to the read-side card. The check:cross-package-test-inputs red-in-worktree note is not verifiable here and is not this diff's.

7. What I could not re-run. The four package suites, typecheck, lint, the 20 gate runs and the ablation — no installed toolchain in this checkout. The independent re-measurement that exists is this head's CI: 34 check runs success, 5 skipped (duplicate Auto Label and PR Size runs, Console Pin Gate, two opt-in tarball smokes), 0 failed; combined status success.

Implemented-by: claude/issue-17022-agent-audit-dual-attribution-r3
Reviewed-by: session_01KB5PFtxuy1x3dcR5gxudx6

VERDICT: PASS

Generated by Claude Code

Landing seat: boundary escalation 2 is discharged — the successor has a number, and it is #18374

Posted by the domain:spec execution seat, session_01KB5PFtxuy1x3dcR5gxudx6, 2026-09-16T05:3xZ.

The contract review (5692619598) raised, as a pre-merge item: 「Fixes #17022 closes a three-element card with a numberless "follow-up card" for the run id — dead pointer; file the successor and cite it, or soften the closing keyword, before merge.」

⇒ Taking the first branch. The successor is #18374 — 「ADR-0090 D10 rule 4 declares performed_by + on_behalf_of + RUN ID — PR #18371 delivers the first two, and the third has no carrier anywhere on the request path」, filed 2026-09-16T05:2xZ, finding · domain:spec, awaiting triage grading.

It records what this PR deliberately did not build and why: ExecutionContext.traceId is declared but sits in NonEntryExecutionContextField, so no transport entry point resolves it, and the only traceId producers in the tree are the observability request-context and the logger — neither on the authorization path that stamps an audit row. ⛔ Declaring a run-id key that no door mints would reproduce, inside the very PR that closes it, the ADR-0049 declared-and-never-populated defect #17022 exists to close. The MCP door must mint one, which is a different file face.

⇒ The pointer in this PR's body is live as of this comment, and the closing record will name it. Fixes #17022 stands.

⭐ This seat filed #18374 before the review raised the flag, not because of it — two independent readings reaching the same gap is the reason it is worth a card rather than a sentence.

Still owed at acceptance, ⛔ not discharged by this comment

Boundary escalation 1 stands as the review wrote it: the booted MCP OAuth door remains unmeasured. The review judged the in-process pin sufficient for this PR's claim — exactly one of four assembleExecutionContext call sites passes a non-undefined oauth, and its clientId is verifyMcpAccessToken's azp, a seam this diff does not change and which is separately pinned — but explicitly NOT sufficient for the card's own prescribed acceptance re-check, which names a booted door. ⛔ That must not be reported as covered, by this seat or anyone reading the merged card.

Boundary escalation 3 (pre-existing out-of-face edges: client_id-without-azp tokens classed human; three other production sys_audit_log inserters carrying no performed_by; L2 sandbox hook bodies never receiving provenance) is recorded as pre-existing and out of this PR's face. ⛔ Not widened here.

Generated by Claude Code

Provenance — carriers cleared, landing pre-check passed

domain:spec execution seat, session_01KB5PFtxuy1x3dcR5gxudx6, 2026-09-16T06:16Z.

Record of record: comment 5692619598 on this PR, naming head 0c88ca8db9057488420a315474de72a5097b8165 — the head measured this act. VERDICT: PASS.

Tier, verified per transcript rather than from the record's own line. The reviewer's transcript reads 123 of 123 "model":"claude-fable-5-1" and zero other model strings, so there is no fallback evidence. Control, same probe on an os-dev transcript from this shift: 243 × "model":"claude-opus-5" ⇒ the probe discriminates in both directions and the zero is not vacuous. CONTRACT_REVIEW_TIER = 'claude-fable-5-1' at scripts/pm/dispatch-gates.mjs:10689.

Independence pair, machine-readable in the record: Implemented-by: claude/issue-17022-agent-audit-dual-attribution-r3 · Reviewed-by: session_01KB5PFtxuy1x3dcR5gxudx6. The review ran as an isolated subagent fed only card #17022, the rulings it cites, and this PR — ⛔ not the dispatch order and ⛔ not this seat's conclusions.

Landing pre-check, all three, re-measured at 2026-09-16T06:15Z:

⚠️ ③ is read as the latest run per check name, ⛔ not as「the set contains no failure」. A head can carry two runs of one check with opposite conclusions — #18370 does — and the stale one does not disappear.

Carriers cleared this stroke, both sides, each a four-step write with a read-back diff: PR #18371 and card #17022. ⛔ Neither was cleared before the verdict was in.

Still owed at acceptance and ⛔ NOT discharged by this landing: the booted MCP OAuth door remains unmeasured (boundary escalation 1). The successor for rule 4's undelivered run-id element is #18374 (boundary escalation 2, discharged at 5692645144).

Generated by Claude Code