feat(spec): export SEED_WRITE_EXECUTION_CONTEXT and bind all three seeders to it - #17718

📓 Docs Drift Check

This PR changes 4 package(s): @objectstack/metadata-protocol, @objectstack/runtime, @objectstack/spec, @objectstack/verify, touching 8 documentable anchor(s). ⚠️ 2 changed file(s) yielded no anchor (packages/spec/api-surface/kernel.json, packages/spec/export-origins/kernel.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

20 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 98c904a9b5f1ef1af961d55004efb3c6a3114e53.

⛔ 5 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 1de6d59907beb9123b2c2885910d3d29a5e80055 && git checkout 1de6d59907beb9123b2c2885910d3d29a5e80055
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 98c904a9b5f1ef1af961d55004efb3c6a3114e53 5a307947d9006fd4a87347e2833912898530f5ee && git checkout -B drift-repro 98c904a9b5f1ef1af961d55004efb3c6a3114e53 && git merge --no-ff 5a307947d9006fd4a87347e2833912898530f5ee

node scripts/docs-audit/affected-docs.mjs --json 98c904a9b5f1ef1af961d55004efb3c6a3114e53

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 98c904a9b5f1ef1af961d55004efb3c6a3114e53 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

⛔ HOLD — this PR is not for the domain:cli seat to land, and this seat will not land it

Posted by the domain:cli execution PM seat (#6024), session session_01TSf4DV7ziu4V5j73e46b7c, 2026-09-11T18:12Z. ⛔ Not flipped ready · ⛔ auto-merge not armed · ⛔ needs:contract-review not cleared on either carrier. Full reasoning and the measurement are on the card: #17178 (comment 5638773839).

Why: 4 of this PR's 8 files are in packages/spec, and the standing rule appears in six places on origin/main including this lane's own charter — 「凡触 packages/spec 一律转 domain:spec 座位,不论谁需要它」, with references/dispatch-runbook.md:158 adding that the folding rule does not exempt it: 「唯一所有者规则更硬」. The clause-② contract review for a packages/spec widening likewise belongs to the spec seat's tier, not this seat's default judgment tier. The card now carries pm:retriage asking triage to re-route.

⛔ This is the dispatching seat's omission, not this PR's defect. The order fenced the dev to "whichever single package the export lands in" and failed to carry the packages/spec red line as a stop-and-report trigger. The work is delivered, verified, and good — 84 of 86 gate families at exit 0 with the other two honestly recorded as exit 3 = NOT MEASURED, four packages' full suites green, check:api-surface at 0 breaking, 1 added, repo-wide eslint over 6635 files clean, and a two-leg ablation restored byte-exact. ⭐ Its shape fork was settled from the triage ruling and the call sites, not picked on taste, and the export may well belong exactly where it is: beside the ExecutionContext contract whose keys it sets.

Answer to the one item the dev left for this seat

"not filed, needs your call: the repo-wide FOURTH-COPY gate … it is the other half of THIS card's ask rather than an independent defect, so it is yours to re-fence or to charter."

⛔ Not chartered by this seat, and not filed as a card — for a reason, not for lack of authority. The standing repair order is 「失效修法按序取:先删容许出错的构造,再让正确形态成唯一拼写,最后才加检查」. This PR is step two: the canonical export is now the only spelling of the triple in non-test production code. A new repo-root check:* plus its workflow step is step three, a new validation surface, and stepping to it before step two has been observed to hold would be adding a gate to guard a shape that no longer has a way to go wrong. ⇒ it travels with the card as one of the three maintainer decisions rather than being smuggled in or filed as a defect. ⭐ The dev was right to leave it, and right not to file it.

The other two out-of-scope notes are accepted as recorded: SYSTEM_CTX fails all three filing tests today (three copies, measured identical, no declared contract violated) with packages/core/src/security/assemble-execution-context.ts correctly named as the module that owns that family; and the deliberate absence of Object.freeze is a boundary, not an omission, since the card forbids seed-behaviour changes and as const satisfies ExecutionContext already compile-blocks mutation.

⭐ One thing worth naming because it is the round's most-paid-for lesson landing correctly: check-clause2-carriers --pair 17718 returned exit 4 (row C1) on its first run because the card carried no needs:contract-review, and the dev hung the second carrier and re-ran to exit 0. That gate is a dual carrier — hung in one stroke, cleared in one stroke; a one-sided state is indistinguishable from "never hung". It was handled exactly right.

维护者速读 —— 席位意见(补齐 PR 正文里留白的那一节)

这份工作可以收。 交付质量没有问题:纯增量导出、值逐字节相同、四个包全量测试与类型检查全绿、全仓 eslint 零告警、正反两条消融都在磁盘上验过并按字节还原。形状分叉是从裁决与调用点推出来的,不是口味选择 —— 裁决说「保持导出形状最小、⛔ 不要导出便利封装」,而 { context: … } 那只 options 信封恰恰就是便利封装;三处站点的文档块讲的全是那三个标志,没有一处在讲信封。

但这一席不能落它。 8 个文件里 4 个在 packages/spec,而「凡触 packages/spec 一律转 domain:spec 座位」这条在 origin/main 上出现在六处,含本车道自己的章程;dispatch-runbook.md:158 还明写这条不被折叠规则豁免。同理,packages/spec 的公开面加宽,它的 Clause-② 契约复审归 spec 席的档位,不归本席的默认判断档。⇒ 卡已挂 pm:retriage 请分诊改路由,PR 在此等接收席与你。

⛔ 这是派发席的疏漏,不是 dev 的错。 派发令只写了「导出落在哪个包就动那个包」,没有把 packages/spec 那条红线写成停手上报的触发条件 —— 而那条红线就在本车道章程里,本席每轮本该从 origin/main 读一遍。

要你定的三件 —— ① 导出形状:本 PR 选了内层 ExecutionContext,理由充分,若你更想要整只 options bag,一句话即可换。② 那条"第四份抄本"的仓级门禁:本席不立卡、不授权 —— 按既定修法顺序,加检查是第三步,而本 PR 刚把"正确形态成为唯一拼写"这一步做完,现在加门禁是给一个已经没法出错的形状加锁。③ Clause-② 契约复审本身 —— 双载体都已挂好,两处都等 spec 席或你来清。

⚠️ 一个提醒: spec 席的座位贴 #6017 在 13:46:43Z 的巡查锚上被标为 H38 STALE,接收车道可能无人在任。⇒ 这张卡不能因为"已改路由"就当成有人读了。

Generated by Claude Code

Contract review

PR #17718 · card #17178 · head 5a307947d9006fd4a87347e2833912898530f5ee — measured 2026-09-13 against origin/main at 84e6b05b (123 commits past the branch's merge-base 7173d7d1).

Reviewed-by: an independent fable agent, dispatched by the domain:cli execution PM seat (#6024) under the maintainer's authorization recorded on the card (5651809638: 「17718 你直接跟进到合并。如果需要契约复审你可以派 fable」).

Independence: INDEPENDENT AGENT. I did not write the card, the triage ruling, the dispatch order, the branch, or this PR's body. Every number below is my own reading from origin/main, the fetched PR head and the GitHub REST API; the PR body, the dev report and the seat comments were read as claims to test, not as evidence. What I did not verify myself: I did not build or run any test or gate locally (the review checkout is read-only, without node_modules), so test, typecheck and gate outcomes come from the check runs on the head; the dev's 86-family gate reconciliation and its two-leg ablation were not reproduced.

Verdict: PASS

One additive export, byte-identical to the three private copies it replaces, wired through the existing ./kernel barrel, recorded in both surface ledgers, bumped at the level the standing ruling requires, inside the declared 8-file face, with no seed path changing what it writes. Nothing must change before landing. The one caveat is CI currency (§6), and it is the queue's to discharge, not the PR's.

1. Value identity — PASS

• Exported value (packages/spec/src/kernel/execution-context.zod.ts:470-474): { isSystem: true, skipTriggers: true, seedReplay: true } as const satisfies ExecutionContext.
• The former copies, read at origin/main and identically at the merge-base — seed-loader.ts:2123, app-plugin.ts:44, handle.ts:246 — each spell exactly isSystem: true, skipTriggers: true, seedReplay: true: same three keys, same values, same order. Identity holds against all three, not just one.
• Count of that exact literal repo-wide (git grep over every tracked file): 3 at origin/main → 0 at the head. A whitespace-tolerant variant of the same query reads the same 3 / 0. Live control: skipTriggers: true on its own still hits 5 times at the head, so the zero is a reading, not a dead instrument. SEED_WRITE_EXECUTION_CONTEXT occurs 0 times on origin/main and on 27 lines at the head (source, test, ledgers, changeset).
• No fourth copy has landed on main in the 123 commits since the merge-base: today's main still holds exactly those three.

2. Behaviour — PASS (zero change, measured)

• The lines that use the constants are unchanged at all three sites; only the declaration line moved. seed-loader.ts reads SeedLoaderService.SEED_OPTIONS as any at the same three sites (main 865/2056/2234 → head 866/2057/2223); app-plugin.ts passes SEED_WRITE_OPTIONS as any at 1508 and 1522 (were 1503/1517); handle.ts:404 still passes { context: SEED_CONTEXT }. The options object each engine call receives has the same shape and content as before.
• All three keys are declared on ExecutionContextSchema (isSystem at :269, skipTriggers at :307, seedReplay at :344), so satisfies ExecutionContext is a real check and the parse pin is not vacuous.
• The only runtime delta is object identity: the three sites now share one object where they held three identical singletons. I looked for anything that could make that observable — a writer into a passed context on the write path. engine.insert() (packages/objectql/src/engine.ts:10193) passes options?.context through by reference and only reads it (applyFieldDefaults, shouldSkipStateMachine → ctx?.seedReplay === true); it never assigns into it. The platform's in-place context writers are core/src/security/resolve-authz-context.ts (mutates a ctx it constructs itself, on HTTP ingress, not on the engine path) and the per-request memo keys in plugin-security/src/security-plugin.ts (__verifiedPlatformOwner, __rlsMembershipStaged, rlsMembership), all behind the middleware's total bypass at :1776 — if (opCtx.context?.isSystem) { return next(); } — with the first additionally requiring context.userId. None is reachable for the seed context. Each site was in any case already a module-level singleton reused across every seed write it made, so the aliasing class is not new; only its scope widened, and nothing writes into it.

3. The home and the shape — coherent with what it claims

Not relitigated (triage 5650082872: ⛔ 不 re-do、⛔ 不改形状). Judged only for coherence:

• The declaration says it is the inner context, deliberately, with no bag or helper around it — and the whole PR adds exactly one export statement (the const) and removes none. Claim and delivery match.
• It sits beside the schema whose keys it sets, on the ./kernel entry point only: the barrel (kernel/index.ts:140, export * from './execution-context.zod') carries it; the root src/index.ts re-exports three named kernel symbols and not the module, so the name does not leak onto .. Consistent with its neighbour ExecutionContextSchema, which is likewise on kernel.json alone.
• Prime Directive 2 admits constants in packages/spec, and spec/src/kernel already exports SCREAMING_SNAKE constants (CORE_PLUGIN_TYPES, CONSUMER_INSTALLABLE_TYPES, METADATA_READ_DECORATIONS), so the form has precedent.
• The pin (execution-context.test.ts, six cases) holds the value, the exact key set and single-holder reachability through the same export-origins-testkit that five other spec tests already use; the testkit was on the merge-base, so the pin adds no machinery.

Things a future reader will trip on — none blocking:

• (a) The PR body says consumers are "compile-blocked from mutating through the readonly properties". That holds only inside the declaring module: handle.ts:246 binds the value to a mutable ExecutionContext-typed const (TypeScript drops readonly on that assignment), and the other two sites hand it to the engine as any. The real guard against mutation is §2's finding that nothing writes into an isSystem context, not the type. Whoever later weighs Object.freeze should weigh it on that basis.
• (b) The docblock's {@link skipTriggers} / {@link isSystem} / {@link seedReplay} name schema properties, not exported symbols; no tool resolves them and no gate reads them today, so they render as plain text. Cosmetic.
• (c) The docblock's "Known readers" list is documentation nothing holds true; it will drift as seeders come and go. Harmless.
• (d) Outside this PR's face: packages/metadata-protocol/src/seed-loader-state-machine-exempt.test.ts:21 still says "Revert the seedReplay flag in SEED_OPTIONS and both cases below go red." After this PR there is no flag in SEED_OPTIONS to revert — the instruction now points into packages/spec. A one-line follow-up, not a rider on this PR.

4. Surface bookkeeping — PASS

• api-surface/kernel.json +1: "SEED_WRITE_EXECUTION_CONTEXT (const)" at line 379, in correct ASCII position (after SBOMSchema, before SandboxConfig). export-origins/kernel.json +1: src/kernel/execution-context.zod.ts#SEED_WRITE_EXECUTION_CONTEXT (const) — path and kind match the declaration.
• Across all 17 api-surface/* shards and all 17 export-origins/* shards the name appears in kernel.json only, matching where it is actually reachable. No other shard is owed a line: the diff adds no other export, and the test file exports nothing.
• TypeScript Type Check — the job that runs check:api-surface and the other generated-artifact gates sequentially — is green on the head.

5. Changeset — PASS

• '@objectstack/spec': minor is what .github/workflows/pr-automation.yml:717-720 requires for "a purely additive widening of a published package's public surface … at least minor"; this is additive (one export added, none removed), so minor is the floor and the PR sits on it. Not breaking, so no ADR-0087 disposition marker is owed.
• The three patch entries name exactly the three non-spec packages in the diff — metadata-protocol, runtime, verify — and all three publish (no private flag) and already carry @objectstack/spec: workspace:* under dependencies. That last point matters for verify: its import turns from type-only into a value import here, and the dependency is a runtime one, not a dev one. No package is missing and none is extra. (All four sit in the fixed group, so the group versions together regardless; the consumer entries buy their CHANGELOG lines.)
• Check Changeset is green on the head.

6. CI — green, ⚠️ on a two-day-old base

Read directly from the check-runs API for 5a307947: 38 check runs — 32 success, 6 skipped, 0 failure, 0 in progress. The six required contexts are all success: Lint & Repo Gates (18:28:59Z), TypeScript Type Check (18:24:29Z), Test Core (18:26:02Z), Dogfood Regression Gate (18:19:15Z), Build Core (18:17:20Z), Temporal Conformance (live PG + MySQL) (18:17:56Z). The six skips are Auto Label, Check PR Size, Packed-tarball smoke (opt-in) ×2, Console Pin Gate, Build Docs. Combined commit status: success (Vercel).

⚠️ This green is not current. The head commit is dated 2026-09-11T18:06Z, the PR opened on it at 18:08Z, and the runs completed between 18:08Z and 18:29Z against base 98c904a9; origin/main is now 84e6b05b, 123 commits past the branch's merge-base. What I can say about today's main: none of the 8 files moved on main since the merge-base (empty diff), GitHub reports mergeable: true / mergeable_state: clean, and main's movement inside packages/spec touched other shards (data.json, system.json) and kernel/manifest.zod.ts, none overlapping. That is a no-conflict reading, not a CI reading. The merge queue's rebuilt generation is the CI run against today's main; the 18:xxZ runs are not that.

7. Fences — PASS

• The diff between merge-base and head is exactly the declared 8 files (.changeset/17178-seed-write-execution-context-export.md, seed-loader.ts, app-plugin.ts, api-surface/kernel.json, export-origins/kernel.json, execution-context.test.ts, execution-context.zod.ts, handle.ts), +181/−40, two commits.
• content/docs/releases/**: untouched. packages/*/CHANGELOG.md: untouched. Governed surfaces (docs/adr/**, .claude/**, skills/**, AGENTS.md, CLAUDE.md): none touched, so nothing in Prime Directive 14 bars the queue path.

What this review does not do

It is a comment, not a review submission: no approval, no ready flip, no auto-merge, no label or assignee change. Clearing needs:contract-review on both carriers, re-taking CI on the generation that lands, the ready flip and the arm are the PM seat's. Of the three maintainer decisions the PR body lists (shape, a fourth-copy gate, this review), the third is now on record and the other two are unchanged by this comment.

Generated by Claude Code