@osolmaz/pi-workflows 0.13.4 → 0.15.0

package/src/workflows/errors.ts

@@ -20,13 +20,22 @@ export class CancelledError extends Error {
  * The current claim holder owns the run from that point on, so the fenced
  * writer must stop changing the run immediately.
  */
+export type ClaimLostReason =
+  | "missingAuthority"
+  | "expired"
+  | "ownerChanged"
+  | "tokenChanged"
+  | "generationChanged";
+
 export class ClaimLostError extends Error {
   readonly runId: string;
+  readonly reason: ClaimLostReason;
 
-  constructor(runId: string) {
-    super(`Workflow run claim lost: ${runId}`);
+  constructor(runId: string, reason: ClaimLostReason = "missingAuthority") {
+    super(`Workflow run claim lost (${reason}): ${runId}`);
     this.name = "ClaimLostError";
     this.runId = runId;
+    this.reason = reason;
   }
 }
 

package/src/workflows/human-decision.ts

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { StateDatabase, workflowStatePath } from "../state/database.js";
 import { resourceIdFor, tokenHash } from "../state/mutation.js";
+import { recordViewerDeltas } from "../state/viewer.js";
 import {
   digestCanonical,
   normalizeDecisionPresentation,
@@ -451,6 +452,7 @@ export class HumanDecisionStore {
         requestHash,
         now,
       );
+      recordDecisionViewerChange(this.state, request.runId, request.decisionId, now);
       return "created";
     });
   }
@@ -473,6 +475,13 @@ export class HumanDecisionStore {
     request: HumanDecisionRequest,
     submission: HumanDecisionSubmission,
   ): Promise<HumanDecisionAcceptance> {
+    return this.acceptSync(request, submission);
+  }
+
+  acceptSync(
+    request: HumanDecisionRequest,
+    submission: HumanDecisionSubmission,
+  ): HumanDecisionAcceptance {
     validateHumanDecisionRequestIntegrity(request);
     const normalized = validateHumanDecisionSubmission(request, submission);
     const attemptedAt = new Date().toISOString();
@@ -511,6 +520,10 @@ export class HumanDecisionStore {
     request: HumanDecisionRequest,
     now = new Date(),
   ): Promise<HumanDecisionAcceptance> {
+    return this.resolveTimeoutSync(request, now);
+  }
+
+  resolveTimeoutSync(request: HumanDecisionRequest, now = new Date()): HumanDecisionAcceptance {
     validateHumanDecisionRequestIntegrity(request);
     if (request.expiresAt === undefined || request.defaultResponse === undefined) {
       throw new Error("Human decision request has no timeout default");
@@ -630,6 +643,7 @@ export class HumanDecisionStore {
         now,
       );
       this.enqueueResolutionEffects(row.resourceId, row.revision + 1, request, "cancelled", now);
+      recordDecisionViewerChange(this.state, request.runId, request.decisionId, now);
       return "created";
     });
   }
@@ -732,6 +746,22 @@ export class HumanDecisionStore {
     return rows.filter(isRequestHashRow).map((row) => this.readRequestFromHash(row.requestHash));
   }
 
+  async listExpiredDefaultRequests(now = new Date()): Promise<HumanDecisionRequest[]> {
+    const timestamp = now.getTime();
+    if (!Number.isFinite(timestamp)) throw new Error("Human decision timeout date is invalid");
+    const rows = this.state.connection
+      .prepare(
+        `SELECT h.request_hash AS requestHash
+         FROM human_decisions h
+         LEFT JOIN human_decision_resolutions r ON r.decision_id = h.decision_id
+         WHERE h.deadline_at IS NOT NULL AND h.deadline_at <= ?
+           AND h.default_response_hash IS NOT NULL AND r.decision_id IS NULL
+         ORDER BY h.deadline_at, h.decision_id`,
+      )
+      .all(timestamp);
+    return rows.filter(isRequestHashRow).map((row) => this.readRequestFromHash(row.requestHash));
+  }
+
   private attemptAcceptance(
     request: HumanDecisionRequest,
     decision: ResolvedHumanDecision,
@@ -837,6 +867,7 @@ export class HumanDecisionStore {
       );
       this.enqueueResolutionEffects(row.resourceId, row.revision + 1, request, "accepted", now);
       this.markSubmission(request.decisionId, attempt.attemptId, "won", responseHash);
+      recordDecisionViewerChange(this.state, request.runId, request.decisionId, now);
       return { status: "accepted", decision };
     });
   }
