@osolmaz/pi-workflows 0.11.2 → 0.12.1

package/dist/controllers/sqlite.d.ts

@@ -1,5 +1,6 @@
 import { type ControllerStore, type EffectReservation, type QueueItem, type QueueRequeueOptions, type WorkflowRecordUpdate, type WorkflowReservation } from "./store.js";
 import type { ChildWorkflowRecord, ControllerEvent, ControllerQueueClaim, ControllerResource, ControllerResourceRef, ControllerResourceStatus, EffectRecord, JsonObject } from "./types.js";
+declare const TURN_INTENT_FACTS_SCHEMA = "pi-workflows.deferred-turn-facts.v1";
 export type WorkflowRunLaunchStatus = "queued" | "starting" | "running" | "parked" | "done" | "failed" | "cancelled";
 /** A user-started workflow run tracked by the durable run queue. */
 export type WorkflowRunQueueRecord = {
@@ -34,12 +35,42 @@ export type WorkflowNotificationRecord = {
     attemptId: string;
     notificationIndex: number;
     targetSessionId: string;
-    kind: "progress" | "final" | "launch_failure";
+    kind: "progress" | "final";
     content: string;
     createdAt: string;
     deliveryClaimExpiresAt: string | null;
     deliveredAt: string | null;
 };
+export type WorkflowTurnIntentCause = "agentCancelled" | "timedOut" | "failed" | "launchFailed" | "controllerInterrupted" | "claimLost";
+export type WorkflowTurnIntentResolution = "workflowPrompt" | "presentation" | "fallback";
+export type WorkflowTurnIntentFacts = JsonObject & {
+    schema: typeof TURN_INTENT_FACTS_SCHEMA;
+    workflowName: string;
+    runId: string;
+    observedState: string;
+    cause: WorkflowTurnIntentCause;
+    nodeId: string | null;
+    attemptId: string | null;
+    reason: string | null;
+    handoff: boolean;
+};
+export type WorkflowTurnIntentRecord = {
+    intentId: string;
+    sourceEventId: string;
+    runId: string;
+    workflowRef: string;
+    targetSessionId: string;
+    cause: WorkflowTurnIntentCause;
+    nodeId: string | null;
+    attemptId: string | null;
+    fallbackFacts: WorkflowTurnIntentFacts;
+    requestedAt: string;
+    eligibleAt: string | null;
+    resolvedAt: string | null;
+    resolution: WorkflowTurnIntentResolution | null;
+    resolutionMessageId: string | null;
+    deliveryClaimExpiresAt: string | null;
+};
 /** One run lifecycle transition in the cross-session event feed. */
 export type RunEventRecord = {
     seq: number;
@@ -138,6 +169,7 @@ export declare class SqliteControllerStore implements ControllerStore {
     private configure;
     private initializeSchema;
     private assertAlphaSchemaLayout;
+    private assertNoLegacyPendingLaunchNotifications;
     private transaction;
     private resourceRow;
     private requireResource;
@@ -291,13 +323,68 @@ export declare class SqliteControllerStore implements ControllerStore {
     listRunEventsAfter(seq: number, options?: {
         limit?: number;
     }): RunEventRecord[];
+    ensureWorkflowTurnIntent(options: {
+        intentId: string;
+        sourceEventId: string;
+        runId: string;
+        workflowRef: string;
+        targetSessionId: string;
+        cause: WorkflowTurnIntentCause;
+        nodeId?: string | null;
+        attemptId?: string | null;
+        fallbackFacts: WorkflowTurnIntentFacts;
+        eligible?: boolean;
+        now?: string;
+    }): WorkflowTurnIntentRecord;
+    getWorkflowTurnIntent(intentId: string): WorkflowTurnIntentRecord | undefined;
+    findPendingWorkflowTurnIntent(options: {
+        runId: string;
+        targetSessionId: string;
+    }): WorkflowTurnIntentRecord | undefined;
+    claimWorkflowTurnIntent(options: {
+        intentId: string;
+        targetSessionId: string;
+        claimToken: string;
+        leaseMs: number;
+        now?: string;
+    }): WorkflowTurnIntentRecord | undefined;
+    claimEligibleWorkflowTurnIntents(options: {
+        targetSessionId: string;
+        claimToken: string;
+        leaseMs: number;
+        limit?: number;
+        now?: string;
+    }): WorkflowTurnIntentRecord[];
+    makeWorkflowTurnIntentEligible(options: {
+        intentId: string;
+        fallbackFacts: WorkflowTurnIntentFacts;
+        now?: string;
+    }): boolean;
+    resolveWorkflowTurnIntent(options: {
+        intentId: string;
+        targetSessionId: string;
+        claimToken: string;
+        resolution: WorkflowTurnIntentResolution;
+        messageId: string;
+        now?: string;
+    }): boolean;
+    releaseWorkflowTurnIntentClaim(options: {
+        intentId: string;
+        targetSessionId: string;
+        claimToken: string;
+    }): boolean;
+    listWorkflowTurnIntents(options?: {
+        targetSessionId?: string;
+        runId?: string;
+        limit?: number;
+    }): WorkflowTurnIntentRecord[];
     enqueueWorkflowNotification(options: {
         runId: string;
         nodeId: string;
         attemptId: string;
         notificationIndex: number;
         targetSessionId: string;
-        kind: "progress" | "final" | "launch_failure";
+        kind: "progress" | "final";
         content: string;
         notificationId?: string;
         now?: string;
@@ -319,3 +406,4 @@ export declare class SqliteControllerStore implements ControllerStore {
     private requireWorkflowRun;
     private requireEvent;
 }
+export {};

package/dist/controllers/sqlite.js

@@ -9,6 +9,7 @@ const MAX_KEY_LENGTH = 512;
 const MAX_ERROR_LENGTH = 8_192;
 const MAX_EVENT_BYTES = 64 * 1024;
 const MAX_RESOURCE_VALUE_BYTES = 1024 * 1024;
+const TURN_INTENT_FACTS_SCHEMA = "pi-workflows.deferred-turn-facts.v1";
 export class SqliteControllerStore {
     filePath;
     database;
@@ -472,8 +473,10 @@ export class SqliteControllerStore {
             const existingQueue = this.database
                 .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'workflow_run_queue'")
                 .get();
-            if (existingQueue !== undefined)
-                this.assertAlphaSchemaLayout();
+            if (existingQueue !== undefined) {
+                this.assertAlphaSchemaLayout(false);
+                this.assertNoLegacyPendingLaunchNotifications();
+            }
             this.transaction(() => {
                 this.database
                     .prepare("INSERT OR IGNORE INTO schema_info (singleton, schema_id) VALUES (1, ?)")
@@ -481,9 +484,10 @@ export class SqliteControllerStore {
                 this.database.exec(SCHEMA_SQL);
             });
         }
-        this.assertAlphaSchemaLayout();
+        this.assertAlphaSchemaLayout(true);
+        this.assertNoLegacyPendingLaunchNotifications();
     }
-    assertAlphaSchemaLayout() {
+    assertAlphaSchemaLayout(requireTurnIntents) {
         const requiredQueueColumns = new Set([
             "run_id",
             "workflow_ref",
@@ -511,6 +515,46 @@ export class SqliteControllerStore {
         if (missing.length > 0) {
             throw new Error("Controller store uses an incompatible alpha layout. Preserve needed run bundles, then reset the project controller store.");
         }
+        if (!requireTurnIntents)
+            return;
+        const requiredIntentColumns = new Set([
+            "intent_id",
+            "source_event_id",
+            "run_id",
+            "workflow_ref",
+            "target_session_id",
+            "cause",
+            "node_id",
+            "attempt_id",
+            "fallback_facts_json",
+            "requested_at",
+            "eligible_at",
+            "resolved_at",
+            "resolution",
+            "resolution_message_id",
+            "delivery_claim_token",
+            "delivery_claim_expires_at",
+        ]);
+        const intentColumns = new Set(this.database.pragma("table_info(workflow_turn_intents)").map((column) => column.name));
+        const missingIntentColumns = [...requiredIntentColumns].filter((column) => !intentColumns.has(column));
+        if (missingIntentColumns.length > 0) {
+            throw new Error("Controller store uses an incompatible alpha turn-intent layout. Preserve needed run bundles, then reset the project controller store.");
+        }
+    }
+    assertNoLegacyPendingLaunchNotifications() {
+        const notificationTable = this.database
+            .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'workflow_notifications'")
+            .get();
+        if (notificationTable === undefined) {
+            throw new Error("Controller store uses an incompatible alpha notification layout. Preserve needed run bundles, then reset the project controller store.");
+        }
+        const legacy = this.database
+            .prepare(`SELECT 1 FROM workflow_notifications
+         WHERE kind = 'launch_failure' AND delivered_at IS NULL LIMIT 1`)
+            .get();
+        if (legacy !== undefined) {
+            throw new Error("Controller store contains pending alpha launch-failure notifications. Preserve needed run bundles, then reset the project controller store.");
+        }
     }
     transaction(task) {
         this.database.exec("BEGIN IMMEDIATE");
@@ -943,6 +987,179 @@ export class SqliteControllerStore {
             payload: parseStoredJson(row.payload_json, "run event payload"),
         }));
     }
+    ensureWorkflowTurnIntent(options) {
+        validateKey(options.intentId, "workflow turn intent id");
+        validateKey(options.sourceEventId, "workflow turn source event id");
+        validateRunId(options.runId);
+        validateKey(options.workflowRef, "workflow turn workflow ref");
+        validateKey(options.targetSessionId, "workflow turn target session id");
+        validateWorkflowTurnIntentCause(options.cause);
+        const nodeId = options.nodeId ?? null;
+        const attemptId = options.attemptId ?? null;
+        if (nodeId !== null)
+            validateKey(nodeId, "workflow turn node id");
+        if (attemptId !== null)
+            validateKey(attemptId, "workflow turn attempt id");
+        const factsJson = workflowTurnIntentFactsJson(options.fallbackFacts);
+        const now = validTimestamp(options.now);
+        const eligibleAt = options.eligible === true ? now : null;
+        this.database
+            .prepare(`INSERT INTO workflow_turn_intents (
+          intent_id, source_event_id, run_id, workflow_ref, target_session_id,
+          cause, node_id, attempt_id, fallback_facts_json, requested_at, eligible_at,
+          resolved_at, resolution, resolution_message_id,
+          delivery_claim_token, delivery_claim_expires_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, NULL)
+        ON CONFLICT(intent_id) DO NOTHING`)
+            .run(options.intentId, options.sourceEventId, options.runId, options.workflowRef, options.targetSessionId, options.cause, nodeId, attemptId, factsJson, now, eligibleAt);
+        const existing = this.getWorkflowTurnIntent(options.intentId);
+        if (existing === undefined) {
+            throw new Error(`Workflow turn intent was not stored: ${options.intentId}`);
+        }
+        if (existing.sourceEventId !== options.sourceEventId ||
+            existing.runId !== options.runId ||
+            existing.workflowRef !== options.workflowRef ||
+            existing.targetSessionId !== options.targetSessionId ||
+            existing.cause !== options.cause ||
+            existing.nodeId !== nodeId ||
+            existing.attemptId !== attemptId) {
+            throw new Error(`Workflow turn intent identity conflict: ${options.intentId}`);
+        }
+        return existing;
+    }
+    getWorkflowTurnIntent(intentId) {
+        validateKey(intentId, "workflow turn intent id");
+        const row = this.database
+            .prepare("SELECT * FROM workflow_turn_intents WHERE intent_id = ?")
+            .get(intentId);
+        return row === undefined ? undefined : workflowTurnIntentFromRow(row);
+    }
+    findPendingWorkflowTurnIntent(options) {
+        validateRunId(options.runId);
+        validateKey(options.targetSessionId, "workflow turn target session id");
+        const row = this.database
+            .prepare(`SELECT * FROM workflow_turn_intents
+         WHERE run_id = ? AND target_session_id = ? AND resolved_at IS NULL
+         ORDER BY requested_at DESC, intent_id DESC LIMIT 1`)
+            .get(options.runId, options.targetSessionId);
+        return row === undefined ? undefined : workflowTurnIntentFromRow(row);
+    }
+    claimWorkflowTurnIntent(options) {
+        validateKey(options.intentId, "workflow turn intent id");
+        validateKey(options.targetSessionId, "workflow turn target session id");
+        validateKey(options.claimToken, "workflow turn claim token");
+        validateDuration(options.leaseMs, "leaseMs");
+        const nowMs = epoch(validTimestamp(options.now));
+        const result = this.database
+            .prepare(`UPDATE workflow_turn_intents
+         SET delivery_claim_token = ?, delivery_claim_expires_at = ?
+         WHERE intent_id = ? AND target_session_id = ? AND resolved_at IS NULL
+           AND (delivery_claim_expires_at IS NULL OR delivery_claim_expires_at <= ?)`)
+            .run(options.claimToken, nowMs + options.leaseMs, options.intentId, options.targetSessionId, nowMs);
+        if (result.changes !== 1)
+            return undefined;
+        const row = this.database
+            .prepare("SELECT * FROM workflow_turn_intents WHERE intent_id = ?")
+            .get(options.intentId);
+        return workflowTurnIntentFromRow(row);
+    }
+    claimEligibleWorkflowTurnIntents(options) {
+        validateKey(options.targetSessionId, "workflow turn target session id");
+        validateKey(options.claimToken, "workflow turn claim token");
+        validateDuration(options.leaseMs, "leaseMs");
+        const limit = options.limit ?? 20;
+        if (!Number.isSafeInteger(limit) || limit <= 0 || limit > 100) {
+            throw new Error("Workflow turn intent limit must be an integer from 1 through 100");
+        }
+        const now = validTimestamp(options.now);
+        const nowMs = epoch(now);
+        return this.transaction(() => {
+            const ids = this.database
+                .prepare(`SELECT intent_id FROM workflow_turn_intents
+           WHERE target_session_id = ? AND resolved_at IS NULL AND eligible_at IS NOT NULL
+             AND eligible_at <= ?
+             AND (delivery_claim_expires_at IS NULL OR delivery_claim_expires_at <= ?)
+           ORDER BY eligible_at, intent_id LIMIT ?`)
+                .all(options.targetSessionId, now, nowMs, limit);
+            if (ids.length === 0)
+                return [];
+            const placeholders = ids.map(() => "?").join(", ");
+            this.database
+                .prepare(`UPDATE workflow_turn_intents
+           SET delivery_claim_token = ?, delivery_claim_expires_at = ?
+           WHERE intent_id IN (${placeholders}) AND resolved_at IS NULL
+             AND (delivery_claim_expires_at IS NULL OR delivery_claim_expires_at <= ?)`)
+                .run(options.claimToken, nowMs + options.leaseMs, ...ids.map((row) => row.intent_id), nowMs);
+            const rows = this.database
+                .prepare(`SELECT * FROM workflow_turn_intents WHERE delivery_claim_token = ?
+           ORDER BY eligible_at, intent_id`)
+                .all(options.claimToken);
+            return rows.map(workflowTurnIntentFromRow);
+        });
+    }
+    makeWorkflowTurnIntentEligible(options) {
+        validateKey(options.intentId, "workflow turn intent id");
+        const result = this.database
+            .prepare(`UPDATE workflow_turn_intents
+         SET fallback_facts_json = ?, eligible_at = COALESCE(eligible_at, ?)
+         WHERE intent_id = ? AND resolved_at IS NULL`)
+            .run(workflowTurnIntentFactsJson(options.fallbackFacts), validTimestamp(options.now), options.intentId);
+        return result.changes === 1;
+    }
+    resolveWorkflowTurnIntent(options) {
+        validateKey(options.intentId, "workflow turn intent id");
+        validateKey(options.targetSessionId, "workflow turn target session id");
+        validateKey(options.claimToken, "workflow turn claim token");
+        validateWorkflowTurnIntentResolution(options.resolution);
+        validateKey(options.messageId, "workflow turn resolution message id");
+        const result = this.database
+            .prepare(`UPDATE workflow_turn_intents
+         SET resolved_at = ?, resolution = ?, resolution_message_id = ?,
+             delivery_claim_token = NULL, delivery_claim_expires_at = NULL
+         WHERE intent_id = ? AND target_session_id = ? AND resolved_at IS NULL
+           AND delivery_claim_token = ?`)
+            .run(validTimestamp(options.now), options.resolution, options.messageId, options.intentId, options.targetSessionId, options.claimToken);
+        return result.changes === 1;
+    }
+    releaseWorkflowTurnIntentClaim(options) {
+        validateKey(options.intentId, "workflow turn intent id");
+        validateKey(options.targetSessionId, "workflow turn target session id");
+        validateKey(options.claimToken, "workflow turn claim token");
+        const result = this.database
+            .prepare(`UPDATE workflow_turn_intents
+         SET delivery_claim_token = NULL, delivery_claim_expires_at = NULL
+         WHERE intent_id = ? AND target_session_id = ? AND resolved_at IS NULL
+           AND delivery_claim_token = ?`)
+            .run(options.intentId, options.targetSessionId, options.claimToken);
+        return result.changes === 1;
+    }
+    listWorkflowTurnIntents(options = {}) {
+        if (options.targetSessionId !== undefined) {
+            validateKey(options.targetSessionId, "workflow turn target session id");
+        }
+        if (options.runId !== undefined)
+            validateRunId(options.runId);
+        const limit = options.limit ?? 20;
+        if (!Number.isSafeInteger(limit) || limit <= 0 || limit > 100) {
+            throw new Error("Workflow turn intent limit must be an integer from 1 through 100");
+        }
+        const clauses = [];
+        const values = [];
+        if (options.targetSessionId !== undefined) {
+            clauses.push("target_session_id = ?");
+            values.push(options.targetSessionId);
+        }
+        if (options.runId !== undefined) {
+            clauses.push("run_id = ?");
+            values.push(options.runId);
+        }
+        const where = clauses.length === 0 ? "" : `WHERE ${clauses.join(" AND ")}`;
+        const rows = this.database
+            .prepare(`SELECT * FROM workflow_turn_intents ${where}
+         ORDER BY requested_at DESC, intent_id DESC LIMIT ?`)
+            .all(...values, limit);
+        return rows.map(workflowTurnIntentFromRow);
+    }
     enqueueWorkflowNotification(options) {
         validateRunId(options.runId);
         validateKey(options.nodeId, "workflow node id");
@@ -1121,7 +1338,7 @@ const SCHEMA_SQL = `
     attempt_id TEXT NOT NULL,
     notification_index INTEGER NOT NULL CHECK (notification_index > 0),
     target_session_id TEXT NOT NULL,
-    kind TEXT NOT NULL CHECK (kind IN ('progress', 'final', 'launch_failure')),
+    kind TEXT NOT NULL CHECK (kind IN ('progress', 'final')),
     content TEXT NOT NULL,
     created_at TEXT NOT NULL,
     delivery_claim_token TEXT,
@@ -1133,6 +1350,40 @@ const SCHEMA_SQL = `
     ON workflow_notifications(target_session_id, delivery_claim_expires_at, created_at)
     WHERE delivered_at IS NULL;
 
+  CREATE TABLE IF NOT EXISTS workflow_turn_intents (
+    intent_id TEXT PRIMARY KEY,
+    source_event_id TEXT NOT NULL,
+    run_id TEXT NOT NULL,
+    workflow_ref TEXT NOT NULL,
+    target_session_id TEXT NOT NULL,
+    cause TEXT NOT NULL CHECK (
+      cause IN ('agentCancelled', 'timedOut', 'failed', 'launchFailed',
+                'controllerInterrupted', 'claimLost')
+    ),
+    node_id TEXT,
+    attempt_id TEXT,
+    fallback_facts_json TEXT NOT NULL,
+    requested_at TEXT NOT NULL,
+    eligible_at TEXT,
+    resolved_at TEXT,
+    resolution TEXT CHECK (resolution IN ('workflowPrompt', 'presentation', 'fallback')),
+    resolution_message_id TEXT,
+    delivery_claim_token TEXT,
+    delivery_claim_expires_at INTEGER,
+    CHECK (
+      (resolved_at IS NULL AND resolution IS NULL AND resolution_message_id IS NULL) OR
+      (resolved_at IS NOT NULL AND resolution IS NOT NULL AND resolution_message_id IS NOT NULL)
+    )
+  );
+  CREATE UNIQUE INDEX IF NOT EXISTS workflow_turn_intents_one_pending_run
+    ON workflow_turn_intents(run_id, target_session_id) WHERE resolved_at IS NULL;
+  CREATE INDEX IF NOT EXISTS workflow_turn_intents_pending_run
+    ON workflow_turn_intents(run_id, target_session_id, requested_at)
+    WHERE resolved_at IS NULL;
+  CREATE INDEX IF NOT EXISTS workflow_turn_intents_eligible_session
+    ON workflow_turn_intents(target_session_id, eligible_at, intent_id)
+    WHERE resolved_at IS NULL AND eligible_at IS NOT NULL;
+
   CREATE TABLE IF NOT EXISTS effects (
     effect_key TEXT NOT NULL,
     resource_uid TEXT NOT NULL,
@@ -1219,7 +1470,48 @@ function workflowFromRow(row) {
         ...(row.error === null ? {} : { error: row.error }),
     };
 }
+function workflowTurnIntentFromRow(row) {
+    const cause = validateWorkflowTurnIntentCause(row.cause);
+    const resolution = row.resolution === null ? null : validateWorkflowTurnIntentResolution(row.resolution);
+    const fallbackFacts = parseStoredJson(row.fallback_facts_json, "workflow turn intent facts");
+    validateWorkflowTurnIntentFacts(fallbackFacts);
+    validateKey(row.intent_id, "workflow turn intent id");
+    validateKey(row.source_event_id, "workflow turn source event id");
+    validateRunId(row.run_id);
+    validateKey(row.workflow_ref, "workflow turn workflow ref");
+    validateKey(row.target_session_id, "workflow turn target session id");
+    validTimestamp(row.requested_at);
+    if (row.eligible_at !== null)
+        validTimestamp(row.eligible_at);
+    if (row.resolved_at !== null)
+        validTimestamp(row.resolved_at);
+    const allResolutionFieldsNull = row.resolved_at === null && row.resolution === null && row.resolution_message_id === null;
+    const allResolutionFieldsSet = row.resolved_at !== null && row.resolution !== null && row.resolution_message_id !== null;
+    if (!allResolutionFieldsNull && !allResolutionFieldsSet) {
+        throw new Error(`Workflow turn intent ${row.intent_id} has inconsistent resolution fields`);
+    }
+    return {
+        intentId: row.intent_id,
+        sourceEventId: row.source_event_id,
+        runId: row.run_id,
+        workflowRef: row.workflow_ref,
+        targetSessionId: row.target_session_id,
+        cause,
+        nodeId: row.node_id,
+        attemptId: row.attempt_id,
+        fallbackFacts,
+        requestedAt: row.requested_at,
+        eligibleAt: row.eligible_at,
+        resolvedAt: row.resolved_at,
+        resolution,
+        resolutionMessageId: row.resolution_message_id,
+        deliveryClaimExpiresAt: row.delivery_claim_expires_at === null ? null : iso(row.delivery_claim_expires_at),
+    };
+}
 function workflowNotificationFromRow(row) {
+    if (row.kind !== "progress" && row.kind !== "final") {
+        throw new Error("Controller store contains an incompatible pending alpha workflow notification. Preserve needed run bundles, then reset the project controller store.");
+    }
     return {
         notificationId: row.notification_id,
         runId: row.run_id,
@@ -1234,6 +1526,89 @@ function workflowNotificationFromRow(row) {
         deliveredAt: row.delivered_at,
     };
 }
+function workflowTurnIntentFactsJson(facts) {
+    validateWorkflowTurnIntentFacts(facts);
+    const json = canonicalJson(facts, "workflow turn intent facts");
+    validateJsonSize(json, "Workflow turn intent facts", MAX_EVENT_BYTES);
+    return json;
+}
+function validateWorkflowTurnIntentFacts(facts) {
+    if (facts === null || typeof facts !== "object" || Array.isArray(facts)) {
+        throw new Error("Workflow turn intent facts must be an object");
+    }
+    const candidate = facts;
+    if (candidate.schema !== TURN_INTENT_FACTS_SCHEMA) {
+        throw new Error(`Workflow turn intent facts schema must be ${TURN_INTENT_FACTS_SCHEMA}`);
+    }
+    const allowedKeys = new Set([
+        "schema",
+        "workflowName",
+        "runId",
+        "observedState",
+        "cause",
+        "nodeId",
+        "attemptId",
+        "reason",
+        "handoff",
+    ]);
+    for (const key of Object.keys(candidate)) {
+        if (!allowedKeys.has(key))
+            throw new Error(`Unknown workflow turn intent facts field: ${key}`);
+    }
+    if (typeof candidate.workflowName !== "string") {
+        throw new Error("Workflow turn intent workflowName must be a string");
+    }
+    if (typeof candidate.runId !== "string") {
+        throw new Error("Workflow turn intent runId must be a string");
+    }
+    if (typeof candidate.observedState !== "string") {
+        throw new Error("Workflow turn intent observedState must be a string");
+    }
+    if (typeof candidate.cause !== "string") {
+        throw new Error("Workflow turn intent cause must be a string");
+    }
+    validateKey(candidate.workflowName, "workflow turn facts workflow name");
+    validateRunId(candidate.runId);
+    validateKey(candidate.observedState, "workflow turn facts observed state");
+    validateWorkflowTurnIntentCause(candidate.cause);
+    if (candidate.nodeId !== null && typeof candidate.nodeId !== "string") {
+        throw new Error("Workflow turn intent nodeId must be a string or null");
+    }
+    if (candidate.attemptId !== null && typeof candidate.attemptId !== "string") {
+        throw new Error("Workflow turn intent attemptId must be a string or null");
+    }
+    if (candidate.reason !== null && typeof candidate.reason !== "string") {
+        throw new Error("Workflow turn intent reason must be a string or null");
+    }
+    if (candidate.nodeId !== null)
+        validateKey(candidate.nodeId, "workflow turn facts node id");
+    if (candidate.attemptId !== null) {
+        validateKey(candidate.attemptId, "workflow turn facts attempt id");
+    }
+    if (candidate.reason !== null && candidate.reason.length > MAX_ERROR_LENGTH) {
+        throw new Error(`Workflow turn intent reason must be at most ${MAX_ERROR_LENGTH} characters`);
+    }
+    if (typeof candidate.handoff !== "boolean") {
+        throw new Error("Workflow turn intent handoff must be a boolean");
+    }
+}
+function validateWorkflowTurnIntentCause(value) {
+    if (value !== "agentCancelled" &&
+        value !== "timedOut" &&
+        value !== "failed" &&
+        value !== "launchFailed" &&
+        value !== "controllerInterrupted" &&
+        value !== "claimLost") {
+        throw new Error(`Invalid workflow turn intent cause: ${value}`);
+    }
+    return value;
+}
+function validateWorkflowTurnIntentResolution(value) {
+    if (value !== "workflowPrompt" && value !== "presentation" && value !== "fallback") {
+        throw new Error(`Invalid workflow turn intent resolution: ${value}`);
+    }
+    return value;
+}
 function workflowRunFromRow(row) {
     return {
         runId: row.run_id,