@immediately-run/sandbox-protocol 0.1.0 → 0.3.0

package/README.md

@@ -56,11 +56,26 @@ are already published. Add; never rename in place.
 
 ## Divergences
 
-A few names still mean different things on the two sides — recorded, not hidden. Each
-carries `divergent: true` and a note explaining the disagreement; the tests here fail a
-marker without a note, and fail a divergence marked on only one side. **R3-274e**
-resolves them and clears the markers, so *zero* markers is the goal state rather than
-the normal one.
+**There are none. R3-274e (0.2.0) resolved the last three**, and a test asserts the
+count is zero — so a marker reappearing is a failure, not a normal state.
+
+The mechanism stays, because the next one will be found the same way. A name whose two
+sides disagree carries `divergent: true` plus a note explaining the disagreement; the
+tests here fail a marker without a note, and fail a divergence marked on only one side.
+Mark it, file the item, resolve it — do not fix it silently in one side's source, which
+is how the three below got there.
+
+What 0.2.0 decided, in one line each (the reasoning is in
+`PLATFORM_LAYERING_SPEC` §6):
+
+| name | was | resolution |
+|---|---|---|
+| `sdk-handshake` | two producers declaring two payloads under one name | the **union**, every field optional — each producer populates what it owns |
+| `editor-context` | the frame declared 2 of the host's 4 fields | the frame's declaration catches up; what it *caches* stays a subset |
+| `fs-change` | neither side declared a type; one read `paths`, the other `paths`+`epoch` | both declare `{paths, epoch}`; `epoch` is kept (apps read it) |
+
+All three are **declaration** changes. No side sends a different byte than it sent
+before — which is what made them resolvable without a compatibility window.
 
 ## Publishing
 

package/dist/fixtures.d.ts

@@ -0,0 +1,40 @@
+/** The shape grammar a snapshot channel is written in (mirrors `WireShape`). */
+interface Shape {
+    fields?: Field[];
+    union?: Shape[];
+    array?: Shape;
+    tuple?: Shape[];
+    type?: string;
+    reads?: string[];
+}
+interface Field {
+    name: string;
+    optional: boolean;
+    type?: string;
+    union?: Shape[];
+    array?: Shape;
+    tuple?: Shape[];
+    fields?: Field[];
+}
+/**
+ * A sample message for every wire name R3-274e resolved.
+ *
+ * Values are deliberately DISTINGUISHABLE — no empty arrays, no all-null unions, no
+ * two fields sharing a value — so a parser that drops, reorders or conflates a field
+ * produces a visibly different result instead of an accidentally-equal one. Both legs
+ * of every nullable union are exercised across the set (`activeFile` a string,
+ * `viewedFile` null).
+ */
+export declare const WIRE_FIXTURES: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+/** The wire names `WIRE_FIXTURES` covers. */
+export declare const FIXTURE_NAMES: readonly string[];
+/**
+ * Validate `value` against a snapshot `Shape`, returning one message per problem
+ * (empty = conformant). Exported so BOTH consuming repos check the fixture with the
+ * same code — a per-repo validator would be one more thing that can agree by accident.
+ *
+ * Deliberately strict about EXTRA fields: a fixture carrying a key the side does not
+ * declare is exactly the drift this is here to catch.
+ */
+export declare function shapeProblems(shape: Shape, value: unknown, path?: string): string[];
+export {};

package/dist/fixtures.js

