fix(spec,objectql): declare the inert-JSON artifact and registry-record package body stages, and stop the record under-reporting functions

[os-litant]

Fixes #17518

Clause-②: yes

Executes ruling A′ — decision batch #192 item 3, comment 5748934194, maintainer 「192 同意」. Its two steps, its refusals (A and B) and its fences are followed as written; every place where the tree made me read the ruling rather than transcribe it is called out below.

Base of every reading in this body: merge commit aac764cc361.

⚠️ The readings below were brought to this head by the seat, not by the round that first wrote them. Two merge rounds have run since the first draft. Each figure corrected here is named in the correcting round's own report on card #17518 — comment 5750725852 for the first, 5750987577 for the second — and the seat re-verified the head, the regenerated index and mergeability itself before editing. Anything not listed in those two reports is the original round's reading, unchanged.

The confidence gap the ruling asked me to close first

「whether effect is required or defaulted on the declaration schema — read it, ⛔ do not mint a value」

Defaulted. FlowFunctionDeclarationSchema.effect is FlowFunctionEffectSchema.default(DEFAULT_FLOW_FUNCTION_EFFECT) where that constant is 'pure' (automation/flow-function.zod.ts). Measured, not read off the source alone: FlowFunctionLoweredDeclarationSchema.safeParse({ handler: 'x' }) succeeds and yields { handler: 'x', effect: 'pure' }. The array member of functions states FlowFunctionEffectSchema.optional() with no default, so the two forms differ and neither is restated anywhere in this diff — each JSON stage inherits its form's own optionality by deriving from it.

That reading is what the producer writes: the bare-callable normalisation uses DEFAULT_FLOW_FUNCTION_EFFECT and the array form gets nothing.

What landed

packages/spec/src/automation/flow-function.zod.ts — FlowFunctionLoweredDeclarationSchema is exported (step 1), with its FlowFunctionLoweredDeclaration / …Parsed aliases. It was a module-local const, and automation/index.ts's export * only re-exports what is already exported.

packages/spec/src/stack.zod.ts — two new bodies beside AssembledPackageBodySchema:

• ArtifactStagePackageBodySchema — the on-disk artifact stage. functions entries are the lowered spellings, hooks[].handler is a string.
• RecordStagePackageBodySchema — the registry record stage: literally ArtifactStagePackageBodySchema.extend({ functions: … }) with functions[].handler optional in both the map-record form and the array form, and nothing else.

AssembledPackageBodySchema, composeStacks and the cannot drift invariant are ⛔ untouched: those callables are live on the stage the assembled body declares itself for, and narrowing it would refuse a published composition function's own output. Both new schemas carry the same structural z.ZodType annotation as the assembled body, for the two reasons recorded there (TS7056; a named alias turning stack.zod into a shared chunk).

packages/spec/src/api/package-api.zod.ts — the installed-package row's manifest is rebound to the record stage (step 1). The z.unknown() override and the docblock defending it are gone, and the sentence that ruling A step 5 assigns to this edit is corrected in place: those two members are not why ArtifactPackageSchema and ObjectStackDefinitionSchema publish no JSON Schema — src/stack.zod.ts is not one of the subpath namespaces build-schemas.ts walks, so neither is ever reached by the emit loop.

packages/objectql/src/registry.ts — step 2. withDeclaredFunctionEntries rewrites a bare callable functions map entry to { handler, effect: DEFAULT_FLOW_FUNCTION_EFFECT } at the assembly boundary, before toRecordManifest runs. toRecordManifest's structural rule is ⛔ untouched and no key is special-cased inside the projection; the two spellings are simply made structurally equal ahead of it. ⛔ No ref is minted, ⛔ no entry is dropped. The caller's manifest is never mutated and a copy is made only when an entry really needed rewriting.

Two places where I read the ruling rather than transcribed it — both stated so they can be overruled

1. 「functions entries the lowered declaration」 is implemented as BOTH lowered members of FlowFunctionEntrySchema, not only the record one. objectstack build emits { myFn: 'myFn' } for a bare entry and { myFn: { handler: 'myFn', effect } } for a declared one, so a stage admitting only the record form would refuse artifacts this repo really writes — the failure mode that withdrew letter B, one key across. Ruling A′'s own step-4 control names both shapes (「a string and a lowered record」). Measured: the artifact stage accepts a body carrying one of each.
2. The array member is transcribed, not derived. functions' array branch is declared inline inside the assembled body's own shape, and narrowing it in place is the one thing this pair may not do. The transcription's drift is guarded instead: stack-json-stage-package-body.test.ts pins the authoring array entry's key set equal to both JSON stages', so a key added there and not here reddens by name.

