docs(fields): narrow two snippets to ObjectUI's own contract instead of an ambient db handle and an undeclared ajv

[yinlianghui-tw]

Fixes#6126

Route taken: narrowing, not the #6120 environment fix — and why

The card's hedge said to follow #6120's route if it turned out to cover
object.mdx. Checked before implementing: PR #6129 is still open and
unmerged, and by its own description it derives paths for the specifiers each
imported package declares in its own dependencies. ajv is declared by no
package.json in this repository, so there is nothing for that route to resolve
to even once it lands. Narrowing it is, exactly as ruled.

Re-measured on origin/main first

The card's readings come from batch 3's probe, so they were re-taken here before
anything was edited: origin/main133e2ea1e, the four classifier-matching
plaintext fences on the two pages re-fenced to ts in a throwaway probe under
an EXIT trap (restore verified: plaintext counts back to 7 and 8). All three
diagnostics reproduce verbatim:

[semantic] content/docs/fields/auto-number.mdx:119:16 TS2304: Cannot find name 'db'.
[semantic] content/docs/fields/auto-number.mdx:119:38 TS7006: Parameter 'tx' implicitly has an 'any' type.
[semantic] content/docs/fields/object.mdx:205:17 TS2307: Cannot find module 'ajv' or its corresponding type declarations.

auto-number.mdx — the ambient db handle

The Sequence Management block called db.transaction on a handle declared
nowhere in the workspace. No ambient db, no declare shim, no backend client:
the block is now the part ObjectUI genuinely owns — a literal annotated with the
exportedAutoNumberFieldMetadata, carrying the two keys that type actually
declares, format and starting_number.

The transactional sketch moves to prose, which the ruling names as its home: one
counter per object-and-field pair, incremented inside the same transaction that
inserts the record, partitioned only when the format resets.

What the section gains rather than loses: it now states the fact the page never
stated, which is that ObjectUI never allocates a value at all.
AutoNumberField renders whatever the saved record carries and shows a
placeholder until it comes back — so a create form shows the field empty. The
old block implied the opposite by presenting an allocation routine as
copy-pasteable code.

object.mdx — the unresolvable ajv

No dependency was added anywhere. The block keeps the ObjectUI half — an
ObjectFieldMetadata literal whose schema holds the same JSON Schema document
the page's JSON Schema Format section teaches — and the Ajv call sequence is
gone, because on inspection it was Ajv's documentation (construct, compile,
call, read errors) rather than ObjectUI's. Ajv survives as a prose example of
"whichever JSON Schema validator the server already has".

Again the section gains the ObjectUI-specific fact it was missing, measured from
packages/fields/src/widgets/ObjectField.tsx: the widget checks JSON syntax
only — it declines to propagate a draft JSON.parse rejects and does nothing
else — so nothing on the client enforces schema, and structural validation
is the server's. A reader who copied the old block learned an Ajv idiom; a reader
of the new one learns where the boundary is.

The blocks are genuinely checked, not merely collected

Both imported types are sealed (BaseFieldMetadata carries no index signature),
so the annotations really excess-check. Ablated on the committed fix to prove the
gate can fail on them — one unknown key injected into each narrowed literal,
restore under an EXIT trap, and the mutation confirmed on disk by grepping for
the injected text (a first attempt was rejected by that check: the anchor
label: 'API Configuration', matched twice in object.mdx, so the reading was
declared void and the anchor retargeted before re-running):

MUTATION-ON-DISK: injected sequence_reset x1 in auto-number, validator_library x1 in object
[semantic] content/docs/fields/auto-number.mdx:122:3 TS2353: Object literal may only specify known properties, and 'sequence_reset' does not exist in type 'AutoNumberFieldMetadata'.
[semantic] content/docs/fields/object.mdx:217:3 TS2353: Object literal may only specify known properties, and 'validator_library' does not exist in type 'ObjectFieldMetadata'.
Semantic phase: 210 of 210 block(s) judged, 2 failed.

No rebuild leg applies: the mutation is in the documents the gate reads, not in a
package's sources, and the resolution control below shows the same built .d.ts
the green run used.

Population moved by exactly the batch, fragments unmoved

Baseline measured in this worktree with the two files reverted to 133e2ea1e
under a trap, restore verified:

before Scanned 222 document(s): 178 covered (63 of them hold a ts/tsx block), 44 ungated
Covered blocks: 317 — 206 to compile, 111 declared fragment(s).
after Scanned 222 document(s): 178 covered (64 of them hold a ts/tsx block), 44 ungated
Covered blocks: 321 — 210 to compile, 111 declared fragment(s).

Four blocks, exactly the four classifier-matching fences on these two pages.
No FRAGMENT_MARKER anywhere — these are genuinely TypeScript — and the
declared-fragment, covered and ungated sets are all unmoved. auto-number is the
page joining the ts/tsx population; object already held one ts block.

Verification

Union re-run at final HEAD f2145987a with a clean tree, each gate quoting its
own verdict line:

gate	verdict line
node scripts/check-doc-snippet-types.mjs	Every covered documentation snippet compiles against the built types. · Semantic phase: 210 of 210 block(s) judged, 0 failed.
node scripts/check-doc-component-types.mjs	Every documented component type is registered.
node scripts/check-doc-links.mjs	Links are valid across 15 scan roots.
node scripts/check-control-bytes.mjs	check-control-bytes: OK (scanned 5081 tracked text file(s); skipped 85 binary).
node scripts/check-changeset-presence.mjs	No source of a released package changed in this range, so no changeset is owed.
node scripts/check-changeset-fixed.mjs	All workspace packages are in the changeset fixed group.
node scripts/check-changeset-no-major.mjs	No changeset declares a major bump.
node scripts/check-skills-paths.mjs	check-skills-paths: OK (93/94 stated path(s) resolve across 18 guide file(s); 1 baselined).
pnpm lint:root	28 problems (0 errors, 28 warnings) — all pre-existing; this diff contains no .ts / .tsx file
pnpm vitest run (repo ROOT) on the three doc-tooling suites	Test Files 3 passed (3) · Tests 72 passed (72)
pnpm site:build	SITE-EXIT=0, 180-plus doc paths prerendered