@@ -0,0 +1,144 @@
+"use strict";
+// One sample message per resolved wire name — the cross-side proof for R3-274e1.
+//
+// R3-274e resolved three names whose two sides had been declaring different shapes
+// under one name (`fs-change`, `editor-context`, `sdk-handshake`; the decisions are in
+// PLATFORM_LAYERING_SPEC §6). Each side's `protocol:check` compares that side's source
+// against its own snapshot — which proves each side matches the CONTRACT, and proves
+// nothing about the two sides matching EACH OTHER. Two snapshots projected from one
+// descriptor set will agree by construction until someone edits the descriptors, and
+// then they will disagree quietly, because nothing reads both.
+//
+// This module is the thing that reads both. It carries ONE sample per name, and this
+// package's own test validates each sample against BOTH sides' declared shapes at once
+// (`fixtures.test.ts`). The consuming repos then drive the SAME object through their
+// real parsers. That is what makes deleting a field from a fixture below fail on both
+// sides rather than one:
+//
+//   epoch removed from `fs-change`  →  sandbox: payload.fields requires it
+//                                  →  sdk:     value.fields requires it, and
+//                                              payload.reads names it
+//
+// Put a fixture here, never in a consuming repo. A per-repo fixture re-creates exactly
+// the "two shapes, one name" condition R3-274e closed — this time in the test data.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIXTURE_NAMES = exports.WIRE_FIXTURES = void 0;
+exports.shapeProblems = shapeProblems;
+/**
+ * A sample message for every wire name R3-274e resolved.
+ *
+ * Values are deliberately DISTINGUISHABLE — no empty arrays, no all-null unions, no
+ * two fields sharing a value — so a parser that drops, reorders or conflates a field
+ * produces a visibly different result instead of an accidentally-equal one. Both legs
+ * of every nullable union are exercised across the set (`activeFile` a string,
+ * `viewedFile` null).
+ */
+exports.WIRE_FIXTURES = Object.freeze({
+    // `{paths, epoch}` — both sides declare both fields. The frame reads only `paths`
+    // (it recompiles on every batch); the SDK's consumers read `epoch` as an ordering
+    // token. Keeping `epoch` was the resolution: apps read it.
+    'fs-change': Object.freeze({
+        epoch: 7,
+        paths: Object.freeze(['/app/src/App.tsx', '/app/content/home.mdx']),
+    }),
+    // The frame's declaration caught up to the host's four fields. What each side
+    // CACHES stays a subset; what travels is all four.
+    'editor-context': Object.freeze({
+        activeFile: '/app/src/App.tsx',
+        dirtyPaths: Object.freeze(['/app/src/App.tsx']),
+        openFiles: Object.freeze(['/app/src/App.tsx', '/app/src/main.tsx']),
+        viewedFile: null,
+    }),
+    // Two legitimate producers, each populating what it owns — hence the union with
+    // every field optional. The fixture populates ALL of them on purpose: a sample
+    // that omitted a field could not detect a side that stopped declaring it.
+    'sdk-handshake': Object.freeze({
+        protocolVersion: '1',
+        sandboxProtocolVersion: '2',
+        sdkVersion: '0.44.0',
+    }),
+});
+/** The wire names `WIRE_FIXTURES` covers. */
+exports.FIXTURE_NAMES = Object.freeze(Object.keys(exports.WIRE_FIXTURES));
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const primitiveMatches = (type, v) => {
+    switch (type) {
+        case 'string':
+            return typeof v === 'string';
+        case 'number':
+            return typeof v === 'number';
+        case 'boolean':
+            return typeof v === 'boolean';
+        case 'null':
+            return v === null;
+        case 'undefined':
+            return v === undefined;
+        default:
+            // A named type (`FsChange`, `EditorContext`) carries no structure here — the
+            // sibling `fields` does. Unknown type text is NOT a failure, or every named
+            // type would have to be duplicated in this file.
+            return true;
+    }
+};
+/**
+ * Validate `value` against a snapshot `Shape`, returning one message per problem
+ * (empty = conformant). Exported so BOTH consuming repos check the fixture with the
+ * same code — a per-repo validator would be one more thing that can agree by accident.
+ *
+ * Deliberately strict about EXTRA fields: a fixture carrying a key the side does not
+ * declare is exactly the drift this is here to catch.
+ */
+function shapeProblems(shape, value, path = '$') {
+    const problems = [];
+    if (shape.union) {
+        const ok = shape.union.some((m) => shapeProblems(m, value, path).length === 0);
+        if (!ok)
+            problems.push(`${path}: matches no member of the declared union`);
+        return problems;
+    }
+    if (shape.array) {
+        if (!Array.isArray(value)) {
+            problems.push(`${path}: declared an array, got ${typeof value}`);
+            return problems;
+        }
+        value.forEach((el, i) => problems.push(...shapeProblems(shape.array, el, `${path}[${i}]`)));
+        return problems;
+    }
+    if (shape.tuple) {
+        if (!Array.isArray(value)) {
+            problems.push(`${path}: declared a tuple, got ${typeof value}`);
+            return problems;
+        }
+        if (value.length !== shape.tuple.length) {
+            problems.push(`${path}: tuple declares ${shape.tuple.length} slot(s), got ${value.length}`);
+            return problems;
+        }
+        shape.tuple.forEach((m, i) => problems.push(...shapeProblems(m, value[i], `${path}[${i}]`)));
+        return problems;
+    }
+    if (shape.fields) {
+        if (!isRecord(value)) {
+            problems.push(`${path}: declared an object, got ${Array.isArray(value) ? 'array' : typeof value}`);
+            return problems;
+        }
+        for (const f of shape.fields) {
+            const present = Object.prototype.hasOwnProperty.call(value, f.name);
+            if (!present) {
+                if (!f.optional)
+                    problems.push(`${path}.${f.name}: required by the declaration, absent`);
+                continue;
+            }
+            problems.push(...shapeProblems(f, value[f.name], `${path}.${f.name}`));
+        }
+        const declared = new Set(shape.fields.map((f) => f.name));
+        for (const k of Object.keys(value)) {
+            if (!declared.has(k))
+                problems.push(`${path}.${k}: present but not declared`);
+        }
+        return problems;
+    }
+    if (shape.type && !primitiveMatches(shape.type, value)) {
+        problems.push(`${path}: declared \`${shape.type}\`, got ${value === null ? 'null' : typeof value}`);
+    }
+    return problems;
+}

