@fungi.computer/braid 0.0.0-stage → 0.1.0

package/dist/runtime/graph-contract.js

@@ -0,0 +1,122 @@
+import { nodeGitAccessListSchema, runCeilingSchema } from "./run-ceiling.js";
+import { hostActorSchema, } from "@fungi.computer/puffball/app-method-runtime";
+import * as S from "effect/Schema";
+import { sha256DigestSchema } from "@fungi.computer/puffball/effect";
+import { resolvedGitAccessSchema, triggerRepositorySchema, } from "../git-access.js";
+import { gitSha1Schema } from "@fungi.computer/puffball/git-representation";
+import { workflowIdSchema } from "../workflow-id.js";
+import { executionPlanSchema } from "../index.js";
+const id = S.String.pipe(S.check(S.isMinLength(1)), S.check(S.isMaxLength(256)));
+const natural = S.Number.pipe(S.check(S.isInt()), S.check(S.isGreaterThanOrEqualTo(0)));
+const resolvedGitAccess = S.declare((value) => resolvedGitAccessSchema.safeParse(value).success);
+/** Provenance supplied only by the admitted published-Workflow trigger owner. */
+export const graphTriggerProvenanceSchema = S.Struct({
+    libraryInstallationId: id,
+    workflowId: S.declare((value) => workflowIdSchema.safeParse(value).success),
+    commit: S.declare((value) => gitSha1Schema.safeParse(value).success),
+    triggerId: id,
+    armedBy: id,
+    nodeGitAccess: S.optionalKey(nodeGitAccessListSchema),
+    /** The firing event's repository, resolving `$trigger.repository`. */
+    repository: S.optionalKey(S.declare((value) => triggerRepositorySchema.safeParse(value).success)),
+});
+const graphPublicationSchema = S.Struct({
+    installationId: id,
+    workflowId: graphTriggerProvenanceSchema.fields.workflowId,
+    commit: graphTriggerProvenanceSchema.fields.commit,
+    digest: S.declare((value) => S.is(sha256DigestSchema)(value)),
+    armedBy: S.declare((value) => hostActorSchema.safeParse(value).success),
+});
+/**
+ * The run's declared delivery: the Agent Session that receives its ending,
+ * whoever started it. Declared at start or arming, never by a node.
+ */
+export const workflowRunDeliverySchema = S.Struct({
+    agentId: id,
+    sessionId: id,
+});
+/** The member who started or armed the run, or the Agent Session that did. */
+export const workflowMemberInitiatorSchema = S.Struct({
+    kind: S.Literal("member"),
+    memberId: id,
+});
+/** Trusted acquisition identity, never Workflow arguments or an Agent creator. */
+export const workflowAgentInitiatorSchema = S.Struct({
+    kind: S.Literal("agent"),
+    agentId: id,
+    sessionId: id,
+    grantorMemberId: id,
+});
+/** A key never becomes a principal of its own; the run always acts as its grantor. */
+export const workflowKeyInitiatorSchema = S.Struct({
+    kind: S.Literal("key"),
+    keyId: id,
+    grantorMemberId: id,
+});
+export const workflowRunInitiatorSchema = S.Union([
+    workflowMemberInitiatorSchema,
+    workflowAgentInitiatorSchema,
+    workflowKeyInitiatorSchema,
+]);
+/** The Agent Session stays host-side; a listing names only the Agent/key and its grantor. */
+export function wireRunInitiator(initiatedBy) {
+    if (initiatedBy.kind === "member")
+        return initiatedBy;
+    if (initiatedBy.kind === "agent")
+        return {
+            kind: "agent",
+            agentId: initiatedBy.agentId,
+            grantorMemberId: initiatedBy.grantorMemberId,
+        };
+    return {
+        kind: "key",
+        keyId: initiatedBy.keyId,
+        grantorMemberId: initiatedBy.grantorMemberId,
+    };
+}
+export const workflowRunSourceValues = [
+    "manual",
+    "schedule",
+    "event",
+    "agent",
+    "key",
+];
+export const workflowRunSourceSchema = S.Literals(workflowRunSourceValues);
+export const graphRunSchema = S.Struct({
+    teamId: id,
+    runId: id,
+    requestId: id,
+    actorId: id,
+    /** Host-bound library for raw as well as published App starts; never guest input. */
+    libraryInstallationId: S.optionalKey(id),
+    /** The Computer the starting member pinned; `computer.*` work runs only there. */
+    computerId: S.NullOr(id),
+    plan: executionPlanSchema,
+    input: S.JsonObject,
+    ceiling: runCeilingSchema,
+    trigger: S.optionalKey(graphTriggerProvenanceSchema),
+    publication: S.optionalKey(graphPublicationSchema),
+    delivery: S.optionalKey(workflowRunDeliverySchema),
+    /** Recorded once, from the admitted preparation; never recomputed later. */
+    source: workflowRunSourceSchema,
+    initiatedBy: workflowRunInitiatorSchema,
+});
+/** Host-owned identity of one App node execution within a graph run. */
+export const graphNodeContextSchema = S.Struct({
+    runId: id,
+    graphId: S.optionalKey(id),
+    nodeId: id,
+    iteration: id,
+    /** Pending-call poll identity, separate from retries of the same poll. */
+    poll: S.optionalKey(natural),
+    /** Opaque engine retry identity, never parsed as authority. */
+    idempotencyKey: S.String,
+    trigger: S.optionalKey(graphTriggerProvenanceSchema),
+    gitAccess: S.optionalKey(resolvedGitAccess),
+});
+/** Publication attribution from an admitted publisher App or trigger owner. */
+export const workflowRunContextSchema = S.Struct({
+    ...graphNodeContextSchema.fields,
+    workflowId: graphPublicationSchema.fields.workflowId,
+    armedBy: graphPublicationSchema.fields.armedBy,
+});

