@defrex/autobuild 0.8.0 → 0.10.0

package/packages/core/src/store/repo-state-events.ts

@@ -0,0 +1,205 @@
+/**
+ * The bounded repository-journal read (AUT-489): a pure subset derivation
+ * that stateless full-state readers can fetch instead of the whole journal
+ * without changing what their reducers report.
+ *
+ * The hosted dispatcher appends ~4 journal events per invocation (run-started,
+ * tick-started, tick-completed/tick-yielded, run-stopped) whether or not it
+ * did anything, so the journal grows forever with wall-clock time while the
+ * durable signal stays small. Every repository-state consumer reduces the
+ * journal through one of four pure reducers whose event-type dependencies
+ * partition the catalog:
+ *
+ * - `reduceDispatchSettings` — only the three dispatcher setting types
+ *   (latest-wins by seq).
+ * - `reduceDispatchStatus(events, latestRun)` — only run-correlated
+ *   dispatcher facts, and it skips every event whose `payload.run` is not the
+ *   latest run. A run's facts are appended under its own run id, which is
+ *   minted at `dispatcher.run-started`, so all facts the reducer keeps live at
+ *   or after the latest run-started.
+ * - `reduceHarvest` (and everything built on it) — only `harvest.*` events
+ *   plus the three setting types, which it explicitly ignores.
+ * - `sandboxStates` — only `orchestrator.sandbox.*` events.
+ *
+ * So the bounded subset is: **every event of a durable (slow-growing) type —
+ * all `harvest.*`, all `orchestrator.sandbox.*`, and the three dispatcher
+ * setting types — plus, when the journal contains at least one
+ * `dispatcher.run-started`, the tail from that latest run-started to the end
+ * of the journal.** For a hosted repository with N no-op invocations this
+ * subset's size is a constant (one invocation's ~4 facts plus the durable
+ * signal), independent of N.
+ *
+ * INVARIANT FOR AUTHORS OF NEW REPOSITORY EVENT TYPES: a new type must either
+ * (a) join `REPOSITORY_STATE_EVENT_TYPES` — it is durable, slow-growing state
+ * some reducer depends on at full replay depth — or (b) join
+ * `REPOSITORY_RUN_SCOPED_EVENT_TYPES` — it is run-correlated and its only
+ * consumers reduce it for the latest run, so the tail from the latest
+ * `dispatcher.run-started` covers it. `tests/store/repo-state-events.test.ts`
+ * asserts the two sets exactly partition `REPOSITORY_EVENT_TYPES`; adding a
+ * type to neither fails the build until the author makes the call. A type in
+ * neither set would be silently dropped from bounded reads.
+ *
+ * Reducing this subset with the state readers yields exactly what a full
+ * replay yields: `reduceDispatchSettings`, `reduceHarvest`, `sandboxStates`
+ * see identical event lists, and `reduceDispatchStatus` sees every event it
+ * keeps (the rest are skipped by the `payload.run !== latestRun` guard). The
+ * journal itself stays append-only; no event is deleted, rewritten, or
+ * re-ordered, and a replay from the start is untouched.
+ */
+import type { RepositoryEvent, RepositoryEventType } from '../events/repository'
+import { defineReducer, type IncrementalReducer } from '../kernel/incremental'
+import {
+  dispatcherSettingEventPayloadSchemas,
+  dispatcherStatusEventPayloadSchemas,
+  harvestEventPayloadSchemas,
+  orchestratorSandboxEventPayloadSchemas,
+} from '../events/repository'
+
+/** The anchor fact a bounded read's tail hangs from. */
+const RUN_STARTED = 'dispatcher.run-started'
+
+/** Durable, slow-growing repository event types: every fact a state reducer
+ * may consult at full replay depth. Derived from the catalog groups so a new
+ * harvest or sandbox event type joins automatically; the three dispatcher
+ * setting types are enumerated because they share one schema group with the
+ * run-correlated `dispatcher.config-reloaded`. */
+export const REPOSITORY_STATE_EVENT_TYPES: readonly RepositoryEventType[] = [
+  ...Object.keys(harvestEventPayloadSchemas),
+  ...Object.keys(orchestratorSandboxEventPayloadSchemas),
+  ...Object.keys(dispatcherSettingEventPayloadSchemas).filter(
+    (type) => type !== 'dispatcher.config-reloaded',
+  ),
+] as RepositoryEventType[]
+
+/** Run-correlated repository event types: facts whose only state consumers
+ * reduce them for the latest dispatcher run, so the tail from the latest
+ * `dispatcher.run-started` contains everything those consumers keep. */
+export const REPOSITORY_RUN_SCOPED_EVENT_TYPES: readonly RepositoryEventType[] = [
+  ...Object.keys(dispatcherStatusEventPayloadSchemas),
+  'dispatcher.config-reloaded',
+] as RepositoryEventType[]
+
+const STATE_TYPES = new Set<string>(REPOSITORY_STATE_EVENT_TYPES)
+
+/**
+ * The race-closed read shape every SQL adapter delegates `getRepoStateEvents`
+ * to (AUT-551). Both adapters issue the anchor probe and the selection as two
+ * separate statements, so a concurrent append of the journal's first
+ * `dispatcher.run-started` between them is invisible to the probe, absent
+ * from the durable-only selection, yet present in the journal by the time the
+ * method returns — a stateless reader can transiently throw
+ * `effective-config-unavailable` where a moment-later full replay would
+ * succeed.
+ *
+ * The fix is a **one-shot anchor re-check on the durable-only outcome**:
+ * after a selection that took the durable-only branch (the probe saw no
+ * anchor), re-probe the anchor once; if an anchor now exists, re-run the
+ * anchored selection against it. The invariant this achieves: a durable-only
+ * result is returned only when the journal was anchor-free as of the final
+ * probe — so a run-started appended between the original probe and the
+ * selection can never be missed while present. When the first probe *did*
+ * find an anchor, no re-check is needed: the anchored select's
+ * `seq >= anchor` arm is monotone-inclusive, so any later run-started (higher
+ * seq) is picked up by that same select. A run-started appended after the
+ * final re-probe is an ordinary post-read concurrent append — outside this
+ * read's snapshot, exactly as if it had landed after the method returned —
+ * and is not this race; that bound is why the re-check is one-shot and never
+ * a loop.
+ *
+ * Non-concurrent behavior is byte-identical: the same two statements run in
+ * the same order; only the durable-only outcome may trigger one extra
+ * probe+select pair.
+ */
+export async function readRepoStateEventsWithAnchorRecheck(
+  probeAnchor: () => Promise<number | undefined>,
+  select: (anchor: number | undefined) => Promise<RepositoryEvent[]>,
+): Promise<RepositoryEvent[]> {
+  const anchor = await probeAnchor()
+  const events = await select(anchor)
+  if (anchor !== undefined) return events
+  const rechecked = await probeAnchor()
+  return rechecked === undefined ? events : select(rechecked)
+}
+
+/** Carried state for the bounded read: the latest run-started seq (the last
+ * in array order, as the whole-array pass overwrites it) and every event seen,
+ * in array order. Nothing is pruned: a later run-started may carry a lower seq
+ * than an earlier one and restore events below the earlier anchor, so only
+ * `finish` can apply the filter exactly. Pruning below a monotone anchor is
+ * valid only for seq-ordered input and belongs with the cached-state
+ * follow-up. */
+export interface RepositoryStateEventsAcc {
+  anchor?: number
+  retained: RepositoryEvent[]
+}
+
+/** Bump when `RepositoryStateEventsAcc` or its fold changes. */
+export const REPOSITORY_STATE_EVENTS_REDUCER_VERSION = 1
+
+const keeps = (event: RepositoryEvent, anchor: number | undefined): boolean =>
+  STATE_TYPES.has(event.type) || (anchor !== undefined && event.seq >= anchor)
+
+export const repositoryStateEventsReducer: IncrementalReducer<
+  RepositoryStateEventsAcc,
+  RepositoryEvent,
+  RepositoryEvent[]
+> = defineReducer<RepositoryStateEventsAcc, RepositoryEvent, RepositoryEvent[]>({
+  version: REPOSITORY_STATE_EVENTS_REDUCER_VERSION,
+  initial: () => ({ retained: [] }),
+  fold(acc, events) {
+    for (const event of events) {
+      if (event.type === RUN_STARTED) acc.anchor = event.seq
+      acc.retained.push(event)
+    }
+  },
+  finish: (acc) => acc.retained.filter((event) => keeps(event, acc.anchor)),
+})
+
+/** Carried state for the pruned journal view: the latest run-started seq and
+ * the subset the bounded read would return as of the events folded so far. Unlike
+ * `RepositoryStateEventsAcc` it prunes on every `dispatcher.run-started`
+ * (everything before the new anchor that is not durable leaves the tail), which
+ * is exact for seq-ordered input — the only input a real journal produces — and
+ * keeps the accumulator bounded, so it is the one a snapshot stores. */
+export interface JournalViewAcc {
+  anchor?: number
+  retained: RepositoryEvent[]
+}
+
+/** Bump when `JournalViewAcc` or its fold changes. */
+export const JOURNAL_VIEW_REDUCER_VERSION = 1
+
+/** Fold seq-ordered events into a journal view in place. */
+export function foldJournalView(acc: JournalViewAcc, events: readonly RepositoryEvent[]): void {
+  for (const event of events) {
+    if (event.type === RUN_STARTED) {
+      acc.anchor = event.seq
+      acc.retained = acc.retained.filter((held) => STATE_TYPES.has(held.type))
+    }
+    if (STATE_TYPES.has(event.type) || acc.anchor !== undefined) acc.retained.push(event)
+  }
+}
+
+export const journalViewReducer: IncrementalReducer<
+  JournalViewAcc,
+  RepositoryEvent,
+  RepositoryEvent[]
+> = defineReducer<JournalViewAcc, RepositoryEvent, RepositoryEvent[]>({
+  version: JOURNAL_VIEW_REDUCER_VERSION,
+  initial: () => ({ retained: [] }),
+  fold: foldJournalView,
+  finish: (acc) => [...acc.retained],
+})
+
+/** The normative subset derivation every adapter implements and the contract
+ * tests use as the oracle: durable types across the whole journal, plus —
+ * only when the journal has one — every event from the latest
+ * `dispatcher.run-started` onward, ordered by seq. A journal with no
+ * run-started has **no tail at all** (durable types only); the anchor is
+ * never defaulted to 0, which would make a `seq >= anchor` clause select the
+ * whole journal and defeat the bound. */
+export function projectRepositoryStateEvents(
+  events: readonly RepositoryEvent[],
+): RepositoryEvent[] {
+  return repositoryStateEventsReducer.reduce(events)
+}

