@@ -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 ( / \* \* S P E C - D E R I V E D \( ( \d + ) e n t r (?: y | i e s ) , ( \d + ) k e y s ? \) \* \* / ) ;
2629+ const [ localEntries , localKeys ] = headerFigures ( / \* \* L O C A L \( ( \d + ) e n t r (?: y | i e s ) , ( \d + ) k e y s ? \) \* \* / ) ;
2630+ const [ totalEntries , totalKeys , tSpecEntries , tSpecKeys , tLocalEntries , tLocalKeys ] = headerFigures (
2631+ / \* \* ( \d + ) e n t r i e s \/ ( \d + ) k e y s \* \* — ( \d + ) \/ ( \d + ) s p e c - d e r i v e d , ( \d + ) \/ ( \d + ) l o c a l \. / ,
2632+ ) ;
2633+ const [ topEntries , topKeys ] = headerFigures ( / \* \* ( \d + ) e n t r i e s \* \* i n ` U n m i r r o r e d D e c l a r e d ` , \* \* ( \d + ) k e y s \* \* a c r o s s t h e m / ) ;
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+
25062685describe ( '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