@defrex/autobuild 0.9.0 → 0.10.0

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

@@ -40,9 +40,10 @@ import {
   type SessionEventWrite,
 } from '../../events/sessions'
 import { createBuildScopedStore } from '../build-scope'
+import type { ReducerSnapshot, SnapshotScope } from '../snapshots'
 import { validateCreatedEvent } from '../new-build'
 import { createSessionScopedStore } from '../session-handle'
-import { DIGEST_EVENT_TYPES, reduceBuildDigest } from '../digest'
+import { DIGEST_EVENT_TYPES, type DigestEventRow, reduceBuildDigest } from '../digest'
 import {
   REPOSITORY_STATE_EVENT_TYPES,
   readRepoStateEventsWithAnchorRecheck,
@@ -135,6 +136,18 @@ import {
 // Exported for the schema-parity test, which pins this DDL against the
 // drizzle schema; schema.ts stays the source of truth, this is its inlined form.
 export const BOOTSTRAP_DDL = [
+  // Reducer snapshots: additive and idempotent, so databases that predate the
+  // table gain it on open.
+  `CREATE TABLE IF NOT EXISTS reducer_snapshots (
+    scope_kind TEXT NOT NULL,
+    scope_key TEXT NOT NULL,
+    reducer TEXT NOT NULL,
+    version INTEGER NOT NULL,
+    cursor INTEGER NOT NULL,
+    state TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    PRIMARY KEY (scope_kind, scope_key, reducer)
+  )`,
   `CREATE TABLE IF NOT EXISTS builds (
     slug TEXT PRIMARY KEY,
     repo TEXT NOT NULL,
@@ -491,7 +504,11 @@ export class SqliteBuildStore implements BuildStore {
     // per build, so the answer cannot drift from `reduceBuild`.
     const rows = this.sqlite
       .query(
-        `SELECT b.slug AS slug, e.seq AS seq, e.ts AS ts, e.type AS type
+        `SELECT b.slug AS slug, e.seq AS seq, e.ts AS ts, e.type AS type,
+                CASE WHEN e.type = 'pr-attachment.reclaimed'
+                  THEN json_extract(e.payload, '$.hostedSeq') END AS hostedSeq,
+                CASE WHEN e.type IN ('execution.started', 'execution.ended')
+                  THEN json_extract(e.payload, '$.instance') END AS instance
          FROM builds b
          LEFT JOIN events e
            ON e.build = b.slug AND e.type IN (${DIGEST_EVENT_TYPES.map(() => '?').join(', ')})
@@ -503,12 +520,20 @@ export class SqliteBuildStore implements BuildStore {
       seq: number | null
       ts: string | null
       type: string | null
+      hostedSeq: number | null
+      instance: string | null
     }[]
-    const eventsByBuild = new Map<string, Pick<AbEvent, 'type' | 'seq' | 'ts'>[]>()
+    const eventsByBuild = new Map<string, DigestEventRow[]>()
     for (const row of rows) {
       if (row.seq === null || row.ts === null || row.type === null) continue
       const events = eventsByBuild.get(row.slug) ?? []
-      events.push({ type: row.type as AbEvent['type'], seq: row.seq, ts: row.ts })
+      events.push({
+        type: row.type as AbEvent['type'],
+        seq: row.seq,
+        ts: row.ts,
+        ...(row.hostedSeq !== null ? { hostedSeq: row.hostedSeq } : {}),
+        ...(row.instance !== null ? { instance: row.instance } : {}),
+      })
       eventsByBuild.set(row.slug, events)
     }
     const digests = new Map<string, BuildDigest>()
@@ -1038,6 +1063,88 @@ export class SqliteBuildStore implements BuildStore {
     })
   }
 
+  async getRepoHighWater(repo: string): Promise<number> {
+    this.requireRepo(repo)
+    const row = this.db
+      .select({ seq: sql<number | null>`max(${repoEvents.seq})` })
+      .from(repoEvents)
+      .where(eq(repoEvents.repo, repo))
+      .get()
+    return row?.seq ?? 0
+  }
+
+  /** The scope's log tail, or `undefined` for a scope that does not exist. */
+  private snapshotTail(scope: SnapshotScope): number | undefined {
+    if (scope.kind === 'build') {
+      const row = this.sqlite
+        .query(
+          'SELECT (SELECT COALESCE(MAX(seq), 0) FROM events WHERE build = ?1) AS tail FROM builds WHERE slug = ?1',
+        )
+        .get(scope.slug) as { tail: number } | null
+      return row?.tail
+    }
+    const row = this.sqlite
+      .query(
+        'SELECT (SELECT COALESCE(MAX(seq), 0) FROM repo_events WHERE repo = ?1) AS tail FROM repo_streams WHERE repo = ?1',
+      )
+      .get(scope.repo) as { tail: number } | null
+    return row?.tail
+  }
+
+  async getReducerSnapshot(
+    scope: SnapshotScope,
+    reducer: string,
+    version: number,
+  ): Promise<ReducerSnapshot | null> {
+    const tail = this.snapshotTail(scope)
+    if (tail === undefined) return null
+    const row = this.sqlite
+      .query(
+        'SELECT version, cursor, state FROM reducer_snapshots WHERE scope_kind = ?1 AND scope_key = ?2 AND reducer = ?3',
+      )
+      .get(scope.kind, scope.kind === 'build' ? scope.slug : scope.repo, reducer) as {
+      version: number
+      cursor: number
+      state: string
+    } | null
+    if (row === null || row.version !== version || row.cursor > tail) return null
+    try {
+      return { version: row.version, cursor: row.cursor, state: JSON.parse(row.state) }
+    } catch {
+      return null
+    }
+  }
+
+  async putReducerSnapshot(
+    scope: SnapshotScope,
+    reducer: string,
+    snapshot: ReducerSnapshot,
+  ): Promise<boolean> {
+    const tail = this.snapshotTail(scope)
+    if (tail === undefined || snapshot.cursor > tail) return false
+    // One statement: the stored cursor never decreases, whatever interleaves.
+    const result = this.sqlite
+      .query(
+        `INSERT INTO reducer_snapshots (scope_kind, scope_key, reducer, version, cursor, state, updated_at)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)
+         ON CONFLICT (scope_kind, scope_key, reducer) DO UPDATE SET
+           version = excluded.version, cursor = excluded.cursor,
+           state = excluded.state, updated_at = excluded.updated_at
+         WHERE excluded.cursor > reducer_snapshots.cursor
+            OR (excluded.cursor = reducer_snapshots.cursor AND excluded.version > reducer_snapshots.version)`,
+      )
+      .run(
+        scope.kind,
+        scope.kind === 'build' ? scope.slug : scope.repo,
+        reducer,
+        snapshot.version,
+        snapshot.cursor,
+        JSON.stringify(snapshot.state ?? null),
+        this.clock().toISOString(),
+      )
+    return result.changes > 0
+  }
+
   async getRepoStateEvents(repo: string): Promise<RepositoryEvent[]> {
     this.requireRepo(repo)
     // Two queries, mirroring the oracle's derivation: the latest

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

@@ -26,6 +26,12 @@ import {
 } from '../events/sessions'
 import { humanActor } from '../events/envelope'
 import { createBuildScopedStore } from './build-scope'
+import {
+  type ReducerSnapshot,
+  type SnapshotScope,
+  snapshotScopeKey,
+  snapshotSupersedes,
+} from './snapshots'
 import { validateCreatedEvent } from './new-build'
 import { createSessionScopedStore } from './session-handle'
 import { reduceBuildDigest } from './digest'
@@ -163,6 +169,8 @@ export class MemoryBuildStore implements BuildStore {
    * stream's close against its appends inside this process (AUT-348). */
   private readonly streamLocks = new StreamLocks()
   private readonly sessions = new Map<string, SessionState>()
+  /** Reducer snapshots (store/snapshots.ts), keyed by scope and reducer name. */
+  private readonly snapshots = new Map<string, ReducerSnapshot>()
   /** `[repo, ticketId, kind, name]` → rows in revision order. A removal is a
    * tombstone row (`removed`, empty manifest) taking the next revision. */
   private readonly ticketAssets = new Map<string, { meta: TicketAssetMeta; removed: boolean }[]>()
@@ -318,7 +326,22 @@ export class MemoryBuildStore implements BuildStore {
     const digests = new Map<string, BuildDigest>()
     for (const slug of slugs) {
       const state = this.builds.get(slug)!
-      digests.set(slug, { slug, ...reduceBuildDigest(state.events) })
+      digests.set(slug, {
+        slug,
+        ...reduceBuildDigest(
+          state.events.map((event) => ({
+            type: event.type,
+            seq: event.seq,
+            ts: event.ts,
+            ...(event.type === 'pr-attachment.reclaimed'
+              ? { hostedSeq: event.payload.hostedSeq }
+              : {}),
+            ...(event.type === 'execution.started' || event.type === 'execution.ended'
+              ? { instance: event.payload.instance }
+              : {}),
+          })),
+        ),
+      })
     }
     return digests
   }
@@ -678,6 +701,50 @@ export class MemoryBuildStore implements BuildStore {
     })
   }
 
+  async getRepoHighWater(repo: string): Promise<number> {
+    return this.repoState(repo).events.at(-1)?.seq ?? 0
+  }
+
+  /** The scope's log tail, or `undefined` for a scope that does not exist. */
+  private snapshotTail(scope: SnapshotScope): number | undefined {
+    const events =
+      scope.kind === 'build'
+        ? this.builds.get(scope.slug)?.events
+        : this.repos.get(scope.repo)?.events
+    return events === undefined ? undefined : (events.at(-1)?.seq ?? 0)
+  }
+
+  async getReducerSnapshot(
+    scope: SnapshotScope,
+    reducer: string,
+    version: number,
+  ): Promise<ReducerSnapshot | null> {
+    const tail = this.snapshotTail(scope)
+    if (tail === undefined) return null
+    const stored = this.snapshots.get(`${snapshotScopeKey(scope)}\u0000${reducer}`)
+    if (stored === undefined || stored.version !== version || stored.cursor > tail) return null
+    return { version: stored.version, cursor: stored.cursor, state: structuredClone(stored.state) }
+  }
+
+  async putReducerSnapshot(
+    scope: SnapshotScope,
+    reducer: string,
+    snapshot: ReducerSnapshot,
+  ): Promise<boolean> {
+    const tail = this.snapshotTail(scope)
+    if (tail === undefined || snapshot.cursor > tail) return false
+    const key = `${snapshotScopeKey(scope)}\u0000${reducer}`
+    if (!snapshotSupersedes(snapshot, this.snapshots.get(key))) return false
+    // The JSON round trip is the stored form every adapter shares, so callers
+    // cannot alias what the store holds.
+    this.snapshots.set(key, {
+      version: snapshot.version,
+      cursor: snapshot.cursor,
+      state: JSON.parse(JSON.stringify(snapshot.state ?? null)),
+    })
+    return true
+  }
+
   async getRepoStateEvents(repo: string): Promise<RepositoryEvent[]> {
     // The oracle runs on the in-memory journal itself, which keeps the pure
     // derivation honest against real adapter data.

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

@@ -8,6 +8,7 @@
  * scope handles in `session-handle.ts` (hosted-only, AUT-339), which scope a
  * store to a single operator session's record.
  */
+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'
@@ -328,6 +329,28 @@ export function scopeLocalStoreToPhaseSession(
       own('getRepoStateEvents', 'repo', repo)
       return store.getRepoStateEvents(repo)
     },
+    async getRepoHighWater(repo: string): Promise<number> {
+      own('getRepoHighWater', 'repo', repo)
+      return store.getRepoHighWater(repo)
+    },
+    async getReducerSnapshot(
+      target: SnapshotScope,
+      reducer: string,
+      version: number,
+    ): Promise<ReducerSnapshot | null> {
+      if (target.kind === 'build') own('getReducerSnapshot', 'build', target.slug)
+      else own('getReducerSnapshot', 'repo', target.repo)
+      return store.getReducerSnapshot(target, reducer, version)
+    },
+    async putReducerSnapshot(
+      target: SnapshotScope,
+      reducer: string,
+      snapshot: ReducerSnapshot,
+    ): Promise<boolean> {
+      if (target.kind === 'build') own('putReducerSnapshot', 'build', target.slug)
+      else own('putReducerSnapshot', 'repo', target.repo)
+      return store.putReducerSnapshot(target, reducer, snapshot)
+    },
     async getRepoBuildDigests(repo: string): Promise<Map<string, BuildDigest>> {
       own('getRepoBuildDigests', 'repo', repo)
       return store.getRepoBuildDigests(repo)

package/packages/core/src/store/remote/client.ts

@@ -46,6 +46,7 @@ import {
 import { createBuildScopedStore } from '../build-scope'
 import { createSessionScopedStore } from '../session-handle'
 import { pollingSubscribe } from '../subscribe'
+import type { ReducerSnapshot, SnapshotScope } from '../snapshots'
 import type { BuildDigest } from '../types'
 import type {
   StreamChunk,
@@ -92,8 +93,11 @@ import {
   eventEnvelopeWireSchema,
   eventListSchema,
   repositoryEventEnvelopeWireSchema,
+  repoHighWaterSchema,
   repositoryEventListSchema,
   okResponseSchema,
+  reducerSnapshotPutResponseSchema,
+  reducerSnapshotResponseSchema,
   placeholderRev,
   repoDepositsResponseSchema,
   repositoryArtifactGetResponseSchema,
@@ -193,7 +197,7 @@ export class RemoteBuildStore implements BuildStore {
   }
 
   private async raw(
-    method: 'GET' | 'POST',
+    method: 'GET' | 'POST' | 'PUT',
     path: string,
     body?: unknown,
     signal?: AbortSignal,
@@ -535,6 +539,51 @@ export class RemoteBuildStore implements BuildStore {
     )
   }
 
+  private snapshotPath(scope: SnapshotScope, reducer: string): string {
+    const root = scope.kind === 'build' ? this.buildPath(scope.slug) : this.repoPath(scope.repo)
+    return `${root}/snapshots/${encodeURIComponent(reducer)}`
+  }
+
+  async getReducerSnapshot(
+    scope: SnapshotScope,
+    reducer: string,
+    version: number,
+  ): Promise<ReducerSnapshot | null> {
+    // Additive routes, no protocol bump. A store that predates them answers
+    // 404 or 405 for the route, which reads as "no snapshot": the caller
+    // replays the log. Auth and transport failures still surface.
+    const response = await this.raw(
+      'GET',
+      `${this.snapshotPath(scope, reducer)}?version=${version}`,
+    )
+    if (response.status === 404 || response.status === 405) return null
+    if (!response.ok) throw await this.toError(response)
+    return reducerSnapshotResponseSchema.parse(await response.json())
+  }
+
+  async putReducerSnapshot(
+    scope: SnapshotScope,
+    reducer: string,
+    snapshot: ReducerSnapshot,
+  ): Promise<boolean> {
+    const response = await this.raw('PUT', this.snapshotPath(scope, reducer), {
+      version: snapshot.version,
+      cursor: snapshot.cursor,
+      state: snapshot.state ?? null,
+    })
+    if (response.status === 404 || response.status === 405) return false
+    if (!response.ok) throw await this.toError(response)
+    return reducerSnapshotPutResponseSchema.parse(await response.json()).written
+  }
+
+  async getRepoHighWater(repo: string): Promise<number> {
+    // Additive route beside `state-events`; the store service and client
+    // ship in version lockstep, so no protocol bump.
+    return this.requestJson('GET', `${this.repoPath(repo)}/high-water`, repoHighWaterSchema).then(
+      (body) => (body as { seq: number }).seq,
+    )
+  }
+
   async getRepoStateEvents(repo: string): Promise<RepositoryEvent[]> {
     // The bounded repository-journal read (AUT-489): one additive route next
     // to `GET events`, reusing the same wire shape. No protocol-version bump

package/packages/core/src/store/remote/index.ts

@@ -20,3 +20,5 @@ export { EventValidationError } from '../../events/catalog'
 export type { Via } from '../../events/envelope'
 export type { SessionEvent, SessionEventWrite } from '../../events/sessions'
 export type { RepositoryEvent, RepositoryEventWrite } from '../../events/repository'
+export { SNAPSHOT_REDUCER_NAME } from '../snapshots'
+export type { ReducerSnapshot, SnapshotScope } from '../snapshots'

package/packages/core/src/store/remote/protocol.ts

@@ -24,6 +24,7 @@
  * Arbitrary computation over the assigned revisions inside `makeEvent`
  * (e.g. `rev + 1`, string interpolation) is unsupported by design.
  */
+import { reducerSnapshotWireSchema } from '../snapshots'
 import { z } from 'zod'
 import { actorSchema } from '../../events/envelope'
 import { ticketRefSchema } from '../../ontology'
@@ -120,6 +121,18 @@ export const repositoryEventEnvelopeWireSchema = z.object({
 })
 export const repositoryEventListSchema = z.array(repositoryEventEnvelopeWireSchema)
 
+/** `GET repos/:repo/high-water`: the journal's greatest assigned seq. */
+export const repoHighWaterSchema = z.object({ seq: z.number().int().nonnegative() })
+
+/** `GET builds|repos/:id/snapshots/:reducer?version=N`: the snapshot or `null`. */
+/** `PUT …/snapshots/:reducer` request body. */
+export const reducerSnapshotPutBodySchema = reducerSnapshotWireSchema
+
+export const reducerSnapshotResponseSchema = reducerSnapshotWireSchema.nullable()
+
+/** `PUT builds|repos/:id/snapshots/:reducer`: whether the row was written. */
+export const reducerSnapshotPutResponseSchema = z.object({ written: z.boolean() })
+
 export const repositoryArtifactMetaWireSchema = z.object({
   repo: z.string(),
   kind: z.string(),
@@ -272,6 +285,8 @@ export const buildDigestWireSchema = z.object({
     }),
   ),
   merged: z.string().min(1).optional(),
+  reclaimPending: z.literal(true).optional(),
+  executionOpen: z.literal(true).optional(),
 })
 export const buildDigestListSchema = z.array(buildDigestWireSchema)
 

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

@@ -47,6 +47,7 @@
  * 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,
@@ -120,6 +121,76 @@ export async function readRepoStateEventsWithAnchorRecheck(
   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
@@ -130,11 +201,5 @@ export async function readRepoStateEventsWithAnchorRecheck(
 export function projectRepositoryStateEvents(
   events: readonly RepositoryEvent[],
 ): RepositoryEvent[] {
-  let anchor: number | undefined
-  for (const event of events) {
-    if (event.type === RUN_STARTED) anchor = event.seq
-  }
-  return events.filter(
-    (event) => STATE_TYPES.has(event.type) || (anchor !== undefined && event.seq >= anchor),
-  )
+  return repositoryStateEventsReducer.reduce(events)
 }

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'
@@ -171,6 +172,35 @@ export function createSessionScopedStore(store: BuildStore, scope: string): Sess
     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))
     },

package/packages/core/src/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'
@@ -62,17 +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> = {}
-  let journalWakeCursor = 0
+/** 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
+}
+
+/** Bump when `SessionAcc`'s shape or fold semantics change. */
+export const SESSION_REDUCER_VERSION = 1
 
-  const open = (): TurnEntry | undefined => turns.findLast((turn) => !isTerminal(turn.state))
+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
@@ -166,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.
@@ -202,3 +222,24 @@ export function reduceSession(events: SessionEvent[]): SessionState {
     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)
+}