@bastani/atomic 0.9.9 → 0.9.10-alpha.1

package/dist/builtin/workflows/src/durable/prompt-reservation-state.ts

@@ -0,0 +1,177 @@
+export interface PromptReservationEntry {
+  readonly reservationId: string;
+  readonly generation: number;
+  readonly tokenId: string;
+}
+
+declare const promptReservationTokenBrand: unique symbol;
+
+/** Opaque ownership proof returned by reserve and required by release. */
+export interface PromptReservationToken extends PromptReservationEntry {
+  readonly [promptReservationTokenBrand]: true;
+}
+
+export interface PromptReservationSnapshot {
+  readonly active: readonly PromptReservationEntry[];
+  readonly released: readonly Omit<PromptReservationEntry, "tokenId">[];
+  readonly anonymousTokenIds: readonly string[];
+  readonly consumedTokenIds: readonly string[];
+}
+
+export function promptReservationToken(entry: PromptReservationEntry): PromptReservationToken {
+  return entry as PromptReservationToken;
+}
+
+export function inactivePromptReservationToken(reservationId: string): PromptReservationToken {
+  return promptReservationToken({ reservationId, generation: 1, tokenId: `inactive:${crypto.randomUUID()}` });
+}
+
+function nextPendingToken(existing: ReadonlySet<string>, index: number): string {
+  let candidate = `pending:${index}`;
+  while (existing.has(candidate)) candidate = `pending:${++index}`;
+  return candidate;
+}
+
+/** Identity-owned prompt tokens with generation tombstones for current backends. */
+export class PromptReservationState {
+  private readonly active = new Map<string, PromptReservationEntry>();
+  private readonly released = new Map<string, number>();
+  private readonly availableTokens = new Set<string>();
+  private readonly anonymousTokens = new Set<string>();
+  private readonly consumedTokens = new Set<string>();
+
+  constructor(pendingPrompts: number, snapshot?: PromptReservationSnapshot) {
+    for (const tokenId of snapshot?.consumedTokenIds ?? []) this.consumedTokens.add(tokenId);
+    for (const entry of snapshot?.active ?? []) {
+      if (this.consumedTokens.has(entry.tokenId)) continue;
+      const current = this.active.get(entry.reservationId);
+      if (current === undefined || entry.generation > current.generation) {
+        this.active.set(entry.reservationId, entry);
+      }
+      this.availableTokens.add(entry.tokenId);
+    }
+    for (const entry of snapshot?.released ?? []) {
+      const generation = Math.max(this.released.get(entry.reservationId) ?? 0, entry.generation);
+      this.released.set(entry.reservationId, generation);
+      const active = this.active.get(entry.reservationId);
+      if (active !== undefined && active.generation <= generation) {
+        this.active.delete(entry.reservationId);
+        this.availableTokens.delete(active.tokenId);
+        this.consumedTokens.add(active.tokenId);
+      }
+    }
+    for (const tokenId of snapshot?.anonymousTokenIds ?? []) {
+      if (this.consumedTokens.has(tokenId)) continue;
+      this.anonymousTokens.add(tokenId);
+      this.availableTokens.add(tokenId);
+    }
+    let index = 0;
+    while (this.availableTokens.size < Math.max(0, Math.trunc(pendingPrompts))) {
+      const tokenId = nextPendingToken(this.availableTokens, index++);
+      this.anonymousTokens.add(tokenId);
+      this.availableTokens.add(tokenId);
+    }
+  }
+
+  get pendingPrompts(): number {
+    return this.availableTokens.size;
+  }
+
+  activeToken(reservationId: string): PromptReservationToken | undefined {
+    const active = this.active.get(reservationId);
+    return active === undefined ? undefined : promptReservationToken(active);
+  }
+
+  claim(reservationId: string): PromptReservationToken | undefined {
+    return this.activeToken(reservationId)
+      ?? (this.anonymousTokens.size > 0 ? this.reserve(reservationId) : undefined);
+  }
+
+  reserve(reservationId: string): PromptReservationToken {
+    const current = this.active.get(reservationId);
+    if (current !== undefined) return promptReservationToken(current);
+    const generation = Math.max(this.released.get(reservationId) ?? 0, 0) + 1;
+    const anonymous = this.released.has(reservationId)
+      ? undefined
+      : this.anonymousTokens.values().next().value as string | undefined;
+    const tokenId = anonymous ?? `reservation:${encodeURIComponent(reservationId)}:${generation}`;
+    if (anonymous !== undefined) this.anonymousTokens.delete(anonymous);
+    const entry = { reservationId, generation, tokenId };
+    this.active.set(reservationId, entry);
+    this.availableTokens.add(tokenId);
+    return promptReservationToken(entry);
+  }
+
+  release(reservationId: string, token: PromptReservationToken): void {
+    const active = this.active.get(reservationId);
+    if (active === undefined || token === undefined || token.reservationId !== reservationId
+      || active.generation !== token.generation || active.tokenId !== token.tokenId) return;
+    this.active.delete(reservationId);
+    this.consume(active.tokenId);
+    this.released.set(reservationId, active.generation);
+  }
+
+  adjust(delta: number): void {
+    const count = Math.max(0, Math.trunc(Math.abs(delta)));
+    for (let index = 0; index < count; index++) {
+      if (delta > 0) {
+        const tokenId = `scalar:${crypto.randomUUID()}`;
+        this.anonymousTokens.add(tokenId);
+        this.availableTokens.add(tokenId);
+      } else if (delta < 0) {
+        const anonymous = this.anonymousTokens.values().next().value as string | undefined;
+        if (anonymous !== undefined) {
+          this.consume(anonymous);
+          continue;
+        }
+        const active = this.active.values().next().value as PromptReservationEntry | undefined;
+        if (active === undefined) break;
+        this.active.delete(active.reservationId);
+        this.released.set(active.reservationId, active.generation);
+        this.consume(active.tokenId);
+      }
+    }
+  }
+
+  snapshot(): PromptReservationSnapshot {
+    return {
+      active: [...this.active.values()],
+      released: [...this.released].map(([reservationId, generation]) => ({ reservationId, generation })),
+      anonymousTokenIds: [...this.anonymousTokens],
+      consumedTokenIds: [...this.consumedTokens],
+    };
+  }
+
+  private consume(tokenId: string): void {
+    this.availableTokens.delete(tokenId);
+    this.anonymousTokens.delete(tokenId);
+    this.consumedTokens.add(tokenId);
+  }
+}
+
+export function mergePromptReservationSnapshots(
+  first: PromptReservationSnapshot | undefined,
+  second: PromptReservationSnapshot | undefined,
+  pendingPrompts: number,
+): PromptReservationSnapshot | undefined {
+  if (first === undefined && second === undefined) return undefined;
+  const consumed = new Set([...(first?.consumedTokenIds ?? []), ...(second?.consumedTokenIds ?? [])]);
+  const released = new Map<string, number>();
+  for (const entry of [...(first?.released ?? []), ...(second?.released ?? [])]) {
+    released.set(entry.reservationId, Math.max(released.get(entry.reservationId) ?? 0, entry.generation));
+  }
+  const active = new Map<string, PromptReservationEntry>();
+  for (const entry of [...(first?.active ?? []), ...(second?.active ?? [])]) {
+    if (consumed.has(entry.tokenId) || (released.get(entry.reservationId) ?? 0) >= entry.generation) continue;
+    const current = active.get(entry.reservationId);
+    if (current === undefined || entry.generation > current.generation) active.set(entry.reservationId, entry);
+  }
+  const anonymousTokenIds = new Set([...(first?.anonymousTokenIds ?? []), ...(second?.anonymousTokenIds ?? [])]);
+  for (const tokenId of consumed) anonymousTokenIds.delete(tokenId);
+  return new PromptReservationState(pendingPrompts, {
+    active: [...active.values()],
+    released: [...released].map(([reservationId, generation]) => ({ reservationId, generation })),
+    anonymousTokenIds: [...anonymousTokenIds],
+    consumedTokenIds: [...consumed],
+  }).snapshot();
+}