package/dist/sandbox.d.ts

@@ -41,11 +41,13 @@ export declare const DONE = "done";
 export interface DonePayload {
     compilatonError: boolean;
 }
-/** `editor-context` — push · host->app. polled with `request-editor-context`. DIVERGENT (R3-274e): declared-incomplete — the host (site-main channelBridge.ts) sends {dirtyPaths, openFiles, activeFile, viewedFile}; this side declares only {dirtyPaths, activeFile?} while the SDK reads all four. `viewedFile` (R3-268) and `openFiles` never entered this declaration. R3-274e picks one shape for both sides.. */
+/** `editor-context` — push · host->app. polled with `request-editor-context`. */
 export declare const EDITOR_CONTEXT = "editor-context";
 export interface EditorContextPayload {
-    activeFile?: null | string | undefined;
+    activeFile: null | string;
     dirtyPaths: Array<string>;
+    openFiles: Array<string>;
+    viewedFile: null | string;
 }
 /** `evaluate` — message · host->app. */
 export declare const EVALUATE = "evaluate";
@@ -53,9 +55,12 @@ export declare const EVALUATE = "evaluate";
 /** `form-factor` — push · host->app. polled with `request-form-factor`. */
 export declare const FORM_FACTOR = "form-factor";
 /** Read off this message today: `formFactor`. */
-/** `fs-change` — message · host->app. DIVERGENT (R3-274e): subset-reads with no declared owner on either side — the host sends {paths, epoch}; this side reads only `paths`, the SDK reads both. Nothing forces the two to agree, which is the divergence PLATFORM_LAYERING_SPEC §2 names as the exemplar. The `kind` also differs (message here, push channel in the SDK). R3-274e decides: keep `epoch` or drop it.. */
+/** `fs-change` — message · host->app. */
 export declare const FS_CHANGE = "fs-change";
-/** Read off this message today: `paths`. */
+export interface FsChangePayload {
+    epoch: number;
+    paths: Array<string>;
+}
 /** `initialized` — message · app->host. */
 export declare const INITIALIZED = "initialized";
 /** `ir-marker` — message · app->host. */
@@ -102,11 +107,12 @@ export declare const RESIZE = "resize";
 export interface ResizePayload {
     height: number;
 }
