chore(gates): collapse the four ADR 0014 R7 rows into the owned refFrame value

R7's owner table listed `refFrameState`, `refFrameScope`, `refFrameTree` and
`refFrameGeneration` as four fields that had to be written together by one
module; the code now carries them as one nominal value, so the table carries one
row. R10 follows: 19 writer-owned fields to 16, 22 owner claims to 19.

The row itself stays. The type stops construction, editing and spread-derivation
of a frame outside ref-frame.ts, but it cannot judge a whole frame moved
unchanged — clearing the field, or assigning another session's frame — and the
table can. The comments say that rather than claiming full enforcement.

Seen red: a planted `session.refFrame = undefined` in snapshot-session.ts fails
R7 with "owned by src/daemon/ref-frame.ts"; green once reverted.

Author: thymikee

scripts/layering/daemon-modularity.ts

@@ -21,8 +21,9 @@ export const DAEMON_MODULARITY_BASELINE = {
   sessionState: {
     // R60 moved `audioProbe` to store-owned. R64 does the same for the neutral `perfCapture`
     // and `lastPerfProfile` records after retiring the two platform-specific perf fields.
-    writerOwnedFields: 19,
-    ownerFileClaims: 22,
+    // The ADR 0014 ref frame then collapsed four rows into one owned value (-3 fields, -3 claims).
+    writerOwnedFields: 16,
+    ownerFileClaims: 19,
   },
   largestTypeCycle: {
     zoneMembers: LARGEST_TYPE_CYCLE_ZONE_CEILINGS,

scripts/layering/model.test.ts

@@ -293,79 +293,79 @@ test('SessionState field names come from the declaration, not a hand-kept list',
       "    kind: 'cwd';",
       '    id: string;',
       '  };',
-      '  refFrameState?: RefFrameState;',
+      '  refFrame?: RefFrame;',
       '};',
       '',
       'export type Other = { notAField: string };',
     ].join('\n'),
   );
   // Nested object members are not session fields, and neighbouring types are not scanned.
-  assert.deepEqual(fields, ['name', 'sessionScope', 'refFrameState']);
+  assert.deepEqual(fields, ['name', 'sessionScope', 'refFrame']);
 });
 
 test('session-state writes are found by field, and non-daemon or undeclared names are not', () => {
   const writes = findSessionStateWrites(
     new Map([
-      ['src/daemon/ref-frame.ts', "session.refFrameState = 'active';"],
+      ['src/daemon/ref-frame.ts', "session.refFrame = 'active';"],
       ['src/daemon/session-snapshot.ts', 'session.snapshotGeneration += 1;'],
       // the store owns the record and may write anything on it
-      ['src/daemon/session-store.ts', "session.refFrameState = 'expired';"],
+      ['src/daemon/session-store.ts', "session.refFrame = 'expired';"],
       // a runner session outside the daemon is a different type that happens to share a name
-      ['src/platforms/apple/runner-session.ts', 'session.refFrameState = 1;'],
+      ['src/platforms/apple/runner-session.ts', 'session.refFrame = 1;'],
       // a local that is not a declared SessionState field
       ['src/daemon/session-observability/internal/session-audio.ts', 'session.somethingElse = 1;'],
       // reads and comparisons are not writes
       [
         'src/daemon/interaction/internal/find.ts',
-        "if (session.refFrameState === 'active') return;",
+        "if (session.refFrame === 'active') return;",
       ],
       // a write into a sub-object is not a write to the field itself
-      ['src/daemon/handlers/session-probe.ts', 'session.refFrameState.inner = 1;'],
+      ['src/daemon/handlers/session-probe.ts', 'session.refFrame.inner = 1;'],
       // a different binding that happens to have a matching property
       [
         'src/daemon/session-lifecycle/internal/session-close.ts',
-        "other.refFrameState = 'expired';",
+        "other.refFrame = 'expired';",
       ],
     ]),
-    ['refFrameState', 'snapshotGeneration'],
+    ['refFrame', 'snapshotGeneration'],
   );
 
   assert.deepEqual(
     writes.map(({ file, field }) => `${file}:${field}`),
-    ['src/daemon/ref-frame.ts:refFrameState', 'src/daemon/session-snapshot.ts:snapshotGeneration'],
+    ['src/daemon/ref-frame.ts:refFrame', 'src/daemon/session-snapshot.ts:snapshotGeneration'],
   );
 });
 
 test('every assignment form is a write, including the ones a regex forgets', () => {
   // A line-based matcher has to enumerate operators, and the ones it misses are the natural
   // ways to write these: `??=` for a default on an optional field, `||=`/`&&=` for a flag.
   const forms = [
-    'session.refFrameState = 1;',
-    'session.refFrameState ??= 1;',
-    'session.refFrameState ||= 1;',
-    'session.refFrameState &&= 1;',
-    'session.refFrameState += 1;',
-    'session.refFrameState -= 1;',
-    'session.refFrameState++;',
-    '--session.refFrameState;',
-    'session\n  .refFrameState = 1;',
+    'session.refFrame = 1;',
+    'session.refFrame ??= 1;',
+    'session.refFrame ||= 1;',
+    'session.refFrame &&= 1;',
+    'session.refFrame += 1;',
+    'session.refFrame -= 1;',
+    'session.refFrame++;',
+    '--session.refFrame;',
+    'session\n  .refFrame = 1;',
   ];
   for (const form of forms) {
     const writes = findSessionStateWrites(new Map([['src/daemon/probe.ts', form]]), [
-      'refFrameState',
+      'refFrame',
     ]);
     assert.deepEqual(
       writes.map(({ field }) => field),
-      ['refFrameState'],
+      ['refFrame'],
       `expected ${JSON.stringify(form)} to count as a write`,
     );
   }
 });
 
 test('a computed session write is reported rather than silently unattributed', () => {
   const writes = findSessionStateWrites(
-    new Map([['src/daemon/probe.ts', 'session[key] = 1;\nsession[`refFrameState`] = 2;']]),
-    ['refFrameState'],
+    new Map([['src/daemon/probe.ts', 'session[key] = 1;\nsession[`refFrame`] = 2;']]),
+    ['refFrame'],
   );
   // `[computed]` has no entry in SESSION_STATE_FIELD_OWNERS, so R7 fails on it by
   // construction — a computed write can never pass as an owned one.
@@ -401,19 +401,19 @@ test('a session write counts through an aliased binding, not only one named `ses
         'src/daemon/probe.ts',
         [
           'nextSession.snapshotGeneration = 3;',
-          'preEntrySession.refFrameState = "active";',
+          'preEntrySession.refFrame = "active";',
           'completedSession.saveScriptComplete = true;',
           // Not a session binding, and not a session write.
           'result.snapshotGeneration = 9;',
-          'flags.refFrameState = "x";',
+          'flags.refFrame = "x";',
         ].join('\n'),
       ],
     ]),