package/dist/builtin/workflows/src/durable/prompt-reservations.ts

@@ -0,0 +1,36 @@
+import type { DurableWorkflowBackend } from "./backend.js";
+import type { PromptReservationToken } from "./prompt-reservation-state.js";
+
+export function durablePromptScope(
+  backend: DurableWorkflowBackend,
+  workflowId: string,
+): { readonly rootWorkflowId: string; readonly scope: string } {
+  return backend.promptReservationScope(workflowId);
+}
+
+export function claimDurablePromptToken(
+  backend: DurableWorkflowBackend,
+  workflowId: string,
+  reservationId: string,
+): PromptReservationToken | undefined {
+  return backend.pendingPromptToken(workflowId, reservationId);
+}
+
+export function reserveDurablePrompt(
+  backend: DurableWorkflowBackend,
+  workflowId: string,
+  reservationId: string,
+): PromptReservationToken {
+  return backend.reservePendingPrompt(workflowId, reservationId);
+}
+
+export function releaseDurablePrompt(
+  backend: DurableWorkflowBackend,
+  workflowId: string,
+  reservationId: string,
+  token: PromptReservationToken,
+): void {
+  backend.releasePendingPrompt(workflowId, reservationId, token);
+}
+
+export type { PromptReservationToken } from "./prompt-reservation-state.js";