package/dist/runtime/graph-dispatch.d.ts

@@ -0,0 +1,31 @@
+import type { WorkflowAppCall } from "./ports.js";
+import type { GraphRun } from "./graph-contract.js";
+import type { NodeCall, Node, Catalog } from "../index.js";
+import type { RunCeiling } from "./run-ceiling.js";
+import { type GraphNodeContext, type WorkflowRunContext } from "./graph-contract.js";
+/**
+ * Resolve an engine node call against the run's own frozen plan. The engine's
+ * claims (installation, method) are accepted only when the plan bound exactly
+ * that pair, and the App id and method digest come from the plan, never from
+ * the call; the Computer is the one the run pinned at start. Null means the
+ * call names something the plan never allowed.
+ */
+/** Canonical installed identity and context of a stored App node, without method input. */
+export type StoredWorkflowNode = Omit<WorkflowAppCall, "input"> & (GraphNodeContext | WorkflowRunContext);
+/** Identity comes only from the frozen compiled plan, never the engine's claimed digest. */
+export type WorkflowNodeTarget = Pick<WorkflowAppCall, "installationId" | "appId" | "method" | "methodDigest" | "computerId">;
+export type WorkflowNodeCeiling = Pick<RunCeiling["nodes"][number], "level" | "capabilities" | "bindings">;
+export type ResolvedWorkflowNodeTarget = Readonly<{
+    node: Extract<Node, {
+        kind: "app";
+    }>;
+    method: Catalog[string]["methods"][string];
+    target: WorkflowNodeTarget;
+}>;
+/** Capture and execution share the same immutable node/installation/method match. */
+export declare function resolveWorkflowNodeTarget(run: Pick<GraphRun, "plan" | "computerId">, call: Pick<NodeCall, "graphId" | "nodeId" | "installationId" | "method">): ResolvedWorkflowNodeTarget | null;
+/** A captured node must cover every required capability and the method's effect. */
+export declare function workflowNodeWithinCeiling(method: Pick<Catalog[string]["methods"][string], "requires" | "effect">, ceiling: WorkflowNodeCeiling): boolean;
+export declare function resolveWorkflowNode(run: Pick<GraphRun, "plan" | "computerId" | "runId" | "trigger" | "publication" | "ceiling">, call: Pick<NodeCall, "graphId" | "nodeId" | "iteration" | "poll" | "idempotencyKey" | "installationId" | "method">): StoredWorkflowNode | null;
+/** Resolve the stored node once, then project its admitted scope into method input. */
+export declare function planNodeCall(run: Pick<GraphRun, "plan" | "computerId" | "runId" | "trigger" | "publication" | "ceiling">, call: NodeCall): WorkflowAppCall | null;

