docs(objectql): the last two carriers of the falsified "schema-uniform" premise state what the tree does

[os-musk]

Fixes #17291

Clause-②: no

Comment-only, per the claim comment's declaration and the dispatch ruling. The executable token stream is byte-identical on both files (proof below); no predicate, accept set, exported symbol or emitted byte moves.

The deliverable was the re-verification, not the edit

Triage asked for two things before any fix: that both sites still say what the card reports, and that they really are the last two — "if a third turns up, that is the finding, not the fix."

Both confirmed. There is no third. The dispatching seat flagged its own predicate as not independently established: it was the single token schema-uniform, and a line-oriented grep cannot see a phrase that wraps a newline. So the population was re-derived with an instrument that can:

1. Line-joining scan over all 8,433 tracked text files — comment leaders (*, //, #, --) dropped, every whitespace run collapsed to one space, with an offset-to-line map so hits still report a real line. A wrapped phrase is visible to this and invisible to grep.
2. Ten spellings of the claim, not one token — schema[-_ ]*uniform (any wrap or spacing), "uniform across rows/batch", "every/all rows drop the same", "same set … row", "identical across/for rows", "row-independent", "does not vary by row", "union is faithful", "the same for every row", "aggregate is faithful".
3. Sentence-level co-occurrence, to catch a spelling nobody thought of: every sentence in the joined text carrying a strip-domain subject (strip / dropped / readonly / preserveAudit / hookWrittenKeys / runtime-owned) and a uniformity assertion and the token "row". 109 sentences; 11 in the strip domain.

Of those 11: two are these sites; three are the already-corrected prior art (packages/spec/src/api/protocol.zod.ts, packages/metadata-protocol/src/protocol.ts, and the generated protocol.mdx mirror), which show up quoting and refuting the claim rather than carrying it; the rest are different subjects (counter scans, sharing conditions, conversion-notice dedup). The three corrected siblings surfacing is the control that makes the two a reading — the predicate family does reach sites of this exact class.

CHANGELOG.md carriers were never touched: five files, compiled release history, untouched and still at five after the fix (the count control below).

The two sites

packages/objectql/src/engine.ts — the per-CALL preserveAudit warning, 60 lines below the hookWrittenKeys: rowHookWrittenKeys[i] call that falsifies it.

packages/objectql/src/validation/rule-validator.ts — the docblock of preserveAuditIgnoredOnInsertWarning. This is the one that contradicted its own file: both hookWrittenKeys option docs above it state the granularity as per ROW, never per call, while this docblock justified a per-call aggregation with uniformity. A reader got two answers and no way to tell which was current. The file now gives one, and says so by pointing at those option docs.

Neither is a carrier #17290 (landed ada286979f, today) missed: that change corrected insertMany's docblock ~450 lines further down, on a different falsified premise (that a caller holding the input rows could attribute a reported name back to rows). Read first; neither undone nor double-corrected.

The aggregation itself is unchanged — the issue explicitly left its shape undecided, and it stays right on the reason the producer already has: a log line has no per-row slot, so the union is the only view one line can represent. Both sites now add the reader guidance the prior art uses: read a name as "at least one row lost this field", never "every row did".

Verification

Comment-only, proven by the executable token stream. A grep -c for removed text cannot tell "the claim stands" from "the claim is quoted and refuted", so the repo's own instrument answers instead — scripts/js-comment-mask.mjs (stripComments), comparing base to HEAD with whitespace collapsed:

IDENTICAL  packages/objectql/src/engine.ts                     208,980B both sides
IDENTICAL  packages/objectql/src/validation/rule-validator.ts   34,672B both sides
VERDICT executable-token-stream UNCHANGED (comment-only)

Both control directions fired (trap-guarded, each mutation proven on disk by anchor counts and a blob hash, each restore verified by blob identity against HEAD plus an empty git diff HEAD):

direction	mutation	expected	observed
A	one code byte (length > 0 to > 1)	DIFFERS	DIFFERS, first divergence located at offset 144,097
B	one comment byte	IDENTICAL	IDENTICAL

Without A the instrument could be blind; without B it could be trivially sensitive. Both ran; the tree was restored after each.

Population, re-measured after the fix, beside a control that still fires:

live source carriers of 'schema-uniform'   0   (was 2)
CHANGELOG.md carriers (CONTROL)            5   (unchanged — never edited)

Tests and gates, at b83db02144:

• pnpm --filter @objectstack/objectql test — 296 files / 4,959 tests passed
• pnpm --filter @objectstack/objectql typecheck — pass (test layer compiles; 40 files / 234 errors / 65 pinned signatures held in the shrink-only debt ledger, unchanged)
• pnpm --filter '@objectstack/objectql...' build — pass (dependency closure)
• Derived gate family via scripts/pm/dispatch-gates.mjs, reconciled with --ran carrying exit codes: 52 derived, 51 run green, 1 NOT MEASURED, 0 unrun. (The derivation was 59 while the changeset was present; deleting it dropped exactly the 7 changeset-family gates and added none. Every gate was re-run at 5b137ee0a5, not inherited.)

NOT MEASURED: pnpm check:dual-build-cjs-loads — exit 3, PREREQUISITE NOT MET. It reads built output for every package and 55 have no dist/ in this worktree; it needs a full-farm pnpm build. ⛔ Recorded as unmeasured, not as a pass. CI builds fresh and runs it there. A comment-only diff cannot move emitted bytes, which the token-stream identity above and the published-surface measurement below both independently show — but neither is that gate's verdict.

⚠️ The local sweep says nothing about the clause-② level axis. With no --event payload, check-changeset-no-major.mjs takes the no-pull-request branch and exits 0. Its green here is not evidence on that axis, and is not reported as such.

No changeset — this diff publishes nothing

Ruled by the maintainer seat after the measurement below; the first push carried a patch changeset and it has been deleted (commit 5b137ee0a5). AGENTS.md defines the label directly: skip-changeset is for a diff that publishes nothing from any released package, and this is one. The label is the maintainer's to apply, not this seat's.

Measured three independent ways, all agreeing:

1. engine.ts — an inline // comment inside a method body, never emitted to a .d.ts under any configuration.
2. rule-validator.ts — the docblock sits on export function preserveAuditIgnoredOnInsertWarning, which is exported from its module but is not re-exported from the package entry: packages/objectql/src/index.ts:437 re-exports only evaluateValidationRules, needsPriorRecord and legalNextStates from that file. The symbol never reaches dist/index.d.ts. Control: that entry carries 82 export statements and does re-export three siblings from the same file — selective, not empty.
3. Built output — after a real build, dist/ greps 0 for the new docblock text and 0 for the old schema-uniform, while the positive control (the runtime string literal from the same function) hits 4 files and dist/index.d.ts carries 2,364 JSDoc lines, so the instrument would have found the docblock had it published.

⚠️ The recent comment-only changesets are not precedent for "comment-only ⇒ patch" — each measured that its corrected TSDoc does reach the built .d.ts. Same rule, opposite measurement. The files[] array is identical across those packages and this one (dist, README.md, CHANGELOG.md), so it was never the discriminator either.

⇒ Check Changeset is expected RED until the skip-changeset label lands; that is the gate working, not a defect.

Acceptance notes

Out of scope, noted and not filed:

• preserveAuditIgnoredOnInsertWarning has no test referencing it anywhere in the tree — only its definition and its single call site. Its docblock records a measurement taken when the ruling landed, but nothing pins that the line fires, or its text. Not filed: not a reproducible defect, not a declared-contract violation, and not a metadata-authoring trap — it is missing coverage, which the acceptance-note channel is for. Successor: any card that changes the create-side preserveAudit posture would touch this function and is the natural place to add the pin.
• The five CHANGELOG.md carriers keep a falsified sentence quotable in compiled release history. Correctly untouchable here — a factual error in a released entry is amended in its own docs-only PR, never as a rider. Noted only so the next reader of a schema-uniform grep knows those five hits are expected.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/objectql/src/validation/rule-validator.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/objectql/src/validation/rule-validator.ts) — pages documenting those are invisible to this run
• 1 name(s) were too generic to anchor anything (single lowercase words)
• 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 — 16 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 98c904a9b5f1ef1af961d55004efb3c6a3114e53 → packageMentionDocs.