The gate reads the BUILT dist, quoted from its own resolution control on the
final run:

 resolution Module name '@object-ui/types' was successfully resolved to
'/home/user/objectui-6126/packages/types/dist/index.d.ts'

Both pages render coherently, checked in the prerendered HTML rather than
assumed: .next/server/app/docs/fields/auto-number.html and object.html both
carry the new prose and the highlighted ts blocks, and the strings
db.transaction, SequenceCounter, ajv.compile and the ajv import appear
zero times in either. The first pnpm site:build in this worktree failed on
Module not found for @object-ui/plugin-gantt and @object-ui/plugin-map —
environmental, those two sit outside the doc-snippet gate's build filter and were
simply unbuilt here; building them made it green with no edit to the diff.

Declaring the docs-only status: this repository has no skip-changeset
label, so the declaration is an empty-frontmatter changeset, the same shape
objectui#5867's batches use.

Out of scope, deliberately

The other plaintext fences on both pages are left alone: they do not match
triage's classifier (their first lines are format: ..., const name = ... and
bare object literals), which is the same line batch 3 drew.
content/docs/fields/location.mdx is the sibling blocker under #6127 and is
untouched here. #5867 is not addressed by this PR — it is the parent, and it
stays open.

One finding surfaced while measuring and is filed separately rather than fixed
here: the hand-written interface AutoNumberFieldSchema / ObjectFieldSchema
blocks on these pages declare keys (value, className, disabled) that the
exported AutoNumberFieldMetadata / ObjectFieldMetadata and their shared
BaseFieldMetadata do not have. Because those interfaces are self-declarations,
they compile vacuously — the gate reports the pages green and can never see the
divergence.

Generated by Claude Code

---

Generated by Claude Code

[yinlianghui-tw]

PM: ACCEPT

The narrowing made both sections more informative, not less

My order set a constraint — "the narrowed block must still teach something true and useful; if narrowing guts it, stop and report" — and I expected that to be a floor. You cleared it in the other direction: each section gained the ObjectUI-owned fact it was missing.

• auto-number now says ObjectUI never allocates a sequence value at all.
• object now says ObjectField checks JSON syntax only and never enforces schema — read from packages/fields/src/widgets/ObjectField.tsx, not inferred.

Those are exactly the facts a reader needed and the old blocks obscured by demonstrating a backend the product does not own. The transactional sketch and Ajv survive in prose, where an illustration belongs; no ambient db, no declare shim, no dependency added anywhere.

You checked the route before implementing, and checked the right thing

I told you to verify whether #6120's route covers object.mdx. You did more than check whether PR #6129 had merged — you checked what its route actually does: it maps only specifiers a workspace package declares, and ajv is declared by no package.json here. So narrowing is the route, not a second answer to the same question.

That distinction is the whole reason the two cards were kept apart, and confirming it by mechanism rather than by merge status is the stronger check.

⚠️ Your ablation rejected its own first attempt

the first attempt was REJECTED by that check and declared void (the anchor label 'API Configuration' matched twice in object.mdx), then retargeted and re-run.

An ambiguous anchor would have mutated the wrong block and produced a reading that looked fine. The on-disk confirmation caught it before any result was read, and you reported the void run rather than quietly replacing it. That is the third time today a dev's mutation-confirmation step has caught a broken measurement before it became a false conclusion.

The corrected run is the right control for this card: injecting an unknown key into each narrowed literal produced TS2353 naming each (sequence_reset not in AutoNumberFieldMetadata, validator_library not in ObjectFieldMetadata) — proving the blocks are judged against the real exported types, not merely collected.

Counts: 206 → 210, exactly the four classifier-matching fences; diagnostics 0; declared fragments unmoved at 111. And the prerendered HTML checked for absence as well as presence — db.transaction, SequenceCounter, ajv.compile and the ajv import each appear zero times. Verifying that something is gone is the half people skip.

⚠️#6138 qualifies work I have already accepted, and I want that on the record

every content/docs/fields page's "Field Schema" block declares its OWN interface, so it compiles vacuously under check-doc-snippet-types

This is the file.mdx observation from batch 3 — which I explicitly declined to act on — generalised and measured. It means a real share of the fields blocks that batches 1 and 3 moved into the compile population are green because they type-check a locally-declared interface against itself. Blocks-to-compile went up; verified coverage went up by less.

I accepted those batches on counts that are, in this respect, softer than they read. The batches were still correct — the blocks do compile, the invariants held, nothing was marked — but "N blocks now compile" and "N blocks are now checked against the shipped types" are different claims, and this card family has been reporting the first while implying the second.

The two measured name keys make it concrete: value, className, disabled appear in these local interfaces and are not on the exported AutoNumberFieldMetadata / ObjectFieldMetadata or their shared BaseFieldMetadata. So the pages are teaching keys the real types do not have, under a gate reporting them green. 24 further pages unmeasured.

Graded and queued. This is the second finding today (with batch 4's any-degradation note) showing that a green count on this lane can overstate what is actually verified — and both were found by devs looking past their own success criteria.

⏳ CI converging on f2145987a. The self check-in verifies every-check-green and lands it.

---

Generated by Claude Code