@nanobpm/nano-workforce 0.138.2 → 0.139.0

package/db/migrations/084_plan_wave_tasks_effective_status.sql

@@ -0,0 +1,51 @@
+-- Epic-detail wave-state: a merged slice must not read "opened" (drift with the summary bar).
+--
+-- `plan_wave_tasks` (059) is the per-task display VIEW the Epic-detail "Wave state" grid binds
+-- (pages/epic-detail.page.json → `wave-state`). Its `status` column exposed the RAW
+-- `plan_tasks.status` verbatim — but nothing writes `plan_tasks.status = 'merged'` when a slice's PR
+-- lands: the merge write-path flips `pull_requests.status` (and, for a close-without-merge, the
+-- `abandonClosedPr` self-heal flips the task terminal), yet a *merged* PR leaves its `plan_tasks` row
+-- frozen at `opened`. So a converged-and-merged slice kept showing Status "opened" in the grid, even
+-- as its sibling summary VIEWs (`plan_wave_counts`/`plan_wave_summary`) already counted it `merged`
+-- via the PR join. That is exactly the drift AGENTS.md forbids: two sibling VIEWs over the same join
+-- disagreeing on whether a slice is merged.
+--
+-- Fix by DERIVING the displayed status the SAME way the count VIEWs bucket `merged` (082): a task is
+-- `merged` iff its PR reached `pull_requests__tracking.derived_status = 'merged'` (the terminal-folded
+-- status the canonical runtime reads, ADR-0065), otherwise it falls through to its own
+-- `plan_tasks.status`. This keeps the per-task grid and the per-wave summary bar in exact agreement —
+-- a single notion of "effective task status", still fully DERIVED with no write-path. `pr_url` /
+-- `process_key` link targets are re-exported by the `pull_requests__tracking` VIEW (`p.*`), so the
+-- single join now sources both the effective status and the link targets. The "Active" tab filter
+-- (`status IN (pending,opened,escalated,waiting-for-lane,blocked)`) therefore drops a merged slice as
+-- intended instead of stranding it under "opened".
+--
+-- Forward-only VIEW redefinition (DROP then CREATE); a merged VIEW is not editable in place. The
+-- runner wraps each file in its own transaction, so this file must NOT contain BEGIN/COMMIT. Kept a
+-- plain `CREATE VIEW … AS SELECT … FROM …` (no CTE / no select-list subquery) so the static
+-- pages↔schema contract guard (scripts/pages-contract.test.ts) still parses it. Numbered after 083.
+
+DROP VIEW IF EXISTS plan_wave_tasks;
+
+CREATE VIEW plan_wave_tasks AS
+SELECT
+  t.id AS id,
+  t.plan_key AS plan_key,
+  t.task_index AS task_index,
+  t.task_id AS task_id,
+  t.title AS title,
+  t.prompt AS prompt,
+  CASE WHEN p.derived_status = 'merged' THEN 'merged' ELSE t.status END AS status,
+  t.pr_key AS pr_key,
+  t.summary AS summary,
+  t.created_at AS created_at,
+  t.updated_at AS updated_at,
+  t.wave AS wave,
+  t.open_question AS open_question,
+  t.answer AS answer,
+  t.draft_pr_key AS draft_pr_key,
+  t.corr_key AS corr_key,
+  p.url AS pr_url,
+  p.process_key AS process_key
+FROM plan_tasks t
+LEFT JOIN pull_requests__tracking p ON p.pr_key = t.pr_key;

package/db/migrations/085_delivery_graph_library.sql