Acceptance, as ruling A′ lists it

criterion	result
both bodies convert under z.toJSONSchema (self-test over the whole body)	YES / YES; control: the assembled body still NO (Function types cannot be represented in JSON Schema); probe controls lit z.string() YES, dark z.object({a: z.function()}) NO
the showcase-shaped manifest (config.ts:244-249) reports 2 functions on the GET /packages row, the bare one as a handler-less declaration	2: {"summarizeCompletedTask":{"effect":"pure"},"sweepProjectHealth":{"effect":"writes"}}, driven through the real SchemaRegistry.installPackage
hooks unchanged	unchanged: an inline handler is dropped (the key is optional and admits that), a string handler survives verbatim. The array functions form also keeps its entry: [{"name":"syncBilling","effect":"writes"}]
AssembledPackageBodySchema / composeStacks / the invariant untouched	untouched — no edit in those regions; assembled-package-body.test.ts and compose-stacks-manifest-preserve.test.ts stay green
the two noted, not filed corrections in the same edit	baseline reason line: made TRUE by step 1 rather than reworded — automation/FlowFunctionLoweredDeclaration is now in json-schema.manifest/automation.json, so 「the lowered record … publishes normally」 is now a fact. package-api.zod.ts docblock last sentence: corrected in place, see above

Stage separation, measured rather than asserted: the record stage accepts the handler-less declaration and the artifact stage refuses it; the assembled body accepts a live callable and both JSON stages refuse it; both JSON stages still refuse an authoring glob and an unknown key (namesapce). So the two keys moved from unknown to a declaration, and nothing else moved.

Reverse verification — two ablations, each restored with proof

Both ran against committed code, each with a trap restore, an on-disk landing proof (anchor grep -c before/after plus a blob-hash change) and a restore proof (git hash-object back to the HEAD blob, git diff HEAD empty).

• A1 — remove the producer normalisation (toRecordManifest(withDeclaredFunctionEntries(manifest)) → toRecordManifest(manifest); anchor 1→0, injected 1, blob b0af60d7… → 17b7c93c…): registry-package-manifest-serializable.test.ts goes 1 failed / 15 passed, naming the exact defect — expected [ 'sweepProjectHealth' ] to deeply equal [ 'summarizeCompletedTask', …(1) ]. Restored blob b0af60d7…, diff empty.
• A3 — collapse the record stage into the artifact stage (jsonStageFunctionsKey(true) → (false); anchor 1→0, injected 2, blob 60c13b43… → 822bed8e…): 2 failed / 79 passed across two files — record accepts the handler-less declaration; ⛔ the ARTIFACT stage refuses it and parses a row carrying the residual the projection really produces. So the one-key difference that IS the fourth stage is load-bearing in both packages' pins. Restored blob 60c13b43…, diff empty.

No ablation is offered for 「both bodies convert」: that claim already carries its discriminating control inside the same test file (the assembled body must NOT convert), which is a lit/dark pair rather than an assertion about itself.

Tests and gates

All through scripts/pm/os-verify-lock.sh with OS_VERIFY_LOCK_SLOT=issue-17518, verdicts read from the wrapper's own VERDICT command-exit line and never a bare $?; every exit code captured before any pipe. Wall-clock figures in the logs are SHARED-BOX seconds.