@@ -1175,6 +1206,24 @@ export class HumanDecisionStore {
   }
 }
 
+function recordDecisionViewerChange(
+  state: StateDatabase,
+  runId: string,
+  decisionId: string,
+  now: number,
+): void {
+  recordViewerDeltas(
+    state,
+    runId,
+    [
+      { targetType: "graph" },
+      { targetType: "replay" },
+      { targetType: "inspector", targetKey: `decision:${decisionId}` },
+    ],
+    now,
+  );
+}
+
 function digestBuffer(value: string): Buffer {
   const hex = value.startsWith("sha256:") ? value.slice(7) : value;
   if (!/^[a-f0-9]{64}$/i.test(hex)) throw new Error("Expected a SHA-256 digest");

package/src/workflows/index.ts

@@ -6,8 +6,10 @@ export {
   compute,
   defineWorkflow,
   defineWorkflowRegistry,
+  idempotentEffect,
   includeWorkflow,
   includedResult,
+  manualEffect,
   isWorkflowDefinition,
   notify,
   shell,

package/src/workflows/schema.ts

@@ -104,6 +104,24 @@ export function assertValidActionNode(node: ActionNodeDefinition, nodeId = "acti
   if (hasExec === hasRun) {
     fail(`node ${nodeId} requires exactly one of run or exec`);
   }
+  if (node.effect === undefined || node.effect === null || typeof node.effect !== "object") {
+    fail(`node ${nodeId} requires a managed effect`);
+  }
+  if (typeof node.effect.type !== "string" || node.effect.type.trim().length === 0) {
+    fail(`node ${nodeId} effect type must be nonempty text`);
+  }
+  if (node.effect.recovery !== "idempotent" && node.effect.recovery !== "manual") {
+    fail(`node ${nodeId} effect recovery must be idempotent or manual`);
+  }
+  if (
+    typeof node.effect.idempotencyKey !== "string" &&
+    typeof node.effect.idempotencyKey !== "function"
+  ) {
+    fail(`node ${nodeId} effect idempotencyKey must be text or a function`);
+  }
+  if (!("request" in node.effect)) {
+    fail(`node ${nodeId} effect requires request data or a request function`);
+  }
   if (hasExec) {
     if (typeof node.exec !== "function") {
       fail(`node ${nodeId} exec must be a function`);
@@ -121,12 +139,7 @@ export function assertValidShellActionNode(
   node: ShellActionNodeDefinition,
   nodeId = "shell",
 ): void {
-  if (typeof node.exec !== "function") {
-    fail(`node ${nodeId} requires an exec function`);
-  }
-  assertOptionalFunction(node.parse, `node ${nodeId} parse`);
-  assertShellUpdates(node, nodeId);
-  assertCommonNodeFields(node, nodeId);
+  assertValidActionNode(node, nodeId);
 }
 
 function assertShellUpdates(node: ShellActionNodeDefinition, nodeId: string): void {

package/src/{viewer → workflows}/session-reducer.ts

@@ -1,4 +1,4 @@
-import type { WorkflowSessionEntryRecord, WorkflowSessionEventRecord } from "../workflows/types.js";
+import type { WorkflowSessionEntryRecord, WorkflowSessionEventRecord } from "./types.js";
 
 export type TemporalContentBlock = {
   contentIndex: number;
@@ -267,6 +267,16 @@ export function reduceSessionEvents(
   return foldSessionEvents(entries, events, throughSeq);
 }
 
+/** Continue a bounded page fold from a durable replay checkpoint. */
+export function reduceSessionEventsFromCheckpoint(
+  entries: WorkflowSessionEntryRecord[],
+  events: WorkflowSessionEventRecord[],
+  throughSeq: number,
+  checkpoint: TemporalSessionState,
+): TemporalSessionState {
+  return foldSessionEvents(entries, events, throughSeq, checkpoint);
+}
+
 /**
  * In-memory seek index. Checkpoints are viewer-only cache state and are never
  * persisted into a SQLite run state.