package/dist/builtin/workflows/src/durable/resume-catalog.ts

@@ -1,209 +1,11 @@
-/**
- * Cross-session resume catalog.
- *
- * Builds the list of resumable workflows for the `/workflow resume` selector by
- * scanning session JSONL files for `workflow.durable.checkpoint` entries. This
- * is the session-file cache described by the issue — it lets a new session
- * discover workflows started in prior sessions without requiring a live DBOS
- * system database connection.
- *
- * The catalog reads session files lazily and caches results per scan. DBOS
- * remains the checkpoint source of truth; this catalog provides the discovery
- * index for the selector UI.
- *
- * cross-ref: issue #1498 — "/workflow resume should show a selector for
- * resumable workflow sessions, analogous to the /resume session selector."
- */
-
-import { readFileSync, existsSync, readdirSync } from "node:fs";
-import { join } from "node:path";
-import type { DurableCheckpointEntry, DurableWorkflowStatus, ResumableWorkflowEntry } from "./types.js";
 import type { DurableWorkflowBackend } from "./backend.js";
-import type { WorkflowSerializableValue } from "../shared/types.js";
-import { isDurableWorkflowResumable } from "./resume-eligibility.js";
-import { DURABLE_FORMAT_VERSION } from "./format-version.js";
-
-// ---------------------------------------------------------------------------
-// Session file scanning
-// ---------------------------------------------------------------------------
-
-/**
- * Scan a session directory for `workflow.durable.checkpoint` entries and build
- * a list of resumable workflows.
- *
- * @param sessionDir Directory containing session JSONL files.
- * @returns Resumable workflow entries, most recently updated first.
- */
-export function scanResumableWorkflows(sessionDir: string): readonly ResumableWorkflowEntry[] {
-  if (!existsSync(sessionDir)) return [];
-  const entries = new Map<string, ResumableWorkflowEntry>();
-  let files: string[];
-  try {
-    files = readdirSync(sessionDir).filter((f) => f.endsWith(".jsonl"));
-  } catch {
-    return [];
-  }
-  for (const file of files) {
-    const filePath = join(sessionDir, file);
-    const fileEntries = readDurableEntriesFromFile(filePath);
-    const sessionFile = filePath;
-    for (const entry of fileEntries) {
-      const existing = entries.get(entry.workflowId);
-      if (!existing || entry.ts > existing.updatedAt) {
-        entries.set(entry.workflowId, entryToResumable(entry, sessionFile));
-      }
-    }
-  }
-  return [...entries.values()].filter(isDurableWorkflowResumable).sort((a, b) => b.updatedAt - a.updatedAt);
-}
-
-function readDurableEntriesFromFile(filePath: string): readonly DurableCheckpointEntry[] {
-  let content: string;
-  try {
-    content = readFileSync(filePath, "utf-8");
-  } catch {
-    return [];
-  }
-  const results: DurableCheckpointEntry[] = [];
-  for (const line of content.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    try {
-      const parsed = JSON.parse(trimmed) as Record<string, unknown>;
-      const rawEntry = durablePayloadFromJsonlEntry(parsed);
-      if (rawEntry !== undefined) {
-        const entry = parseDurableEntry(rawEntry);
-        if (entry) results.push(entry);
-      }
-    } catch {
-      // Skip malformed lines.
-    }
-  }
-  return results;
-}
-
-function durablePayloadFromJsonlEntry(parsed: Record<string, unknown>): Record<string, unknown> | undefined {
-  if (parsed["type"] === "workflow.durable.checkpoint") return parsed;
-  if (parsed["type"] !== "custom" || parsed["customType"] !== "workflow.durable.checkpoint") return undefined;
-  const data = parsed["data"];
-  if (typeof data !== "object" || data === null || Array.isArray(data)) return undefined;
-  return data as Record<string, unknown>;
-}
-
-function parseDurableEntry(raw: Record<string, unknown>): DurableCheckpointEntry | undefined {
-  if (raw["formatVersion"] !== DURABLE_FORMAT_VERSION) return undefined;
-
-  const workflowId = raw["workflowId"];
-  const name = raw["name"];
-  const inputs = raw["inputs"];
-  const status = raw["status"];
-  const ts = raw["ts"];
-  if (typeof workflowId !== "string" || typeof name !== "string" || typeof status !== "string" || typeof ts !== "number") return undefined;
-  if (!isWorkflowSerializableObject(inputs)) return undefined;
-  return {
-    formatVersion: DURABLE_FORMAT_VERSION,
-    type: "workflow.durable.checkpoint",
-    workflowId,
-    name,
-    inputs,
-    status: status as DurableWorkflowStatus,
-    completedCheckpoints: typeof raw["completedCheckpoints"] === "number" ? raw["completedCheckpoints"] : 0,
-    pendingPrompts: typeof raw["pendingPrompts"] === "number" ? raw["pendingPrompts"] : 0,
-    ...(typeof raw["label"] === "string" ? { label: raw["label"] } : {}),
-    ...(typeof raw["rootWorkflowId"] === "string" ? { rootWorkflowId: raw["rootWorkflowId"] } : {}),
-    ...(typeof raw["resumable"] === "boolean" ? { resumable: raw["resumable"] } : {}),
-    ...(typeof raw["invocationCwd"] === "string" ? { invocationCwd: raw["invocationCwd"] } : {}),
-    ...(typeof raw["workflowCwd"] === "string" ? { workflowCwd: raw["workflowCwd"] } : {}),
-    ...(typeof raw["repositoryRoot"] === "string" ? { repositoryRoot: raw["repositoryRoot"] } : {}),
-    ...(typeof raw["gitWorktreeRoot"] === "string" ? { gitWorktreeRoot: raw["gitWorktreeRoot"] } : {}),
-    ts,
-  };
-}
+import type { ResumableWorkflowEntry } from "./types.js";
 