@@ -0,0 +1,32 @@
+-- The reusable delivery-graph LIBRARY store (issue #522, epic #519 S3) — the durable base the
+-- Library App-View (S4/#523), filesystem import (S5/#524), and export (S6/#525) build on. Unlike the
+-- `staged` proposals store (`delivery_graph_proposals`, migration 075), which is content-digest-keyed
+-- and TTL-swept, a library entry is meant to be EDITED and KEPT: its graph can change while its
+-- identity stays stable, and it never ages out.
+--
+--   • id (PK) — a slug + short-hash of the entry's NAME (`<slug>-<sha256(name)[:8]>`), NOT the content
+--     digest. Library entries are editable (the graph is mutable), so keying on the content would move
+--     the row on every edit; keying on the (human, mutable) name gives a stable, human-readable id that
+--     is idempotent on re-save of the same name (an upsert refreshes the graph, preserves created_at).
+--   • name — the human name of the saved graph. Its slug/hash derives the id.
+--   • description — an optional human note.
+--   • graph — the `DeliveryGraph` JSON (serialised). Validated (compiled) at save time so an
+--     uncompilable graph can never be persisted.
+--   • source — how the entry entered the library: `composed` (saved from a raw graph JSON),
+--     `imported` (loaded from the filesystem, S5/#524), `from-staged` (saved from a staged proposal's
+--     digest), or `from-dispatched` (saved from a dispatched proposal's digest).
+--   • created_at / updated_at — ISO-8601 timestamps; created_at is preserved across an idempotent
+--     re-save of the same name. No `expires_at`: the library has NO TTL (contrast `delivery_graph_proposals`).
+CREATE TABLE IF NOT EXISTS delivery_graph_library (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  description TEXT,
+  graph TEXT NOT NULL,
+  source TEXT NOT NULL DEFAULT 'composed',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+-- The list App-View orders entries newest-first; index the sort key.
+CREATE INDEX IF NOT EXISTS ix_delivery_graph_library_created
+  ON delivery_graph_library (created_at);

package/openapi.yaml

@@ -1663,6 +1663,21 @@ components:
           description: >-
             OPTIONAL run-level ISO-8601 SLA for `human` nodes (#505) before they record an `escalated`
             outcome. Absent → the `P1D` default. An invalid duration is rejected at submit.
+    DeliveryGraphDismissRequest:
+      description: >-
+        The OPERATOR dismiss request (#520). The cockpit's staged-proposals grid posts the content
+        `digest` of the proposal the operator wants to discard as noise; the door loads that staged
+        proposal and flips it to the terminal `dismissed` status. Dismiss is an operator action — this
+        request carries NO graph and NO token (the graph is already staged; the operator's click is the
+        approval). It launches nothing.
+      type: object
+      additionalProperties: false
+      required:
+        - digest
+      properties:
+        digest:
+          type: string
+          description: The staged proposal's content digest (its primary key) — the proposal to dismiss.
     DeliveryGraphProposalBpmnRequest:
       description: >-
         Request the compiled BPMN of a staged delivery-graph proposal for read-only DI PREVIEW. Carries
@@ -1757,6 +1772,153 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/StagedProposalSummary"
+    DeliveryGraphLibraryEntry:
+      description: >-
+        One saved reusable delivery-graph LIBRARY entry (issue #522, epic #519 S3) — the durable base
+        the Library App-View (S4/#523), filesystem import (S5/#524), and export (S6/#525) build on.
+        Unlike a `staged` proposal (content-digest-keyed, TTL-swept), a library entry is keyed by a
+        slug + short-hash of its NAME — the name *is* the identity — so its graph can be edited in
+        place without moving the row, and it never ages out. (A rename is not an in-place update:
+        because the id is derived from the name, renaming derives a new id, i.e. a new entry; the old
+        row remains until explicitly deleted.) The full `graph` JSON is carried so the export
+        affordance (S6/#525) can build a client-side download from the list payload without a second
+        fetch.
+      type: object
+      additionalProperties: false
+      required:
+        - id
+        - name
+        - description
+        - graph
+        - source
+        - createdAt
+        - updatedAt
+      properties:
+        id:
+          type: string
+          description: The entry's stable id — `<slug>-<sha256(name)[:8]>`, derived from the name (not the content).
+        name:
+          type: string
+          description: The saved graph's human name.
+        description:
+          type: string
+          nullable: true
+          description: An optional human note, or null when none was given.
+        graph:
+          type: string
+          description: The `DeliveryGraph` JSON (serialised) — validated/compiled before it was ever persisted.
+        source:
+          type: string
+          enum: [composed, imported, from-staged, from-dispatched]
+          description: How the entry entered the library (raw compose, filesystem import, or a staged/dispatched proposal's digest).
+        createdAt:
+          type: string
+          description: When the entry was first saved (ISO-8601); preserved across an idempotent re-save of the same name.
+        updatedAt:
+          type: string
+          description: When the entry was last saved/edited (ISO-8601).
+    DeliveryGraphLibraryList:
+      description: Every saved library entry (issue #522), newest first.
+      type: object
+      additionalProperties: false
+      required:
+        - count
+        - entries
+      properties:
+        count:
+          type: integer
+        entries:
+          type: array
+          items:
+            $ref: "#/components/schemas/DeliveryGraphLibraryEntry"
+    SaveToLibrarySubmit:
+      description: >-
+        Save a delivery graph to the reusable library (issue #522). Carries the entry `name` (its
+        slug/hash derive the id) and an optional `description`, PLUS exactly one graph source: either a
+        raw `graphJson` STRING (validated + compiled before persisting, `source: composed`), or the
+        `digest` of an existing staged/dispatched proposal whose already-stored graph is reused
+        (`source: from-staged` / `from-dispatched`). A graph that fails to compile is a clean 400 and
+        nothing is persisted.
+      type: object
+      additionalProperties: false
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          description: The entry's human name — its slug + short-hash derive the stable library id (re-saving the same name upserts).
+        description:
+          type: string
+          description: An optional human note stored alongside the entry.
+        graphJson:
+          type: string
+          description: >-
+            A raw `DeliveryGraph` JSON string to validate, compile and save (`source: composed`).
+            Mutually exclusive with `digest`.
+        digest:
+          type: string
+          description: The content digest of an existing staged/dispatched proposal whose stored graph is reused. Mutually exclusive with `graphJson`.
+    ImportToLibrarySubmit:
+      description: >-
+        Import a delivery graph into the reusable library FROM A FILE (issue #524, epic #519 S5). The
+        compose App-View's `<input type=file accept=.json>` reads the selected file's text client-side
+        and POSTs it here as the raw `graphJson` string. The door validates + compiles it via the SAME
+        `parseAndCompileText` pipeline the preview/stage/save doors use, then persists it with
+        `source: imported`. A file that is not valid JSON, or a graph that fails to compile, is a clean
+        400 with path-qualified errors and NOTHING is persisted. The entry `name` defaults to the
+        imported graph's own `name`; an explicit `name` overrides it (an unnamed graph with no override
+        is a clean 400).
+      type: object
+      additionalProperties: false
+      required:
+        - graphJson
+      properties:
+        graphJson:
+          type: string
+          description: The raw `DeliveryGraph` JSON text read from the imported file (validated + compiled before persisting).
+        name:
+          type: string
+          description: Optional override for the entry name — its slug + short-hash derive the library id. Defaults to the imported graph's own `name`.
+        description:
+          type: string
+          description: An optional human note stored alongside the imported entry.
+    SaveToLibraryResult:
+      description: >-
+        The save-to-library outcome (issue #522). `ok` discriminates success; success carries the
+        persisted `entry`, a failure carries a human `error` (and, for a compile failure, path-qualified
+        `errors`). Nothing is persisted on a failure.
+      type: object
+      additionalProperties: false
+      required:
+        - ok
+      properties:
+        ok:
+          type: boolean
+          description: True when the graph validated and the entry was saved; false otherwise.
+        error:
+          type: string
+          description: A human-readable failure message.
+        errors:
+          type: array
+          items:
+            $ref: "#/components/schemas/DeliveryCompileError"
+          description: Path-qualified validation/compile failures, when the submitted or referenced graph was malformed.
+        entry:
+          $ref: "#/components/schemas/DeliveryGraphLibraryEntry"
+    DeleteLibraryEntryResult:
+      description: The delete-library-entry outcome (issue #522). `deleted` is true when a row was removed, false when the id named nothing (idempotent).
+      type: object
+      additionalProperties: false
+      required:
+        - ok
+        - deleted
+      properties:
+        ok:
+          type: boolean
+          description: True — the request was well-formed and processed.
+        deleted:
+          type: boolean
+          description: True when an entry was removed; false when the id named no entry (a re-delete is a clean no-op).
     DeliveryGraphTextResult:
       description: >-
         The delivery-graph text-ingress outcome (issue #460) — a single shape covering the JSON-paste
@@ -3020,6 +3182,39 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/DeliveryGraphTextResult"
+  /actions/delivery-graph/dismiss:
+    post:
+      operationId: dismissProposal
+      summary: OPERATOR DISMISS — discard a staged delivery-graph proposal by its digest as noise (idempotent). (#520)
+      description: >-
+        The OPERATOR-ONLY dismiss door (#520). The cockpit's staged-proposals grid posts the `digest` of
+        the proposal the operator wants to discard as noise; this door loads that live `staged` proposal
+        and flips it to the terminal `dismissed` status, so it drops out of the staged list — exactly like
+        `superseded`/`expired`, but recording a deliberate operator discard rather than a TTL sweep or a
+        newer digest landing. It launches nothing. Idempotent: a re-dismiss of an already-terminal
+        (dismissed / dispatched / superseded / expired) or unknown digest is a clean 400, leaving state
+        untouched.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DeliveryGraphDismissRequest"
+      responses:
+        "200":
+          description: The staged proposal was dismissed; it drops out of the staged list.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeliveryGraphTextResult"
+        "400":
+          description: >-
+            The digest was missing, or named no live staged proposal (unknown / already dismissed /
+            dispatched / superseded / expired). The body carries a human `error`. Nothing changed.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeliveryGraphTextResult"
   /actions/delivery-graph/proposal-bpmn:
     post:
       operationId: previewProposalBpmn
@@ -3076,6 +3271,177 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /actions/delivery-graph/library/save:
+    post:
+      operationId: saveToLibrary
+      summary: Save a delivery graph to the reusable library — from a raw graph JSON or an existing proposal digest (issue #522, #519 S3).
+      description: >-
+        Persist a delivery graph to the reusable LIBRARY (issue #522, epic #519 S3) — the durable base
+        S4/S5/S6 build on. The request carries the entry `name` (its slug + short-hash derive the stable
+        library id, so re-saving the same name upserts) plus EITHER a raw `graphJson` STRING (validated
+        and compiled via the SAME `parseAndCompileText` pipeline the preview/stage doors use, then saved
+        with `source: composed`) OR the `digest` of an existing staged/dispatched proposal whose
+        already-stored graph is reused (`source: from-staged` / `from-dispatched`). A graph that is not
+        valid JSON or fails to compile is a clean 400 and NOTHING is persisted (an uncompilable graph can
+        never enter the library). Unlike a staged proposal, a library entry has no TTL. This door is
+        INTENTIONALLY UNGUARDED (no shared-secret requirement), unlike the get/delete/import library
+        doors: it is also invoked by a DECLARATIVE page row action ("Save to library" on the
+        In-flight/History grid) that structurally cannot attach the `x-hook-secret` header, so a guard
+        here would make the door unreachable by its own UI. See PR #533 review.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SaveToLibrarySubmit"
+      responses:
+        "200":
+          description: The graph validated and the entry was saved (upserted on its name-derived id).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SaveToLibraryResult"
+        "400":
+          description: The request was malformed, the referenced digest named no stored graph, or the graph failed to compile — nothing persisted.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SaveToLibraryResult"
+  /actions/delivery-graph/library/import:
+    post:
+      operationId: importToLibrary
+      summary: Import a delivery graph FROM A FILE into the reusable library (issue #524, #519 S5).
+      description: >-
+        Import a delivery graph into the LIBRARY from a filesystem file (issue #524, epic #519 S5). The
+        compose App-View's `<input type=file accept=.json>` reads the chosen file's text client-side and
+        POSTs it here as the raw `graphJson`. The door validates + compiles it via the SAME
+        `parseAndCompileText` pipeline the preview/stage/save doors use, then persists it with
+        `source: imported`. A file that is not valid JSON, or a graph that fails to compile, is a clean
+        400 with path-qualified errors and NOTHING is persisted. The entry name defaults to the imported
+        graph's own `name` (an explicit `name` overrides it). The optional shared-secret guard mirrors the
+        get/delete library doors: when NANO_PR_WEBHOOK_SECRET is set, callers must present it via the
+        x-hook-secret header (unset → open). (The `save` door is unguarded — it is also reached by a
+        declarative page row action that cannot carry the header.)
+      security:
+        - hookSecret: []
+        - {}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ImportToLibrarySubmit"
+      responses:
+        "200":
+          description: The imported graph validated and the entry was saved (source=imported).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SaveToLibraryResult"
+        "400":
+          description: The file was not valid JSON, carried no usable name, or the graph failed to compile — nothing persisted.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SaveToLibraryResult"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SaveToLibraryResult"
+  /delivery-graph/library:
+    get:
+      operationId: listLibrary
+      summary: List the saved reusable delivery-graph library entries (issue #522, #519 S3), newest first.
+      description: >-
+        The read behind the Library App-View (S4/#523): every saved library entry, newest first, with
+        its full `graph` JSON so the export affordance (S6/#525) can build a client-side download from
+        the list payload. Read-only. The optional shared-secret guard mirrors the other read doors
+        (getLineage / listActivePrs / listStagedProposals): when NANO_PR_WEBHOOK_SECRET is set, callers
+        must present it via the x-hook-secret header.
+      security:
+        - hookSecret: []
+        - {}
+      responses:
+        "200":
+          description: The saved library entries, newest first.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeliveryGraphLibraryList"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+  /delivery-graph/library/{id}:
+    get:
+      operationId: getLibraryEntry
+      summary: Fetch one saved library entry by id (issue #522, #519 S3).
+      description: >-
+        Return one saved library entry (issue #522) by its `id`, including its full `graph` JSON. An
+        unknown id is a clean 404. The optional shared-secret guard mirrors the other read doors.
+      security:
+        - hookSecret: []
+        - {}
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The library entry's id (`<slug>-<sha256(name)[:8]>`).
+      responses:
+        "200":
+          description: The library entry.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeliveryGraphLibraryEntry"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "404":
+          description: No library entry exists for the given id.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+    delete:
+      operationId: deleteLibraryEntry
+      summary: Delete one saved library entry by id (issue #522, #519 S3).
+      description: >-
+        Delete one saved library entry (issue #522) by its `id`. Idempotent — deleting an id that names
+        no entry returns `deleted: false` (a clean no-op), not an error. The optional shared-secret guard
+        mirrors the other write doors.
+      security:
+        - hookSecret: []
+        - {}
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The library entry's id to delete.
+      responses:
+        "200":
+          description: The delete was processed (see `deleted` for whether a row was actually removed).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeleteLibraryEntryResult"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /actions/start/feature:
     post:
       operationId: startFeature

package/operations/deleteLibraryEntry.test.ts

@@ -0,0 +1,88 @@
+// Tests for DELETE /app/api/delivery-graph/library/{id} → `deleteLibraryEntry` (issue #522, epic #519
+// S3). Idempotent delete: a known id is removed (`deleted:true`); an unknown / already-gone id is a
+// clean no-op (`deleted:false`), never an error.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi, DataLayer } from "@nanobpm/urban";
+import { bootTestApp } from "@nanobpm/urban-testkit";
+import { buildLibraryEntryRow, deliveryGraphLibrary, saveLibraryEntry } from "../app/deliveryGraphLibrary.ts";
+import { noopLog } from "../test/log.ts";
+import handler from "./deleteLibraryEntry.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+const GRAPH = JSON.stringify({ name: "runbook", nodes: [] });
+
+async function withApp(fn: (app: AppApi, data: DataLayer) => Promise<void>): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-dglibdel-"));
+  const app = await bootTestApp(APP_ROOT, { env: { NANO_APP_DB_URL: `file:${join(dir, "app.db")}` } });
+  try {
+    const edge = { data: app.db, log: noopLog() } as unknown as AppApi;
+    await fn(edge, app.db);
+  } finally {
+    await app.stop?.();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const req = { headers: new Headers() } as any;
+async function call(app: AppApi, id: string) {
+  return (await handler({ req, params: { id }, query: {} } as any, app)) as any;
+}
+
+test("delete-library-entry: a known id → 200 deleted:true and the row is gone", async () => {
+  await withApp(async (app, data) => {
+    const saved = await saveLibraryEntry(data, buildLibraryEntryRow({ name: "runbook", graphJson: GRAPH, source: "composed" }));
+    const res = await call(app, saved.id);
+    assertEquals(res.status, 200);
+    assertEquals(res.body.ok, true);
+    assertEquals(res.body.deleted, true);
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 0);
+  });
+});
+
+test("delete-library-entry: an unknown id → 200 deleted:false (idempotent no-op)", async () => {
+  await withApp(async (app) => {
+    const res = await call(app, "no-such-id");
+    assertEquals(res.status, 200);
+    assertEquals(res.body.ok, true);
+    assertEquals(res.body.deleted, false);
+  });
+});
+
+test("delete-library-entry: a re-delete of an already-gone id → deleted:false", async () => {
+  await withApp(async (app, data) => {
+    const saved = await saveLibraryEntry(data, buildLibraryEntryRow({ name: "runbook", graphJson: GRAPH, source: "composed" }));
+    assertEquals((await call(app, saved.id)).body.deleted, true);
+    assertEquals((await call(app, saved.id)).body.deleted, false);
+  });
+});
+
+// The optional shared-secret guard is enforced in the handler (not by OpenAPI `security`), mirroring
+// the other write/read doors. `SECRET` is captured at module import, so we cache-bust re-import the
+// handler with NANO_PR_WEBHOOK_SECRET set to exercise both the rejected (401) path (which must NOT
+// delete) and the authorized (200) path against a real booted data layer holding a known entry.
+test("delete-library-entry: shared-secret guard — 401 without x-hook-secret (no delete), 200 with it", async () => {
+  await withApp(async (app, data) => {
+    const saved = await saveLibraryEntry(data, buildLibraryEntryRow({ name: "runbook", graphJson: GRAPH, source: "composed" }));
+    const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+    process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+    try {
+      const mod = await import(`./deleteLibraryEntry.ts?guard=${Date.now()}`);
+      const guarded = mod.default as (c: any, a: any) => Promise<any>;
+      const bad = await guarded({ req: { headers: new Headers() }, params: { id: saved.id }, query: {} } as any, app);
+      assertEquals(bad.status, 401);
+      // The rejected request must not have touched the row.
+      assertEquals((await deliveryGraphLibrary(data).all()).length, 1);
+      const ok = await guarded({ req: { headers: new Headers({ "x-hook-secret": "s3cr3t" }) }, params: { id: saved.id }, query: {} } as any, app);
+      assertEquals(ok.status, 200);
+      assertEquals(ok.body.deleted, true);
+      assertEquals((await deliveryGraphLibrary(data).all()).length, 0);
+    } finally {
+      if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+      else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+    }
+  });
+});

package/operations/deleteLibraryEntry.ts

@@ -0,0 +1,23 @@
+// DELETE /app/api/delivery-graph/library/{id} → operationId `deleteLibraryEntry` (issue #522, epic
+// #519 S3). Delete one saved library entry by its `id`. Idempotent: deleting an id that names no entry
+// returns `deleted: false` (a clean no-op), not an error — so a double-click / retry from the S4
+// Library App-View never errors.
+//
+// The optional shared-secret guard mirrors the other write/read doors: when NANO_PR_WEBHOOK_SECRET is
+// set, callers must present it via the x-hook-secret header; unset → open.
+
+import { deleteLibraryEntry } from "../app/deliveryGraphLibrary.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("deleteLibraryEntry", async ({ params, req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("deleteLibraryEntry rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const deleted = await deleteLibraryEntry(app.data, params.id);
+  app.log.info("delete-library-entry", { id: params.id, deleted });
+  return { status: 200, body: { ok: true, deleted } };
+});