feat(spec): the object-form runtime form field declares the grid widget's eight camelCase keys (#21768)

[objectstack-fleet]

Fixes #21768
Clause-②: yes (widening)

What this does

The spec half of objectstack-ai/objectui#11610, which renamed the grid widget's eight field-level keys to camelCase (merge 2abec3a96c). The .objectui-sha pin on main is 9dfaca654311, and it carries that merge: merge-base --is-ancestor 2abec3a96c 9dfaca654311 exits 0, which proves ancestry on its own.

This executes ruling B on #21704 fork 2 (record 5978663135). That ruling deferred the eight keys "until objectui camelCases them". This PR also answers objectui's two asks in 5981368783 and the at-tier review's ③ in 5986881331. It works under the claim 5987845581.

	before	after
runtime form field (buildObjectFormRuntimeField: object-form customFields[], and the inline arm of both forms' sections[].fields[])	minRows … sortField refused as unrecognized keys	declared with the widget's value types
the eight snake_case spellings	refused, with one shared prescription: "these come in once the widget reads a camelCase spelling"	still refused by name; each refusal names its own camelCase key
totalField	not declared	described as the grid's CHILD column summed into the footer, not the PARENT field a master-detail or record:line_items sum is saved to

Census at the pin (objectui 9dfaca654311, read with git show)

key	value type: GridFieldMetadata (types/src/field-types.ts:1031-1088) and the zod mirror (types/src/zod/form.zod.ts:1102-1117)	grid read (fields/src/widgets/GridField.tsx, cfg = field at :669)	snake_case spelling
minRows	number / z.number()	:762; Remove stops at it (:882, :1447)	min_rows: refused
maxRows	number / z.number()	:763; Add, Duplicate and the blank row stop at it (:808, :850, :892, :1077, :1487)	max_rows: refused
allowAdd	boolean / z.boolean()	:749, !== false; off when read-only or disabled	allow_add: refused
allowDelete	boolean / z.boolean()	:750, the same	allow_delete: refused
allowReorder	boolean / z.boolean()	:783, the same	allow_reorder: refused
totalField	string / z.string()	:771; summed into the footer at :919-923	total_field: refused
addLabel	string / z.string()	:1322 (empty state) and :1491 (Add button)	add_label: refused
sortField	string / z.string()	:778; stamped on every row by emit (:785-790)	sort_field: refused

• No snake_case read remains. git grep of the eight snake_case spellings over objectui's packages/*/src (tests and stories excluded) returns only its refusal faces:

  • the TS tombstones (field-types.ts:1106-1141, form.ts:2108-2143);
  • GRID_FIELD_RETIRED_KEYS (field-types.ts:1159);
  • the zod alias refusals (zod/form.zod.ts:1122-1129);
  • one comment in GridField.tsx:617.

  The widget refuses a field that carries any of them, and draws a refusal instead of the grid (GridField.tsx:643-650). The control grep for the camelCase spellings over the same scope has 38 hits in GridField.tsx alone.

• FormField takes each key by reference to GridFieldMetadata (types/src/form.ts:2079-2094).

• totalField is a homonym. The line-items panel and the master-detail form both hand the grid their amountField as its totalField (plugin-form/src/LineItemsPanel.tsx:710, MasterDetailForm.tsx:876).

Writers of either spelling in this repo (base 75ddcd1b41)

• snake_case: none authored.
  • The only authored value is the spec pin's own refusal probe (component-form-custom-fields-sections-typed.pin.test.ts, min_rows).
  • Prose mentions: the S-forms changeset's FROM → TO row, the console pin changeset's interim note, and dated comments in conversions/registry.ts, migrations/registry.ts and two migration entries.
• camelCase on an inline form field: none in examples/, skills/, content/docs/ or apps/.
  • The addLabel hits there (examples/app-showcase/.../project-workspace.page.ts:59, skills/objectstack-ui/SKILL.md:83) are master-detail detail entries, a different surface that is unchanged.
  • The objectui writer this PR pins is the schema catalog's fields-grid/line-items-grid field, which carries all eight keys.

Changes, packages/spec/src/ui/component.zod.ts

• The eight members. A new builder, objectFormRuntimeFieldGridMembers(), declares them, and the runtime field spreads it into its shape. The builder's docblock carries the read points above.
• The refusal map. OBJECT_FORM_GRID_WIDGET_SNAKE_KEYS is now a map from each snake_case key to its camelCase key (satisfies the declared key union, so a value naming an undeclared key fails tsc).
• One guidance set per entry, under the map's name. A set answers once per message, so this way each written spelling gets its own bullet naming its own replacement. The total_field bullet also restates the CHILD-column meaning.
• The three comments moved:
  • the line-items guidance block, re-measured at 9dfaca654311: LineItemsPanel.tsx:696-720, :816-827, spelled addLabel / sortField;
  • the customFields fork note, which now records the rename;
  • the master-detail sortField retirement note, which keeps its dated read and adds a hop sentence: the derived field is handed to the grid as sortField at MasterDetailForm.tsx:877, and the entry key is still a tombstone.
• One runtime string had to change, because this PR makes it false. record:line_items' sortField refusal said "No block takes an authored sortField". An inline grid field now takes one, for the rows of its own value, so the sentence now reads "No block takes an authored sortField for child records". The accept set is unchanged.

content/docs/references/ui/component.mdx was regenerated by check:generated --fix, which named only gen:docs as stale. The changeset is .changeset/21768-object-form-runtime-field-grid-camelcase-keys.md: @objectstack/spec minor, with Clause-②: yes (widening) at line start.

D3 reading

No accept set narrows. Every value that parsed at the base still parses, so no ADR-0087 D3 entry and no conversion is owed. Before this PR, the eight camelCase keys were refused (unrecognized_keys) and the eight snake_case keys were refused. After it, the camelCase keys parse and the snake_case keys are still refused. A camelCase key with the wrong value type is still refused, now as invalid_type. No step-18 file is touched.

Tests, at head bb32836dc9

component-form-custom-fields-sections-typed.pin.test.ts

• §1: the catalog writer parses byte-identical as a customFields member. Lit controls: the keys on an object-form section's inline entry, with the three switches false, and on an object-master-detail-form section's inline entry.
• §2: the existing min_rows row keeps its code and path. Its prescription check now asserts that the bullet names min_rows and minRows.
• §3: the key-set pin gains the eight keys.
• §5 (new):
  • each snake_case key gives unrecognized_keys at customFields.0, and exactly one bullet names that key and its camelCase key. The camelCase key then parses with the same value.
  • two retired keys on one field give two bullets, one each.
  • a section's inline entry refuses total_field the same way.
  • each camelCase key refuses a wrong value type as invalid_type at its own path.
  • each describe names its one reader.
  • the totalField homonym: the inline grid field's describe starts with the CHILD column and the footer, and names amountField. The record:line_items and master-detail detail-entry describes start with "Parent field to receive the rolled-up sum" and never say CHILD or footer.

The assertions check named subjects, not copy.

master-detail-detail-sort-field-retirement.test.ts

• Its tree-scoped absence walk flagged the new pin's sortField: 'position'. The walk's own header covers this case: "A future schema that declares a sortField of its own would trip this walk: narrow the matcher to detail entries then, never exclude the new file."
• So the matcher is narrowed, and no file is excluded. A match is skipped only when the object literal around it names type or widget grid / field:grid at its own level, which marks the inline grid field.
• Three anti-vacuity probes stay offenders: a nested column's grid type, an inline grid field placed earlier than a detail entry in the same text, and type: 'grids'.
• The six pre-existing probes are unchanged.

Ablation

• Prediction, written before the run: dropping sortField from the builder turns six tests red. They are §3's key set, §1's two grid writer rows, §5's sort_field refusal row, §5's sortField value-type row, and §5's describes test. The retirement pin stays green.
• Method: node scripts/ablation-replace.mjs --delete. The anchor hit once and went 1 → 0, and the blob went 298601db7467 → 48deefce4054.
• Result: exactly those six went red, Tests 6 failed | 108 passed (114).
• Restore: the blob matches HEAD 298601db7467, git diff HEAD is empty, and git status --porcelain is empty.
• Two runs: at edbdef7bf8, and again at bb32836dc9. The subject is imported from ./component.zod (source, not dist), so no rebuild is involved.

Suites

• pnpm --filter @objectstack/spec build && pnpm --filter @objectstack/spec typecheck at bb32836dc9: exit 0.
  • check:test-typecheck says OK, and the debt ledger is unchanged.
  • tsc -p tsconfig.test.json --listFilesOnly lists both edited test files, and neither has a ledger entry.
• The full spec suite (vitest run --project local): Test Files 615 passed (615), Tests 18383 passed | 1 todo. It ran at edbdef7bf8. The only later change is the pin file's assertion wording, re-run at bb32836dc9 with alias-integrity.test.ts and strict-object.test.ts: Tests 166 passed (166).

Gates, at head bb32836dc9

• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derives 110 commands for this change set, and every one exits 0.
  • --ran reconciliation: 110 derived, 110 run, 0 NOT-MEASURED, 0 UNRUN.
  • Exit codes were captured before any pipe.
  • check:type-check-debt ran under the verify lock, because its first unlocked run hit the 280s per-command cap.
• At the first head (edbdef7bf8), six gates (check:doc-formula-expressions, check:doc-security-posture, check:skill-examples, check:docs-transcript-drift, check:lean-entry-closure and check:dual-build-cjs-loads) first answered exit 3, PREREQUISITE NOT MET, because their packages had no dist. After a turbo build of lint, formula, client-react and objectql (all cache hits), each answered 0. All six also answered 0 at bb32836dc9.
• Lint, a measured narrowing. Repo-wide pnpm lint is CI's. Locally, ESLint ran over the three edited TS files at bb32836dc9, with three pieces of evidence:
  • Population: each file resolves a config through --print-config (packages/**/*.{ts,tsx,mts,cts}), so none is ignored.
  • Count: --format json reports 3 files, 0 errors and 0 warnings.
  • Invariance: the resolved parserOptions holds only ecmaVersion and sourceType, with no project, and no typed rule is on. Linting is not type-aware, so this diff cannot change the verdict on any file it did not touch.
• Not measured locally: the path-scheduled CI jobs and type-check lanes that dispatch-gates lists outside its derived set (Test Core shards, Dogfood, Build Core, Build Docs, Temporal Conformance, and the workspace and consumer type checks). CI runs them.

Declared beyond the claim's listed surface

• master-detail-detail-sort-field-retirement.test.ts: the claim lists no file for this edit. The new sortField member is what tripped the walk, and the walk's header says what to do, so it was narrowed, not excluded (see Tests).
• The record:line_items sortField refusal sentence: the sentence became false with this PR, so it was corrected in the same file (see Changes).

Acceptance notes

• main is 2 commits past this branch's base (ba57588665). They touch service-settings, the QA checklist JSON and a comment-only hunk in spec/src/contracts/crypto-provider.ts. None of that overlaps this diff, so main was not merged in. CI's merge ref covers the combination.
• Three dated prose records still describe the pre-rename spelling or the old reach. All are accurate as dated reads, and nothing parses them. Carrier: none.
  • The replacement text of the D3 entry ui-record-line-items-props-closed says "sortField, which no block takes".
  • conversions/registry.ts (about :12488) and the retired-key entry 18.ui__ObjectMasterDetailFormProps__details.sortField say the derived field is "handed to the grid as sort_field (:874)", read at pin 89cad75d5570.
  • The S-forms D3 reason says the snake_case keys stay out "until the widget reads a camelCase" spelling.
• The pending S-forms changeset (.changeset/21464-component-props-form-custom-fields-sections-typed.md) still says the eight keys "come in once the widget reads a camelCase spelling". If it ships in the same release as this changeset, the CHANGELOG reads as a sequence: that entry, then this one stating that they came in. It is not edited here, because it is outside this PR's surface. Carrier: none.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/concepts/architecture.mdx (via allowDelete (literal, a string literal in allow_delete))
• content/docs/getting-started/common-patterns.mdx (via allowDelete (literal, a string literal in allow_delete))
• content/docs/permissions/delegated-administration.mdx (via allowDelete (literal, a string literal in allow_delete))
• content/docs/permissions/index.mdx (via allowDelete (literal, a string literal in allow_delete))
• content/docs/permissions/permission-metadata.mdx (via allowDelete (literal, a string literal in allow_delete))
• content/docs/permissions/permission-sets.mdx (via allowDelete (literal, a string literal in allow_delete))
• content/docs/permissions/permissions-matrix.mdx (via allowDelete (literal, a string literal in allow_delete))
• content/docs/protocol/objectql/security.mdx (via allowDelete (literal, a string literal in allow_delete))

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

• content/docs/releases/v14.mdx (via allowDelete (literal, a string literal in allow_delete))

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 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 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; 97 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 — 138 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 a3ffc4512df5d9ebc1c9e5dee70813d89bf549db → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json a3ffc4512df5d9ebc1c9e5dee70813d89bf549db

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