-    ['snapshotGeneration', 'refFrameState', 'saveScriptComplete'],
+    ['snapshotGeneration', 'refFrame', 'saveScriptComplete'],
   );
   assert.deepEqual(
     writes.map(({ field, line }) => `${line}:${field}`),
-    ['1:snapshotGeneration', '2:refFrameState', '3:saveScriptComplete'],
+    ['1:snapshotGeneration', '2:refFrame', '3:saveScriptComplete'],
   );
 });
 

scripts/layering/session-state.ts

@@ -25,8 +25,10 @@
 // the set of writers that exist, so the gate's job is to stop the set from growing quietly.
 // Adding a field to `SessionState` forces a deliberate owner; writing an existing field from
 // a new module fails until that module is either declared an owner or, better, calls the
-// owner instead. ADR 0014's ref frame is the worked example — its four fields moved together
-// across two modules until `activateRefFrame` took the transition.
+// owner instead. ADR 0014's ref frame is the worked example, and the one that has since been
+// taken further than this table can go: its four fields moved together across two modules
+// until `activateRefFrame` took the transition, and they are now a single value whose nominal
+// type no other module can construct, edit, or derive from an existing frame.
 //
 // Detection is AST-based (`oxc-parser`, already a devDependency) rather than a line regex. A
 // regex has to enumerate assignment operators, and the ones it forgets are exactly the ones
@@ -49,12 +51,13 @@ export type SessionStateWrite = {
  * owner list has one entry is a field only that module can get wrong.
  */
 export const SESSION_STATE_FIELD_OWNERS: Readonly<Record<string, readonly string[]>> = {
-  // ADR 0014 ref frame: the four frame fields move together or the frame is incoherent, so
-  // both issuance forms go through ref-frame.ts.
-  refFrameState: ['src/daemon/ref-frame.ts'],
-  refFrameScope: ['src/daemon/ref-frame.ts'],
-  refFrameTree: ['src/daemon/ref-frame.ts'],
-  refFrameGeneration: ['src/daemon/ref-frame.ts'],
+  // ADR 0014 ref frame. The four frame fields this row replaced moved together or the frame was
+  // incoherent, and only this table said so; `RefFrame` is now a nominal type (`#`-private
+  // fields) that no other module can construct, edit, or spread into a new frame, and the
+  // transitions replace it whole. The row stays because the type cannot judge a whole frame
+  // moved unchanged: assigning `undefined` (a reset to the pristine frame) and assigning a
+  // frame read off another session.
+  refFrame: ['src/daemon/ref-frame.ts'],
   // Scoped-snapshot lineage is cleared at two distinct events: crossing a device side-effect
   // seam (ref-frame.ts) and replacing the stored observation (session-snapshot.ts).
   snapshotScopeSource: ['src/daemon/ref-frame.ts', 'src/daemon/session-snapshot.ts'],