• pnpm --filter @objectstack/spec test — 505 files / 14749 tests passed (up by two files and 38 tests from the first draft reading — the population fix(spec)!: a dataset-bound dashboard widget owns appearance, the dataset owns structure #19363 and fix(spec): answer an axis-silent key with both ends of the range, not the cheaper-spelled one #19318 brought in on the fifth merge)
• pnpm --filter @objectstack/objectql test — 303 files / 5044 tests passed
• pnpm --filter @objectstack/runtime exec vitest run --maxWorkers=2 over the package-door / artifact-collection population, re-run on the final head in two batches with every path named so the population is reproducible — batch A 8 files / 84 tests passed (src/artifact-collections, src/artifact-function-declarations, src/artifact-reference, src/bundle-function-entries, src/package-door-error-parity, src/package-door-namespace-conflict-code, src/domains/package-door-producer-key-carry, src/load-artifact-bundle.granted-permissions) and batch B 6 files / 60 tests passed (src/security/artifact-granted-permissions, src/domains/packages-serializable-response, src/domains/packages-single-door, src/domains/packages-protocol-handle-typing, src/domains/packages-read-delete-response-conformance, src/domains/packages-publish-drafts-response-conformance). ⚠️ The earlier draft reported a smaller count for a differently-drawn list; the FILE LIST differs, not a test that vanished — the enumeration above is the population, and the filter preflight now reports nothing unselected.
• pnpm --filter @objectstack/spec --filter @objectstack/objectql typecheck — exit 0; both test layers compile (spec 53 files / 257 errors / 142 pins; objectql 40 / 234 / 65, unchanged). ⚠️ The spec ledger moved from 54 / 259 / 144 by main's feat(spec): the /packages doors declare the query parameters they execute, and retire the two they never did #19364 arriving in a merge, ⛔ not by this PR.
• Targeted re-run on the final head aac764cc361: the five spec stage/compose files — 5 files / 130 tests passed.

Gates. node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived from this tree, every command run with its exit code written to a file, reconciled with --ran: 116 derived, 114 run, 2 NOT-MEASURED, 0 UNRUN, and the tool's own verdict line says so. 113 exit 0. The two NOT-MEASURED are the tool's DERIVED classification of an exit 3; a third measured nothing too, and the tool cannot see it because its refusal code is 2. ⛔ None of the three is a finding:

• check:dual-build-cjs-loads — exit 3, its own PREREQUISITE NOT MET … ⛔ This is NOT a pass: nothing was measured (66 packages have no dist; it wants a whole-repo build).
• check:type-check-debt — exit 3, same shape, same wording, wants the full package closure built.
• check-engine-split-ratio --days 90 — exit 2, refuses on a shallow clone whose oldest visible commit sits inside the 90-day window. It says a ratio derived there would be 「real, plausible and WRONG」.

A fourth, check:skill-examples, first exited 1 on an unbuilt packages/client-react; after building that package it re-runs green — 258 prose examples type-check across 3 surfaces. Both readings are stated here, and the reconciliation record carries ONE of them — the green re-run — because the tool flags a doubly-recorded family and says to make the record state one thing. The re-derivation on the final head yields 116 families: check:api-surface-declarations is gone (retired upstream by #19024 mid-round) and check:gitlink-declared is new, run green. No family is left unrun.

Ratchet families re-run after the last merge, on aac764cc361: check:generated (all 15 artifacts up to date), check:api-surface, check:authorable-surface, check:export-origins, check:declaration-map, check:docs, check:skill-refs, check:entry-nameability, check:dual-source-exports, check:spec-changes, check:spec-parsed-alias, check:published-files, check:nul-bytes, check:cross-package-test-inputs, check:test-source-alias, check:type-check-coverage — all exit 0. Control characters: grep -naP over every file I hand-edited returns nothing (exit 1).

Generated artefacts in this diff, and why each moved

• json-schema.manifest/automation.json, authorable-surface/automation.json, authorable-defaults/automation.json, api-surface/*, export-origins/*, declaration-map/automation.json, content/docs/references/** — the new exports, regenerated by the package's own gen: scripts. authorable-defaults records automation/FlowFunctionLoweredDeclaration:effect = "pure", which is the confidence-gap reading in ledger form.
• packages/spec/dropped-refinements.baseline.json — four api/* entries each gain one site (…manifest.hooks.element.object), counts 569 → 573. Cause: the record stage declares hooks where z.unknown() declared nothing, so HookSchema's object refinement now reaches the runtime and not the published file. The ledger is hand-edited by design and the build printed the exact delta.
• skills/objectstack-platform/references/_index.md — one generated line listing stack.zod.ts's exports.

skills/** readings, and the landing tier

This diff touches skills/objectstack-platform/references/_index.md, so the PR is governed, Tier H on its file list. ⛔ It stays a draft and no AI seat merges, queues or arms auto-merge on it.

Both readings the skills rule requires, at merge base c334ba0f3a6:

• changed file, whole file: 41 lines before, 41 after — net 0. The diff is one regenerated line.
• package total (sum of every SKILL.md): 6145 before, 6145 after — net 0.

node scripts/check-skills-token-ratchet.mjs exits 0 and classifies this file as generator-owned (measured, not ratcheted), so no authored ceiling is charged.

Clause ②, and the changeset is not one package's

Clause-②: yes, and two changesets because two published packages move:

• @objectstack/spec — minor. New exports, and the two installed-package responses move from z.unknown() on functions / hooks to declared JSON shapes. That is a narrowing on a published declaration; what it does NOT withdraw is measured, on real producers: the showcase shape, the array form and the already-lowered body an artifact boot installs all parse.
• @objectstack/objectql — patch. GET /packages reports functions it previously dropped. No API is added or removed; a read door stops under-reporting. Grade it up if a payload gaining entries reads as minor to the reviewer.

Serial and merge state, re-taken by this seat

Changed-file map re-taken first-hand over all 33 open PRs (271 file rows) rather than inherited. LIT control packages/spec/src/ui/action-params.zod.ts resolves to #19315; DARK control packages/spec/src/zzz-no-such.zod.ts resolves to nothing.

• packages/spec/src/automation/flow-function.zod.ts, packages/spec/src/api/package-api.zod.ts, packages/objectql/src/registry.ts — free.
• packages/spec/src/stack.zod.ts — held by docs(spec): scope the email-template locale-floor claims to a call that names a locale #18482, spec: pre-parse __proto__ guard on ObjectSchema.fields and AssignmentConfigSchema.assignments (#17852, #18847) #19147, spec: declaresCollection reads a pipe's authorable side, so a preprocess-wrapped collection key cannot silently leave the merge refusal set (#19150) #19314, all below A′'s region. spec: pre-parse __proto__ guard on ObjectSchema.fields and AssignmentConfigSchema.assignments (#17852, #18847) #19147 landed during this round and merged cleanly here (its stack.zod.ts hunk is a comment).
• packages/spec/dropped-refinements.baseline.json — also written by spec: pre-parse __proto__ guard on ObjectSchema.fields and AssignmentConfigSchema.assignments (#17852, #18847) #19147 (landed, resolved here) and by the still-open feat(spec)!: publish the $-prefix key ban the normalized filter enforces, and make the ratchet able to see it #19335, which rewrites the same measured header and adds entries. That is a line-level contention on a ledger whose correct value is recomputable: whoever lands second re-runs pnpm --filter @objectstack/spec build and re-applies the delta it prints. ⛔ Not a semantic collision.

origin/main has been merged five times on this branch. #19024 (which retired api-surface-declarations/) came in early, which is why no api-surface-declarations/*.txt appears in this diff. The fifth merge brought #19363 — a BREAKING spec change, four retired-key migration entries and one ADR-0087 semantic conversion — plus #19318, #19369 and #19303, which is why the full spec suite was re-run rather than only the generated gates.

That fifth merge conflicted on exactly one path, content/docs/references/index.mdx, a routed merge=os-regen artifact both sides move. It was resolved by the runbook's ORDER and ⛔ not by hand: merge base captured before the merge, git merge, the driver's silent drop MEASURED (the merged blob was byte-identical to this branch's side, so main's was gone), main's side restored into the WORKING TREE ONLY with git restore --source, then gen:schema && gen:docs on the committed merge. The regenerated file is the UNION, proven in both directions: against this branch's side it differs by exactly main's delta (UI 157 schemas becomes 158, DashboardWidgetChartConfig listed) and against main's side by exactly this branch's (Automation 74 becomes 75, FlowFunctionLoweredDeclaration listed); the total moves 1533 to 1534. ⛔ scripts/pm/os-regen-merge.sh was NOT used — its step-2 non-idempotence across a regeneration commit is filed as #19392.

Acceptance notes

• noted, not filed: regenerating packages/spec/api-surface-declarations/ui.txt produced a 184-line change that is a pure permutation of its own content — the same union members in a different order, 0 removed, 0 added, 35 reshaped. Verified as a precedented shape rather than a defect: commit 24d622b94b8, a spec change touching zero files under packages/spec/src/ui/, moved the same file by 5 lines whose sorted content is byte-identical. The whole artefact was retired upstream by revert(spec): take back the declaration-text snapshot, restore the 27 signature hashes #19024 mid-round, so nothing of it survives in this diff and the population is gone. Carrier: none — the file no longer exists.
• noted, not filed: packages/objectql's tests resolve @objectstack/metadata-protocol from dist, so after merging upstream The in-process installPackage door ignores the enableOnInstall its own request schema declares — honour it the way the HTTP door does (successor of #18605, ruling batch #153 item 5 letter 1) #19277 the seven assertions in protocol-install-package-enable-on-install.test.ts failed against a stale build of a package this PR never touches; building that one package turns all seven green. A local-environment reading, not a repo defect, and check:test-source-alias already owns the aliased/unaliased ledger this sits in. Carrier: the next seat that runs objectql's suite after a merge — it will see the same red and should build the dependency before reading it as a finding.

维护者速读(草稿)

改了什么 —— 一个包的「包体」在平台里其实要经过四个阶段:作者写的、内存里装配好的、落盘成 artifact 的、注册表记录下来的。前两个早有声明,后两个从来没有。这次把后两个补上:ArtifactStagePackageBodySchema(落盘 artifact)和 RecordStagePackageBodySchema(注册表记录),放在既有的装配体旁边,装配体一个字不动。同时修好一个生产者缺陷:GET /packages 以前会把「裸写的函数」整条漏报,现在两种写法都报。

为什么改 —— 两件事各有代价。其一,装配体里有两个键(functions、hooks)声明了「可以是一个活的函数」,而 JSON Schema 表达不了函数,于是任何嵌入它的接口都会整份丢掉自己的 JSON Schema;读 API 只能把这两个键写成「什么都收、不检查」。其二,我们自己发布的 showcase 声明了 2 个函数,而 GET /packages 只报 1 个——机器可读的读门把事实说少了。

风险与代价(含回滚) —— 风险集中在一处:那两个键从「什么都收」变成「按声明收」,理论上可能拒掉今天能读的行。已实测三种真实生产者(showcase 的写法、数组写法、artifact 启动装回来的写法)全部照常通过,并且用两次消融证明了这些断言真的会红而不是摆设。⛔ 装配体与 composeStacks 未动,所以 os dev / os serve 的行为不受影响——这正是上一版裁决 B 被撤回的原因,这次没有重蹈。回滚:两个 spec 改动与 objectql 改动互相独立,git revert 任一半都不会让另一半变红;最小回滚是把 package-api.zod.ts 的那一行绑回装配体,新声明留着不用。

席位意见 ——

你要做的 —— 这个 PR 的文件里有一份 skills/** 的生成文件,按规则整单属于 Tier H,只有你(或你授权的批准)能让它落地;AI 席位不会合并、不会排队、不会解除 draft。请看两点:① @objectstack/objectql 我打的是 patch,理由是「读门修复、不增删 API」,若你认为「载荷多出条目」应算 minor,说一声即可改;② functions 的声明式阶段我按「两种 lowered 写法都收」实现(理由写在上面第 1 条),如果裁决本意是只收记录式那一种,也请直接说,那会让 objectstack build 今天写出的一种 artifact 被拒。

---

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/objectql, @objectstack/spec, touching 18 documentable anchor(s). ⚠️ 9 changed file(s) yielded no anchor (packages/spec/api-surface/automation.json, packages/spec/api-surface/root.json, packages/spec/authorable-defaults/automation.json, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

2 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/kernel/contracts/metadata-service.mdx (via /api/v1/packages/:packageId (route, bridged from symbol installPackage — its route source's handler names it))
• content/docs/protocol/kernel/error-handling.mdx (via /api/v1/packages/:packageId (route, bridged from symbol installPackage — its route source's handler names it))

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

• content/docs/releases/v12.mdx (via installPackage (symbol, a method of class SchemaRegistry))
• content/docs/releases/v17/17-0.mdx (via /api/v1/packages/:packageId (route, bridged from symbol installPackage — its route source's handler names it))
• content/docs/releases/v17/17-4.mdx (via /api/v1/packages/:packageId (route, bridged from symbol installPackage — its route source's handler names it))

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.

What this run could not see

• 9 changed file(s) yielded no anchor (packages/spec/api-surface/automation.json, packages/spec/api-surface/root.json, packages/spec/authorable-defaults/automation.json, …) — pages documenting those are invisible to this run
• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 100 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 137 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 61dd96f227e05a8d1d0c93a4f6a13cb7eaa6cdf4 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 0de10314fd550c25cf7c43994f2c5d5694433ca2 — the merge of head aac764cc36113b4e52820c1695715f000ccbe1b4 into base 61dd96f227e05a8d1d0c93a4f6a13cb7eaa6cdf4, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

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

node scripts/docs-audit/affected-docs.mjs --json 61dd96f227e05a8d1d0c93a4f6a13cb7eaa6cdf4

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

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

[os-litant]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: aac764cc36113b4e52820c1695715f000ccbe1b4

① Derived judgments

Governing ruling, established from the thread rather than the PR body. The card carries four ruling records. 5651572469 (batch #127 item 4, 2026-09-13, maintainer 「其他同意」) prescribed an artifact-stage body BESIDE the assembled one and the read-row rebind. 5716259259 (batch #149 item 1 letter B, 09-17) was presented after a pm:retriage (5706769218 / 5706819210) that did not cite #127, and prescribed the opposite: narrow the assembled body through entry-schema variants. Round R4 measured B as unexecutable (it refuses the in-repo fixture composeStacks builds today, contradicts the 「cannot drift」 invariant, and cannot meet its own acceptance because the inline array member keeps a z.function() handler) and delivered an empty diff by design (Release 5728544298). 5729478920 (batch #159 item 2 letter A, 09-18) restated #127 and WITHDREW B. Round R5 then stalled at A's own step 4: toRecordManifest leaves a residual that is neither a string nor a lowered record, and the producer is packages/objectql/src/registry.ts, outside the surface A drew — second empty diff (Release 5729976367). 5748934194 (batch #192 item 3 letter A′, 2026-09-20, maintainer 「192 同意」) is A plus the mechanism for step 4: a record-stage body with functions[].handler optional, the read rows rebound to THAT stage, and a bare-callable normalisation in objectql at the assembly boundary, ⛔ no minted ref, ⛔ no dropped entry. A′ governs the delivered diff, and the diff executes it step for step. The two places the PR body says it read the ruling rather than transcribed it are judged below.

What @objectstack/spec gains at this head (read from api-surface/, export-origins/, json-schema.manifest/, authorable-*/ and the source, not the PR body): root exports ArtifactStagePackageBodySchema, RecordStagePackageBodySchema and the four …Body / …BodyParsed type aliases; automation exports FlowFunctionLoweredDeclarationSchema with FlowFunctionLoweredDeclaration / …Parsed. json-schema.manifest/automation.json gains automation/FlowFunctionLoweredDeclaration; authorable-surface gains its handler and effect; authorable-defaults records effect = "pure"; the reference docs gain the section and index.mdx counts 1534. declaration-map/automation.json newly maps the AUTHORING FlowFunctionDeclarationSchema to automation/FlowFunctionLoweredDeclaration — that is the generator's documented base-pass rule (it follows the .extend() receiver of an exported def), not a hand edit, and it collides with nothing because the authoring declaration has no def of its own. Nothing exported is lost; the only removal is the module-private AssembledPackageRecordBodySchema const in package-api.zod.ts, which was never exported.

What changes. AssembledInstalledPackageSchema.manifest — the row both ListInstalledPackagesResponse and GetInstalledPackageResponse carry through InstalledPackageAtEitherStageSchema — rebinds from the assembled body with two z.unknown() holes to RecordStagePackageBodySchema. The published JSON Schema of the two responses therefore declares functions and hooks in full (the generated content/docs/references/api/package-api.mdx rows move from any to the lowered shapes). dropped-refinements.baseline.json gains four sites, all …manifest.hooks.element.object: that is HookSchema.object's pre-existing .refine() (hook.zod.ts:220) now reaching the runtime through a declared key while staying out of the JSON output — the ledger doing its job, not a weakened gate.

Is AssembledPackageBodySchema genuinely untouched? Yes, measured two ways. git diff 4b58dcf96..aac764cc3 -- packages/spec/src/stack.zod.ts is one widened import line plus a 142-line pure insertion between the AssembledPackageBodyParsed alias and ArtifactPackageSchema; AssembledPackageBodySchema (1283-1286), assembledPackageBodyShape (1167), composeStacks and the 「cannot drift」 invariant (3974) are byte-identical to the base. Both fenced files (data/hook.zod.ts, migrations/registry.ts) have an empty diff. Executed in an exported copy of this head (never in the clone): compose-stacks-manifest-preserve.test.ts + assembled-package-body.test.ts + the two new or changed spec test files — 4 files / 120 tests green. My own probe: the assembled body accepts a live callable in the map form, the array form and hooks[].handler, and both JSON stages refuse all three.

Do the two stage schemas admit what objectstack build and SchemaRegistry.installPackage really write? packages/cli/src/utils/lower-callables.ts:254-265 writes out[ref] = ref (a bare string) for a bare entry and { ...value, handler: ref } for a declared one; :188-204 lowers hooks[].handler to a string. Probe on the artifact stage: bare ref string accepted, lowered record accepted, callable refused, { effect } residual refused, empty-string ref refused. installPackage has exactly ONE record-writing site (registry.ts:4301, toRecordManifest(withDeclaredFunctionEntries(manifest))), so no update or upgrade path bypasses the normaliser. Probe on the record stage: { effect: 'writes' } accepted, {} accepted and parses to { effect: 'pure' }, array { name, effect? } and { name } accepted, string and lowered record accepted, callables refused. Hooks: a projected hook with neither handler nor body is accepted by all three stages because base HookSchema.handler is already .optional() (hook.zod.ts:252, deprecated in favour of body), so the PR's z.string().optional() inherits that optionality rather than adding it — ruling A′'s 「hooks[].handler a string」 is met. Strictness parity: a map entry with an unknown key is refused by all three stages (the lowered form derives from the strictObject declaration); an ARRAY entry with an unknown key is stripped by all three, because the authoring array member is plain z.object (stack.zod.ts:648) and the transcription matches it — no new tolerance in either direction.

OPEN QUESTION 1 — admitting both lowered spellings. Faithful, and I would have failed the other reading. The ruling's phrase 「functions entries the lowered declaration」 is shorthand for the lowered members of FlowFunctionEntrySchema, which are exactly two (flow-function.zod.ts:265-270: the bare ref string and FlowFunctionLoweredDeclarationSchema); ruling A's step 4, which A′ inherits verbatim, names the legitimate wire shapes as 「a string or a lowered record」. A stage admitting only the record form would refuse every artifact objectstack build writes for a bare function — the class of failure that withdrew B, one key across. Nothing in the tree supports the single-form reading.

Does the objectql change alter what GET /packages serves, and how? Yes, additively. withDeclaredFunctionEntries rewrites a bare callable map entry to { handler: fn, effect: DEFAULT_FLOW_FUNCTION_EFFECT } before the structural projection, which then leaves { effect: 'pure' } — the same value normalizeFlowFunctionEntry assigns a bare callable at boot (flow-function.zod.ts:324), so the record reports what the runtime actually does with the entry, not a minted value. Rows for packages with bare-callable entries gain those keys; nothing is removed; the showcase row goes 1 → 2. The projection's structural rule is untouched, no ref is minted, and the caller's manifest is copied only when an entry was rewritten. No in-repo consumer reads manifest.functions off a registry row (packages/runtime/src/app-plugin.ts:2282 reads the live bundle via resolveArtifactCollections; lit control manifest.objects hits). One asymmetry, not a defect: a bare entry lands as { effect: 'pure' } explicitly, while a declared entry authored without effect lands as {}; both sit inside the record stage, which defaults the latter on parse.

The two ruling items read rather than transcribed, my verdict on each. (a) unemitted-schemas.baseline.json is not edited: its reason line for Automation.FlowFunctionDeclarationSchema says the lowered record 「publishes normally」, which was false while the const was module-local and is true now that automation/FlowFunctionLoweredDeclaration is in the manifest — A′'s correction is achieved by making the sentence true. Acceptable. (b) The package-api.zod.ts docblock's last sentence is corrected in place, and the correction is true: scripts/build-schemas.ts imports the subpath namespaces (../src/kernel, ../src/ui, …) and never ../src/stack.zod, so those two members were never why ArtifactPackageSchema / ObjectStackDefinitionSchema publish no JSON Schema.

One class of row moves from tolerated to refused-by-declaration: a map entry whose effect is neither pure nor writes (reachable only from a defineStack({ strict: false }) host) now fails the record stage where z.unknown() accepted it. That is a producer defect the declaration exists to name, and packages/runtime/src/domains/packages.ts builds its response directly (deps.success({ packages: rows, … })) with no schema parse on the wire, so it changes what the contract says, not what the door does.

② Semver level

The written rule (AGENTS.md 1064-1068 at origin/main): a bug fix in a released package takes patch; the declaration is Clause-②: yes|no with at most one arm; yes takes at least minor; (narrowing) is BREAKING and must carry its FROM → TO migration when it removes or renames anything an author can write. Clause ② itself is defined in .claude/skills/pm-dispatch/references/lanes/spec.md:21-22: widening the accept set or expanding the public surface, however small, is Clause ②; narrowing is still contract surface but does not trigger it, and declaring yes on it is never an error. SKILL.md:515: pulling behaviour back to its declared contract does not touch it.

• @objectstack/spec: minor — correct. Nine new permanently published exports expand the public surface, so Clause-②: yes and at least minor. The read-row narrowing withdraws nothing an author can write: the values it now refuses are a live callable in a JSON row and an invalid effect, neither of which a valid producer emits (measured above on the build output, the projection residual and the array form), so no (narrowing) arm and no migration are owed. This is also exactly the grade ruling 🔗 Broken links detected in documentation #127 item 6 assigned to 「the read API's two keys narrow from anything to their declared shape」.
• @objectstack/objectql: patch — correct under the written rule; this is my reading of OPEN QUESTION 2. No export is added, removed or renamed; the payload gains entries the previous declaration (z.unknown()) already permitted, so no consumer could have relied on their absence; the record is being pulled back to what the package declared and to the record stage, which SKILL.md:515 says is not Clause ②. That is a bug fix in a released package, and the rule assigns it patch. The PR-level Clause-②: yes is satisfied by the spec changeset; the rule does not require every changeset in a yes PR to be minor. Grading it minor would not be an error under lanes/spec.md:22, but it is not what the rule asks for, and ruling A′ asked only that the payload change be declared in the objectql changeset, which it is.

③ Boundary flags

• Published contract semantics moved (handled). The two installed-package read responses now DECLARE manifest.functions and manifest.hooks instead of accepting anything. Every row the door really serves still parses (measured on the build output, the projection residual, the array form and a projected hook), and the door has no runtime response parse, so no runtime refusal that did not exist before is introduced. The four new dropped-refinements sites are recorded by name.
• GET /packages payload change (handled, declared in the objectql changeset). Additive; nothing that was on the wire leaves it.
• Tier H surface, for the maintainer's hand. skills/objectstack-platform/references/_index.md moves one generated line (net 0 tokens, check:skill-refs green). Because the Exports: fallback lists the first five non-constant exports in source order (packages/spec/scripts/lib/export-list.ts, slice(0, 5)), the stack.zod.ts pointer row now names ArtifactStagePackageBodySchema and RecordStagePackageBodySchema and NO LONGER names ArtifactPackageSchema or ObjectStackDefinitionSchema. That is the generator's rule rather than this PR's editing and is not a reason to fail, but it is a visible change to a customer-facing skill index, and the two names that dropped are the file's most consequential exports. A module doc block on stack.zod.ts in a separate change would stop the row depending on export order.
• No security or permission boundary, no migration or retirement shape, no gate weakened. AssembledPackageBodySchema, composeStacks, the drift invariant and both fenced files are untouched.

Measurement notes. The two new schemas carry the structural annotation z.ZodType(Record(string, unknown), Record(string, unknown)) — written here with parentheses in place of angle brackets — the same as the assembled body. Executed locally on an exported copy of this head: 4 spec test files / 120 tests, and a 25-row probe of the three stage schemas with lit and dark controls (z.string() converts, z.object({ a: z.function() }) does not; 55 / 55 / 55 shape members). NOT MEASURED locally: the @objectstack/objectql suite and the runtime conformance files — execution evidence for those is the 42 check runs on this sha (38 success, 4 skipped) read from the API — and the check:generated family, read from the diff and the same check runs.

Implemented-by: claude/issue-17518-assembled-package-body-inert-json
Reviewed-by: session_01LvwGppdonww4zGLWZo5rho

VERDICT: PASS

---

Generated by Claude Code