-/** `sdk-handshake` — message · app->host. DIVERGENT (R3-274e): divergent-declared — TWO producers of one name with different payloads: this frame announces {protocolVersion, sandboxProtocolVersion}, the SDK announces {protocolVersion, sdkVersion}. R3-274d gave the frame its own SANDBOX_PROTOCOL_VERSION (announced additively; the host logs it, fail-open) and retired the sibling-checkout read that used to source `protocolVersion`. R3-274e picks one shape.. */
+/** `sdk-handshake` — message · app->host. */
 export declare const SDK_HANDSHAKE = "sdk-handshake";
 export interface SdkHandshakePayload {
-    protocolVersion: string;
-    sandboxProtocolVersion: string;
+    protocolVersion?: string | undefined;
+    sandboxProtocolVersion?: string | undefined;
+    sdkVersion?: string | undefined;
 }
 /** `start` — message · app->host. */
 export declare const START = "start";

package/dist/sandbox.js

@@ -1,7 +1,7 @@
 "use strict";
 // GENERATED by scripts/generate.mjs — DO NOT EDIT.
 // Source of truth: src/descriptors.protocol.mjs (@immediately-run/sandbox-protocol)
-// descriptorsHash: fbd9b76f9e8edc71
+// descriptorsHash: 235f4011d391bd63
 //
 // The sandbox↔SDK wire vocabulary (PLATFORM_LAYERING_SPEC §2 / S1). Import the
 // constants instead of writing the string: a rename then has ONE edit site and
@@ -23,7 +23,7 @@ exports.AUTH_STATE = 'auth-state';
 exports.CONSOLE = 'console';
 /** `done` — message · app->host. */
 exports.DONE = 'done';
-/** `editor-context` — push · host->app. polled with `request-editor-context`. DIVERGENT (R3-274e): declared-incomplete — the host (site-main channelBridge.ts) sends {dirtyPaths, openFiles, activeFile, viewedFile}; this side declares only {dirtyPaths, activeFile?} while the SDK reads all four. `viewedFile` (R3-268) and `openFiles` never entered this declaration. R3-274e picks one shape for both sides.. */
+/** `editor-context` — push · host->app. polled with `request-editor-context`. */
 exports.EDITOR_CONTEXT = 'editor-context';
 /** `evaluate` — message · host->app. */
 exports.EVALUATE = 'evaluate';
@@ -31,9 +31,8 @@ exports.EVALUATE = 'evaluate';
 /** `form-factor` — push · host->app. polled with `request-form-factor`. */
 exports.FORM_FACTOR = 'form-factor';
 /** Read off this message today: `formFactor`. */
-/** `fs-change` — message · host->app. DIVERGENT (R3-274e): subset-reads with no declared owner on either side — the host sends {paths, epoch}; this side reads only `paths`, the SDK reads both. Nothing forces the two to agree, which is the divergence PLATFORM_LAYERING_SPEC §2 names as the exemplar. The `kind` also differs (message here, push channel in the SDK). R3-274e decides: keep `epoch` or drop it.. */
+/** `fs-change` — message · host->app. */
 exports.FS_CHANGE = 'fs-change';
-/** Read off this message today: `paths`. */
 /** `initialized` — message · app->host. */
 exports.INITIALIZED = 'initialized';
 /** `ir-marker` — message · app->host. */
@@ -72,7 +71,7 @@ exports.REQUEST_THEME = 'request-theme';
 exports.REQUEST_VCS_STATE = 'request-vcs-state';
 /** `resize` — message · app->host. */
 exports.RESIZE = 'resize';
-/** `sdk-handshake` — message · app->host. DIVERGENT (R3-274e): divergent-declared — TWO producers of one name with different payloads: this frame announces {protocolVersion, sandboxProtocolVersion}, the SDK announces {protocolVersion, sdkVersion}. R3-274d gave the frame its own SANDBOX_PROTOCOL_VERSION (announced additively; the host logs it, fail-open) and retired the sibling-checkout read that used to source `protocolVersion`. R3-274e picks one shape.. */
+/** `sdk-handshake` — message · app->host. */
 exports.SDK_HANDSHAKE = 'sdk-handshake';
 /** `start` — message · app->host. */
 exports.START = 'start';

package/dist/sdk.d.ts

@@ -54,13 +54,13 @@ export interface DroppedItemPayload {
         y: number;
     };
 }
