al-sem 0.0.1

package/src/snapshot/derive/inputs.ts

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+import type { SemanticModel } from "../../model/model.ts";
+import type { SnapshotInput } from "../types.ts";
+
+/**
+ * Walk the workspace + .alpackages directory, fingerprint each input file
+ * that contributes to snapshot identity:
+ *   - app.json                          → kind:"app-json"
+ *   - .alpackages/*.app                 → kind:"dep-package"
+ *   - roots.config.json (if loaded)     → kind:"roots-config"
+ *   - al-sem.coverage.yaml (if present) → kind:"policy"
+ *
+ * The `roots-config` entry is sourced from `model.identity.rootsConfig`
+ * rather than re-read from disk. `analyzeWorkspace` is the sole loader and
+ * sets that field only when the config was actually consulted — so
+ * `analyzeWorkspace({ noRootsConfig: true })` keeps the file out of the
+ * fingerprint even when it exists on disk. This is what lets
+ * `--no-roots-config` produce a different `workspaceFingerprint` from a
+ * baseline run, so diff tools can tell the two states apart.
+ *
+ * Paths relative to workspaceDir, forward-slash-normalised. Output sorted by
+ * (kind, path).
+ */
+export function deriveInputs(model: SemanticModel, workspaceDir: string): SnapshotInput[] {
+	const out: SnapshotInput[] = [];
+
+	// Standalone .app subject (snapshot-from-.app): the .app file IS the sole input,
+	// fingerprinted by its raw bytes so distinct .apps get distinct workspaceFingerprints.
+	if (
+		workspaceDir.toLowerCase().endsWith(".app") &&
+		existsSync(workspaceDir) &&
+		statSync(workspaceDir).isFile()
+	) {
+		return [
+			{ kind: "app-package", path: basename(workspaceDir), contentHash: hashFile(workspaceDir) },
+		];
+	}
+
+	const appJson = join(workspaceDir, "app.json");
+	if (existsSync(appJson)) {
+		out.push({
+			kind: "app-json",
+			path: rel(workspaceDir, appJson),
+			contentHash: hashFile(appJson),
+		});
+	}
+
+	const alpackages = join(workspaceDir, ".alpackages");
+	if (existsSync(alpackages) && statSync(alpackages).isDirectory()) {
+		for (const name of readdirSync(alpackages)) {
+			if (!name.endsWith(".app")) continue;
+			const p = join(alpackages, name);
+			out.push({ kind: "dep-package", path: rel(workspaceDir, p), contentHash: hashFile(p) });
+		}
+	}
+
+	// roots.config.json: read identity rather than re-hash from disk. This
+	// lets `analyzeWorkspace({ noRootsConfig: true })` keep the file out of
+	// the fingerprint even when the file exists on disk. `analyzeWorkspace`
+	// sets `model.identity.rootsConfig` only when the config was actually
+	// loaded.
+	if (model.identity.rootsConfig !== undefined) {
+		out.push({
+			kind: "roots-config",
+			path: rel(workspaceDir, model.identity.rootsConfig.path),
+			contentHash: model.identity.rootsConfig.contentHash,
+		});
+	}
+
+	const coveragePolicy = join(workspaceDir, "al-sem.coverage.yaml");
+	if (existsSync(coveragePolicy)) {
+		out.push({
+			kind: "policy",
+			path: rel(workspaceDir, coveragePolicy),
+			contentHash: hashFile(coveragePolicy),
+		});
+	}
+
+	out.sort((a, b) => `${a.kind}|${a.path}`.localeCompare(`${b.kind}|${b.path}`));
+	return out;
+}
+
+function hashFile(p: string): string {
+	return createHash("sha256").update(readFileSync(p)).digest("hex");
+}
+
+function rel(from: string, p: string): string {
+	return relative(from, p).split("\\").join("/");
+}

package/src/snapshot/derive/operation-evidence.ts

