给 6 个 zod 模块补真正的模块头 doc block —— #5059 新规则下这些页面的开篇介绍需要显式声明

[os-zhuang]

Part of #5059(跨座位转移:落点在 packages/spec/src/**/*.zod.ts,属 domain:spec 座位文件面,domain:spec-tooling 座位红线之外)。域标签交分诊座位补。

背景

#5059 / PR #6134 修好了参考页开篇被内部注释顶替的缺陷:getFileDescription() 现在只认不属于任何符号的模块级 doc block(列 0、位于头部区、且不紧邻声明——即 TSDoc 自身的 attachment 规则)。规则落地后 6 个受害页治愈、178 页描述逐字节保留。

本单要做的

副作用是:另有约 6 页的开篇散文读起来是真的模块介绍,但写在紧贴第一个 schema 处,按新规则归 TSDoc 所有(仍是该符号的悬停文本),页面因此不再显示它:

• content/docs/references/data/driver-postgres.mdx
• content/docs/references/data/driver-mysql.mdx
• content/docs/references/data/driver-sqlite.mdx
• content/docs/references/cloud/template-manifest.mdx
• content/docs/references/system/doc.mdx
• content/docs/references/api/error-code-ledger.mdx

修法:给这 6 个 zod 模块各加一个真正的模块头块(即一个不文档化任何符号的顶层 doc block,与新规则相容),介绍随之回归页面;然后重新生成 content/docs/references/**。这些是 driver / manifest / doc 类页面,作者确实会落在上面,介绍有真实拉动。

⛔ 明确排除的做法(PM 2026-08-07 裁决)

不得改回「若 doc block 附着于第一个导出的 schema 就照发」这类宽容回退——那正是把 Transport Protocol Enum 发布到 Realtime 参考页的规则,且在结构层面与正确情形不可区分。#5059 的全部价值就在这条规则的严格性:想要页面开篇,就写一个真模块头(178 个现存源文件已经这么做了)。

优先级

低。rc.4 按 A 方案(保持现状)发布——散文未丢失、页面仍有 Source 提示,「宁缺勿错」一致执行。本单是把介绍正确地要回来。

Refs: #5059 · PR #6134

[hotlong]

Triage (maintainer-directed batch, 2026-08-07): routed domain:spec — the fix lands in six packages/spec/src/**/*.zod.ts modules (real module-header doc blocks per the #5059 rule) + docs regen. Anchored by code read; triage seat may veto.

---

Generated by Claude Code

[hotlong]

Triage: domain:spec → domain:spec-surface (seat #6298; existing-stock migration pass, maintainer-instructed 2026-08-07). Admission test met — adding real module-header doc blocks to six zod modules under the #5059 rule is text only; regenerated reference pages ride the same PR per the seat's "产物随源走" clause.

---

Generated by Claude Code

[hotlong]

pm:blocked applied + Blocked-by: #5783 body line (spec-surface seat #6298, session session_01JTSZAjgtL3oR6YcpNDhW3T). Reason: both cards edit the error-code-ledger zod module — #5783 removes the OVERLAY_PERSISTENCE_FAILED entry, this card adds the module-header doc block. Same-file claims serialize strictly; #5783 is target:v17 and flies first.

For the post-unlock dispatch: this card's regen (6 reference pages) joins whatever regen train is then in flight — the error-code-ledger.mdx page will have just been regenerated by #5783, so the module-header edit rides on the post-#5783 state of the file; branch off fresh origin/main and the four-step resync applies at landing as usual.

---

Generated by Claude Code

[os-project-manager]

Unlock + claim (paired with the body/label edit just made in the same pen):

pm:blocked removed and the Blocked-by: #5783 body line deleted together — #5783 closed via PR #6389, merged to main as d9bef4590, so the same-file serialization on the error-code-ledger zod module is released. Unblock condition verified against origin/main, not memory.

Claim: PM loop round 2 (domain:spec-surface seat #6298)
Session: session_018ffcE95NaMJcL9XJ9VDYgk (GitHub os-project-manager)
Branch: claude/issue-6145-module-header-doc-blocks
Worktree: objectstack-issue-6145
Domain: domain:spec-surface
File surface: the 6 zod module source files behind the listed reference pages (data/driver-postgres, data/driver-mysql, data/driver-sqlite, cloud/template-manifest, system/doc, api/error-code-ledger) — one true module-header doc block each, nothing else in those files; the regenerated content/docs/references/** pages for exactly those modules; .changeset/*.md (stop on breach; explain in the report)
Serial constraints cleared: predecessor #5783 / PR #6389 MERGED (d9bef4590) — error-code-ledger.zod.ts is fresh on main and the branch is cut from fresh origin/main per the handover ledger's instruction. In-lane in-flight #6423 (#6365, in merge queue) is file-disjoint (object.zod.ts + batch-20 test). Sweep #6243 / PR #6288 merged. #6083 / PR #6279 (bare-name flip) still unmerged — minimal diff, zero alias zones. This card regenerates the references tree; no other regen of that tree is currently in flight from this lane.
Container weight: M (6 doc blocks + reference regen), mode:subagent shared container.

---

Generated by Claude Code

[os-project-manager]

ACCEPT — PR #6447 (spec-surface seat #6298, session session_018ffcE95NaMJcL9XJ9VDYgk; reviewed directly from the PR's diff, body and check runs at head 490ab51 — the review ran ahead of the dev's JSON report at the maintainer's request to compress landing latency; the report, when it arrives, is archival).

Verified:

• 14 files, all accounted for against the claim's declared surface: the 6 zod modules (each doc block promoted verbatim to a true module header above the imports — a pure move; the PR proves the per-file non-empty-line multiset is byte-identical to main), exactly the 6 reference pages regenerated (+110/−0 — the other 178 pages untouched), the corpus pin in file-description.test.ts (asserts the six SOURCES' openings via the real findModuleDocBlock(), with reverse verification: re-gluing one header turns it red), and one substantive English changeset (@objectstack/spec: patch).
• Rulings honored: the ⛔-excluded lenient fallback was not taken — scripts/build-docs.ts / scripts/lib/file-description.ts and all gate machinery untouched; content/docs/releases/ untouched; object.zod.ts untouched; authorable-surface.base.json not in the diff (no acceptance-surface movement — the source edits are comment/import reordering only).
• Same-day-churn handling: fix(spec,rest): OVERLAY_PERSISTENCE_FAILED leaves the error-code ledger, plus three same-origin residues (#5783) #6389's fresh "Retiring a code" section rides inside the promoted error-code-ledger header unmodified; spec: ADR-0122 phase 2 — flip bare names to parsed semantics (#6083) #6279 (bare-name flip) was merged into the branch with zero conflicts and the ESLint-job gate list re-run green afterward, per the PR body.
• Premise verified per file by the dev with the real findModuleDocBlock() probe on current main (all six NULL before, all six answering after) — not assumed from the card.
• CI: ESLint job success (20:29:37Z). TypeScript Type Check still in_progress at review time — per gate discipline the ready-flip + auto-merge arm happens the moment its conclusion is success (checkpoint armed). One open compliance item handed to the dev mid-flight: the PR body is being rewritten in English per the 2026-08-06 language policy (substance unchanged).

---

Generated by Claude Code