-/** `editor-context` — push · host->app. polled with `request-editor-context`. DIVERGENT (R3-274e): declared-incomplete — the host (site-main channelBridge.ts) sends {dirtyPaths, openFiles, activeFile, viewedFile}; this side declares only {dirtyPaths, activeFile?} while the SDK reads all four. `viewedFile` (R3-268) and `openFiles` never entered this declaration. R3-274e picks one shape for both sides.. */
+/** `editor-context` — push · host->app. polled with `request-editor-context`. */
 export declare const EDITOR_CONTEXT = "editor-context";
 /** Read off this message today: `activeFile`, `dirtyPaths`, `openFiles`, `viewedFile`. */
 /** `form-factor` — push · host->app. polled with `request-form-factor`. */
 export declare const FORM_FACTOR = "form-factor";
 /** Read off this message today: `formFactor`. */
-/** `fs-change` — push · host->app. DIVERGENT (R3-274e): subset-reads with no declared owner on either side — the host sends {paths, epoch}; this side reads only `paths`, the SDK reads both. Nothing forces the two to agree, which is the divergence PLATFORM_LAYERING_SPEC §2 names as the exemplar. The `kind` also differs (message here, push channel in the SDK). R3-274e decides: keep `epoch` or drop it.. */
+/** `fs-change` — push · host->app. */
 export declare const FS_CHANGE = "fs-change";
 /** Read off this message today: `epoch`, `paths`. */
 /** `invitations` — push · host->app. polled with `request-invitations`. */
@@ -283,11 +283,12 @@ export declare const REQUEST_SESSION_MOUNTS = "request-session-mounts";
 export declare const REQUEST_THEME = "request-theme";
 /** `request-vcs-state` — poll · app->host. */
 export declare const REQUEST_VCS_STATE = "request-vcs-state";
-/** `sdk-handshake` — message · app->host. DIVERGENT (R3-274e): divergent-declared — TWO producers of one name with different payloads: this frame announces {protocolVersion, sandboxProtocolVersion}, the SDK announces {protocolVersion, sdkVersion}. R3-274d gave the frame its own SANDBOX_PROTOCOL_VERSION (announced additively; the host logs it, fail-open) and retired the sibling-checkout read that used to source `protocolVersion`. R3-274e picks one shape.. */
+/** `sdk-handshake` — message · app->host. */
 export declare const SDK_HANDSHAKE = "sdk-handshake";
 export interface SdkHandshakePayload {
-    protocolVersion: string;
-    sdkVersion: string;
+    protocolVersion?: string | undefined;
+    sandboxProtocolVersion?: string | undefined;
+    sdkVersion?: string | undefined;
 }
 /** `secrets-metadata` — push · host->app. polled with `request-secrets-metadata`. */
 export declare const SECRETS_METADATA = "secrets-metadata";

package/dist/sdk.js

@@ -1,7 +1,7 @@
 "use strict";
 // GENERATED by scripts/generate.mjs — DO NOT EDIT.
 // Source of truth: src/descriptors.protocol.mjs (@immediately-run/sandbox-protocol)
-// descriptorsHash: fbd9b76f9e8edc71
+// descriptorsHash: 235f4011d391bd63
 //
 // The sandbox↔SDK wire vocabulary (PLATFORM_LAYERING_SPEC §2 / S1). Import the
 // constants instead of writing the string: a rename then has ONE edit site and
@@ -35,13 +35,13 @@ exports.DIAGNOSTICS = 'diagnostics';
 exports.DND_CANCEL = 'dnd-cancel';
 /** `dropped-item` — message · host->app. */
 exports.DROPPED_ITEM = 'dropped-item';
-/** `editor-context` — push · host->app. polled with `request-editor-context`. DIVERGENT (R3-274e): declared-incomplete — the host (site-main channelBridge.ts) sends {dirtyPaths, openFiles, activeFile, viewedFile}; this side declares only {dirtyPaths, activeFile?} while the SDK reads all four. `viewedFile` (R3-268) and `openFiles` never entered this declaration. R3-274e picks one shape for both sides.. */
+/** `editor-context` — push · host->app. polled with `request-editor-context`. */
 exports.EDITOR_CONTEXT = 'editor-context';
 /** Read off this message today: `activeFile`, `dirtyPaths`, `openFiles`, `viewedFile`. */
 /** `form-factor` — push · host->app. polled with `request-form-factor`. */
 exports.FORM_FACTOR = 'form-factor';
 /** Read off this message today: `formFactor`. */
