@osolmaz/pi-workflows 0.16.5 → 0.16.7

package/src/state/project-store.ts

@@ -0,0 +1,218 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { StateDatabase, workflowStatePath } from "./database.js";
+import { recordViewerDeltas } from "./viewer.js";
+
+type LeaseRow = {
+  generation: number;
+  ownerType: string | null;
+  ownerId: string | null;
+  tokenHash: Buffer | null;
+  expiresAt: number | null;
+};
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isLeaseRow(value: unknown): value is LeaseRow {
+  return isRecord(value);
+}
+
+function isProjectRow(value: unknown): value is { projectId: string } {
+  return isRecord(value);
+}
+
+function isRevisionRow(value: unknown): value is { revision: number } {
+  return isRecord(value);
+}
+
+export function isSequenceRow(value: unknown): value is { seq: number } {
+  return isRecord(value);
+}
+
+function projectIdFor(canonicalPath: string): string {
+  return `project-${createHash("sha256").update(canonicalPath).digest("hex").slice(0, 40)}`;
+}
+
+function canonicalProjectPath(value: string): string {
+  try {
+    return fs.realpathSync.native(value);
+  } catch {
+    return path.resolve(value);
+  }
+}
+
+export function validTimestamp(value?: string): string {
+  const date = value === undefined ? new Date() : new Date(value);
+  if (!Number.isFinite(date.getTime())) throw new Error("Invalid timestamp");
+  return date.toISOString();
+}
+
+export function epoch(value: string): number {
+  return Date.parse(value);
+}
+
+/** Shared connection, project, and revision operations; domain stores own their rows. */
+export abstract class ProjectStore {
+  readonly filePath: string;
+
+  readonly state: StateDatabase;
+
+  private readonly ownsState: boolean;
+
+  protected readonly projectId: string | null;
+
+  private closed = false;
+
+  constructor(
+    filePath: string = workflowStatePath(),
+    options: {
+      readOnly?: boolean;
+      projectPath?: string;
+      state?: StateDatabase;
+      /** Server-only global view. Project-scoped mutations still require projectPath. */
+      global?: boolean;
+    } = {},
+  ) {
+    this.ownsState = options.state === undefined;
+    this.state =
+      options.state ??
+      new StateDatabase({
+        filePath,
+        mode: options.readOnly === true ? "read-only" : "read-write",
+        checkLegacyState: filePath === workflowStatePath(),
+      });
+    this.filePath = this.state.filePath;
+    if (options.global === true) {
+      this.projectId = null;
+    } else {
+      const projectPath = options.projectPath === undefined ? process.cwd() : options.projectPath;
+      this.projectId =
+        this.state.mode === "read-only"
+          ? this.findProject(projectPath)
+          : this.ensureProject(projectPath);
+    }
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.ownsState) this.state.close();
+  }
+
+  private ensureProject(projectPath: string): string {
+    const canonicalPath = canonicalProjectPath(projectPath);
+    const projectId = projectIdFor(canonicalPath);
+    this.state.connection
+      .prepare(
+        `INSERT INTO projects(project_id, canonical_path, created_at)
+         VALUES (?, ?, ?) ON CONFLICT(project_id) DO NOTHING`,
+      )
+      .run(projectId, canonicalPath, Date.now());
+    return projectId;
+  }
+
+  private findProject(projectPath: string): string | null {
+    const row = this.state.connection
+      .prepare("SELECT project_id AS projectId FROM projects WHERE canonical_path = ?")
+      .get(canonicalProjectPath(projectPath));
+    return isProjectRow(row) ? row.projectId : null;
+  }
+
+  protected requireProjectId(): string {
+    if (this.projectId === null) throw new Error("Project is not registered in the state database");
+    return this.projectId;
+  }
+
+  protected requireLease(resourceId: string): LeaseRow {
+    const row = this.state.connection
+      .prepare(
+        `SELECT generation, owner_type AS ownerType, owner_id AS ownerId,
+                token_hash AS tokenHash, expires_at AS expiresAt
+         FROM leases WHERE resource_id = ?`,
+      )
+      .get(resourceId);
+    /* istanbul ignore if -- exact schema and internal query shape */
+    /* istanbul ignore if -- impossible after exact schema and transaction checks */
+    if (!isLeaseRow(row)) throw new Error(`Lease is missing: ${resourceId}`);
+    return row;
+  }
+
+  protected resourceRevision(resourceId: string): number {
+    const row = this.state.connection
+      .prepare("SELECT revision FROM resources WHERE resource_id = ?")
+      .get(resourceId);
+    /* istanbul ignore if -- exact schema and internal query shape */
+    /* istanbul ignore if -- impossible after exact schema and transaction checks */
+    if (!isRevisionRow(row)) throw new Error(`Resource is missing: ${resourceId}`);
+    return row.revision;
+  }
+
+  protected bumpResource(resourceId: string, expectedRevision: number, now: number): void {
+    const result = this.state.connection
+      .prepare(
+        "UPDATE resources SET revision = revision + 1, updated_at = ? WHERE resource_id = ? AND revision = ?",
+      )
+      .run(now, resourceId, expectedRevision);
+    if (result.changes !== 1) throw new Error("Resource revision conflict");
+    const run = this.state.connection
+      .prepare(
+        `SELECT r.run_id AS runId
+         FROM runs r JOIN viewer_runs v ON v.run_id = r.run_id
+         WHERE r.resource_id = ?`,
+      )
+      .get(resourceId);
+    if (isRecord(run) && typeof run.runId === "string") {
+      recordViewerDeltas(
+        this.state,
+        run.runId,
+        [
+          { targetType: "summary" },
+          { targetType: "graph" },
+          { targetType: "replay" },
+          { targetType: "inspector", targetKey: "run" },
+        ],
+        now,
+      );
+    }
+  }
+
+  protected insertEvent(
+    resourceId: string,
+    revision: number,
+    type: string,
+    actorType: string,
+    actorId: string | null,
+    payload: unknown,
+    now: number,
+    leaseGeneration?: number,
+  ): string {
+    const eventId = `event-${randomUUID()}`;
+    const payloadHash = this.state.putJson(payload, now);
+    this.state.connection
+      .prepare(
+        `INSERT INTO events(
+           event_id, resource_id, resource_revision, event_type, actor_type,
+           actor_id, lease_generation, payload_hash, recorded_at
+         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        eventId,
+        resourceId,
+        revision,
+        type,
+        actorType,
+        actorId,
+        leaseGeneration ?? null,
+        payloadHash,
+        now,
+      );
+    return eventId;
+  }
+
+  protected assertWritable(): void {
+    if (this.state.mode === "read-only") throw new Error("State store is read-only");
+  }
+}

package/src/state/prune.ts

@@ -450,13 +450,6 @@ function treeHasBlocker(
           OR (s.run_id IN (${values}) AND a.run_id NOT IN (${values}))`,
       [...runIds, ...runIds, ...runIds, ...runIds],
     ) ||
-    hasRow(
-      database,
-      `SELECT 1 FROM continuations
-       WHERE (parent_run_id IN (${values}) AND continuation_run_id NOT IN (${values}))
-          OR (continuation_run_id IN (${values}) AND parent_run_id NOT IN (${values}))`,
-      [...runIds, ...runIds, ...runIds, ...runIds],
-    ) ||
     hasRow(
       database,
       `SELECT 1 FROM workflow_settings
@@ -545,12 +538,6 @@ function deleteRunAggregates(database: Database.Database, runIds: string[]): voi
     const effectValues = placeholders(effectIds);
     database.prepare(`DELETE FROM effects WHERE effect_id IN (${effectValues})`).run(...effectIds);
   }
-  database
-    .prepare(
-      `DELETE FROM continuations
-       WHERE parent_run_id IN (${values}) OR continuation_run_id IN (${values})`,
-    )
-    .run(...runIds, ...runIds);
   const allResources = [...new Set([...resources, ...effectRows.map((row) => row.resourceId)])];
   if (allResources.length !== 0) {
     database

package/src/state/schema.ts

@@ -115,11 +115,9 @@ CREATE TABLE runs (
   project_id TEXT REFERENCES projects(project_id),
   parent_run_id TEXT REFERENCES runs(run_id),
   root_run_id TEXT NOT NULL REFERENCES runs(run_id),
-  lineage_kind TEXT CHECK (lineage_kind IS NULL OR lineage_kind IN ('continuation', 'restart')),
+  lineage_kind TEXT CHECK (lineage_kind IS NULL OR lineage_kind IN ('restart')),
   restart_number INTEGER NOT NULL DEFAULT 0 CHECK (restart_number >= 0),
-  parent_terminal_fingerprint BLOB CHECK (
-    parent_terminal_fingerprint IS NULL OR length(parent_terminal_fingerprint) = 32
-  ),
+  parent_run_revision INTEGER CHECK (parent_run_revision IS NULL OR parent_run_revision >= 0),
   definition_digest BLOB NOT NULL REFERENCES workflow_definitions(definition_digest),
   workflow_ref TEXT NOT NULL,
   launch_options_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
@@ -132,15 +130,14 @@ CREATE TABLE runs (
   input_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
   final_output_hash BLOB REFERENCES blobs(blob_hash),
   error_hash BLOB REFERENCES blobs(blob_hash),
-  presentation_prompt_hash BLOB REFERENCES blobs(blob_hash),
   created_at INTEGER NOT NULL,
   updated_at INTEGER NOT NULL,
   finished_at INTEGER,
-  CHECK ((status IN ('waiting', 'completed', 'failed', 'timed_out', 'cancelled')) = (finished_at IS NOT NULL)),
+  CHECK ((status IN ('completed', 'failed', 'timed_out', 'cancelled')) = (finished_at IS NOT NULL)),
   CHECK ((parent_run_id IS NULL) = (lineage_kind IS NULL)),
   CHECK (
-    (lineage_kind = 'restart' AND parent_terminal_fingerprint IS NOT NULL) OR
-    (lineage_kind IS NOT 'restart' AND parent_terminal_fingerprint IS NULL)
+    (lineage_kind = 'restart' AND parent_run_revision IS NOT NULL) OR
+    (lineage_kind IS NOT 'restart' AND parent_run_revision IS NULL)
   ),
   CHECK (parent_run_id IS NOT NULL OR restart_number = 0)
 ) STRICT;
@@ -278,8 +275,7 @@ CREATE TABLE run_queue (
     'queued', 'starting', 'running', 'parked', 'done', 'failed', 'cancelled'
   )),
   available_at INTEGER NOT NULL,
-  affinity_runner_id TEXT,
-  origin_session_id TEXT NOT NULL,
+  origin_session_id TEXT,
   consecutive_errors INTEGER NOT NULL DEFAULT 0 CHECK (consecutive_errors >= 0),
   error_code TEXT,
   error_hash BLOB REFERENCES blobs(blob_hash),
@@ -291,7 +287,7 @@ CREATE TABLE run_queue (
 
 CREATE INDEX run_queue_claim_idx ON run_queue(status, available_at, created_at);
 CREATE UNIQUE INDEX run_queue_active_session_idx ON run_queue(origin_session_id)
-WHERE status IN ('queued', 'starting', 'running');
+WHERE origin_session_id IS NOT NULL AND status IN ('queued', 'starting', 'running', 'parked');
 
 CREATE TABLE host_commands (
   request_id TEXT PRIMARY KEY,
@@ -377,7 +373,7 @@ CREATE TABLE node_attempts (
   settings_change_number INTEGER CHECK (settings_change_number IS NULL OR settings_change_number >= 0),
   settings_hash BLOB REFERENCES blobs(blob_hash),
   started_at INTEGER,
-  deadline_at INTEGER,
+  timeout_ms REAL CHECK (timeout_ms IS NULL OR timeout_ms >= 0),
   finished_at INTEGER,
   created_at INTEGER NOT NULL,
   updated_at INTEGER NOT NULL,
@@ -387,13 +383,23 @@ CREATE TABLE node_attempts (
 CREATE UNIQUE INDEX node_attempts_active_idx ON node_attempts(run_id)
 WHERE status IN ('pending', 'running', 'waiting');
 CREATE INDEX node_attempts_run_idx ON node_attempts(run_id, created_at);
-CREATE INDEX node_attempts_deadline_idx ON node_attempts(deadline_at) WHERE deadline_at IS NOT NULL;
+-- NULL means not configured; zero is an explicitly unlimited timeout.
+CREATE TABLE attempt_active_intervals (
+  attempt_id TEXT NOT NULL REFERENCES node_attempts(attempt_id) ON DELETE CASCADE,
+  interval_number INTEGER NOT NULL CHECK (interval_number > 0),
+  started_at INTEGER NOT NULL,
+  observed_at INTEGER NOT NULL,
+  ended_at INTEGER,
+  elapsed_ms REAL NOT NULL DEFAULT 0 CHECK (elapsed_ms >= 0),
+  PRIMARY KEY (attempt_id, interval_number)
+) STRICT;
+CREATE UNIQUE INDEX attempt_active_intervals_open_idx ON attempt_active_intervals(attempt_id)
+WHERE ended_at IS NULL;
 
 CREATE TABLE run_steps (
   run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
   step_index INTEGER NOT NULL CHECK (step_index >= 0),
   attempt_id TEXT NOT NULL REFERENCES node_attempts(attempt_id),
-  output_override_hash BLOB REFERENCES blobs(blob_hash),
   PRIMARY KEY (run_id, step_index),
   UNIQUE (run_id, attempt_id)
 ) STRICT;
@@ -504,11 +510,10 @@ CREATE TABLE interactive_requests (
   run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
   attempt_id TEXT NOT NULL UNIQUE REFERENCES node_attempts(attempt_id) ON DELETE CASCADE,
   target_session_id TEXT NOT NULL,
-  kind TEXT NOT NULL CHECK (kind IN ('agent', 'assistant', 'decision')),
+  kind TEXT NOT NULL CHECK (kind IN ('agent', 'assistant', 'checkpoint', 'decision')),
   contract_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
   revision INTEGER NOT NULL DEFAULT 1 CHECK (revision > 0),
   status TEXT NOT NULL CHECK (status IN ('pending', 'settled', 'cancelled')),
-  unproductive_turn_ends INTEGER NOT NULL DEFAULT 0 CHECK (unproductive_turn_ends >= 0),
   accepted_submission_id TEXT,
   created_at INTEGER NOT NULL,
   updated_at INTEGER NOT NULL,
@@ -520,6 +525,8 @@ CREATE TABLE interactive_requests (
 
 CREATE INDEX interactive_requests_session_idx
   ON interactive_requests(target_session_id, status, created_at);
+CREATE UNIQUE INDEX interactive_requests_pending_run_idx
+  ON interactive_requests(run_id) WHERE status = 'pending';
 
 CREATE TABLE workflow_messages (
   workflow_message_id TEXT PRIMARY KEY,
@@ -615,13 +622,6 @@ CREATE TABLE human_decision_submissions (
   PRIMARY KEY (decision_id, attempt_id)
 ) STRICT;
 
-CREATE TABLE continuations (
-  decision_id TEXT PRIMARY KEY REFERENCES human_decisions(decision_id) ON DELETE CASCADE,
-  parent_run_id TEXT NOT NULL UNIQUE REFERENCES runs(run_id),
-  continuation_run_id TEXT NOT NULL UNIQUE REFERENCES runs(run_id),
-  created_at INTEGER NOT NULL
-) STRICT;
-
 CREATE TABLE controller_resources (
   controller_resource_id TEXT PRIMARY KEY,
   resource_id TEXT NOT NULL UNIQUE REFERENCES resources(resource_id) ON DELETE CASCADE,

package/src/state/workflow-messages.ts

@@ -8,7 +8,7 @@ export const WORKFLOW_TURN_SCHEMA = "pi-workflows.workflow-turn.v1" as const;
 
 export type WorkflowMessageKind = "step" | "decision" | "notification" | "terminal" | "followUp";
 export type WorkflowMessageStatus = "pending" | "sent" | "cancelled";
-export type WorkflowStepReason = "initial" | "reminder" | "resumed";
+export type WorkflowStepReason = "initial" | "resumed";
 export type WorkflowTurnState = "started" | "ended";
 export type WorkflowTurnStopReason = "completed" | "aborted" | "error" | "lost";
 
@@ -278,6 +278,8 @@ export class WorkflowMessageStore {
       if (message.runId !== options.runId || message.targetSessionId !== options.targetSessionId) {
         throw new Error("Workflow turn does not match its message");
       }
+      if (!message.content.triggerTurn)
+        throw new Error("Workflow message does not request a model turn");
       if (message.status !== "sent") throw new Error("Workflow turn requires a sent message");
       const open = this.openTurnForMessage(options.workflowMessageId);
       if (open !== undefined) {
@@ -496,7 +498,7 @@ export function isWorkflowMessageContent(value: unknown): value is WorkflowMessa
 
 function validateContent(content: WorkflowMessageContent, kind: WorkflowMessageKind): void {
   if (!isWorkflowMessageContent(content)) throw new Error("Workflow message content is invalid");
-  const shouldTrigger = kind === "step" || kind === "terminal" || kind === "followUp";
+  const shouldTrigger = kind === "step" || kind === "followUp";
   if (content.triggerTurn !== shouldTrigger) {
     throw new Error(`Workflow message kind ${kind} has invalid turn behavior`);
   }

package/src/viewer/backup.ts

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { StateDatabase, workflowStatePath } from "../state/database.js";
+import { workflowStateViolations } from "../workflows/diagnostics.js";
 
 /** Verify only an explicit inactive backup. Active state is verified through WorkflowClient. */
 export function verifyInactiveBackup(
@@ -15,6 +16,12 @@ export function verifyInactiveBackup(
   const state = new StateDatabase({ filePath: resolved, mode: "read-only" });
   try {
     state.integrityCheck();
+    const violations = workflowStateViolations(state);
+    if (violations.length > 0) {
+      throw new Error(
+        violations.map((item) => `${item.code} ${item.runId}: ${item.detail}`).join("\n"),
+      );
+    }
   } finally {
     state.close();
   }

package/src/workflows/diagnostics.ts

@@ -0,0 +1,78 @@
+import type { StateDatabase } from "../state/database.js";
+
+export type WorkflowStateViolation = {
+  code:
+    | "queueState"
+    | "waitingRequest"
+    | "pendingRequest"
+    | "acceptedRequest"
+    | "activeClock"
+    | "sessionTurns";
+  runId: string;
+  detail: string;
+};
+
+/** Inspect domain facts without repairing or reinterpreting durable state. */
+export function workflowStateViolations(state: StateDatabase): WorkflowStateViolation[] {
+  const checks: Array<{ code: WorkflowStateViolation["code"]; detail: string; sql: string }> = [
+    {
+      code: "queueState",
+      detail: "Execution and queue terminal states disagree.",
+      sql: `SELECT r.run_id AS runId FROM runs r JOIN run_queue q ON q.run_id = r.run_id
+        WHERE ((q.status IN ('done', 'failed', 'cancelled')) OR
+          (r.status IN ('completed', 'failed', 'timed_out', 'cancelled') AND NOT EXISTS (
+            SELECT 1 FROM effects e WHERE e.source_resource_id = r.resource_id
+              AND e.effect_type = 'run.settle_queue' AND e.status = 'pending')))
+        AND NOT ((r.status = 'completed' AND q.status = 'done')
+          OR (r.status IN ('failed', 'timed_out') AND q.status = 'failed')
+          OR (r.status = 'cancelled' AND q.status = 'cancelled'))`,
+    },
+    {
+      code: "waitingRequest",
+      detail: "A waiting run has no pending request or unconsumed accepted response.",
+      sql: `SELECT r.run_id AS runId FROM runs r WHERE r.status = 'waiting' AND NOT EXISTS (
+        SELECT 1 FROM interactive_requests i WHERE i.run_id = r.run_id
+          AND (i.status = 'pending' OR (i.status = 'settled' AND i.consumed_at IS NULL)))`,
+    },
+    {
+      code: "pendingRequest",
+      detail: "A pending request has no matching active attempt and live run.",
+      sql: `SELECT i.run_id AS runId FROM interactive_requests i
+        JOIN runs r ON r.run_id = i.run_id JOIN node_attempts a ON a.attempt_id = i.attempt_id
+        WHERE i.status = 'pending' AND (a.run_id <> i.run_id
+          OR a.status NOT IN ('pending', 'running', 'waiting', 'interrupted')
+          OR r.status NOT IN ('running', 'waiting'))`,
+    },
+    {
+      code: "acceptedRequest",
+      detail: "A settled request has no matching accepted submission.",
+      sql: `SELECT i.run_id AS runId FROM interactive_requests i
+        LEFT JOIN interactive_submissions s ON s.submission_id = i.accepted_submission_id
+        WHERE i.status = 'settled' AND (s.submission_id IS NULL OR s.request_id <> i.request_id OR s.outcome <> 'accepted')`,
+    },
+    {
+      code: "activeClock",
+      detail: "An active interval belongs to paused, terminal, or unconfigured work.",
+      sql: `SELECT DISTINCT a.run_id AS runId FROM attempt_active_intervals t
+        JOIN node_attempts a ON a.attempt_id = t.attempt_id JOIN runs r ON r.run_id = a.run_id
+        WHERE t.ended_at IS NULL AND (r.paused = 1 OR r.status NOT IN ('running', 'waiting')
+          OR a.status NOT IN ('pending', 'running', 'waiting') OR a.timeout_ms IS NULL)`,
+    },
+    {
+      code: "sessionTurns",
+      detail: "A Pi session has more than one open workflow turn.",
+      sql: `SELECT DISTINCT t.run_id AS runId FROM workflow_turns t WHERE t.state = 'started'
+        AND t.target_session_id IN (SELECT target_session_id FROM workflow_turns
+          WHERE state = 'started' GROUP BY target_session_id HAVING COUNT(*) > 1)`,
+    },
+  ];
+  return state.readTransaction(() =>
+    checks.flatMap(({ code, detail, sql }) =>
+      (state.connection.prepare(sql).all() as { runId: string }[]).map(({ runId }) => ({
+        code,
+        runId,
+        detail,
+      })),
+    ),
+  );
+}