package/packages/core/src/store/retention.ts

@@ -38,6 +38,13 @@
  */
 export const OPERATOR_NOTES_REPO_KIND = 'operator-notes'
 
+/** The repository artifact carrying the schema-validated composed Config one
+ * dispatch run used. The embedded orchestrator's hosted wiring resolves its
+ * per-repository configuration from the latest revision of this kind
+ * (AUT-342). Defined here — the store must not import from the CLI — and
+ * re-exported by `cli/dispatch.ts`, which deposits it. */
+export const DISPATCHER_EFFECTIVE_CONFIG_ARTIFACT = 'dispatcher-effective-config'
+
 /**
  * Repository-scoped artifact kinds subject to retention. Values mirror the
  * kind constants in `cli/dispatch.ts` (DISPATCHER_EFFECTIVE_CONFIG_ARTIFACT)

package/packages/core/src/store/session-handle.ts

@@ -1,3 +1,4 @@
+import type { ReducerSnapshot, SnapshotScope } from './snapshots'
 import type { EventType } from '../events/payloads'
 import type { EventWrite } from '../events/catalog'
 import type { RepositoryEventType, RepositoryEventWrite } from '../events/repository'
@@ -13,6 +14,7 @@ import type {
   Artifact,
   ArtifactInput,
   ArtifactMeta,
+  BuildDigest,
   BuildRecord,
   BuildStore,
   NewBuildInput,
@@ -26,6 +28,13 @@ import type {
   SubscribeOptions,
   Unsubscribe,
 } from './types'
+import type {
+  TicketAsset,
+  TicketAssetInput,
+  TicketAssetLimits,
+  TicketAssetMeta,
+  TicketAssetSummary,
+} from './ticket-assets'
 import type {
   StreamChunk,
   StreamOutcome,
@@ -160,6 +169,41 @@ export function createSessionScopedStore(store: BuildStore, scope: string): Sess
     getRepoEvents(repo: string, _sinceSeq?: number): Promise<RepositoryEvent[]> {
       return Promise.reject(new SessionScopeError(scope, 'getRepoEvents', repo))
     },
+    getRepoStateEvents(repo: string): Promise<RepositoryEvent[]> {
+      return Promise.reject(new SessionScopeError(scope, 'getRepoStateEvents', repo))
+    },
+    getRepoHighWater(repo: string): Promise<number> {
+      return Promise.reject(new SessionScopeError(scope, 'getRepoHighWater', repo))
+    },
+    getReducerSnapshot(
+      target: SnapshotScope,
+      _reducer: string,
+      _version: number,
+    ): Promise<ReducerSnapshot | null> {
+      return Promise.reject(
+        new SessionScopeError(
+          scope,
+          'getReducerSnapshot',
+          target.kind === 'build' ? target.slug : target.repo,
+        ),
+      )
+    },
+    putReducerSnapshot(
+      target: SnapshotScope,
+      _reducer: string,
+      _snapshot: ReducerSnapshot,
+    ): Promise<boolean> {
+      return Promise.reject(
+        new SessionScopeError(
+          scope,
+          'putReducerSnapshot',
+          target.kind === 'build' ? target.slug : target.repo,
+        ),
+      )
+    },
+    getRepoBuildDigests(repo: string): Promise<Map<string, BuildDigest>> {
+      return Promise.reject(new SessionScopeError(scope, 'getRepoBuildDigests', repo))
+    },
     putRepoArtifact(repo: string, _artifact: ArtifactInput): Promise<RepositoryArtifactMeta> {
       return Promise.reject(new SessionScopeError(scope, 'putRepoArtifact', repo))
     },
@@ -173,6 +217,48 @@ export function createSessionScopedStore(store: BuildStore, scope: string): Sess
     listRepoArtifacts(repo: string, _kind?: string): Promise<RepositoryArtifactMeta[]> {
       return Promise.reject(new SessionScopeError(scope, 'listRepoArtifacts', repo))
     },
+    ticketAssetLimits(repo: string): Promise<TicketAssetLimits> {
+      return Promise.reject(new SessionScopeError(scope, 'ticketAssetLimits', repo))
+    },
+    putTicketAsset(
+      repo: string,
+      _ticketId: string,
+      _asset: TicketAssetInput,
+    ): Promise<TicketAssetMeta> {
+      return Promise.reject(new SessionScopeError(scope, 'putTicketAsset', repo))
+    },
+    getTicketAsset(
+      repo: string,
+      _ticketId: string,
+      _kind: string,
+      _name: string,
+      _rev?: number,
+    ): Promise<TicketAsset | null> {
+      return Promise.reject(new SessionScopeError(scope, 'getTicketAsset', repo))
+    },
+    getPinnedTicketAsset(
+      slug: string,
+      _kind: string,
+      _name: string,
+      _rev?: number,
+    ): Promise<TicketAsset | null> {
+      return Promise.reject(new SessionScopeError(scope, 'getPinnedTicketAsset', slug))
+    },
+    listTicketAssets(
+      repo: string,
+      _ticketId: string,
+      _opts?: { revisions?: boolean },
+    ): Promise<TicketAssetSummary[]> {
+      return Promise.reject(new SessionScopeError(scope, 'listTicketAssets', repo))
+    },
+    removeTicketAsset(
+      repo: string,
+      _ticketId: string,
+      _kind: string,
+      _name: string,
+    ): Promise<TicketAssetMeta | null> {
+      return Promise.reject(new SessionScopeError(scope, 'removeTicketAsset', repo))
+    },
     claimRepoLease(repo: string, _holder: string, _ttlMs: number): Promise<boolean> {
       return Promise.reject(new SessionScopeError(scope, 'claimRepoLease', repo))
     },
@@ -199,6 +285,14 @@ export function createSessionScopedStore(store: BuildStore, scope: string): Sess
       own('appendSessionEvent', id)
       return store.appendSessionEvent(id, event)
     },
+    async appendSessionEventIfCurrent<T extends SessionEventType>(
+      id: string,
+      expectedSeq: number,
+      event: SessionEventWrite<T>,
+    ): Promise<SessionEventEnvelope<T> | null> {
+      own('appendSessionEventIfCurrent', id)
+      return store.appendSessionEventIfCurrent(id, expectedSeq, event)
+    },
     async getSessionEvents(
       id: string,
       sinceSeq?: number,

package/packages/core/src/{sessions/reducer.ts → store/session-reducer.ts}

@@ -6,6 +6,7 @@
  * history; unknown facts cannot exist.
  */
 import type { SessionEvent } from '../events/sessions'