package/dist/runtime/graph-dispatch.js

@@ -0,0 +1,111 @@
+import { appCapabilityIdSchema } from "@fungi.computer/puffball/app";
+import { resolveGitAccess, resolvedGitAccessEqual } from "../git-access.js";
+import { workflowRunContextSchema, graphNodeContextSchema, } from "./graph-contract.js";
+import * as S from "effect/Schema";
+import * as Option from "effect/Option";
+/** Capture and execution share the same immutable node/installation/method match. */
+export function resolveWorkflowNodeTarget(run, call) {
+    const { plan } = run;
+    const graph = call.graphId === undefined
+        ? plan.definition
+        : plan.definition.subgraphs?.[call.graphId];
+    const node = graph?.nodes.find((candidate) => {
+        if (candidate.kind !== "app" ||
+            candidate.id !== call.nodeId ||
+            candidate.method !== call.method)
+            return false;
+        const binding = plan.bindings[candidate.app];
+        return (binding !== undefined &&
+            "installationId" in binding &&
+            binding.installationId === call.installationId);
+    });
+    if (node?.kind !== "app")
+        return null;
+    const required = plan.requiredBindings.find((binding) => binding.app === node.app &&
+        binding.installationId === call.installationId &&
+        binding.method === call.method);
+    if (required === undefined)
+        return null;
+    const app = plan.definition.apps[required.app];
+    const method = app === undefined
+        ? undefined
+        : plan.catalog[app.appId]?.methods[call.method];
+    if (app === undefined || method === undefined)
+        return null;
+    return {
+        node,
+        method,
+        target: {
+            installationId: call.installationId,
+            appId: app.appId,
+            method: call.method,
+            methodDigest: method.digest,
+            computerId: run.computerId,
+        },
+    };
+}
+/** A captured node must cover every required capability and the method's effect. */
+export function workflowNodeWithinCeiling(method, ceiling) {
+    const requires = S.decodeUnknownOption(S.Array(appCapabilityIdSchema))(method.requires);
+    return (Option.isSome(requires) &&
+        requires.value.every((capability) => ceiling.capabilities.includes(capability)) &&
+        (method.effect === "read" || ceiling.level === "write"));
+}
+export function resolveWorkflowNode(run, call) {
+    const resolved = resolveWorkflowNodeTarget(run, call);
+    if (resolved === null)
+        return null;
+    const { node, method, target } = resolved;
+    const { plan } = run;
+    const ceiling = run.ceiling.nodes.find((candidate) => candidate.graphId === call.graphId && candidate.nodeId === node.id);
+    if (ceiling === undefined || !workflowNodeWithinCeiling(method, ceiling))
+        return null;
+    let context = {
+        runId: run.runId,
+        nodeId: call.nodeId,
+        iteration: call.iteration,
+        idempotencyKey: call.idempotencyKey,
+    };
+    if (run.publication !== undefined)
+        context = {
+            ...context,
+            workflowId: run.publication.workflowId,
+            armedBy: run.publication.armedBy,
+        };
+    if (run.trigger !== undefined)
+        context = { ...context, trigger: run.trigger };
+    if (call.graphId !== undefined)
+        context = { ...context, graphId: call.graphId };
+    if (call.poll !== undefined)
+        context = { ...context, poll: call.poll };
+    if (node.gitAccess !== undefined) {
+        const scope = run.ceiling.nodeGitAccess.find((candidate) => candidate.graphId === call.graphId && candidate.nodeId === node.id);
+        const expected = resolveGitAccess(plan.bindings, node.gitAccess, run.trigger?.repository);
+        if (scope === undefined ||
+            expected === null ||
+            !resolvedGitAccessEqual(scope.gitAccess, expected))
+            return null;
+        context = { ...context, gitAccess: scope.gitAccess };
+    }
+    return {
+        ...("workflowId" in context
+            ? S.decodeUnknownSync(workflowRunContextSchema)(context)
+            : S.decodeUnknownSync(graphNodeContextSchema)(context)),
+        ...target,
+        bindingCeiling: ceiling.bindings,
+    };
+}
+/** Resolve the stored node once, then project its admitted scope into method input. */
+export function planNodeCall(run, call) {
+    const resolved = resolveWorkflowNode(run, call);
+    if (resolved === null)
+        return null;
+    let input = call.input;
+    if (resolved.gitAccess !== undefined) {
+        const object = S.decodeUnknownOption(S.JsonObject)(input);
+        if (Option.isNone(object))
+            return null;
+        input = { ...object.value, gitAccess: resolved.gitAccess };
+    }
+    return { ...resolved, input };
+}

