test(scripts): census the $-dialect lowercase aliases before objectui#8568 is ruled

[os-steve]

Refs #8568

⛔ This PR rules NOTHING. objectui#8568 names three directions — retire the converter's aliases, teach ValueDataSource the aliases, keep both and document the split — and this change takes no position on any of them. The card stays OPEN.

It delivers only the prerequisite the card names in its own words:

option 1's cost is entirely a function of how many authors are relying on the tolerance, and nobody has measured that.

Zero behaviour change. No acceptance set moves. operatorMap, ValueDataSource and every $-dialect arm are byte-identical to main. Against the merge-base, the change set is exactly 3 files, 958 insertions, 0 deletions: two new files under scripts/ plus one scripts entry in the root package.json.

---

The number

pnpm census:dollar-dialect-aliases, HEAD 738cc8bdc:

ALIASES = accepted but not canonical (4) : $notin $notcontains $startswith $endswith

Alias occurrences, whole tree              : 24
  of which in operator-key position        : 7
Alias occurrences in the AUTHORED CORPUS   : 0
  of which in operator-key position        : 0

role                  total  payload  mention
converter-ledger         10        3        7
refusal-ledger            6        0        6
implementation            4        4        0
release-notes             4        0        4

Every one of the 24 occurrences is either the map that defines the aliases, or something pointing at that map. Nothing in examples/, apps/, content/, docs/, e2e/ or skills/ authors one. The four "payloads" outside the map are the converter's own unit tests exercising the alias arms.

So: in the corpus this repository can reach, option 1's blast radius is zero authored filters and the work is the ledger — the map's four rows, the converter's alias assertions, and the README rows PR #8565's pin will name.

Why examples/ is zero for a structural reason, not a lucky one

examples/ authors filters exclusively in the object-form dialect ({ "operator": "eq" }), not the $-dialect. Measured: 7 rows across 3 files under components-complex-filter-builder/, and no $-operator in key position anywhere in that tree. That dialect has its own table (FILTER_OPERATOR_ALIASES), which is tolerant by design and case-folding by construction (normalizeFilterOperator lowercases before the lookup) and carries bare startswith / endswith / notcontains / notin as first-class members. Option 1 does not touch it.

Conflating the two dialects is the single largest way to misread this number, and it is easy: a grep for startswith cannot tell them apart. The census requires the $ and requires operator-key position, and ships a control that fails if a sibling row is ever counted.

---

⚠️ What this census CANNOT see — the part that bounds every option

