refactor(binary): factor IE canonical-reader/json-snapshot into ie-common

The IE binary formats (ITM, SPL, EFF) carried byte-identical
canonical-reader and json-snapshot scaffolding — `s/itm/spl/eff/`
across three files each. Hand-rolling the same shape per format meant
a bug fix or new envelope field had to be applied three times, with
nothing preventing one format from drifting.

Two new factories under `binary/src/ie-common/`:

- `canonical-reader.ts` produces `getDocument` / `rebuildDocument` /
  `createSnapshot` for any IE format given its (Doc, Snap) zod schema
  pair. Snapshot envelope shape (`schemaVersion: 1`, `format`,
  `formatName`, optional `opaqueRanges` / `warnings`) lives here as
  one definition.

- `json-snapshot.ts` produces `createJson` / `loadJson` with the
  same parser-round-trip discipline (`parseWithSchemaValidation` →
  serialize → reparse → semantic-stringify match). The parser is
  passed as a thunk to break the canonical-layer ↔ parser import
  cycle.

Each format's `<format>/canonical-reader.ts` and
`<format>/json-snapshot.ts` shrink to ~10 LOC of factory invocation
plus the named re-exports (`getItmCanonicalDocument`,
`createCanonicalItmJsonSnapshot`, etc.) that the per-format
adapter / serializer / tests already import.

Writers stay per-format: ITM/SPL share a header+abilities+effects
layout but EFF is a single fixed-size record, so no clean shared
shape exists across all three. format-adapter.ts also stays per
format because each format's `semanticFieldKey` routing differs
structurally (ITM/SPL emit "abilities[]" / "effects[]" segments;
EFF emits "header" / "body").

933 tests pass (no behavior change).

Author: burner1024

binary/src/eff/canonical-reader.ts

@@ -1,55 +1,23 @@
 /**
- * Reader helpers for rebuilding EffCanonicalSnapshot/EffCanonicalDocument
- * from a parsed display tree (ParseResult). The parser stores the canonical
- * doc on `result.document` directly; the rebuild path mirrors the other IE
- * formats and is exercised by the JSON-snapshot reload flow.
+ * EFF canonical-reader: thin wrapper around the IE canonical-reader factory
+ * (`ie-common/canonical-reader.ts`).
  */
 
-import { parseWithSchemaValidation } from "../schema-validation";
+import { createIeCanonicalReader } from "../ie-common/canonical-reader";
 import {
     type EffCanonicalDocument,
     type EffCanonicalSnapshot,
     effCanonicalDocumentSchemaPermissive,
     effCanonicalSnapshotSchemaPermissive,
 } from "./canonical-schemas";
-import type { ParseResult } from "../types";
 
-export function getEffCanonicalDocument(result: ParseResult): EffCanonicalDocument | undefined {
-    if (!result.document) return undefined;
-    return parseWithSchemaValidation(
-        effCanonicalDocumentSchemaPermissive,
-        result.document,
-        "Invalid EFF canonical document",
-    );
-}
+const reader = createIeCanonicalReader<EffCanonicalDocument, EffCanonicalSnapshot>({
+    formatId: "eff",
+    formatLabel: "EFF",
+    documentSchemaPermissive: effCanonicalDocumentSchemaPermissive,
+    snapshotSchemaPermissive: effCanonicalSnapshotSchemaPermissive,
+});
 
-export function rebuildEffCanonicalDocument(result: ParseResult): EffCanonicalDocument {
-    const doc = getEffCanonicalDocument(result);
-    if (!doc) {
-        throw new Error(
-            "EFF canonical document missing from ParseResult; display-tree-only rebuild is not implemented",
-        );
-    }
-    return doc;
-}
-
-export function createEffCanonicalSnapshot(result: ParseResult): EffCanonicalSnapshot {
-    const document = rebuildEffCanonicalDocument(result);
-    const snapshot: EffCanonicalSnapshot = {
-        schemaVersion: 1,
-        format: "eff",
-        formatName: result.formatName,
-        document,
-    };
-    if (result.opaqueRanges && result.opaqueRanges.length > 0) {
-        return parseWithSchemaValidation(
-            effCanonicalSnapshotSchemaPermissive,
-            { ...snapshot, opaqueRanges: result.opaqueRanges },
-            "Invalid EFF canonical snapshot",
-        );
-    }
-    if (result.warnings) {
-        return { ...snapshot, warnings: result.warnings };
-    }
-    return snapshot;
-}
+export const getEffCanonicalDocument = reader.getDocument;
+export const rebuildEffCanonicalDocument = reader.rebuildDocument;
+export const createEffCanonicalSnapshot = reader.createSnapshot;

binary/src/eff/json-snapshot.ts

