cloving 1.3.0 → 1.5.0

package/dist/src/storage/decision-snapshots.js

@@ -1,14 +1,10 @@
+import { loadCommandWaits } from "./command-wait-rows.js";
 import { loadDecisions, loadDocuments, } from "./decision-rows.js";
-import { latestSequence, loadAttempts, loadSnapshot, outboxRow, projectionRows, text, } from "./domain-rows.js";
+import { latestSequence, loadAttempts, loadSnapshot, projectionRows, text, } from "./domain-rows.js";
 import { loadEffects } from "./effect-rows.js";
-export async function loadOperationSnapshot(connection) {
-    return {
-        outbox: (await connection.all("SELECT operation_id, kind, run_id, created_sequence, released_sequence FROM outbox ORDER BY created_sequence, rowid")).map(outboxRow),
-        deliveries: await loadAttempts(connection),
-    };
-}
 export async function loadProjections(connection) {
     return {
+        waits: await loadCommandWaits(connection),
         ...(await projectionRows(connection)),
         ...(await loadDecisions(connection)),
         deliveries: await loadAttempts(connection),
@@ -23,9 +19,21 @@ export async function loadDecided(connection) {
         documents: await loadDocuments(connection),
     };
 }
-export async function loadCurrent(connection) {
+export async function loadEffected(connection) {
     return {
         ...(await loadDecided(connection)),
         effects: await loadEffects(connection),
     };
 }
+export async function loadCurrent(connection) {
+    return {
+        ...(await loadEffected(connection)),
+        waits: await loadCommandWaits(connection),
+    };
+}
+export async function loadWaiting(connection) {
+    return {
+        ...(await loadEffected(connection)),
+        waits: await loadCommandWaits(connection, { version: "opened" }),
+    };
+}

package/dist/src/storage/domain-changes.d.ts

@@ -1,3 +1,4 @@
+import { type CommandWaitRow } from "./command-wait-rows.ts";
 import { type DetailRow, type DocumentRow, type GateRow } from "./decision-rows.ts";
 import { type CommandRow, type DefinitionRow, type EventRow, type RunRow, type SqlConnection } from "./domain-rows.ts";
 import { type EffectRows } from "./effect-rows.ts";
@@ -37,11 +38,12 @@ export interface DomainChange extends EffectRows {
     readonly staged: readonly StagedDelivery[];
     readonly closed: readonly ClosedDelivery[];
     readonly gates: readonly GateRow[];
+    readonly waits: readonly CommandWaitRow[];
     readonly details: readonly DetailRow[];
     readonly documents: readonly DocumentRow[];
     readonly completesAdoption: boolean;
 }
-export declare function persistChange(value: unknown, connection: SqlConnection): Promise<void>;
+export declare function persistChange(value: unknown, connection: SqlConnection): Promise<DomainChange>;
 export declare function gateParameters(row: GateRow): readonly unknown[];
 export declare function detailParameters(row: DetailRow): readonly unknown[];
 export declare function decisionStatements(change: Pick<DomainChange, "gates" | "details" | "documents">): readonly Statement[];

package/dist/src/storage/domain-changes.js

@@ -1,3 +1,4 @@
+import { commandWaitRow, commandWaitStatements, } from "./command-wait-rows.js";
 import { detailColumns, detailRow, documentRow, gateColumns, gateRow, } from "./decision-rows.js";
 import { commandRow, definitionRow, eventRow, integer, latestSequence, optionalInteger, optionalText, runRow, text, } from "./domain-rows.js";
 import { effectStatements } from "./effect-changes.js";
@@ -9,6 +10,7 @@ export async function persistChange(value, connection) {
         throw new Error("stale-authority-sequence");
     for (const statement of statements(change))
         await connection.run(statement.sql, statement.parameters);
+    return change;
 }
 function statements(change) {
     return [
@@ -48,6 +50,7 @@ function statements(change) {
         ...deliveryStatements(change),
         ...decisionStatements(change),
         ...effectStatements(change),
+        ...commandWaitStatements(change.waits),
         ...(change.completesAdoption
             ? [
                 {
@@ -195,6 +198,7 @@ function parseChange(value) {
             receipt: optionalText(row, "receipt"),
         })),
         gates: list(value, "gates").map(gateRow),
+        waits: list(value, "waits").map(commandWaitRow),
         details: list(value, "details").map(detailRow),
         documents: list(value, "documents").map(documentRow),
         budgets: list(value, "budgets").map(budgetRow),

package/dist/src/storage/domain-schema.d.ts

@@ -2,7 +2,12 @@ import { type SqlConnection } from "./domain-rows.ts";
 export declare const baselineVersion = 1;
 export declare const adoptedVersion = 2;
 export declare const decidedVersion = 3;
-export declare const currentVersion = 4;
+export declare const effectedVersion = 4;
+export declare const waitingVersion = 5;
+export declare const checkedVersion = 6;
+export declare const spendingVersion = 7;
+export declare const eventIndexVersion = 8;
+export declare const currentVersion = 9;
 export declare const baselineSchema = "\nCREATE TABLE schema_migrations (\n  version INTEGER PRIMARY KEY,\n  checksum TEXT NOT NULL\n) STRICT;\nCREATE TABLE events (\n  sequence INTEGER PRIMARY KEY,\n  type TEXT NOT NULL,\n  run_id TEXT NOT NULL,\n  command_id TEXT NOT NULL UNIQUE,\n  recorded_at TEXT NOT NULL,\n  request TEXT NOT NULL,\n  payload TEXT NOT NULL\n) STRICT;\nCREATE TABLE definitions (\n  pin TEXT PRIMARY KEY,\n  manifest TEXT NOT NULL\n) STRICT;\nCREATE TABLE runs (\n  run_id TEXT PRIMARY KEY,\n  status TEXT NOT NULL,\n  revision INTEGER NOT NULL,\n  workflow TEXT NOT NULL REFERENCES definitions (pin) DEFERRABLE INITIALLY DEFERRED,\n  paused_from TEXT,\n  gates TEXT NOT NULL,\n  sequence INTEGER NOT NULL REFERENCES events (sequence) DEFERRABLE INITIALLY DEFERRED\n) STRICT;\nCREATE TABLE commands (\n  command_id TEXT PRIMARY KEY,\n  request TEXT NOT NULL,\n  sequence INTEGER NOT NULL UNIQUE REFERENCES events (sequence) DEFERRABLE INITIALLY DEFERRED\n) STRICT;\nCREATE TABLE outbox (\n  operation_id TEXT PRIMARY KEY,\n  kind TEXT NOT NULL,\n  run_id TEXT NOT NULL REFERENCES runs (run_id) DEFERRABLE INITIALLY DEFERRED,\n  created_sequence INTEGER NOT NULL REFERENCES events (sequence) DEFERRABLE INITIALLY DEFERRED,\n  released_sequence INTEGER REFERENCES events (sequence) DEFERRABLE INITIALLY DEFERRED\n) STRICT;\n";
 export type SchemaRefusal = {
     readonly kind: "refused";
@@ -17,6 +22,16 @@ export type SchemaState = {
     readonly kind: "adopted";
 } | {
     readonly kind: "decided";
+} | {
+    readonly kind: "effected";
+} | {
+    readonly kind: "waiting";
+} | {
+    readonly kind: "checked";
+} | {
+    readonly kind: "indexed";
+} | {
+    readonly kind: "event-indexed";
 } | {
     readonly kind: "current";
 } | SchemaRefusal;

package/dist/src/storage/domain-schema.js

@@ -1,11 +1,17 @@
 import { createHash, randomUUID } from "node:crypto";
 import { DatabaseSync } from "node:sqlite";
 import { integer, optionalInteger, optionalText, text, } from "./domain-rows.js";
-import { effectSchema } from "./effect-schema.js";
+import { commandWaitSchema, commandWaitCheckSchema, } from "./command-wait-rows.js";
+import { effectSchema, runIndexes, spendingIndexes } from "./effect-schema.js";
 export const baselineVersion = 1;
 export const adoptedVersion = 2;
 export const decidedVersion = 3;
-export const currentVersion = 4;
+export const effectedVersion = 4;
+export const waitingVersion = 5;
+export const checkedVersion = 6;
+export const spendingVersion = 7;
+export const eventIndexVersion = 8;
+export const currentVersion = 9;
 export const baselineSchema = `
 CREATE TABLE schema_migrations (
   version INTEGER PRIMARY KEY,
@@ -102,9 +108,29 @@ CREATE TABLE documents (
   body TEXT NOT NULL
 ) STRICT;
 `;
-const schemas = [baselineSchema, adoption, decisions, effectSchema];
+const schemas = [
+    baselineSchema,
+    adoption,
+    decisions,
+    effectSchema,
+    commandWaitSchema,
+    commandWaitCheckSchema,
+    spendingIndexes,
+    "CREATE INDEX events_run_type_sequence ON events (run_id, type, sequence);",
+    runIndexes,
+];
 const checksums = schemas.map((schema) => createHash("sha256").update(schema).digest("hex"));
-const versionKinds = ["baseline", "adopted", "decided", "current"];
+const versionKinds = [
+    "baseline",
+    "adopted",
+    "decided",
+    "effected",
+    "waiting",
+    "checked",
+    "indexed",
+    "event-indexed",
+    "current",
+];
 export async function inspectSchema(connection) {
     const version = integer(await connection.get("PRAGMA user_version"), "user_version");
     const detail = String(version);
@@ -132,6 +158,11 @@ export async function createSchema(connection) {
     await recordVersion(connection, baselineVersion);
     await adoptSchema(connection, null);
     await upgradeSchema(connection, decidedVersion);
+    await upgradeSchema(connection, effectedVersion);
+    await upgradeSchema(connection, waitingVersion);
+    await upgradeSchema(connection, checkedVersion);
+    await upgradeSchema(connection, spendingVersion);
+    await upgradeSchema(connection, eventIndexVersion);
     await upgradeSchema(connection, currentVersion);
 }
 export async function upgradeSchema(connection, version) {

package/dist/src/storage/effect-schema.d.ts

@@ -1 +1,3 @@
 export declare const effectSchema = "\nCREATE TABLE run_budgets (\n  run_id TEXT PRIMARY KEY REFERENCES runs (run_id) DEFERRABLE INITIALLY DEFERRED,\n  effect_limit INTEGER NOT NULL,\n  spent INTEGER NOT NULL CHECK (spent <= effect_limit),\n  capabilities TEXT NOT NULL,\n  exhausted_sequence INTEGER REFERENCES events (sequence) DEFERRABLE INITIALLY DEFERRED\n) STRICT;\nCREATE TABLE operations (\n  operation_id TEXT PRIMARY KEY,\n  run_id TEXT NOT NULL REFERENCES runs (run_id) DEFERRABLE INITIALLY DEFERRED,\n  capability TEXT NOT NULL,\n  method TEXT NOT NULL,\n  target TEXT NOT NULL,\n  payload TEXT NOT NULL,\n  input_digest TEXT NOT NULL,\n  units INTEGER NOT NULL,\n  lease_key TEXT NOT NULL,\n  recovery_limit INTEGER NOT NULL,\n  status TEXT NOT NULL,\n  reason TEXT,\n  attempts INTEGER NOT NULL,\n  receipt TEXT,\n  worker TEXT,\n  result TEXT,\n  requested_sequence INTEGER NOT NULL REFERENCES events (sequence) DEFERRABLE INITIALLY DEFERRED,\n  wait_sequence INTEGER REFERENCES events (sequence) DEFERRABLE INITIALLY DEFERRED,\n  settled_sequence INTEGER REFERENCES events (sequence) DEFERRABLE INITIALLY DEFERRED\n) STRICT;\nCREATE INDEX operations_run ON operations (run_id);\nCREATE INDEX operations_waiting ON operations (wait_sequence) WHERE status = 'waiting';\nCREATE TABLE leases (\n  resource_key TEXT PRIMARY KEY,\n  operation_id TEXT NOT NULL REFERENCES operations (operation_id) DEFERRABLE INITIALLY DEFERRED,\n  generation INTEGER NOT NULL CHECK (generation > 0),\n  expires_at TEXT NOT NULL,\n  state TEXT NOT NULL CHECK (state IN ('held', 'expired', 'released')),\n  granted_sequence INTEGER NOT NULL REFERENCES events (sequence) DEFERRABLE INITIALLY DEFERRED\n) STRICT;\nCREATE INDEX leases_due ON leases (expires_at) WHERE state = 'held';\nCREATE TABLE effect_evidence (\n  sequence INTEGER PRIMARY KEY REFERENCES events (sequence) DEFERRABLE INITIALLY DEFERRED,\n  run_id TEXT NOT NULL,\n  operation_id TEXT NOT NULL,\n  disposition TEXT NOT NULL,\n  reason TEXT\n) STRICT;\nCREATE TABLE stopped_operations (\n  operation_id TEXT PRIMARY KEY,\n  run_id TEXT NOT NULL REFERENCES runs (run_id) DEFERRABLE INITIALLY DEFERRED,\n  sequence INTEGER NOT NULL REFERENCES events (sequence) DEFERRABLE INITIALLY DEFERRED\n) STRICT;\nCREATE TABLE dispatch_attempts (\n  effect_id TEXT PRIMARY KEY REFERENCES deliveries (effect_id) DEFERRABLE INITIALLY DEFERRED,\n  purpose TEXT NOT NULL,\n  lease_generation INTEGER,\n  authority_epoch INTEGER NOT NULL\n) STRICT;\n";
+export declare const spendingIndexes = "\nCREATE INDEX events_spend_window ON events (julianday(recorded_at));\nCREATE INDEX operations_worker_settled ON operations (settled_sequence) WHERE capability = 'claude';\nCREATE INDEX operations_worker_open ON operations (requested_sequence) WHERE capability = 'claude' AND settled_sequence IS NULL AND status NOT IN ('refused', 'completed', 'failed', 'stopped', 'cancelled');\n";
+export declare const runIndexes = "\nCREATE INDEX effect_evidence_run_sequence ON effect_evidence (run_id, sequence);\nCREATE INDEX stopped_operations_run ON stopped_operations (run_id);\n";

package/dist/src/storage/effect-schema.js

@@ -57,3 +57,12 @@ CREATE TABLE dispatch_attempts (
   authority_epoch INTEGER NOT NULL
 ) STRICT;
 `;
+export const spendingIndexes = `
+CREATE INDEX events_spend_window ON events (julianday(recorded_at));
+CREATE INDEX operations_worker_settled ON operations (settled_sequence) WHERE capability = 'claude';
+CREATE INDEX operations_worker_open ON operations (requested_sequence) WHERE capability = 'claude' AND settled_sequence IS NULL AND status NOT IN ('refused', 'completed', 'failed', 'stopped', 'cancelled');
+`;
+export const runIndexes = `
+CREATE INDEX effect_evidence_run_sequence ON effect_evidence (run_id, sequence);
+CREATE INDEX stopped_operations_run ON stopped_operations (run_id);
+`;

package/dist/src/storage/projection-changes.d.ts

@@ -0,0 +1,12 @@
+import type { ProjectionSnapshot } from "./decision-snapshots.ts";
+import type { DomainChange } from "./domain-changes.ts";
+import type { EventRow } from "./domain-rows.ts";
+import type { OperationRow } from "./effect-rows.ts";
+export declare function binaryOrder(left: string, right: string): number;
+export interface ProjectedChange extends Pick<DomainChange, "previous" | "sequence" | "definitions" | "runs" | "commands" | "added" | "released" | "staged" | "closed" | "gates" | "details" | "waits"> {
+    readonly events: readonly Pick<EventRow, "sequence" | "recordedAt">[];
+    readonly operations: readonly Pick<OperationRow, "operationId" | "status">[];
+}
+export declare function projectedChange(change: DomainChange): ProjectedChange;
+export declare function followingSequence(sequence: number, change: Pick<ProjectedChange, "events">): number;
+export declare function changedProjection(snapshot: ProjectionSnapshot, changes: readonly ProjectedChange[]): ProjectionSnapshot;

package/dist/src/storage/projection-changes.js

@@ -0,0 +1,194 @@
+export function binaryOrder(left, right) {
+    return Buffer.compare(Buffer.from(left), Buffer.from(right));
+}
+function upserted(rows, upsert) {
+    if (upsert.rows.length === 0)
+        return rows;
+    const next = [...rows];
+    const positions = new Map(next.map((row, index) => [upsert.key(row), index]));
+    for (const row of upsert.rows) {
+        const key = upsert.key(row);
+        const position = positions.get(key) ?? next.length;
+        positions.set(key, position);
+        next[position] = row;
+    }
+    return next.sort(upsert.order);
+}
+function definitions(rows, added) {
+    const known = new Set(rows.map((row) => row.pin));
+    const fresh = added.filter((row) => {
+        if (known.has(row.pin))
+            return false;
+        known.add(row.pin);
+        return true;
+    });
+    return upserted(rows, {
+        rows: fresh,
+        key: (row) => row.pin,
+        order: (left, right) => binaryOrder(left.pin, right.pin),
+    });
+}
+function runs(rows, change) {
+    return upserted(rows, {
+        rows: change,
+        key: (row) => row.runId,
+        order: (left, right) => binaryOrder(left.runId, right.runId),
+    });
+}
+function commands(rows, added) {
+    if (added.length === 0)
+        return rows;
+    return [...rows, ...added].sort((left, right) => left.sequence - right.sequence);
+}
+function appendGuarded(table, entry) {
+    const key = table.key(entry.row);
+    if (entry.open)
+        table.open.set(key, [...(table.open.get(key) ?? []), table.rows.length]);
+    table.rows.push(entry.row);
+}
+function guarded(rows, fields) {
+    const table = { rows: [], open: new Map(), key: fields.key };
+    for (const row of rows)
+        appendGuarded(table, { row, open: fields.open(row) });
+    return table;
+}
+function settleGuarded(table, settlement) {
+    for (const index of table.open.get(settlement.key) ?? []) {
+        const row = table.rows[index];
+        if (row === undefined)
+            continue;
+        table.rows[index] = settlement.update(row);
+    }
+    table.open.delete(settlement.key);
+}
+function outbox(rows, changes) {
+    if (changes.every((change) => change.added.length + change.released.length === 0))
+        return rows;
+    const table = guarded(rows, {
+        key: (row) => row.operationId,
+        open: (row) => row.releasedSequence === null,
+    });
+    for (const change of changes) {
+        for (const row of change.added)
+            appendGuarded(table, {
+                row: { ...row, releasedSequence: null },
+                open: true,
+            });
+        for (const { operationId, releasedSequence } of change.released)
+            settleGuarded(table, {
+                key: operationId,
+                update: (row) => ({ ...row, releasedSequence }),
+            });
+    }
+    return table.rows.sort((left, right) => left.createdSequence - right.createdSequence);
+}
+function stagedAttempt(row, sequence) {
+    return {
+        effectId: row.effectId,
+        operationId: row.operationId,
+        inputDigest: row.inputDigest,
+        stagedSequence: sequence,
+        outcome: null,
+        receipt: null,
+        purpose: row.purpose,
+        leaseGeneration: row.leaseGeneration,
+        epoch: row.authorityEpoch,
+    };
+}
+function deliveries(rows, changes) {
+    if (changes.every((change) => change.closed.length + change.staged.length === 0))
+        return rows;
+    const table = guarded(rows, {
+        key: (row) => row.effectId,
+        open: (row) => row.outcome === null,
+    });
+    for (const change of changes) {
+        for (const { effectId, outcome, receipt } of change.closed)
+            settleGuarded(table, {
+                key: effectId,
+                update: (row) => ({ ...row, outcome, receipt }),
+            });
+        for (const row of change.staged)
+            appendGuarded(table, {
+                row: stagedAttempt(row, change.sequence),
+                open: true,
+            });
+    }
+    return table.rows.sort((left, right) => left.stagedSequence - right.stagedSequence);
+}
+function gates(rows, change) {
+    return upserted(rows, {
+        rows: change,
+        key: (row) => JSON.stringify([row.runId, row.gateId]),
+        order: (left, right) => left.openedSequence - right.openedSequence ||
+            binaryOrder(left.gateId, right.gateId),
+    });
+}
+function details(rows, change) {
+    return upserted(rows, {
+        rows: change,
+        key: (row) => row.runId,
+        order: (left, right) => binaryOrder(left.runId, right.runId),
+    });
+}
+function waits(rows, change) {
+    return upserted(rows, {
+        rows: change,
+        key: (row) => JSON.stringify([row.runId, row.name]),
+        order: (left, right) => binaryOrder(left.runId, right.runId) ||
+            binaryOrder(left.name, right.name),
+    });
+}
+function pending(operations, change) {
+    if (change.length === 0)
+        return operations;
+    const next = new Set(operations);
+    for (const row of change)
+        if (row.status === "dispatch-pending")
+            next.add(row.operationId);
+        else
+            next.delete(row.operationId);
+    return [...next].sort(binaryOrder);
+}
+export function projectedChange(change) {
+    return {
+        previous: change.previous,
+        sequence: change.sequence,
+        definitions: change.definitions,
+        events: change.events.map(({ sequence, recordedAt }) => ({
+            sequence,
+            recordedAt,
+        })),
+        runs: change.runs,
+        commands: change.commands,
+        added: change.added,
+        released: change.released,
+        staged: change.staged,
+        closed: change.closed,
+        gates: change.gates,
+        details: change.details,
+        waits: change.waits,
+        operations: change.operations.map(({ operationId, status }) => ({
+            operationId,
+            status,
+        })),
+    };
+}
+export function followingSequence(sequence, change) {
+    return Math.max(sequence, ...change.events.map((event) => event.sequence));
+}
+export function changedProjection(snapshot, changes) {
+    const rows = (select) => changes.flatMap(select);
+    return {
+        definitions: definitions(snapshot.definitions, rows((change) => change.definitions)),
+        runs: runs(snapshot.runs, rows((change) => change.runs)),
+        commands: commands(snapshot.commands, rows((change) => change.commands)),
+        outbox: outbox(snapshot.outbox, changes),
+        gates: gates(snapshot.gates, rows((change) => change.gates)),
+        details: details(snapshot.details, rows((change) => change.details)),
+        waits: waits(snapshot.waits, rows((change) => change.waits)),
+        deliveries: deliveries(snapshot.deliveries, changes),
+        pending: pending(snapshot.pending, rows((change) => change.operations)),
+        sequence: changes.reduce(followingSequence, snapshot.sequence),
+    };
+}

package/dist/src/storage/projection-lookups.d.ts

@@ -0,0 +1,7 @@
+import { type SqlConnection } from "./domain-rows.ts";
+export type MessageOutcome = "committed" | "rolled-back" | "missing";
+export declare function messageOutcomes(connection: SqlConnection, messageIds: readonly string[]): Promise<ReadonlyMap<string, MessageOutcome>>;
+export declare function runTimes(connection: SqlConnection): Promise<ReadonlyMap<string, string>>;
+export declare function recordedTimes(connection: SqlConnection, sequences: readonly number[]): Promise<ReadonlyMap<number, string>>;
+export declare function submittedWorkflows(connection: SqlConnection): Promise<ReadonlyMap<string, string>>;
+export declare function storedWorkflows(connection: SqlConnection, digests: readonly string[]): Promise<ReadonlyMap<string, string | null>>;

package/dist/src/storage/projection-lookups.js

@@ -0,0 +1,30 @@
+import { integer, optionalText, text, } from "./domain-rows.js";
+const workflowColumn = "json_extract(s.body, '$.workflowId') AS workflow_id FROM documents s";
+const workflowFilter = "json_valid(s.body) AND json_type(s.body, '$.workflowId') = 'text'";
+export async function messageOutcomes(connection, messageIds) {
+    const rows = await connection.all("SELECT id, completed_at_ms IS NOT NULL AND rejection IS NULL AND error IS NULL AS committed FROM solid_messages WHERE id IN (SELECT value FROM json_each(?))", [JSON.stringify(messageIds)]);
+    return new Map(rows.map((row) => [
+        text(row, "id"),
+        integer(row, "committed") === 1 ? "committed" : "rolled-back",
+    ]));
+}
+export async function runTimes(connection) {
+    const rows = await connection.all("SELECT r.run_id, e.recorded_at FROM runs r JOIN events e ON e.sequence = r.sequence");
+    return new Map(rows.map((row) => [text(row, "run_id"), text(row, "recorded_at")]));
+}
+export async function recordedTimes(connection, sequences) {
+    if (sequences.length === 0)
+        return new Map();
+    const rows = await connection.all("SELECT sequence, recorded_at FROM events WHERE sequence IN (SELECT value FROM json_each(?))", [JSON.stringify(sequences)]);
+    return new Map(rows.map((row) => [integer(row, "sequence"), text(row, "recorded_at")]));
+}
+export async function submittedWorkflows(connection) {
+    const rows = await connection.all(`SELECT DISTINCT s.digest, ${workflowColumn} JOIN run_details d ON d.submission = s.digest WHERE ${workflowFilter}`);
+    return new Map(rows.map((row) => [text(row, "digest"), text(row, "workflow_id")]));
+}
+export async function storedWorkflows(connection, digests) {
+    if (digests.length === 0)
+        return new Map();
+    const rows = await connection.all(`SELECT s.digest, ${workflowColumn} WHERE s.digest IN (SELECT value FROM json_each(?)) AND ${workflowFilter}`, [JSON.stringify(digests)]);
+    return new Map(rows.map((row) => [text(row, "digest"), optionalText(row, "workflow_id")]));
+}

package/dist/src/testing-requests.d.ts

@@ -0,0 +1,15 @@
+import type { ProtectedRequest, GateRequest, HandoffRequest, RunWaitRequest, CommandWaitRequest } from "./step-bridge.ts";
+export type ScenarioRequest = readonly ["effect", ProtectedRequest] | readonly ["gate", GateRequest] | readonly ["waitForDecision", GateRequest] | readonly ["handoff", HandoffRequest] | readonly ["waitForRun", RunWaitRequest] | readonly ["waitForCommand", CommandWaitRequest] | readonly [
+    "sleep",
+    {
+        readonly seconds: number;
+    } | {
+        readonly until: string;
+    }
+];
+export interface ScenarioResult {
+    readonly spent?: number;
+    readonly outcome: unknown;
+    readonly requests: readonly ScenarioRequest[];
+}
+export declare function scenarioResult(value: unknown): value is ScenarioResult;

package/dist/src/testing-requests.js

@@ -0,0 +1,93 @@
+import { isInstant } from "./authority/instants.js";
+import { isCommandWaitRequest } from "./command-wait.js";
+import { record } from "./protocol.js";
+export function scenarioResult(value) {
+    const result = record(value);
+    return (result !== undefined &&
+        Object.hasOwn(result, "outcome") &&
+        Array.isArray(result["requests"]) &&
+        result["requests"].every(scenarioRequest) &&
+        (result["spent"] === undefined || typeof result["spent"] === "number"));
+}
+function scenarioRequest(value) {
+    if (!requestPair(value))
+        return false;
+    const request = record(value[1]);
+    if (request === undefined)
+        return false;
+    switch (value[0]) {
+        case "effect":
+            return protectedRequest(request);
+        case "gate":
+        case "waitForDecision":
+            return gateRequest(request);
+        case "handoff":
+            return handoffRequest(request);
+        case "waitForRun":
+            return runWaitRequest(request);
+        case "waitForCommand":
+            return isCommandWaitRequest(request);
+        case "sleep":
+            return sleepRequest(request);
+        default:
+            return false;
+    }
+}
+function requestPair(value) {
+    return Array.isArray(value) && value.length === 2;
+}
+function runWaitRequest(request) {
+    return (typeof request["runId"] === "string" &&
+        typeof request["maximumWaitSeconds"] === "number");
+}
+function sleepRequest(request) {
+    if (typeof request["until"] === "string")
+        return isInstant(request["until"]);
+    const seconds = request["seconds"];
+    return (typeof seconds === "number" &&
+        Number.isInteger(seconds) &&
+        seconds >= 1 &&
+        seconds <= 86400);
+}
+function gateRequest(request) {
+    return (typeof request["gateId"] === "string" &&
+        (request["kind"] === "question" || request["kind"] === "approval") &&
+        typeof request["prompt"] === "string" &&
+        optionalText(request["expiresAt"]));
+}
+function handoffRequest(request) {
+    const input = record(request["input"]);
+    return (typeof request["workflowId"] === "string" &&
+        input !== undefined &&
+        Object.values(input).every(handoffValue));
+}
+function protectedRequest(request) {
+    return (protectedScope(request["scope"]) &&
+        ["capability", "method", "target", "payload"].every((key) => typeof request[key] === "string") &&
+        typeof request["units"] === "number" &&
+        optionalText(request["resource"]));
+}
+function protectedScope(value) {
+    const scope = record(value);
+    if (scope === undefined)
+        return false;
+    const stage = record(scope["stage"]);
+    return (typeof scope["phase"] === "string" &&
+        typeof scope["operation"] === "string" &&
+        typeof scope["round"] === "number" &&
+        optionalText(scope["key"]) &&
+        (scope["stage"] === undefined ||
+            (stage !== undefined &&
+                ["id", "visit", "branch"].every((key) => typeof stage[key] === "string"))));
+}
+function optionalText(value) {
+    return value === undefined || typeof value === "string";
+}
+function handoffValue(value) {
+    if (value === null || ["string", "boolean", "number"].includes(typeof value))
+        return true;
+    if (Array.isArray(value))
+        return value.every(handoffValue);
+    const fields = record(value);
+    return fields !== undefined && Object.values(fields).every(handoffValue);
+}

package/dist/src/testing.d.ts

@@ -1,5 +1,7 @@
-import { type HandoffValue, type ProtectedResult, type GateResult, type DecisionResult, type RunWaitOutcome, type ProtectedRequest, type GateRequest, type HandoffRequest, type RunWaitRequest } from "./step-bridge.ts";
+import { type ScenarioRequest, type ScenarioResult } from "./testing-requests.ts";
+import { type HandoffValue, type ProtectedResult, type GateResult, type DecisionResult, type RunWaitOutcome, type CommandWaitProgress } from "./step-bridge.ts";
 export interface StepScenario {
+    readonly commandWaits?: Readonly<Record<string, readonly CommandWaitProgress[]>>;
     readonly turn?: ProtectedResult;
     readonly effects?: Readonly<Record<string, readonly ProtectedResult[]>>;
     readonly gate?: GateResult;
@@ -11,16 +13,8 @@ export interface WorkflowScenario extends StepScenario {
     readonly workflow: string;
     readonly exportName: string;
     readonly input: HandoffValue;
-    readonly decision?: HandoffValue;
-}
-export type ScenarioRequest = readonly ["effect", ProtectedRequest] | readonly ["gate", GateRequest] | readonly ["waitForDecision", GateRequest] | readonly ["handoff", HandoffRequest] | readonly ["waitForRun", RunWaitRequest] | readonly ["sleep", {
-    readonly seconds: number;
-}];
-export interface ScenarioResult {
-    readonly spent?: number;
-    readonly outcome: unknown;
-    readonly requests: readonly ScenarioRequest[];
 }
+export type { ScenarioRequest, ScenarioResult } from "./testing-requests.ts";
 export declare function fakeStepBridge(scenario: StepScenario): {
     requests: ScenarioRequest[];
     readonly spent: number;