@sema-agent/core 5.19.0 → 5.21.0

package/dist/core/with-retry.d.ts

@@ -1,3 +1,19 @@
+/**
+ * `withRetry` (design/61 §9, core thin helper) — the consumer side of the typed-retryable error contract
+ * (`remote-env.ts`). Retries a Result-returning op, but **only** on a whitelisted typed-retryable code, up to
+ * `maxAttempts`, with optional backoff. All remote adapters (E2B / SSH / ADB) reuse it so they don't each
+ * re-implement "retry by typed code + backoff" (and risk getting the contract wrong).
+ *
+ * 🔴 **Apply ONLY to IDEMPOTENT establishment ops** — `connect` / `reconnect` (design/61 §2(A)). The error
+ * contract is "the caller decides retry per idempotency; the adapter MUST NOT blind-retry"; this helper IS that
+ * caller-side decision, scoped to the safe (idempotent) layer. **Never wrap a side-effecting operation** — and
+ * never put a permanent code (`"auth_failed"`, `"unsupported"`) in `retryableCodes` (retrying a rejected key
+ * burns the budget / can lock the account).
+ *
+ * Determinism / fault injection (council §9 F): the `op(attempt)` closure is the injection point (a test
+ * scripts a per-attempt error sequence), and `opts.sleep` overrides the real backoff delay — so
+ * "first attempt fails, second succeeds" is tested deterministically without a real device/network.
+ */
 export type RetryResult<T, E> = {
     ok: true;
     value: T;
@@ -6,10 +22,18 @@ export type RetryResult<T, E> = {
     error: E;
 };
 export interface RetryPolicy {
+    /** Error codes that warrant a retry (a typed-retryable whitelist). A code not in this list returns immediately. */
     retryableCodes: readonly string[];
+    /** Total attempts, `>= 1`. (e.g. ADB first-auth = 2; SSH connect-drop = a few.) */
     maxAttempts: number;
+    /** Backoff before attempt N (1-based; called with the attempt that just FAILED, so N≥1). Default: no wait. */
     backoffMs?: (failedAttempt: number) => number;
 }
+/**
+ * Run `op` until it succeeds, a non-retryable error surfaces, or `maxAttempts` is exhausted. `op` receives the
+ * 1-based attempt number. Returns the success, or the LAST failure (so an exhausted-but-still-failing op surfaces
+ * its final typed error to the caller).
+ */
 export declare function withRetry<T, E extends {
     code: string;
 }>(op: (attempt: number) => Promise<RetryResult<T, E>>, policy: RetryPolicy, opts?: {

package/dist/core/workflow-journal-store.d.ts

@@ -1,37 +1,197 @@
 import type { TaskResult } from "./types.js";
+/**
+ * design/97 CORE-7 — one recorded `ctx.agent` result in a workflow's RESUME journal. Unlike the observation-only
+ * {@link WorkflowRunStore} (best-effort, swallowed on throw), the journal is LOAD-BEARING: a resume replays the
+ * longest unchanged PREFIX of these (keyed by the deterministic {@link workflowAgentCallKey}) and runs only the
+ * first changed/new call + everything after it live. Same script + same args → 100% cache hit.
+ */
 export interface WorkflowJournalEntry {
+    /** The agent's deterministic call key (`ordinal:specIdentityHash`) — the replay match key. */
     callKey: string;
+    /** The agent's TaskResult, replayed verbatim when a resume's call key matches at the same ordinal. */
     result: TaskResult;
 }
+/** REF-D5: the resume-claim key triple — ONE shape for the interface pair and every implementation
+ *  (it was re-inlined seven times; a key-field rename must red every leg at once). */
 export interface ResumeClaimArgs {
     sourceRunId: string;
     newRunId: string;
     scope: string;
 }
+/**
+ * The seam a resume reads/writes its journal through. Core ships {@link InMemoryWorkflowJournalStore}; a durable
+ * deployment provides a Postgres-backed one (service SVC-2) so a workflow survives a replica crash. The owner of
+ * a run is the sole writer of its journal.
+ *
+ * 🔐 `scope` (the TENANT/principal of the resuming run) is LOAD-BEARING for multi-tenant isolation (CORE-9 audit
+ * BLOCKER): an LLM controls the `resumeFromRunId`, so `load` MUST be constrained to the caller's scope — exactly
+ * as {@link WorkflowRunStore} puts scope in the WHERE of every method. A store implementation MUST return ONLY a
+ * run's journal whose recorded scope equals the requested `scope` (a cross-scope `resumeFromRunId` resolves to an
+ * EMPTY journal → the resume safely diverges to a live re-run, never disclosing another tenant's results).
+ *
+ * SESSION-axis RULING (clay 裁定 2026-07-22, B-2 会话轴扫描案; FINAL form settled in the γ batch):
+ * `load` is deliberately SCOPE-only, PERMANENTLY — same-scope callers from a different session may
+ * replay a run's journal. Rationale: (a) same-scope = same trust domain (the task-list store
+ * records the same posture) and a runId is engine-minted, not enumerable; (b) cross-session resume
+ * is `resumeFromRunId`'s CORE legitimate use — a fresh session picking up yesterday's run has a new
+ * taskId AND a new sessionId by construction, so ANY engine-side session/owner clamp on this face
+ * refuses exactly the contract the tool teaches (the [1455] prefix-replay pins are the regression
+ * proof; a γ-batch recheck attempt was reverted on them). Layering: the ENGINE owns the scope
+ * hard-wall (this WHERE); the SESSION acceptance arm belongs to the SERVING layer, which has a
+ * session-bound connection to adjudicate against (server 1.247's wire-face soft acceptance). This
+ * face diverges from poll/stop (scope+owner/session positive-match) BY DESIGN: they gate on the
+ * caller's CURRENT identity, resume asserts continuity with a PRIOR leg.
+ */
 export interface WorkflowJournalStore {
+    /** Entries for `runId` IF its recorded scope === `scope`, ASCENDING by ordinal; otherwise EMPTY (cross-scope). */
     load(runId: string, scope: string): Promise<WorkflowJournalEntry[]>;
+    /** Record one agent's result under `(runId, scope)`. MUST be idempotent per `(runId, ordinal)` — a resumed run
+     *  re-appends the cached results of its replayed prefix, so a second append for the same ordinal overwrites. */
     append(runId: string, scope: string, entry: WorkflowJournalEntry): Promise<void>;
+    /** [1409]③ (CC diagnostics parity, additive): a HUMAN/MODEL-readable coordinate for this run's journal —
+     *  the file store returns the on-disk jsonl path (CC "Read journal.jsonl" local form); a service store
+     *  returns its API route (cloud form). `undefined`/absent ⇒ the completion notification's diagnostics
+     *  line teaches only the TaskOutput route (which is always live). Engine-facing string, never parsed. */
     locator?(runId: string, scope: string): string | undefined;
+    /**
+     * RB-242 ([1980] server → [1981] core ruling, 2026-07-30) — ADMISSION for a resume, so two concurrent
+     * `resumeFromRunId` legs off ONE source run cannot fork its execution.
+     *
+     * Why a store seam at all: the engine's own mutex is in-process only (`startWorkflow` refuses a duplicate
+     * `runId` and refuses resuming from a source still ACTIVE here). A resume mints a FRESH runId, so a second
+     * resume off the same source — from another process, replica, or a later session — trips neither guard: both
+     * legs replay the same prefix and then re-run the whole suffix LIVE, duplicating every side effect after it,
+     * each writing its own journal, neither ever seeing the other. The only place that fork is visible is the
+     * shared durable layer, i.e. here.
+     *
+     * OPTIONAL, and absence is a first-class state: a store that does NOT implement this has NO STORE-LEVEL lease
+     * semantics. RB-367 ([2054] test AI dual-process probe): a store without the hook is no longer completely
+     * unguarded, though — `runWorkflow`'s engine falls back to a process-local admission table for exactly this
+     * shape, so a same-process double `resumeFromRunId` off one source is still refused even against a store
+     * that never implements this member. That fallback cannot see a SECOND process, which is the one thing a
+     * real implementation is for — core's own {@link InMemoryWorkflowJournalStore} DOES implement this member
+     * (with in-process-only semantics; a single-process store cannot promise more), so the engine's fallback
+     * table is, in practice, only ever exercised by some OTHER store that omits the hook.
+     *
+     * Contract:
+     *  - `granted: true` ⇒ the caller (`newRunId`) now HOLDS the claim on `(sourceRunId, scope)` and owes exactly
+     *    one {@link releaseResumeClaim} for it. The engine calls that at the run's terminal boundary — completed,
+     *    failed, cancelled/aborted, or abandoned by a total-timeout — in a `finally`.
+     *  - `granted: false` ⇒ someone else holds it. The engine REFUSES the resume with an explicit error rather
+     *    than forking; `holder` (the holding leg's `newRunId`, when the store can attribute it) goes into that
+     *    error text so an operator can find the run that is actually still going. `holder` is store-supplied text
+     *    and is charset-clamped before it lands in a message.
+     *  - IDEMPOTENT for the same holder: a re-claim by the SAME `newRunId` on a claim it already holds MUST be
+     *    granted (a retry must not deadlock a run against itself).
+     *  - `scope` is the journal scope passed through VERBATIM ([1981]). A claim is keyed by `(sourceRunId, scope)`,
+     *    NOT by `sourceRunId` alone: a cross-scope caller already resolves to an EMPTY journal (the CORE-9 wall
+     *    above) so it cannot fork anything, and letting it take a global claim would hand any tenant a
+     *    denial-of-resume lever over another's runs.
+     *  - THROWING is a store failure, not a refusal — it propagates and fails the resume. Return `{granted:false}`
+     *    to refuse.
+     *  - A GRANT MEANS POSSESSION (RB-356①, codex 异源复审 2026-07-29). `granted: true` may only be returned once
+     *    the claim is RECORDED where every other contender will see it; a store that cannot tell whether it holds
+     *    the claim must refuse, with `holder` omitted if it cannot attribute the winner. The asymmetry is the
+     *    reason: an unearned refusal fails one resume loudly and is recoverable, an unearned grant forks a run
+     *    and its duplicated side effects are not.
+     *  - ACQUISITION MUST BE ATOMIC (RB-354). Contenders must never be able to observe a claim MID-ACQUISITION
+     *    and read that state as "no claim" — an implementation that reserves the key first and fills the record
+     *    in a second step needs the reservation itself to be the exclusion (SQL: one INSERT; core's file store:
+     *    write a temp, then `link` it into place). Note this interacts with crash recovery: any rule of the form
+     *    "an incomplete record is dead, take it over" is only safe if an in-flight acquisition can never look
+     *    incomplete.
+     *
+     * TWO INVALIDATION DOMAINS, each covering what the other cannot ([1981], settled with server):
+     *  1. ENGINE release — the normal path, prompt, covers every terminal outcome of a live engine.
+     *  2. STORE TTL — the backstop for an engine that DIED holding a claim (crash/kill/replica loss): it never
+     *     reaches its `finally`, so only a store-side expiry can ever free that row. Server's SQL twins land this
+     *     as the bake-store `idem_key UNIQUE` + TTL shape; core's file store carries the same TTL semantics.
+     *     A store implementing neither expiry nor release would wedge the source run's resume permanently.
+     */
     resumeClaim?(input: ResumeClaimArgs): Promise<{
         granted: boolean;
         holder?: string;
     }>;
+    /**
+     * RB-242 ([1981]) — release the claim {@link resumeClaim} granted to `newRunId` on `(sourceRunId, scope)`.
+     * Called by the engine at the resuming run's TERMINAL boundary (in a `finally`, so abort/error/abandon are
+     * covered), and ONLY when the matching claim was actually granted.
+     *
+     * MUST be idempotent and MUST NOT release a claim the caller does not hold: the claim may already be gone
+     * (TTL-reaped after a stall, then taken over by another leg), and unlinking the successor's claim would
+     * re-open exactly the fork this seam exists to prevent. A missing claim is a no-op, never an error.
+     *
+     * A throw here is swallowed by the engine — a release failure must never replace the run's real outcome, and
+     * the store's TTL is the standing backstop for the row it left behind.
+     *
+     * RB-355 (codex 异源复审 2026-07-29): the engine's terminal boundary now BOUNDS this call (and its wait on
+     * the {@link resumeClaim} verdict) by a timeout — a store that hangs would otherwise keep the run's `done`
+     * promise pending forever, after the outcome is already decided. A release that outlives that bound is
+     * treated exactly like one that throws: swallowed, with the TTL as the backstop. Implementations should not
+     * rely on the engine waiting indefinitely for cleanup.
+     */
     releaseResumeClaim?(input: ResumeClaimArgs): Promise<void>;
 }
+/** The ordinal a callKey (`ordinal:hash`) was minted at — the journal's positional index. The sole producer
+ *  ({@link workflowAgentCallKey}) always emits a well-formed `<int>:<hash>`; a MALFORMED key (no leading int)
+ *  falls back to `0` rather than throwing — callers must not feed it arbitrary strings (audit note). */
 export declare const MAX_JOURNAL_RESULT_BYTES: number;
+/** True when a serialized journal result is too large to store (UTF-8 byte length over {@link MAX_JOURNAL_RESULT_BYTES}). */
 export declare function oversizeJournalResult(serialized: string): boolean;
 export declare function callKeyOrdinal(callKey: string): number;
+/** RB-243 ([1937]): the errorCode a journal OVERSIZE TOMBSTONE carries — the resume path recognizes it to
+ *  say WHY an ordinal never replays. `failed` + this code lands on the T2A-4 no-replay arm, so replay
+ *  behavior is identical to the entry simply being absent (the pre-tombstone shape). */
 export declare const JOURNAL_OVERSIZE_ERROR_CODE = "workflow.journal_oversize";
+/** RB-243 ([1937]): mint the tiny FAILED entry the ENGINE journals in place of an oversize result. The
+ *  tombstone is minted in the engine, NOT in a store — the stores' skip semantics are unchanged (the
+ *  §4.1 backend-parity pin depends on that layering; a store-side tombstone would re-create the RB-168
+ *  dialect divergence). Never copies `result.result`/`structuredOutput` (the oversize payload); keeps
+ *  taskId/sessionId/stats so the journal read-face still shows the session handle and the paid spend. */
 export declare function journalOversizeTombstone(result: TaskResult, bytes: number): TaskResult;
+/**
+ * RB-367 ([2054] test AI dual-process probe, core-side judgment) — the TTL a resume claim {@link
+ * InMemoryWorkflowJournalStore} grants survives WITHOUT an engine release: the backstop for an engine that
+ * abandoned a granted claim without ever reaching the terminal `finally` that releases it (a bug, not the
+ * normal path — the normal path releases promptly). Same VALUE as the file store's `RESUME_CLAIM_TTL_MS`
+ * (`src/stores/file/workflow-journal-store.ts`) — kept as an independent constant rather than imported from
+ * it, because `core/` is upstream of `stores/file/` (the file store already imports FROM this module; the
+ * reverse would invert that layering) and an in-memory store's claims die with the process regardless, so the
+ * two constants have no shared-drift risk to guard against by literally sharing one declaration.
+ */
 export declare const IN_MEMORY_RESUME_CLAIM_TTL_MS: number;
+/** In-process journal store (core default). A single-replica run; durable resume across crashes needs the
+ *  service's Postgres store (SVC-2). Records each run's `scope` and enforces it on load (CORE-9 audit BLOCKER:
+ *  a cross-scope resumeFromRunId resolves to an empty journal — no cross-tenant disclosure).
+ *
+ *  RB-367: also carries a REAL {@link WorkflowJournalStore.resumeClaim}/{@link
+ *  WorkflowJournalStore.releaseResumeClaim} implementation (this store used to be the canonical example of a
+ *  store WITHOUT the seam — its own header said so). Left unimplemented, the DEFAULT deployment (no
+ *  `journalStore` supplied, or this store supplied explicitly) had NO protection against two same-process
+ *  `resumeFromRunId` calls off one source forking its execution — the class of bug RB-242 exists to close, and
+ *  a test AI's dual-process probe found it wide open on the default path while the file store's half already
+ *  worked. A single-process store's promise is necessarily single-process: this implementation gives no
+ *  cross-process guarantee (there is no shared medium to publish a claim on), so a multi-process deployment
+ *  still needs a store that IS durable/shared (the file or SQL stores) for the seam to mean anything beyond
+ *  this one process. */
 export declare class InMemoryWorkflowJournalStore implements WorkflowJournalStore {
     private readonly runs;
+    /** RB-367 resume claims, nested by scope then sourceRunId (rather than a single string-concatenated key) so
+     *  untrusted-length `scope`/`sourceRunId` text (`sourceRunId` is `resumeFromRunId` — LLM-controlled) can never
+     *  collide across the boundary between the two fields. */
     private readonly resumeClaims;
     private claimsForScope;
+    /** RB-367 — contract parity with the file store: keyed by `(sourceRunId, scope)`; idempotent re-grant to the
+     *  SAME holder; an unexpired claim held by someone else refuses (naming the holder); an expired or absent
+     *  claim is free to take. Acquisition is a single synchronous Map read-then-write with no `await` between
+     *  the check and the publish — there is no window (matching the atomicity RB-354 requires of a durable
+     *  implementation) in which a concurrent caller could observe the key as free mid-acquire. */
     resumeClaim(input: ResumeClaimArgs): Promise<{
         granted: boolean;
         holder?: string;
     }>;
+    /** RB-367 — release ONLY a claim `newRunId` still holds (a missing/foreign/already-taken-over claim is a
+     *  no-op, never an error — matches the file store's contract). */
     releaseResumeClaim(input: ResumeClaimArgs): Promise<void>;
     load(runId: string, scope: string): Promise<WorkflowJournalEntry[]>;
     append(runId: string, scope: string, entry: WorkflowJournalEntry): Promise<void>;

package/dist/core/workflow-run-store-contract.d.ts

@@ -1,5 +1,30 @@
 import { type WorkflowRunStore } from "./workflow-run-store.js";
 import type { WorkflowRun, WorkflowRunStatus } from "../orchestration/workflow.js";
+/**
+ * design/97 S1b/§D.8 — the **runner-agnostic** cross-backend contract for {@link WorkflowRunStore}, so the
+ * SAME assertions run over every backend AND **service can import it to verify its own PG implementation**
+ * (§D.8: "contract 函数须 service 可复用，放可被 import 的位置，非纯 test/ 私有").
+ *
+ * It lives in `src/` (compiled into `dist/`, re-exported from the package barrel) and uses Node's built-in
+ * `assert` — NO vitest dependency — so it runs under any harness (vitest, node:test, a bare script). Core's
+ * `test/cross-backend-shared.ts` wraps {@link workflowRunStoreContract} in a single vitest `it()` to bind it
+ * to the InMemory + File backends; service binds it to its PG store.
+ *
+ * The fixtures pin `createdAt`/`endedAt` so the `listByScope` ordering + `reap` retention are deterministic
+ * (no wall clock). `make()` must return a FRESH, empty store each call.
+ */
+/** Build a {@link WorkflowRun} fixture (terminal `completed` by default). All fields explicit + deterministic. */
 export declare function createWorkflowRun(over?: Partial<WorkflowRun>): WorkflowRun;
+/**
+ * The full cross-backend contract for {@link WorkflowRunStore}. `make` returns a fresh store; `runAssertion`
+ * lets a harness label/await each case (a vitest binding passes `it`; a bare runner can pass a sequential
+ * runner). The DEFAULT runs the cases inline and sequentially (so `service` can call
+ * `await workflowRunStoreContract(make)` with no harness at all).
+ *
+ * ⚠️ Binding note (service [390]): the cases are REGISTERED eagerly and awaited via `Promise.all` — an async
+ * `runAssertion` that schedules work concurrently will interleave cases. Bindings whose stores share state
+ * (e.g. SQL twins on one table) must CHAIN the assertions themselves (serialize inside `runAssertion`).
+ */
 export declare function workflowRunStoreContract(make: () => WorkflowRunStore, runAssertion?: (name: string, fn: () => Promise<void>) => void): Promise<void>;
+/** Re-export so a contract caller can label runs by status without re-importing the run module. */
 export type { WorkflowRunStatus };

package/dist/core/workflow-run-store.d.ts

@@ -1,47 +1,165 @@
 import type { WorkflowRun, WorkflowRunStatus } from "../orchestration/workflow.js";
+/**
+ * design/97 S1b — the **WorkflowRunStore** persistence seam for the workflow-mode primitive
+ * (`src/orchestration/workflow.ts`, S1a). It is the durable home for a {@link WorkflowRun} so the
+ * `/workflows` observability layer (S1c) can list runs IN PROGRESS *and the history* (completed / failed),
+ * across replicas — the "看之前的" core seam (design/97 §A/§D.1).
+ *
+ * **Distinct from the four load-bearing durable seams** (session / checkpoint / memory / tool-result): those
+ * are the engine's suspend/resume命脉, so core ships PG adapters for them. A WorkflowRunStore is an
+ * **observation layer — opt-in, non-engine-critical** — so per design/97 §D.8 (clay 2026-06-22 拍) core
+ * ships ONLY: this interface + {@link InMemoryWorkflowRunStore} (process-local / default / tests) +
+ * `FileWorkflowRunStore` (zero-dependency, TOC-local persistence — `src/stores/file/workflow-run-store.ts`).
+ * **The PG backend lives in service (TOB), implementing THIS interface** when it needs cross-replica
+ * `/workflows` history. `WorkflowRun` / `WorkflowRunStatus` are imported type-only — this module is purely
+ * the store contract + projection, it does NOT re-home the run model (that stays in `workflow.ts`).
+ *
+ * Mirrors the {@link import("./checkpoint-store.js").CheckpointStore} shape: create-once `put`, `get`, an
+ * **atomic CAS `update`** (scope + `rev` optimistic-concurrency — concurrent agents racing to record progress
+ * on the same run), a `listByScope` returning lightweight {@link WorkflowRunSummary} projections (history
+ * included, NOT pending-only like CheckpointStore.listByScope), and a `reap` retention sweep that only ever
+ * deletes TERMINAL runs (never a running one). The {@link summarizeWorkflowRun} projection is SHARED across
+ * all backends (anti-drift, exactly like `summarizeCheckpoint`).
+ */
+/**
+ * A lightweight, read-only projection of one {@link WorkflowRun} returned in bulk by
+ * {@link WorkflowRunStore.listByScope} so the `/workflows` list view (CLI design/92 / client design/90) can
+ * enumerate a scope's runs in ONE call — no N+1 `get`s, no full run payloads. Every field is DERIVED from
+ * the persisted run (nothing here is a new source of truth or a gate input). Built by the shared
+ * {@link summarizeWorkflowRun} so the projection is IDENTICAL across the in-memory, file, and (service) PG
+ * backends.
+ */
 export interface WorkflowRunSummary {
+    /** The run id ({@link WorkflowRun.id}). */
     id: string;
+    /** The tenant / grouping key this run lives in ({@link WorkflowRun.scope}). */
     scope: string;
+    /** γ 批 ([1510] server request): the ORIGINATING session id ({@link WorkflowRun.originatingSessionId}),
+     *  projected so a serving layer's LIST face can apply its session acceptance/filter arm without an
+     *  N+1 `get` of the full run. Absent for a direct `runWorkflow` call / sessionless deployment. */
     originatingSessionId?: string;
+    /** design/99 MF-W: the workflow's display name from the script's `export const meta` ({@link WorkflowRun.name}).
+     *  Projected here so the `/workflows` list view labels each row WITHOUT an N+1 `get` of the full run.
+     *  Absent for a direct `runWorkflow` call that supplied no name. */
     name?: string;
+    /** One-line description from the script's meta ({@link WorkflowRun.description}); absent if none. */
     description?: string;
+    /** Lifecycle status ({@link WorkflowRun.status}): running / completed / failed. */
     status: WorkflowRunStatus;
+    /** Count of agent-runs that ended failed ({@link WorkflowRun.agentFailures}) — present only when > 0.
+     *  Lets a list view flag a "completed, with failures" run without an N+1 `get` of the full run. */
     agentFailures?: number;
+    /** Title of the latest phase recorded ({@link WorkflowRun.phases}`.at(-1).title`) — what the run is on RIGHT
+     *  NOW for a `running` row (so the `/workflows` list shows the live phase without subscribing to the event
+     *  stream). Absent when no phase has started yet. */
     currentPhase?: string;
+    /** Number of phases recorded so far ({@link WorkflowRun.phases}`.length`). */
     phaseCount: number;
+    /** Number of agent-runs recorded so far ({@link WorkflowRun.agents}`.length`). */
     agentCount: number;
+    /** Total tokens spent = own + nested (`stats.tokens + stats.nested.tokens`) — the figure a triage view
+     *  sorts/compares by. own/nested stay SEPARATE on the full run (R-5); the summary folds them for display. */
     tokens: number;
+    /** When the run started ({@link WorkflowRun.startedAt}, epoch ms). */
     startedAt: number;
+    /** When the run finished ({@link WorkflowRun.endedAt}, epoch ms) — absent while still running. */
     endedAt?: number;
+    /** When the run record was created ({@link WorkflowRun.createdAt}, epoch ms) — the `listByScope` sort key. */
     createdAt: number;
 }
+/**
+ * design/97 S1b: project a {@link WorkflowRun} to its lightweight {@link WorkflowRunSummary}. SHARED by every
+ * {@link WorkflowRunStore} impl so the projection is IDENTICAL across the in-memory, file, and (service) PG
+ * backends (the anti-drift guard — exactly like `summarizeCheckpoint`). Pure; reads no clock/random. Total
+ * spend folds own + nested (`stats.tokens + stats.nested.tokens`), the one place the two are summed.
+ */
 export declare function summarizeWorkflowRun(run: WorkflowRun): WorkflowRunSummary;
+/** Whether a run is in a TERMINAL state — the ONLY states {@link WorkflowRunStore.reap} may delete (a
+ *  `running` run is never reaped, so an in-flight workflow's record can't vanish out from under it). */
 export declare function isTerminalWorkflowStatus(status: WorkflowRunStatus): boolean;
+/** A typed workflow-run-store error so callers branch on `code` (mirrors `CheckpointError`). */
 export declare class WorkflowRunStoreError extends Error {
     readonly code: "workflow_run.already_exists";
     constructor(code: "workflow_run.already_exists", message: string);
 }
+/** REF-D18: `listByScope`'s query options — the SINGLE shape the interface method and both the
+ *  In-Memory and File implementations reference. */
 export interface WorkflowRunListByScopeOptions {
     status?: WorkflowRunStatus;
     limit?: number;
     session?: string;
 }
+/**
+ * The pluggable persistence seam for workflow runs (design/97 S1b). Symmetric with `CheckpointStore`:
+ * create-once `put`, `get`, an atomic CAS `update`, a `listByScope` query (history included), and a `reap`
+ * retention sweep. A durable backend (service's PG) makes `/workflows` history cross-replica; the default
+ * {@link InMemoryWorkflowRunStore} is process-only (single instance / tests).
+ */
 export interface WorkflowRunStore {
+    /** Create-once. Throws {@link WorkflowRunStoreError} `already_exists` on a token collision (never a silent
+     *  overwrite — a reused id would clobber a live run's record). */
     put(id: string, run: WorkflowRun): Promise<void>;
     get(id: string): Promise<WorkflowRun | null>;
+    /**
+     * Atomic CAS update of an EXISTING run (`UPDATE … SET … WHERE id=? AND scope=?` [`AND rev=?`]). Returns
+     * `true` for the winner, `false` when the row is missing, the `scope` does not match (multi-tenant
+     * isolation — a wrong-scope update must not win), or `expect.rev` does not match the live row's `rev`
+     * (an intervening update bumped it). On success the store bumps the row's `rev` (monotonic) and persists
+     * the new `run`. The workflow owner is the sole writer (best-effort progress recording — design/97 §F),
+     * so `expect.rev` lets it detect a lost write rather than silently clobber.
+     */
     update(id: string, scope: string, run: WorkflowRun, expect?: {
         rev: number;
     }): Promise<boolean>;
+    /**
+     * List lightweight {@link WorkflowRunSummary} projections for runs in `scope` — **history included** (the
+     * completed / failed runs, NOT pending-only like `CheckpointStore.listByScope`), so this is the "看之前的"
+     * core query. Newest first (`createdAt` DESC). `opts.status` filters to one lifecycle state; `opts.limit`
+     * caps the result count (applied AFTER the sort, so it keeps the newest N). An empty scope returns `[]`.
+     */
+    /** `opts.session` ([1513] server ask, δ 尾件): STORE-side push-down filter on
+     *  `originatingSessionId` — strict equality, rows WITHOUT the field excluded (filter semantics,
+     *  deliberately unlike the per-id acceptance arm's absent-pass). Applied BEFORE limit, so the
+     *  serving layer's "this session's workflows" is FULL-history, not page-window ([1513] cli note). */
     listByScope(scope: string, opts?: WorkflowRunListByScopeOptions): Promise<WorkflowRunSummary[]>;
+    /**
+     * Retention sweep: delete OLD **terminal** runs in `scope` (a `running` run is NEVER deleted — design/97
+     * §D.1/§F). Returns the count deleted (for metrics). Retention is by either policy (apply BOTH when both
+     * given — a run is reaped if it fails either bound):
+     *  - `opts.maxAgeMs`: delete a terminal run whose `endedAt` (else `createdAt`) is older than `now -
+     *    maxAgeMs`.
+     *  - `opts.keep`: keep only the newest `keep` terminal runs (by `createdAt` DESC); delete the rest.
+     * With NEITHER option set, nothing is deleted (a no-op `0`) — retention is always an explicit policy.
+     */
     reap(scope: string, now: number, opts?: {
         maxAgeMs?: number;
         keep?: number;
     }): Promise<number>;
 }
+/**
+ * REF-A5 — THE optimistic-concurrency guard for {@link WorkflowRunStore.update}, shared by every backend:
+ * scope in the WHERE (multi-tenant isolation — a wrong-scope update never wins), row must exist, and an
+ * `expect.rev` that no longer matches the LIVE row loses (an intervening update bumped it). Returns the
+ * row to persist, or `null` when the CAS lost; PURE — it neither reads nor writes any store state, so
+ * each backend keeps its own persistence mechanism (in-memory `Map.set` vs ledger commit) around it.
+ * RB-59 (a cross-instance CAS both instances won) landed on this predicate.
+ */
 export declare function nextWorkflowRunOnUpdate(cur: WorkflowRun | undefined, id: string, scope: string, run: WorkflowRun, expect?: {
     rev: number;
 }): WorkflowRun | null;
+/**
+ * REF-A5 — THE `listByScope` query projection, shared by every backend: scope/status/session filter →
+ * newest-first by `createdAt` → truncate → {@link summarizeWorkflowRun}. Pure over any row iterable, so
+ * the in-memory backend passes its `Map` values and the file backend passes the replayed ledger's.
+ */
 export declare function queryWorkflowRuns(runs: Iterable<WorkflowRun>, scope: string, opts?: WorkflowRunListByScopeOptions): WorkflowRunSummary[];
+/**
+ * Default in-process {@link WorkflowRunStore}. Single-instance / tests only — it does NOT survive a restart
+ * or span replicas. Single-threaded JS already serializes `update`, so the CAS is trivially atomic here;
+ * `structuredClone` on the boundaries prevents aliasing (a later mutation of the caller's object — the live
+ * `WorkflowRun` the workflow keeps mutating — must not corrupt the stored row, and a returned run must not
+ * be a live reference the caller can mutate back into the store).
+ */
 export declare class InMemoryWorkflowRunStore implements WorkflowRunStore {
     private runs;
     put(id: string, run: WorkflowRun): Promise<void>;
@@ -54,5 +172,6 @@ export declare class InMemoryWorkflowRunStore implements WorkflowRunStore {
         maxAgeMs?: number;
         keep?: number;
     }): Promise<number>;
+    /** Test/inspection helper: number of stored runs. */
     get size(): number;
 }

package/dist/core/workflow-run-store.js

@@ -1,3 +1,4 @@
+import { assertRetentionPolicy } from "./retention-policy.js";
 export function summarizeWorkflowRun(run) {
     const latestPhase = run.phases.at(-1);
     return {
@@ -73,6 +74,7 @@ export class InMemoryWorkflowRunStore {
         return queryWorkflowRuns(this.runs.values(), scope, opts);
     }
     async reap(scope, now, opts) {
+        assertRetentionPolicy("WorkflowRunStore.reap", opts);
         if (opts?.maxAgeMs === undefined && opts?.keep === undefined)
             return 0;
         const terminal = [...this.runs.values()].filter((r) => r.scope === scope && isTerminalWorkflowStatus(r.status));