Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Commit 1b69ca5

Browse files
os-justinclaude
andauthored
test(types): re-derive ObjectViewSchema's side of the #6058 split as LOCAL and pin the header counts (#7776)
The zod-mirror-parity header routed ObjectViewSchema's ten unmirrored declared keys as SPEC-DERIVED on a scanner false positive that #6705 removed from SPEC_DERIVED_PAIRS without settling the routing. Re-derived on the tree: the mirror is BaseSchema.extend of local literals and z.lazy siblings and takes no shape from the spec; read through the @objectstack/spec@17.2.0 pin, the spec models four of the ten keys on View-shaped schemas and six nowhere. The entry is LOCAL; the 4 / 6 reading is recorded on it for whoever mirrors. The split's counts (1 / 2 spec-derived, 13 / 94 local, 14 / 96 total) are now derived from the ledger and SPEC_DERIVED_PAIRS membership and pinned against the header read off disk, so the prose can no longer drift silently. Test only. Claude-Session: https://claude.ai/code/session_01BAZFhALsQsGqxui8sNqM8s Co-authored-by: Claude <noreply@anthropic.com>
1 parent 669d71b commit 1b69ca5

2 files changed

Lines changed: 212 additions & 26 deletions

File tree

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
---
3+
4+
Re-derive `ObjectViewSchema`'s side of the objectui#6058 SPEC-DERIVED / LOCAL split in
5+
`zod-mirror-parity.test.ts` (it is LOCAL: the mirror takes no shape from the spec), correct
6+
the split's counts, and pin them against the ledger and `SPEC_DERIVED_PAIRS` (objectui#7279).
7+
Test only; no package is released by this change.

‎packages/types/src/__tests__/zod-mirror-parity.test.ts‎

