mellos-mapping 0.20.0 → 0.20.2

package/lib/domain/ops.d.ts

@@ -5,14 +5,25 @@
  * 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
+ * These functions enforce the structural invariants I1-I10 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.
+ *
+ * Every declared thing can also be REVISED, because a ghost design is a
+ * hypothesis and revising it is honest work: a node moves band (moveNode), a
+ * band is renamed or re-ordered (updateLayer), a group or lane is relabeled
+ * (updateGroup, updateLane), and every optional field a node carries can be
+ * cleared as explicitly as it was set (null, never an empty string).
+ */
+import { type GroupId, type LaneId, type LayerId, type MapError, type MapKind, type MellosMap, type NodeId, type NodeKind, type NodeStatus, type Rank, type Result, type SubmapRef } from './types.js';
+/**
+ * Set, replace or clear the map title.
+ * @param title - the new title; null (or an explicit undefined) removes the
+ *   field entirely, so a cleared title serializes as an absent key rather
+ *   than as an empty string nobody can tell from a real one.
  */
-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;
+export declare function setTitle(map: MellosMap, title: string | null | undefined): MellosMap;
 /** Set or replace the map kind (presentation intent — never structural). */
 export declare function setKind(map: MellosMap, kind: MapKind): MellosMap;
 export interface DeclareLaneInput {
@@ -21,6 +32,8 @@ export interface DeclareLaneInput {
 }
 /** Add a new lane (I8). Declaration order is left-to-right render order. */
 export declare function declareLane(map: MellosMap, input: DeclareLaneInput): Result<MellosMap, MapError>;
+/** Relabel a lane. The column keeps its id, its order and its members. */
+export declare function updateLane(map: MellosMap, id: LaneId, label: string): Result<MellosMap, MapError>;
 /**
  * Remove a lane.
  * Postcondition: former members stay on the map, merely off-lane — removing
@@ -30,16 +43,34 @@ export declare function removeLane(map: MellosMap, id: LaneId): Result<MellosMap
 export interface DeclareLayerInput {
     readonly id: LayerId;
     readonly name: string;
-    readonly rank: number;
+    readonly rank: Rank;
 }
 /** Add a new band. Refuses duplicate ids and duplicate ranks (I1). */
 export declare function declareLayer(map: MellosMap, input: DeclareLayerInput): Result<MellosMap, MapError>;
+export interface UpdateLayerInput {
+    readonly name?: string;
+    readonly rank?: Rank;
+}
+/**
+ * Rename a band and/or move it in the vertical order. Absent fields are left
+ * untouched; the band keeps its id and its occupants either way.
+ *
+ * A rank change is the one revision that can invalidate the whole graph, so
+ * it is validated against the map as a whole before anything changes:
+ *   - the new rank is free (I1) — bands stay totally ordered;
+ *   - EVERY edge, not only the ones touching this band, still points
+ *     strictly downward under the new order (I4). Re-ranking a band moves
+ *     all of its nodes at once, so an edge two bands away can be the one
+ *     that breaks; the refusal names it.
+ * @returns the reordered map, or the first refusal.
+ */
+export declare function updateLayer(map: MellosMap, id: LayerId, input: UpdateLayerInput): Result<MellosMap, MapError>;
 export interface DeclareGroupInput {
     readonly id: GroupId;
     readonly label: string;
     readonly layer: LayerId;
 }
-/** Add a new group to an existing band (I6). */
+/** Add a new group to an existing band (I6), under an id no node holds (I10). */
 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>;
@@ -62,6 +93,12 @@ export interface DeclareNodeInput {
     readonly label: string;
     readonly layer: LayerId;
     readonly status?: NodeStatus;
+    /**
+     * Verification evidence, for a node declared straight into `done` — work
+     * already finished when the map is drawn is as entitled to its proof as
+     * work finished under the map's eyes.
+     */
+    readonly evidence?: string;
     readonly detail?: string;
     readonly group?: GroupId;
     readonly kind?: NodeKind;
@@ -69,8 +106,9 @@ export interface DeclareNodeInput {
     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).
+ * Add a new node to an existing band (I2, I3) under an id no group holds
+ * (I10), optionally joining a same-band group (I7) and/or an existing lane
+ * (I9).
  */
 export declare function declareNode(map: MellosMap, input: DeclareNodeInput): Result<MellosMap, MapError>;
 /**
@@ -83,8 +121,10 @@ export interface UpdateNodeInput {
     readonly id: NodeId;
     readonly status?: NodeStatus;
     readonly label?: string;
-    readonly evidence?: string;
-    readonly detail?: string;
+    /** Text replaces the evidence; null clears it (a node demoted back to a plan). */
+    readonly evidence?: string | null;
+    /** Text replaces the design notes; null clears them. */
+    readonly detail?: string | null;
     /** 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. */
@@ -96,10 +136,29 @@ export interface UpdateNodeInput {
 }
 /**
  * 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.
+ * kind, lane and/or submap link. Absent fields are left untouched, null
+ * clears the field. No transition rules: the ledger records whatever the
+ * caller reports, whenever they report it.
+ * Postcondition: the node keeps its band — moving between bands is moveNode,
+ * which is the operation that re-checks I4.
  */
 export declare function updateNode(map: MellosMap, input: UpdateNodeInput): Result<MellosMap, MapError>;
+/**
+ * Move a node to another band — the revision every ghost design eventually
+ * needs, and the only way to empty a band without deleting work.
+ *
+ * Validated before anything changes:
+ *   - the target band exists (I2);
+ *   - every edge touching the node still points strictly downward from its
+ *     NEW rank (I4) — a move that would flatten or invert a dependency is
+ *     refused, naming the edge that blocks it;
+ *   - group membership (I7) still holds. A grouped node may only move to its
+ *     group's band; the move never silently ungroups it, because dropping a
+ *     subsystem membership is a decision the caller must make out loud with
+ *     updateNode({ group: null }).
+ * @returns the map with the node rebanded, or the first refusal.
+ */
+export declare function moveNode(map: MellosMap, id: NodeId, layer: LayerId): Result<MellosMap, MapError>;
 /**
  * Remove a node.
  * Postcondition (explicit part of this contract): every edge touching the

package/lib/domain/ops.js

@@ -5,10 +5,16 @@
  * 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
+ * These functions enforce the structural invariants I1-I10 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.
+ *
+ * Every declared thing can also be REVISED, because a ghost design is a
+ * hypothesis and revising it is honest work: a node moves band (moveNode), a
+ * band is renamed or re-ordered (updateLayer), a group or lane is relabeled
+ * (updateGroup, updateLane), and every optional field a node carries can be
+ * cleared as explicitly as it was set (null, never an empty string).
  */
 import { err, ok, } from './types.js';
 function findLayer(map, id) {
@@ -32,8 +38,28 @@ function checkMembership(map, node, nodeLayer, group) {
 function hasEdge(map, from, to) {
     return map.edges.some((e) => e.from === from && e.to === to);
 }
-/** Set or replace the map title. */
+/**
+ * Validate that a new id does not already name the OTHER kind of box (I10).
+ * Ids are compared as raw slugs on purpose: the shared namespace is exactly
+ * what the brands cannot express, which is why this check exists.
+ */
+function checkIdSpace(map, id, declaring) {
+    const taken = declaring === 'node'
+        ? map.groups.some((g) => g.id === id)
+        : map.nodes.some((n) => n.id === id);
+    return taken ? { kind: 'id-collision', id, taken: declaring === 'node' ? 'group' : 'node' } : undefined;
+}
+/**
+ * Set, replace or clear the map title.
+ * @param title - the new title; null (or an explicit undefined) removes the
+ *   field entirely, so a cleared title serializes as an absent key rather
+ *   than as an empty string nobody can tell from a real one.
+ */
 export function setTitle(map, title) {
+    if (title === null || title === undefined) {
+        const { title: _dropped, ...rest } = map;
+        return rest;
+    }
     return { ...map, title };
 }
 /** Set or replace the map kind (presentation intent — never structural). */
@@ -49,6 +75,12 @@ export function declareLane(map, input) {
         return err({ kind: 'duplicate-lane', id: input.id });
     return ok({ ...map, lanes: [...map.lanes, { id: input.id, label: input.label }] });
 }
+/** Relabel a lane. The column keeps its id, its order and its members. */
+export function updateLane(map, id, label) {
+    if (!findLane(map, id))
+        return err({ kind: 'unknown-lane', id });
+    return ok({ ...map, lanes: map.lanes.map((l) => (l.id === id ? { ...l, label } : l)) });
+}
 /**
  * Remove a lane.
  * Postcondition: former members stay on the map, merely off-lane — removing
@@ -77,10 +109,53 @@ export function declareLayer(map, input) {
         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). */
+/**
+ * Rename a band and/or move it in the vertical order. Absent fields are left
+ * untouched; the band keeps its id and its occupants either way.
+ *
+ * A rank change is the one revision that can invalidate the whole graph, so
+ * it is validated against the map as a whole before anything changes:
+ *   - the new rank is free (I1) — bands stay totally ordered;
+ *   - EVERY edge, not only the ones touching this band, still points
+ *     strictly downward under the new order (I4). Re-ranking a band moves
+ *     all of its nodes at once, so an edge two bands away can be the one
+ *     that breaks; the refusal names it.
+ * @returns the reordered map, or the first refusal.
+ */
+export function updateLayer(map, id, input) {
+    const layer = findLayer(map, id);
+    if (!layer)
+        return err({ kind: 'unknown-layer', id });
+    if (input.rank !== undefined && input.rank !== layer.rank) {
+        const rankHolder = map.layers.find((l) => l.rank === input.rank && l.id !== id);
+        if (rankHolder)
+            return err({ kind: 'duplicate-rank', rank: input.rank, existing: rankHolder.id });
+        // Layers are guaranteed to exist for stored nodes (I2), so no lookup misses.
+        const rankAfter = (nodeId) => {
+            const nodeLayer = findNode(map, nodeId).layer;
+            return nodeLayer === id ? input.rank : findLayer(map, nodeLayer).rank;
+        };
+        for (const e of map.edges) {
+            const fromRank = rankAfter(e.from);
+            const toRank = rankAfter(e.to);
+            if (fromRank <= toRank)
+                return err({ kind: 'edge-not-downward', from: e.from, fromRank, to: e.to, toRank });
+        }
+    }
+    const updated = {
+        ...layer,
+        ...(input.name !== undefined ? { name: input.name } : {}),
+        ...(input.rank !== undefined ? { rank: input.rank } : {}),
+    };
+    return ok({ ...map, layers: map.layers.map((l) => (l.id === id ? updated : l)) });
+}
+/** Add a new group to an existing band (I6), under an id no node holds (I10). */
 export function declareGroup(map, input) {
     if (findGroup(map, input.id))
         return err({ kind: 'duplicate-group', id: input.id });
+    const collision = checkIdSpace(map, input.id, 'group');
+    if (collision)
+        return err(collision);
     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 }] });
@@ -133,12 +208,16 @@ 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).
+ * Add a new node to an existing band (I2, I3) under an id no group holds
+ * (I10), 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 });
+    const collision = checkIdSpace(map, input.id, 'node');
+    if (collision)
+        return err(collision);
     if (!findLayer(map, input.layer))
         return err({ kind: 'unknown-layer', id: input.layer });
     if (input.group !== undefined) {
@@ -153,6 +232,7 @@ export function declareNode(map, input) {
         label: input.label,
         layer: input.layer,
         status: input.status ?? 'planned',
+        ...(input.evidence !== undefined ? { evidence: input.evidence } : {}),
         ...(input.detail !== undefined ? { detail: input.detail } : {}),
         ...(input.group !== undefined ? { group: input.group } : {}),
         ...(input.kind !== undefined ? { kind: input.kind } : {}),
@@ -184,10 +264,20 @@ export function linkNodes(map, from, to, label) {
         return err({ kind: 'edge-not-downward', from, fromRank, to, toRank });
     return ok({ ...map, edges: [...map.edges, { from, to, ...(label !== undefined ? { label } : {}) }] });
 }
+/**
+ * Resolve one optional-and-clearable field: absent input keeps the stored
+ * value, null erases it, anything else replaces it.
+ */
+function resolveOptional(input, current) {
+    return input === undefined ? current : input === null ? undefined : input;
+}
 /**
  * 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.
+ * kind, lane and/or submap link. Absent fields are left untouched, null
+ * clears the field. No transition rules: the ledger records whatever the
+ * caller reports, whenever they report it.
+ * Postcondition: the node keeps its band — moving between bands is moveNode,
+ * which is the operation that re-checks I4.
  */
 export function updateNode(map, input) {
     const node = findNode(map, input.id);
@@ -201,24 +291,65 @@ export function updateNode(map, input) {
     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 { group: currentGroup, kind: currentKind, lane: currentLane, submap: currentSubmap, evidence: currentEvidence, detail: currentDetail, ...bare } = node;
+    const nextGroup = resolveOptional(input.group, currentGroup);
+    const nextKind = resolveOptional(input.kind, currentKind);
+    const nextLane = resolveOptional(input.lane, currentLane);
+    const nextSubmap = resolveOptional(input.submap, currentSubmap);
+    const nextEvidence = resolveOptional(input.evidence, currentEvidence);
+    const nextDetail = resolveOptional(input.detail, currentDetail);
     const updated = {
         ...bare,
+        ...(nextEvidence !== undefined ? { evidence: nextEvidence } : {}),
+        ...(nextDetail !== undefined ? { detail: nextDetail } : {}),
         ...(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)) });
 }
+/**
+ * Move a node to another band — the revision every ghost design eventually
+ * needs, and the only way to empty a band without deleting work.
+ *
+ * Validated before anything changes:
+ *   - the target band exists (I2);
+ *   - every edge touching the node still points strictly downward from its
+ *     NEW rank (I4) — a move that would flatten or invert a dependency is
+ *     refused, naming the edge that blocks it;
+ *   - group membership (I7) still holds. A grouped node may only move to its
+ *     group's band; the move never silently ungroups it, because dropping a
+ *     subsystem membership is a decision the caller must make out loud with
+ *     updateNode({ group: null }).
+ * @returns the map with the node rebanded, or the first refusal.
+ */
+export function moveNode(map, id, layer) {
+    const node = findNode(map, id);
+    if (!node)
+        return err({ kind: 'unknown-node', id });
+    const target = findLayer(map, layer);
+    if (!target)
+        return err({ kind: 'unknown-layer', id: layer });
+    if (node.group !== undefined) {
+        const bad = checkMembership(map, id, layer, node.group);
+        if (bad)
+            return err(bad);
+    }
+    // Layers are guaranteed to exist for stored nodes (I2), so no lookup misses.
+    const rankAfter = (nodeId) => nodeId === id ? target.rank : findLayer(map, findNode(map, nodeId).layer).rank;
+    for (const e of map.edges) {
+        if (e.from !== id && e.to !== id)
+            continue;
+        const fromRank = rankAfter(e.from);
+        const toRank = rankAfter(e.to);
+        if (fromRank <= toRank)
+            return err({ kind: 'edge-not-downward', from: e.from, fromRank, to: e.to, toRank });
+    }
+    return ok({ ...map, nodes: map.nodes.map((n) => (n.id === id ? { ...n, layer } : n)) });
+}
 /**
  * Remove a node.
  * Postcondition (explicit part of this contract): every edge touching the

package/lib/domain/types.d.ts

@@ -8,7 +8,9 @@
  *
  * 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).
+ *   I1. Layer ids are unique; layer ranks are unique (bands are totally
+ *       ordered). A rank is a Rank — a branded integer in a closed range, so
+ *       "unique" and "strictly lower" are decidable; see makeRank.
  *   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
@@ -26,6 +28,13 @@
  *       bands (a sequence participant, a swim lane); lane declaration order
  *       is left-to-right render order.
  *   I9. A node's lane, when set, exists.
+ *  I10. Node ids and group ids share ONE namespace: an id names a node or a
+ *       group, never both. I3 and I6 are per-set and a group is a BOX in
+ *       every view that shows one — the far zoom replaces its members with
+ *       it, and a detail panel resolves a hovered id against groups first.
+ *       Two boxes under one id therefore make the second unreachable and
+ *       the aggregated view ambiguous, which is a structural fault and not
+ *       a rendering accident, so it is refused where ids are declared.
  *
  * The map kind (dev | architecture | dataflow | behavior-tree | sequence) is
  * presentation intent, not structure: every kind shares the same invariants,
@@ -90,6 +99,34 @@ 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>;
+/**
+ * A band's position on the vertical order — a branded integer, never a raw
+ * number. The brand is what makes I1 and I4 hold: `===` dedupe (I1) and
+ * `fromRank > toRank` (I4) are both silently false for NaN, so a NaN rank
+ * would admit same-band and reciprocal edges and lose acyclicity. The closed
+ * range is the same one every surface (tool schema, file format) states, so
+ * a rank the domain accepts always survives a save/reload round trip.
+ */
+export type Rank = number & {
+    readonly __brand: 'Rank';
+};
+/** Bottom band — "primitives are the ground". */
+export declare const RANK_MIN = 0;
+/** Highest band. A map deeper than a hundred bands is a different problem. */
+export declare const RANK_MAX = 99;
+export declare const RANK_RULE_TEXT = "an integer in 0..99, 0 = bottom / most primitive";
+export type InvalidRank = {
+    readonly kind: 'invalid-rank';
+    readonly raw: number;
+    readonly rule: string;
+};
+/**
+ * The only way to obtain a Rank.
+ * @param raw - a candidate rank; NaN, Infinity, fractions and out-of-range
+ *   integers are refused.
+ * @returns the branded rank, or the refusal as a value.
+ */
+export declare function makeRank(raw: number): Result<Rank, InvalidRank>;
 /**
  * Closed vocabulary of map kinds — the diagram's presentation intent.
  * 'dev' (the default) is the progress ledger; the rest are documentation
@@ -112,7 +149,7 @@ export declare function makeNodeStatus(raw: string): Result<NodeStatus, {
 export interface MapLayer {
     readonly id: LayerId;
     readonly name: string;
-    readonly rank: number;
+    readonly rank: Rank;
 }
 /**
  * A labeled cluster of same-band nodes — a subsystem. The far zoom renders
@@ -172,7 +209,7 @@ export interface MellosMap {
 }
 export declare const EMPTY_MAP: MellosMap;
 /** Every way an operation can be refused, as data. */
-export type MapError = InvalidId | {
+export type MapError = InvalidId | InvalidRank | {
     readonly kind: 'invalid-status';
     readonly raw: string;
 } | {
@@ -180,7 +217,7 @@ export type MapError = InvalidId | {
     readonly id: LayerId;
 } | {
     readonly kind: 'duplicate-rank';
-    readonly rank: number;
+    readonly rank: Rank;
     readonly existing: LayerId;
 } | {
     readonly kind: 'duplicate-node';
@@ -205,6 +242,10 @@ export type MapError = InvalidId | {
 } | {
     readonly kind: 'duplicate-group';
     readonly id: GroupId;
+} | {
+    readonly kind: 'id-collision';
+    readonly id: NodeId | GroupId;
+    readonly taken: 'node' | 'group';
 } | {
     readonly kind: 'unknown-group';
     readonly id: GroupId;
@@ -234,9 +275,9 @@ export type MapError = InvalidId | {
 } | {
     readonly kind: 'edge-not-downward';
     readonly from: NodeId;
-    readonly fromRank: number;
+    readonly fromRank: Rank;
     readonly to: NodeId;
-    readonly toRank: number;
+    readonly toRank: Rank;
 };
 /** Human-readable rendering of a MapError, for tool results and logs. */
 export declare function describeMapError(e: MapError): string;

package/lib/domain/types.js

@@ -8,7 +8,9 @@
  *
  * 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).
+ *   I1. Layer ids are unique; layer ranks are unique (bands are totally
+ *       ordered). A rank is a Rank — a branded integer in a closed range, so
+ *       "unique" and "strictly lower" are decidable; see makeRank.
  *   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
@@ -26,6 +28,13 @@
  *       bands (a sequence participant, a swim lane); lane declaration order
  *       is left-to-right render order.
  *   I9. A node's lane, when set, exists.
+ *  I10. Node ids and group ids share ONE namespace: an id names a node or a
+ *       group, never both. I3 and I6 are per-set and a group is a BOX in
+ *       every view that shows one — the far zoom replaces its members with
+ *       it, and a detail panel resolves a hovered id against groups first.
+ *       Two boxes under one id therefore make the second unreachable and
+ *       the aggregated view ambiguous, which is a structural fault and not
+ *       a rendering accident, so it is refused where ids are declared.
  *
  * The map kind (dev | architecture | dataflow | behavior-tree | sequence) is
  * presentation intent, not structure: every kind shares the same invariants,
@@ -58,6 +67,22 @@ export function makeNodeKind(raw) {
 export function makeSubmapRef(raw) {
     return ID_RULE.test(raw) ? ok(raw) : err({ kind: 'invalid-id', raw, rule: ID_RULE_TEXT });
 }
+/** Bottom band — "primitives are the ground". */
+export const RANK_MIN = 0;
+/** Highest band. A map deeper than a hundred bands is a different problem. */
+export const RANK_MAX = 99;
+export const RANK_RULE_TEXT = `an integer in ${RANK_MIN}..${RANK_MAX}, 0 = bottom / most primitive`;
+/**
+ * The only way to obtain a Rank.
+ * @param raw - a candidate rank; NaN, Infinity, fractions and out-of-range
+ *   integers are refused.
+ * @returns the branded rank, or the refusal as a value.
+ */
+export function makeRank(raw) {
+    return Number.isInteger(raw) && raw >= RANK_MIN && raw <= RANK_MAX
+        ? ok(raw)
+        : err({ kind: 'invalid-rank', raw, rule: RANK_RULE_TEXT });
+}
 /**
  * Closed vocabulary of map kinds — the diagram's presentation intent.
  * 'dev' (the default) is the progress ledger; the rest are documentation
@@ -80,6 +105,8 @@ export function describeMapError(e) {
     switch (e.kind) {
         case 'invalid-id':
             return `invalid id "${e.raw}" (rule: ${e.rule})`;
+        case 'invalid-rank':
+            return `invalid rank ${e.raw} (rule: ${e.rule})`;
         case 'invalid-status':
             return `invalid status "${e.raw}" (expected: ${NODE_STATUSES.join(' | ')})`;
         case 'duplicate-layer':
@@ -100,6 +127,9 @@ export function describeMapError(e) {
             return `node "${e.id}" cannot depend on itself`;
         case 'duplicate-group':
             return `group "${e.id}" already exists`;
+        case 'id-collision':
+            return (`id "${e.id}" already names a ${e.taken} on this map; nodes and groups share one id namespace ` +
+                `(both render as boxes, so one id must mean one box) — rename "${e.id}"`);
         case 'unknown-group':
             return `group "${e.id}" does not exist`;
         case 'invalid-map-kind':
@@ -112,9 +142,10 @@ export function describeMapError(e) {
             return (`node "${e.node}" (layer ${e.nodeLayer}) cannot join group "${e.group}" (layer ${e.groupLayer}); ` +
                 `groups cluster nodes within one band`);
         case 'layer-not-empty':
-            return `layer "${e.id}" still holds node "${e.occupant}"; move or remove its nodes first`;
+            return (`layer "${e.id}" still holds node "${e.occupant}"; move its nodes to another band (moveNode) ` +
+                `or remove them (removeNode) first`);
         case 'layer-holds-group':
-            return `layer "${e.id}" still holds group "${e.occupant}"; remove its groups first`;
+            return `layer "${e.id}" still holds group "${e.occupant}"; remove its groups (removeGroup) first`;
         case 'edge-not-downward':
             return (`edge ${e.from} (rank ${e.fromRank}) -> ${e.to} (rank ${e.toRank}) is not strictly downward; ` +
                 `dependencies may only point to a lower layer`);

package/lib/render/canvas.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Layer 4a — the drawing surface: a grid of cells that knows how to merge
+ * crossing lines, and how to emit itself as terminal rows.
+ *
+ * Two kinds of ink live in a cell. A LITERAL is a character somebody chose (a
+ * label, a box border); a MASK is a set of directions a routed line passes
+ * through, and the character comes out of the mask at emit time. That is what
+ * makes junctions free: two wires crossing simply union their masks, and ┼
+ * appears without anyone routing around anything.
+ *
+ * The surface knows nothing about maps, statuses or zoom — it takes a Style
+ * (the ink palette below) and coordinates, and it is the only place ANSI is
+ * produced.
+ */
+import type { RenderOptions, Viewport } from './options.js';
+export type Style = 'none' | 'dim' | 'amber' | 'green' | 'greenDim' | 'red' | 'faint';
+/** SGR parameter per style; combined with bold ("1") at emit time. */
+export declare const SGR: Readonly<Record<Style, string>>;
+export declare const ANSI_RESET = "\u001B[0m";
+export declare const UP = 1;
+export declare const DOWN = 2;
+export declare const LEFT = 4;
+export declare const RIGHT = 8;
+export declare class Canvas {
+    private readonly rows;
+    private cell;
+    get height(): number;
+    get width(): number;
+    /** Write literal text starting at (x, y). Returns the column just past it. */
+    text(x: number, y: number, s: string, style: Style, bold?: boolean): number;
+    /** Merge a routed-line direction mask into (x, y). */
+    line(x: number, y: number, mask: number, heavyHorizontal?: boolean, bright?: boolean): void;
+    /**
+     * Emit terminal lines, optionally windowed to a viewport. Slicing happens
+     * at the cell level so ANSI codes reopen correctly inside the window and a
+     * CJK character cut in half at either edge degrades to a space instead of
+     * shifting the whole row. Routed wiring (mask cells) emits FAINT — the
+     * circuit board recedes, the boxes glow.
+     */
+    emit(opts: RenderOptions, viewport?: Viewport): string[];
+}
+/**
+ * Draw an orthogonal polyline through `points` (consecutive points must share
+ * an x or a y). Interior cells of a segment carry the segment's axis mask;
+ * every point cell carries only the directions of the segments that actually
+ * touch it — so path endpoints become clean junction stubs (e.g. ┬ when
+ * entering a box border) and turning points become corner characters, all via
+ * the same mask union. Zero-length segments vanish naturally.
+ */
+export declare function drawPath(canvas: Canvas, points: ReadonlyArray<readonly [number, number]>, bright?: boolean): void;