mellos-mapping 0.18.0 → 0.20.0

package/lib/domain/ops.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Layer 0 — pure operations on a MellosMap.
+ *
+ * Every operation follows validate -> prepare -> commit: all refusals happen
+ * before any new value is built, and the commit expression can no longer
+ * fail. Inputs are never mutated; the result always carries a fresh map.
+ *
+ * These functions enforce the structural invariants I1-I9 documented in
+ * types.ts and nothing else. In particular there are no workflow rules here:
+ * any status may be set at any time, in any order. Discipline lives with the
+ * caller; this layer only keeps the map structurally true.
+ */
+import { type GroupId, type LaneId, type LayerId, type MapError, type MapKind, type MellosMap, type NodeId, type NodeKind, type NodeStatus, type Result, type SubmapRef } from './types.js';
+/** Set or replace the map title. */
+export declare function setTitle(map: MellosMap, title: string): MellosMap;
+/** Set or replace the map kind (presentation intent — never structural). */
+export declare function setKind(map: MellosMap, kind: MapKind): MellosMap;
+export interface DeclareLaneInput {
+    readonly id: LaneId;
+    readonly label: string;
+}
+/** Add a new lane (I8). Declaration order is left-to-right render order. */
+export declare function declareLane(map: MellosMap, input: DeclareLaneInput): Result<MellosMap, MapError>;
+/**
+ * Remove a lane.
+ * Postcondition: former members stay on the map, merely off-lane — removing
+ * a column label never destroys work records (same contract as removeGroup).
+ */
+export declare function removeLane(map: MellosMap, id: LaneId): Result<MellosMap, MapError>;
+export interface DeclareLayerInput {
+    readonly id: LayerId;
+    readonly name: string;
+    readonly rank: number;
+}
+/** Add a new band. Refuses duplicate ids and duplicate ranks (I1). */
+export declare function declareLayer(map: MellosMap, input: DeclareLayerInput): Result<MellosMap, MapError>;
+export interface DeclareGroupInput {
+    readonly id: GroupId;
+    readonly label: string;
+    readonly layer: LayerId;
+}
+/** Add a new group to an existing band (I6). */
+export declare function declareGroup(map: MellosMap, input: DeclareGroupInput): Result<MellosMap, MapError>;
+/** Rename a group. */
+export declare function updateGroup(map: MellosMap, id: GroupId, label: string): Result<MellosMap, MapError>;
+/**
+ * Remove a group.
+ * Postcondition: former members stay on the map, merely ungrouped — removing
+ * a cluster label never destroys work records.
+ */
+export declare function removeGroup(map: MellosMap, id: GroupId): Result<MellosMap, MapError>;
+/**
+ * Derived, never stored: a group's aggregate status. Any regressed member
+ * cracks the group; else any spinner spins it; else all-done (non-empty)
+ * completes it; anything else is planned.
+ */
+export declare function groupStatus(map: MellosMap, id: GroupId): NodeStatus;
+/** Derived, never stored: the whole map's aggregate status (same rules as groupStatus). */
+export declare function mapStatus(map: MellosMap): NodeStatus;
+export interface DeclareNodeInput {
+    readonly id: NodeId;
+    readonly label: string;
+    readonly layer: LayerId;
+    readonly status?: NodeStatus;
+    readonly detail?: string;
+    readonly group?: GroupId;
+    readonly kind?: NodeKind;
+    readonly lane?: LaneId;
+    readonly submap?: SubmapRef;
+}
+/**
+ * Add a new node to an existing band (I2, I3), optionally joining a same-band
+ * group (I7) and/or an existing lane (I9).
+ */
+export declare function declareNode(map: MellosMap, input: DeclareNodeInput): Result<MellosMap, MapError>;
+/**
+ * Add the dependency edge `from USES to`, optionally labeled with what flows
+ * along it. Refuses self-edges, duplicates and any edge that does not point
+ * strictly downward (I4).
+ */
+export declare function linkNodes(map: MellosMap, from: NodeId, to: NodeId, label?: string): Result<MellosMap, MapError>;
+export interface UpdateNodeInput {
+    readonly id: NodeId;
+    readonly status?: NodeStatus;
+    readonly label?: string;
+    readonly evidence?: string;
+    readonly detail?: string;
+    /** A GroupId joins that group (I7 validated); null leaves the current group. */
+    readonly group?: GroupId | null;
+    /** A NodeKind sets the presentation kind; null clears it. */
+    readonly kind?: NodeKind | null;
+    /** A LaneId joins that lane (I9 validated); null leaves the current lane. */
+    readonly lane?: LaneId | null;
+    /** A SubmapRef links a child map page; null unlinks it. */
+    readonly submap?: SubmapRef | null;
+}
+/**
+ * Update a node's status, label, evidence, design detail, group membership,
+ * kind and/or lane. Absent fields are left untouched. No transition rules:
+ * the ledger records whatever the caller reports, whenever they report it.
+ */
+export declare function updateNode(map: MellosMap, input: UpdateNodeInput): Result<MellosMap, MapError>;
+/**
+ * Remove a node.
+ * Postcondition (explicit part of this contract): every edge touching the
+ * node is removed with it — a map never holds edges to missing nodes.
+ */
+export declare function removeNode(map: MellosMap, id: NodeId): Result<MellosMap, MapError>;
+/** Remove one dependency edge. */
+export declare function removeEdge(map: MellosMap, from: NodeId, to: NodeId): Result<MellosMap, MapError>;
+/** Remove a band. Only empty bands may go — neither a node (I2) nor a group (I6) may be orphaned. */
+export declare function removeLayer(map: MellosMap, id: LayerId): Result<MellosMap, MapError>;

