mellos-mapping 0.19.0 → 0.20.0

package/lib/semantics/semantics.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Layer 1c — medium-neutral VIEW SEMANTICS of a MellosMap.
+ *
+ * Every renderer (the terminal pane, a web panel, a future editor view) must
+ * agree on what a zoom step MEANS, when a map aggregates into its groups,
+ * how sequence time is oriented, and which map kinds render neutrally.
+ * Those rules live here, pure of any medium: no cells, no glyphs, no DOM,
+ * no I/O. Geometry — how a mode maps onto character cells or pixels — stays
+ * private to each renderer.
+ */
+import type { MapGroup, MapNode, MellosMap, NodeStatus } from '../domain/types.js';
+/** One wheel tick on the zoom ladder. */
+export type ZoomStep = -4 | -3 | -2 | -1 | 0 | 1 | 2;
+export declare const ZOOM_MIN: ZoomStep;
+export declare const ZOOM_MAX: ZoomStep;
+export declare const ZOOM_DEFAULT: ZoomStep;
+export declare function clampZoom(n: number): ZoomStep;
+/**
+ * What a zoom step MEANS, before any renderer decides what it looks like:
+ * scaling only compresses, the ends of the ladder switch mode. 'detail'
+ * unfolds evidence and design notes; 'overview' switches to the aggregated
+ * far view (groups become the nodes — see aggregateMap); 'boxes' is every
+ * step in between, where boxes stay boxes and only whitespace and label
+ * budgets change.
+ */
+export declare function zoomMode(zoom: ZoomStep): 'detail' | 'boxes' | 'overview';
+/** What a footer shows: a percentage while scaling, a mode name at the ends. */
+export declare function zoomLabel(zoom: ZoomStep): string;
+/** Documentation kinds render neutrally: no status skins, no progress counts. */
+export declare function isNeutralKind(map: MellosMap): boolean;
+/**
+ * The derived coarse picture the far zoom renders when the map declares
+ * groups: each group becomes ONE labeled node (status derived from members,
+ * label carrying done/total), ungrouped nodes stay themselves, and edges
+ * collapse onto representatives (intra-group wiring disappears into the
+ * box). Derived for rendering only — never persisted. A map without groups
+ * returns undefined and falls back to whatever anonymous overview the
+ * renderer draws.
+ */
+export declare function aggregateMap(map: MellosMap): MellosMap | undefined;
+/** One neighbour across a dependency edge, with what flows along it. */
+export interface NeighborRef {
+    readonly id: string;
+    readonly label: string;
+    readonly status: NodeStatus;
+    readonly edgeLabel?: string;
+}
+/** Everything a detail panel derives for a focused NODE. */
+export interface NodeFocus {
+    readonly kind: 'node';
+    readonly node: MapNode;
+    readonly layerName: string;
+    readonly laneLabel?: string;
+    /** Lower neighbours this node stands on (on sequence pages: the earlier events). */
+    readonly uses: readonly NeighborRef[];
+    /** Upper neighbours standing on this node (on sequence pages: the later events). */
+    readonly usedBy: readonly NeighborRef[];
+}
+/** Everything a detail panel derives for a focused GROUP (the far zoom's boxes). */
+export interface GroupFocus {
+    readonly kind: 'group';
+    readonly group: MapGroup;
+    readonly status: NodeStatus;
+    readonly layerName: string;
+    readonly members: readonly MapNode[];
+    /** Outside-the-group lower neighbours, each shown as its own group when it has one. */
+    readonly uses: readonly NeighborRef[];
+    /** Outside-the-group upper neighbours, each shown as its own group when it has one. */
+    readonly usedBy: readonly NeighborRef[];
+}
+/**
+ * Derive what a detail panel says about one focused id — a node, or a group
+ * when the far zoom's aggregated boxes are what the pointer is over. Pure
+ * data: every renderer picks its own glyphs, colors, and words (a sequence
+ * page reads uses/usedBy as after/before; that is the caller's vocabulary).
+ * @param map - the map the focus lives in.
+ * @param focusId - node or group id.
+ * @returns the focus view, or undefined when the id names neither.
+ */
+export declare function focusInfo(map: MellosMap, focusId: string): NodeFocus | GroupFocus | undefined;
+/**
+ * Page slugs some node of any map dives into. A page referenced as a submap
+ * is interior detail — it is reached by diving through its linking node,
+ * never by sitting beside its parent as a sibling tab.
+ * @param maps - every known page's map (undefined entries are skipped).
+ * @returns the referenced submap slugs.
+ */
+export declare function submapRefs(maps: Iterable<MellosMap | undefined>): Set<string>;
+/**
+ * Where a sub-map page was dived into from: the entry whose map links the
+ * page, plus the linking node's label. Derived by scan, so a breadcrumb
+ * survives any client restart with an empty dive stack.
+ * @param entries - known pages as (key, map) pairs; keys are caller-owned.
+ * @param pageId - the sub-map page's slug.
+ * @returns the linking entry's key and node label, or undefined for a top-level page.
+ */
+export declare function diveParent<K>(entries: Iterable<readonly [K, MellosMap | undefined]>, pageId: string): {
+    parent: K;
+    label: string;
+} | undefined;
+/**
+ * The page a client shows when nobody asked for one: the most recently
+ * WRITTEN page — the ledger last touched is almost always the effort under
+ * way. Keys without a readable timestamp lose; an empty set answers the
+ * first key (caller-ordered: default page first, then slug order).
+ * @param keys - candidate page keys in the caller's fallback order.
+ * @param mtimeOf - last-written timestamp of a key, undefined when unknown.
+ * @returns the winning key, or undefined for an empty candidate set.
+ */
+export declare function mostRecentKey<K>(keys: readonly K[], mtimeOf: (key: K) => number | undefined): K | undefined;
+/**
+ * Sequence pages read like the classic diagram: time flows DOWNWARD, the
+ * earliest step right under the participant headers. The stored map keeps
+ * rank 0 = earliest with edges pointing later -> earlier ("later stands on
+ * earlier"); this derived value inverts the ranks and reverses the edges so
+ * unchanged top-down machinery draws top-down time — each wire now runs
+ * from the sender's moment down into the receiver's. Derived for rendering
+ * only, never persisted (same contract as aggregateMap).
+ */
+export declare function flipForSequence(map: MellosMap): MellosMap;

