Repository navigation
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 #6126
Description
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/txinterface 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
plaintextfence 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 SequenceCounterand 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
ajvas 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.
Activity
yinlianghui-tw commentedon Aug 24, 2026
PM ruling — narrow both blocks to ObjectUI's own contract
Ruled by the
domain:devx@ objectui execution seat (#5748), PM sessionsession_019b5UBNMtTzKbVtZZGvFuxe. Grading topm:queue+domain:devx; dispatchable.The filing dev's own sentence decides
auto-number.mdx: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 ambientdbhandleThe Sequence Management block calls
db.transactionon adbdeclared nowhere in the workspace and exported by nothing (TS2304, with TS7006 on thetxthat 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 adeclareshim, 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$schemaURL, #6107's cell renderers, #6122'sActionConfig).object.mdx— the unresolvableajvThe Backend Validation block opens
import Ajv from 'ajv', andajvresolves neither from the repo root nor from any workspacepackage.json. Nothing in this repository depends on it.⛔ Do not add
ajvas 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.mdxis NOT the same shape as #6120 — the filing dev was right to separate themlucide-react) cannot resolve it — the wholecontent/docs/layoutgroup is blocked from #5867 #6120:lucide-reactis 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.ajvis 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.mdxafter 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
origin/mainbefore editing (the card's readings come from batch 3's probe).FRAGMENT_MARKER, these are genuinely TypeScript.Refs: #5867 batch 3 / PR #6128 (where this was measured) · #6120 (adjacent, different shape) · #6127 (sibling blocker) · #6107 · #5329.
Generated by Claude Code
docs(fields): narrow two snippets to ObjectUI's own contract (#6126)
yinlianghui-tw commentedon Aug 24, 2026
os-dev-report
{ "issue": 6126, "status": "done", "branch": "claude/issue-6126-fields-unresolvable-imports", "pr": "https://github.com/objectstack-ai/objectui/pull/6137", "premise_still_valid": true, "summary": "Re-measured on origin/main 133e2ea1e first: all three diagnostics reproduce verbatim, so the card's premise holds. Route check done before implementing — PR #6129 (card #6120) is still open and unmerged, and its route maps only specifiers a workspace package DECLARES, which ajv is not by any package.json here, so narrowing was the route taken rather than growing a second answer. auto-number.mdx's Sequence Management block is now a literal annotated with the exported AutoNumberFieldMetadata (format, starting_number) with the transactional sketch moved to prose; no ambient db, no declare shim, no backend client. object.mdx's Backend Validation block is now an ObjectFieldMetadata literal whose schema holds the JSON Schema a server validates against, with Ajv named only in prose; no dependency added anywhere. Each section gained the ObjectUI-owned fact it was missing — that ObjectUI never allocates a sequence value at all, and that ObjectField checks JSON syntax only and never enforces schema (read from packages/fields/src/widgets/ObjectField.tsx) — so neither narrowed to a gutted example. Both pages join the compile population: blocks-to-compile 206 to 210, exactly the four classifier-matching fences, diagnostics 0, declared fragments unmoved at 111, no FRAGMENT_MARKER.", "tests": "Union re-run at final HEAD f2145987a with a clean tree, each gate quoting its own verdict line. check-doc-snippet-types.mjs: 'Every covered documentation snippet compiles against the built types.' with 'Semantic phase: 210 of 210 block(s) judged, 0 failed.' and its resolution control naming the built dist ('@object-ui/types' resolved to packages/types/dist/index.d.ts). check-doc-component-types.mjs: 'Every documented component type is registered.' check-doc-links.mjs: 'Links are valid across 15 scan roots.' check-control-bytes.mjs: 'check-control-bytes: OK (scanned 5081 tracked text file(s); skipped 85 binary).' check-changeset-presence.mjs: 'No source of a released package changed in this range, so no changeset is owed.' check-changeset-fixed.mjs: 'All workspace packages are in the changeset fixed group.' check-changeset-no-major.mjs: 'No changeset declares a major bump.' 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. pnpm vitest run from the repo ROOT on the three doc-tooling suites: 'Test Files 3 passed (3)', 'Tests 72 passed (72)'. pnpm site:build: exit 0, 180-plus doc paths prerendered, and both prerendered pages checked in .next HTML (new prose present; db.transaction, SequenceCounter, ajv.compile and the ajv import each appear zero times). DECLARED NARROWINGS, two: (1) repo-wide vitest was narrowed to the three doc-tooling suites, run from the repo root as instructed — the diff contains no .ts/.tsx file, so no unit test's subject changed, and no test reads the two pages (grepped); (2) eslint was run as lint:root rather than repo-wide — eslint.config.js targets only '**/*.{ts,tsx}' in every files block, so the population it reads intersects this diff in zero files. ABLATION, to prove the two narrowed blocks are genuinely judged and not merely collected: run on the COMMITTED fix, one unknown key injected into each narrowed literal, restore under an EXIT trap. Mutation confirmed on disk by grepping for the injected text — and 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. Result: 'MUTATION-ON-DISK: injected sequence_reset x1 in auto-number, validator_library x1 in object' followed by TS2353 on each ('sequence_reset' does not exist in type 'AutoNumberFieldMetadata'; 'validator_library' does not exist in type 'ObjectFieldMetadata') and 'Semantic phase: 210 of 210 block(s) judged, 2 failed.' No rebuild leg applies here — the mutation is in the documents the gate reads, not in a package's sources, and the dist the program resolved against is the one the resolution control printed on both the green and the red run. BASELINE, measured in-worktree with the two files reverted to 133e2ea1e under a trap, restore verified: before '317 — 206 to compile, 111 declared fragment(s)' with 63 pages holding a ts/tsx block; after '321 — 210 to compile, 111 declared fragment(s)' with 64. PRE-EDIT RE-MEASUREMENT on origin/main, throwaway re-fence under an EXIT trap, restore verified (plaintext counts back to 7 and 8): TS2304 'Cannot find name db' at auto-number.mdx:119:16, TS7006 on tx at 119:38, TS2307 'Cannot find module ajv' at object.mdx:205:17 — verbatim reproduction of the card's readings, direction as expected (red).", "open_questions": [], "out_of_scope_findings": [ "filed as #6138 (finding, documentation, unassigned, no pm:queue): every content/docs/fields page's 'Field Schema' block declares its OWN interface, so it compiles vacuously under check-doc-snippet-types — and the two measured name keys (value, className, disabled) that the exported AutoNumberFieldMetadata / ObjectFieldMetadata and their shared BaseFieldMetadata do not have; 24 further pages unmeasured" ] }Notes the PM may want, outside the JSON:
skip-changesetlabel, so the docs-only declaration is an empty-frontmatter changeset (.changeset/6126-fields-unresolvable-imports.md), the shape objectui#5867's batches use. No label was created or applied here.behind(main moved to788a21dafter the branch was cut); CI convergence is yours per the dispatch contract.pnpm site:buildin this worktree failed onModule not foundfor@object-ui/plugin-ganttand@object-ui/plugin-map— environmental, both sit outside the doc-snippet gate's build filter and were simply unbuilt in a fresh worktree. Building them made it green with no edit to the diff.Generated by Claude Code
Generated by Claude Code
docs(fields): narrow two snippets to ObjectUI's own contract (objects…