package/lib/domain/ops.js

@@ -0,0 +1,253 @@
+/**
+ * Layer 0 — pure operations on a MellosMap.
+ *
+ * Every operation follows validate -> prepare -> commit: all refusals happen
+ * before any new value is built, and the commit expression can no longer
+ * fail. Inputs are never mutated; the result always carries a fresh map.
+ *
+ * These functions enforce the structural invariants I1-I9 documented in
+ * types.ts and nothing else. In particular there are no workflow rules here:
+ * any status may be set at any time, in any order. Discipline lives with the
+ * caller; this layer only keeps the map structurally true.
+ */
+import { err, ok, } from './types.js';
+function findLayer(map, id) {
+    return map.layers.find((l) => l.id === id);
+}
+function findNode(map, id) {
+    return map.nodes.find((n) => n.id === id);
+}
+function findGroup(map, id) {
+    return map.groups.find((g) => g.id === id);
+}
+/** Validate that `node` may join `group` (I7): the group exists on the node's own band. */
+function checkMembership(map, node, nodeLayer, group) {
+    const g = findGroup(map, group);
+    if (!g)
+        return { kind: 'unknown-group', id: group };
+    if (g.layer !== nodeLayer)
+        return { kind: 'group-layer-mismatch', node, nodeLayer, group, groupLayer: g.layer };
+    return undefined;
+}
+function hasEdge(map, from, to) {
+    return map.edges.some((e) => e.from === from && e.to === to);
+}
+/** Set or replace the map title. */
+export function setTitle(map, title) {
+    return { ...map, title };
+}
+/** Set or replace the map kind (presentation intent — never structural). */
+export function setKind(map, kind) {
+    return { ...map, kind };
+}
+function findLane(map, id) {
+    return map.lanes.find((l) => l.id === id);
+}
+/** Add a new lane (I8). Declaration order is left-to-right render order. */
+export function declareLane(map, input) {
+    if (findLane(map, input.id))
+        return err({ kind: 'duplicate-lane', id: input.id });
+    return ok({ ...map, lanes: [...map.lanes, { id: input.id, label: input.label }] });
+}
+/**
+ * Remove a lane.
+ * Postcondition: former members stay on the map, merely off-lane — removing
+ * a column label never destroys work records (same contract as removeGroup).
+ */
+export function removeLane(map, id) {
+    if (!findLane(map, id))
+        return err({ kind: 'unknown-lane', id });
+    return ok({
+        ...map,
+        lanes: map.lanes.filter((l) => l.id !== id),
+        nodes: map.nodes.map((n) => {
+            if (n.lane !== id)
+                return n;
+            const { lane: _dropped, ...rest } = n;
+            return rest;
+        }),
+    });
+}
+/** Add a new band. Refuses duplicate ids and duplicate ranks (I1). */
+export function declareLayer(map, input) {
+    if (findLayer(map, input.id))
+        return err({ kind: 'duplicate-layer', id: input.id });
+    const rankHolder = map.layers.find((l) => l.rank === input.rank);
+    if (rankHolder)
+        return err({ kind: 'duplicate-rank', rank: input.rank, existing: rankHolder.id });
+    return ok({ ...map, layers: [...map.layers, { id: input.id, name: input.name, rank: input.rank }] });
+}
+/** Add a new group to an existing band (I6). */
+export function declareGroup(map, input) {
+    if (findGroup(map, input.id))
+        return err({ kind: 'duplicate-group', id: input.id });
+    if (!findLayer(map, input.layer))
+        return err({ kind: 'unknown-layer', id: input.layer });
+    return ok({ ...map, groups: [...map.groups, { id: input.id, label: input.label, layer: input.layer }] });
+}
+/** Rename a group. */
+export function updateGroup(map, id, label) {
+    if (!findGroup(map, id))
+        return err({ kind: 'unknown-group', id });
+    return ok({ ...map, groups: map.groups.map((g) => (g.id === id ? { ...g, label } : g)) });
+}
+/**
+ * Remove a group.
+ * Postcondition: former members stay on the map, merely ungrouped — removing
+ * a cluster label never destroys work records.
+ */
+export function removeGroup(map, id) {
+    if (!findGroup(map, id))
+        return err({ kind: 'unknown-group', id });
+    return ok({
+        ...map,
+        groups: map.groups.filter((g) => g.id !== id),
+        nodes: map.nodes.map((n) => {
+            if (n.group !== id)
+                return n;
+            const { group: _dropped, ...rest } = n;
+            return rest;
+        }),
+    });
+}
+/** Aggregate status over a set of nodes: regression trumps, then activity, then completion. */
+function aggregateStatus(nodes) {
+    if (nodes.some((n) => n.status === 'regressed'))
+        return 'regressed';
+    if (nodes.some((n) => n.status === 'in-progress'))
+        return 'in-progress';
+    if (nodes.length > 0 && nodes.every((n) => n.status === 'done'))
+        return 'done';
+    return 'planned';
+}
+/**
+ * Derived, never stored: a group's aggregate status. Any regressed member
+ * cracks the group; else any spinner spins it; else all-done (non-empty)
+ * completes it; anything else is planned.
+ */
+export function groupStatus(map, id) {
+    return aggregateStatus(map.nodes.filter((n) => n.group === id));
+}
+/** Derived, never stored: the whole map's aggregate status (same rules as groupStatus). */
+export function mapStatus(map) {
+    return aggregateStatus(map.nodes);
+}
+/**
+ * Add a new node to an existing band (I2, I3), optionally joining a same-band
+ * group (I7) and/or an existing lane (I9).
+ */
+export function declareNode(map, input) {
+    if (findNode(map, input.id))
+        return err({ kind: 'duplicate-node', id: input.id });
+    if (!findLayer(map, input.layer))
+        return err({ kind: 'unknown-layer', id: input.layer });
+    if (input.group !== undefined) {
+        const bad = checkMembership(map, input.id, input.layer, input.group);
+        if (bad)
+            return err(bad);
+    }
+    if (input.lane !== undefined && !findLane(map, input.lane))
+        return err({ kind: 'unknown-lane', id: input.lane });
+    const node = {
+        id: input.id,
+        label: input.label,
+        layer: input.layer,
+        status: input.status ?? 'planned',
+        ...(input.detail !== undefined ? { detail: input.detail } : {}),
+        ...(input.group !== undefined ? { group: input.group } : {}),
+        ...(input.kind !== undefined ? { kind: input.kind } : {}),
+        ...(input.lane !== undefined ? { lane: input.lane } : {}),
+        ...(input.submap !== undefined ? { submap: input.submap } : {}),
+    };
+    return ok({ ...map, nodes: [...map.nodes, node] });
+}
+/**
+ * Add the dependency edge `from USES to`, optionally labeled with what flows
+ * along it. Refuses self-edges, duplicates and any edge that does not point
+ * strictly downward (I4).
+ */
+export function linkNodes(map, from, to, label) {
+    if (from === to)
+        return err({ kind: 'self-edge', id: from });
+    const fromNode = findNode(map, from);
+    if (!fromNode)
+        return err({ kind: 'unknown-node', id: from });
+    const toNode = findNode(map, to);
+    if (!toNode)
+        return err({ kind: 'unknown-node', id: to });
+    if (hasEdge(map, from, to))
+        return err({ kind: 'duplicate-edge', from, to });
+    // Layers are guaranteed to exist for stored nodes (I2), so the lookups cannot miss.
+    const fromRank = findLayer(map, fromNode.layer).rank;
+    const toRank = findLayer(map, toNode.layer).rank;
+    if (fromRank <= toRank)
+        return err({ kind: 'edge-not-downward', from, fromRank, to, toRank });
+    return ok({ ...map, edges: [...map.edges, { from, to, ...(label !== undefined ? { label } : {}) }] });
+}
+/**
+ * Update a node's status, label, evidence, design detail, group membership,
+ * kind and/or lane. Absent fields are left untouched. No transition rules:
+ * the ledger records whatever the caller reports, whenever they report it.
+ */
+export function updateNode(map, input) {
+    const node = findNode(map, input.id);
+    if (!node)
+        return err({ kind: 'unknown-node', id: input.id });
+    if (input.group !== undefined && input.group !== null) {
+        const bad = checkMembership(map, node.id, node.layer, input.group);
+        if (bad)
+            return err(bad);
+    }
+    if (input.lane !== undefined && input.lane !== null && !findLane(map, input.lane)) {
+        return err({ kind: 'unknown-lane', id: input.lane });
+    }
+    const { group: currentGroup, kind: currentKind, lane: currentLane, submap: currentSubmap, ...bare } = node;
+    const nextGroup = input.group === undefined ? currentGroup : input.group === null ? undefined : input.group;
+    const nextKind = input.kind === undefined ? currentKind : input.kind === null ? undefined : input.kind;
+    const nextLane = input.lane === undefined ? currentLane : input.lane === null ? undefined : input.lane;
+    const nextSubmap = input.submap === undefined ? currentSubmap : input.submap === null ? undefined : input.submap;
+    const updated = {
+        ...bare,
+        ...(nextGroup !== undefined ? { group: nextGroup } : {}),
+        ...(nextKind !== undefined ? { kind: nextKind } : {}),
+        ...(nextLane !== undefined ? { lane: nextLane } : {}),
+        ...(nextSubmap !== undefined ? { submap: nextSubmap } : {}),
+        ...(input.status !== undefined ? { status: input.status } : {}),
+        ...(input.label !== undefined ? { label: input.label } : {}),
+        ...(input.evidence !== undefined ? { evidence: input.evidence } : {}),
+        ...(input.detail !== undefined ? { detail: input.detail } : {}),
+    };
+    return ok({ ...map, nodes: map.nodes.map((n) => (n.id === input.id ? updated : n)) });
+}
+/**
+ * Remove a node.
+ * Postcondition (explicit part of this contract): every edge touching the
+ * node is removed with it — a map never holds edges to missing nodes.
+ */
+export function removeNode(map, id) {
+    if (!findNode(map, id))
+        return err({ kind: 'unknown-node', id });
+    return ok({
+        ...map,
+        nodes: map.nodes.filter((n) => n.id !== id),
+        edges: map.edges.filter((e) => e.from !== id && e.to !== id),
+    });
+}
+/** Remove one dependency edge. */
+export function removeEdge(map, from, to) {
+    if (!hasEdge(map, from, to))
+        return err({ kind: 'unknown-edge', from, to });
+    return ok({ ...map, edges: map.edges.filter((e) => !(e.from === from && e.to === to)) });
+}
+/** Remove a band. Only empty bands may go — neither a node (I2) nor a group (I6) may be orphaned. */
+export function removeLayer(map, id) {
+    if (!findLayer(map, id))
+        return err({ kind: 'unknown-layer', id });
+    const occupant = map.nodes.find((n) => n.layer === id);
+    if (occupant)
+        return err({ kind: 'layer-not-empty', id, occupant: occupant.id });
+    const groupOccupant = map.groups.find((g) => g.layer === id);
+    if (groupOccupant)
+        return err({ kind: 'layer-holds-group', id, occupant: groupOccupant.id });
+    return ok({ ...map, layers: map.layers.filter((l) => l.id !== id) });
+}

