@transitrix/diagrams 1.5.0 → 1.7.6

package/src/capability-map/__tests__/dsm-layout.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import { layoutCapabilityMap } from '../dsm-layout.js';
+import type { CapabilityMap } from '../dsm-schema.js';
+
+function map(): CapabilityMap {
+  return {
+    organisation: 'Acme Corp',
+    set_id: 'v1.0',
+    capabilities: [
+      { id: 1, name: 'Customer Acquisition', address: '1.0.0' },
+      { id: 2, name: 'Lead Qualification', address: '1.1.0' },
+      { id: 3, name: 'Inbound Lead Scoring', address: '1.1.1' },
+      { id: 4, name: 'Order Management', address: '2.0.0' },
+      { id: 5, name: 'Parked idea', address: '0.0.0', backlog: true },
+    ],
+  };
+}
+
+describe('layoutCapabilityMap', () => {
+  it('lays out a virtual root plus every on-diagram capability, one column per level', () => {
+    const layout = layoutCapabilityMap(map());
+    expect(layout.rootNode.data).toBeNull();
+    expect(layout.nodes).toHaveLength(4); // backlog entry excluded
+    const byId = new Map(layout.nodes.map((n) => [n.id, n]));
+    expect(byId.get(1)!.x).toBe(byId.get(4)!.x); // both L1s share a column
+    expect(byId.get(2)!.x).toBeGreaterThan(byId.get(1)!.x); // L2 one column further right
+    expect(byId.get(3)!.x).toBeGreaterThan(byId.get(2)!.x); // L3 further still
+    expect(byId.get(1)!.x).toBeGreaterThan(layout.rootNode.x); // root sits left of the L1s
+  });
+
+  it('connects the root to every L1 and each parent to its children', () => {
+    const layout = layoutCapabilityMap(map());
+    const edgeSet = new Set(layout.edges.map((e) => `${e.source}->${e.target}`));
+    expect(edgeSet.has('root->1')).toBe(true);
+    expect(edgeSet.has('root->4')).toBe(true);
+    expect(edgeSet.has('1->2')).toBe(true);
+    expect(edgeSet.has('2->3')).toBe(true);
+  });
+
+  it('marks a node as having hidden children when its subtree is collapsed', () => {
+    const layout = layoutCapabilityMap(map(), { hideCollapsed: [2] });
+    const cap2 = layout.nodes.find((n) => n.id === 2)!;
+    expect(cap2.hasHiddenChildren).toBe(true);
+    expect(layout.nodes.some((n) => n.id === 3)).toBe(false); // hidden subtree omitted
+  });
+
+  it('returns just the root when there are no on-diagram capabilities', () => {
+    const layout = layoutCapabilityMap({ organisation: 'Empty Co', set_id: 'v1', capabilities: [] });
+    expect(layout.nodes).toHaveLength(0);
+    expect(layout.rootNode.data).toBeNull();
+  });
+});