The authored-corpus zero is consumer-local, not seam-wide (objectui#6839). This repo is a renderer; the filters it lowers are authored as metadata, and the metadata store is not in this tree. Invisible from here, and therefore not in any count above:

• view / list-view / sharing-rule criteria already stored in a deployment database. FilterConditionField writes criteria_json into exactly such a store, and nothing here can enumerate what is in one;
• seed, demo and app metadata shipped from objectstack-ai/objectstack or any other producer repo;
• filters assembled at runtime by published @object-ui/* consumers;
• any filter whose operator key is COMPUTED ({ [op]: value }), which no static scan resolves.

A zero here means "this repo does not rely on the tolerance". It does not mean "no author relies on the tolerance", and it must not be quoted as if it did.

One measured fact that narrows the unseen population

kvToCondition — the reader that loads stored $-criteria back into the filter builder — has arms for $contains, $icontains, $notContains, $ncontains, $gt, $lt, $gte, $lte, $startsWith, $endsWith, $null, $exists, $in, $nin, $ne. It has an arm for none of the four aliases (verified: 0 matches for case '$notin'|'$startswith'|'$endswith'|'$notcontains'), so they fall to default: return null — "criteria can't be represented", which drops the admin into the raw-JSON editor.

⇒ On the one authoring surface this repo ships, a stored lowercase alias already fails to round-trip today. It executes on the ObjectStack adapter and cannot be reopened in the builder. That is a real, pre-existing degradation for exactly the population option 1 would break, and it lowers option 1's marginal cost.

---

Verification of the card's own claims

PR #8565's reconciliation pin does redden when the aliases are removed — CONFIRMED. readme-filter-operator-table.test.ts reads operatorMap out of filter-converter.ts's source (operatorMapFromSource, anchored on const operatorMap) and asserts, among others, that every spelling in the README's first column lowers — so a README row whose spelling no longer lowers is reported as is refused by convertFiltersToAST, so it is not a supported operator, and that row's worked example throws. Removing an alias reddens on two independent assertions.

Anchors re-derived, not trusted. The four spellings are exactly the four named. Their positions are not: measured today they are at filter-converter.ts L75 / L79 / L81 / L83 with the comment at L65 — a uniform +6 from the line numbers in the dispatch. The set held; the addresses did not.

---

What is delivered, and why a committed script rather than a one-off

A one-off number would have been enough for a stable count. This one is not stable and is not simple:

1. It must be re-measured at the moment a direction lands, and by whoever lands it — a count from today does not price a change made next week.
2. The naive measurement is wrong in a way that looks right. Two dialects, one of them deliberately case-folding; a case-insensitive grep reports the canonical corpus as alias reliance, and a case-insensitive exclusion erases the aliases entirely. Both hazards were live while this was being written.
3. After option 1 the alias set is empty, and a script that hunted four hardcoded spellings would keep reporting on a dialect the code no longer speaks. So the set is DERIVED — operatorMap read from source (the technique the docs(data-objectstack): re-derive the filter-operator table from convertFiltersToAST and pin it #8565 pin already uses, because the map is not exported) minus @objectstack/spec's FILTER_OPERATORS. Hardcoding the four would have rebuilt this card's own defect one level up.

Report-only, under the tree's existing census:* convention (census:body-dialect, census:tsconfig-test-parity, census:cross-file-line-citations) — the spelling that already means "runnable, reported, not blocking". Not wired into CI: objectui#8568 reserves that decision.

The four controls, because a zero with no lit positive control is not a reading

control	kind	reading on this tree
canonical-twin	positive, must be LIT	3/3 twins visible to the same scanner: $notContains=42, $startsWith=36, $endsWith=29
authored-reach	positive, must be LIT	9 canonical $-operator payloads in NON-TEST authored files (AuditLogPage.tsx:122 $gte, recordReadability.ts:164 $in, …)
impossible	negative, must be DEAD	$startswithzzz: 0
sibling-dialect	negative, must be DEAD	4 $-free bait rows present in FILTER_OPERATOR_ALIASES; 0 counted as $-dialect

authored-reach excludes tests deliberately: reaching only the suites is not reaching the metadata. sibling-dialect measures its own bait, because "counted zero sibling rows" and "there are no sibling rows left to count" are otherwise the same reading.

Ablation — the controls can actually fail

Run on the committed tree, mutation proven on disk by anchor counts and blob hash before the result was read, restored by git checkout HEAD -- path and proven restored by blob equality plus an empty git diff HEAD:

leg	sibling-dialect	census exit
baseline	PASS — 4 bait rows, 0 counted	0
$-guard loosened at BOTH layers (prefilter + regexes)	FAIL — 4 bait rows, 10 counted	1, "this run is NOT a reading"
restored	PASS — 4 bait rows, 0 counted	0

⚠️ Reported because it is what happened, not what was predicted. The first ablation loosened the REGEX alone and the control stayed GREEN — the literal prefilter in scanText had already excluded the file before the regex ran. So the runtime control witnesses the composed scanner; a one-layer regression is caught by the suite, which pins $-strictness and case-sensitivity directly on scanText. That asymmetry is now written where the control is defined instead of being left for the next reader.

The suite also caught two real defects in the instrument, both of the "PASS while witnessing nothing" family: the census scanning itself (its fixture text includes the impossible spelling, so the negative control fired on its own declaration the moment the files became tracked), and the bait gap above. Both are fixed in the second commit.

---

Gates

Re-run on the merged tree at HEAD 738cc8bdc, after origin/main advanced to efead6c60 mid-flight. Every exit code captured to a file before it was read, never through a pipe.

gate	exit	note
pnpm run type-check:scripts	0	scripts/**/*.ts is a glob include, so the new test is covered automatically
pnpm exec turbo run lint --concurrency=2	0	CI's own pnpm lint; 47/47 tasks, 0 errors repo-wide
pnpm exec vitest run scripts/	0	136 files passed, 2 skipped; 3990 tests passed
pnpm run check:new-line-citations	0	the gate that landed in #8974 while this was in flight — 0 new cross-file citations added by this branch, its own controls firing
pnpm run check:control-bytes	0	plus a direct grep -naP over the diff, no hits
node scripts/check-changeset-presence.mjs	0	none owed — nothing published moved
node scripts/check-governed-queue-guard.mjs --test (3 paths)	0	NOT GOVERNED — ordinary review route
pnpm run check:doc-types	0
pnpm run check:doc-snippets	0	first run exit 2 = PREREQUISITE NOT MET; scoped build, then 0
pnpm run check:doc-examples	0	same: exit 2 first, then 0. 124 blocks, 89 ledger rows all matching
pnpm run check:entry-guard	0	shrink-only counters unmoved
node scripts/check-unreferenced-sources.mjs	0
node scripts/check-pre-install-import-graph.mjs	0
node scripts/check-lint-coverage.mjs	0	46/46
node scripts/check-type-check-coverage.mjs	0

Lint population, stated so the reading is checkable. An auxiliary whole-tree pnpm exec eslint . --no-inline-config --format json (not CI's command — CI runs turbo run lint per package) judged 4720 files by eslint's own config. The two new files carry 0 errors and 0 warnings. The files it reports with errors are all under apps/, packages/ and e2e/; this diff touches none of them. Invariance: eslint.config.js declares no type-aware linting (0 matches for projectService, parserOptions, project:, tsconfigRootDir, and 0 for tsconfig), so nothing in this diff can move the verdict on any untouched file.

Heavy runs went through the container's shared verify lock; each printed VERDICT command-exit 0. Those wall-clock figures are shared-box seconds, not idle-box seconds.

Merge with main. origin/main advanced from 3ff3fc63f to efead6c60 during this task. Merged in and resolved: the only conflict was the root package.json, where #8974 and this branch each added a scripts entry immediately after census:cross-file-line-citations. Both entries kept. origin/main is an ancestor of this head, and the change set against the new merge-base is unchanged at 3 files / 958 insertions.

Serial adjacency, re-derived here rather than cited. All open PRs enumerated and their file lists read directly. At the first reading none touched the root package.json; by the time #8974 merged, one did — which is the conflict resolved above, and a demonstration of why the dispatch said not to trust any adjacency snapshot, including this one. Both new files are new, so no open PR can conflict on them.

---

Out of scope, filed separately

objectui#8976 — the same seam has a third acceptance-set disagreement, in the direction opposite to this card's: $icontains is a canonical member of the spec's FILTER_OPERATORS, ValueDataSource executes it, this repo's own FilterConditionField emits it for the containsCaseInsensitive builder operator, and convertFiltersToAST refuses it with INVALID_FILTER / 400. Measured both legs in one process with a $contains control that passes on both sides. PR #8565's pin is structurally blind to it: it holds the README tables against operatorMap's keys and the unknown-operator error's list, and $icontains is in neither.

Noted, not filed: kvToCondition's missing alias arms (written up above as census evidence — it reads as consistent with the contract-first direction rather than as a defect, and whoever rules objectui#8568 is the reader who needs it).

---

For whoever rules the three options

• In-repo cost of option 1 is zero authored filters and a bounded ledger edit. CI will name the ledger rows: PR docs(data-objectstack): re-derive the filter-operator table from convertFiltersToAST and pin it #8565's pin reddens on removal, by design.
• The out-of-repo cost is unmeasured and unmeasurable from here. Stored criteria_json is the population that matters and it is not in this tree. The census says so in its own output rather than leaving the zero to be quoted flat.
• Those authors are already half-broken. A stored lowercase alias does not round-trip through the filter builder today.
• Re-run pnpm census:dollar-dialect-aliases at the moment a direction lands. It derives its own alias set, so it stays correct on a tree where the aliases are gone.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MPaVWWMuWeT5LgB1qoXjVB