Lines changed: 205 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1188,31 +1188,55 @@ interface KnownDrift {
11881188
* explicit that forcing the 121 per-key decisions now would be wrong. Two splits
11891189
* are recorded here so whoever works them off does not re-derive them:
11901190
*
1191-
* - **SPEC-DERIVED (2 entries, 12 keys)** — `DashboardWidgetSchema`,
1192-
* `ObjectViewSchema`. It was 3 / 13 until objectui#7623 RETIRED
1191+
* - **SPEC-DERIVED (1 entry, 2 keys)** — `DashboardWidgetSchema`. It was 2 / 12
1192+
* until objectui#7279 RE-DERIVED `ObjectViewSchema`'s side and moved that entry
1193+
* (ten keys) to the LOCAL half — a RECLASSIFICATION on evidence, not a repair:
1194+
* no key moved between ledgers and no mirror changed. It was 3 / 13 until
1195+
* objectui#7623 RETIRED
11931196
* `DashboardComponentSchema.title` by deleting the DECLARATION — the
11941197
* objectui#7129 route, reaching this half for the first time. That key was never
11951198
* going to be answered by #2231 unification: the spec's strict `DashboardSchema`
11961199
* refuses a root `title` outright, and objectui#7509 had already retired every
11971200
* read of it, so the local declaration was offering a member the spec models
11981201
* nowhere and no renderer consumed. ⚠️ objectui#6705 invalidated the
1199-
* evidence for ONE of the two that remain: `ObjectViewSchema` is no longer in
1202+
* evidence for `ObjectViewSchema`: it is no longer in
12001203
* `SPEC_DERIVED_PAIRS` below, because it never referenced a spec schema — it is
12011204
* `BaseSchema.extend({…})` of local literals, and the pre-#6705 text scanner
12021205
* charged it a neighbouring private const's `Spec…` token. That misclassification
1203-
* is left STANDING as #6705 found it — neither the entry's classification nor its
1204-
* key count moved for it: re-routing those keys from #2231's
1206+
* was left STANDING as #6705 found it — re-routing those keys from #2231's
12051207
* unification question to a local mirror edit is a remedy decision on the
1206-
* `UnmirroredDeclared` ledger, which #6705 was fenced out of. Whoever works
1207-
* this split off must re-derive `ObjectViewSchema`'s side first.
1208-
* For `DashboardWidgetSchema` the reading is unchanged:
1208+
* `UnmirroredDeclared` ledger, which #6705 was fenced out of — until
1209+
* objectui#7279 re-derived the side on two measurements. (a) The mirror
1210+
* (`objectql.zod.ts`, `ObjectViewSchema = BaseSchema.extend({…})`) takes NO
1211+
* shape from the spec: every member is a local literal or a `z.lazy` to a
1212+
* sibling objectui mirror, and the `Spec…` consts below it (`KanbanConfig`,
1213+
* `ViewKindEnum`) feed `ListViewSchema`. (b) Read through the pin
1214+
* (`@objectstack/spec@17.2.0`, `ui` entry, all 122 exported object schemas
1215+
* walked; control keys `objectName` / `columns` hit), the spec models FOUR of
1216+
* the ten keys on View-shaped schemas — `listViews` on `ViewSchema`;
1217+
* `navigation`, `searchableFields`, `filterableFields` on `ListViewSchema` and
1218+
* `ObjectListViewSchema` — and SIX nowhere: `allowCreateView`,
1219+
* `defaultListView`, `defaultViewType`, `showViewSwitcher`, `viewActions`,
1220+
* `viewTabBar`. Neither fact makes the pair spec-derived: this route exists for
1221+
* a mirror that IS the spec schema by reference, where growing a key means
1222+
* diverging from the spec; this mirror can grow any key without touching it.
1223+
* So the entry is LOCAL and its remedy is the ordinary local route
1224+
* (objectui#6152's worklist) — a widening of ten keys is a remedy on the manual
1225+
* floor, ⛔ not performed by #7279. The 4 / 6 reading is recorded on the entry
1226+
* for whoever mirrors: the four take their shape BY REFERENCE from the spec slot
1227+
* that models them, the six are plain hand-written omissions.
1228+
* For `DashboardWidgetSchema` the reading is unchanged (reconfirmed on the tree
1229+
* by objectui#7279: `specFieldsExcept(SpecDashboardWidgetSchema.shape, …)`):
12091230
* its mirror takes its shape BY REFERENCE from `@objectstack/spec`. An
12101231
* unmirrored declared key there means the LOCAL declaration carries members the
12111232
* spec schema does not model, which is objectui#2231's unification question and
12121233
* NOT a local mirror edit. They are marked, not exempted: exempting them in the
12131234
* instrument would re-blind exactly the pairs objectui#5927 leaned on hardest.
1214-
* - **LOCAL (12 entries, 84 keys)** — plain omissions from a hand-written mirror.
1215-
* It was 13 / 84 until objectui#7129 RETIRED `DetailViewSectionSchema.hideEmpty`,
1235+
* - **LOCAL (13 entries, 94 keys)** — plain omissions from a hand-written mirror.
1236+
* It was 12 / 84 until objectui#7279 RECLASSIFIED the `ObjectViewSchema` entry
1237+
* (ten keys) into this half from the SPEC-DERIVED one — the split's first move
1238+
* of an ENTRY between its halves; no key and no mirror moved. Before that it
1239+
* was 13 / 84 until objectui#7129 RETIRED `DetailViewSectionSchema.hideEmpty`,
12161240
* a shrink by removing the DECLARATION rather than by mirroring it, 12 / 83
12171241
* until objectui#7352 MIRRORED `ChartSchema.drillDown` — its whole entry — and
12181242
* 11 / 82 until objectui#7655 SEEDED a `ChatbotFloatingSchema` entry with the two
@@ -1230,8 +1254,18 @@ interface KnownDrift {
12301254
* RETIRED one from the SPEC-DERIVED half (13 → 12 keys there), objectui#7352
12311255
* MIRRORED two — the LOCAL `ChartSchema` entry and the seeded `ObjectDataTableSchema`
12321256
* one — and objectui#7655 SEEDED the LOCAL `ChatbotFloatingSchema` entry, born with
1233-
* two keys. The ledger now totals **14 entries / 96 keys** — 2 / 12 spec-derived,
1234-
* 12 / 84 local; the seeded pair is no longer among them.
1257+
* two keys. objectui#7279 then moved `ObjectViewSchema` between the halves (2 / 12
1258+
* and 12 / 84 before it) without moving the totals. The seeded pair is no longer
1259+
* among them, and the ledger now totals — on ONE line, because the pin below reads
1260+
* this sentence off disk —
1261+
* **14 entries / 96 keys** — 1 / 2 spec-derived, 13 / 94 local.
1262+
*
1263+
* ⛔ The four split figures above and this totals line are PINNED: 'objectui#7279'
1264+
* at the bottom of this file derives every one of them from the `UnmirroredDeclared`
1265+
* ledger and `SPEC_DERIVED_PAIRS` membership and compares them with the figures read
1266+
* off this header. A figure edited by hand without the ledger moving is red, and so
1267+
* is a ledger that moved without its figure — which is exactly how this split drifted
1268+
* three times between objectui#6058 and objectui#7279.
12351269
*
12361270
* ## How this was measured, and the trap that makes the number hard to get
12371271
*
@@ -1361,12 +1395,30 @@ interface UnmirroredDeclared {
13611395
| 'reorderableColumns' | 'resizableColumns' | 'rowColor' | 'rowHeight' | 'rowSpecActions'
13621396
| 'singleClickEdit';
13631397
/**
1364-
* SPEC-DERIVED → objectui#2231. ⭐ This pair had NO entry in EITHER ledger before
1365-
* objectui#6058 — eleven declared keys the published validator has never heard of,
1366-
* and the guard reported the pair clean. It is the clearest single instance of the
1367-
* blind spot this ledger exists to make visible. It was eleven: `onNavigate` is in
1368-
* `RuntimeOnlyDeclared` below (objectui#6152), which does NOT change the routing of
1369-
* the other ten — they are still spec-derived and still go to objectui#2231.
1398+
* LOCAL since objectui#7279 — recorded as SPEC-DERIVED → objectui#2231 from
1399+
* objectui#6058 until then, on the scanner false positive objectui#6705 exposed: the
1400+
* mirror is `BaseSchema.extend({…})` of local literals and `z.lazy` siblings, it
1401+
* references no spec schema, and it is not in `SPEC_DERIVED_PAIRS`. ⭐ This pair had
1402+
* NO entry in EITHER ledger before objectui#6058 — eleven declared keys the
1403+
* published validator has never heard of, and the guard reported the pair clean.
1404+
* It is the clearest single instance of the blind spot this ledger exists to make
1405+
* visible. It was eleven: `onNavigate` is in `RuntimeOnlyDeclared` below
1406+
* (objectui#6152), which did not change the routing of the other ten. Their route
1407+
* is the ordinary local one (objectui#6152's worklist); the ten-key widening is a
1408+
* remedy on the manual floor and was ⛔ not performed by #7279. For whoever
1409+
* mirrors, the spec read through the pin (`@objectstack/spec@17.2.0`, `ui` entry)
1410+
* splits them 4 / 6:
1411+
* - FOUR the spec models on View-shaped schemas — take the shape BY REFERENCE:
1412+
* `navigation` (`ListViewSchema.navigation` = `NavigationConfigSchema`, the
1413+
* very type the declaration imports for `ViewNavigationConfig`);
1414+
* `searchableFields` and `filterableFields` (`ListViewSchema`, `array(string)`;
1415+
* the spec marks `filterableFields` a legacy shorthand for `userFilters.fields`);
1416+
* `listViews` (`ViewSchema.listViews`, a record of spec list views — ⚠️ the
1417+
* declaration's value is the local `NamedListView`, so the VALUE type is a
1418+
* unification question the mirror edit must not paper over with a `z.any()`).
1419+
* - SIX the spec models nowhere — plain hand-written omissions: `allowCreateView`,
1420+
* `defaultListView`, `defaultViewType`, `showViewSwitcher`, `viewActions`,
1421+
* `viewTabBar`.
13701422
*/
13711423
'objectql.zod.ts#ObjectViewSchema':
13721424
| 'allowCreateView' | 'defaultListView' | 'defaultViewType' | 'filterableFields'
@@ -1529,10 +1581,11 @@ interface RuntimeOnlyDeclared {
15291581
/** 1 of `ObjectGridSchema`'s former 17. POLICY group. Read at `ObjectGrid.tsx:1334`. */
15301582
'objectql.zod.ts#ObjectGridSchema': 'onNavigate';
15311583
/**
1532-
* 1 of `ObjectViewSchema`'s former 11 — the one key that sits in both stories. This
1533-
* pair is ALSO spec-derived, so its other ten keys stay in `UnmirroredDeclared` and
1534-
* stay routed to objectui#2231; reclassifying its callback does not re-route the
1535-
* pair. POLICY group.
1584+
* 1 of `ObjectViewSchema`'s former 11 — the one key that sits in both stories. Its
1585+
* other ten keys stay in `UnmirroredDeclared`; reclassifying its callback did not
1586+
* re-route the pair, and neither did objectui#7279's move of that entry from the
1587+
* split's SPEC-DERIVED half to its LOCAL one (the pair was never spec-derived —
1588+
* see the entry above). POLICY group.
15361589
*/
15371590
'objectql.zod.ts#ObjectViewSchema': 'onNavigate';
15381591
/**
@@ -2196,10 +2249,13 @@ const SPEC_DERIVED_PAIRS: readonly string[] = [
21962249
// literal. Its declaration ends ~50 lines above the next `export const`, and
21972250
// the old text window ran on to that boundary, swallowing the private
21982251
// `KanbanConfig = SpecKanbanConfigSchema…` block that belongs to no export.
2199-
// ⚠️ The `ObjectViewSchema` removal has a consequence this card did NOT settle:
2200-
// the objectui#6058 split in this file's header routes its unmirrored declared
2201-
// keys as SPEC-DERIVED — a routing that rests on the false positive. That
2202-
// classification is deliberately left as it stands here; see the note there.
2252+
// ⚠️ The `ObjectViewSchema` removal had a consequence #6705 did NOT settle: the
2253+
// objectui#6058 split in this file's header routed its unmirrored declared keys
2254+
// as SPEC-DERIVED — a routing that rested on the false positive. objectui#7279
2255+
// re-derived that side on the tree and through the spec pin and moved the entry
2256+
// to the split's LOCAL half (its `UnmirroredDeclared` docblock carries the
2257+
// per-key reading). The split's counts now derive from THIS list's membership
2258+
// and are pinned against the header by 'objectui#7279' below.
22032259
'complex.zod.ts#DashboardComponentSchema',
22042260
'complex.zod.ts#DashboardWidgetSchema',
22052261
'form.zod.ts#SelectOptionSchema',
@@ -2503,6 +2559,129 @@ this derivation subtracts from the pinned population, so it fails as a consequen
25032559
});
25042560
});
25052561

2562+
/* ── The SPEC-DERIVED / LOCAL split is derived, and the header is pinned to it ── */
2563+
2564+
/**
2565+
* Entry → declared-key members of one of the two unmirrored ledgers, read from this
2566+
* file's own AST the way `ledgerEntryKeys` reads the entry names. Each property
2567+
* signature's type is a union of string literals (or one literal); the literals ARE
2568+
* the keys, so this is the instrument that sizes a ledger in keys, not just entries.
2569+
*
2570+
* A member that is not a string literal is a hard error rather than a skipped row:
2571+
* a ledger that quietly grew a `string` or `never` arm would otherwise read as fewer
2572+
* keys, and every count below would still pass.
2573+
*/
2574+
function ledgerEntryMembers(ledger: 'UnmirroredDeclared' | 'RuntimeOnlyDeclared'): Map<string, string[]> {
2575+
selfAst ??= ts.createSourceFile(
2576+
SELF, readFileSync(SELF, 'utf8'), ts.ScriptTarget.ESNext, false, ts.ScriptKind.TS,
2577+
);
2578+
const decl = selfAst.statements.find(
2579+
(s): s is ts.InterfaceDeclaration => ts.isInterfaceDeclaration(s) && s.name.text === ledger,
2580+
);
2581+
if (!decl) throw new Error(`no top-level interface ${ledger} in ${SELF} — it was renamed, or the reader is reading the wrong file`);
2582+
const out = new Map<string, string[]>();
2583+
for (const m of decl.members) {
2584+
if (!ts.isPropertySignature(m) || !m.type) continue;
2585+
const entry = ts.isStringLiteral(m.name) ? m.name.text : m.name.getText(selfAst);
2586+
const arms = ts.isUnionTypeNode(m.type) ? m.type.types : [m.type];
2587+
out.set(entry, arms.map((arm) => {
2588+
if (ts.isLiteralTypeNode(arm) && ts.isStringLiteral(arm.literal)) return arm.literal.text;
2589+
throw new Error(`${ledger}['${entry}'] has a member that is not a string literal: ${arm.getText(selfAst)}`);
2590+
}));
2591+
}
2592+
return out;
2593+
}
2594+
2595+
/**
2596+
* One figure the file header writes down, read off disk. The spelling must occur
2597+
* EXACTLY once: a second copy — a stale figure left standing beside a corrected one —
2598+
* would let the pin pass on whichever copy the regex met first.
2599+
*/
2600+
function headerFigures(spelling: RegExp): number[] {
2601+
const hits = [...readFileSync(SELF, 'utf8').matchAll(new RegExp(spelling.source, 'gu'))];
2602+
expect(hits.length, `the header spelling ${spelling} must occur exactly once in ${SELF}; it occurs ${hits.length} times`)
2603+
.toBe(1);
2604+
return hits[0].slice(1).map(Number);
2605+
}
2606+
2607+
describe('the SPEC-DERIVED / LOCAL split is derived, and the header is pinned to it (objectui#7279)', () => {
2608+
/** The split, derived: `UnmirroredDeclared` entries by `SPEC_DERIVED_PAIRS` membership. */
2609+
const derive = () => {
2610+
const rows = Array.from(ledgerEntryMembers('UnmirroredDeclared'));
2611+
const size = (subset: typeof rows) => ({
2612+
entries: subset.length,
2613+
keys: subset.reduce((n, [, keys]) => n + keys.length, 0),
2614+
});
2615+
return {
2616+
specDerived: size(rows.filter(([entry]) => SPEC_DERIVED_PAIRS.includes(entry))),
2617+
local: size(rows.filter(([entry]) => !SPEC_DERIVED_PAIRS.includes(entry))),
2618+
total: size(rows),
2619+
};
2620+
};
2621+
2622+
it('the split figures and the totals the header writes down equal the ledger', () => {
2623+
// objectui#6058 wrote the split as prose with counts; objectui#7623, #7129, #7352
2624+
// and #7655 each moved the ledger and corrected the counts by hand, and #7279
2625+
// found the SPEC-DERIVED half still carrying an entry `SPEC_DERIVED_PAIRS` had
2626+
// dropped at #6705. Nothing compared the two — this does. Every figure is read
2627+
// off the header's OWN spelling, so a rewording that drops the digit is red too.
2628+
const [specEntries, specKeys] = headerFigures(/\*\*SPEC-DERIVED \((\d+) entr(?:y|ies), (\d+) keys?\)\*\*/);
2629+
const [localEntries, localKeys] = headerFigures(/\*\*LOCAL \((\d+) entr(?:y|ies), (\d+) keys?\)\*\*/);
2630+
const [totalEntries, totalKeys, tSpecEntries, tSpecKeys, tLocalEntries, tLocalKeys] = headerFigures(
2631+
/\*\*(\d+) entries \/ (\d+) keys\*\* — (\d+) \/ (\d+) spec-derived, (\d+) \/ (\d+) local\./,
2632+
);
2633+
const [topEntries, topKeys] = headerFigures(/\*\*(\d+) entries\*\* in `UnmirroredDeclared`, \*\*(\d+) keys\*\* across them/);
2634+
2635+
const header = {
2636+
specDerived: { entries: specEntries, keys: specKeys },
2637+
local: { entries: localEntries, keys: localKeys },
2638+
total: { entries: totalEntries, keys: totalKeys },
2639+
totalsLine: { specDerived: { entries: tSpecEntries, keys: tSpecKeys }, local: { entries: tLocalEntries, keys: tLocalKeys } },
2640+
topOfFile: { entries: topEntries, keys: topKeys },
2641+
};
2642+
const ledger = derive();
2643+
expect(header, `
2644+
The header's SPEC-DERIVED / LOCAL split figures disagree with the ledger.
2645+
2646+
WHICH SIDE TO CHANGE — decide by what your diff touched, not by which number looks
2647+
right (git diff -- packages/types/src/__tests__/zod-mirror-parity.test.ts):
2648+
2649+
* you moved an UnmirroredDeclared entry or key, or SPEC_DERIVED_PAIRS membership
2650+
=> correct the header's figures to the derived ones below, and ADD the history
2651+
sentence the split keeps for every move (it is cumulative by design).
2652+
* you edited a header figure by hand, or carried one in from a card or a comment
2653+
=> put it back. The ledger is the measurement; the header only records it.
2654+
2655+
⛔ Never reconcile the two by editing a ledger KEY SET or SPEC_DERIVED_PAIRS: both are
2656+
pinned elsewhere in this file against the mirrors themselves.`)
2657+
.toEqual({
2658+
specDerived: ledger.specDerived,
2659+
local: ledger.local,
2660+
total: ledger.total,
2661+
totalsLine: { specDerived: ledger.specDerived, local: ledger.local },
2662+
topOfFile: ledger.total,
2663+
});
2664+
});
2665+
2666+
it('the member reader can actually see the unions (non-vacuity)', () => {
2667+
// A reader that returned no members would derive 0 keys on both halves and a
2668+
// header written as 0 / 0 would pass while measuring nothing — the same failure
2669+
// mode 'the ledger reader can actually see the ledgers' guards for entry names.
2670+
const members = ledgerEntryMembers('UnmirroredDeclared');
2671+
expect(Array.from(members.keys()), 'the member reader and the entry reader disagree on the entry list')
2672+
.toEqual(ledgerEntryKeys('UnmirroredDeclared'));
2673+
const ledger = derive();
2674+
expect(ledger.specDerived.entries, 'the SPEC-DERIVED half read as EMPTY — `DashboardWidgetSchema` is in both the ledger and SPEC_DERIVED_PAIRS')
2675+
.toBeGreaterThan(0);
2676+
expect(ledger.local.entries, 'the LOCAL half read as EMPTY').toBeGreaterThan(0);
2677+
expect(ledger.total.keys, 'no entry read as a union of more than one literal — the reader is not walking union arms')
2678+
.toBeGreaterThan(ledger.total.entries);
2679+
for (const [entry, keys] of members) {
2680+
expect(keys.length, `${entry} read as having no keys`).toBeGreaterThan(0);
2681+
}
2682+
});
2683+
});
2684+
25062685
describe('the spec-reference scan reads code, not prose (objectui#6705)', () => {
25072686
const scan = (src: string): string[] => [...specReferencingExports('fixture.zod.ts', src)].sort();
25082687

0 commit comments

Comments
 (0)