package/dist/runtime/graph-run-store.d.ts

@@ -0,0 +1,79 @@
+import * as S from "effect/Schema";
+import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
+import { type GraphRun } from "./graph-contract.js";
+import { reviewAnswerSchema, type NodeEvent, type GraphReview } from "../index.js";
+declare const deliverySchema: S.Struct<{
+    readonly runId: S.String;
+    readonly nodeId: S.String;
+    readonly iteration: S.String;
+    readonly instanceId: S.String;
+    readonly eventType: S.String;
+    readonly answer: S.Union<readonly [S.Struct<{
+        readonly approved: S.Boolean;
+    }>, S.Struct<{
+        readonly choice: S.String;
+        readonly note: S.optionalKey<S.String>;
+    }>]>;
+}>;
+export type ReviewDelivery = typeof deliverySchema.Type;
+export type GraphReviewer = {
+    readonly kind: "member" | "agent";
+    readonly actorId: string;
+    readonly isOwner: boolean;
+};
+/** The durable state of every Workflow run: runs, node events, reviews and outcomes. */
+export declare function createGraphWorkflowRuns(options: {
+    sql: WatchdogSqliteOwner["sql"];
+    transactionSync: <T>(body: () => T) => T;
+}): {
+    read: (runId: string) => GraphRun | null;
+    /**
+     * Up to 50 runs for one installation, newest first; a viewer narrows
+     * further to their own. `started_at` is the host clock at insert, kept
+     * out of the record so a replay still compares equal.
+     */
+    list(filter: {
+        installationId: string;
+        actorId?: string;
+        workflowId?: string;
+    }): readonly (GraphRun & {
+        startedAt: number;
+    })[];
+    /** Runs with no recorded outcome, oldest first. */
+    active(): readonly GraphRun[];
+    outcome(runId: string): "active" | "terminal" | "cancelled" | null;
+    markTerminal(runId: string, outcome?: "terminal" | "cancelled"): void;
+    startCompiled: (input: GraphRun) => "started" | "replay" | "conflict";
+    start(input: GraphRun): Promise<"started" | "replay" | "conflict">;
+    recordEvent(input: NodeEvent): void;
+    events(runId: string): readonly NodeEvent[];
+    openReview(input: GraphReview): number;
+    reviews(runId: string): {
+        review: {
+            readonly show: readonly S.Json[];
+            readonly title: string;
+            readonly timeout: number;
+            readonly runId: string;
+            readonly nodeId: string;
+            readonly reviewers: "runner" | "owners";
+            readonly iteration: string;
+            readonly instanceId: string;
+            readonly eventType: string;
+            readonly position?: readonly {
+                readonly node: string;
+                readonly loop: "repeat" | "map";
+                readonly index: number;
+                readonly count: number;
+            }[];
+            readonly choices?: readonly string[];
+        };
+        status: "closed" | "pending" | "answered" | "delivered" | "timed_out";
+        openedAt: number;
+        expiresAt: number;
+    }[];
+    answerReview(key: Pick<GraphReview, "runId" | "nodeId" | "iteration">, answer: typeof reviewAnswerSchema.Type, reviewer: GraphReviewer): "accepted" | "denied" | "not_waiting" | "invalid";
+    /** Durable pending delivery survives a sender restart; native event sends may be repeated. */
+    pendingReviewDeliveries(runId: string): readonly ReviewDelivery[];
+    markReviewDelivered(delivery: ReviewDelivery): void;
+};
+export {};

