docs: every docs code sample parses with @objectstack/spec 17.7.0, held by a CI gate (closes #316)

[objectstack-fleet]

Fixes #316

This is the second of two stacked PRs that close the docs code-sample family (#301, #307, #316). It is based on PR A (staged/issue-316-a), and its diff here is against A. It does two things:

• The samples on the remaining 14 English pages parse with @objectstack/spec 17.7.0 (npm latest; versioned in objectstack 4e4e8814).
• A CI gate keeps every ts/js block on every English page parsing against a pinned spec.

With A and #315 (already on main), every English code sample parses.

Size: 4280 changed lines against A (+1100/−3180). check-governed-merges --test on this PR's 38 paths, with that size, answers "NOT governed … 4280 changed line(s) ≤ 5000". Each English correction ships here with its own sibling deletions, as ruling A requires.

Two commits on A's tip e585f02: 9144f75 (the pages) and a45e682 (the gate). This branch's tree equals the reviewed work merged onto main: git merge-tree --write-tree dc8213d 853ed96 gives 80a304d, and so does staged/issue-316-b^{tree}, so git diff dc8213d staged/issue-316-b is byte-identical to that merge's diff.

What changed, per page

Sources are the published spec, packages/spec/src/** at objectstack 4e4e8814. The npm tarball ships the same files. ObjectStack's public docs at the same commit are cited as "ObjectStack content/docs/…".

• reference/cel.mdx:
  • The six one-liners become real slots: a formula field; a script rule's condition, which is TRUE for the invalid record; a field's visibleWhen; a start node's condition; a schedule's expression: cron…; and a notify node's plain-string title.
  • The "Where each one is used" table names keys that exist. Field.conditionalRequired becomes requiredWhen: the alias was removed in protocol 17 (data/field.zod.ts:1817). Validation.predicate becomes a script rule's condition. Flow.step.when becomes a start node's or an edge's condition. Action.guard becomes visible / disabled.
  • tmpl for notification subjects/bodies is reversed. Measured, NotifyConfigSchema refuses a tmpl value for title ("expected string"). The typed template slots are the deprecated titleFormat (data/object.zod.ts:2239) and the AI prompt templates (ai/model-registry.zod.ts:121).
  • The { dialect, source } type signature is opted out of the gate and renders as before.
• build/agents.mdx:
  • knowledge was removed in 17.0.0 (ai/agent.zod.ts:429). Grounding now goes in instructions, and source access is set per source.
  • memory.shortTerm (:479) and longTerm.store (:196) were removed. The memory table now documents longTerm.enabled, longTerm.maxEntries and reflectionInterval.
  • "Any manual flow (type: 'manual')" becomes a type: 'flow' action (ObjectStack ai/actions-as-tools.mdx).
• configure/data-sources.mdx (it has no locale siblings: docs: delete the 14 locale siblings that still forecast federation as unshipped #290 deleted them):
  • config.connection is not a key; a postgres config is flat.
  • An inline password is refused, even one read from the environment. The secret is named in external.credentialsRef (data/datasource.zod.ts:318, prescription in data/driver/common.zod.ts:106).
  • The sample uses defineDatasource(). The claim that a plain object "is exactly what the examples/app-crm stack does" is reversed: at 4e4e8814 that stack uses defineDatasource.
  • The manifest gets type and name, and AnalyticsReplica is declared.
• build/interface/apps.mdx: mobileNavigation was removed in 17.0.0, "fully unimplemented" (ui/app.zod.ts:1649).
• build/interface/dashboards.mdx: refreshIntervalSeconds (ui/dashboard.zod.ts:1775); no certified measures, a key that does not exist.
• quickstart.mdx: Field.lookup('sys_user', …). configure/permissions/record-access.mdx, reference/rest-api.mdx: the objects get their required fields.
• build/interface/forms.mdx, build/interface/pages.mdx, configure/permissions/{field-level-security,permission-sets}.mdx, reference/field-types.mdx: fragment comments, real options, and conditionalRequired → requiredWhen in the field-types table.
• reference/objectql.mdx: the query-shape type signature is opted out and renders as before.

Locale siblings: ruling A of #256 (AGENTS.md, #319)

Page	Call	Siblings
reference/cel	delete: tmpl for notifications is reversed; the table's keys are removed or renamed	de, es, fr, ja, ko, zh-Hans, zh-Hant
build/agents	delete: the knowledge block, the memory tiers and the manual flow are removed	de, es, fr, ja, ko, zh-Hans, zh-Hant
build/interface/apps	delete: mobile navigation is removed	zh-Hans, zh-Hant
build/interface/dashboards	delete: certified measures are removed	zh-Hans, zh-Hant
forms, pages, record-access, rest-api, field-level-security, permission-sets, field-types, objectql	keep: code shape only	stale, reported
data-sources, quickstart	nothing to delete	none exist

18 files are deleted. Before each deletion, I confirmed that the sibling carries the claim. gen-zh-hant --check passes with 54 files.

The gate: .github/scripts/check-doc-samples.mjs

The script header has the full contract.

• What it reads: every English page (the locales come from apps/docs/lib/i18n.ts), and in it every fenced ts/js block.

• How it judges a block, by the first rule that matches:

  1. the opt-out marker;
  2. not a spec sample (N/A): it imports only from other packages, or it constructs a class one of them provided;
  3. CEL strings, checked for slot shape only, because the spec ships no CEL parser;
  4. a fragment, whose first comment names its kind (22 kinds; docs: make the views and flows code samples parse with @objectstack/spec 17.7.0 #315's own comments match unchanged);
  5. statements, evaluated as published with only TypeScript syntax removed.

  Every spec constructor call is a parse. Imports are checked against the entry point, and type imports go through the TypeScript compiler. Every flow is also parsed against its executor contracts, and a stack's requires is judged with its page's flows, as Docs code samples the current @objectstack/spec refuses: the remaining view fragments in build/interface/views.mdx and the send_email flow action in build/automation/flows.mdx #307 did. A block that matches no rule fails.

• The opt-out marker is {/* doc-sample: skip — WHY */}, on the last line before the fence. It is an MDX comment: it renders nothing, and lib/source.ts strips it from the llms bodies. Use it for a counter-example or a type signature. A marker without a reason, a marker that drifted off its fence, and a marker on an unread block all fail. Two blocks use it, both type signatures.

• The pin: .github/scripts/doc-samples/package.json pins @objectstack/spec to exactly 17.7.0, with an npm lockfile. The gate refuses any other installed version.

  • It sits outside the pnpm workspace on purpose. As a devDependency of tools/ci-scripts, it re-resolved fumadocs-core's optional zod peer from 4.4.3 to 4.6.5 while fumadocs-mdx kept 4.4.3. That is two zod copies in the docs build.
  • The workspace lockfile is untouched.

• Bumping it: a Dependabot entry for /.github/scripts/doc-samples, in the objectstack group, opens the bump as a PR. The gate runs on that PR, so a release that newly refuses a sample turns its own bump red. By hand, run npm install --prefix .github/scripts/doc-samples --save-exact @objectstack/spec@VERSION.

• CI: npm ci --prefix .github/scripts/doc-samples, then the gate, next to "Generated zh-Hant is current", before type-check. The --self-test joins tools/ci-scripts/run-self-tests.mjs.

  • A spec bump moves the test task's hash. Measured with the lockfile mutated and then restored: a36d68f → bd1b30c → a36d68f.

• Self-test: 51 cases. Each of the 22 fragment kinds must have a fixture it passes and a fixture it refuses.

• Cost: the gate takes about 2 s and the self-test about 6 s; npm ci installs 3 packages.

Parse results: @objectstack/spec 17.7.0

Page	A (= dc8213d here) as published	fragments classified	this PR
build/agents.mdx	1 pass, 1 refused	1 pass, 1 refused	2 pass
reference/cel.mdx	1 pass, 7 unchecked	3 pass, 4 refused, 1 skip	7 pass, 1 skip
build/interface/dashboards.mdx	0 pass, 1 refused, 6 unchecked	5 pass, 2 refused	7 pass
build/interface/apps.mdx	1 pass, 3 unchecked	3 pass, 1 refused	3 pass
configure/data-sources.mdx	0 pass, 4 refused	0 pass, 4 refused	4 pass
build/interface/forms.mdx	1 pass, 3 unchecked	3 pass, 1 refused	4 pass
reference/rest-api.mdx	0 pass, 1 refused	0 pass, 1 refused	1 pass
reference/field-types.mdx	0 pass, 4 unchecked	4 pass	4 pass
configure/permissions/record-access.mdx	0 pass, 1 refused	0 pass, 1 refused	1 pass
build/interface/pages.mdx	0 pass, 4 unchecked	4 pass	4 pass
quickstart.mdx	0 pass, 1 refused	0 pass, 1 refused	1 pass
configure/permissions/field-level-security.mdx	0 pass, 1 unchecked	1 pass	1 pass
configure/permissions/permission-sets.mdx	0 pass, 1 unchecked	1 pass	1 pass
reference/objectql.mdx	0 pass, 1 unchecked	1 skip	1 skip
These 14 pages	4 pass, 9 refused, 30 unchecked	25 pass, 16 refused, 2 skip	40 pass, 2 skip

"Unchecked" means a fragment with no comment saying what it is; the gate fails it. The middle column adds only those comments.

Red and green:

Tree	Verdict
dc8213d	EXIT 1 · ✗ doc samples: 66 block(s) refused or unchecked on 21 page(s) · 35 pass · 10 not a spec sample · 0 opted out
A (e585f02)	EXIT 1 · ✗ doc samples: 39 block(s) refused or unchecked on 14 page(s) · 62 pass, exactly this PR's 14 pages
this PR (a45e682)	EXIT 0 · ✓ doc samples: every ts/js block on 79 English page(s) parses with @objectstack/spec 17.7.0 · 98 pass · 10 not a spec sample · 2 opted out
--self-test	EXIT 0 · ✓ self-test: 51 case(s) hold, and each of the 22 fragment kinds has a fixture it passes and one it refuses (@objectstack/spec 17.7.0)

Page-text ablation, on a scratch copy of the merged tree:

• retention: { maxAge: '14d' } → '14d' (anchor 1 → 0): EXIT 1, lifecycle.retention: Invalid input: expected object, received string.
• Deleting the objectql marker (1 → 0): EXIT 1, "no fragment kind this gate knows".

Verification at a45e682

Gate	Verdict
pnpm install --frozen-lockfile	EXIT 0, and the workspace lockfile is unchanged
pnpm turbo run type-check --continue --force (lock)	VERDICT command-exit 0 · ✓ Types generated successfully · 1 successful, 0 cached
NEXT_PRIVATE_STANDALONE=true pnpm turbo run build --force (lock)	VERDICT command-exit 0 · 1 successful, 0 cached. The OG-image font-fetch errors are this container's egress, and they are non-fatal
pnpm turbo run test --force (lock)	VERDICT command-exit 0 · ✓ 11 self-test(s) passed
check-doc-samples.mjs / --self-test	EXIT 0 / EXIT 0 (above)
check-locale-surface.mjs	EXIT 0 · ✓ every advertised URL has a source file and every source file is advertised; … neither llms consumer carries … an MDX comment
check-positioning.mjs	EXIT 0 · ✓ positioning: 4 copies equal their constants; the brand is right in 659 pages and 2 llms bodies; no stale sentence in 79 English sources and the en entry of 2 legal pages
check-search-locales.mjs	EXIT 0 · ✓ search locales: all 8 locales answer 200, find "permissions", find every own page by its title within the first 3 pages, and find nothing for a nonce
gen-zh-hant.mjs --check	EXIT 0 · ✓ zh-Hant: 54 generated file(s) match the zh-Hans sources byte for byte.
Ownership, with the workflow argv against this PR's base (git diff --name-status --no-renames staged/issue-316-a...HEAD), --actor hotlong, TRANSLATION_BOT_LOGIN set	EXIT 0 · ✓ 38 file(s) changed: 18 translation artifact(s) deleted, none added or modified. With the bot as actor (the control): EXIT 1. Against origin/main...HEAD: EXIT 0 · 64 files, 36 deleted; the control is EXIT 1
check-translations.mjs	EXIT 0 · ✓ translations gate passed. Reported, not blocking: zh-Hans 39 stale / 39 missing; the others 20 stale / 59 missing
check-translation-output.mjs --self-test / --files	EXIT 0 / EXIT 0 · ✓ translation output gate passed (213 pre-existing finding(s) reported)
check-node-floor.mjs --self-test / run	EXIT 0 · ✓ self-test: 17 rule case(s), 24 satisfies case(s) and 18 range case(s) … / EXIT 0 · ✅ Every declared floor clears what the dependency tree requires, and the declarations agree.
check-half-states.mjs --self-test	EXIT 0 · 1551 cases pass
Control bytes in the changed files	0

Browser. These pages are byte-identical to the reviewed work, so its measurements still apply. next start served the build, and Chromium loaded the changed pages at 1440 and 390:

• HTTP 200 and the right h1 on every page;
• scrollWidth equal to the viewport;
• every code box inside the viewport: 303–1137 px at 1440, 17–373 px at 390;
• no marker text visible;
• /zh-Hant/docs/reference/cel answers 200 with the English body.

I looked at the CEL examples and table, the agent memory table, the apps mobile note, the data-sources declaration and the objectql type signature.

NOT MEASURED: behaviour on a running ObjectOS runtime.

Acceptance notes

• A spec-internal mismatch, for objectstack. packages/spec/src/shared/expression.zod.ts's dialect table lists the template dialect for "notification subjects/bodies". But NotifyConfigSchema.title is z.string(), and it refuses a tmpl value: defineFlow and the notify contract both answer "expected string, received object". The seam runs from the spec's template-dialect row to automation/io-node-config.zod.ts NotifyConfigSchema.title. cel.mdx follows the parse. The seat routes this to objectstack.
• Prose that still names things the spec lacks. reference/cel.mdx's variable table says input is available in "flow steps".
• Node floor. check-node-floor reads pnpm-lock.yaml only, so the spec's engines.node >=22.0.0 in the npm lockfile is outside it. That is below the repo floor (22.12.0), so nothing is missed today.
• AGENTS.md says the Chinese coverage is "62 of 79 pages". It is lower after A and B: number drift.

维护者速读（草稿）

• 改了什么： 剩余 14 个英文页面的代码示例现在都能被 @objectstack/spec 17.7.0 解析。按 [Decision] An English docs correction leaves its locale siblings asserting the corrected-away claim — #59 says delete them, the seat post says leave them, and #68 blocks the pass that would fix them #256 裁决 A，删除了 4 个页面的 18 个译文。新增 CI 门禁：每个 PR 都用锁定版本的 spec 解析全部英文示例。门禁内置 51 个自测用例。
• 为什么改： 读者照抄示例会直接报 schema 错误。spec 几乎每个版本都会收紧形状；没有门禁，这类问题会反复出现（Docs polish from the 2026-10-06 audit: muted-text contrast, the License table on phones, FAQ formatting, search ranking, glossary order, licence/license spelling #301、Docs code samples the current @objectstack/spec refuses: the remaining view fragments in build/interface/views.mdx and the send_email flow action in build/automation/flows.mdx #307、Docs code samples, family close-out: workflows, approvals, actions and cel pages show flow and view samples that @objectstack/spec 17.7.0 refuses; add a docs-sample parse gate so the family stays closed #316）。
• 风险与代价（含回滚）： CI 多两步：一次 npm 安装（3 个包），门禁约 2 秒。spec 刻意装在 pnpm workspace 之外，否则文档站会出现两份 zod。Dependabot 升级 spec 时，若新版本拒收某个示例，那个升级 PR 会变红，需要顺手修示例。被删译文由下一轮翻译重新生成，期间显示英文。回滚：revert a45e682 可去掉门禁，revert 9144f75 可撤回页面修复。
• 席位意见：
• 你要做的： 在 PR A 之后合并。确认接受门禁及其 Dependabot 条目。

Pushed head

a8ce2ea on claude/pm-dispatch-objectos-ju9td1, a fast-forward with no force. It starts at the remote branch head c57caa2 (PR #320), merges origin/main @ 5483c4a (#320's squash; after the merge the diff against main is empty), and cherry-picks 9144f75 and a45e682. git diff origin/main a8ce2ea is byte-identical to git diff e585f02 a45e682. Size: 38 files, +1100/−3180 = 4280 changed lines, under the 5000-line human-merge line.

---

Generated by Claude Code