@@ -1,42 +1,24 @@
+/**
+ * EFF JSON-snapshot: thin wrapper around the IE json-snapshot factory
+ * (`ie-common/json-snapshot.ts`).
+ */
+
 import {
     createEffCanonicalSnapshot,
     effCanonicalSnapshotSchemaPermissive,
     serializeEffCanonicalSnapshot,
     type EffCanonicalSnapshot,
 } from "./canonical";
 import { effParser } from "./index";
-import { parseWithSchemaValidation } from "../schema-validation";
-import type { ParseOptions, ParseResult } from "../types";
-
-interface LoadedCanonicalEffSnapshot {
-    readonly snapshot: EffCanonicalSnapshot;
-    readonly bytes: Uint8Array;
-    readonly parseResult: ParseResult;
-}
-
-export function createCanonicalEffJsonSnapshot(parseResult: ParseResult): string {
-    return `${JSON.stringify(createEffCanonicalSnapshot(parseResult), null, 2)}\n`;
-}
-
-export function loadCanonicalEffJsonSnapshot(
-    jsonText: string,
-    parseOptions?: ParseOptions,
-): LoadedCanonicalEffSnapshot {
-    const snapshot = parseWithSchemaValidation(
-        effCanonicalSnapshotSchemaPermissive,
-        JSON.parse(jsonText),
-        "Invalid canonical EFF snapshot",
-    );
-    const bytes = serializeEffCanonicalSnapshot(snapshot);
-    const reparsed = effParser.parse(bytes, parseOptions);
-    if (reparsed.errors && reparsed.errors.length > 0) {
-        throw new Error(`Canonical EFF snapshot did not round-trip: ${reparsed.errors[0]}`);
-    }
+import { createIeJsonSnapshot } from "../ie-common/json-snapshot";
 
-    const reparsedSnapshot = createEffCanonicalSnapshot(reparsed);
-    if (JSON.stringify(snapshot) !== JSON.stringify(reparsedSnapshot)) {
-        throw new Error("Canonical EFF snapshot did not round-trip semantically");
-    }
+const layer = createIeJsonSnapshot<EffCanonicalSnapshot>({
+    formatLabel: "EFF",
+    snapshotSchemaPermissive: effCanonicalSnapshotSchemaPermissive,
+    createSnapshot: createEffCanonicalSnapshot,
+    serializeSnapshot: serializeEffCanonicalSnapshot,
+    getParser: () => effParser,
+});
 
-    return { snapshot, bytes, parseResult: reparsed };
-}
+export const createCanonicalEffJsonSnapshot = layer.createJson;
+export const loadCanonicalEffJsonSnapshot = layer.loadJson;

binary/src/ie-common/canonical-reader.ts