@@ -0,0 +1,70 @@
+import type { SemanticModel } from "../../model/model.ts";
+import { createIdentityIndex } from "../../model/stable-identity.ts";
+import type { StableRoutineId } from "../../model/stable-identity.ts";
+import type { OperationEvidence, SnapshotIdentityTable } from "../types.ts";
+
+/**
+ * Emit OperationEvidence for every OperationSite + RecordOperation that
+ * appears as the witnessOperationId of a CapabilityFact (direct or inherited).
+ *
+ * Sort by operationId.
+ */
+export function deriveOperationEvidence(
+	model: SemanticModel,
+	_idx: SnapshotIdentityTable,
+): OperationEvidence[] {
+	const idCvt = createIdentityIndex();
+	const referenced = new Set<string>();
+	for (const r of model.routines ?? []) {
+		const summary = r.summary;
+		if (summary === undefined) continue;
+		for (const f of [
+			...(summary.capabilityFactsDirect ?? []),
+			...(summary.capabilityFactsInherited ?? []),
+		]) {
+			if (f.witnessOperationId !== undefined) {
+				referenced.add(String(f.witnessOperationId));
+			}
+		}
+	}
+
+	const out: OperationEvidence[] = [];
+	for (const r of model.routines ?? []) {
+		const stableObject = idCvt.toStableObjectId(r.objectId);
+		const stableRoutine = idCvt.toStableRoutineIdFromParts(
+			stableObject,
+			r.canonical?.normalizedSignatureHash ?? "",
+		) as StableRoutineId;
+
+		for (const op of r.features?.operationSites ?? []) {
+			if (!referenced.has(String(op.id))) continue;
+			const a = op.sourceAnchor;
+			out.push({
+				operationId: op.id,
+				routine: stableRoutine,
+				sourceFile: a.sourceUnitId,
+				startLine: a.range.startLine,
+				startColumn: a.range.startColumn,
+				endLine: a.range.endLine,
+				endColumn: a.range.endColumn,
+				displayText: op.kind,
+			});
+		}
+		for (const ro of r.features?.recordOperations ?? []) {
+			if (!referenced.has(String(ro.id))) continue;
+			const a = ro.sourceAnchor;
+			out.push({
+				operationId: ro.id,
+				routine: stableRoutine,
+				sourceFile: a.sourceUnitId,
+				startLine: a.range.startLine,
+				startColumn: a.range.startColumn,
+				endLine: a.range.endLine,
+				endColumn: a.range.endColumn,
+				displayText: `${ro.recordVariableName ?? "?"}.${ro.op}`,
+			});
+		}
+	}
+	out.sort((a, b) => String(a.operationId).localeCompare(String(b.operationId)));
+	return out;
+}

package/src/snapshot/derive/permissions.ts