package/lib/semantics/semantics.js

@@ -0,0 +1,256 @@
+/**
+ * Layer 1c — medium-neutral VIEW SEMANTICS of a MellosMap.
+ *
+ * Every renderer (the terminal pane, a web panel, a future editor view) must
+ * agree on what a zoom step MEANS, when a map aggregates into its groups,
+ * how sequence time is oriented, and which map kinds render neutrally.
+ * Those rules live here, pure of any medium: no cells, no glyphs, no DOM,
+ * no I/O. Geometry — how a mode maps onto character cells or pixels — stays
+ * private to each renderer.
+ */
+import { groupStatus } from '../domain/ops.js';
+export const ZOOM_MIN = -4;
+export const ZOOM_MAX = 2;
+export const ZOOM_DEFAULT = 0;
+export function clampZoom(n) {
+    return Math.max(ZOOM_MIN, Math.min(ZOOM_MAX, Math.round(n)));
+}
+/**
+ * What a zoom step MEANS, before any renderer decides what it looks like:
+ * scaling only compresses, the ends of the ladder switch mode. 'detail'
+ * unfolds evidence and design notes; 'overview' switches to the aggregated
+ * far view (groups become the nodes — see aggregateMap); 'boxes' is every
+ * step in between, where boxes stay boxes and only whitespace and label
+ * budgets change.
+ */
+export function zoomMode(zoom) {
+    if (zoom >= 1)
+        return 'detail';
+    if (zoom <= -4)
+        return 'overview';
+    return 'boxes';
+}
+/** What a footer shows: a percentage while scaling, a mode name at the ends. */
+export function zoomLabel(zoom) {
+    switch (zoom) {
+        case 2:
+            return 'detail+';
+        case 1:
+            return 'detail';
+        case 0:
+            return '100%';
+        case -1:
+            return '85%';
+        case -2:
+            return '70%';
+        case -3:
+            return '55%';
+        case -4:
+            return 'overview';
+    }
+}
+// ---------------------------------------------------------------------------
+// kind semantics
+// ---------------------------------------------------------------------------
+/** Documentation kinds render neutrally: no status skins, no progress counts. */
+export function isNeutralKind(map) {
+    return map.kind !== undefined && map.kind !== 'dev';
+}
+// ---------------------------------------------------------------------------
+// derived views (never persisted)
+// ---------------------------------------------------------------------------
+/**
+ * The derived coarse picture the far zoom renders when the map declares
+ * groups: each group becomes ONE labeled node (status derived from members,
+ * label carrying done/total), ungrouped nodes stay themselves, and edges
+ * collapse onto representatives (intra-group wiring disappears into the
+ * box). Derived for rendering only — never persisted. A map without groups
+ * returns undefined and falls back to whatever anonymous overview the
+ * renderer draws.
+ */
+export function aggregateMap(map) {
+    if (map.groups.length === 0)
+        return undefined;
+    // Group ids join the node-id slug space inside this derived value; the
+    // brands only guard PERSISTED maps, and this one never leaves rendering.
+    const representative = new Map();
+    for (const n of map.nodes)
+        representative.set(n.id, (n.group ?? n.id));
+    const nodes = map.groups.map((g) => {
+        const members = map.nodes.filter((n) => n.group === g.id);
+        const done = members.filter((n) => n.status === 'done').length;
+        return {
+            id: g.id,
+            // neutral kinds document structure, not progress — no member counts
+            label: isNeutralKind(map) ? g.label : `${g.label} ${done}/${members.length}`,
+            layer: g.layer,
+            status: groupStatus(map, g.id),
+        };
+    });
+    for (const n of map.nodes)
+        if (n.group === undefined)
+            nodes.push(n);
+    const seen = new Set();
+    const edges = [];
+    for (const e of map.edges) {
+        const from = representative.get(e.from);
+        const to = representative.get(e.to);
+        if (from === to || seen.has(`${from}->${to}`))
+            continue;
+        seen.add(`${from}->${to}`);
+        edges.push({ from: from, to: to });
+    }
+    return {
+        ...(map.title !== undefined ? { title: map.title } : {}),
+        ...(map.kind !== undefined ? { kind: map.kind } : {}),
+        layers: map.layers,
+        groups: [],
+        lanes: map.lanes,
+        nodes,
+        edges,
+    };
+}
+/**
+ * Derive what a detail panel says about one focused id — a node, or a group
+ * when the far zoom's aggregated boxes are what the pointer is over. Pure
+ * data: every renderer picks its own glyphs, colors, and words (a sequence
+ * page reads uses/usedBy as after/before; that is the caller's vocabulary).
+ * @param map - the map the focus lives in.
+ * @param focusId - node or group id.
+ * @returns the focus view, or undefined when the id names neither.
+ */
+export function focusInfo(map, focusId) {
+    const layerNameOf = (layerId) => map.layers.find((l) => l.id === layerId)?.name ?? layerId;
+    const group = map.groups.find((g) => g.id === focusId);
+    if (group) {
+        const members = map.nodes.filter((n) => n.group === group.id);
+        const memberIds = new Set(members.map((n) => n.id));
+        // A neighbour is shown as its own group when it has one, else as itself.
+        const rep = (id) => {
+            const n = map.nodes.find((x) => x.id === id);
+            const owner = n.group !== undefined ? map.groups.find((g) => g.id === n.group) : undefined;
+            return owner !== undefined
+                ? { id: owner.id, label: owner.label, status: groupStatus(map, owner.id) }
+                : { id: n.id, label: n.label, status: n.status };
+        };
+        const dedupe = (refs) => {
+            const seen = new Set();
+            const out = [];
+            for (const r of refs) {
+                if (seen.has(r.id))
+                    continue;
+                seen.add(r.id);
+                out.push(r);
+            }
+            return out;
+        };
+        return {
+            kind: 'group',
+            group,
+            status: groupStatus(map, group.id),
+            layerName: layerNameOf(group.layer),
+            members,
+            uses: dedupe(map.edges
+                .filter((e) => memberIds.has(e.from) && !memberIds.has(e.to))
+                .map((e) => rep(e.to))),
+            usedBy: dedupe(map.edges
+                .filter((e) => memberIds.has(e.to) && !memberIds.has(e.from))
+                .map((e) => rep(e.from))),
+        };
+    }
+    const node = map.nodes.find((n) => n.id === focusId);
+    if (!node)
+        return undefined;
+    const ref = (id, edgeLabel) => {
+        const n = map.nodes.find((x) => x.id === id);
+        return {
+            id,
+            label: n?.label ?? id,
+            status: n?.status ?? 'planned',
+            ...(edgeLabel !== undefined ? { edgeLabel } : {}),
+        };
+    };
+    const laneLabel = node.lane !== undefined ? map.lanes.find((l) => l.id === node.lane)?.label : undefined;
+    return {
+        kind: 'node',
+        node,
+        layerName: layerNameOf(node.layer),
+        ...(laneLabel !== undefined ? { laneLabel } : {}),
+        uses: map.edges.filter((e) => e.from === node.id).map((e) => ref(e.to, e.label)),
+        usedBy: map.edges.filter((e) => e.to === node.id).map((e) => ref(e.from, e.label)),
+    };
+}
+// ---------------------------------------------------------------------------
+// page-set semantics — which pages are siblings, and where a dive came from
+// ---------------------------------------------------------------------------
+/**
+ * Page slugs some node of any map dives into. A page referenced as a submap
+ * is interior detail — it is reached by diving through its linking node,
+ * never by sitting beside its parent as a sibling tab.
+ * @param maps - every known page's map (undefined entries are skipped).
+ * @returns the referenced submap slugs.
+ */
+export function submapRefs(maps) {
+    const refs = new Set();
+    for (const m of maps) {
+        for (const n of m?.nodes ?? [])
+            if (n.submap !== undefined)
+                refs.add(n.submap);
+    }
+    return refs;
+}
+/**
+ * Where a sub-map page was dived into from: the entry whose map links the
+ * page, plus the linking node's label. Derived by scan, so a breadcrumb
+ * survives any client restart with an empty dive stack.
+ * @param entries - known pages as (key, map) pairs; keys are caller-owned.
+ * @param pageId - the sub-map page's slug.
+ * @returns the linking entry's key and node label, or undefined for a top-level page.
+ */
+export function diveParent(entries, pageId) {
+    for (const [key, m] of entries) {
+        const node = m?.nodes.find((n) => n.submap === pageId);
+        if (node !== undefined)
+            return { parent: key, label: node.label };
+    }
+    return undefined;
+}
+/**
+ * The page a client shows when nobody asked for one: the most recently
+ * WRITTEN page — the ledger last touched is almost always the effort under
+ * way. Keys without a readable timestamp lose; an empty set answers the
+ * first key (caller-ordered: default page first, then slug order).
+ * @param keys - candidate page keys in the caller's fallback order.
+ * @param mtimeOf - last-written timestamp of a key, undefined when unknown.
+ * @returns the winning key, or undefined for an empty candidate set.
+ */
+export function mostRecentKey(keys, mtimeOf) {
+    let best;
+    let bestMtime = -Infinity;
+    for (const key of keys) {
+        const mtime = mtimeOf(key);
+        if (mtime !== undefined && mtime > bestMtime) {
+            best = key;
+            bestMtime = mtime;
+        }
+    }
+    return best ?? keys[0];
+}
+/**
+ * Sequence pages read like the classic diagram: time flows DOWNWARD, the
+ * earliest step right under the participant headers. The stored map keeps
+ * rank 0 = earliest with edges pointing later -> earlier ("later stands on
+ * earlier"); this derived value inverts the ranks and reverses the edges so
+ * unchanged top-down machinery draws top-down time — each wire now runs
+ * from the sender's moment down into the receiver's. Derived for rendering
+ * only, never persisted (same contract as aggregateMap).
+ */
+export function flipForSequence(map) {
+    if (map.kind !== 'sequence')
+        return map;
+    return {
+        ...map,
+        layers: map.layers.map((l) => ({ ...l, rank: -l.rank })),
+        edges: map.edges.map((e) => ({ from: e.to, to: e.from, ...(e.label !== undefined ? { label: e.label } : {}) })),
+    };
+}