-/** `fs-change` — push · host->app. DIVERGENT (R3-274e): subset-reads with no declared owner on either side — the host sends {paths, epoch}; this side reads only `paths`, the SDK reads both. Nothing forces the two to agree, which is the divergence PLATFORM_LAYERING_SPEC §2 names as the exemplar. The `kind` also differs (message here, push channel in the SDK). R3-274e decides: keep `epoch` or drop it.. */
+/** `fs-change` — push · host->app. */
 exports.FS_CHANGE = 'fs-change';
 /** Read off this message today: `epoch`, `paths`. */
 /** `invitations` — push · host->app. polled with `request-invitations`. */
@@ -118,7 +118,7 @@ exports.REQUEST_SESSION_MOUNTS = 'request-session-mounts';
 exports.REQUEST_THEME = 'request-theme';
 /** `request-vcs-state` — poll · app->host. */
 exports.REQUEST_VCS_STATE = 'request-vcs-state';
-/** `sdk-handshake` — message · app->host. DIVERGENT (R3-274e): divergent-declared — TWO producers of one name with different payloads: this frame announces {protocolVersion, sandboxProtocolVersion}, the SDK announces {protocolVersion, sdkVersion}. R3-274d gave the frame its own SANDBOX_PROTOCOL_VERSION (announced additively; the host logs it, fail-open) and retired the sibling-checkout read that used to source `protocolVersion`. R3-274e picks one shape.. */
+/** `sdk-handshake` — message · app->host. */
 exports.SDK_HANDSHAKE = 'sdk-handshake';
 /** `secrets-metadata` — push · host->app. polled with `request-secrets-metadata`. */
 exports.SECRETS_METADATA = 'secrets-metadata';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/sandbox-protocol",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "The sandbox<->SDK wire protocol: ONE descriptor set, projected into the wire-name constants, the payload types, and the per-side snapshots both repos gate against (PLATFORM_LAYERING_SPEC S1). Consumed by sandbox and immediately-run-sdk so a wire change is a version bump, not a hand-copied file.",
   "license": "UNLICENSED",
   "repository": {
@@ -23,6 +23,10 @@
       "types": "./dist/sdk.d.ts",
       "default": "./dist/sdk.js"
     },
+    "./fixtures": {
+      "types": "./dist/fixtures.d.ts",
+      "default": "./dist/fixtures.js"
+    },
     "./snapshots/sandbox": "./snapshots/sandbox.json",
     "./snapshots/sdk": "./snapshots/sdk.json",
     "./package.json": "./package.json"

package/snapshots/sandbox.json