@@ -0,0 +1,186 @@
+// src/snapshot/derive/permissions.ts
+//
+// Two halves merged into one PermissionFact[]:
+//
+// (a) DeclaredPermissionFact[] from model.permissionSets when present.
+//     Phase 0c ships best-effort: the model does not expose permissionSets
+//     yet. Phase 4 wires PermissionSet projection.
+//
+// (b) RequiredPermissionFact[] derived per spec §3.8:
+//       read|insert|modify|delete on table T → R|I|M|D on TableData T
+//       execute on codeunit|page|report O    → X on O
+//     Only facts whose resourceId is resolved (not undefined or null) are emitted —
+//     unresolved capability facts carry no stable target and cannot produce
+//     a meaningful permission entry.
+//
+// Each required fact carries the coverage status of its source routine's
+// inherited cone (G6 enforcement). Output sorted canonically.
+
+import type { CapabilityOp } from "../../model/capability.ts";
+import type { SemanticModel } from "../../model/model.ts";
+import type {
+	PermissionFact,
+	PermissionRight,
+	RequiredPermissionFact,
+} from "../../model/permission.ts";
+import { createIdentityIndex } from "../../model/stable-identity.ts";
+import type {
+	StableObjectId,
+	StableRoutineId,
+	StableTableId,
+} from "../../model/stable-identity.ts";
+import type { SnapshotIdentityTable } from "../types.ts";
+
+const TABLE_OP_TO_RIGHT: Partial<Record<CapabilityOp, PermissionRight>> = {
+	read: "R",
+	insert: "I",
+	modify: "M",
+	delete: "D",
+};
+
+/**
+ * Derive the full PermissionFact[] for the snapshot.
+ *
+ * Two halves merged into one array:
+ *
+ * (a) DeclaredPermissionFact[] from PermissionSet objects — minimal in
+ *     Phase 0c (the model does not project permissionSets yet; Phase 4
+ *     enriches this branch).
+ *
+ * (b) RequiredPermissionFact[] derived per spec §3.8:
+ *       read|insert|modify|delete on table T → R|I|M|D on TableData T
+ *       execute on codeunit|page|report O    → X on O
+ *
+ * Each required perm carries coverage status — G6 enforcement: callers
+ * see "may be incomplete" when the cone is partial. Output sorted
+ * canonically by (kind, subject/set, target, rights).
+ *
+ * `idx` is the SnapshotIdentityTable produced earlier; not consulted
+ * directly (id rewriting goes through createIdentityIndex), but accepting
+ * it keeps the deriver signature uniform with the rest of the family.
+ */
+export function derivePermissions(
+	model: SemanticModel,
+	_idx: SnapshotIdentityTable,
+): PermissionFact[] {
+	const idCvt = createIdentityIndex();
+	const out: PermissionFact[] = [];
+
+	// (a) Declared — only emit if the model exposes permissionSets.
+	// Phase 4 wires PermissionSet projection; Phase 0c is best-effort.
+	const ps = (model as unknown as { permissionSets?: unknown[] }).permissionSets;
+	if (Array.isArray(ps)) {
+		for (const item of ps) {
+			const entry = item as Record<string, unknown>;
+			if (
+				typeof entry.permissionSet === "string" &&
+				typeof entry.target === "string" &&
+				typeof entry.targetKind === "string" &&
+				Array.isArray(entry.rights) &&
+				typeof entry.scope === "string"
+			) {
+				out.push({
+					kind: "declared",
+					permissionSet: entry.permissionSet as never,
+					target: entry.target as never,
+					targetKind: entry.targetKind as never,
+					rights: entry.rights as PermissionRight[],
+					scope: entry.scope as "Inherent" | "Assignable",
+				});
+			}
+		}
+	}
+
+	// (b) Required — one entry per (routine, target, right) triple.
+	for (const r of model.routines ?? []) {
+		const summary = r.summary;
+		if (summary === undefined) continue;
+
+		const stableObject = idCvt.toStableObjectId(r.objectId);
+		const stableSubject = idCvt.toStableRoutineIdFromParts(
+			stableObject,
+			r.canonical.normalizedSignatureHash,
+		) as StableRoutineId;
+
+		// Coverage: prefer inheritedStatus (whole cone), fall back to
+		// directStatus, then "unknown".
+		const coverage =
+			summary.coverage?.inheritedStatus ?? summary.coverage?.directStatus ?? "unknown";
+
+		const facts = [
+			...(summary.capabilityFactsDirect ?? []),
+			...(summary.capabilityFactsInherited ?? []),
+		];
+
+		// Deduplicate within this routine's contribution.
+		const seen = new Set<string>();
+
+		for (const f of facts) {
+			if (f.resourceKind === "table" && f.resourceId != null) {
+				const right = TABLE_OP_TO_RIGHT[f.op];
+				if (right === undefined) continue;
+				const stableTable = idCvt.toStableTableId(f.resourceId as string);
+				const key = `${stableSubject}|${stableTable}|${right}`;
+				if (seen.has(key)) continue;
+				seen.add(key);
+				const req: RequiredPermissionFact = {
+					kind: "required",
+					subject: stableSubject,
+					target: stableTable as StableTableId,
+					targetKind: "TableData",
+					rights: [right],
+					derivedFromCapability: {
+						op: f.op,
+						...(f.witnessCallsiteId !== undefined
+							? { witnessCallsiteId: f.witnessCallsiteId }
+							: {}),
+					},
+					coverage,
+				};
+				out.push(req);
+			} else if (
+				f.op === "execute" &&
+				f.resourceId != null &&
+				(f.resourceKind === "codeunit" || f.resourceKind === "page" || f.resourceKind === "report")
+			) {
+				const stableObj = idCvt.toStableObjectId(f.resourceId as string);
+				const key = `${stableSubject}|${stableObj}|X`;
+				if (seen.has(key)) continue;
+				seen.add(key);
+				const req: RequiredPermissionFact = {
+					kind: "required",
+					subject: stableSubject,
+					target: stableObj as StableObjectId,
+					targetKind: capitaliseObjectKind(f.resourceKind),
+					rights: ["X"],
+					derivedFromCapability: {
+						op: f.op,
+						...(f.witnessCallsiteId !== undefined
+							? { witnessCallsiteId: f.witnessCallsiteId }
+							: {}),
+					},
+					coverage,
+				};
+				out.push(req);
+			}
+		}
+	}
+
+	out.sort((a, b) => permKey(a).localeCompare(permKey(b)));
+	return out;
+}
+
+function capitaliseObjectKind(k: "codeunit" | "page" | "report"): "Codeunit" | "Page" | "Report" {
+	if (k === "codeunit") return "Codeunit";
+	if (k === "page") return "Page";
+	return "Report";
+}
+
+function permKey(p: PermissionFact): string {
+	if (p.kind === "declared") {
+		return ["D", String(p.permissionSet), String(p.target), p.targetKind, p.rights.join("")].join(
+			"|",
+		);
+	}
+	return ["R", String(p.subject), String(p.target), p.targetKind, p.rights.join("")].join("|");
+}

