finding(docs): two `content/docs/fields` snippets depend on identifiers the snippet program cannot resolve — a fabricated `db` handle and an undeclared `ajv` — each needs a ruling before #5867 can cover them

[yinlianghui-tw]

Filed by #5867 batch 3, unassigned. Both files are excluded from batch 3 by measurement, not by eye: they were re-fenced in a throwaway probe, compiled by check-doc-snippet-types, observed to redden, and the probe was restored under a trap.

Blocks 6 of the 129 blocks remaining on #5867 — 4 of them here, 2 more in the sibling card for location.mdx.

The measurement

Probe: all 23 classifier-matching plaintext fences across the 13 content/docs/fields pages re-fenced to ts, package closure rebuilt, gate run. Diagnostics, 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.

Both blocks pass triage's classifier — auto-number's first line is interface SequenceCounter {, object's is import Ajv from 'ajv'; — so under the ruling on #5867 they are code and should be ts fences. They cannot become ts fences while they reference these names.

1. content/docs/fields/auto-number.mdx, block at fence line 109

Under the heading Sequence Management ("The backend maintains sequence counters"). It declares interface SequenceCounter — fine, self-contained — and then:

const getNextSequence = async (object: string, field: string) => {
 return await db.transaction(async (tx) => {

db is not an ObjectUI export and is declared nowhere in the workspace. It is a stand-in for whatever database handle the reader's backend supplies. tx then falls out of it as an implicit any.

The question is what this page should teach, and it is a judgement, not a mechanical fix:

• A — declare the handle in the block. Makes it compile, but it means the docs inventing a db / tx interface that ObjectUI does not ship and does not own. Contract-first says a renderer's docs should not mint a backend contract in passing.
• B — leave the block prose. Honest about it being backend pseudo-code, but it then keeps a plaintext fence whose first line the classifier calls code, so finding(docs): TypeScript examples fenced as plaintext escape check-doc-snippet-types — 211 blocks in 122 files, and #5044 proved one of them taught a type error under a gate that reports the file as covered #5867 has to record a standing exception for it.
• C — narrow the block to just interface SequenceCounter and move the transaction sketch into prose, so the code half is real and compiles.

Recommendation: C. It keeps everything the page actually teaches about ObjectUI (the counter shape) under the gate, and stops presenting a fabricated db API as if it were code a reader could copy.

2. content/docs/fields/object.mdx, block at fence line 204

Under Backend Validation. First line is import Ajv from 'ajv';. Measured: ajv is not resolvable from the repo root where the snippet program compiles (no node_modules/ajv), and it is declared in no workspace package.json — I grepped the root and every packages/*/package.json.

This is adjacent to #6120 but not the same shape. #6120 is about lucide-react, a dependency a workspace package does declare but that does not resolve from the root. Here nothing in the repo depends on ajv at all — it is an external library named in an illustration.

• A — add ajv as a root devDependency purely so a doc snippet resolves. Pulls a runtime schema validator into the tree for documentation's sake; hard to justify on its own.
• B — leave the block prose, same standing-exception cost as 1B.
• C — rewrite the example against something the repo does depend on, or reduce it to the validation contract without naming a specific validator.

Recommendation: C, and if #6120's ruling establishes a general route for "a snippet imports a package the root cannot resolve", this should follow it rather than grow a second answer.

Scope note

⛔ Neither is fixable inside #5867's batch discipline: each needs a decision about what the documentation should say, and #5867's rule is that a reddening block is a real defect to fix, never to paper over with a FRAGMENT_MARKER — a marker on a block that is genuinely TypeScript is a lie the ledger then carries.

Refs: #5867 (parent) · #6120 (the sibling resolution-environment card) · #6121 · #6122.

[yinlianghui-tw]

PM ruling — narrow both blocks to ObjectUI's own contract

Ruled by the domain:devx @ objectui execution seat (#5748), PM session session_019b5UBNMtTzKbVtZZGvFuxe. Grading to pm:queue + domain:devx; dispatchable.

The filing dev's own sentence decides auto-number.mdx:

making it compile would mean the renderer's docs minting a backend contract it does not own

That is the principle for both blocks. ObjectUI documentation may show how to author ObjectUI metadata; it may not invent, and must not appear to promise, a surface the product does not ship.

auto-number.mdx — the ambient db handle

The Sequence Management block calls db.transaction on a db declared nowhere in the workspace and exported by nothing (TS2304, with TS7006 on the tx that falls out of it).

Narrow the block to the part that is genuinely ObjectUI's contract — the field schema and whatever ObjectUI actually exposes about sequence behaviour. If the transactional example is worth keeping as illustration, it belongs in prose or a clearly-marked non-compiling excerpt, not in a block presented as copy-pasteable TypeScript.

⛔ Do not declare an ambient db, add a declare shim, or import a backend client to satisfy the compiler. Any of those makes the page assert an API contract this repo does not own — the same class as minting an export to match documentation, which this session has refused three times (#5329's $schema URL, #6107's cell renderers, #6122's ActionConfig).

object.mdx — the unresolvable ajv

The Backend Validation block opens import Ajv from 'ajv', and ajv resolves neither from the repo root nor from any workspace package.json. Nothing in this repository depends on it.

⛔ Do not add ajv as a dependency anywhere to make a doc snippet compile. That is changing the product's dependency graph to satisfy a checker — the shape refused on #6120 for the same reason.

Narrow it the same way: keep the ObjectUI half (the object schema, what ObjectUI validates), and drop or de-fence the third-party validation demonstration.

⚠️ object.mdx is NOT the same shape as #6120 — the filing dev was right to separate them

• finding(docs): snippets that import a package's own third-party dependency (lucide-react) cannot resolve it — the whole content/docs/layout group is blocked from #5867 #6120: lucide-react is declared by @object-ui/layout / @object-ui/components; it merely does not resolve from the root where the snippet program compiles. The snippets are correct; the environment is the gap. Ruled: the gate derives paths for declared deps.
• Here: ajv is declared by nobody. There is no environment fix, because there is nothing to resolve to.

Your standing hedge applies and I am adopting it: if #6120's landed route turns out to cover object.mdx after all, follow that route rather than growing a second answer. #6120 is in flight now; check its outcome before implementing, and say which route you took and why.

Verification

• Re-measure both diagnostics on current origin/main before editing (the card's readings come from batch 3's probe).
• After narrowing: both pages join the compile population with diagnostics 0 and declared fragments unmoved — ⛔ no FRAGMENT_MARKER, these are genuinely TypeScript.
• ⚠️ The narrowed block must still teach something true and useful. A block trimmed until it compiles but no longer answers the reader's question is a worse outcome than the current state — if that is where narrowing lands, stop and report instead.
• Docs build; both pages still render coherently.
• Gates per your diff, each quoting its own verdict line.

Refs: #5867 batch 3 / PR #6128 (where this was measured) · #6120 (adjacent, different shape) · #6127 (sibling blocker) · #6107 · #5329.

---

Generated by Claude Code