package/src/capability-map/__tests__/dsm-mutations.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect } from 'vitest';
+import { reparent, addChild, deleteWithDescendants, moveBranchToBacklog, restoreFromBacklog, normaliseAddresses } from '../dsm-mutations.js';
+import type { CapabilityMap } from '../dsm-schema.js';
+
+function baseMap(): CapabilityMap {
+  return {
+    organisation: 'Acme Corp',
+    set_id: 'v1.0',
+    capabilities: [
+      { id: 1, name: 'Customer Acquisition', address: '1.0.0' },
+      { id: 2, name: 'Lead Qualification', address: '1.1.0' },
+      { id: 3, name: 'Inbound Lead Scoring', address: '1.1.1' },
+      { id: 4, name: 'Order Management', address: '2.0.0' },
+    ],
+  };
+}
+
+describe('reparent', () => {
+  it('moves an L3 under a different L2 (no cascade)', () => {
+    const map = baseMap();
+    const r = reparent(map, 3, 4); // Inbound Lead Scoring (L3) -> Order Management (L1)... newLevel would be 2
+    expect(r.ok).toBe(true);
+    const moved = r.result!.capabilities.find((c) => c.id === 3)!;
+    expect(moved.address).toBe('2.1.0'); // now an L2 under capability 4
+  });
+
+  it('promotes an L2 to L1 and cascades its L3 children to L2 (spec §9)', () => {
+    const map = baseMap();
+    const r = reparent(map, 2, 0); // Lead Qualification (L2, id 2) -> virtual root
+    expect(r.ok).toBe(true);
+    const promoted = r.result!.capabilities.find((c) => c.id === 2)!;
+    const child = r.result!.capabilities.find((c) => c.id === 3)!;
+    expect(promoted.address).toBe('3.0.0'); // first free L1 slot (1 and 2 taken)
+    expect(child.address).toBe('3.1.0'); // cascaded from L3 to L2 under the new L1
+  });
+
+  it('refuses a demotion that would push a grandchild past L3', () => {
+    const map = baseMap();
+    // Capability 1 (L1) has descendant 2 (L2) and 3 (L3, a grandchild).
+    // Demoting 1 under 4 (making 1 an L2) would need 3 to become L4.
+    const r = reparent(map, 1, 4);
+    expect(r.ok).toBe(false);
+  });
+
+  it('refuses reparenting onto its own descendant (cycle)', () => {
+    const map = baseMap();
+    const r = reparent(map, 2, 3); // Lead Qualification onto its own child
+    expect(r.ok).toBe(false);
+  });
+
+  it('refuses reparenting onto itself', () => {
+    const map = baseMap();
+    expect(reparent(map, 1, 1).ok).toBe(false);
+  });
+
+  it('leaves the original map untouched', () => {
+    const map = baseMap();
+    reparent(map, 3, 4);
+    expect(map.capabilities.find((c) => c.id === 3)!.address).toBe('1.1.1');
+  });
+});
+
+describe('addChild', () => {
+  it('assigns the first free address under the parent', () => {
+    const map = baseMap();
+    const r = addChild(map, 1, { name: 'New L2' });
+    expect(r.ok).toBe(true);
+    const added = r.result!.capabilities.find((c) => c.name === 'New L2')!;
+    expect(added.address).toBe('1.2.0');
+    expect(added.backlog).toBe(false);
+  });
+
+  it('assigns a new L1 address when parentId is 0 (root)', () => {
+    const map = baseMap();
+    const r = addChild(map, 0, { name: 'New L1' });
+    expect(r.ok).toBe(true);
+    expect(r.result!.capabilities.find((c) => c.name === 'New L1')!.address).toBe('3.0.0');
+  });
+
+  it('refuses adding a child under an L3 (would exceed max depth)', () => {
+    const map = baseMap();
+    const r = addChild(map, 3, { name: 'Too deep' });
+    expect(r.ok).toBe(false);
+  });
+});
+
+describe('deleteWithDescendants', () => {
+  it('removes the capability and every descendant', () => {
+    const map = baseMap();
+    const r = deleteWithDescendants(map, 2); // Lead Qualification + its L3 child
+    expect(r.ok).toBe(true);
+    const ids = r.result!.capabilities.map((c) => c.id);
+    expect(ids).not.toContain(2);
+    expect(ids).not.toContain(3);
+    expect(ids).toContain(1);
+    expect(ids).toContain(4);
+  });
+});
+
+describe('moveBranchToBacklog / restoreFromBacklog', () => {
+  it('moves a branch to the backlog and back', () => {
+    const map = baseMap();
+    const toBacklog = moveBranchToBacklog(map, 2);
+    expect(toBacklog.ok).toBe(true);
+    const backlogged = toBacklog.result!.capabilities.filter((c) => c.id === 2 || c.id === 3);
+    expect(backlogged.every((c) => c.backlog && c.address === '0.0.0')).toBe(true);
+
+    const restored = restoreFromBacklog(toBacklog.result!, 2, 4);
+    expect(restored.ok).toBe(true);
+    const cap2 = restored.result!.capabilities.find((c) => c.id === 2)!;
+    expect(cap2.backlog).toBe(false);
+    expect(cap2.address).toBe('2.1.0');
+    // Restoring the parent doesn't automatically restore its backlogged
+    // children — matches deleteWithDescendants/addChild's scope (this
+    // mutation acts on the single named id only).
+    expect(restored.result!.capabilities.find((c) => c.id === 3)!.backlog).toBe(true);
+  });
+});
+
+describe('normaliseAddresses', () => {
+  it('moves a capability with an unresolvable parent address to the backlog', () => {
+    const map: CapabilityMap = {
+      organisation: 'Acme Corp',
+      set_id: 'v1.0',
+      capabilities: [
+        { id: 1, name: 'Customer Acquisition', address: '1.0.0' },
+        { id: 2, name: 'Dangling L2', address: '9.1.0' }, // no capability at 9.0.0
+      ],
+    };
+    const result = normaliseAddresses(map);
+    const dangling = result.capabilities.find((c) => c.id === 2)!;
+    expect(dangling.backlog).toBe(true);
+    expect(dangling.address).toBe('0.0.0');
+  });
+
+  it('leaves a well-formed hierarchy unchanged', () => {
+    const map = baseMap();
+    const result = normaliseAddresses(map);
+    expect(result.capabilities).toEqual(map.capabilities);
+  });
+});