package/lib/store/format.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Layer 1a — the state-file FORMAT of a MellosMap, pure of any I/O.
+ *
+ * This module owns the on-disk vocabulary (version, page-id grammar) and the
+ * two format promises every consumer relies on:
+ *
+ *   P1. Whatever parseMap accepts satisfies the structural invariants of
+ *       Layer 0. Parsing is done by REPLAYING the raw data through the domain
+ *       operations, so a hand-edited or corrupted file can never smuggle an
+ *       invariant violation into the process (validate at the boundary,
+ *       trust internal code afterwards).
+ *   F1. serializeMap is the inverse of parseMap for valid maps.
+ *
+ * No node:* imports — this module must load in a browser as-is. Filesystem
+ * concerns (atomic writes, page file listing, focus requests) live in
+ * ./store.ts, the Node-side half.
+ */
+import { type InvalidId, type MapError, type MellosMap, type Result } from '../domain/types.js';
+/** On-disk format version. Bump only with a documented migration. */
+export declare const STATE_FILE_VERSION = 1;
+export type PageId = string & {
+    readonly __brand: 'PageId';
+};
+export declare function makePageId(raw: string): Result<PageId, InvalidId>;
+export type StoreError = {
+    readonly kind: 'not-found';
+    readonly path: string;
+} | {
+    readonly kind: 'malformed-json';
+    readonly path: string;
+    readonly detail: string;
+} | {
+    readonly kind: 'bad-shape';
+    readonly path: string;
+    readonly detail: string;
+} | {
+    readonly kind: 'invariant-violation';
+    readonly path: string;
+    readonly violation: MapError;
+};
+export declare function describeStoreError(e: StoreError): string;
+/**
+ * Rebuild a MellosMap from untrusted raw data by replaying it through the
+ * Layer 0 operations (P1). Field order in the file does not matter; replay
+ * order (layers -> lanes -> groups -> nodes -> edges) supplies the required
+ * declaration order.
+ */
+export declare function parseMap(raw: unknown, path: string): Result<MellosMap, StoreError>;
+/** Serialize a map into the on-disk shape. Inverse of parseMap for valid maps (F1). */
+export declare function serializeMap(map: MellosMap): string;

