@bastani/atomic 0.8.31-alpha.5 → 0.9.0-alpha.1

package/dist/builtin/workflows/src/shared/store-prompt-methods.ts

@@ -0,0 +1,219 @@
+import type {
+  RecordStagePromptAnswerOptions,
+  ResolveStagePendingPromptOptions,
+  Store,
+} from "./store-public-types.js";
+import type { PendingPrompt } from "./store-types.js";
+import { isTerminalStageStatus, TERMINAL_STATUSES, type StoreContext } from "./store-internal.js";
+
+type PromptStoreMethods = Pick<
+  Store,
+  | "recordPendingPrompt"
+  | "resolvePendingPrompt"
+  | "awaitPendingPrompt"
+  | "recordStagePendingPrompt"
+  | "resolveStagePendingPrompt"
+  | "awaitStagePendingPrompt"
+  | "recordStagePromptAnswer"
+  | "recordStagePromptDraft"
+  | "getStagePromptDraft"
+  | "clearStagePromptDraft"
+  | "getStagePromptAnswer"
+  | "clearStagePromptAnswer"
+>;
+
+export function createPromptStoreMethods(context: StoreContext): PromptStoreMethods {
+  const { state } = context;
+
+  return {
+    recordPendingPrompt(runId: string, prompt: PendingPrompt): boolean {
+      const run = context.findRun(runId);
+      if (!run) return false;
+      if (TERMINAL_STATUSES.has(run.status)) return false;
+      if (run.pendingPrompt !== undefined) return false;
+      run.pendingPrompt = { ...prompt };
+      context.bumpAndNotify();
+      return true;
+    },
+
+    resolvePendingPrompt(runId: string, promptId: string, response: unknown): boolean {
+      const run = context.findRun(runId);
+      if (!run) return false;
+      const pending = run.pendingPrompt;
+      if (!pending || pending.id !== promptId) return false;
+      run.pendingPrompt = undefined;
+      // Notify first so observers see the cleared state before the waiter resumes the workflow body.
+      context.bumpAndNotify();
+      const entry = state.resolvers.get(promptId);
+      if (entry) {
+        state.resolvers.delete(promptId);
+        entry.resolve(response);
+      }
+      return true;
+    },
+
+    awaitPendingPrompt(runId: string, promptId: string): Promise<unknown> {
+      return new Promise<unknown>((resolve, reject) => {
+        const run = context.findRun(runId);
+        if (!run) {
+          reject(new Error(`atomic-workflows: run "${runId}" not found`));
+          return;
+        }
+        const pending = run.pendingPrompt;
+        if (!pending || pending.id !== promptId) {
+          reject(new Error(`atomic-workflows: pending prompt "${promptId}" not registered on run "${runId}"`));
+          return;
+        }
+        state.resolvers.set(promptId, { promptId, resolve, reject });
+      });
+    },
+
+    recordStagePendingPrompt(runId: string, stageId: string, prompt: PendingPrompt): boolean {
+      const run = context.findRun(runId);
+      if (!run) return false;
+      if (TERMINAL_STATUSES.has(run.status)) return false;
+      const stage = context.findStage(run, stageId);
+      if (!stage) return false;
+      if (isTerminalStageStatus(stage.status)) return false;
+      if (stage.pendingPrompt !== undefined) return false;
+      stage.pendingPrompt = { ...prompt };
+      stage.promptFootprint = { ...prompt };
+      stage.status = "awaiting_input";
+      stage.awaitingInputSince = prompt.createdAt;
+      context.bumpAndNotify();
+      return true;
+    },
+
+    resolveStagePendingPrompt(
+      runId: string,
+      stageId: string,
+      promptId: string,
+      response: unknown,
+      options: ResolveStagePendingPromptOptions = {},
+    ): boolean {
+      const run = context.findRun(runId);
+      if (!run) return false;
+      const stage = context.findStage(run, stageId);
+      if (!stage) return false;
+      const pending = stage.pendingPrompt;
+      if (!pending || pending.id !== promptId) return false;
+      state.stagePromptDrafts.delete(context.stagePromptDraftKey(runId, stageId, promptId));
+      if (options.recordAnswer !== false) {
+        state.stagePromptAnswers.set(context.stagePromptAnswerKey(runId, stageId), {
+          runId,
+          stageId,
+          promptId,
+          kind: pending.kind,
+          value: response,
+          answeredAt: Date.now(),
+          ...(options.answerSource !== undefined ? { answerSource: options.answerSource } : {}),
+        });
+        stage.promptAnswerState = "available";
+      } else {
+        state.stagePromptAnswers.delete(context.stagePromptAnswerKey(runId, stageId));
+        delete stage.promptAnswerState;
+      }
+      stage.pendingPrompt = undefined;
+      if (stage.status === "awaiting_input") {
+        stage.status = "running";
+        delete stage.awaitingInputSince;
+      }
+      context.bumpAndNotify();
+      const entry = state.resolvers.get(promptId);
+      if (entry) {
+        state.resolvers.delete(promptId);
+        entry.resolve(response);
+      }
+      return true;
+    },
+
+    awaitStagePendingPrompt(runId: string, stageId: string, promptId: string): Promise<unknown> {
+      return new Promise<unknown>((resolve, reject) => {
+        const run = context.findRun(runId);
+        if (!run) {
+          reject(new Error(`atomic-workflows: run "${runId}" not found`));
+          return;
+        }
+        const stage = context.findStage(run, stageId);
+        if (!stage) {
+          reject(new Error(`atomic-workflows: stage "${stageId}" not found on run "${runId}"`));
+          return;
+        }
+        const pending = stage.pendingPrompt;
+        if (!pending || pending.id !== promptId) {
+          reject(
+            new Error(
+              `atomic-workflows: pending prompt "${promptId}" not registered on stage "${stageId}" in run "${runId}"`,
+            ),
+          );
+          return;
+        }
+        state.resolvers.set(promptId, { promptId, resolve, reject });
+      });
+    },
+
+    recordStagePromptAnswer(
+      runId: string,
+      stageId: string,
+      prompt: PendingPrompt,
+      response: unknown,
+      options: RecordStagePromptAnswerOptions = {},
+    ): boolean {
+      const run = context.findRun(runId);
+      if (!run) return false;
+      if (TERMINAL_STATUSES.has(run.status)) return false;
+      const stage = context.findStage(run, stageId);
+      if (!stage) return false;
+      if (isTerminalStageStatus(stage.status)) return false;
+      state.stagePromptAnswers.set(context.stagePromptAnswerKey(runId, stageId), {
+        runId,
+        stageId,
+        promptId: prompt.id,
+        kind: prompt.kind,
+        value: response,
+        answeredAt: Date.now(),
+        ...(options.answerSource !== undefined ? { answerSource: options.answerSource } : {}),
+      });
+      if (stage.promptFootprint === undefined) stage.promptFootprint = { ...prompt };
+      stage.promptAnswerState = "available";
+      if (stage.status === "awaiting_input") {
+        stage.status = "running";
+        delete stage.awaitingInputSince;
+      }
+      context.bumpAndNotify();
+      return true;
+    },
+
+    recordStagePromptDraft(runId: string, stageId: string, promptId: string, text: string): boolean {
+      if (context.stageHasActiveTextPrompt(runId, stageId, promptId) === undefined) return false;
+      state.stagePromptDrafts.set(context.stagePromptDraftKey(runId, stageId, promptId), text);
+      return true;
+    },
+
+    getStagePromptDraft(runId: string, stageId: string, promptId: string): string | undefined {
+      if (context.stageHasActiveTextPrompt(runId, stageId, promptId) === undefined) return undefined;
+      return state.stagePromptDrafts.get(context.stagePromptDraftKey(runId, stageId, promptId));
+    },
+
+    clearStagePromptDraft(runId: string, stageId: string, promptId: string): boolean {
+      return state.stagePromptDrafts.delete(context.stagePromptDraftKey(runId, stageId, promptId));
+    },
+
+    getStagePromptAnswer(runId: string, stageId: string) {
+      return state.stagePromptAnswers.get(context.stagePromptAnswerKey(runId, stageId));
+    },
+
+    clearStagePromptAnswer(runId: string, stageId: string): void {
+      const removed = state.stagePromptAnswers.delete(context.stagePromptAnswerKey(runId, stageId));
+      const run = context.findRun(runId);
+      const stage = run ? context.findStage(run, stageId) : undefined;
+      const clearAvailabilityMarker = stage?.promptAnswerState === "available";
+      if (clearAvailabilityMarker) {
+        delete stage.promptAnswerState;
+      }
+      if (removed || clearAvailabilityMarker) {
+        context.bumpAndNotify();
+      }
+    },
+  };
+}

