@cleocode/playbooks 2026.4.88

package/dist/state.js

@@ -0,0 +1,322 @@
+/**
+ * State layer for playbook runtime — CRUD against playbook_runs + playbook_approvals.
+ * Uses node:sqlite DatabaseSync for consistency with rest of CLEO.
+ *
+ * All JSON-shaped columns (`bindings`, `iteration_counts`) are serialized to
+ * text at the write boundary and strictly parsed on read. Parse failures throw
+ * rather than silently reset state, per the data-integrity contract of ADR-013.
+ *
+ * Multi-column updates and cross-table operations run inside a BEGIN/COMMIT
+ * transaction so partial failures cannot leave the run in a half-mutated state.
+ *
+ * @task T889 / T904 / W4-8
+ */
+import { randomUUID } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Row mappers
+// ---------------------------------------------------------------------------
+/**
+ * Strictly parses a JSON payload stored in a playbook column. Throws a
+ * descriptive error on malformed JSON so state corruption surfaces at the
+ * boundary rather than mutating downstream logic.
+ */
+function parseJsonColumn(raw, column, runId) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`playbook state: failed to parse JSON column "${column}" for run ${runId}: ${message}`);
+    }
+}
+/**
+ * Maps a snake_case `playbook_runs` row to the contract-shaped
+ * {@link PlaybookRun}. Performs strict JSON parsing and validates the status
+ * column against the enum.
+ */
+function rowToPlaybookRun(row) {
+    const bindings = parseJsonColumn(row.bindings, 'bindings', row.run_id);
+    const iterationCounts = parseJsonColumn(row.iteration_counts, 'iteration_counts', row.run_id);
+    return {
+        runId: row.run_id,
+        playbookName: row.playbook_name,
+        playbookHash: row.playbook_hash,
+        currentNode: row.current_node,
+        bindings,
+        errorContext: row.error_context,
+        status: row.status,
+        iterationCounts,
+        epicId: row.epic_id ?? undefined,
+        sessionId: row.session_id ?? undefined,
+        startedAt: row.started_at,
+        completedAt: row.completed_at ?? undefined,
+    };
+}
+/**
+ * Maps a snake_case `playbook_approvals` row to the contract-shaped
+ * {@link PlaybookApproval}. Converts the integer `auto_passed` column to a
+ * boolean at the boundary.
+ */
+function rowToPlaybookApproval(row) {
+    return {
+        approvalId: row.approval_id,
+        runId: row.run_id,
+        nodeId: row.node_id,
+        token: row.token,
+        requestedAt: row.requested_at,
+        approvedAt: row.approved_at ?? undefined,
+        approver: row.approver ?? undefined,
+        reason: row.reason ?? undefined,
+        status: row.status,
+        autoPassed: row.auto_passed === 1,
+    };
+}
+// ---------------------------------------------------------------------------
+// Playbook run CRUD
+// ---------------------------------------------------------------------------
+/**
+ * Inserts a new playbook run with a freshly generated UUID, `status='running'`,
+ * and the provided initial bindings. Returns the hydrated {@link PlaybookRun}
+ * read back from the row so callers see all server-defaulted columns
+ * (`started_at`, empty `iteration_counts`, etc.).
+ */
+export function createPlaybookRun(db, input) {
+    const runId = randomUUID();
+    const bindingsJson = JSON.stringify(input.initialBindings ?? {});
+    const insert = db.prepare(`INSERT INTO playbook_runs (
+       run_id, playbook_name, playbook_hash, bindings, status,
+       iteration_counts, epic_id, session_id
+     ) VALUES (?, ?, ?, ?, 'running', '{}', ?, ?)`);
+    insert.run(runId, input.playbookName, input.playbookHash, bindingsJson, input.epicId ?? null, input.sessionId ?? null);
+    const row = db.prepare('SELECT * FROM playbook_runs WHERE run_id = ?').get(runId);
+    if (!row) {
+        throw new Error(`playbook state: failed to read back run ${runId} after insert`);
+    }
+    return rowToPlaybookRun(row);
+}
+/**
+ * Fetches a playbook run by its primary key. Returns `null` when the run
+ * does not exist. Never throws on missing rows.
+ */
+export function getPlaybookRun(db, runId) {
+    const row = db.prepare('SELECT * FROM playbook_runs WHERE run_id = ?').get(runId);
+    return row ? rowToPlaybookRun(row) : null;
+}
+/**
+ * Applies a partial patch to a playbook run inside a transaction so mixed
+ * column updates (e.g. `status` + `currentNode`) commit atomically. Returns
+ * the fully-hydrated run read back after commit.
+ */
+export function updatePlaybookRun(db, runId, patch) {
+    const sets = [];
+    const values = [];
+    if ('playbookName' in patch && patch.playbookName !== undefined) {
+        sets.push('playbook_name = ?');
+        values.push(patch.playbookName);
+    }
+    if ('playbookHash' in patch && patch.playbookHash !== undefined) {
+        sets.push('playbook_hash = ?');
+        values.push(patch.playbookHash);
+    }
+    if ('currentNode' in patch) {
+        sets.push('current_node = ?');
+        values.push(patch.currentNode ?? null);
+    }
+    if ('bindings' in patch && patch.bindings !== undefined) {
+        sets.push('bindings = ?');
+        values.push(JSON.stringify(patch.bindings));
+    }
+    if ('errorContext' in patch) {
+        sets.push('error_context = ?');
+        values.push(patch.errorContext ?? null);
+    }
+    if ('status' in patch && patch.status !== undefined) {
+        sets.push('status = ?');
+        values.push(patch.status);
+    }
+    if ('iterationCounts' in patch && patch.iterationCounts !== undefined) {
+        sets.push('iteration_counts = ?');
+        values.push(JSON.stringify(patch.iterationCounts));
+    }
+    if ('epicId' in patch) {
+        sets.push('epic_id = ?');
+        values.push(patch.epicId ?? null);
+    }
+    if ('sessionId' in patch) {
+        sets.push('session_id = ?');
+        values.push(patch.sessionId ?? null);
+    }
+    if ('completedAt' in patch) {
+        sets.push('completed_at = ?');
+        values.push(patch.completedAt ?? null);
+    }
+    if (sets.length === 0) {
+        const existing = getPlaybookRun(db, runId);
+        if (!existing) {
+            throw new Error(`playbook state: run ${runId} not found for update`);
+        }
+        return existing;
+    }
+    db.exec('BEGIN');
+    try {
+        const stmt = db.prepare(`UPDATE playbook_runs SET ${sets.join(', ')} WHERE run_id = ?`);
+        values.push(runId);
+        const result = stmt.run(...values);
+        if (result.changes === 0) {
+            throw new Error(`playbook state: run ${runId} not found for update`);
+        }
+        db.exec('COMMIT');
+    }
+    catch (err) {
+        db.exec('ROLLBACK');
+        throw err;
+    }
+    const row = db.prepare('SELECT * FROM playbook_runs WHERE run_id = ?').get(runId);
+    if (!row) {
+        throw new Error(`playbook state: run ${runId} disappeared after update`);
+    }
+    return rowToPlaybookRun(row);
+}
+/**
+ * Lists playbook runs filtered by status and/or epic. Defaults to `ORDER BY
+ * started_at DESC` so the newest runs surface first for dashboards.
+ */
+export function listPlaybookRuns(db, opts = {}) {
+    const clauses = [];
+    const values = [];
+    if (opts.status) {
+        clauses.push('status = ?');
+        values.push(opts.status);
+    }
+    if (opts.epicId) {
+        clauses.push('epic_id = ?');
+        values.push(opts.epicId);
+    }
+    const where = clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '';
+    const limitClause = typeof opts.limit === 'number' ? 'LIMIT ?' : '';
+    if (limitClause)
+        values.push(opts.limit ?? 0);
+    const sql = `SELECT * FROM playbook_runs ${where} ORDER BY started_at DESC ${limitClause}`;
+    const rows = db.prepare(sql).all(...values);
+    return rows.map(rowToPlaybookRun);
+}
+/**
+ * Deletes a playbook run by primary key. Returns `true` if a row was removed.
+ * CASCADE wipes all associated approvals via the foreign-key constraint on
+ * `playbook_approvals.run_id`.
+ */
+export function deletePlaybookRun(db, runId) {
+    const result = db.prepare('DELETE FROM playbook_runs WHERE run_id = ?').run(runId);
+    return Number(result.changes) > 0;
+}
+// ---------------------------------------------------------------------------
+// Playbook approval CRUD
+// ---------------------------------------------------------------------------
+/**
+ * Inserts a new approval record with a freshly generated UUID, `status='pending'`,
+ * and the caller-supplied opaque token. Returns the hydrated
+ * {@link PlaybookApproval} so callers see the server-defaulted `requested_at`.
+ */
+export function createPlaybookApproval(db, input) {
+    const approvalId = randomUUID();
+    const autoPassed = input.autoPassed ? 1 : 0;
+    db.prepare(`INSERT INTO playbook_approvals (
+       approval_id, run_id, node_id, token, status, auto_passed
+     ) VALUES (?, ?, ?, ?, 'pending', ?)`).run(approvalId, input.runId, input.nodeId, input.token, autoPassed);
+    const row = db
+        .prepare('SELECT * FROM playbook_approvals WHERE approval_id = ?')
+        .get(approvalId);
+    if (!row) {
+        throw new Error(`playbook state: failed to read back approval ${approvalId} after insert`);
+    }
+    return rowToPlaybookApproval(row);
+}
+/**
+ * Fetches an approval by its opaque token. Returns `null` if no row matches.
+ * The token column carries a UNIQUE constraint so at most one row is returned.
+ */
+export function getPlaybookApprovalByToken(db, token) {
+    const row = db.prepare('SELECT * FROM playbook_approvals WHERE token = ?').get(token);
+    return row ? rowToPlaybookApproval(row) : null;
+}
+/**
+ * Applies a partial patch to an approval record inside a transaction. Used by
+ * the approval-resume flow to transactionally set both `status` and
+ * `approved_at` when a human resolves a HITL checkpoint.
+ */
+export function updatePlaybookApproval(db, approvalId, patch) {
+    const sets = [];
+    const values = [];
+    if ('runId' in patch && patch.runId !== undefined) {
+        sets.push('run_id = ?');
+        values.push(patch.runId);
+    }
+    if ('nodeId' in patch && patch.nodeId !== undefined) {
+        sets.push('node_id = ?');
+        values.push(patch.nodeId);
+    }
+    if ('token' in patch && patch.token !== undefined) {
+        sets.push('token = ?');
+        values.push(patch.token);
+    }
+    if ('approvedAt' in patch) {
+        sets.push('approved_at = ?');
+        values.push(patch.approvedAt ?? null);
+    }
+    if ('approver' in patch) {
+        sets.push('approver = ?');
+        values.push(patch.approver ?? null);
+    }
+    if ('reason' in patch) {
+        sets.push('reason = ?');
+        values.push(patch.reason ?? null);
+    }
+    if ('status' in patch && patch.status !== undefined) {
+        sets.push('status = ?');
+        values.push(patch.status);
+    }
+    if ('autoPassed' in patch && patch.autoPassed !== undefined) {
+        sets.push('auto_passed = ?');
+        values.push(patch.autoPassed ? 1 : 0);
+    }
+    if (sets.length === 0) {
+        const row = db
+            .prepare('SELECT * FROM playbook_approvals WHERE approval_id = ?')
+            .get(approvalId);
+        if (!row) {
+            throw new Error(`playbook state: approval ${approvalId} not found for update`);
+        }
+        return rowToPlaybookApproval(row);
+    }
+    db.exec('BEGIN');
+    try {
+        const stmt = db.prepare(`UPDATE playbook_approvals SET ${sets.join(', ')} WHERE approval_id = ?`);
+        values.push(approvalId);
+        const result = stmt.run(...values);
+        if (result.changes === 0) {
+            throw new Error(`playbook state: approval ${approvalId} not found for update`);
+        }
+        db.exec('COMMIT');
+    }
+    catch (err) {
+        db.exec('ROLLBACK');
+        throw err;
+    }
+    const row = db
+        .prepare('SELECT * FROM playbook_approvals WHERE approval_id = ?')
+        .get(approvalId);
+    if (!row) {
+        throw new Error(`playbook state: approval ${approvalId} disappeared after update`);
+    }
+    return rowToPlaybookApproval(row);
+}
+/**
+ * Lists all approvals for a given run, ordered by `requested_at ASC` so the
+ * first HITL checkpoint surfaces first.
+ */
+export function listPlaybookApprovals(db, runId) {
+    const rows = db
+        .prepare('SELECT * FROM playbook_approvals WHERE run_id = ? ORDER BY requested_at ASC, approval_id ASC')
+        .all(runId);
+    return rows.map(rowToPlaybookApproval);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@cleocode/playbooks",
+  "version": "2026.4.88",
+  "description": "Playbook DSL + runtime for CLEO — T889 Orchestration Coherence v3",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "dependencies": {
+    "drizzle-orm": "1.0.0-beta.19-d95b7a4",
+    "js-yaml": "^4.1.0",
+    "@cleocode/contracts": "2026.4.88",
+    "@cleocode/core": "2026.4.88"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
+  },
+  "keywords": [
+    "cleo",
+    "playbook",
+    "orchestration",
+    "dsl",
+    "cantbook"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kryptobaseddev/cleo.git",
+    "directory": "packages/playbooks"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/__tests__/approval.test.ts

@@ -0,0 +1,295 @@
+/**
+ * W4-16 approval / resume-token real-sqlite tests (no mocks).
+ *
+ * All tests run against an in-memory sqlite DB with the T889 migration
+ * applied — zero fakes, zero stubs, zero mocks of `createHmac`.
+ *
+ * @task T889 / T908 / W4-16
+ */
+
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import type { DatabaseSync as _DatabaseSyncType } from 'node:sqlite';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  approveGate,
+  createApprovalGate,
+  E_APPROVAL_ALREADY_DECIDED,
+  E_APPROVAL_NOT_FOUND,
+  generateResumeToken,
+  getPendingApprovals,
+  getPlaybookSecret,
+  rejectGate,
+} from '../approval.js';
+
+const _require = createRequire(import.meta.url);
+type DatabaseSync = _DatabaseSyncType;
+const { DatabaseSync } = _require('node:sqlite') as {
+  DatabaseSync: new (...args: ConstructorParameters<typeof _DatabaseSyncType>) => DatabaseSync;
+};
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MIGRATION_SQL = resolve(
+  __dirname,
+  '../../../core/migrations/drizzle-tasks/20260417220000_t889-playbook-tables/migration.sql',
+);
+
+function applyMigration(db: DatabaseSync, sql: string): void {
+  const statements = sql
+    .split(/--> statement-breakpoint/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  for (const stmt of statements) {
+    const lines = stmt.split('\n');
+    const hasSql = lines.some((l) => l.trim().length > 0 && !l.trim().startsWith('--'));
+    if (hasSql) db.exec(stmt);
+  }
+}
+
+function seedRun(db: DatabaseSync, runId: string): void {
+  db.prepare(
+    `INSERT INTO playbook_runs (run_id, playbook_name, playbook_hash)
+     VALUES (?, 'rcasd', 'hash')`,
+  ).run(runId);
+}
+
+describe('W4-16: Resume-token generation', () => {
+  it('is deterministic for identical inputs', () => {
+    const t1 = generateResumeToken('r1', 'n1', { a: 1, b: 2 }, 'secret');
+    const t2 = generateResumeToken('r1', 'n1', { a: 1, b: 2 }, 'secret');
+    expect(t1).toBe(t2);
+    expect(t1).toHaveLength(32);
+    expect(t1).toMatch(/^[0-9a-f]{32}$/);
+  });
+
+  it('differs for different runIds', () => {
+    const a = generateResumeToken('r1', 'n1', {}, 'secret');
+    const b = generateResumeToken('r2', 'n1', {}, 'secret');
+    expect(a).not.toBe(b);
+  });
+
+  it('differs for different bindings', () => {
+    const a = generateResumeToken('r1', 'n1', { x: 1 }, 'secret');
+    const b = generateResumeToken('r1', 'n1', { x: 2 }, 'secret');
+    expect(a).not.toBe(b);
+  });
+
+  it('is binding-key-order invariant via canonical JSON', () => {
+    const a = generateResumeToken('r1', 'n1', { alpha: 1, beta: 2 }, 'secret');
+    const b = generateResumeToken('r1', 'n1', { beta: 2, alpha: 1 }, 'secret');
+    expect(a).toBe(b);
+  });
+
+  it('differs when secret rotates', () => {
+    const a = generateResumeToken('r1', 'n1', {}, 'secretA');
+    const b = generateResumeToken('r1', 'n1', {}, 'secretB');
+    expect(a).not.toBe(b);
+  });
+
+  it('getPlaybookSecret reads CLEO_PLAYBOOK_SECRET from env override', () => {
+    const s = getPlaybookSecret({ CLEO_PLAYBOOK_SECRET: 'prod-secret' } as NodeJS.ProcessEnv);
+    expect(s).toBe('prod-secret');
+    const fallback = getPlaybookSecret({} as NodeJS.ProcessEnv);
+    expect(fallback.length).toBeGreaterThan(0);
+    expect(fallback).not.toBe('prod-secret');
+  });
+});
+
+describe('W4-16: Approval DB operations', () => {
+  let db: DatabaseSync;
+
+  beforeEach(() => {
+    db = new DatabaseSync(':memory:');
+    db.exec('PRAGMA foreign_keys=ON');
+    applyMigration(db, readFileSync(MIGRATION_SQL, 'utf8'));
+    seedRun(db, 'run-1');
+  });
+
+  afterEach(() => db.close());
+
+  it('createApprovalGate writes row with generated token and status=pending', () => {
+    const approval = createApprovalGate(db, {
+      runId: 'run-1',
+      nodeId: 'node-a',
+      bindings: { x: 1 },
+      secret: 'test-secret',
+    });
+    const expectedToken = generateResumeToken('run-1', 'node-a', { x: 1 }, 'test-secret');
+    expect(approval.token).toBe(expectedToken);
+    expect(approval.status).toBe('pending');
+    expect(approval.autoPassed).toBe(false);
+    expect(approval.approvalId).toMatch(/^[0-9a-f-]{36}$/);
+    expect(approval.requestedAt).toBeTruthy();
+    expect(approval.approvedAt).toBeUndefined();
+    expect(approval.approver).toBeUndefined();
+    expect(approval.reason).toBeUndefined();
+  });
+
+  it('createApprovalGate with autoPassed=true records status=approved + auto_passed=1', () => {
+    const approval = createApprovalGate(db, {
+      runId: 'run-1',
+      nodeId: 'node-auto',
+      bindings: {},
+      autoPassed: true,
+      approver: 'policy:conservative',
+      reason: 'auto-approve low-risk deterministic step',
+      secret: 'test-secret',
+    });
+    expect(approval.status).toBe('approved');
+    expect(approval.autoPassed).toBe(true);
+    expect(approval.approver).toBe('policy:conservative');
+    expect(approval.reason).toBe('auto-approve low-risk deterministic step');
+
+    const row = db
+      .prepare('SELECT auto_passed FROM playbook_approvals WHERE approval_id = ?')
+      .get(approval.approvalId) as { auto_passed: number };
+    expect(row.auto_passed).toBe(1);
+  });
+
+  it('approveGate sets status=approved, approvedAt, approver, reason', () => {
+    const gate = createApprovalGate(db, {
+      runId: 'run-1',
+      nodeId: 'node-b',
+      bindings: { y: 'hello' },
+      secret: 'test-secret',
+    });
+    const updated = approveGate(db, gate.token, 'keaton@cleo', 'reviewed RCASD plan');
+    expect(updated.status).toBe('approved');
+    expect(updated.approver).toBe('keaton@cleo');
+    expect(updated.reason).toBe('reviewed RCASD plan');
+    expect(updated.approvedAt).toBeTruthy();
+    expect(updated.autoPassed).toBe(false);
+    expect(updated.approvalId).toBe(gate.approvalId);
+  });
+
+  it('approveGate throws E_APPROVAL_NOT_FOUND for unknown token', () => {
+    expect(() => approveGate(db, 'deadbeef'.repeat(4), 'who', 'why')).toThrowError(
+      new RegExp(E_APPROVAL_NOT_FOUND),
+    );
+  });
+
+  it('approveGate throws E_APPROVAL_ALREADY_DECIDED for already-approved gate', () => {
+    const gate = createApprovalGate(db, {
+      runId: 'run-1',
+      nodeId: 'node-c',
+      bindings: {},
+      secret: 'test-secret',
+    });
+    approveGate(db, gate.token, 'user1');
+    expect(() => approveGate(db, gate.token, 'user2')).toThrowError(
+      new RegExp(E_APPROVAL_ALREADY_DECIDED),
+    );
+  });
+
+  it('rejectGate sets status=rejected with approver + reason', () => {
+    const gate = createApprovalGate(db, {
+      runId: 'run-1',
+      nodeId: 'node-d',
+      bindings: {},
+      secret: 'test-secret',
+    });
+    const updated = rejectGate(db, gate.token, 'auditor', 'contract violation');
+    expect(updated.status).toBe('rejected');
+    expect(updated.approver).toBe('auditor');
+    expect(updated.reason).toBe('contract violation');
+    expect(updated.approvedAt).toBeTruthy();
+  });
+
+  it('rejectGate throws E_APPROVAL_ALREADY_DECIDED for already-rejected gate', () => {
+    const gate = createApprovalGate(db, {
+      runId: 'run-1',
+      nodeId: 'node-e',
+      bindings: {},
+      secret: 'test-secret',
+    });
+    rejectGate(db, gate.token, 'user1');
+    expect(() => rejectGate(db, gate.token, 'user2')).toThrowError(
+      new RegExp(E_APPROVAL_ALREADY_DECIDED),
+    );
+    expect(() => approveGate(db, gate.token, 'user3')).toThrowError(
+      new RegExp(E_APPROVAL_ALREADY_DECIDED),
+    );
+  });
+
+  it('getPendingApprovals returns only pending, ordered by requestedAt', () => {
+    const g1 = createApprovalGate(db, {
+      runId: 'run-1',
+      nodeId: 'node-p1',
+      bindings: { k: 1 },
+      secret: 'test-secret',
+    });
+    const g2 = createApprovalGate(db, {
+      runId: 'run-1',
+      nodeId: 'node-p2',
+      bindings: { k: 2 },
+      secret: 'test-secret',
+    });
+    const g3 = createApprovalGate(db, {
+      runId: 'run-1',
+      nodeId: 'node-p3',
+      bindings: { k: 3 },
+      autoPassed: true,
+      secret: 'test-secret',
+    });
+
+    const pending = getPendingApprovals(db);
+    expect(pending).toHaveLength(2);
+    const ids = pending.map((p) => p.approvalId);
+    expect(ids).toContain(g1.approvalId);
+    expect(ids).toContain(g2.approvalId);
+    expect(ids).not.toContain(g3.approvalId);
+    // Ordering: requested_at ASC, then approval_id ASC as tiebreaker
+    // since both inserts happened in the same second under datetime('now').
+    const sorted = [...pending].sort((a, b) => {
+      const t = a.requestedAt.localeCompare(b.requestedAt);
+      return t !== 0 ? t : a.approvalId.localeCompare(b.approvalId);
+    });
+    expect(pending.map((p) => p.approvalId)).toEqual(sorted.map((p) => p.approvalId));
+  });
+
+  it('full flow: create -> approve -> pending list shrinks', () => {
+    const a = createApprovalGate(db, {
+      runId: 'run-1',
+      nodeId: 'node-x',
+      bindings: { a: 1 },
+      secret: 'test-secret',
+    });
+    const b = createApprovalGate(db, {
+      runId: 'run-1',
+      nodeId: 'node-y',
+      bindings: { b: 2 },
+      secret: 'test-secret',
+    });
+    expect(getPendingApprovals(db)).toHaveLength(2);
+
+    // Query by token round-trips the same approvalId
+    const lookup = db
+      .prepare('SELECT approval_id FROM playbook_approvals WHERE token = ?')
+      .get(a.token) as { approval_id: string };
+    expect(lookup.approval_id).toBe(a.approvalId);
+
+    approveGate(db, a.token, 'reviewer');
+
+    const remaining = getPendingApprovals(db);
+    expect(remaining).toHaveLength(1);
+    expect(remaining[0]?.approvalId).toBe(b.approvalId);
+  });
+
+  it('rowToApproval handles null approver/reason correctly (fields omitted)', () => {
+    const gate = createApprovalGate(db, {
+      runId: 'run-1',
+      nodeId: 'node-null',
+      bindings: {},
+      secret: 'test-secret',
+    });
+    // Never approved — approver/reason/approvedAt should all be absent
+    expect(gate.approver).toBeUndefined();
+    expect(gate.reason).toBeUndefined();
+    expect(gate.approvedAt).toBeUndefined();
+    expect('approver' in gate).toBe(false);
+    expect('reason' in gate).toBe(false);
+    expect('approvedAt' in gate).toBe(false);
+  });
+});