package/src/capability-map/__tests__/dsm-validate.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest';
+import { validateCapabilityMapData } from '../dsm-validate.js';
+import type { CapabilityMap } from '../dsm-schema.js';
+
+function validMap(): CapabilityMap {
+  return {
+    organisation: 'Acme Corp',
+    set_id: 'v1.0',
+    capabilities: [
+      { id: 1, name: 'Customer Acquisition', address: '1.0.0' },
+      { id: 2, name: 'Lead Qualification', address: '1.1.0' },
+      { id: 3, name: 'Inbound Lead Scoring', address: '1.1.1' },
+    ],
+  };
+}
+
+describe('validateCapabilityMapData', () => {
+  it('accepts a well-formed map', () => {
+    expect(validateCapabilityMapData(validMap()).valid).toBe(true);
+  });
+
+  it('flags a duplicate id', () => {
+    const map = validMap();
+    map.capabilities[1].id = 1;
+    const result = validateCapabilityMapData(map);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.code === 'DUPLICATE_ID')).toBe(true);
+  });
+
+  it('flags a malformed address', () => {
+    const map = validMap();
+    map.capabilities[0].address = 'not-an-address';
+    const result = validateCapabilityMapData(map);
+    expect(result.errors.some((e) => e.code === 'INVALID_ADDRESS_FORMAT')).toBe(true);
+  });
+
+  it('flags a too-deep address as MAX_DEPTH_EXCEEDED, not INVALID_ADDRESS_FORMAT', () => {
+    const map = validMap();
+    map.capabilities[0].address = '1.2.3.4';
+    const result = validateCapabilityMapData(map);
+    expect(result.errors.some((e) => e.code === 'MAX_DEPTH_EXCEEDED')).toBe(true);
+    expect(result.errors.some((e) => e.code === 'INVALID_ADDRESS_FORMAT')).toBe(false);
+  });
+
+  it('flags a duplicate on-diagram address', () => {
+    const map = validMap();
+    map.capabilities[1].address = '1.0.0';
+    const result = validateCapabilityMapData(map);
+    expect(result.errors.some((e) => e.code === 'DUPLICATE_ADDRESS')).toBe(true);
+  });
+
+  it('warns on a missing parent by address', () => {
+    const map = validMap();
+    map.capabilities[1].address = '9.1.0'; // no capability at 9.0.0
+    const result = validateCapabilityMapData(map);
+    expect(result.warnings.some((w) => w.code === 'MISSING_PARENT_BY_ADDRESS')).toBe(true);
+  });
+
+  it('does not flag a backlog entry\'s address as a duplicate or requiring a parent', () => {
+    const map = validMap();
+    map.capabilities.push({ id: 4, name: 'Parked idea', address: '0.0.0', backlog: true });
+    const result = validateCapabilityMapData(map);
+    expect(result.valid).toBe(true);
+  });
+});

package/src/capability-map/address.ts