package/dist/builtin/workflows/src/shared/store-public-types.ts

@@ -0,0 +1,215 @@
+import type { WorkflowOutputValues } from "./types.js";
+import type {
+  PendingPrompt,
+  PromptKind,
+  RunSnapshot,
+  StageInputRequest,
+  StageSnapshot,
+  StageNotice,
+  StoreSnapshot,
+  ToolEvent,
+  RunStatus,
+  WorkflowFailureKind,
+  WorkflowFailureCode,
+  WorkflowFailureRecoverability,
+  WorkflowFailureDisposition,
+  WorkflowNotice,
+  WorkflowChildRunRef,
+} from "./store-types.js";
+
+export interface RunEndMetadata {
+  readonly failureKind?: WorkflowFailureKind;
+  readonly failureCode?: WorkflowFailureCode;
+  readonly failureRecoverability?: WorkflowFailureRecoverability;
+  readonly failureDisposition?: WorkflowFailureDisposition;
+  readonly failureMessage?: string;
+  readonly failedStageId?: string;
+  readonly resumable?: boolean;
+  readonly retryAfterMs?: number;
+  readonly exited?: boolean;
+  readonly exitReason?: string;
+}
+
+export interface RunBlockedMetadata extends RunEndMetadata {
+  readonly failureRecoverability: "recoverable";
+  readonly failedStageId: string;
+  readonly resumable: true;
+  readonly blockedAt?: number;
+}
+
+export type StagePromptAnswerSource = "workflow_ui" | "workflow_tool";
+
+export interface PromptAnswerRecord {
+  readonly runId: string;
+  readonly stageId: string;
+  readonly promptId: string;
+  readonly kind: PromptKind;
+  readonly value: unknown;
+  readonly answeredAt: number;
+  readonly answerSource?: StagePromptAnswerSource;
+}
+
+export interface ResolveStagePendingPromptOptions {
+  /**
+   * Whether to retain the response in the live-only prompt answer ledger for
+   * continuation replay. Abort/default resolutions should set this to false.
+   */
+  readonly recordAnswer?: boolean;
+  /** Identifies who answered the prompt so notification code can avoid echoing workflow-tool answers. */
+  readonly answerSource?: StagePromptAnswerSource;
+}
+
+export interface RecordStagePromptAnswerOptions {
+  /** Identifies who answered the prompt so notification code can avoid echoing workflow-tool answers. */
+  readonly answerSource?: StagePromptAnswerSource;
+}
+
+export interface Store {
+  runs(): readonly RunSnapshot[];
+  notices(): readonly WorkflowNotice[];
+  activeRunId(): string | null;
+  recordRunStart(run: RunSnapshot): void;
+  recordStageStart(runId: string, stage: StageSnapshot): void;
+  /** Link a workflow boundary stage to its live child run before that child completes. */
+  recordStageWorkflowChildRun(runId: string, stageId: string, ref: WorkflowChildRunRef): boolean;
+  recordToolStart(runId: string, stageId: string, evt: ToolEvent): void;
+  recordToolEnd(runId: string, stageId: string, evt: ToolEvent): void;
+  recordStageEnd(runId: string, stage: StageSnapshot): void;
+  /**
+   * Records the end of a run.
+   * Returns `true` if state changed, `false` if the run was not found or
+   * already in a terminal state (completed | failed | killed | skipped | cancelled | blocked).
+   * `result` is applied for intentional success/exit statuses (completed | skipped | cancelled | blocked).
+   * `error` is only applied for status "failed" | "killed".
+   */
+  recordRunEnd(
+    runId: string,
+    status: RunStatus,
+    result?: WorkflowOutputValues,
+    error?: string,
+    metadata?: RunEndMetadata,
+  ): boolean;
+  /**
+   * Record an active, recoverable workflow failure without ending the run.
+   * The run remains resumable/running and carries failure metadata for status,
+   * persistence restore, and continuation decisions.
+   */
+  recordRunBlocked(runId: string, error: string, metadata: RunBlockedMetadata): boolean;
+  /**
+   * Remove a run from live workflow history/status. Any pending HIL prompt
+   * waiter is rejected because the workflow will not resume through that path.
+   * Returns `true` when a run was removed, `false` when the id is unknown.
+   */
+  removeRun(runId: string): boolean;
+  recordNotice(notice: WorkflowNotice): void;
+  /**
+   * Acknowledges a notice by id.
+   * Returns `true` if notice was found and not yet acked, `false` otherwise.
+   */
+  ackNotice(id: string): boolean;
+  /**
+   * Record a pending HIL prompt for a run. The run must exist; if it's
+   * already in a terminal state or already has a pending prompt, the call
+   * is rejected (`false`). On success, store subscribers fire.
+   *
+   * Resolution lives on `awaitPendingPrompt` / `resolvePendingPrompt`.
+   */
+  recordPendingPrompt(runId: string, prompt: PendingPrompt): boolean;
+  /**
+   * Resolve the pending prompt on a run with a user-provided response.
+   * Returns `true` when the run had a matching pending prompt (the prompt
+   * is cleared and any waiter rejected with the response). `false` for
+   * unknown runId, missing prompt, or id mismatch.
+   *
+   * `response` is forwarded verbatim to the awaiter; callers shape it to
+   * match the prompt's kind (string for input/editor, boolean for confirm,
+   * one of `choices` for select).
+   */
+  resolvePendingPrompt(runId: string, promptId: string, response: unknown): boolean;
+  /**
+   * Wait for a previously recorded pending prompt to resolve. Returns the
+   * response value passed to `resolvePendingPrompt`. Rejects if the run is
+   * terminated (cancelled / killed) before the user responds.
+   *
+   * Used by the background UI adapter to bridge `ctx.ui.*` calls to the
+   * overlay-driven response. Foreground runs never call this.
+   */
+  awaitPendingPrompt(runId: string, promptId: string): Promise<unknown>;
+  /** Record a pending HIL prompt for a specific workflow stage/node. */
+  recordStagePendingPrompt(runId: string, stageId: string, prompt: PendingPrompt): boolean;
+  /** Resolve a pending HIL prompt on a specific workflow stage/node. */
+  resolveStagePendingPrompt(
+    runId: string,
+    stageId: string,
+    promptId: string,
+    response: unknown,
+    options?: ResolveStagePendingPromptOptions,
+  ): boolean;
+  /** Wait for a stage/node-scoped HIL prompt to resolve. */
+  awaitStagePendingPrompt(runId: string, stageId: string, promptId: string): Promise<unknown>;
+  /**
+   * Record a live-only prompt answer for prompt-node UIs that do not use
+   * `stage.pendingPrompt` (notably arbitrary `ctx.ui.custom<T>` widgets).
+   * The raw value stays in the private answer ledger and is never serialized
+   * into snapshots or persistence.
+   */
+  recordStagePromptAnswer(
+    runId: string,
+    stageId: string,
+    prompt: PendingPrompt,
+    response: unknown,
+    options?: RecordStagePromptAnswerOptions,
+  ): boolean;
+  /**
+   * Record a live-only draft for an active stage-local input/editor prompt.
+   * Draft text may contain secrets and must never be copied into snapshots,
+   * status output, logs, notifications, or persisted metadata.
+   */
+  recordStagePromptDraft(runId: string, stageId: string, promptId: string, text: string): boolean;
+  /** Return a live-only draft for an active stage-local input/editor prompt, if present. */
+  getStagePromptDraft(runId: string, stageId: string, promptId: string): string | undefined;
+  /** Clear a live-only draft for a stage-local prompt. */
+  clearStagePromptDraft(runId: string, stageId: string, promptId: string): boolean;
+  /**
+   * Return the live-only prompt answer record for a completed prompt stage, if
+   * still available. The returned value may contain secrets and must never be
+   * logged, serialized, or copied into snapshots/persistence. Answers remain
+   * resident in memory until explicitly cleared, the run is removed, or the
+   * store is cleared.
+   */
+  getStagePromptAnswer(runId: string, stageId: string): PromptAnswerRecord | undefined;
+  /** Clear the live-only prompt answer record for a stage. Primarily used by tests/cleanup. */
+  clearStagePromptAnswer(runId: string, stageId: string): void;
+  /**
+   * Record Pi/pi SDK session metadata for a stage after lazy attach. The
+   * serializable snapshot tracks this so post-mortem reopen via
+   * `SessionManager.open(sessionFile)` is possible without storing live
+   * handles in the store. Returns `true` when state changed.
+   */
+  recordStageSession(runId: string, stageId: string, session: { sessionId?: string; sessionFile?: string }): boolean;
+  /** Toggle the `attachable` flag on a stage. */
+  recordStageAttachable(runId: string, stageId: string, attachable: boolean): boolean;
+  /** Toggle the `attached` flag on a stage. Snapshot-only. */
+  recordStageAttached(runId: string, stageId: string, attached: boolean): boolean;
+  /** Mark a live stage as awaiting a user response, or restore it to running. */
+  recordStageAwaitingInput(runId: string, stageId: string, awaiting: boolean, ts?: number): boolean;
+  /** Record the serializable descriptor of a brokered structured prompt awaiting an answer. */
+  recordStageInputRequest(runId: string, stageId: string, request: StageInputRequest): boolean;
+  /** Clear a stage's brokered structured-prompt descriptor. */
+  clearStageInputRequest(runId: string, stageId: string): boolean;
+  /** Mark a stage as `paused` and record `pausedAt`. */
+  recordStagePaused(runId: string, stageId: string, pausedAt?: number): boolean;
+  /** Clear `paused`/`blocked` state on a stage and record `resumedAt`. */
+  recordStageResumed(runId: string, stageId: string, resumedAt?: number): boolean;
+  recordStageBlocked(runId: string, stageId: string, blockedBy: string): boolean;
+  recordStageUnblocked(runId: string, stageId: string): boolean;
+  recordStageNotice(runId: string, stageId: string, notice: StageNotice): boolean;
+  /** Mark a run as `paused`. */
+  recordRunPaused(runId: string, pausedAt?: number): boolean;
+  /** Restore a run from `paused` back to `running`. */
+  recordRunResumed(runId: string, resumedAt?: number): boolean;
+  /** Drop every run and notice. */
+  clear(): void;
+  snapshot(): StoreSnapshot;
+  subscribe(fn: (snap: StoreSnapshot) => void): () => void;
+}