package/lib/domain/types.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Layer 0 — domain model of a Mellos Map.
+ *
+ * A Mellos Map is a layered dependency map of a system under construction:
+ * horizontal layer bands ordered by rank (rank 0 = bottom = most primitive),
+ * nodes living inside exactly one band, and dependency edges that may only
+ * point STRICTLY DOWNWARD across bands.
+ *
+ * Structural invariants owned by this layer (and only these — the map is a
+ * ledger, not a judge; it records work honestly and never polices workflow):
+ *   I1. Layer ids are unique; layer ranks are unique (bands are totally ordered).
+ *   I2. Every node belongs to exactly one existing layer.
+ *   I3. Node ids are unique.
+ *   I4. An edge `from -> to` means "from USES to" and requires
+ *       rank(layer(from)) > rank(layer(to)).
+ *       Corollary: the graph is acyclic by construction — every edge strictly
+ *       decreases rank, so no cycle detection is ever needed.
+ *       Same-layer edges are rejected on purpose: if A needs a sibling B,
+ *       either B is really a lower-layer concept or A and B are one node.
+ *   I5. Node status is one of the closed vocabulary in NODE_STATUSES.
+ *   I6. Group ids are unique; every group lives in an existing layer.
+ *   I7. A node's group, when set, exists and lives in the node's own layer —
+ *       a group is band-local cohesion (a labeled subsystem the far zoom can
+ *       render); structure ACROSS bands is what layers and edges express.
+ *   I8. Lane ids are unique. A lane is a named vertical column CROSSING all
+ *       bands (a sequence participant, a swim lane); lane declaration order
+ *       is left-to-right render order.
+ *   I9. A node's lane, when set, exists.
+ *
+ * The map kind (dev | architecture | dataflow | behavior-tree | sequence) is
+ * presentation intent, not structure: every kind shares the same invariants,
+ * and the renderer alone decides what the kind changes (legend, neutral
+ * status skins, lane emphasis).
+ *
+ * Everything here is immutable data plus pure types. No I/O, no clock, no
+ * process state.
+ */
+/** Result type — expected failures are values, never exceptions. */
+export type Result<T, E> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: E;
+};
+export declare const ok: <T>(value: T) => {
+    ok: true;
+    value: T;
+};
+export declare const err: <E>(error: E) => {
+    ok: false;
+    error: E;
+};
+/** Ids are branded slugs, never raw strings, so a NodeId cannot leak into a LayerId slot. */
+export type NodeId = string & {
+    readonly __brand: 'NodeId';
+};
+export type LayerId = string & {
+    readonly __brand: 'LayerId';
+};
+export type GroupId = string & {
+    readonly __brand: 'GroupId';
+};
+export type LaneId = string & {
+    readonly __brand: 'LaneId';
+};
+/** Open per-node vocabulary (selector, action, db …); known kinds get a glyph in the renderer. */
+export type NodeKind = string & {
+    readonly __brand: 'NodeKind';
+};
+/**
+ * Wiki-style link from a node to a child map's page. No existence invariant
+ * on purpose: declaring the reference before the page is legal — the pane
+ * simply has nowhere to dive until the page appears.
+ */
+export type SubmapRef = string & {
+    readonly __brand: 'SubmapRef';
+};
+/** The shared slug grammar for every id in the system (nodes, layers, groups, lanes, kinds, store pages). */
+export declare const ID_RULE: RegExp;
+export declare const ID_RULE_TEXT = "lowercase letters, digits and dashes, starting with a letter or digit, 1-64 chars";
+export type InvalidId = {
+    readonly kind: 'invalid-id';
+    readonly raw: string;
+    readonly rule: string;
+};
+export declare function makeNodeId(raw: string): Result<NodeId, InvalidId>;
+export declare function makeLayerId(raw: string): Result<LayerId, InvalidId>;
+export declare function makeGroupId(raw: string): Result<GroupId, InvalidId>;
+export declare function makeLaneId(raw: string): Result<LaneId, InvalidId>;
+export declare function makeNodeKind(raw: string): Result<NodeKind, InvalidId>;
+export declare function makeSubmapRef(raw: string): Result<SubmapRef, InvalidId>;
+/**
+ * Closed vocabulary of map kinds — the diagram's presentation intent.
+ * 'dev' (the default) is the progress ledger; the rest are documentation
+ * diagrams rendered with neutral skins. Structure is identical for all.
+ */
+export declare const MAP_KINDS: readonly ["dev", "architecture", "dataflow", "behavior-tree", "sequence"];
+export type MapKind = (typeof MAP_KINDS)[number];
+export declare function makeMapKind(raw: string): Result<MapKind, {
+    kind: 'invalid-map-kind';
+    raw: string;
+}>;
+/** Closed status vocabulary. Transitions are NOT policed — see module header. */
+export declare const NODE_STATUSES: readonly ["planned", "in-progress", "done", "regressed"];
+export type NodeStatus = (typeof NODE_STATUSES)[number];
+export declare function makeNodeStatus(raw: string): Result<NodeStatus, {
+    kind: 'invalid-status';
+    raw: string;
+}>;
+/** A horizontal band. rank 0 is the bottom (most primitive) band. */
+export interface MapLayer {
+    readonly id: LayerId;
+    readonly name: string;
+    readonly rank: number;
+}
+/**
+ * A labeled cluster of same-band nodes — a subsystem. The far zoom renders
+ * groups instead of members, so the overview keeps meaningful names. A
+ * group's status is always DERIVED from its members (see groupStatus),
+ * never stored.
+ */
+export interface MapGroup {
+    readonly id: GroupId;
+    readonly label: string;
+    readonly layer: LayerId;
+}
+/**
+ * A named vertical column crossing all bands (I8) — a sequence participant
+ * or an architecture swim lane. Declaration order is left-to-right.
+ */
+export interface MapLane {
+    readonly id: LaneId;
+    readonly label: string;
+}
+/** A unit of work living in exactly one band. */
+export interface MapNode {
+    readonly id: NodeId;
+    readonly label: string;
+    readonly layer: LayerId;
+    readonly status: NodeStatus;
+    /** Verification evidence for `done`, or the observed breakage for `regressed`. */
+    readonly evidence?: string;
+    /** Design notes: responsibility, contract, key decisions. Free text. */
+    readonly detail?: string;
+    /** Membership in a same-band group (I7), for the aggregated far zoom. */
+    readonly group?: GroupId;
+    /** Per-node kind (selector, action, db …); known kinds render as a glyph prefix. */
+    readonly kind?: NodeKind;
+    /** Column membership (I9), for laned kinds such as sequence. */
+    readonly lane?: LaneId;
+    /** Child map page: the pane badges the node ⊞ and double-click dives in. */
+    readonly submap?: SubmapRef;
+}
+/** `from` USES `to`. Must point strictly downward (invariant I4). */
+export interface DepEdge {
+    readonly from: NodeId;
+    readonly to: NodeId;
+    /** What flows along the edge: a protocol, a message, a data name. */
+    readonly label?: string;
+}
+/** The whole map. A plain immutable value — operations return new maps. */
+export interface MellosMap {
+    readonly title?: string;
+    /** Presentation intent; absent means 'dev' (the progress ledger). */
+    readonly kind?: MapKind;
+    readonly layers: readonly MapLayer[];
+    readonly groups: readonly MapGroup[];
+    readonly lanes: readonly MapLane[];
+    readonly nodes: readonly MapNode[];
+    readonly edges: readonly DepEdge[];
+}
+export declare const EMPTY_MAP: MellosMap;
+/** Every way an operation can be refused, as data. */
+export type MapError = InvalidId | {
+    readonly kind: 'invalid-status';
+    readonly raw: string;
+} | {
+    readonly kind: 'duplicate-layer';
+    readonly id: LayerId;
+} | {
+    readonly kind: 'duplicate-rank';
+    readonly rank: number;
+    readonly existing: LayerId;
+} | {
+    readonly kind: 'duplicate-node';
+    readonly id: NodeId;
+} | {
+    readonly kind: 'unknown-layer';
+    readonly id: LayerId;
+} | {
+    readonly kind: 'unknown-node';
+    readonly id: NodeId;
+} | {
+    readonly kind: 'duplicate-edge';
+    readonly from: NodeId;
+    readonly to: NodeId;
+} | {
+    readonly kind: 'unknown-edge';
+    readonly from: NodeId;
+    readonly to: NodeId;
+} | {
+    readonly kind: 'self-edge';
+    readonly id: NodeId;
+} | {
+    readonly kind: 'duplicate-group';
+    readonly id: GroupId;
+} | {
+    readonly kind: 'unknown-group';
+    readonly id: GroupId;
+} | {
+    readonly kind: 'invalid-map-kind';
+    readonly raw: string;
+} | {
+    readonly kind: 'duplicate-lane';
+    readonly id: LaneId;
+} | {
+    readonly kind: 'unknown-lane';
+    readonly id: LaneId;
+} | {
+    readonly kind: 'group-layer-mismatch';
+    readonly node: NodeId;
+    readonly nodeLayer: LayerId;
+    readonly group: GroupId;
+    readonly groupLayer: LayerId;
+} | {
+    readonly kind: 'layer-not-empty';
+    readonly id: LayerId;
+    readonly occupant: NodeId;
+} | {
+    readonly kind: 'layer-holds-group';
+    readonly id: LayerId;
+    readonly occupant: GroupId;
+} | {
+    readonly kind: 'edge-not-downward';
+    readonly from: NodeId;
+    readonly fromRank: number;
+    readonly to: NodeId;
+    readonly toRank: number;
+};
+/** Human-readable rendering of a MapError, for tool results and logs. */
+export declare function describeMapError(e: MapError): string;