feat(spec): declare rows (multiline editors) and options[].description as authorable field-metadata keys (objectui#6140 / objectui#6153, spec half)

[os-warren]

Part of objectstack-ai/objectui#6140
Part of objectstack-ai/objectui#6153

The SPEC HALF of the ruled two-card family. Maintainer ruling 2026-08-25 on objectui#6140 (verbatim: 「就全部接受，然后继续下一批」) = Option A: declare rows so validation and the running widget finally agree, aligning the TextareaFieldMetadata precedent. objectui#6153 inherited the frame per key: options[].description is genuinely consumed and gets declared; dependsOn is NOT declared (resolved objectui-side against the canonical depends_on). The objectui half (types/widget/docs) dispatches after this lands. Clause-② is ruled yes on both cards, so this PR parks as DRAFT + needs:contract-review — it is not awaiting more code, it is awaiting contract review.

What lands

• rows (positive integer) on FieldSchema — packages/spec/src/data/field.zod.ts. Both keys were consumed-but-undeclared: objectui's RichTextField (the one widget behind the markdown/html/richtext registry keys, objectui#5498) reads richField?.rows || 8 through an as any, TextAreaField reads textareaField?.rows || 4 — while the strict publish door refused the key on every type. Declared with the spec: maxLength is authorable on every field type and validated as no more than a number — maxLength: 0 and maxLength: 12.5 parse cleanly #11566 template: a module-local MULTILINE_EDITOR_FIELD_TYPES set plus a superRefine that refuses the key outside it, message enumerating the set itself.
• description (string) on SelectOptionSchema — same file. objectui's LookupField searches it on authored static options (opt.description && opt.description.toLowerCase().includes(q), LookupField.tsx:526) and recordToOption emits the same key for fetched options. The object.form options repeater has offered a description input all along; the declaration makes that offer honest. It flows into FormSelectOptionSchema mechanically via the Narrow the per-option default key OUT of the form-view options vocabulary — the object-field face keeps it (enforced, #7246), the form-view face parses-and-ignores it (ruled on objectui#6263) #12868 Omit-by-reference construction (pinned there).
• Both authoring forms show rows for exactly the accepted set (field.form.ts, object.form.ts), the spec: maxLength is authorable on every field type and validated as no more than a number — maxLength: 0 and maxLength: 12.5 parse cleanly #11566/spec: minLength still has the pre-#11566 defect pair — validated as no more than a number, authorable on every field type #11949 forms-convergence discipline.
• Gate-prescribed regenerations, nothing hand-edited: docs references (gen:docs), authorable-surface shards (data/Field:rows, data/SelectOption:description, ui/FormSelectOption:description), i18n bundles (merge mode, check-i18n-bundles.mjs --write — translated locales received source text and still need translating), liveness state-counts (gen:liveness-counts), plus a census --fix re-anchor of system-context.mdx (pure line rot from the field.zod.ts insertion) and a liveness ledger entry classifying field/rows live with cross-repo evidence (the placeholder precedent shape).
• Changeset: .changeset/field-rows-and-option-description-declared.md, @objectstack/spec minor — additive accepted-set expansion, following the declare-the-consumed-members precedent of the recent spec expansion changesets (spec-save-meta-item-request-members is the shape template; the in-tree ruling precedents are spec: maxLength is authorable on every field type and validated as no more than a number — maxLength: 0 and maxLength: 12.5 parse cleanly #11566/spec: minLength still has the pre-#11566 defect pair — validated as no more than a number, authorable on every field type #11949/signature / qrcode have no maxLength enforcement anywhere, so they cannot join the TEXT family — a data-URI signature is refused at 255 chars and the declared bound binds nothing #11875). Non-breaking, so no ADR-0087 marker is owed (gate green).
• Pins: packages/spec/src/data/field-rows-option-description.test.ts — 28 pins: accept pins preserving values through parse on all four types and through the real select-field and lookup-field doors; shape refusals (0 / -5 / 2.5); wrong-type refusals with the custom issue at path rows; publish-door controls proving the refusal is GONE for exactly the ruled keys and STILL PRESENT for undeclared neighbours — the four inert editor keys (toolbar/preview/minHeight/maxHeight) on a markdown field, and icon / dependsOn on the option shape.

The derived judgments contract review should look at

1. rows applicability set = textarea, markdown, html, richtext. The RULED pair is markdown/html. textarea and richtext are derived members, from the measured consumption set: the same two widget reads serve all four types, the spec refuses the key on EVERY type today, and declaring the ruled pair while still refusing the precedent type's own declared key would manufacture a fresh declared-vs-enforced split on exactly the type the ruling aligns to. Trimming to the literal pair is a two-line change if review prefers it.
2. rows value shape int().min(1). objectui's TextareaFieldMetadata spells rows?: number only because a TS interface cannot say more; the house count discipline (spec: Field.scale accepts meaningless declarations (2.5, -1) — now that scale is enforced, malformed declarations should be refused at authoring time #8321/spec: maxLength is authorable on every field type and validated as no more than a number — maxLength: 0 and maxLength: 12.5 parse cleanly #11566: a count of 0, -5 or 2.5 has no defined meaning) is applied, matching maxLength/minLength one key above. No upper bound invented.
3. description reaches the form-view option face by the Narrow the per-option default key OUT of the form-view options vocabulary — the object-field face keeps it (enforced, #7246), the form-view face parses-and-ignores it (ruled on objectui#6263) #12868 Omit construction — one vocabulary by design; splitting the faces for this key would need its own ruling.

Explicitly NOT here

• dependsOn — the inherited ruling resolves it objectui-side (widget reads the canonical declared depends_on); a camelCase twin is not licensed. Pinned refused.
• The four inert rich-text editor keys — the capability expansion stops at rows; none of them was found declared anywhere in spec (fence check clean). Pinned refused.
• Anything objectui-side (no @object-ui/types edits, no widget edits, no rich-text.mdx).

Evidence (local, at 83eeba1b)

• Full spec suite via the verify lock: 445 files / 11888 tests passed; artifact gates: "All 14 generated artifacts are up to date."
• New pin file: 28/28 green. Reverse verification from the committed state: field.zod.ts reverted to base 7483afdd (mutation proved on disk: 0 grep hits for the set and the key), pin file went 22 failed / 6 passed — exactly the six control pins staying green — then restore via checkout of HEAD, proved by empty git diff HEAD and matching git hash-object vs the HEAD blob, back to 28/28.
• Spec typecheck (tsc + scripts + test layers): green — "check:test-typecheck: OK — @objectstack/spec's test layer compiles under packages/spec/tsconfig.test.json". platform-objects typecheck green after bundle regen.
• Repo-wide pnpm lint (eslint, no inline config): exit 0, full run, no narrowing — at e665729f; the one later commit touches only liveness/field.json + state-counts.md.
• check:i18n OK (9 packages in sync), check:i18n-coverage OK (602 baselined, none new), check:liveness green ("every governed-type property … is classified"), census OK (145 anchors resolve), plus the dispatch-gates derived families (doc gates, changeset gates, published-files, dual-build-cjs, type-check ratchets, nul-bytes…) all exit 0 — verdict lines archived in the run log.
• check:test-completeness locally NOT MEASURED by design (it parses a CI test log; its own output says to record exactly that).

Landing

DRAFT + needs:contract-review by ruling (Clause-②). The cards close on the objectui half — the Part of lines above are deliberate, and objectui#6153 remains open here as well.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/driver-sql, @objectstack/platform-objects, @objectstack/spec, touching 12 documentable anchor(s). ⚠️ 4 changed file(s) yielded no anchor (packages/spec/authorable-surface/data.json, packages/spec/authorable-surface/ui.json, packages/spec/liveness/field.json, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/concepts/metadata-driven.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/data-modeling/external-datasources.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/data-modeling/field-types.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/data-modeling/validation-rules.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/deployment/troubleshooting.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/deployment/validating-metadata.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/getting-started/quick-reference.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/kernel/contracts/data-engine.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/protocol/backward-compatibility.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/protocol/objectql/types.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/protocol/objectui/concept.mdx (via FieldSchema (symbol, a top-level const))

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

• content/docs/releases/v17.mdx (via FieldSchema (symbol, a top-level const))

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

• 4 changed file(s) yielded no anchor (packages/spec/authorable-surface/data.json, packages/spec/authorable-surface/ui.json, packages/spec/liveness/field.json, …) — pages documenting those are invisible to this run
• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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 — 129 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 6b285eca42a780636ea416a916e0de228f797fc1 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 6b285eca42a780636ea416a916e0de228f797fc1

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

[os-warren]

@评审链(接手本 PR 落地的席位)——派发席状态探询,单次不刷屏:

本 PR 自 07:52Z 你方 main-sync + 清标后已 33/33 check 全绿(08:15Z 起),但至今仍停在 draft,>1 小时无动作。它是三张卡的关键路径:objectui 半边(#6140/#6153 收口)与 #13632 / #13671(同热文件 field.zod.ts / form offers,都压在本 PR 落地后)。

两个走法任选,请回一个:

1. 你方继续持有落地权:ready + 入队即可(base 已前移,mergeable 显示 unknown,可能需要再一次 main-sync——你方分支,你方操作);
2. 若你方巡检已收班:在此明示把落地权交还派发席,本席按维护者「绿了即合」的在案先例接手 ready + auto-merge(条款② 复核你方已 PASS、标签已清,审计链完整)。

无回应下本席不碰分支;下一探针(~09:50Z)若仍无动静,将升级到维护者决策箱。

---

Generated by Claude Code

[os-warren]

os-dev-report

{
  "issue": "PR#13669-sync",
  "status": "done",
  "branch": "claude/issue-6140-field-metadata-declared-keys-spec",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/13669",
  "premise_still_valid": true,
  "summary": "Main-sync conflict resolution round, no behavior changes. Exactly ONE conflicted file: content/docs/permissions/system-context.mdx (generated census anchor table -> generated-artifact class). Why it text-conflicted despite its merge=os-regen routing: the routing line was added on main by 13646 AFTER this branch forked, and the merge reads gitattributes from the branch-side worktree, which lacked it -- expected git behavior, not a bug. Resolution followed the os-regen-merge.sh sequence by hand (the script cannot resume an in-progress merge; merge-base b8fc7280 was captured pre-merge): took origin/main's side as placeholder, committed the merge FIRST (865d63b4), then regenerated on the merged tree -- gen:schema, gen:docs, gen:liveness-counts came back byte-identical (nothing silently dropped; the only both-sides-moved regen path was the census page), census --fix re-anchored exactly 1 line (field.zod.ts:1451 -> 1514, the branch's own insertion shift) committed as 5a4b5e4b, i18n bundles verified already in sync (no --write needed). All ruled shapes preserved and pinned: rows four-type applicability set, dependsOn refused, four inert editor keys refused; shard entries data/Field:rows, data/SelectOption:description, ui/FormSelectOption:description and the liveness live entry for rows all present post-regen. No source-file conflicts, no takes-one-side judgment calls arose. Main moved again mid-run (eb717a12 -> 936aa2d3, 9 commits, none touching packages/spec): verified the pushed branch merges cleanly with the new tip (git merge-tree --write-tree exit 0) AND that the census page 3-way TEXT-merges clean (git merge-file exit 0, zero markers) since GitHub merges without the custom driver -- mergeable_state should flip clean without another sync round. Pushed 9c2f8667..5a4b5e4b. Did not touch ready/draft state or labels per dispatch.",
  "tests": "All at final head 5a4b5e4b, union run AFTER the final commit. 28-pin file via verify-lock: 'Test Files 1 passed (1)', 'Tests 28 passed (28)'. Full spec suite via verify-lock: 'Test Files 445 passed (445)', 'Tests 11912 passed (11912)'. Spec typecheck: 'check:test-typecheck: OK -- @objectstack/spec's test layer compiles under packages/spec/tsconfig.test.json'. check:generated: 'All 14 generated artifacts are up to date.' Census gate: 'check-system-context-census: OK -- 109 elevation read sites in 20 packages across 45 files, all anchored; 145 anchors resolve, 27 declared non-read.' i18n: 'check-i18n-bundles: OK (9 package(s) -- all bundles in sync, no undeclared authoring keys).' dispatch-gates.mjs (no paths, derived at 5a4b5e4b, 23-path change set vs merge base eb717a12): 60 derived commands run, 58 exit 0, 2 exit 3 = self-declared NOT MEASURED refusals, not reds (check-test-completeness parses a CI test log; scripts/pm/check-half-states.mjs needs a GitHub route this container lacks -- its pnpm check:pm-half-states self-test half exits 0). check:nul-bytes OK (7588 files). dispatch-gates flagged 3 stale gate scripts vs the then-newer main tip; none of the three matched this card's paths (verified by grep over the derivation output). check-dev-prereqs initially refused PREREQUISITE NOT MET (workspace not built), satisfied by a full turbo build under the lock, then exit 0. All exits captured before any pipe.",
  "mcp_calls": "3 -- 1 comment write, 1 planned comment read-back, 1 planned PR mergeable-state read (PR body itself read via the zero-quota page-payload channel)",
  "open_questions": [],
  "out_of_scope_findings": []
}

Generated by Claude Code

---

Generated by Claude Code