@@ -0,0 +1,48 @@
+import type { Capability } from './dsm-schema.js';
+
+/** 'X.Y.Z' -> [X, Y, Z]. Throws on malformed input — callers on untrusted
+ *  data should validate with validateCapabilityMapData first. */
+export function parseAddress(address: string): [number, number, number] {
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(address.trim());
+  if (!m) throw new Error(`parseAddress: expected 'X.Y.Z', got "${address}"`);
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+export function formatAddress(triple: [number, number, number]): string {
+  return triple.join('.');
+}
+
+/** X.0.0 -> L1, X.Y.0 -> L2, X.Y.Z -> L3, 0.0.0 -> backlog. */
+export function getLevel(address: string): 1 | 2 | 3 | 'backlog' {
+  const [x, y, z] = parseAddress(address);
+  if (x === 0) return 'backlog';
+  if (y === 0) return 1;
+  if (z === 0) return 2;
+  return 3;
+}
+
+/** '1.2.3' -> '1.2.0'; '1.2.0' -> '1.0.0'; '1.0.0' -> null (L1 has no parent). */
+export function getParentAddress(address: string): string | null {
+  const [x, y, z] = parseAddress(address);
+  if (z !== 0) return formatAddress([x, y, 0]);
+  if (y !== 0) return formatAddress([x, 0, 0]);
+  return null;
+}
+
+/** First address under `parent` (an L1 or L2 address) not already taken. */
+export function getFirstFreeAddress(parent: string, capabilities: Capability[]): string {
+  const [x, y] = parseAddress(parent);
+  const level = getLevel(parent);
+  if (level !== 1 && level !== 2) {
+    throw new Error(`getFirstFreeAddress: parent must be an L1 or L2 address, got "${parent}" (${level})`);
+  }
+  for (let n = 1; n < 1000; n++) {
+    const candidate = level === 1 ? formatAddress([x, n, 0]) : formatAddress([x, y, n]);
+    if (!isAddressTaken(candidate, capabilities)) return candidate;
+  }
+  throw new Error(`getFirstFreeAddress: no free address under "${parent}" (searched 1..999)`);
+}
+
+export function isAddressTaken(address: string, capabilities: Capability[]): boolean {
+  return capabilities.some((c) => !c.backlog && c.address === address);
+}

package/src/capability-map/dsm-layout.ts

@@ -0,0 +1,142 @@
+import type { CapabilityMap, LayoutOptions, CapabilityMapLayout, LaidOutNode, LaidOutEdge } from './dsm-schema.js';
+import { getLevel, getParentAddress } from './address.js';
+
+const DEFAULT_NODE_WIDTH = 250;
+const DEFAULT_NODE_HEIGHT = 64;
+const DEFAULT_RANK_SEP = 80;
+const DEFAULT_NODE_SEP = 24;
+/** Width of the virtual organisation-root node — narrower than a capability
+ *  card since it carries only a label, no maturity dot or address. */
+const ROOT_WIDTH = 200;
+
+/**
+ * Lays out a capability map's on-diagram (non-backlog) capabilities, plus a
+ * virtual organisation-root node one column to the left of the L1s (§6.1).
+ * Backlog filtering is a Layer B / component concern (same split as the
+ * goals module) — this function lays out whatever `capabilities` it's given,
+ * using their address to derive parent/child structure.
+ */
+export function layoutCapabilityMap(map: CapabilityMap, options: LayoutOptions = {}): CapabilityMapLayout {
+  const {
+    nodeWidth = DEFAULT_NODE_WIDTH,
+    nodeHeight = DEFAULT_NODE_HEIGHT,
+    rankSep = DEFAULT_RANK_SEP,
+    nodeSep = DEFAULT_NODE_SEP,
+    hideCollapsed = [],
+    // organisationLabel isn't stored on LaidOutNode (its `data` is a
+    // Capability | null, with no label slot for the virtual root) — the
+    // component reads `layoutOptions.organisationLabel ?? map.organisation`
+    // directly when it renders the root card.
+  } = options;
+
+  const hiddenSet = new Set(hideCollapsed);
+  const onDiagram = map.capabilities.filter((c) => !c.backlog);
+  const byId = new Map(onDiagram.map((c) => [c.id, c]));
+  const addressToId = new Map(onDiagram.map((c) => [c.address, c.id]));
+
+  const children = new Map<number, number[]>();
+  const l1Ids: number[] = [];
+  for (const c of onDiagram) {
+    const level = getLevel(c.address);
+    if (level === 'backlog') continue;
+    if (level === 1) {
+      l1Ids.push(c.id);
+      continue;
+    }
+    const parentAddress = getParentAddress(c.address);
+    const parentId = parentAddress ? addressToId.get(parentAddress) : undefined;
+    if (parentId === undefined) {
+      // MISSING_PARENT_BY_ADDRESS is a warning, not an error — render it
+      // hanging directly off the root rather than dropping it silently.
+      l1Ids.push(c.id);
+      continue;
+    }
+    if (!children.has(parentId)) children.set(parentId, []);
+    children.get(parentId)!.push(c.id);
+  }
+
+  const byAddress = (a: number, b: number): number =>
+    byId.get(a)!.address.localeCompare(byId.get(b)!.address, undefined, { numeric: true });
+  l1Ids.sort(byAddress);
+  for (const kids of children.values()) kids.sort(byAddress);
+
+  const hiddenSubtrees = new Set<number>();
+  function markHidden(id: number): void {
+    for (const child of children.get(id) ?? []) {
+      hiddenSubtrees.add(child);
+      markHidden(child);
+    }
+  }
+  for (const id of hiddenSet) markHidden(id);
+
+  const nodes: LaidOutNode[] = [];
+  const edges: LaidOutEdge[] = [];
+  const columnNextY = new Map<number, number>();
+  const getNextY = (col: number): number => columnNextY.get(col) ?? 0;
+  const advanceY = (col: number, delta: number): void => { columnNextY.set(col, (columnNextY.get(col) ?? 0) + delta); };
+
+  function placeSubtree(id: number, col: number): { top: number; bottom: number } {
+    const cap = byId.get(id)!;
+    const allChildIds = children.get(id) ?? [];
+    const childIds = allChildIds.filter((c) => !hiddenSubtrees.has(c));
+    const hasHiddenChildren = childIds.length < allChildIds.length;
+
+    if (childIds.length === 0) {
+      const y = getNextY(col);
+      advanceY(col, nodeHeight + nodeSep);
+      nodes.push({ id, x: col * (nodeWidth + rankSep), y, width: nodeWidth, height: nodeHeight, data: cap, hasHiddenChildren });
+      return { top: y, bottom: y + nodeHeight };
+    }
+
+    const spans = childIds.map((cid) => placeSubtree(cid, col + 1));
+    const spanTop = Math.min(...spans.map((s) => s.top));
+    const spanBottom = Math.max(...spans.map((s) => s.bottom));
+    const parentY = spanTop + (spanBottom - spanTop) / 2 - nodeHeight / 2;
+    const curColY = getNextY(col);
+    const finalY = Math.max(parentY, curColY);
+    advanceY(col, finalY - curColY + nodeHeight + nodeSep);
+
+    nodes.push({ id, x: col * (nodeWidth + rankSep), y: finalY, width: nodeWidth, height: nodeHeight, data: cap, hasHiddenChildren });
+    for (const cid of childIds) edges.push({ source: id, target: cid });
+    return { top: Math.min(finalY, spanTop), bottom: Math.max(finalY + nodeHeight, spanBottom) };
+  }
+
+  for (const id of l1Ids) {
+    if (hiddenSubtrees.has(id)) continue;
+    placeSubtree(id, 1);
+    for (const [col, y] of columnNextY) columnNextY.set(col, y + nodeSep);
+  }
+
+  if (nodes.length === 0) {
+    const rootNode: LaidOutNode = { id: 0, x: 0, y: 0, width: ROOT_WIDTH, height: nodeHeight, data: null, hasHiddenChildren: false };
+    return { rootNode, nodes: [], edges: [], bounds: { x: 0, y: 0, width: ROOT_WIDTH, height: nodeHeight } };
+  }
+
+  const minX = Math.min(...nodes.map((n) => n.x));
+  const minY = Math.min(...nodes.map((n) => n.y));
+  const maxX = Math.max(...nodes.map((n) => n.x + n.width));
+  const maxY = Math.max(...nodes.map((n) => n.y + n.height));
+
+  const l1IdSet = new Set(l1Ids);
+  const l1Nodes = nodes.filter((n) => l1IdSet.has(n.id));
+  const rootTop = Math.min(...l1Nodes.map((n) => n.y));
+  const rootBottom = Math.max(...l1Nodes.map((n) => n.y + n.height));
+  const rootY = rootTop + (rootBottom - rootTop) / 2 - nodeHeight / 2;
+  const rootNode: LaidOutNode = { id: 0, x: 0, y: rootY, width: ROOT_WIDTH, height: nodeHeight, data: null, hasHiddenChildren: false };
+
+  const rootEdges: LaidOutEdge[] = l1Ids
+    .filter((id) => !hiddenSubtrees.has(id))
+    .map((id) => ({ source: 'root' as const, target: id }));
+
+  return {
+    rootNode,
+    nodes,
+    edges: [...rootEdges, ...edges],
+    bounds: {
+      x: Math.min(0, minX),
+      y: Math.min(rootY, minY),
+      width: Math.max(maxX, ROOT_WIDTH) - Math.min(0, minX),
+      height: Math.max(rootY + nodeHeight, maxY) - Math.min(rootY, minY),
+    },
+  };
+}

package/src/capability-map/dsm-mutations.ts

@@ -0,0 +1,208 @@
+import type { Capability, CapabilityMap, MutationResult, ValidationError } from './dsm-schema.js';
+import { parseAddress, getLevel, getParentAddress, getFirstFreeAddress, isAddressTaken } from './address.js';
+
+function cloneMap(map: CapabilityMap): CapabilityMap {
+  return {
+    organisation: map.organisation,
+    set_id: map.set_id,
+    capabilities: map.capabilities.map((c) => ({
+      ...c,
+      maturity: c.maturity ? c.maturity.map((m) => ({ ...m })) : undefined,
+    })),
+  };
+}
+
+function nextId(map: CapabilityMap): number {
+  return Math.max(0, ...map.capabilities.map((c) => c.id)) + 1;
+}
+
+function refusalError(message: string): MutationResult<CapabilityMap> {
+  const err: ValidationError = { code: 'MUTATION_REFUSED', message };
+  return { ok: false, error: err };
+}
+
+/** True when `addr` sits anywhere under `ancestorAddr` in the address hierarchy. */
+function isDescendantAddress(addr: string, ancestorAddr: string): boolean {
+  const [ax, ay, az] = parseAddress(addr);
+  const [px, py, pz] = parseAddress(ancestorAddr);
+  if (px !== ax) return false;
+  if (py === 0) return ay !== 0 || az !== 0; // ancestor is L1 — any L2/L3 under the same X
+  if (pz === 0) return ay === py && az !== 0; // ancestor is L2 — only L3s under the same X.Y
+  return false; // ancestor is L3 — no descendants possible (max depth)
+}
+
+/** First unused top-level (L1) address — the "parent" for a promote-to-L1 reparent. */
+function firstFreeL1(capabilities: Capability[]): string {
+  for (let x = 1; x < 1000; x++) {
+    const candidate = `${x}.0.0`;
+    if (!isAddressTaken(candidate, capabilities)) return candidate;
+  }
+  throw new Error('firstFreeL1: no free top-level address (searched 1..999)');
+}
+
+/**
+ * Move `sourceId` under `targetId` (or under the virtual root when
+ * `targetId` is 0 — the sentinel matching the goals module's `parent_id: 0`
+ * convention, since the root isn't itself a Capability with an id).
+ *
+ * Recomputes addresses for the whole moved branch (§5.1). The depth check is
+ * expressed once, generically, as "every descendant's new level must stay in
+ * 1..3" — this covers both directions the spec discusses explicitly (L2→L1
+ * promotion, where descendants move one level shallower) and the symmetric,
+ * unspecified case (L1→L2 demotion, where descendants move one level
+ * deeper) without needing separate per-direction rules: an L1 with L3
+ * grandchildren refuses demotion to L2 because that would need a 4th level,
+ * caught by the same check.
+ */
+export function reparent(map: CapabilityMap, sourceId: number, targetId: number): MutationResult<CapabilityMap> {
+  const clone = cloneMap(map);
+  const source = clone.capabilities.find((c) => c.id === sourceId);
+  if (!source || source.backlog) return refusalError(`Capability ${sourceId} not found (use restoreFromBacklog for backlog items)`);
+  if (sourceId === targetId) return refusalError('Cannot reparent to self');
+
+  const target = targetId === 0 ? null : clone.capabilities.find((c) => c.id === targetId);
+  if (targetId !== 0 && (!target || target.backlog)) return refusalError(`Target capability ${targetId} not found`);
+
+  if (target && isDescendantAddress(target.address, source.address)) {
+    return refusalError('Cannot reparent: target is a descendant of the source (would create a cycle)');
+  }
+
+  const sourceLevel = getLevel(source.address);
+  if (sourceLevel === 'backlog') return refusalError(`Capability ${sourceId} has no on-diagram address`);
+  const targetLevel = target ? getLevel(target.address) : 0;
+  const newLevel = (typeof targetLevel === 'number' ? targetLevel : 0) + 1;
+  if (newLevel > 3) return refusalError('Reparent would exceed max depth (L3)');
+
+  const levelDelta = newLevel - sourceLevel;
+  const originalSourceAddress = source.address;
+
+  // Snapshot descendants + their original address/level BEFORE anything is
+  // reassigned — both for the depth check and to resolve old-parent links
+  // while walking the branch top-down below.
+  const descendants = clone.capabilities
+    .filter((c) => !c.backlog && c.id !== sourceId && isDescendantAddress(c.address, originalSourceAddress))
+    .map((c) => ({ cap: c, originalAddress: c.address, originalLevel: getLevel(c.address) as 1 | 2 | 3 }));
+
+  for (const d of descendants) {
+    const newDescLevel = d.originalLevel + levelDelta;
+    if (newDescLevel > 3 || newDescLevel < 1) {
+      return refusalError(`Reparent would push descendant ${d.cap.id} to level ${newDescLevel}, outside 1..3`);
+    }
+  }
+
+  const oldAddressToId = new Map<string, number>(clone.capabilities.filter((c) => !c.backlog).map((c) => [c.address, c.id]));
+  const newAddressById = new Map<number, string>();
+
+  source.address = target ? getFirstFreeAddress(target.address, clone.capabilities) : firstFreeL1(clone.capabilities);
+  newAddressById.set(sourceId, source.address);
+
+  // Shallowest-first so each descendant's old parent has already been
+  // re-addressed (or is the source itself) by the time we reach it.
+  descendants.sort((a, b) => a.originalLevel - b.originalLevel);
+  for (const d of descendants) {
+    const oldParentAddress = getParentAddress(d.originalAddress);
+    const oldParentId = oldParentAddress ? oldAddressToId.get(oldParentAddress) : undefined;
+    const newParentAddress = oldParentId != null ? newAddressById.get(oldParentId) : undefined;
+    if (!newParentAddress) {
+      return refusalError(`Reparent could not resolve the new parent address for descendant ${d.cap.id}`);
+    }
+    const newAddress = getFirstFreeAddress(newParentAddress, clone.capabilities);
+    d.cap.address = newAddress;
+    newAddressById.set(d.cap.id, newAddress);
+  }
+
+  return { ok: true, result: clone };
+}
+
+export function addChild(map: CapabilityMap, parentId: number, newCap: Omit<Capability, 'id' | 'address'>): MutationResult<CapabilityMap> {
+  const clone = cloneMap(map);
+  const parent = parentId === 0 ? null : clone.capabilities.find((c) => c.id === parentId);
+  if (parentId !== 0 && (!parent || parent.backlog)) return refusalError(`Parent capability ${parentId} not found`);
+
+  const parentLevel = parent ? getLevel(parent.address) : 0;
+  const newLevel = (typeof parentLevel === 'number' ? parentLevel : 0) + 1;
+  if (newLevel > 3) return refusalError('New child would exceed max depth (L3)');
+
+  const address = parent ? getFirstFreeAddress(parent.address, clone.capabilities) : firstFreeL1(clone.capabilities);
+  const id = nextId(clone);
+  clone.capabilities.push({ ...newCap, id, address, backlog: false });
+  return { ok: true, result: clone };
+}
+
+export function deleteWithDescendants(map: CapabilityMap, id: number): MutationResult<CapabilityMap> {
+  const clone = cloneMap(map);
+  const target = clone.capabilities.find((c) => c.id === id);
+  if (!target) return refusalError(`Capability ${id} not found`);
+
+  const toDelete = new Set<number>([id]);
+  if (!target.backlog) {
+    for (const c of clone.capabilities) {
+      if (!c.backlog && isDescendantAddress(c.address, target.address)) toDelete.add(c.id);
+    }
+  }
+  clone.capabilities = clone.capabilities.filter((c) => !toDelete.has(c.id));
+  return { ok: true, result: clone };
+}
+
+/** Moves a whole branch to the backlog. Descendants move with it (a
+ *  backlogged capability's on-diagram children would otherwise dangle). */
+export function moveBranchToBacklog(map: CapabilityMap, id: number): MutationResult<CapabilityMap> {
+  const clone = cloneMap(map);
+  const target = clone.capabilities.find((c) => c.id === id);
+  if (!target) return refusalError(`Capability ${id} not found`);
+  if (target.backlog) return refusalError(`Capability ${id} is already in the backlog`);
+
+  const branch = [target, ...clone.capabilities.filter((c) => !c.backlog && isDescendantAddress(c.address, target.address))];
+  for (const c of branch) {
+    c.backlog = true;
+    c.address = '0.0.0';
+  }
+  return { ok: true, result: clone };
+}
+
+export function restoreFromBacklog(map: CapabilityMap, id: number, parentId: number): MutationResult<CapabilityMap> {
+  const clone = cloneMap(map);
+  const target = clone.capabilities.find((c) => c.id === id);
+  if (!target || !target.backlog) return refusalError(`Capability ${id} is not in the backlog`);
+
+  const parent = parentId === 0 ? null : clone.capabilities.find((c) => c.id === parentId);
+  if (parentId !== 0 && (!parent || parent.backlog)) return refusalError(`Parent capability ${parentId} not found`);
+  const parentLevel = parent ? getLevel(parent.address) : 0;
+  const newLevel = (typeof parentLevel === 'number' ? parentLevel : 0) + 1;
+  if (newLevel > 3) return refusalError('Restore would exceed max depth (L3)');
+
+  target.address = parent ? getFirstFreeAddress(parent.address, clone.capabilities) : firstFreeL1(clone.capabilities);
+  target.backlog = false;
+  return { ok: true, result: clone };
+}
+
+/**
+ * Repairs addresses that don't resolve to an existing parent (MISSING_PARENT_BY_ADDRESS):
+ * reassigns each such capability to the first free slot under its would-be
+ * parent's level, or moves it to the backlog when no such parent exists at all.
+ */
+export function normaliseAddresses(map: CapabilityMap): CapabilityMap {
+  const clone = cloneMap(map);
+  const addressToId = new Map<string, number>(clone.capabilities.filter((c) => !c.backlog).map((c) => [c.address, c.id]));
+
+  // Re-derive level-by-level (L1 first) so an L1 fixed up in this pass can
+  // already serve as a valid parent for an L2 processed right after it.
+  const byLevel = clone.capabilities
+    .filter((c) => !c.backlog)
+    .map((c) => ({ cap: c, level: getLevel(c.address) }))
+    .filter((e): e is { cap: Capability; level: 1 | 2 | 3 } => typeof e.level === 'number')
+    .sort((a, b) => a.level - b.level);
+
+  for (const { cap, level } of byLevel) {
+    if (level === 1) continue; // L1 has no parent to validate against
+    const parentAddress = getParentAddress(cap.address);
+    if (parentAddress && addressToId.has(parentAddress)) continue; // already fine
+
+    // No resolvable parent: reassign to the backlog rather than guessing one.
+    addressToId.delete(cap.address);
+    cap.backlog = true;
+    cap.address = '0.0.0';
+  }
+
+  return clone;
+}