@@ -190,16 +190,13 @@
         "fields": [
           {
             "name": "activeFile",
-            "optional": true,
+            "optional": false,
             "union": [
               {
                 "type": "null"
               },
               {
                 "type": "string"
-              },
-              {
-                "type": "undefined"
               }
             ]
           },
@@ -209,6 +206,25 @@
             "array": {
               "type": "string"
             }
+          },
+          {
+            "name": "openFiles",
+            "optional": false,
+            "array": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "viewedFile",
+            "optional": false,
+            "union": [
+              {
+                "type": "null"
+              },
+              {
+                "type": "string"
+              }
+            ]
           }
         ],
         "reads": [
@@ -219,9 +235,7 @@
       "sites": [
         "src/editor/EditorContextService.ts",
         "src/editor/editorContextState.ts"
-      ],
-      "divergent": true,
-      "divergentNote": "declared-incomplete — the host (site-main channelBridge.ts) sends {dirtyPaths, openFiles, activeFile, viewedFile}; this side declares only {dirtyPaths, activeFile?} while the SDK reads all four. `viewedFile` (R3-268) and `openFiles` never entered this declaration. R3-274e picks one shape for both sides."
+      ]
     },
     "evaluate": {
       "kind": "message",
@@ -252,15 +266,28 @@
       "kind": "message",
       "direction": "host->app",
       "payload": {
+        "fields": [
+          {
+            "name": "epoch",
+            "optional": false,
+            "type": "number"
+          },
+          {
+            "name": "paths",
+            "optional": false,
+            "array": {
+              "type": "string"
+            }
+          }
+        ],
         "reads": [
           "paths"
         ]
       },
       "sites": [
-        "src/index.ts"
-      ],
-      "divergent": true,
-      "divergentNote": "subset-reads with no declared owner on either side — the host sends {paths, epoch}; this side reads only `paths`, the SDK reads both. Nothing forces the two to agree, which is the divergence PLATFORM_LAYERING_SPEC §2 names as the exemplar. The `kind` also differs (message here, push channel in the SDK). R3-274e decides: keep `epoch` or drop it."
+        "src/index.ts",
+        "src/protocol/fsChange.ts"
+      ]
     },
     "initialized": {
       "kind": "message",
@@ -487,21 +514,45 @@
         "fields": [
           {
             "name": "protocolVersion",
-            "optional": false,
-            "type": "string"
+            "optional": true,
+            "union": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "undefined"
+              }
+            ]
           },
           {
             "name": "sandboxProtocolVersion",
-            "optional": false,
-            "type": "string"
+            "optional": true,
+            "union": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "undefined"
+              }
+            ]
+          },
+          {
+            "name": "sdkVersion",
+            "optional": true,
+            "union": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "undefined"
+              }
+            ]
           }
         ]
       },
       "sites": [
         "src/index.ts"
-      ],
-      "divergent": true,
-      "divergentNote": "divergent-declared — TWO producers of one name with different payloads: this frame announces {protocolVersion, sandboxProtocolVersion}, the SDK announces {protocolVersion, sdkVersion}. R3-274d gave the frame its own SANDBOX_PROTOCOL_VERSION (announced additively; the host logs it, fail-open) and retired the sibling-checkout read that used to source `protocolVersion`. R3-274e picks one shape."
+      ]
     },
     "start": {
       "kind": "message",

package/snapshots/sdk.json

@@ -416,9 +416,7 @@
       },
       "sites": [
         "src/editorContext.ts"
-      ],
-      "divergent": true,
-      "divergentNote": "declared-incomplete — the host (site-main channelBridge.ts) sends {dirtyPaths, openFiles, activeFile, viewedFile}; this side declares only {dirtyPaths, activeFile?} while the SDK reads all four. `viewedFile` (R3-268) and `openFiles` never entered this declaration. R3-274e picks one shape for both sides."
+      ]
     },
     "form-factor": {
       "kind": "push",
@@ -503,9 +501,7 @@
       },
       "sites": [
         "src/onFsChange.ts"
-      ],
-      "divergent": true,
-      "divergentNote": "subset-reads with no declared owner on either side — the host sends {paths, epoch}; this side reads only `paths`, the SDK reads both. Nothing forces the two to agree, which is the divergence PLATFORM_LAYERING_SPEC §2 names as the exemplar. The `kind` also differs (message here, push channel in the SDK). R3-274e decides: keep `epoch` or drop it."
+      ]
     },
     "invitations": {
       "kind": "push",
@@ -1715,21 +1711,45 @@
         "fields": [
           {
             "name": "protocolVersion",
-            "optional": false,
-            "type": "string"
+            "optional": true,
+            "union": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "undefined"
+              }
+            ]
+          },
+          {
+            "name": "sandboxProtocolVersion",
+            "optional": true,
+            "union": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "undefined"
+              }
+            ]
           },
           {
             "name": "sdkVersion",
-            "optional": false,
-            "type": "string"
+            "optional": true,
+            "union": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "undefined"
+              }
+            ]
           }
         ]
       },
       "sites": [
         "src/runtime.ts"
-      ],
-      "divergent": true,
-      "divergentNote": "divergent-declared — TWO producers of one name with different payloads: this frame announces {protocolVersion, sandboxProtocolVersion}, the SDK announces {protocolVersion, sdkVersion}. R3-274d gave the frame its own SANDBOX_PROTOCOL_VERSION (announced additively; the host logs it, fail-open) and retired the sibling-checkout read that used to source `protocolVersion`. R3-274e picks one shape."
+      ]
     },
     "secrets-metadata": {
       "kind": "push",