package/src/snapshot/derive/root-classifications.ts

@@ -0,0 +1,56 @@
+import type { SemanticModel } from "../../model/model.ts";
+import { createIdentityIndex } from "../../model/stable-identity.ts";
+import type { StableRoutineId } from "../../model/stable-identity.ts";
+import type { RootClassificationSlot, SnapshotIdentityTable } from "../types.ts";
+
+/**
+ * Project `model.rootClassifications` (Phase 1 §4.3 classifier output) into
+ * the snapshot's `RootClassificationSlot[]` shape. Only the `routineId` field
+ * is rewritten (internal `RoutineId` → `StableRoutineId`); all provenance
+ * fields (`source`, `confidence`, `sourceAnchor`, `configEntryId`,
+ * `resolutionStatus`) pass through verbatim.
+ *
+ * Routines that don't appear in `model.routines` are silently dropped — they
+ * shouldn't exist in practice (the classifier only emits for known routines),
+ * but the engine-never-throws contract is preserved either way.
+ *
+ * Output is sorted by `StableRoutineId` for determinism, matching every other
+ * deriver in `src/snapshot/derive/`.
+ */
+export function deriveRootClassifications(
+	model: SemanticModel,
+	_idx: SnapshotIdentityTable,
+): RootClassificationSlot[] {
+	const idCvt = createIdentityIndex();
+
+	// Build internal RoutineId → StableRoutineId lookup once.
+	const routineToStable = new Map<string, StableRoutineId>();
+	for (const r of model.routines ?? []) {
+		const stableObject = idCvt.toStableObjectId(r.objectId);
+		const stable = idCvt.toStableRoutineIdFromParts(
+			stableObject,
+			r.canonical?.normalizedSignatureHash ?? "",
+		) as StableRoutineId;
+		routineToStable.set(String(r.id), stable);
+	}
+
+	const out: RootClassificationSlot[] = [];
+	for (const c of model.rootClassifications ?? []) {
+		const stable = routineToStable.get(String(c.routineId));
+		if (stable === undefined) continue;
+		const slot: RootClassificationSlot = {
+			routineId: stable,
+			kinds: [...c.kinds],
+			externallyReachable: c.externallyReachable,
+			source: c.source,
+			confidence: c.confidence,
+		};
+		if (c.sourceAnchor !== undefined) slot.sourceAnchor = c.sourceAnchor;
+		if (c.configEntryId !== undefined) slot.configEntryId = c.configEntryId;
+		if (c.resolutionStatus !== undefined) slot.resolutionStatus = c.resolutionStatus;
+		out.push(slot);
+	}
+
+	out.sort((a, b) => String(a.routineId).localeCompare(String(b.routineId)));
+	return out;
+}

