@nanobpm/nano-workforce 0.138.3 → 0.139.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.139.0](https://github.com/nanobpm/nano-workforce/compare/v0.138.3...v0.139.0) (2026-08-24)
+
+### Features
+
+* deliver the delivery graph surface epic (dismiss, run history, reusable graph library import/export) ([#534](https://github.com/nanobpm/nano-workforce/issues/534)) ([dcbf4b1](https://github.com/nanobpm/nano-workforce/commit/dcbf4b15e2e78dd4bdecf7b06c8fdf8d3849a9d7)), closes [#519](https://github.com/nanobpm/nano-workforce/issues/519) [#526](https://github.com/nanobpm/nano-workforce/issues/526) [#521](https://github.com/nanobpm/nano-workforce/issues/521)
+
 ## [0.138.3](https://github.com/nanobpm/nano-workforce/compare/v0.138.2...v0.138.3) (2026-08-24)
 
 ### Bug Fixes

package/app/contracts.ts

@@ -384,6 +384,22 @@ export const WIRE_CONTRACTS = {
     shape:
       '{ name?: string, nodes: Array<{ id: string, kind: "agent"|"wait"|"human"|"connector", emits?: Array<{ name: string, type: "string"|"number"|"boolean"|"artifact"|"version"|"url", description?: string }>, agent?: { jobType: string, prompt?: string }, wait?: ReadinessProbe, human?: { formKey?: string, prompt?: string }, connector?: { target: string, dedupeKey?: string, payload?: object } }>, edges?: Array<{ from: string, to: string }> }',
   },
+  "deliveryGraph.compose.fill": {
+    category: "wire",
+    name: "deliveryGraph.compose.fill",
+    owner: "pages/delivery-graphs/mount.js",
+    semantics:
+      "The INBOUND reuse-fill host-bridge message that loads a saved `DeliveryGraph` JSON into the Delivery Graphs COMPOSE App-View textarea (`#dg-json`) — issue #523, epic #519 S4. The compose mount (consumer) registers a same-origin `window` `message` listener for this shape and routes it through its single `fillComposer()` seam; the producer is the Library App-View **Reuse** action (#523), which posts it across the App-View iframe boundary (the INBOUND twin of the existing OUTBOUND `nano-navigate` DI-preview bridge). The filesystem **Import** control (#524) is NOT a producer of this message — it lives in the same compose mount and fills directly through `fillComposer()`, no cross-frame hop. The `type` string is exported ONCE as `DG_COMPOSE_FILL_MESSAGE` from pages/delivery-graphs/mount.js — the Reuse producer imports it, never re-declares a synonym.",
+    shape: '{ type: "nano-delivery-graph-compose-fill", graphJson: string }',
+  },
+  "deliveryGraph.library.import.submit": {
+    category: "wire",
+    name: "deliveryGraph.library.import.submit",
+    owner: "operations/importToLibrary.ts",
+    semantics:
+      "Filesystem-import request body POSTed to /actions/delivery-graph/library/import (issue #524, epic #519 S5). Declared in openapi.yaml as `ImportToLibrarySubmit`; the compose App-View's `<input type=file accept=.json>` reads the picked file's text client-side and POSTs it here as the raw `graphJson` string. The door validates + compiles it through the SAME `parseAndCompileText` pipeline preview/stage/save use, then persists `source: imported` — an uncompilable graph is a clean 400 and NOTHING is written. Its `name` defaults to the imported graph's own `name`; an explicit `name` overrides it (an unnamed graph with no override is a clean 400 — the library id is name-derived). Related to but DISTINCT from `SaveToLibrarySubmit` (which is graphJson-OR-digest and needs no required file text); consume this ONE shape across the openapi edge, the door, and the compose mount — do not re-declare a synonym.",
+    shape: "{ graphJson: string, name?: string, description?: string }",
+  },
 } as const satisfies Record<string, WireContract>;
 
 export const TYPE_CONTRACTS = {

package/app/deliveryGraph.test.ts

@@ -76,6 +76,90 @@ test("a non-object graph is rejected without throwing", () => {
   assertEquals(validateDeliveryGraph({ nodes: "nope" })[0].code, "empty-graph");
 });
 
+test("invalid-graph-name: a non-string top-level `name` is rejected, path-qualified", () => {
+  // Regression (#524 review): a JSON-string import body bypasses the OpenAPI shape gate, so a
+  // non-string `name` would otherwise reach the compiler and THROW out of `escapeXml` (surfacing as a
+  // 400 with no path-qualified `errors`). The semantic validator now catches it cleanly.
+  const err = hasCode(validateDeliveryGraph({ ...WELL_FORMED, name: 42 }), "invalid-graph-name");
+  assertEquals(err.path, "name");
+});
+
+test("invalid-graph-name: a top-level `name` longer than 255 chars is rejected, path-qualified", () => {
+  // Regression (#524 review): an over-long name would otherwise be persisted despite violating the
+  // openapi `DeliveryGraph.name` `maxLength: 255` contract.
+  const err = hasCode(validateDeliveryGraph({ ...WELL_FORMED, name: "x".repeat(256) }), "invalid-graph-name");
+  assertEquals(err.path, "name");
+  // The boundary (exactly 255) is accepted.
+  assertEquals(validateDeliveryGraph({ ...WELL_FORMED, name: "x".repeat(255) }), []);
+});
+
+test("invalid-graph-name: `name` length is counted by code point, not UTF-16 code unit", () => {
+  // Regression (#524 review): JS `String.length` counts UTF-16 code units, but openapi `maxLength`
+  // counts Unicode code points. A name of 255 astral characters (each 2 code units) is WITHIN the
+  // contract and must be accepted; the previous `String.length` check wrongly rejected it as 510.
+  const astral255 = "\u{1F600}".repeat(255); // 255 emoji code points = 510 UTF-16 code units
+  assertEquals([...astral255].length, 255);
+  assertEquals(validateDeliveryGraph({ ...WELL_FORMED, name: astral255 }), []);
+  // 256 code points is over the limit and rejected, path-qualified.
+  const astral256 = "\u{1F600}".repeat(256);
+  const err = hasCode(validateDeliveryGraph({ ...WELL_FORMED, name: astral256 }), "invalid-graph-name");
+  assertEquals(err.path, "name");
+});
+
+test("too-many-nodes: a node set larger than the openapi `maxItems: 256` cap is rejected", () => {
+  // Regression (#524 review): a JSON-string import/save body bypasses the OpenAPI shape gate, so the
+  // declared `nodes.maxItems: 256` bound is re-enforced here — otherwise an oversized-but-compilable
+  // graph reaches the layout/compiler and is persisted.
+  const node = (i: number) => ({ id: `n${i}`, kind: "human", human: { prompt: "x" } });
+  const tooMany = Array.from({ length: 257 }, (_, i) => node(i));
+  const err = hasCode(validateDeliveryGraph({ nodes: tooMany }), "too-many-nodes");
+  assertEquals(err.path, "nodes");
+  // The cap SHORT-CIRCUITS the per-node walk: an oversized array is rejected on the cap ALONE, so
+  // even when every node is independently invalid (here: `human` config of the wrong type) the
+  // validator returns ONLY the single `too-many-nodes` error rather than doing 257 nodes' worth of
+  // per-node validation/map-building work first (#533 review — make the resource limit effective).
+  const oversizedAndInvalid = Array.from({ length: 257 }, (_, i) => ({ id: `n${i}`, kind: "human", human: 42 }));
+  assertEquals(validateDeliveryGraph({ nodes: oversizedAndInvalid }), [
+    {
+      path: "nodes",
+      message: "delivery graph has too many nodes (257) — the limit is 256",
+      code: "too-many-nodes",
+    },
+  ]);
+  // The boundary (exactly 256) is accepted (no too-many-nodes error).
+  const exactly = Array.from({ length: 256 }, (_, i) => node(i));
+  assertEquals(
+    validateDeliveryGraph({ nodes: exactly }).filter((e) => e.code === "too-many-nodes"),
+    [],
+  );
+});
+
+test("too-many-edges: an edge set larger than the openapi `maxItems: 1024` cap is rejected", () => {
+  // Regression (#524 review): re-enforce `edges.maxItems: 1024` for the bypassed shape gate.
+  const nodes = [
+    { id: "a", kind: "human", human: { prompt: "x" } },
+    { id: "b", kind: "human", human: { prompt: "y" } },
+  ];
+  const tooMany = Array.from({ length: 1025 }, () => ({ from: "a", to: "b" }));
+  const err = hasCode(validateDeliveryGraph({ nodes, edges: tooMany }), "too-many-edges");
+  assertEquals(err.path, "edges");
+  // The cap SHORT-CIRCUITS the edge walk: an oversized edge array is rejected before any endpoint
+  // resolution / adjacency work, so even 1025 dangling edges surface ONLY the cap error, not 1025
+  // `dangling-edge` errors (#533 review — make the resource limit effective).
+  const oversizedDangling = Array.from({ length: 1025 }, () => ({ from: "ghost", to: "phantom" }));
+  const capOnly = validateDeliveryGraph({ nodes, edges: oversizedDangling });
+  assertEquals(capOnly.filter((e) => e.code === "dangling-edge"), []);
+  assertEquals(hasCode(capOnly, "too-many-edges").path, "edges");
+});
+
+test("too-many-emits: a node declaring more than the openapi `maxItems: 32` facts is rejected", () => {
+  // Regression (#524 review): re-enforce `DeliveryNodeCommon.emits.maxItems: 32` for the bypassed gate.
+  const emits = Array.from({ length: 33 }, (_, i) => ({ name: `f${i}`, type: "string" }));
+  const graph = { nodes: [{ id: "a", kind: "wait", wait: { kind: "capability", target: "x:y" }, emits }] };
+  const err = hasCode(validateDeliveryGraph(graph), "too-many-emits");
+  assertEquals(err.path, "nodes[0].emits");
+});
+
 test("unknown-kind: a node kind outside the closed allowlist is rejected, path-qualified", () => {
   const errors = validateDeliveryGraph({
     nodes: [{ id: "x", kind: "script", script: { run: "rm -rf /" } }],

package/app/deliveryGraph.ts

@@ -57,6 +57,10 @@ export function isDeliveryGuardScalarType(type: unknown): type is DeliveryGuardS
  * class (unknown-kind / dangling / cycle / bad-`from`) without string-matching the message. */
 export type DeliveryGraphErrorCode =
   | "empty-graph"
+  | "invalid-graph-name"
+  | "too-many-nodes"
+  | "too-many-edges"
+  | "too-many-emits"
   | "missing-id"
   | "invalid-id"
   | "duplicate-id"
@@ -130,6 +134,29 @@ export const FACT_NAME_MAX_LENGTH = 128;
 const NODE_ID_PATTERN = /^[A-Za-z_][A-Za-z0-9_.-]*$/;
 const NODE_ID_MAX_LENGTH = 128;
 
+/** The graph's optional top-level `name` must match openapi's `DeliveryGraph.name` `maxLength: 255`.
+ * Re-enforced here INDEPENDENTLY of the OpenAPI shape gate because later steps trust it: the compiler
+ * feeds `graph.name` straight into `escapeXml(processName)` / `escapeMermaid`, so a NON-STRING name
+ * (`.replace` is not a function) THROWS out of the compiler — a bypassed shape gate (a direct delegate
+ * call, or a JSON-string body like the library import door's `graphJson`, where the OpenAPI schema
+ * never touches the parsed value) would otherwise surface as an unhandled fault mapped to a 400 with
+ * NO path-qualified `errors`, and an over-long name would be persisted despite violating the contract.
+ * Validating it here turns both into a clean, path-qualified `invalid-graph-name` failure. Length is
+ * counted by Unicode CODE POINT (`[...name].length`), matching openapi/JSON-Schema `maxLength`
+ * semantics — NOT JS `String.length`, which counts UTF-16 code units and would reject an in-contract
+ * name of ≤255 astral characters (e.g. emoji) as over-long. */
+const GRAPH_NAME_MAX_LENGTH = 255;
+
+/** Whole-graph fan-out caps mirroring openapi's `DeliveryGraph` array bounds (`nodes.maxItems: 256`,
+ * `edges.maxItems: 1024`) and `DeliveryNodeCommon.emits.maxItems: 32`. Re-enforced here INDEPENDENTLY
+ * of the OpenAPI shape gate because a bypassed gate (a direct delegate call, or a JSON-string body
+ * like the library import/save doors' `graphJson`, where the schema never touches the parsed value)
+ * would otherwise let an oversized-but-compilable graph reach the layout/compiler and be persisted —
+ * both violating the declared contract and exposing the import path to avoidable CPU/memory growth. */
+const GRAPH_MAX_NODES = 256;
+const GRAPH_MAX_EDGES = 1024;
+const NODE_MAX_EMITS = 32;
+
 /** The per-kind config key a node of the given kind must carry (`agent` → `agent`, etc.). */
 const CONFIG_KEY: Record<DeliveryNodeKind, string> = {
   agent: "agent",
@@ -212,6 +239,39 @@ export function validateDeliveryGraph(graph: unknown): DeliveryGraphError[] {
       message: "delivery graph is empty — declare at least one node",
       code: "empty-graph",
     });
+  } else if (nodes.length > GRAPH_MAX_NODES) {
+    // Short-circuit on the cap BEFORE the per-node walk. Raw `graphJson` (the import/save doors)
+    // bypasses openapi's `nodes.maxItems: 256`, so an arbitrarily large array would otherwise still
+    // drive the full `nodes.forEach` — building the id→facts/types maps for every supplied node —
+    // before returning the same 400. Rejecting on the cap ALONE keeps the advertised resource limit
+    // effective (bounded validation work on an oversized untrusted import), rather than merely
+    // reporting it after doing the unbounded walk.
+    return [
+      {
+        path: "nodes",
+        message: `delivery graph has too many nodes (${nodes.length}) — the limit is ${GRAPH_MAX_NODES}`,
+        code: "too-many-nodes",
+      },
+    ];
+  }
+
+  // Top-level `name` (optional): mirror openapi's `DeliveryGraph.name` `maxLength: 255`, INDEPENDENTLY
+  // of the shape gate — a non-string name would otherwise throw out of the compiler's `escapeXml`, and
+  // an over-long one would be persisted despite violating the contract (see GRAPH_NAME_MAX_LENGTH).
+  if (graph.name !== undefined) {
+    if (typeof graph.name !== "string") {
+      errors.push({
+        path: "name",
+        message: "delivery graph `name` must be a string",
+        code: "invalid-graph-name",
+      });
+    } else if ([...graph.name].length > GRAPH_NAME_MAX_LENGTH) {
+      errors.push({
+        path: "name",
+        message: `delivery graph \`name\` must be \u2264 ${GRAPH_NAME_MAX_LENGTH} characters`,
+        code: "invalid-graph-name",
+      });
+    }
   }
 
   // Pass 1: node ids + kinds + per-kind config + declared facts. Build the id → declared-facts map
@@ -305,6 +365,12 @@ export function validateDeliveryGraph(graph: unknown): DeliveryGraphError[] {
           message: "`emits` must be an array of typed fact declarations",
           code: "missing-config",
         });
+      } else if (rawNode.emits.length > NODE_MAX_EMITS) {
+        errors.push({
+          path: `${path}.emits`,
+          message: `node declares too many emitted facts (${rawNode.emits.length}) — the limit is ${NODE_MAX_EMITS}`,
+          code: "too-many-emits",
+        });
       } else {
         rawNode.emits.forEach((rawFact, j) => {
           if (!isRecord(rawFact) || typeof rawFact.name !== "string" || rawFact.name.length === 0) {
@@ -374,6 +440,19 @@ export function validateDeliveryGraph(graph: unknown): DeliveryGraphError[] {
       message: "`edges`, when present, must be an array of `{ from, to }` dependency edges",
       code: "invalid-edges",
     });
+  } else if (edges.length > GRAPH_MAX_EDGES) {
+    // Re-enforce openapi's `edges.maxItems: 1024` INDEPENDENTLY of the bypassed shape gate, so an
+    // oversized-but-compilable graph cannot reach the layout/compiler and be persisted. Short-circuit
+    // on the cap BEFORE the `edges.forEach` walk: like the node cap, a raw import that bypasses
+    // `maxItems` must not force endpoint resolution, `guardEdges` allocation, and adjacency work for
+    // every edge before returning the same 400 — so the advertised resource limit stays effective.
+    // Any node-level errors already accumulated in pass 1 are returned alongside the cap.
+    errors.push({
+      path: "edges",
+      message: `delivery graph has too many edges (${edges.length}) — the limit is ${GRAPH_MAX_EDGES}`,
+      code: "too-many-edges",
+    });
+    return errors;
   }
   // consumer (`to`) → set of upstream node ids (`from`'s node) — the dependency direction.
   const adjacency = new Map<string, Set<string>>();

package/app/deliveryGraphCompiler.ts

@@ -276,8 +276,10 @@ export async function compileDeliveryGraph(
     return { ok: false, errors: validationErrors.map(({ path, message }) => ({ path, message })) };
   }
 
-  // The graph passed both the OpenAPI shape gate (at the edge) and the semantic validator, so it is
-  // safe to narrow to the typed contract. Every field below is well-formed by construction.
+  // The graph passed the OpenAPI `DeliveryGraph` SHAPE gate (the runtime edge for the typed agent
+  // door; `validateDeliveryGraphShape` in the shared text-ingress for the graphJson-string doors) and
+  // the semantic validator, so it is safe to narrow to the typed contract. Every field below is
+  // well-formed by construction.
   // biome-ignore lint/plugin: validated external body narrowed to its contract after validateDeliveryGraph
   const typed = graph as DeliveryGraph;
   const nodes = [...typed.nodes].sort((a, b) => byCodeUnit(a.id, b.id));

package/app/deliveryGraphLibrary.test.ts

@@ -0,0 +1,134 @@
+// Unit coverage for the reusable delivery-graph LIBRARY aggregate (app/deliveryGraphLibrary.ts, issue
+// #522, epic #519 S3). Two layers: the PURE helpers (slugify, name-derived id, row builder) tested in
+// isolation, and the I/O (`saveLibraryEntry` upsert-on-name identity, `listLibraryEntries` newest-first,
+// `getLibraryEntry`, `deleteLibraryEntry` idempotence) exercised against the REAL provisioned SQLite
+// data layer so the migration + raw table ops are validated, not modelled.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { DataLayer } from "@nanobpm/urban";
+import { bootTestApp } from "@nanobpm/urban-testkit";
+import {
+  buildLibraryEntryRow,
+  deleteLibraryEntry,
+  deliveryGraphLibrary,
+  getLibraryEntry,
+  libraryEntryId,
+  listLibraryEntries,
+  saveLibraryEntry,
+  slugifyName,
+} from "./deliveryGraphLibrary.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+
+async function withData(fn: (data: DataLayer) => Promise<void>): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-dglib-"));
+  const app = await bootTestApp(APP_ROOT, { env: { NANO_APP_DB_URL: `file:${join(dir, "app.db")}` } });
+  try {
+    await fn(app.db);
+  } finally {
+    await app.stop?.();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const GRAPH = JSON.stringify({ name: "runbook", nodes: [] });
+
+// ── pure helpers ──────────────────────────────────────────────────────────────
+test("slugifyName: lowercases, collapses non-alphanumerics to single dashes, trims", () => {
+  assertEquals(slugifyName("Runbook A"), "runbook-a");
+  assertEquals(slugifyName("  My  Graph!! "), "my-graph");
+  assertEquals(slugifyName("weird__name.v2"), "weird-name-v2");
+});
+
+test("slugifyName: a name with no alphanumerics falls back to `graph`", () => {
+  assertEquals(slugifyName("   "), "graph");
+  assertEquals(slugifyName("***"), "graph");
+});
+
+test("libraryEntryId: `<slug>-<8-hex>`, stable per name and trimmed identically", () => {
+  const id = libraryEntryId("Runbook A");
+  assert(/^runbook-a-[0-9a-f]{8}$/.test(id), `unexpected id: ${id}`);
+  // Deterministic + whitespace-insensitive (trimmed to the same identity).
+  assertEquals(libraryEntryId("Runbook A"), id);
+  assertEquals(libraryEntryId("  Runbook A  "), id);
+});
+
+test("libraryEntryId: names that slugify the same are disambiguated by the name hash", () => {
+  // Both slugify to `runbook-a`, but the short hash keys off the ORIGINAL trimmed name.
+  const a = libraryEntryId("Runbook A");
+  const b = libraryEntryId("runbook.a");
+  assert(a.startsWith("runbook-a-"));
+  assert(b.startsWith("runbook-a-"));
+  assert(a !== b, "distinct names must yield distinct ids even when their slugs match");
+});
+
+test("buildLibraryEntryRow: derives id from name, normalises a blank description to null", () => {
+  const row = buildLibraryEntryRow({ name: "  runbook  ", description: "   ", graphJson: GRAPH, source: "composed" });
+  assertEquals(row.id, libraryEntryId("runbook"));
+  assertEquals(row.name, "runbook");
+  assertEquals(row.description, null);
+  assertEquals(row.source, "composed");
+  assert(typeof row.created_at === "string" && row.created_at.length > 0);
+  assertEquals(row.updated_at, row.created_at);
+});
+
+// ── I/O against the real data layer ─────────────────────────────────────────────
+test("saveLibraryEntry: first save inserts; the row round-trips through get", async () => {
+  await withData(async (data) => {
+    const written = await saveLibraryEntry(
+      data,
+      buildLibraryEntryRow({ name: "runbook", description: "a note", graphJson: GRAPH, source: "composed" }),
+    );
+    const fetched = await getLibraryEntry(data, written.id);
+    assert(fetched !== null);
+    assertEquals(fetched?.name, "runbook");
+    assertEquals(fetched?.description, "a note");
+    assertEquals(fetched?.graph, GRAPH);
+    assertEquals(fetched?.source, "composed");
+  });
+});
+
+test("saveLibraryEntry: re-saving the same name UPSERTS (one row), refreshes graph, preserves created_at", async () => {
+  await withData(async (data) => {
+    const first = await saveLibraryEntry(
+      data,
+      buildLibraryEntryRow({ name: "runbook", graphJson: GRAPH, source: "composed", createdAt: "2024-01-01T00:00:00.000Z" }),
+    );
+    const editedGraph = JSON.stringify({ name: "runbook", nodes: [{ id: "a", kind: "human" }] });
+    const second = await saveLibraryEntry(
+      data,
+      buildLibraryEntryRow({ name: "runbook", graphJson: editedGraph, source: "from-staged" }),
+    );
+    assertEquals(first.id, second.id);
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 1);
+    const fetched = await getLibraryEntry(data, second.id);
+    assertEquals(fetched?.graph, editedGraph);
+    assertEquals(fetched?.source, "from-staged");
+    // created_at is anchored to the first save; the graph edit did not move the row.
+    assertEquals(fetched?.created_at, "2024-01-01T00:00:00.000Z");
+  });
+});
+
+test("listLibraryEntries: every saved entry, newest first", async () => {
+  await withData(async (data) => {
+    await saveLibraryEntry(data, buildLibraryEntryRow({ name: "older", graphJson: GRAPH, source: "composed", createdAt: "2024-01-01T00:00:00.000Z" }));
+    await saveLibraryEntry(data, buildLibraryEntryRow({ name: "newer", graphJson: GRAPH, source: "composed", createdAt: "2024-06-01T00:00:00.000Z" }));
+    const list = await listLibraryEntries(data);
+    assertEquals(list.length, 2);
+    assertEquals(list[0].name, "newer");
+    assertEquals(list[1].name, "older");
+  });
+});
+
+test("deleteLibraryEntry: removes a known entry (true); a re-delete is an idempotent no-op (false)", async () => {
+  await withData(async (data) => {
+    const row = await saveLibraryEntry(data, buildLibraryEntryRow({ name: "runbook", graphJson: GRAPH, source: "composed" }));
+    assertEquals(await deleteLibraryEntry(data, row.id), true);
+    assertEquals(await getLibraryEntry(data, row.id), null);
+    assertEquals(await deleteLibraryEntry(data, row.id), false);
+    assertEquals(await deleteLibraryEntry(data, "no-such-id"), false);
+  });
+});

package/app/deliveryGraphLibrary.ts

@@ -0,0 +1,153 @@
+// app/deliveryGraphLibrary.ts — the reusable delivery-graph LIBRARY aggregate (issue #522, epic #519
+// S3). The durable base the Library App-View (S4/#523), filesystem import (S5/#524), and export
+// (S6/#525) build on. It mirrors the `delivery_graph_proposals` store/door pattern
+// (`app/deliveryGraphProposals.ts`) so downstream slices meet a familiar API surface — but with two
+// deliberate differences that reflect what a library IS:
+//
+//   • Keyed by a slug + short-hash of the entry NAME (`libraryEntryId`), NOT the content digest.
+//     Proposals are content-addressed (a re-compile is a new digest, a new row); a library entry is
+//     meant to have its GRAPH edited in place — the NAME *is* the identity, so keying on the human,
+//     readable name gives a stable, human-readable id and re-saving the same name is idempotent
+//     (upsert: the graph refreshes, `created_at` is preserved). Because the id is derived from the
+//     name, a rename is NOT an in-place update: it derives a *new* id (a new entry), leaving the old
+//     row until it is explicitly deleted.
+//   • NO TTL. A proposal ages out of the cockpit; a saved library entry is kept until explicitly
+//     deleted — there is no `expires_at` and no sweep.
+//
+// The pure helpers (`slugifyName`, `libraryEntryId`, `buildLibraryEntryRow`) are DB-free so they
+// unit-test in isolation; `saveLibraryEntry` / `listLibraryEntries` / `getLibraryEntry` /
+// `deleteLibraryEntry` supply the I/O.
+
+import { createHash } from "node:crypto";
+import type { DataLayer } from "@nanobpm/urban";
+import type { DeliveryGraphLibraryEntry as DeliveryGraphLibraryEntryDto } from "../nano-generated/api-io.d.ts";
+
+const now = () => new Date().toISOString();
+
+/** How a library entry entered the library. `composed` = saved from a raw graph JSON; `imported` =
+ * loaded from the filesystem (S5/#524); `from-staged` / `from-dispatched` = saved from a staged or
+ * dispatched proposal's digest (its already-stored graph reused). */
+export const DELIVERY_LIBRARY_SOURCES = ["composed", "imported", "from-staged", "from-dispatched"] as const;
+export type DeliveryLibrarySource = typeof DELIVERY_LIBRARY_SOURCES[number];
+
+/** One saved library entry — the durable row keyed by name-derived `id`. `graph` is the serialised
+ * `DeliveryGraph` JSON (validated/compiled before it is ever written). */
+export interface DeliveryGraphLibraryEntry {
+  id: string;
+  name: string;
+  description: string | null;
+  graph: string;
+  source: DeliveryLibrarySource;
+  created_at: string;
+  updated_at: string;
+}
+
+/** The `delivery_graph_library` aggregate accessor — the durable library store keyed by name-derived `id`. */
+export const deliveryGraphLibrary = (data: DataLayer) =>
+  data.table<DeliveryGraphLibraryEntry>("delivery_graph_library", "id");
+
+/** Slugify a human name into an id-safe token: lowercased, non-alphanumerics collapsed to single `-`,
+ * trimmed of leading/trailing `-`. A name with no alphanumerics (e.g. `"   "`) yields `"graph"` so the
+ * id is always well-formed. */
+export function slugifyName(name: string): string {
+  const slug = name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || "graph";
+}
+
+/** The stable, human-readable library id for a NAME — `<slug>-<sha256(name)[:8]>`. Derived from the
+ * (mutable) name rather than the content, so an entry's graph can be edited without moving its row, and
+ * re-saving the SAME name is idempotent (same id → upsert). The short hash disambiguates two names that
+ * slugify to the same token (e.g. `"Runbook A"` vs `"runbook.a"`), keyed off the ORIGINAL trimmed name
+ * so the id survives punctuation the slug drops. */
+export function libraryEntryId(name: string): string {
+  const trimmed = name.trim();
+  const hash = createHash("sha256").update(trimmed).digest("hex").slice(0, 8);
+  return `${slugifyName(trimmed)}-${hash}`;
+}
+
+/** Build a durable library row for a NAMED graph. `createdAt` is preserved across an idempotent re-save
+ * of the same name (omit it — defaulting to now — for a first save). `graphJson` must already be a
+ * validated/compiled `DeliveryGraph` serialisation (the door validates via `parseAndCompileText`). */
+export function buildLibraryEntryRow(input: {
+  name: string;
+  description?: string | null;
+  graphJson: string;
+  source: DeliveryLibrarySource;
+  createdAt?: string;
+}): DeliveryGraphLibraryEntry {
+  const at = now();
+  const name = input.name.trim();
+  const description = typeof input.description === "string" && input.description.trim() !== "" ? input.description.trim() : null;
+  return {
+    id: libraryEntryId(name),
+    name,
+    description,
+    graph: input.graphJson,
+    source: input.source,
+    created_at: input.createdAt ?? at,
+    updated_at: at,
+  };
+}
+
+/** Persist a library entry, UPSERTing on its name-derived `id`. A first save inserts; a re-save of the
+ * same name refreshes the graph/description/source and `updated_at` while PRESERVING the original
+ * `created_at` — an edit updates in place, it does not create a duplicate. Because `created_at` is
+ * preserved, a re-save never changes the entry's position in the newest-first list, regardless of
+ * which fields (graph included) changed. Returns the written row. */
+export async function saveLibraryEntry(data: DataLayer, row: DeliveryGraphLibraryEntry): Promise<DeliveryGraphLibraryEntry> {
+  const table = deliveryGraphLibrary(data);
+  const existing = await table.get(row.id);
+  const toWrite: DeliveryGraphLibraryEntry = existing ? { ...row, created_at: existing.created_at } : row;
+  if (existing) {
+    const { id, ...patch } = toWrite;
+    await table.update(row.id, patch);
+  } else {
+    await table.insert(toWrite);
+  }
+  return toWrite;
+}
+
+/** Every saved library entry, newest first. The Library App-View (S4/#523) polls this to render the
+ * list. Read-only; no write. `DataLayer.all()` has no `ORDER BY` (see `app/lineage.ts`), so — like
+ * every other read-projection in this app — we sort in memory. The library is a curated, small-
+ * cardinality set (human-saved graphs), so the O(n log n) sort is not a hot path; the
+ * `ix_delivery_graph_library_created` index is kept for a future DB-ordered read path. */
+export async function listLibraryEntries(data: DataLayer): Promise<DeliveryGraphLibraryEntry[]> {
+  const rows = await deliveryGraphLibrary(data).all();
+  return rows.sort((a, b) => b.created_at.localeCompare(a.created_at));
+}
+
+/** Load one library entry by its `id`, or null when unknown. */
+export async function getLibraryEntry(data: DataLayer, id: string): Promise<DeliveryGraphLibraryEntry | null> {
+  return (await deliveryGraphLibrary(data).get(id)) ?? null;
+}
+
+/** Delete one library entry by its `id`. Returns true when a row was removed, false when the id named
+ * nothing (idempotent — a re-delete of an already-gone entry is a clean no-op). */
+export async function deleteLibraryEntry(data: DataLayer, id: string): Promise<boolean> {
+  const table = deliveryGraphLibrary(data);
+  const existing = await table.get(id);
+  if (!existing) return false;
+  await table.delete(id);
+  return true;
+}
+
+/** Project a durable library row into the operator-facing `DeliveryGraphLibraryEntry` DTO the doors
+ * return — the single snake_case → camelCase mapping, so no door re-invents it (derivation over
+ * duplication). The full `graph` JSON is carried so the export affordance (S6/#525) can build a
+ * client-side download from a list payload without a second fetch. */
+export function libraryEntryDto(row: DeliveryGraphLibraryEntry): DeliveryGraphLibraryEntryDto {
+  return {
+    id: row.id,
+    name: row.name,
+    description: row.description,
+    graph: row.graph,
+    source: row.source,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}