-function isWorkflowSerializableObject(value: unknown): value is Readonly<Record<string, WorkflowSerializableValue>> {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
-  const obj = value as Record<string, unknown>;
-  for (const key of Object.keys(obj)) {
-    if (!isSerializableValue(obj[key])) return false;
-  }
-  return true;
-}
-
-function isSerializableValue(value: unknown): value is WorkflowSerializableValue {
-  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") return true;
-  if (Array.isArray(value)) return value.every(isSerializableValue);
-  if (typeof value === "object") {
-    const obj = value as Record<string, unknown>;
-    return Object.keys(obj).every((k) => isSerializableValue(obj[k]));
-  }
-  return false;
-}
-
-function entryToResumable(entry: DurableCheckpointEntry, sessionFile: string): ResumableWorkflowEntry {
-  return {
-    workflowId: entry.workflowId,
-    name: entry.name,
-    inputs: entry.inputs,
-    status: entry.status,
-    completedCheckpoints: entry.completedCheckpoints,
-    pendingPrompts: entry.pendingPrompts,
-    sessionFile,
-    ...(entry.label !== undefined ? { label: entry.label } : {}),
-    ...(entry.rootWorkflowId !== undefined ? { rootWorkflowId: entry.rootWorkflowId } : {}),
-    ...(entry.resumable !== undefined ? { resumable: entry.resumable } : {}),
-    ...(entry.invocationCwd !== undefined ? { invocationCwd: entry.invocationCwd } : {}),
-    ...(entry.workflowCwd !== undefined ? { workflowCwd: entry.workflowCwd } : {}),
-    ...(entry.repositoryRoot !== undefined ? { repositoryRoot: entry.repositoryRoot } : {}),
-    ...(entry.gitWorktreeRoot !== undefined ? { gitWorktreeRoot: entry.gitWorktreeRoot } : {}),
-    createdAt: entry.ts,
-    updatedAt: entry.ts,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Backend-backed catalog
-// ---------------------------------------------------------------------------
-
-/**
- * List resumable workflows from a durable backend (in-memory or file-backed).
- * Used when the session file scan is not available (e.g. same-process resume).
- */
+/** List resumable workflows directly from the ready backend. */
 export function listResumableFromBackend(backend: DurableWorkflowBackend): readonly ResumableWorkflowEntry[] {
   return backend.listResumableWorkflows();
 }
 
-/**
- * Append a durable checkpoint entry to a session JSONL persistence port.
- * This caches the top-level workflow metadata so a future session can discover
- * it via {@link scanResumableWorkflows}.
- */
-export function persistDurableCacheEntry(
-  persistence: { appendEntry?: (type: string, payload: Record<string, unknown>) => string | undefined },
-  entry: DurableCheckpointEntry,
-): void {
-  if (typeof persistence.appendEntry !== "function") return;
-  persistence.appendEntry("workflow.durable.checkpoint", {
-    formatVersion: entry.formatVersion,
-    workflowId: entry.workflowId,
-    name: entry.name,
-    inputs: entry.inputs as Record<string, unknown>,
-    status: entry.status,
-    completedCheckpoints: entry.completedCheckpoints,
-    pendingPrompts: entry.pendingPrompts,
-    ...(entry.label !== undefined ? { label: entry.label } : {}),
-    ...(entry.rootWorkflowId !== undefined ? { rootWorkflowId: entry.rootWorkflowId } : {}),
-    ...(entry.resumable !== undefined ? { resumable: entry.resumable } : {}),
-    ...(entry.invocationCwd !== undefined ? { invocationCwd: entry.invocationCwd } : {}),
-    ...(entry.workflowCwd !== undefined ? { workflowCwd: entry.workflowCwd } : {}),
-    ...(entry.repositoryRoot !== undefined ? { repositoryRoot: entry.repositoryRoot } : {}),
-    ...(entry.gitWorktreeRoot !== undefined ? { gitWorktreeRoot: entry.gitWorktreeRoot } : {}),
-    ts: entry.ts,
-  });
-}
-
-/**
- * Format the resumable workflow list for display in the selector.
- */
 export function formatResumableWorkflowList(entries: readonly ResumableWorkflowEntry[]): string {
   if (entries.length === 0) return "No resumable or completed workflows found.";
   const hasCompleted = entries.some((entry) => entry.status === "completed");

package/dist/builtin/workflows/src/durable/resume-eligibility.ts

@@ -1,6 +1,6 @@
 import type { DurableWorkflowStatus } from "./types.js";
 
-/** Metadata shared by durable handles and session-cache resume entries. */
+/** Metadata required to classify a current DBOS workflow as resumable. */
 export interface DurableResumeCandidate {
   readonly workflowId: string;
   readonly status: DurableWorkflowStatus;
@@ -16,5 +16,45 @@ export function isDurableWorkflowResumable(candidate: DurableResumeCandidate): b
   if (!isRoot) return false;
   if (candidate.status === "failed" || candidate.status === "blocked") return candidate.resumable !== false;
   const hasResumeProgress = candidate.completedCheckpoints > 0 || candidate.pendingPrompts > 0;
-  return (candidate.status === "running" || candidate.status === "paused") && hasResumeProgress;
+  return candidate.resumable !== false
+    && (candidate.status === "running" || candidate.status === "paused")
+    && hasResumeProgress;
+}
+
+/**
+ * Liveness window for a `running` workflow owned by another Atomic process.
+ * Active LM stages refresh durable timing metadata at least every ~30s, so a
+ * running handle whose metadata is fresher than this window is treated as
+ * genuinely executing in that other session rather than crashed.
+ */
+export const FOREIGN_LIVE_WORKFLOW_WINDOW_MS = 120_000;
+
+export interface ForeignLivenessCandidate {
+  readonly status: DurableWorkflowStatus;
+  readonly updatedAt: number;
+  readonly ownerExecutorId?: string;
+}
+
+/** Whether a running workflow appears live in a DIFFERENT Atomic process. */
+export function isForeignLiveWorkflow(
+  candidate: ForeignLivenessCandidate,
+  localExecutorId: string,
+  now: number = Date.now(),
+): boolean {
+  if (candidate.status !== "running") return false;
+  if (candidate.ownerExecutorId === undefined || candidate.ownerExecutorId === localExecutorId) return false;
+  return now - candidate.updatedAt < FOREIGN_LIVE_WORKFLOW_WINDOW_MS;
+}
+
+/**
+ * Whether a running workflow appears genuinely live ANYWHERE (any owner).
+ * Live-running workflows are never resume targets: offering them would allow
+ * double-dispatch across sessions. Only stale-heartbeat (crashed) running
+ * workflows surface, presented as crashed rather than running.
+ */
+export function isLiveRunningWorkflow(
+  candidate: Pick<ForeignLivenessCandidate, "status" | "updatedAt">,
+  now: number = Date.now(),
+): boolean {
+  return candidate.status === "running" && now - candidate.updatedAt < FOREIGN_LIVE_WORKFLOW_WINDOW_MS;
 }