package/src/snapshot/derive/schema.ts

@@ -0,0 +1,130 @@
+import { createHash } from "node:crypto";
+import type { Field, Key, Table } from "../../model/entities.ts";
+import type { SemanticModel } from "../../model/model.ts";
+import { createIdentityIndex } from "../../model/stable-identity.ts";
+import type { SchemaFact, SnapshotIdentityTable } from "../types.ts";
+
+/**
+ * Project every workspace table + its fields + keys to SchemaFact[].
+ *
+ * Enum + enum-value projections are deferred to Phase 1+ schema work — the
+ * model does not expose enum members at L2 in the current pipeline.
+ *
+ * shapeFingerprint = SHA-256(canonical-json(shape)):
+ *   Table shape: { number, name }
+ *   Field shape: { dataType, fieldClass, isBlobLike }
+ *   Key shape:   { fields: StableFieldId[], isEnabled }
+ *     where fields are the stable field ids (appGuid:Table:N#fieldNum) sorted
+ *     to make the fingerprint position-independent within the field list.
+ *
+ * stableId formats (from createIdentityIndex):
+ *   Table: `${appGuid}:Table:${tableNumber}`
+ *   Field: `${stableTableId}#${fieldNumber}`
+ *   Key:   `${stableTableId}#K${keyIndex}`   (index from the Key.id suffix)
+ *
+ * Output sorted by stableId for determinism.
+ */
+export function deriveSchema(model: SemanticModel, _idx: SnapshotIdentityTable): SchemaFact[] {
+	const idCvt = createIdentityIndex();
+	const out: SchemaFact[] = [];
+
+	for (const tbl of model.tables ?? []) {
+		const stableTable = idCvt.toStableTableId(tbl.id);
+		out.push(makeTableFact(tbl, stableTable));
+
+		for (const fld of tbl.fields) {
+			const stableField = idCvt.toStableFieldId(fld.id);
+			out.push(makeFieldFact(fld, stableField, idCvt));
+		}
+
+		for (const key of tbl.keys) {
+			const stableKey = stableKeyId(key.id, stableTable);
+			out.push(makeKeyFact(key, stableKey, idCvt));
+		}
+	}
+
+	out.sort((a, b) => a.stableId.localeCompare(b.stableId));
+	return out;
+}
+
+// ---------------------------------------------------------------------------
+// Per-entity fact builders
+// ---------------------------------------------------------------------------
+
+function makeTableFact(tbl: Table, stableId: string): SchemaFact {
+	return {
+		kind: "table",
+		stableId,
+		shapeFingerprint: sha256(canonicalJson({ number: tbl.tableNumber, name: tbl.name })),
+	};
+}
+
+function makeFieldFact(
+	fld: Field,
+	stableId: string,
+	_idCvt: ReturnType<typeof createIdentityIndex>,
+): SchemaFact {
+	return {
+		kind: "field",
+		stableId,
+		shapeFingerprint: sha256(
+			canonicalJson({
+				dataType: fld.dataType,
+				fieldClass: fld.fieldClass,
+				isBlobLike: fld.isBlobLike,
+			}),
+		),
+	};
+}
+
+function makeKeyFact(
+	key: Key,
+	stableId: string,
+	idCvt: ReturnType<typeof createIdentityIndex>,
+): SchemaFact {
+	// Convert internal FieldIds to stable ids for cross-version stability.
+	const stableFields = key.fields.map((f) => idCvt.toStableFieldId(f)).sort();
+	return {
+		kind: "key",
+		stableId,
+		shapeFingerprint: sha256(
+			canonicalJson({
+				fields: stableFields,
+				isEnabled: key.isEnabled ?? true,
+			}),
+		),
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Key stable-id derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive a stable key id from the raw KeyId.
+ * KeyId format: `${tableId}/key/${index}` (from encodeKeyId in model/ids.ts).
+ * We strip the table prefix and replace the `/key/` segment with `#K` so the
+ * result is: `${stableTableId}#K${keyIndex}`.
+ */
+function stableKeyId(keyId: string, stableTable: string): string {
+	const marker = "/key/";
+	const pos = keyId.lastIndexOf(marker);
+	const keyIndex = pos >= 0 ? keyId.slice(pos + marker.length) : keyId;
+	return `${stableTable}#K${keyIndex}`;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function canonicalJson(v: unknown): string {
+	if (v === null || typeof v !== "object") return JSON.stringify(v);
+	if (Array.isArray(v)) return `[${v.map(canonicalJson).join(",")}]`;
+	const o = v as Record<string, unknown>;
+	const keys = Object.keys(o).sort();
+	return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`).join(",")}}`;
+}
+
+function sha256(s: string): string {
+	return createHash("sha256").update(s, "utf8").digest("hex");
+}

package/src/snapshot/derive/typed-edges.ts

@@ -0,0 +1,60 @@
+// src/snapshot/derive/typed-edges.ts
+//
+// Project model.typedEdges (populated by Phase 0b-β combined-graph) with
+// from/to rewritten from internal RoutineId → StableRoutineId.
+//
+// Every edge in the discriminated union has a `from: RoutineId` field.
+// All except `object-run-unresolved` also have a `to: RoutineId` field.
+// Both are rewritten in-place on a shallow copy of the edge.
+//
+// Sort key: (kind, from, to).
+
+import type { GraphEdge } from "../../model/graph-edge.ts";
+import type { SemanticModel } from "../../model/model.ts";
+import { createIdentityIndex } from "../../model/stable-identity.ts";
+import type { SnapshotIdentityTable } from "../types.ts";
+
+/**
+ * Project model.typedEdges (populated by Phase 0b-β combined-graph) with
+ * from/to rewritten internal RoutineId → StableRoutineId.
+ *
+ * Sort by (kind, from, to).
+ */
+export function deriveTypedEdges(model: SemanticModel, _idx: SnapshotIdentityTable): GraphEdge[] {
+	const idCvt = createIdentityIndex();
+
+	// Build a RoutineId → StableRoutineId lookup for every routine in the model.
+	const routineToStable = new Map<string, string>();
+	for (const r of model.routines ?? []) {
+		const stableObject = idCvt.toStableObjectId(r.objectId);
+		const stable = idCvt.toStableRoutineIdFromParts(
+			stableObject,
+			r.canonical?.normalizedSignatureHash ?? "",
+		);
+		routineToStable.set(r.id as unknown as string, stable);
+	}
+
+	const remap = (id: string): string => routineToStable.get(id) ?? id;
+
+	const out: GraphEdge[] = [];
+	for (const e of model.typedEdges ?? []) {
+		// Shallow-copy and rewrite from/to where present.
+		const copy = { ...e } as GraphEdge;
+		if ("from" in copy && typeof copy.from === "string") {
+			(copy as { from: string }).from = remap(copy.from);
+		}
+		if ("to" in copy && typeof copy.to === "string") {
+			(copy as { to: string }).to = remap(copy.to);
+		}
+		out.push(copy);
+	}
+
+	out.sort((a, b) => edgeKey(a).localeCompare(edgeKey(b)));
+	return out;
+}
+
+function edgeKey(e: GraphEdge): string {
+	const from = "from" in e ? String(e.from ?? "") : "";
+	const to = "to" in e ? String((e as { to?: unknown }).to ?? "") : "";
+	return [e.kind, from, to].join("|");
+}

package/src/snapshot/derive/workspace-fingerprint.ts

@@ -0,0 +1,19 @@
+import { createHash } from "node:crypto";
+import type { SnapshotInput } from "../types.ts";
+
+/**
+ * SHA-256 over the sorted (kind, path, contentHash) triples + alsemVersion.
+ * Stable across runs given the same inputs + version; differs when ANY input
+ * contentHash or the alsem version changes.
+ */
+export function computeWorkspaceFingerprint(
+	inputs: readonly SnapshotInput[],
+	alsemVersion: string,
+): string {
+	const sorted = [...inputs].sort((a, b) =>
+		`${a.kind}|${a.path}`.localeCompare(`${b.kind}|${b.path}`),
+	);
+	const lines = sorted.map((i) => `${i.kind}\t${i.path}\t${i.contentHash}`);
+	lines.push(`alsemVersion\t${alsemVersion}`);
+	return createHash("sha256").update(lines.join("\n"), "utf8").digest("hex");
+}

package/src/snapshot/deserialize.ts

@@ -0,0 +1,40 @@
+import { decode as cborDecode } from "cbor-x";
+import { type CapabilitySnapshot, SNAPSHOT_SCHEMA_VERSION, type SnapshotFormat } from "./types.ts";
+
+/**
+ * Deserialize a snapshot from bytes. Auto-detects format unless `formatHint`
+ * is provided:
+ *   - first byte 0x7b ('{') → JSON
+ *   - first two bytes 0x1f 0x8b → gzip → un-gzip → CBOR
+ *   - otherwise → CBOR
+ *
+ * Asserts schemaVersion. Phase 0c only accepts 1; future versions add
+ * migration shims here.
+ */
+export function deserializeSnapshot(
+	bytes: Uint8Array,
+	formatHint?: SnapshotFormat,
+): CapabilitySnapshot {
+	const fmt = formatHint ?? detectFormat(bytes);
+	let parsed: unknown;
+	if (fmt === "json") {
+		parsed = JSON.parse(new TextDecoder().decode(bytes));
+	} else if (fmt === "cbor.gz") {
+		parsed = cborDecode(Bun.gunzipSync(bytes as unknown as ArrayBuffer));
+	} else {
+		parsed = cborDecode(bytes);
+	}
+	const snap = parsed as CapabilitySnapshot;
+	if (snap.schemaVersion !== SNAPSHOT_SCHEMA_VERSION) {
+		throw new Error(
+			`deserializeSnapshot: unknown schemaVersion ${snap.schemaVersion} (this build only handles ${SNAPSHOT_SCHEMA_VERSION})`,
+		);
+	}
+	return snap;
+}
+
+function detectFormat(bytes: Uint8Array): SnapshotFormat {
+	if (bytes.length >= 2 && bytes[0] === 0x1f && bytes[1] === 0x8b) return "cbor.gz";
+	if (bytes.length >= 1 && bytes[0] === 0x7b) return "json";
+	return "cbor";
+}

package/src/snapshot/serialize-cbor-gz.ts

@@ -0,0 +1,12 @@
+import { serializeCbor } from "./serialize-cbor.ts";
+import type { CapabilitySnapshot } from "./types.ts";
+
+/**
+ * CBOR + gzip serializer. Wraps the CBOR output with Bun's built-in
+ * gzipSync. Byte-stable; smaller than uncompressed CBOR; starts with
+ * the gzip magic bytes 0x1f 0x8b used by the deserializer auto-detect.
+ */
+export function serializeCborGz(snapshot: CapabilitySnapshot): Uint8Array {
+	const cbor = serializeCbor(snapshot);
+	return Bun.gzipSync(cbor as unknown as ArrayBuffer) as Uint8Array;
+}

package/src/snapshot/serialize-cbor.ts

@@ -0,0 +1,19 @@
+import { Encoder } from "cbor-x";
+import type { CapabilitySnapshot } from "./types.ts";
+
+// Pinned encoder options for deterministic output.
+const encoder = new Encoder({
+	useRecords: false,
+	mapsAsObjects: true,
+	pack: false,
+});
+
+/**
+ * CBOR serializer. Returns a Uint8Array.
+ *
+ * Deterministic: encoder options pinned; cbor-x's tag tables and key order
+ * are stable for plain JS objects. Round-trip tested in Task 18 deserializer.
+ */
+export function serializeCbor(snapshot: CapabilitySnapshot): Uint8Array {
+	return encoder.encode(snapshot);
+}