@@ -0,0 +1,101 @@
+/**
+ * Shared canonical-reader factory for the IE binary formats (ITM, SPL, EFF).
+ *
+ * Each format's `<format>/canonical-reader.ts` calls `createIeCanonicalReader`
+ * to get the three operations every IE format needs:
+ *   - `getDocument(result)`     — pull the canonical doc off `result.document`
+ *                                 with permissive schema validation, undefined
+ *                                 if absent.
+ *   - `rebuildDocument(result)` — same plus a non-null assertion; the parser
+ *                                 always sets `result.document`, so a missing
+ *                                 doc here is a programming error.
+ *   - `createSnapshot(result)`  — wrap the doc in the IE snapshot envelope
+ *                                 (`schemaVersion: 1`, `format`, `formatName`,
+ *                                 optional `opaqueRanges` / `warnings`).
+ *
+ * The body of each operation was byte-identical across the three formats
+ * (`s/itm/spl/eff/`); only the schema types and the format-id discriminant
+ * varied. Hand-rolling the same shape per format guaranteed they'd drift —
+ * one format could grow a snapshot field the others didn't get.
+ */
+
+import { z } from "zod";
+import { parseWithSchemaValidation } from "../schema-validation";
+import type { ParseResult } from "../types";
+
+export type IeFormatId = "itm" | "spl" | "eff";
+
+interface IeSnapshotEnvelope<Doc> {
+    readonly schemaVersion: 1;
+    readonly format: IeFormatId;
+    readonly formatName?: string;
+    readonly document: Doc;
+}
+
+export interface IeCanonicalReaderConfig<Doc, Snap extends IeSnapshotEnvelope<Doc>> {
+    readonly formatId: IeFormatId;
+    /** Display label used in error messages (`"ITM"`, `"SPL"`, `"EFF"`). */
+    readonly formatLabel: string;
+    readonly documentSchemaPermissive: z.ZodType<Doc>;
+    readonly snapshotSchemaPermissive: z.ZodType<Snap>;
+}
+
+export interface IeCanonicalReader<Doc, Snap extends IeSnapshotEnvelope<Doc>> {
+    readonly getDocument: (result: ParseResult) => Doc | undefined;
+    readonly rebuildDocument: (result: ParseResult) => Doc;
+    readonly createSnapshot: (result: ParseResult) => Snap;
+}
+
+export function createIeCanonicalReader<Doc, Snap extends IeSnapshotEnvelope<Doc>>(
+    config: IeCanonicalReaderConfig<Doc, Snap>,
+): IeCanonicalReader<Doc, Snap> {
+    const { formatId, formatLabel, documentSchemaPermissive, snapshotSchemaPermissive } = config;
+
+    const getDocument = (result: ParseResult): Doc | undefined => {
+        if (!result.document) return undefined;
+        return parseWithSchemaValidation(
+            documentSchemaPermissive,
+            result.document,
+            `Invalid ${formatLabel} canonical document`,
+        );
+    };
+
+    const rebuildDocument = (result: ParseResult): Doc => {
+        const doc = getDocument(result);
+        if (!doc) {
+            throw new Error(
+                `${formatLabel} canonical document missing from ParseResult; display-tree-only rebuild is not implemented`,
+            );
+        }
+        return doc;
+    };
+
+    const createSnapshot = (result: ParseResult): Snap => {
+        const document = rebuildDocument(result);
+        // Build the wire-shape envelope every IE snapshot has, then promote
+        // through the snapshot zod for variants that carry `opaqueRanges`
+        // (validates the shape) or attach `warnings` directly. The cast is
+        // safe by construction: Snap extends IeSnapshotEnvelope<Doc>, and
+        // we only ever produce the union of {base, base+opaqueRanges,
+        // base+warnings} which the per-format snapshot schema enumerates.
+        const envelope: IeSnapshotEnvelope<Doc> = {
+            schemaVersion: 1,
+            format: formatId,
+            formatName: result.formatName,
+            document,
+        };
+        if (result.opaqueRanges && result.opaqueRanges.length > 0) {
+            return parseWithSchemaValidation(
+                snapshotSchemaPermissive,
+                { ...envelope, opaqueRanges: result.opaqueRanges },
+                `Invalid ${formatLabel} canonical snapshot`,
+            );
+        }
+        if (result.warnings) {
+            return { ...envelope, warnings: result.warnings } as unknown as Snap;
+        }
+        return envelope as unknown as Snap;
+    };
+
+    return { getDocument, rebuildDocument, createSnapshot };
+}

binary/src/ie-common/json-snapshot.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared JSON-snapshot factory for the IE binary formats (ITM, SPL, EFF).
+ *
+ * Each format's `<format>/json-snapshot.ts` calls `createIeJsonSnapshot` to
+ * get a serialise/load pair that follows the same round-trip discipline:
+ *   - `createJson(result)`     — JSON.stringify the canonical snapshot.
+ *   - `loadJson(text, opts)`   — parse the JSON, validate against the
+ *                                permissive snapshot schema, serialise to
+ *                                bytes, re-parse, and assert the re-parsed
+ *                                snapshot stringifies identically. The
+ *                                parser is provided as a thunk so per-format
+ *                                callers can avoid the canonical layer →
+ *                                parser → canonical layer import cycle.
+ *
+ * Failure-mode design: load throws on either parser-level errors or a
+ * semantic round-trip mismatch. Both indicate a hand-edited snapshot whose
+ * bytes don't reflect the doc shape (or a parser bug); the caller doesn't
+ * silently get an out-of-sync result.
+ */
+
+import { z } from "zod";
+import { parseWithSchemaValidation } from "../schema-validation";
+import type { BinaryParser, ParseOptions, ParseResult } from "../types";
+
+export interface IeJsonSnapshotConfig<Snap> {
+    readonly formatLabel: string;
+    readonly snapshotSchemaPermissive: z.ZodType<Snap>;
+    readonly createSnapshot: (result: ParseResult) => Snap;
+    readonly serializeSnapshot: (snapshot: Snap) => Uint8Array;
+    /**
+     * Lazy parser accessor — the parser usually transitively imports the
+     * canonical layer, so resolving it eagerly here would create a cycle.
+     * The thunk is invoked on first load.
+     */
+    readonly getParser: () => BinaryParser;
+}
+
+export interface IeLoadedJsonSnapshot<Snap> {
+    readonly snapshot: Snap;
+    readonly bytes: Uint8Array;
+    readonly parseResult: ParseResult;
+}
+
+export interface IeJsonSnapshot<Snap> {
+    readonly createJson: (result: ParseResult) => string;
+    readonly loadJson: (jsonText: string, parseOptions?: ParseOptions) => IeLoadedJsonSnapshot<Snap>;
+}
+
+export function createIeJsonSnapshot<Snap>(config: IeJsonSnapshotConfig<Snap>): IeJsonSnapshot<Snap> {
+    const { formatLabel, snapshotSchemaPermissive, createSnapshot, serializeSnapshot, getParser } = config;
+
+    const createJson = (result: ParseResult): string => {
+        return `${JSON.stringify(createSnapshot(result), null, 2)}\n`;
+    };
+
+    const loadJson = (jsonText: string, parseOptions?: ParseOptions): IeLoadedJsonSnapshot<Snap> => {
+        const snapshot = parseWithSchemaValidation(
+            snapshotSchemaPermissive,
+            JSON.parse(jsonText),
+            `Invalid canonical ${formatLabel} snapshot`,
+        );
+        const bytes = serializeSnapshot(snapshot);
+        const reparsed = getParser().parse(bytes, parseOptions);
+        if (reparsed.errors && reparsed.errors.length > 0) {
+            throw new Error(`Canonical ${formatLabel} snapshot did not round-trip: ${reparsed.errors[0]}`);
+        }
+        const reparsedSnapshot = createSnapshot(reparsed);
+        if (JSON.stringify(snapshot) !== JSON.stringify(reparsedSnapshot)) {
+            throw new Error(`Canonical ${formatLabel} snapshot did not round-trip semantically`);
+        }
+        return { snapshot, bytes, parseResult: reparsed };
+    };
+
+    return { createJson, loadJson };
+}