package/lib/store/format.js

@@ -0,0 +1,215 @@
+/**
+ * Layer 1a — the state-file FORMAT of a MellosMap, pure of any I/O.
+ *
+ * This module owns the on-disk vocabulary (version, page-id grammar) and the
+ * two format promises every consumer relies on:
+ *
+ *   P1. Whatever parseMap accepts satisfies the structural invariants of
+ *       Layer 0. Parsing is done by REPLAYING the raw data through the domain
+ *       operations, so a hand-edited or corrupted file can never smuggle an
+ *       invariant violation into the process (validate at the boundary,
+ *       trust internal code afterwards).
+ *   F1. serializeMap is the inverse of parseMap for valid maps.
+ *
+ * No node:* imports — this module must load in a browser as-is. Filesystem
+ * concerns (atomic writes, page file listing, focus requests) live in
+ * ./store.ts, the Node-side half.
+ */
+import { declareGroup, declareLane, declareLayer, declareNode, linkNodes, setKind, setTitle, updateNode } from '../domain/ops.js';
+import { EMPTY_MAP, ID_RULE, ID_RULE_TEXT, describeMapError, err, makeGroupId, makeLaneId, makeLayerId, makeMapKind, makeNodeId, makeNodeKind, makeNodeStatus, makeSubmapRef, ok, } from '../domain/types.js';
+/** On-disk format version. Bump only with a documented migration. */
+export const STATE_FILE_VERSION = 1;
+export function makePageId(raw) {
+    return ID_RULE.test(raw) ? ok(raw) : err({ kind: 'invalid-id', raw, rule: ID_RULE_TEXT });
+}
+export function describeStoreError(e) {
+    switch (e.kind) {
+        case 'not-found':
+            return `no map file at ${e.path}`;
+        case 'malformed-json':
+            return `map file ${e.path} is not valid JSON: ${e.detail}`;
+        case 'bad-shape':
+            return `map file ${e.path} has an unexpected shape: ${e.detail}`;
+        case 'invariant-violation':
+            return `map file ${e.path} violates a structural invariant: ${describeMapError(e.violation)}`;
+    }
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function asArray(v) {
+    return Array.isArray(v) ? v : [];
+}
+function optionalString(v) {
+    return typeof v === 'string' ? v : undefined;
+}
+/**
+ * Rebuild a MellosMap from untrusted raw data by replaying it through the
+ * Layer 0 operations (P1). Field order in the file does not matter; replay
+ * order (layers -> lanes -> groups -> nodes -> edges) supplies the required
+ * declaration order.
+ */
+export function parseMap(raw, path) {
+    if (!isRecord(raw))
+        return err({ kind: 'bad-shape', path, detail: 'root is not an object' });
+    if (raw['version'] !== STATE_FILE_VERSION) {
+        return err({ kind: 'bad-shape', path, detail: `version is ${String(raw['version'])}, expected ${STATE_FILE_VERSION}` });
+    }
+    let map = EMPTY_MAP;
+    const title = optionalString(raw['title']);
+    if (title !== undefined)
+        map = setTitle(map, title);
+    const rawKind = optionalString(raw['kind']);
+    if (rawKind !== undefined) {
+        const kind = makeMapKind(rawKind);
+        if (!kind.ok)
+            return err({ kind: 'invariant-violation', path, violation: kind.error });
+        map = setKind(map, kind.value);
+    }
+    for (const [i, rawLayer] of asArray(raw['layers']).entries()) {
+        if (!isRecord(rawLayer))
+            return err({ kind: 'bad-shape', path, detail: `layers[${i}] is not an object` });
+        const id = makeLayerId(String(rawLayer['id'] ?? ''));
+        if (!id.ok)
+            return err({ kind: 'invariant-violation', path, violation: id.error });
+        const name = optionalString(rawLayer['name']);
+        const rank = rawLayer['rank'];
+        if (name === undefined || typeof rank !== 'number' || !Number.isInteger(rank)) {
+            return err({ kind: 'bad-shape', path, detail: `layers[${i}] needs a string name and an integer rank` });
+        }
+        const next = declareLayer(map, { id: id.value, name, rank });
+        if (!next.ok)
+            return err({ kind: 'invariant-violation', path, violation: next.error });
+        map = next.value;
+    }
+    for (const [i, rawLane] of asArray(raw['lanes']).entries()) {
+        if (!isRecord(rawLane))
+            return err({ kind: 'bad-shape', path, detail: `lanes[${i}] is not an object` });
+        const id = makeLaneId(String(rawLane['id'] ?? ''));
+        if (!id.ok)
+            return err({ kind: 'invariant-violation', path, violation: id.error });
+        const label = optionalString(rawLane['label']);
+        if (label === undefined)
+            return err({ kind: 'bad-shape', path, detail: `lanes[${i}] needs a string label` });
+        const declared = declareLane(map, { id: id.value, label });
+        if (!declared.ok)
+            return err({ kind: 'invariant-violation', path, violation: declared.error });
+        map = declared.value;
+    }
+    for (const [i, rawGroup] of asArray(raw['groups']).entries()) {
+        if (!isRecord(rawGroup))
+            return err({ kind: 'bad-shape', path, detail: `groups[${i}] is not an object` });
+        const id = makeGroupId(String(rawGroup['id'] ?? ''));
+        if (!id.ok)
+            return err({ kind: 'invariant-violation', path, violation: id.error });
+        const layer = makeLayerId(String(rawGroup['layer'] ?? ''));
+        if (!layer.ok)
+            return err({ kind: 'invariant-violation', path, violation: layer.error });
+        const label = optionalString(rawGroup['label']);
+        if (label === undefined)
+            return err({ kind: 'bad-shape', path, detail: `groups[${i}] needs a string label` });
+        const declared = declareGroup(map, { id: id.value, label, layer: layer.value });
+        if (!declared.ok)
+            return err({ kind: 'invariant-violation', path, violation: declared.error });
+        map = declared.value;
+    }
+    for (const [i, rawNode] of asArray(raw['nodes']).entries()) {
+        if (!isRecord(rawNode))
+            return err({ kind: 'bad-shape', path, detail: `nodes[${i}] is not an object` });
+        const id = makeNodeId(String(rawNode['id'] ?? ''));
+        if (!id.ok)
+            return err({ kind: 'invariant-violation', path, violation: id.error });
+        const layer = makeLayerId(String(rawNode['layer'] ?? ''));
+        if (!layer.ok)
+            return err({ kind: 'invariant-violation', path, violation: layer.error });
+        const status = makeNodeStatus(String(rawNode['status'] ?? ''));
+        if (!status.ok)
+            return err({ kind: 'invariant-violation', path, violation: status.error });
+        const label = optionalString(rawNode['label']);
+        if (label === undefined)
+            return err({ kind: 'bad-shape', path, detail: `nodes[${i}] needs a string label` });
+        const detail = optionalString(rawNode['detail']);
+        const rawGroup = optionalString(rawNode['group']);
+        let group;
+        if (rawGroup !== undefined) {
+            const made = makeGroupId(rawGroup);
+            if (!made.ok)
+                return err({ kind: 'invariant-violation', path, violation: made.error });
+            group = made.value;
+        }
+        const rawNodeKind = optionalString(rawNode['kind']);
+        let nodeKind;
+        if (rawNodeKind !== undefined) {
+            const made = makeNodeKind(rawNodeKind);
+            if (!made.ok)
+                return err({ kind: 'invariant-violation', path, violation: made.error });
+            nodeKind = made.value;
+        }
+        const rawLane = optionalString(rawNode['lane']);
+        let lane;
+        if (rawLane !== undefined) {
+            const made = makeLaneId(rawLane);
+            if (!made.ok)
+                return err({ kind: 'invariant-violation', path, violation: made.error });
+            lane = made.value;
+        }
+        const rawSubmap = optionalString(rawNode['submap']);
+        let submap;
+        if (rawSubmap !== undefined) {
+            const made = makeSubmapRef(rawSubmap);
+            if (!made.ok)
+                return err({ kind: 'invariant-violation', path, violation: made.error });
+            submap = made.value;
+        }
+        const declared = declareNode(map, {
+            id: id.value,
+            label,
+            layer: layer.value,
+            status: status.value,
+            ...(detail !== undefined ? { detail } : {}),
+            ...(group !== undefined ? { group } : {}),
+            ...(nodeKind !== undefined ? { kind: nodeKind } : {}),
+            ...(lane !== undefined ? { lane } : {}),
+            ...(submap !== undefined ? { submap } : {}),
+        });
+        if (!declared.ok)
+            return err({ kind: 'invariant-violation', path, violation: declared.error });
+        map = declared.value;
+        const evidence = optionalString(rawNode['evidence']);
+        if (evidence !== undefined) {
+            const updated = updateNode(map, { id: id.value, evidence });
+            if (!updated.ok)
+                return err({ kind: 'invariant-violation', path, violation: updated.error });
+            map = updated.value;
+        }
+    }
+    for (const [i, rawEdge] of asArray(raw['edges']).entries()) {
+        if (!isRecord(rawEdge))
+            return err({ kind: 'bad-shape', path, detail: `edges[${i}] is not an object` });
+        const from = makeNodeId(String(rawEdge['from'] ?? ''));
+        if (!from.ok)
+            return err({ kind: 'invariant-violation', path, violation: from.error });
+        const to = makeNodeId(String(rawEdge['to'] ?? ''));
+        if (!to.ok)
+            return err({ kind: 'invariant-violation', path, violation: to.error });
+        const linked = linkNodes(map, from.value, to.value, optionalString(rawEdge['label']));
+        if (!linked.ok)
+            return err({ kind: 'invariant-violation', path, violation: linked.error });
+        map = linked.value;
+    }
+    return ok(map);
+}
+/** Serialize a map into the on-disk shape. Inverse of parseMap for valid maps (F1). */
+export function serializeMap(map) {
+    const body = {
+        version: STATE_FILE_VERSION,
+        ...(map.title !== undefined ? { title: map.title } : {}),
+        ...(map.kind !== undefined ? { kind: map.kind } : {}),
+        layers: map.layers,
+        ...(map.lanes.length > 0 ? { lanes: map.lanes } : {}),
+        ...(map.groups.length > 0 ? { groups: map.groups } : {}),
+        nodes: map.nodes,
+        edges: map.edges,
+    };
+    return JSON.stringify(body, null, 2) + '\n';
+}