fix(cli): os generate schema falls back like every other toJSONSchema call site, so the IDE schema it exists to write is written

[claude]

Fixes #17873

Clause-②: no

Declared by the domain:cli seat (#6024), not by the implementer, and re-measured on this head 30361ba9b45626203f1e95267f0fb0baa22a9f0f rather than carried over from the claim: the per-file matcher over the added lines of packages/cli/src/commands/generate.ts returns zero exported declarations, with the control lit — the word export occurs 28 times in that file, so the zero is a reading and not a dark instrument. Removed export lines: 0. No new flag (Flags. appears on no added line). The handling is confined to the body of the module-private runSchemaGeneration, and packages/cli/src/index.ts publishes this module through export { default as GenerateCommand } — the default export only. ⇒ the axis stands down and the changeset's patch on @objectstack/cli stands. Card-side carrier: comment 5649039554 on #17873.

runSchemaGeneration in packages/cli/src/commands/generate.ts was the one z.toJSONSchema call site in this repository that neither fell back nor used the unrepresentable convention. Its bare two-argument call has no JSON form in either io direction on this tree, so the catch below it did printError(...) + process.exit(1) and the command could never reach its own fs.writeFileSync — for any repository, for any flags.

It now runs the three-tier ladder packages/spec/scripts/build-schemas.ts already runs for every schema it publishes, with packages/metadata-protocol/src/protocol.ts's unrepresentable: 'any' as the third tier. Each tier re-raises anything the known-unsupported predicate does not recognise, so a real conversion failure is still loud. The handling is entirely inside the module-private function: no new flag, no new accepted key, no new exported symbol.

Reproduction, with a lit control

Taken on this branch's merge base, through the built @objectstack/spec, with the card's own control:

CONTROL-lit (output mode, same options object, z.object({ a: z.string() })): OK
generate-schema call (output):                 THROWS - Transforms cannot be represented in JSON Schema
io: 'input':                                   THROWS - Function types cannot be represented in JSON Schema
io: 'input' + unrepresentable: 'any':          OK, 44 properties

Per member, in the strict authoring direction, 4 of 44 have no JSON form — exactly the four the card named:

packages   <-  Function types cannot be represented in JSON Schema
hooks      <-  Custom types cannot be represented in JSON Schema
functions  <-  Function types cannot be represented in JSON Schema
onEnable   <-  Function types cannot be represented in JSON Schema

After the change, a real run writes the artefact:

os generate schema -o objectstack.schema.json   ->  exit 0, 3245514 bytes
  i Converted in the authoring (input) direction - the output direction contains a transform with no JSON form
  i Nodes with no JSON form (live callables) are published as unconstrained - they accept any value in this schema

维护者速读(草稿)

改了什么。 os generate schema 过去 100% 失败——它是全仓唯一一处既不回退、也不用 unrepresentable 约定的 toJSONSchema 调用点。现在它按 build-schemas.ts 已有的三层阶梯降级,第三层用 metadata-protocol 已有的 unrepresentable: 'any'。⛔ 没发明第四种机制,⛔ 没加 flag,⛔ 没加导出符号。

为什么改。 分诊已裁:「命令应当像本仓其他调用点那样处理不可表达成员(回退 + unrepresentable: 'any'),⛔ 不应当裸调用后直接 process.exit(1)。这是往本仓已确立的约定上收,⛔ 不是新决策。」

⭐ 这份 IDE schema 现在对那四个成员承诺什么——逐条读自产物本身,不是读自源码。

产物落在第三层(authoring 方向 + unrepresentable: 'any'),$schema = https://json-schema.org/draft/2020-12/schema,顶层 type: object、44 个 properties、additionalProperties: false。

成员	产物里的片段	对作者的承诺
onEnable	只有 {"description": "…"}——⛔ 无 type、无任何约束	整个成员不再被校验:写什么都通过,IDE 对它一个字都不说
hooks	type: "array",items 是完整对象(required: ["name","object","events"]、additionalProperties: false);handler = {"anyOf": [{"type":"string"}, {}]}	数组与每条 hook 的结构照常校验;只有 handler 的「内联函数」那一支不受约束
functions	{"description": "…", "anyOf": [映射形式, 数组形式]},两支结构均保留;handler 位置为 {}	两种写法都照常校验;只有 handler 的值不受约束
packages	type: "array",items 完整;不受约束的点在 manifest.hooks[].handler 与 manifest.functions 的 handler 上	包体结构照常校验;只有其中嵌套的 handler 可调用体不受约束

⚠️ 一处需要更正卡与分诊的共同措辞:unrepresentable: 'any' 并没有把这四个成员整体变成 {}。整体变成不受约束的只有 onEnable 一个;另外三个成员的结构完整保留,被放宽的是它们内部的可调用叶子节点。另一半读数同样重要:产物里绝大多数 {} 与本次改动无关——只能严格转换、⛔ 根本不经过第三层的成员(objects / apps / views)本身就各带 40 / 11 / 41 个 {},它们来自 spec 里原有的 z.unknown() / z.any()。真正因本次放宽而产生的节点,全文档只有 5 个(4 个在 packages 下的 handler 上,1 个是 onEnable 本身)。

另外,已退役的键(如 hook.timeout)在产物里是 {"description": "[REMOVED] …", "not": {}} —— not: {} 是拒收,不是放宽:墓碑照常拒绝该键,并把迁移说明带给 IDE 用户。

⛔ 没有采纳的三条出路,各自会承诺什么。

• 按名丢弃这四个成员:IDE 会把 packages / hooks / functions / onEnable 当作未声明的键——在 additionalProperties: false 之下它们会被报成错误,即一份合法的 objectstack.config.ts 被标红。
• unrepresentable: 'any' 走 output 方向:同样能产出文件,但 output 派生会把 752 处带 default 的属性升级为 required,于是一份合法配置被报成「缺 752 个键」。本 PR 因此取 authoring 方向,并把这一点写成一条断言。
• 退役该命令:content/docs/api/data-flow.mdx 承诺的那条 IDE 自动补全通路(以及 VS Code 扩展的 jsonValidation 指向一个不存在的文件 —— schemas/objectstack.schema.json 从未存在过,也没有任何脚本生成它 #5028 想要的那个文件)将永久没有生产者。⛔ 退役属维护者底线,本席无权执行。

风险与代价(含回滚)。 风险集中在一句话:这份 IDE schema 从「不存在」变成「存在但对上述可调用叶子不设限」。回滚成本极低——改动全在一个模块私有函数体内,git revert 即回到今天的「命令必失败」状态,⛔ 不影响运行时、⛔ 不影响任何已发布的导出面。

席位意见。 ⛔ 本席不答这一问,也不代答。 这四个成员对外承诺什么是对外承诺的改变,分诊明写「⛔ 不可裁(确属产品)」,交付席与本席都无权替你选;上面那一问就是原样交到你手上的。本席只提供三件可核的事实,⛔ 不含推荐:

1. 上表逐条读自产物本身,不是读自源码;本席已独立复核其中的载重项(复核见本 PR 的 ## Contract review 评论),并确认卡与分诊共同的措辞「四个成员整体变成 {}」只对 onEnable 成立——这是交付方主动更正上游措辞,⛔ 不是本席事后补的。
2. 本 PR 不依赖你的答案。 改动全在一个模块私有函数体内,回滚是一次 git revert,⛔ 不动任何已发布的导出面、⛔ 不改运行时行为。你答 no 不会让已落地的东西变成半成品。
3. 若答 no,另外两条路各自会承诺什么已列在上一节(按名丢弃 ⇒ 合法配置被标红;output 方向 ⇒ 合法配置被报缺 752 个键),⛔ 本席对其中任何一条不作推荐。

⭐ 你要做的(一个 token 即可)。 上表就是本 PR 交付的产物对那四个成员的承诺,现在把它交给你否决:接受吗?yes / no。

Acceptance notes

Measured on the way through; none of it belongs to this card.

• The pin runs in the NIGHTLY tier, not the merge queue. It spawns the CLI, so it is an e2e test by behaviour and carries the .e2e.test.ts name this repo's name-based switch (scripts/nightly-tiers.mjs) uses to move e2e off per-PR and merge-queue runs. runSchemaGeneration is module-private and §0 forbids exporting it, so spawning is the only way to run the command — there is no cheaper queue-tier pin available without a new export. Naming it out of the .e2e tier purely to buy queue coverage would be gaming that switch, so it is named for what it is and the consequence is declared here instead. Noted, not filed.
• hooks.timeout is published as a tombstone, and that is the tombstone working. {"description": "[REMOVED] hook.timeout was removed in @objectstack/spec 17 …", "not": {}} — not: {} refuses every value, so an IDE rejects the retired key and shows the migration line. Noted, not filed.
• Docs read, both ways. The only page in content/docs/** that mentions this command is content/docs/api/data-flow.mdx:200 — "JSON Schema | VS Code, IntelliJ | Autocomplete and validation for objectstack.config.ts (via os generate schema)". It states that the command produces such a schema and says nothing about what it promises per member, so it is true of the artefact this PR now produces and needs no edit. content/docs/deployment/cli.mdx's os generate section documents only the metadata-scaffold types and never mentions the schema sub-command at all. Control for the grep: os generate lights 5 pages in the same sweep. Noted, not filed.
• The tier order is build-schemas.ts's, and it has one latent consequence worth stating. Tiers 1 and 2 both throw today, so the landing tier is 3 regardless of order. If a future spec removed the transform, tier 1 (output, strict) would land and the document would flip to the output derivation — the 752-defaulted-keys shape above. Assertion (e) of the pin is what would catch that. Noted, not filed: nothing reproduces it today.
• VS Code 扩展的 jsonValidation 指向一个不存在的文件 —— schemas/objectstack.schema.json 从未存在过,也没有任何脚本生成它 #5028's half is untouched — no jsonValidation pointer is added or moved here.

Verification

leg	reading
pin, green	Test Files 1 passed (1) · Tests 8 passed (8)
ablation — handling reverted to the bare call on disk	Test Files 1 failed (1) · Tests 8 failed (8)
ablation, on-disk proof	injected marker = 1 · widenedUnrepresentable = 0 · unrepresentable: 'any', code lines = 0 · mutated blob 6d2865d0 ≠ HEAD blob 1fccbeff
restore	git diff HEAD empty · git hash-object = 1fccbeffad798a50a13b3f8a97859ca574e16a23 = the HEAD blob
pin, re-run after restore	Test Files 1 passed (1) · Tests 8 passed (8)

The ablation script carried trap restore EXIT INT TERM with an absolute REPO_ROOT, restored with git checkout HEAD -- <path> (never the bare form, which restores from the index), and refused to report a reading at all unless the mutation was proven present on disk — it fired once, correctly, on a first attempt whose expectation had miscounted comment text.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TSf4DV7ziu4V5j73e46b7c

---

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 4 documentable anchor(s).

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

• content/docs/api/data-flow.mdx (via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/deployment/cli.mdx (via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/protocol/kernel/lifecycle.mdx (via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/protocol/objectql/types.mdx (via os generate (command, read off packages/cli/src/commands/generate.ts))

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

• content/docs/releases/v17/17-4.mdx (via os generate (command, read off packages/cli/src/commands/generate.ts))

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

• 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.

Coarse fallback — 24 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 134b410a90c6e5e7311c840076dcd5d486841f1d → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 9ca24545986759e0b7fcd9b58584b069975e1336 — the merge of head 30361ba9b45626203f1e95267f0fb0baa22a9f0f into base 134b410a90c6e5e7311c840076dcd5d486841f1d, 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 9ca24545986759e0b7fcd9b58584b069975e1336 && git checkout 9ca24545986759e0b7fcd9b58584b069975e1336
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 134b410a90c6e5e7311c840076dcd5d486841f1d 30361ba9b45626203f1e95267f0fb0baa22a9f0f && git checkout -B drift-repro 134b410a90c6e5e7311c840076dcd5d486841f1d && git merge --no-ff 30361ba9b45626203f1e95267f0fb0baa22a9f0f

node scripts/docs-audit/affected-docs.mjs --json 134b410a90c6e5e7311c840076dcd5d486841f1d

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

[claude]

Contract review — PR #17903 (card #17873)

Head reviewed: 30361ba9b45626203f1e95267f0fb0baa22a9f0f. Three paths, +359/−3. Readings taken 2026-09-12T22:43–23:20Z against origin/* refs and the merge base 134b410a90c6e5e7311c840076dcd5d486841f1d.

⚠️ Independence: the implementer is a mode:subagent dev of this same PM session; ⛔ not an arm's-length second opinion.

① Derived judgments — each measured here, ⛔ none ratified from the report

1. ⛔ The half triage refused to rule is DECLARED, not defaulted — and this seat did not answer it either. The ## 维护者速读(草稿) carries a four-row table read out of the artefact, names all three alternatives with what each would have promised (drop-by-name ⇒ a valid config reported invalid under additionalProperties: false; unrepresentable: 'any' in the output direction ⇒ 752 defaulted properties promoted to required, so a valid config is reported as missing 752 keys; retirement ⇒ the IDE path content/docs/api/data-flow.mdx:200 promises loses its only producer), and ends in one token: 「接受吗?yes / no」. ⚠️ The section shipped with an empty 「席位意见。」 heading — a maintainer-facing blank. This seat filled it, with process only: an explicit ⛔ refusal to answer or recommend, the three checkable facts, and the note that the PR does not depend on the answer. ⛔ No product judgment was added by this seat anywhere.

2. ⭐ The delivery CORRECTED the card and triage's shared wording, and the correction is right. Both said unrepresentable: 'any' turns the four members into {}. Measured on the artefact, that is true of onEnable alone; hooks, functions and packages keep their full structure and only their callable leaves widen — five widened nodes in the whole document. The pin encodes exactly that claim rather than restating it in prose: hooks.handler asserts branches.filter(isUnconstrained) toHaveLength(1) beside a surviving {type:'string'} branch; packages asserts the same length-1 on the nested manifest.hooks[].handler; onEnable asserts Object.keys(onEnable) equals ['description']. ⇒ a future widening of any other branch reds the pin. ⭐ It also says which {} are not this change's (objects 40 · apps 11 · views 41, from the spec's own z.unknown()/z.any()), and that a retired key's {"not": {}} is a refusal, not a widening — the two readings a censusing reviewer would otherwise get backwards.

3. ⭐ The third tier COULD NOT have been spec's, and that is forced by the ruling rather than chosen. build-schemas.ts's third tier is projectByPruningUnionBranches, which exists only at packages/spec/scripts/build-schemas.ts, packages/spec/scripts/lib/union-branch-projection.ts and its test; packages/spec/src/index.ts spells it zero times, with the control lit (export → 72 in that file). ⇒ importing it would require editing packages/spec, which §0 forbids and which this lane's standing rule routes to the domain:spec seat regardless of who needs it. So tier three is metadata-protocol's unrepresentable: 'any' — ⛔ not a fourth mechanism, and exactly what triage's acceptance line prescribed.

4. No published surface moves, and the level follows — re-measured on this head. The per-file matcher over the added lines of packages/cli/src/commands/generate.ts returns zero exported declarations, control lit (export occurs 28 times in that file); zero export lines removed; zero added lines mention Flags. or static flags. packages/cli/src/index.ts publishes this module as export { default as GenerateCommand } — the default export only. Paths under packages/spec/: 0. Under content/docs/releases/: 0. ⇒ Clause-②: no and @objectstack/cli: patch both stand. ⛔ Nothing was raised to quiet a gate and ⛔ no changeset was dropped.

5. The pin asserts the ARTEFACT, ⛔ never 「it did not throw」. Five groups: (a) exit 0 and the output file written by name; (b) the bytes parse as JSON; (c) $schema is the declared draft, $id, type: object, >30 properties, additionalProperties: false; (d) one sub-test per member, above; (e) the authoring derivation, no defaulted property published as required.

6. ⭐ And row (e) was VACUOUS on the first ablation — the dev found that itself and strengthened it BEFORE reporting. An empty document has no offenders either, so offenders == [] proved nothing; it now carries a lit control, expect(census.inspected).toBeGreaterThan(0), and both ablation legs were re-taken against the strengthened file. ⭐ That is the order's own standard (「a pin that stays green under ablation is vacuous and must be strengthened before you report」) met without being asked twice.

7. The ablation is executed, and its restore is proved by STATE rather than by an exit code. Mutated: 8 of 8 rows red, command exit 1, no file written. On-disk proof taken before any verdict was read — injected marker ×1, unrepresentable: 'any' ×0, and a mutated blob 6d2865d0 differing from HEAD's 1fccbeff. Restored: 8 of 8 green, with git diff HEAD empty and git hash-object equal to the HEAD blob. ⭐ A first attempt whose expectation had miscounted comment text was discarded and the anchor corrected, ⛔ not silently re-run.

② semver level — patch on @objectstack/cli

Consistent with ①.4: the command is pulled back to behaviour it already declares (it could never reach its own fs.writeFileSync), with no exported symbol and no new accepted flag or key. Check Changeset is green on this head after the declaration was written into the body — see ③.b.

③ Boundary flags, the docs advisory, and one consequence stated plainly

a. ⚠️ The central pin runs in the NIGHTLY tier, ⛔ NOT the merge queue — and that is the honest naming rather than a gap being hidden. It spawns the CLI, so it is an e2e test by behaviour and carries the .e2e.test.ts name scripts/nightly-tiers.mjs switches on. runSchemaGeneration is module-private and §0 forbids exporting it, so spawning is the only way to run the command at all; renaming it out of the tier purely to buy queue coverage would be gaming that switch. ⇒ the consequence, said plainly: this PR's load-bearing pin does not gate the merge queue, and the first PR to touch this command inherits that. Declared in the PR's own acceptance notes. ⛔ Accepted as scoped, ⛔ not waved off.

b. The red Check Changeset was this seat's to clear, and it was cleared by a BODY EDIT alone. scripts/check-changeset-no-major.mjs reads the clause-② declaration out of github.event.pull_request.body and refuses a PR whose declaration is unreadable while a changeset grades patch a package the diff grew; the delivered body carried no such line. Written 22:43Z after re-measuring the axis on this head (①.4); new generation 103633509537 returned success with no push and no re-run — the workflow subscribes to edited for exactly this. Record 5649185377.

c. ⭐ The docs advisory's four hand-written pages were answered with a reading, and this seat re-took all four independently. Control lit on every page (os generate fires 1 / 7 / 6 / 3):

page	what it says	falsified?
content/docs/api/data-flow.mdx:200	the only os generate schema mention in the four: the JSON Schema gives VS Code / IntelliJ autocomplete and validation for objectstack.config.ts	no — ⭐ and it was describing a capability that could not run; this PR makes the page true
content/docs/deployment/cli.mdx	os generate schema ×0; its seven mentions are the metadata-scaffold types and the os generate <type> <name> table row	no
content/docs/protocol/kernel/lifecycle.mdx	os generate schema ×0; all six are os generate migration	no
content/docs/protocol/objectql/types.mdx	os generate schema ×0; all three are os generate migration	no

content/docs/releases/v17/17-4.mdx is release-owned: 0 paths in the diff, ⛔ not read for editing.

d. Gates. 63 families derived, 63 run, all exit 0. ⭐ Four returned exit 3 = PREREQUISITE NOT MET on the first sweep (check:dual-build-cjs-loads, check:i18n, check:i18n-coverage, check:i18n-walk-parity), all for the same missing packages/cli/dist; re-run after the build, all four returned 0, and neither reading is reported as the other. pnpm lint exit 0 at this head. Package legs: typecheck 0; vitest run 249 files / 3332 tests passed. Heavy runs went through os-verify-lock.sh with verdicts read from its VERDICT line.

e. ③ is already satisfied on this head: 34 check names, all terminal — 29 success / 5 skipped / zero failures.

Independence pair

Implemented-by: claude/issue-17873-generate-schema-unrepresentable (mode:subagent)
Reviewed-by: os-sales — domain:cli execution seat, issue #6024, session_01TSf4DV7ziu4V5j73e46b7c
Independence: SELF-REVIEW — the implementer is a subagent of the reviewing seat's own session

Tier: default judgment — 「余席条款②复核 = 默认判断档自审加门禁」.

Verdict

PASS. ⛔ No carrier to clear: the claim declared the axis no, the measurement on this head agrees, and check-clause2-carriers --pair 17903 returns exit 0 (both carriers agree, no widening tell). ⇒ the landing pre-check is ③ every check green, which this head already meets. ⚠️ Landing this does not answer the maintainer's question in ①.1 — that question stands open on the card after the merge, and ⛔ merging is not consent to it: the rollback is one git revert of a module-private function body.

---

Generated by Claude Code