feat(binary): permissive parse + strict save

Splits canonical-doc validation into two modes so the editor and JSON
snapshot dump stay graceful for files with value-level deviations
(out-of-enum, out-of-domain, linked-count drift) while save-back-to-bytes
still rejects committable garbage.

Layering:

- spec/derive-zod adds a `mode: "strict" | "permissive"` option to
  toZodSchema. Permissive omits enum-membership refinements, domain bounds,
  and the linked-count superRefine; structural refinements (codec range,
  bit-width, array length, strictObject keys, integer typing) stay on in
  both modes — the doc shape must remain walkable regardless.

- pro/canonical-schemas exposes both proCanonicalSnapshotSchema (strict,
  default) and proCanonicalSnapshotSchemaPermissive from one factory.

- pro/canonical-reader and pro/json-snapshot.ts switch to the permissive
  schema. Out-of-enum / out-of-domain values now produce a usable canonical
  doc instead of being rejected at parse-time. (MAP unchanged: its
  canonical layer is hand-written and was already value-level permissive
  by design — see the comment at map/canonical-schemas.ts:89.)

- pro/canonical-writer's serializeProCanonicalDocument continues to
  validate against the strict schema before serialising — that's now the
  singular save gate. New regression test pro-canonical-writer-strict-gate
  pins the behaviour.

- pro/index.ts: enumField (which pushed errors on unknown enum values) is
  replaced by enumFieldTolerant, which renders "Unknown (N)" inline like
  walkStruct already does for spec-driven fields. parseCritter loses the
  `errors` parameter; the parser's errors array is now reserved for
  structural fatals only (size mismatch, truncation, unknown root type).

- map/parse-helpers.ts: enumField was dead code (no callers); deleted.
  map/parse-sections.ts had a post-display scan that re-converted
  walkStruct's tolerant "Unknown (N)" rows into errors; deleted, as it was
  actively defeating the tolerant design.

- cli: warnings print to stderr but no longer block JSON snapshot output.

The editor's banner infrastructure (errors-container, warnings-container,
renderMessages) was already wired through the init message channel; with
the parser changes it now naturally surfaces graceful-load info without
rendering an empty tree on what were previously fatal-treated value-level
issues.

Author: burner1024

binary/src/cli.ts

@@ -52,6 +52,18 @@ async function processFile(filePath: string, mode: OutputMode): Promise<FileResu
             return "error";
         }
 
+        // Warnings are non-fatal: surface them to stderr but proceed with the
+        // snapshot output. `parse` reserves `errors` for structural failures
+        // that prevent display (size mismatch, truncation, unknown root type);
+        // value-level oddities arrive in `warnings` and the canonical doc is
+        // built permissively for them.
+        if (result.warnings && result.warnings.length > 0) {
+            console.error(`Warnings parsing ${filePath}:`);
+            for (const w of result.warnings) {
+                console.error(`  ${w}`);
+            }
+        }
+
         const json = createBinaryJsonSnapshot(result).trimEnd();
         const jsonPath = getSnapshotPath(filePath);
 

binary/src/map/parse-helpers.ts

@@ -59,21 +59,6 @@ export function flagsField(
     return field(name, display, offset, size, "flags", undefined, value);
 }
 
-export function enumField(
-    name: string,
-    value: number,
-    lookup: Record<number, string>,
-    offset: number,
-    size: number,
-    errors?: string[],
-): ParsedField {
-    const resolved = lookup[value];
-    if (resolved === undefined && errors) {
-        errors.push(`Invalid ${name} at offset 0x${offset.toString(16)}: ${value}`);
-    }
-    return field(name, resolved ?? `Unknown (${value})`, offset, size, "enum", undefined, value);
-}
-
 export function int32Field(name: string, data: Uint8Array, offset: number): ParsedField {
     const view = new DataView(data.buffer, data.byteOffset + offset, 4);
     return field(name, view.getInt32(0, false), offset, 4, "int32");

binary/src/map/parse-sections.ts

@@ -32,7 +32,7 @@ import {
 import { walkStruct } from "../spec/walk-display";
 import { field, makeGroup, int32Field, HEADER_PADDING_OFFSET, HEADER_PADDING_SIZE } from "./parse-helpers";
 
-export function parseHeaderSection(data: Uint8Array, errors: string[]): ParsedGroup {
+export function parseHeaderSection(data: Uint8Array, _errors: string[]): ParsedGroup {
     const header = parseHeader(data);
 
     // walkStruct produces the 11 numeric/enum/flags rows from the spec +
@@ -41,25 +41,18 @@ export function parseHeaderSection(data: Uint8Array, errors: string[]): ParsedGr
     // The cast widens MapHeader (specific shape) to walkStruct's generic
     // record constraint; the spec keys are a subset of MapHeader's so the
     // runtime access is sound.
+    //
+    // Out-of-enum values surface inline as `Unknown (N)`; they are not pushed
+    // to `errors` because the parser is read-permissive (mirroring PRO). The
+    // strict gate against committable garbage lives at the canonical-write
+    // path; here we just describe what the file actually says.
     const numericGroup = walkStruct(
         mapHeaderCanonicalSpec,
         mapHeaderPresentation,
         0,
         header as unknown as Record<string, number>,
         "Header",
     );
-    for (const fieldEntry of numericGroup.fields) {
-        if ("fields" in fieldEntry) continue;
-        if (
-            fieldEntry.type === "enum" &&
-            typeof fieldEntry.value === "string" &&
-            fieldEntry.value.startsWith("Unknown (")
-        ) {
-            errors.push(
-                `Invalid ${fieldEntry.name} at offset 0x${fieldEntry.offset.toString(16)}: ${fieldEntry.rawValue}`,
-            );
-        }
-    }
 
     const fields = [...numericGroup.fields];
     fields.splice(1, 0, field("Filename", header.filename, 0x04, 16, "string"));

binary/src/pro/canonical-reader.ts

@@ -20,8 +20,8 @@ import {
 } from "./types";
 import type { ParsedField, ParsedGroup, ParseResult } from "../types";
 import {
-    proCanonicalSnapshotSchema,
-    proCanonicalDocumentSchema,
+    proCanonicalSnapshotSchemaPermissive,
+    proCanonicalDocumentSchemaPermissive,
     type ProCanonicalSnapshot,
     type ProCanonicalDocument,
 } from "./canonical-schemas";
@@ -377,7 +377,7 @@ function rebuildProCanonicalSnapshot(parseResult: ParseResult): ProCanonicalSnap
     }
 
     return parseWithSchemaValidation(
-        proCanonicalSnapshotSchema,
+        proCanonicalSnapshotSchemaPermissive,
         {
             schemaVersion: 1,
             format: "pro",
@@ -395,7 +395,7 @@ export function createProCanonicalSnapshot(parseResult: ParseResult): ProCanonic
     const embeddedDocument = getProCanonicalDocument(parseResult);
     if (embeddedDocument) {
         return parseWithSchemaValidation(
-            proCanonicalSnapshotSchema,
+            proCanonicalSnapshotSchemaPermissive,
             {
                 schemaVersion: 1,
                 format: "pro",
@@ -414,6 +414,6 @@ export function rebuildProCanonicalDocument(parseResult: ParseResult): ProCanoni
 }
 
 export function getProCanonicalDocument(parseResult: ParseResult): ProCanonicalDocument | undefined {
-    const parsed = proCanonicalDocumentSchema.safeParse(parseResult.document);
+    const parsed = proCanonicalDocumentSchemaPermissive.safeParse(parseResult.document);
     return parsed.success ? parsed.data : undefined;
 }