binary/src/itm/canonical-reader.ts

@@ -1,58 +1,24 @@
 /**
- * Reader helpers for rebuilding ItmCanonicalSnapshot/ItmCanonicalDocument
- * from a parsed display tree (ParseResult). The parser stores the canonical
- * doc on `result.document` directly; the rebuild path mirrors PRO/MAP and
- * is exercised by the JSON-snapshot reload flow.
+ * ITM canonical-reader: thin wrapper around the IE canonical-reader factory
+ * (`ie-common/canonical-reader.ts`). The factory body documents the shared
+ * shape; this file only supplies ITM's schemas and format discriminants.
  */
 
-import { parseWithSchemaValidation } from "../schema-validation";
+import { createIeCanonicalReader } from "../ie-common/canonical-reader";
 import {
     type ItmCanonicalDocument,
     type ItmCanonicalSnapshot,
     itmCanonicalDocumentSchemaPermissive,
     itmCanonicalSnapshotSchemaPermissive,
 } from "./canonical-schemas";
-import type { ParseResult } from "../types";
 
-export function getItmCanonicalDocument(result: ParseResult): ItmCanonicalDocument | undefined {
-    if (!result.document) return undefined;
-    return parseWithSchemaValidation(
-        itmCanonicalDocumentSchemaPermissive,
-        result.document,
-        "Invalid ITM canonical document",
-    );
-}
+const reader = createIeCanonicalReader<ItmCanonicalDocument, ItmCanonicalSnapshot>({
+    formatId: "itm",
+    formatLabel: "ITM",
+    documentSchemaPermissive: itmCanonicalDocumentSchemaPermissive,
+    snapshotSchemaPermissive: itmCanonicalSnapshotSchemaPermissive,
+});
 
-export function rebuildItmCanonicalDocument(result: ParseResult): ItmCanonicalDocument {
-    // The parser always sets result.document. A caller arriving here without
-    // one would be programming error — display-tree-only rebuild via walkGroup
-    // is not implemented (and not currently needed by any flow).
-    const doc = getItmCanonicalDocument(result);
-    if (!doc) {
-        throw new Error(
-            "ITM canonical document missing from ParseResult; display-tree-only rebuild is not implemented",
-        );
-    }
-    return doc;
-}
-
-export function createItmCanonicalSnapshot(result: ParseResult): ItmCanonicalSnapshot {
-    const document = rebuildItmCanonicalDocument(result);
-    const snapshot: ItmCanonicalSnapshot = {
-        schemaVersion: 1,
-        format: "itm",
-        formatName: result.formatName,
-        document,
-    };
-    if (result.opaqueRanges && result.opaqueRanges.length > 0) {
-        return parseWithSchemaValidation(
-            itmCanonicalSnapshotSchemaPermissive,
-            { ...snapshot, opaqueRanges: result.opaqueRanges },
-            "Invalid ITM canonical snapshot",
-        );
-    }
-    if (result.warnings) {
-        return { ...snapshot, warnings: result.warnings };
-    }
-    return snapshot;
-}
+export const getItmCanonicalDocument = reader.getDocument;
+export const rebuildItmCanonicalDocument = reader.rebuildDocument;
+export const createItmCanonicalSnapshot = reader.createSnapshot;