+import { defineReducer, type IncrementalReducer } from '../kernel/incremental'
 
 export type SessionStatus = 'idle' | 'running' | 'suspended' | 'awaiting-approval' | 'archived'
 export type SessionSuspensionCause = 'budget' | 'approval'
@@ -13,7 +14,7 @@ export type TurnOutcomeState = 'open' | 'suspended' | 'completed' | 'failed'
 
 export type SessionTurnTrigger =
   | { kind: 'message'; messageSeq: number }
-  | { kind: 'wake'; build: string; seq: number; type: string }
+  | { kind: 'wake'; build?: string; journal?: true; seq: number; type: string }
 
 export interface SessionTurn {
   turn: string
@@ -21,8 +22,11 @@ export interface SessionTurn {
   startedSeq: number
   trigger: SessionTurnTrigger
   state: TurnOutcomeState
-  usage?: { inputTokens: number; outputTokens: number; turns?: number }
+  usage?: { inputTokens: number; outputTokens: number; steps: number; turns?: number }
   error?: string
+  /** The typed failure class of a failed turn (provider-unavailable,
+   * exhausted, credentials, configuration, or internal). */
+  kind?: 'provider-unavailable' | 'exhausted' | 'credentials' | 'configuration' | 'internal'
 }
 
 export interface SessionState {
@@ -43,6 +47,10 @@ export interface SessionState {
   wakeGlobs: string[]
   /** Per build, the highest build event seq a wake trigger has consumed. */
   wakeCursors: Record<string, number>
+  /** The highest repository-journal seq a wake trigger has consumed (0 when
+   * no journal wake has been consumed). The journal has an independent seq
+   * space with no build slug, so it gets its own cursor. */
+  journalWakeCursor: number
   /** Every turn in start order, with its stream id and outcome. */
   turns: SessionTurn[]
 }
@@ -55,16 +63,28 @@ interface TurnEntry extends SessionTurn {
 const isTerminal = (state: SessionTurn['state']): boolean =>
   state === 'completed' || state === 'failed'
 
-/** Reduce a session's events into its derived state. `session.archived` is
- * terminal: every fact after it is ignored — the archived state is frozen. */
-export function reduceSession(events: SessionEvent[]): SessionState {
-  const turns: TurnEntry[] = []
-  let archived = false
-  let pendingApproval: SessionState['pendingApproval']
-  let wakeGlobs: string[] = []
-  const wakeCursors: Record<string, number> = {}
+/** The carried accumulator: the reduced fields plus the per-turn suspension
+ * cause the public state drops. Once `archived`, the fold ignores every later
+ * event, so an advance after archive stays frozen. */
+export interface SessionAcc {
+  turns: TurnEntry[]
+  archived: boolean
+  pendingApproval: SessionState['pendingApproval']
+  wakeGlobs: string[]
+  wakeCursors: Record<string, number>
+  journalWakeCursor: number
+}
 
-  const open = (): TurnEntry | undefined => turns.findLast((turn) => !isTerminal(turn.state))
+/** Bump when `SessionAcc`'s shape or fold semantics change. */
+export const SESSION_REDUCER_VERSION = 1
+
+function foldSession(acc: SessionAcc, events: readonly SessionEvent[]): void {
+  const turns = acc.turns
+  let archived = acc.archived
+  let pendingApproval = acc.pendingApproval
+  let wakeGlobs = acc.wakeGlobs
+  const wakeCursors = acc.wakeCursors
+  let journalWakeCursor = acc.journalWakeCursor
 
   for (const event of events) {
     if (archived) break
@@ -85,8 +105,15 @@ export function reduceSession(events: SessionEvent[]): SessionState {
         }
         turns.push(entry)
         if (event.payload.trigger.kind === 'wake') {
-          const build = event.payload.trigger.build
-          wakeCursors[build] = Math.max(wakeCursors[build] ?? 0, event.payload.trigger.seq)
+          if (event.payload.trigger.journal === true) {
+            journalWakeCursor = Math.max(journalWakeCursor, event.payload.trigger.seq)
+          } else {
+            // The catalog's `.check()` guarantees `build` when `journal` is
+            // absent — a stored trigger can never be a journal wake without
+            // the flag or a build wake without the slug.
+            const build = event.payload.trigger.build!
+            wakeCursors[build] = Math.max(wakeCursors[build] ?? 0, event.payload.trigger.seq)
+          }
         }
         break
       }
@@ -118,11 +145,13 @@ export function reduceSession(events: SessionEvent[]): SessionState {
           pendingApproval.toolCallId === event.payload.toolCallId
         ) {
           pendingApproval = undefined
-          // The answer resumes the turn; `turn.resumed` is the runner's
-          // acknowledgement of the same fact, so between answer and resume
-          // the status is already `running` when a turn is open.
-          const entry = turns.findLast((candidate) => candidate.turn === event.payload.turn)
-          if (entry && entry.state === 'suspended') entry.state = 'open'
+          // The answer only clears the pending approval — `turn.resumed` is
+          // the sole resume fact, recorded by the runner when it actually
+          // picks the turn up. Flipping the turn state here (the earlier
+          // behavior) made a session look `running` while no runner existed:
+          // an answered approval whose resuming invocation died would be
+          // unrecoverable. The status sequence after an answer is therefore
+          // awaiting-approval → suspended(approval) → running.
         }
         break
       }
@@ -139,6 +168,7 @@ export function reduceSession(events: SessionEvent[]): SessionState {
         if (entry && !isTerminal(entry.state)) {
           entry.state = 'failed'
           entry.error = event.payload.error
+          entry.kind = event.payload.kind
         }
         break
       }
@@ -148,7 +178,15 @@ export function reduceSession(events: SessionEvent[]): SessionState {
     }
   }
 
-  const openEntry = open()
+  acc.archived = archived
+  acc.pendingApproval = pendingApproval
+  acc.wakeGlobs = wakeGlobs
+  acc.journalWakeCursor = journalWakeCursor
+}
+
+function finishSession(acc: SessionAcc): SessionState {
+  const { turns, archived, pendingApproval, wakeGlobs, wakeCursors, journalWakeCursor } = acc
+  const openEntry = turns.findLast((turn) => !isTerminal(turn.state))
   // Status precedence: archived > awaiting-approval > suspended > running >
   // idle. An unanswered approval outranks its turn's suspension; the answer
   // that clears it hands status back to the turn.
@@ -180,6 +218,28 @@ export function reduceSession(events: SessionEvent[]): SessionState {
     ...(pendingApproval !== undefined ? { pendingApproval } : {}),
     wakeGlobs,
     wakeCursors,
+    journalWakeCursor,
     turns: turns.map(({ suspensionCause: _suspensionCause, ...turn }) => turn),
   }
 }
+
+export const sessionReducer: IncrementalReducer<SessionAcc, SessionEvent, SessionState> =
+  defineReducer({
+    version: SESSION_REDUCER_VERSION,
+    initial: (): SessionAcc => ({
+      turns: [],
+      archived: false,
+      pendingApproval: undefined,
+      wakeGlobs: [],
+      wakeCursors: {},
+      journalWakeCursor: 0,
+    }),
+    fold: foldSession,
+    finish: finishSession,
+  })
+
+/** Reduce a session's events into its derived state. `session.archived` is
+ * terminal: every fact after it is ignored — the archived state is frozen. */
+export function reduceSession(events: SessionEvent[]): SessionState {
+  return sessionReducer.reduce(events)
+}

package/packages/core/src/store/snapshots.ts

@@ -0,0 +1,88 @@
+/**
+ * Reducer snapshots: a cache beside the event log, never an authority.
+ *
+ * For one scope (a build log or a repository journal) and one registered
+ * reducer, the store may keep that reducer's serialized accumulator as of a
+ * cursor, so a process with no hot memory loads it, reads only the events
+ * newer than the cursor, and advances — instead of replaying the whole log.
+ *
+ * The log always regenerates a snapshot. Every consumer treats a missing,
+ * version-mismatched, ahead-of-log, malformed or unreadable snapshot as a miss
+ * and replays; deleting every snapshot changes no observable output.
+ */
+import { z } from 'zod'
+import type { IncrementalReducer } from '../kernel/incremental'
+import type { BuildStore } from './types'
+
+export type SnapshotScope = { kind: 'build'; slug: string } | { kind: 'repo'; repo: string }
+
+export interface ReducerSnapshot {
+  /** The reducer version that wrote `state`; a reader on another version
+   * ignores the snapshot. */
+  version: number
+  /** The greatest event seq folded into `state`. */
+  cursor: number
+  /** The reducer's JSON accumulator as of `cursor`. */
+  state: unknown
+}
+
+export const reducerSnapshotWireSchema = z.object({
+  version: z.number().int().min(1),
+  cursor: z.number().int().min(0),
+  state: z.unknown(),
+})
+
+/** The registry name a snapshot is keyed by: a short identifier, safe in a URL
+ * path segment and a SQL key. */
+export const SNAPSHOT_REDUCER_NAME = /^[A-Za-z][A-Za-z0-9._-]{0,63}$/
+
+export function snapshotScopeKey(scope: SnapshotScope): string {
+  return scope.kind === 'build' ? `build:${scope.slug}` : `repo:${scope.repo}`
+}
+
+/** Whether a put replaces the stored row. The stored cursor never decreases:
+ * a higher cursor wins whatever the versions, and an upgraded reducer replaces
+ * an older shape at an unchanged cursor. */
+export function snapshotSupersedes(
+  next: Pick<ReducerSnapshot, 'version' | 'cursor'>,
+  stored: Pick<ReducerSnapshot, 'version' | 'cursor'> | undefined,
+): boolean {
+  if (stored === undefined) return true
+  if (next.cursor !== stored.cursor) return next.cursor > stored.cursor
+  return next.version > stored.version
+}
+
+type SnapshotStore = Pick<BuildStore, 'getReducerSnapshot' | 'putReducerSnapshot'>
+
+/** Read a snapshot, degrading every failure to a miss. */
+export async function loadReducerSnapshot(
+  store: Partial<SnapshotStore>,
+  scope: SnapshotScope,
+  name: string,
+  reducer: Pick<IncrementalReducer<unknown, unknown, unknown>, 'version'>,
+): Promise<ReducerSnapshot | null> {
+  if (store.getReducerSnapshot === undefined) return null
+  try {
+    const found = await store.getReducerSnapshot(scope, name, reducer.version)
+    if (found === null || found.version !== reducer.version) return null
+    if (!Number.isInteger(found.cursor) || found.cursor < 0) return null
+    return found
+  } catch {
+    return null
+  }
+}
+
+/** Write a snapshot best-effort; a failing store never reaches the caller. */
+export async function persistReducerSnapshot(
+  store: Partial<SnapshotStore>,
+  scope: SnapshotScope,
+  name: string,
+  snapshot: ReducerSnapshot,
+): Promise<boolean> {
+  if (store.putReducerSnapshot === undefined) return false
+  try {
+    return await store.putReducerSnapshot(scope, name, snapshot)
+  } catch {
+    return false
+  }
+}

package/packages/core/src/store/streams/session-writer.ts

@@ -23,7 +23,6 @@
  * never reorder), retries re-queue at the front under the same discipline,
  * and `close` waits out any in-flight drain before closing the stream.
  */
-import type { SessionStreamSink } from '../../ports/types'
 import { STREAM_PART_MAX_BYTES, truncationPart } from '../../ports/runner/stream-parts'
 import type { JsonRecord } from '../../ports/runner/json-record'
 import {
@@ -52,6 +51,22 @@ export interface SessionStreamSinkOptions {
   schedule?: (flush: () => void, ms: number) => () => void
 }
 
+/** The sink's concrete surface. Structurally a superset of the
+ * `SessionStreamSink` port (ports/types.ts): `open` keeps its port-declared
+ * shape for the build-runner's `openSessionStreamLabel` caller, while the
+ * orchestrator turn runner additionally uses `resume` (bind to an
+ * already-open stream — a resumed invocation must append to the turn's
+ * existing stream, never create a second one) and `flush` (await the drain,
+ * so a step-boundary checkpoint is durable before the next step starts). */
+export type SessionStreamWriter = {
+  open(label: string): Promise<string>
+  append(parts: StreamPart[]): void
+  close(outcome: StreamOutcome): Promise<void>
+} & {
+  resume(streamId: string): Promise<string>
+  flush(): Promise<void>
+}
+
 /** Consecutive failed flushes before the writer stops streaming a session. */
 const MAX_FLUSH_FAILURES = 3
 
@@ -131,8 +146,10 @@ function boundPart(part: StreamPart, maxBytes: number): StreamPart[] {
 /**
  * Create the bracket-scoped sink. `open` creates the store stream and
  * returns its id; appends buffer until then and flush on the cadence.
+ * `resume` binds to an already-open stream instead of creating one;
+ * `flush` awaits the drain without closing.
  */
-export function createSessionStreamSink(options: SessionStreamSinkOptions): SessionStreamSink {
+export function createSessionStreamSink(options: SessionStreamSinkOptions): SessionStreamWriter {
   const { store, scope } = options
   const flushMs = options.flushMs ?? 250
   const maxPartBytes = STREAM_PART_MAX_BYTES
@@ -288,6 +305,29 @@ export function createSessionStreamSink(options: SessionStreamSinkOptions): Sess
       }
     },
 
+    /** Bind to an already-open stream — the resume path. Never calls
+     * `createStream`, so a fresh invocation appends to the turn's existing
+     * stream instead of creating a second one nothing reads. Appends made
+     * before the bind stay buffered and flush right after. */
+    async resume(boundStreamId) {
+      if (streamId !== undefined) {
+        throw new Error(`session stream sink already bound to "${streamId}"`)
+      }
+      streamId = boundStreamId
+      ensureTimer()
+      await requestFlush()
+      return streamId
+    },
+
+    /** Await the drain of everything appended so far (joining the in-flight
+     * drain under the single-flight rule), so a caller can make a checkpoint
+     * durable without closing. Best-effort like `append`: a defunct writer
+     * resolves without throwing, and the diagnostic hook already fired. */
+    async flush() {
+      if (streamId === undefined) return
+      await requestFlush()
+    },
+
     append(parts) {
       // Never throws: after defunct/close or before a successful open,
       // parts are dropped or buffered without surfacing an error.