docs: make the data, actions, workflows and approvals code samples parse with @objectstack/spec 17.7.0 (part 1 of #316)

[objectstack-fleet]

Part of #316

This is the first of two stacked PRs that close the docs code-sample family (#301, #307, #316). Here, the samples on eight English pages parse with the latest published @objectstack/spec, 17.7.0 (npm latest, published 2026-10-06T12:22Z; versioned in objectstack 4e4e8814, "chore: version packages (#21352)"). The pages are the data model and its three subpages, actions, and the three automation pages. The locale siblings that ruling A requires go with them. PR B, stacked on this one, fixes the other 14 pages and adds the CI gate. It closes the card; #316 stays open until then.

Why two PRs: together the change is 8334 changed lines (+1354/−6980). Most of that is deleted translations, and it is over the 5000-line human-merge threshold. This PR is 4054 (+254/−3800). check-governed-merges --test on this PR's 26 paths, with that size, answers "NOT governed … 4054 changed line(s) ≤ 5000". Each English correction ships here with its own sibling deletions, as ruling A requires.

One commit: e585f02, on main @ dc8213d.

What changed, per page

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

• build/automation/workflows.mdx: rewritten around the state_machine validation rule.
  • The XState-style StateMachineConfig is not in 17.7.0: there is no such type and no schema. "The XState StateMachineSchema … left the package in #21320" (api/protocol.zod.ts:2621).
  • A workflow is now one of the object's validations, the state_machine rule: field, transitions, initialStates (data/validation.zod.ts:187). The pattern is ObjectStack's content/docs/automation/workflows.mdx and protocol/objectql/state-machine.mdx.
  • The has_resolution guard becomes requiredWhen on resolution, which is a transition gate (data/field.zod.ts:1817). The state-machine page says "A state_machine rule has no per-transition guard".
  • Removed or reversed: events, cond guards, type: 'final' (now an explicit []), and "Events, not field writes", which becomes "Writes, not events".
  • The side-effect flow gets labels, status, and real update_record / notify configs. {TODAY()} is the documented value interpolation (ObjectStack automation/flows.mdx:1895).
• build/automation/index.mdx: the chooser said "by these events" and "states, transitions, and guards". It now says what the workflows page says.
• build/automation/approvals.mdx:
  • The start and end nodes get labels, and the update_record nodes get real configs.
  • resolveAs moves onto the expression approver, the key the approval contract reads (automation/approval.zod.ts:505). As a node-config key it is refused.
  • The legal_review node gets a label.
  • The approve / reject edge labels stay; they are documented at :382.
• build/interface/actions.mdx:
  • Action is imported from @objectstack/spec/ui: the root entry point exports no Action.
  • confirmText beside params is refused ("TWO dialogs for one decision"), so the question moves to description, as the refusal prescribes (ui/action.zod.ts:2087).
  • There is no flow node that calls an action. The "flow step (type: 'action')" surface and the "From a flow" sample are removed. The section now shows the other direction, an action with type: 'flow' (ObjectStack protocol/objectui/actions.mdx).
  • There is no view-container actions key. Placement is the action's locations, and a list view names rowActions / bulkActions (ui/view.zod.ts:2826).
• build/data/index.mdx:
  • The stack's namespace is todo: defineStack refuses todo_task under myapp.
  • helpText becomes inlineHelpText.
  • Field pattern does not exist. The regex moves to a format rule.
  • Validation rules get their type, and condition is the invalid case.
  • ownership takes 'user' | 'business_unit' | 'org' | 'none'.
  • lifecycle uses retention: { maxAge } and storage: { strategy: 'rotation', shards, unit } (data/object.zod.ts:904).
  • The types table drops decimal, which does not exist, and fixes the Field.lookup / Field.masterDetail signatures: (reference, config).
• build/data/relationships.mdx: Field.masterDetail('order', …); real options on the grade select; the summary fragment says it is a field of the Order object.
• build/data/formulas.mdx: Field.decimal does not exist; it becomes Field.currency / Field.number({ scale }). The rating select gets real options.
• build/data/validation-rules.mdx: fragments say what they are, the status select gets real options, and the mixed email / indexes fragment becomes the object keys it is.

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

Page	Call	Siblings
build/automation/workflows	delete: XState state machine, guards and events are removed or reversed	zh-Hans, zh-Hant
build/automation/index	delete: "by these events" and "guards" are reversed (the zh-Hans text carried 按这些事件 and 守卫条件)	zh-Hans, zh-Hant
build/interface/actions	delete: the flow-step surface and view-level placement are removed	de, es, fr, ja, ko, zh-Hans, zh-Hant
build/data/index	delete: the decimal type, field pattern and the ownership values are removed	de, es, fr, ja, ko, zh-Hans, zh-Hant
approvals, relationships, formulas, validation-rules	keep: code shape only (labels, configs, builder signatures, options, a key's location, comments)	stale, reported

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

Parse results: @objectstack/spec 17.7.0

The checker is PR B's check-doc-samples.mjs, run against this branch's tree. "Unchecked" means a fragment with no comment saying what it is. The middle column adds only those comments, to show what the fragments held.

Page	dc8213d as published	dc8213d, fragments classified	this PR
build/data/index.mdx	3 pass, 6 refused, 1 unchecked	4 pass, 6 refused	10 pass
build/interface/actions.mdx	1 pass, 2 refused, 1 unchecked	1 pass, 3 refused	4 pass
build/automation/workflows.mdx	0 pass, 2 refused	0 pass, 2 refused	2 pass
build/automation/approvals.mdx	0 pass, 1 refused, 5 unchecked	3 pass, 3 refused	6 pass
build/data/validation-rules.mdx	1 pass, 1 refused, 3 unchecked	3 pass, 2 refused	5 pass
build/data/relationships.mdx	3 pass, 2 refused, 1 unchecked	4 pass, 2 refused	6 pass
build/data/formulas.mdx	3 pass, 2 refused	3 pass, 2 refused	5 pass
These 7 pages	11 pass, 16 refused, 11 unchecked	18 pass, 20 refused	38 pass

build/automation/index.mdx has no code block.

Across the whole English corpus: dc8213d gives ✗ doc samples: 66 block(s) refused or unchecked on 21 page(s). This branch gives ✗ … 39 block(s) refused or unchecked on 14 page(s) · 62 pass. All 39 are on the 14 pages PR B fixes: agents 1, apps 3, dashboards 7, forms 3, pages 4, data-sources 4, field-level-security 1, permission-sets 1, record-access 1, quickstart 1, cel 7, field-types 4, objectql 1, rest-api 1. The gate is not in CI on this branch; PR B adds it.

Verification at e585f02

Gate	Verdict
pnpm install --frozen-lockfile	EXIT 0
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 · ✓ 10 self-test(s) passed
check-locale-surface.mjs	EXIT 0 · ✓ every advertised URL has a source file and every source file is advertised; …
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: 58 generated file(s) match the zh-Hans sources byte for byte.
Ownership, with the workflow argv (git diff --name-status --no-renames origin/main...HEAD), --actor hotlong, TRANSLATION_BOT_LOGIN set	EXIT 0 · ✓ 26 file(s) changed: 18 translation artifact(s) deleted, none added or modified. With the bot as actor (the control): EXIT 1
check-translations.mjs	EXIT 0 · ✓ translations gate passed. Reported, not blocking: zh-Hans 43 stale / 35 missing; the others 22 stale / 57 missing
check-translation-output.mjs --self-test / --files	EXIT 0 / EXIT 0 · ✓ translation output gate passed (235 pre-existing finding(s) reported)
check-node-floor.mjs, with --self-test; check-half-states.mjs --self-test	EXIT 0; EXIT 0 · 1551 cases pass

Browser. These pages are byte-identical to the reviewed staged/issue-316 work, so the earlier measurements still apply. next start served that build, and Chromium loaded each page at 1440 and 390: HTTP 200, the right h1, scrollWidth equal to the viewport, and every code box inside it (303–1137 px at 1440, 17–373 px at 390). /zh-Hans/docs/build/automation/workflows and /ja/docs/build/interface/actions answer 200 with the English body.

NOT MEASURED: behaviour on a running ObjectOS runtime.

Acceptance notes

• Prose that still names things the spec lacks. The build/data "Computed" table lists created, lastModified, createdBy and lastModifiedBy as field types, which are not in FieldType. It is a table, so no gate sees it.
• Stacking. PR B is cut from this branch's tip. Its own diff against this branch is 4280 lines. staged/issue-316-b's tree equals the reviewed 853ed96 merged onto dc8213d (tree 80a304d).

Pushed head

c57caa2 on claude/pm-dispatch-objectos-ju9td1, a fast-forward with no force. It starts at the remote branch head e463447, merges origin/main @ dc8213d (after the merge the diff against main is empty), and cherry-picks e585f02. git diff origin/main c57caa2 is byte-identical to git diff dc8213d e585f02. Size: 26 files, +254/−3800 = 4054 changed lines, under the 5000-line human-merge line. PR B (Fixes #316, the other 14 pages and the gate) follows on top of this one.

---

Generated by Claude Code