package/dist/builtin/workflows/src/shared/store-run-methods.ts

@@ -0,0 +1,223 @@
+import type { WorkflowOutputValues } from "./types.js";
+import type { Store, RunBlockedMetadata, RunEndMetadata } from "./store-public-types.js";
+import type { RunSnapshot, RunStatus, StoreSnapshot, WorkflowNotice } from "./store-types.js";
+import { accumulatePausedDurationMs, elapsedRunMs } from "./timing.js";
+import { isTopLevelWorkflowRun } from "./run-visibility.js";
+import {
+  applyRunEndMetadata,
+  clearRunFailureMetadata,
+  clearStaleBlockedRunMetadata,
+  TERMINAL_STATUSES,
+  type StoreContext,
+} from "./store-internal.js";
+
+type RunStoreMethods = Pick<
+  Store,
+  | "runs"
+  | "notices"
+  | "activeRunId"
+  | "recordRunStart"
+  | "recordRunEnd"
+  | "recordRunBlocked"
+  | "removeRun"
+  | "recordNotice"
+  | "ackNotice"
+  | "recordRunPaused"
+  | "recordRunResumed"
+  | "clear"
+  | "snapshot"
+  | "subscribe"
+>;
+
+export function createRunStoreMethods(context: StoreContext): RunStoreMethods {
+  const { state } = context;
+
+  return {
+    runs(): readonly RunSnapshot[] {
+      return state.runs;
+    },
+
+    notices(): readonly WorkflowNotice[] {
+      return state.notices;
+    },
+
+    activeRunId(): string | null {
+      // Most recently started top-level run that hasn't ended. Nested workflow runs stay in the
+      // store for live control/expanded graph rendering, but should not steal the active slot.
+      for (let i = state.runs.length - 1; i >= 0; i--) {
+        const run = state.runs[i];
+        if (run && isTopLevelWorkflowRun(run) && run.endedAt === undefined) {
+          return run.id;
+        }
+      }
+      // Degraded fallback: a child run is in flight but no top-level run is.
+      for (let i = state.runs.length - 1; i >= 0; i--) {
+        const run = state.runs[i];
+        if (run && run.endedAt === undefined) {
+          return run.id;
+        }
+      }
+      return null;
+    },
+
+    recordRunStart(run: RunSnapshot): void {
+      state.runs.push(run);
+      context.bumpAndNotify();
+    },
+
+    recordRunEnd(
+      runId: string,
+      status: RunStatus,
+      result?: WorkflowOutputValues,
+      error?: string,
+      metadata?: RunEndMetadata,
+    ): boolean {
+      const run = context.findRun(runId);
+      if (!run) return false;
+      if (TERMINAL_STATUSES.has(run.status)) return false;
+      run.status = status;
+      run.endedAt = Date.now();
+      if (run.pausedAt !== undefined) {
+        run.pausedDurationMs = accumulatePausedDurationMs(run.pausedDurationMs, run.pausedAt, run.endedAt);
+        run.pausedAt = undefined;
+      }
+      run.durationMs = elapsedRunMs(run, run.endedAt);
+      const wasBlocked = run.blockedAt !== undefined || run.failureDisposition === "active_blocked";
+      delete run.blockedAt;
+      if (status === "completed" || status === "skipped" || status === "cancelled" || status === "blocked") {
+        if (result !== undefined) run.result = result;
+        clearRunFailureMetadata(run);
+        if (metadata !== undefined) applyRunEndMetadata(run, metadata);
+      } else {
+        if (wasBlocked && error === undefined) delete run.error;
+        if ((status === "failed" || status === "killed") && error !== undefined) {
+          run.error = error;
+        }
+        if (wasBlocked) clearStaleBlockedRunMetadata(run, metadata);
+        if (metadata !== undefined) applyRunEndMetadata(run, metadata);
+        if (run.failureDisposition === "active_blocked") delete run.failureDisposition;
+        if (status === "killed") {
+          run.failureRecoverability = "non_recoverable";
+          run.failureDisposition = "terminal_killed";
+          run.resumable = false;
+        }
+      }
+      const pending = run.pendingPrompt;
+      if (pending) {
+        run.pendingPrompt = undefined;
+        context.rejectPrompt(pending.id, `atomic-workflows: run ${runId} ended before prompt resolved`);
+      }
+      context.rejectAllStagePrompts(runId, run, `atomic-workflows: run ${runId} ended before prompt resolved`);
+      context.bumpAndNotify();
+      return true;
+    },
+
+    recordRunBlocked(runId: string, error: string, metadata: RunBlockedMetadata): boolean {
+      const run = context.findRun(runId);
+      if (!run) return false;
+      if (TERMINAL_STATUSES.has(run.status)) return false;
+      run.status = "running";
+      run.error = error;
+      run.failureKind = metadata.failureKind;
+      run.failureCode = metadata.failureCode;
+      run.failureRecoverability = metadata.failureRecoverability;
+      run.failureDisposition = metadata.failureDisposition;
+      run.failureMessage = metadata.failureMessage;
+      run.failedStageId = metadata.failedStageId;
+      run.resumable = metadata.resumable;
+      run.blockedAt = metadata.blockedAt ?? Date.now();
+      if (metadata.retryAfterMs !== undefined) run.retryAfterMs = metadata.retryAfterMs;
+      context.bumpAndNotify();
+      return true;
+    },
+
+    removeRun(runId: string): boolean {
+      const index = state.runs.findIndex((r) => r.id === runId);
+      if (index < 0) return false;
+      const run = state.runs[index]!;
+      const pending = run.pendingPrompt;
+      if (pending) {
+        context.rejectPrompt(pending.id, `atomic-workflows: run ${runId} was removed before prompt resolved`);
+      }
+      context.rejectAllStagePrompts(runId, run, `atomic-workflows: run ${runId} was removed before prompt resolved`);
+      for (const stage of run.stages) {
+        state.stagePromptAnswers.delete(context.stagePromptAnswerKey(runId, stage.id));
+      }
+      state.runs.splice(index, 1);
+      for (let i = state.notices.length - 1; i >= 0; i--) {
+        if (state.notices[i]?.runId === runId) state.notices.splice(i, 1);
+      }
+      context.bumpAndNotify();
+      return true;
+    },
+
+    recordNotice(notice: WorkflowNotice): void {
+      state.notices.push(notice);
+      context.bumpAndNotify();
+    },
+
+    ackNotice(id: string): boolean {
+      const notice = state.notices.find((n) => n.id === id);
+      if (!notice || notice.ackedAt !== undefined) return false;
+      notice.ackedAt = Date.now();
+      context.bumpAndNotify();
+      return true;
+    },
+
+    recordRunPaused(runId: string, pausedAt?: number): boolean {
+      const run = context.findRun(runId);
+      if (!run) return false;
+      if (TERMINAL_STATUSES.has(run.status)) return false;
+      if (run.status === "paused") return false;
+      run.status = "paused";
+      run.pausedAt = pausedAt ?? Date.now();
+      run.resumedAt = undefined;
+      context.bumpAndNotify();
+      return true;
+    },
+
+    recordRunResumed(runId: string, resumedAt?: number): boolean {
+      const run = context.findRun(runId);
+      if (!run) return false;
+      if (TERMINAL_STATUSES.has(run.status)) return false;
+      if (run.status !== "paused") return false;
+      const resumedTs = resumedAt ?? Date.now();
+      run.status = "running";
+      run.pausedDurationMs = accumulatePausedDurationMs(run.pausedDurationMs, run.pausedAt, resumedTs);
+      run.resumedAt = resumedTs;
+      run.pausedAt = undefined;
+      context.bumpAndNotify();
+      return true;
+    },
+
+    clear(): void {
+      if (
+        state.runs.length === 0 &&
+        state.notices.length === 0 &&
+        state.resolvers.size === 0 &&
+        state.stagePromptAnswers.size === 0 &&
+        state.stagePromptDrafts.size === 0
+      ) return;
+      state.runs.length = 0;
+      state.notices.length = 0;
+      for (const entry of state.resolvers.values()) {
+        entry.reject(new Error("atomic-workflows: store cleared"));
+      }
+      state.resolvers.clear();
+      state.stagePromptAnswers.clear();
+      state.stagePromptDrafts.clear();
+      context.bumpAndNotify();
+    },
+
+    snapshot(): StoreSnapshot {
+      return context.snapshot();
+    },
+
+    subscribe(fn: (snap: StoreSnapshot) => void): () => void {
+      state.listeners.add(fn);
+      return () => {
+        state.listeners.delete(fn);
+      };
+    },
+  };
+}