package/dist/runtime/graph-run-store.js

@@ -0,0 +1,267 @@
+import * as S from "effect/Schema";
+import { admitRunInput, decodeExecutionPlan, canonicalJson } from "../index.js";
+import { graphRunSchema } from "./graph-contract.js";
+import { nodeEventSchema, graphReviewSchema, reviewAnswerSchema, } from "../index.js";
+const rowSchema = S.Struct({ record: S.String });
+const deliverySchema = S.Struct({
+    runId: S.String,
+    nodeId: S.String,
+    iteration: S.String,
+    instanceId: S.String,
+    eventType: S.String,
+    answer: reviewAnswerSchema,
+});
+/** The durable state of every Workflow run: runs, node events, reviews and outcomes. */
+export function createGraphWorkflowRuns(options) {
+    const { sql } = options;
+    sql.exec(`CREATE TABLE IF NOT EXISTS hub_graph_runs (run_id TEXT PRIMARY KEY,request_id TEXT NOT NULL UNIQUE,installation_id TEXT,workflow_id TEXT,actor_id TEXT NOT NULL,started_at INTEGER NOT NULL,record TEXT NOT NULL) STRICT`);
+    sql.exec(`CREATE INDEX IF NOT EXISTS hub_graph_runs_listing ON hub_graph_runs(installation_id, actor_id, started_at DESC, run_id DESC)`);
+    sql.exec(`CREATE TABLE IF NOT EXISTS hub_graph_terminal_runs (run_id TEXT PRIMARY KEY REFERENCES hub_graph_runs(run_id), outcome TEXT NOT NULL CHECK(outcome IN ('terminal','cancelled'))) STRICT`);
+    // The decoder forbids empty named graph ids; the empty SQL key names only the root.
+    sql.exec(`CREATE TABLE IF NOT EXISTS hub_graph_node_events (run_id TEXT NOT NULL,graph_id TEXT NOT NULL,node_id TEXT NOT NULL,iteration TEXT NOT NULL,poll INTEGER NOT NULL,state TEXT NOT NULL,attempt INTEGER NOT NULL,record TEXT NOT NULL,PRIMARY KEY(run_id,graph_id,node_id,iteration,poll,state,attempt)) STRICT`);
+    sql.exec(`CREATE TABLE IF NOT EXISTS workflow_graph_reviews (run_id TEXT NOT NULL,node_id TEXT NOT NULL,iteration TEXT NOT NULL,status TEXT NOT NULL CHECK(status IN ('pending','answered','delivered','timed_out','closed')),record TEXT NOT NULL,delivery TEXT,opened_at INTEGER NOT NULL,expires_at INTEGER NOT NULL,PRIMARY KEY(run_id,node_id,iteration)) STRICT`);
+    const read = (runId) => {
+        const row = sql
+            .exec("SELECT record FROM hub_graph_runs WHERE run_id=?", runId)
+            .toArray()[0];
+        return row === undefined
+            ? null
+            : S.decodeUnknownSync(graphRunSchema)(JSON.parse(S.decodeUnknownSync(rowSchema)(row).record));
+    };
+    const requireRun = (runId) => {
+        const run = read(runId);
+        if (!run)
+            throw new Error("Unknown graph run");
+        return run;
+    };
+    const requireActive = (runId) => {
+        const run = read(runId);
+        if (run === null ||
+            sql
+                .exec("SELECT run_id FROM hub_graph_terminal_runs WHERE run_id=?", runId)
+                .toArray().length !== 0)
+            throw new Error("Workflow run is not active");
+        return run;
+    };
+    /** Only the Team run owner supplies already compiled, stored plans here. */
+    const startCompiled = (input) => {
+        const decoded = S.decodeUnknownSync(graphRunSchema)(input, {
+            onExcessProperty: "error",
+        });
+        const admitted = admitRunInput(decoded.plan.definition, decoded.input);
+        if (admitted.kind === "invalid")
+            throw new Error("Invalid graph run input");
+        const run = { ...decoded, input: admitted.input };
+        return options.transactionSync(() => {
+            const row = sql
+                .exec("SELECT record FROM hub_graph_runs WHERE request_id=? OR run_id=?", run.requestId, run.runId)
+                .toArray()[0];
+            if (row !== undefined) {
+                const prior = S.decodeUnknownSync(graphRunSchema)(JSON.parse(S.decodeUnknownSync(rowSchema)(row).record));
+                return canonicalJson(prior) === canonicalJson(run)
+                    ? "replay"
+                    : "conflict";
+            }
+            sql.exec("INSERT INTO hub_graph_runs(run_id,request_id,installation_id,workflow_id,actor_id,started_at,record) VALUES(?,?,?,?,?,?,?)", run.runId, run.requestId, run.publication?.installationId ??
+                run.libraryInstallationId ??
+                run.trigger?.libraryInstallationId ??
+                null, run.publication?.workflowId ?? run.trigger?.workflowId ?? null, run.actorId, Date.now(), JSON.stringify(run));
+            return "started";
+        });
+    };
+    return {
+        read,
+        /**
+         * Up to 50 runs for one installation, newest first; a viewer narrows
+         * further to their own. `started_at` is the host clock at insert, kept
+         * out of the record so a replay still compares equal.
+         */
+        list(filter) {
+            const conditions = ["installation_id=?"];
+            const params = [filter.installationId];
+            if (filter.actorId !== undefined) {
+                conditions.push("actor_id=?");
+                params.push(filter.actorId);
+            }
+            if (filter.workflowId !== undefined) {
+                conditions.push("workflow_id=?");
+                params.push(filter.workflowId);
+            }
+            return sql
+                .exec(`SELECT record,started_at FROM hub_graph_runs WHERE ${conditions.join(" AND ")} ORDER BY started_at DESC, run_id DESC LIMIT 50`, ...params)
+                .toArray()
+                .map((row) => {
+                const parsed = S.decodeUnknownSync(S.Struct({ record: S.String, started_at: S.Number }))(row);
+                return {
+                    ...S.decodeUnknownSync(graphRunSchema)(JSON.parse(parsed.record)),
+                    startedAt: parsed.started_at,
+                };
+            });
+        },
+        /** Runs with no recorded outcome, oldest first. */
+        active() {
+            return sql
+                .exec("SELECT record FROM hub_graph_runs WHERE run_id NOT IN (SELECT run_id FROM hub_graph_terminal_runs) ORDER BY rowid")
+                .toArray()
+                .map((row) => S.decodeUnknownSync(graphRunSchema)(JSON.parse(S.decodeUnknownSync(rowSchema)(row).record)));
+        },
+        outcome(runId) {
+            if (read(runId) === null)
+                return null;
+            const row = sql
+                .exec("SELECT outcome FROM hub_graph_terminal_runs WHERE run_id=?", runId)
+                .toArray()[0];
+            return row === undefined
+                ? "active"
+                : S.decodeUnknownSync(S.Struct({ outcome: S.Literals(["terminal", "cancelled"]) }))(row).outcome;
+        },
+        markTerminal(runId, outcome = "terminal") {
+            requireRun(runId);
+            options.transactionSync(() => {
+                sql.exec("INSERT OR IGNORE INTO hub_graph_terminal_runs(run_id,outcome) VALUES(?,?)", runId, outcome);
+                sql.exec("UPDATE workflow_graph_reviews SET status='closed',delivery=NULL WHERE run_id=? AND status IN ('pending','answered')", runId);
+            });
+        },
+        startCompiled,
+        async start(input) {
+            const run = S.decodeUnknownSync(graphRunSchema)(input, {
+                onExcessProperty: "error",
+            });
+            await decodeExecutionPlan(run.plan);
+            return startCompiled(run);
+        },
+        recordEvent(input) {
+            const event = S.decodeUnknownSync(nodeEventSchema)(input, {
+                onExcessProperty: "error",
+            });
+            requireActive(event.runId);
+            options.transactionSync(() => {
+                const prior = sql
+                    .exec("SELECT record FROM hub_graph_node_events WHERE run_id=? AND graph_id=? AND node_id=? AND iteration=? AND poll=? AND state=? AND attempt=?", event.runId, event.graphId ?? "", event.nodeId, event.iteration, event.poll ?? -1, event.state, event.attempt)
+                    .toArray()[0];
+                if (prior !== undefined)
+                    return;
+                const count = S.decodeUnknownSync(S.Struct({ count: S.Number }))(sql
+                    .exec("SELECT count(*) AS count FROM hub_graph_node_events WHERE run_id=?", event.runId)
+                    .toArray()[0]).count;
+                if (count >= 4096)
+                    throw new Error("Graph event bound exceeded");
+                sql.exec("INSERT OR IGNORE INTO hub_graph_node_events(run_id,graph_id,node_id,iteration,poll,state,attempt,record) VALUES(?,?,?,?,?,?,?,?)", event.runId, event.graphId ?? "", event.nodeId, event.iteration, event.poll ?? -1, event.state, event.attempt, JSON.stringify({ ...event, recordedAt: Date.now() }));
+                if (event.state === "failed" && event.refusal === "review_timeout")
+                    sql.exec("UPDATE workflow_graph_reviews SET status='timed_out' WHERE run_id=? AND node_id=? AND iteration=? AND status IN ('pending','answered')", event.runId, event.nodeId, event.iteration);
+            });
+        },
+        events(runId) {
+            requireRun(runId);
+            return sql
+                .exec("SELECT record FROM hub_graph_node_events WHERE run_id=? ORDER BY rowid", runId)
+                .toArray()
+                .map((row) => S.decodeUnknownSync(nodeEventSchema)(JSON.parse(S.decodeUnknownSync(rowSchema)(row).record)));
+        },
+        openReview(input) {
+            const review = S.decodeUnknownSync(graphReviewSchema)(input, {
+                onExcessProperty: "error",
+            });
+            requireActive(review.runId);
+            return options.transactionSync(() => {
+                const row = sql
+                    .exec("SELECT record,expires_at FROM workflow_graph_reviews WHERE run_id=? AND node_id=? AND iteration=?", review.runId, review.nodeId, review.iteration)
+                    .toArray()[0];
+                if (row !== undefined) {
+                    const stored = S.decodeUnknownSync(S.Struct({ record: S.String, expires_at: S.Number }))(row);
+                    if (stored.record !== JSON.stringify(review))
+                        throw new Error("Conflicting graph review");
+                    return stored.expires_at;
+                }
+                const openedAt = Date.now();
+                const expiresAt = openedAt + review.timeout;
+                sql.exec("INSERT INTO workflow_graph_reviews(run_id,node_id,iteration,status,record,opened_at,expires_at) VALUES(?,?,?,'pending',?,?,?)", review.runId, review.nodeId, review.iteration, JSON.stringify(review), openedAt, expiresAt);
+                return expiresAt;
+            });
+        },
+        reviews(runId) {
+            requireRun(runId);
+            return sql
+                .exec("SELECT record,status,opened_at,expires_at FROM workflow_graph_reviews WHERE run_id=? ORDER BY rowid", runId)
+                .toArray()
+                .map((row) => {
+                const parsed = S.decodeUnknownSync(S.Struct({
+                    record: S.String,
+                    status: S.Literals([
+                        "pending",
+                        "answered",
+                        "delivered",
+                        "timed_out",
+                        "closed",
+                    ]),
+                    opened_at: S.Number,
+                    expires_at: S.Number,
+                }))(row);
+                return {
+                    review: S.decodeUnknownSync(graphReviewSchema)(JSON.parse(parsed.record)),
+                    status: parsed.status,
+                    openedAt: parsed.opened_at,
+                    expiresAt: parsed.expires_at,
+                };
+            });
+        },
+        answerReview(key, answer, reviewer) {
+            const run = requireRun(key.runId);
+            if (sql
+                .exec("SELECT run_id FROM hub_graph_terminal_runs WHERE run_id=?", key.runId)
+                .toArray().length !== 0)
+                return "not_waiting";
+            const checked = S.decodeUnknownSync(reviewAnswerSchema)(answer, {
+                onExcessProperty: "error",
+            });
+            return options.transactionSync(() => {
+                const row = sql
+                    .exec("SELECT record,status,expires_at FROM workflow_graph_reviews WHERE run_id=? AND node_id=? AND iteration=?", key.runId, key.nodeId, key.iteration)
+                    .toArray()[0];
+                if (row === undefined)
+                    return "not_waiting";
+                const parsed = S.decodeUnknownSync(S.Struct({
+                    record: S.String,
+                    status: S.String,
+                    expires_at: S.Number,
+                }))(row);
+                const review = S.decodeUnknownSync(graphReviewSchema)(JSON.parse(parsed.record));
+                if (reviewer.kind === "agent" ||
+                    (!reviewer.isOwner &&
+                        (review.reviewers === "owners" || reviewer.actorId !== run.actorId)))
+                    return "denied";
+                if (parsed.status !== "pending")
+                    return "not_waiting";
+                if (Date.now() >= parsed.expires_at) {
+                    sql.exec("UPDATE workflow_graph_reviews SET status='timed_out' WHERE run_id=? AND node_id=? AND iteration=? AND status='pending'", key.runId, key.nodeId, key.iteration);
+                    return "not_waiting";
+                }
+                // The answer must fit the review: a choice it offers, or approve/reject.
+                if ("choice" in checked
+                    ? !review.choices?.includes(checked.choice)
+                    : review.choices !== undefined)
+                    return "invalid";
+                const delivery = {
+                    ...key,
+                    instanceId: review.instanceId,
+                    eventType: review.eventType,
+                    answer: checked,
+                };
+                sql.exec("UPDATE workflow_graph_reviews SET status='answered',delivery=? WHERE run_id=? AND node_id=? AND iteration=? AND status='pending'", JSON.stringify(delivery), key.runId, key.nodeId, key.iteration);
+                return "accepted";
+            });
+        },
+        /** Durable pending delivery survives a sender restart; native event sends may be repeated. */
+        pendingReviewDeliveries(runId) {
+            requireRun(runId);
+            return sql
+                .exec("SELECT delivery FROM workflow_graph_reviews WHERE run_id=? AND status='answered'", runId)
+                .toArray()
+                .map((row) => S.decodeUnknownSync(deliverySchema)(JSON.parse(S.decodeUnknownSync(S.Struct({ delivery: S.String }))(row)
+                .delivery)));
+        },
+        markReviewDelivered(delivery) {
+            sql.exec("UPDATE workflow_graph_reviews SET status='delivered' WHERE run_id=? AND node_id=? AND iteration=? AND status='answered'", delivery.runId, delivery.nodeId, delivery.iteration);
+        },
+    };
+}