spexcode 0.6.1 → 0.6.5

package/spec-cli/src/graphCache.ts

@@ -1,641 +0,0 @@
-import { createHash } from 'node:crypto'
-import { readFileSync, readdirSync, statSync } from 'node:fs'
-import { isAbsolute, join, resolve } from 'node:path'
-import { buildBoard, rebasePublishedSessions, spliceSessions } from './graph.js'
-import { headSha, repoRoot, withGitAbortSignal } from './git.js'
-import { listSessionIds, mainBranch, mainCheckout, readPublicRecordEntry, sessionArtifactPath, sessionRecordPath } from './layout.js'
-import { boardThreads } from './issues.js'
-import { resolveForgeHost } from '../../spec-forge/src/drivers.js'
-import { residentForgeState } from '../../spec-forge/src/resident.js'
-import { resolveProjectIdentity } from './project-identity.js'
-import { readReviewSnapshot } from './reviewSnapshot.js'
-import { sessionEvalProjection } from '../../spec-eval/src/sessioneval.js'
-
-export type Board = Awaited<ReturnType<typeof buildBoard>>
-export type BoardConsistency = 'fresh' | 'stale-ok'
-export type BoardRead = { board: Board; freshness: 'fresh' | 'stale'; refreshing: boolean; error?: string }
-export type BoardJsonRead = BoardRead & { json: string }
-export type RevisionPublication = {
-  revision: () => number
-  invalidate: () => void
-  wait: () => Promise<void>
-}
-
-type BoardInputRevision = {
-  full: string
-  sessions: string
-  projections: string
-  combined: string
-  fullParts: Record<string, string>
-  projectionIds: string[]
-}
-type SessionInputRevision = Pick<BoardInputRevision, 'sessions' | 'projections' | 'projectionIds'>
-const DEBUG = process.env.SPEXCODE_BOARD_DEBUG === '1'
-
-function textOrNull(path: string): string | null {
-  try { return readFileSync(path, 'utf8') }
-  catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
-    throw error
-  }
-}
-
-function gitDirOf(root: string): string {
-  const dotgit = join(root, '.git')
-  try { if (statSync(dotgit).isDirectory()) return dotgit }
-  catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return ''
-    throw error
-  }
-  const dotgitText = textOrNull(dotgit)
-  if (dotgitText === null) return ''
-  const match = dotgitText.match(/^gitdir:\s*(.+)$/m)
-  if (!match) throw new Error(`unparseable gitdir pointer at ${dotgit}`)
-  const dir = match[1].trim()
-  return isAbsolute(dir) ? dir : resolve(root, dir)
-}
-
-function commonDirOf(root: string): string {
-  const gitDir = gitDirOf(root)
-  if (!gitDir) return ''
-  const common = textOrNull(join(gitDir, 'commondir'))
-  if (common === null) return gitDir
-  const dir = common.trim()
-  if (!dir) throw new Error(`empty commondir pointer at ${join(gitDir, 'commondir')}`)
-  return isAbsolute(dir) ? dir : resolve(gitDir, dir)
-}
-
-function refSha(root: string, ref: string): string {
-  if (/^[0-9a-f]{40}$/.test(ref)) return ref
-  const common = commonDirOf(root)
-  if (!common) return '<missing>'
-  const names = ref.startsWith('refs/') ? [ref] : [`refs/heads/${ref}`, `refs/remotes/${ref}`]
-  for (const name of names) {
-    const loose = textOrNull(join(common, name))
-    if (loose !== null) return loose.trim() || '<missing>'
-  }
-  const packed = textOrNull(join(common, 'packed-refs'))
-  if (packed !== null) {
-    for (const line of packed.split('\n')) {
-      if (!line || line[0] === '#' || line[0] === '^') continue
-      const space = line.indexOf(' ')
-      if (space > 0 && names.includes(line.slice(space + 1).trim())) return line.slice(0, space).trim()
-    }
-  }
-  return '<missing>'
-}
-
-function headRevision(root: string): string {
-  if (!gitDirOf(root)) return '<missing>'
-  return headSha(root)
-}
-
-// Patrol validation needs a stronger contract than the overlay cache's best-effort mtime key: ctime catches
-// a same-size edit whose mtime was restored, and every non-ENOENT read failure is loud instead of collapsing an
-// unreadable subtree into a stable "unchanged" revision. A path that vanishes during the sample is represented
-// by its absence and is rechecked by the producer fence.
-function strictSpecTreeRevision(wtPath: string): string {
-  const root = join(wtPath, '.spec')
-  try { statSync(root) }
-  catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return ''
-    throw error
-  }
-  const parts: string[] = []
-  const stack = [root]
-  while (stack.length) {
-    const dir = stack.pop()!
-    let entries
-    try { entries = readdirSync(dir, { withFileTypes: true }) }
-    catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
-      continue
-    }
-    for (const entry of entries) {
-      const path = join(dir, entry.name)
-      if (entry.isDirectory()) { stack.push(path); continue }
-      try {
-        const stat = statSync(path)
-        parts.push(`${path}:${stat.mtimeMs}:${stat.ctimeMs}:${stat.size}`)
-      } catch (error) {
-        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
-      }
-    }
-  }
-  return parts.sort().join('\n')
-}
-
-function worktreeRevision(root: string): unknown {
-  return {
-    root,
-    head: headRevision(root),
-    spec: strictSpecTreeRevision(root),
-  }
-}
-
-function digest(value: unknown): string {
-  return createHash('sha256').update(JSON.stringify(value)).digest('hex')
-}
-
-// The patrol's cheap authority check. These are exactly the mutable inputs a board assembly reads, folded
-// without doing the assembly: HEAD/config + `.spec`, governed records and active governed worktree state,
-// the issue-store carrier, and the already-resident session-eval projections. It intentionally does not call
-// listSessions or sessionEvalProjections: verification must neither poll tmux again nor mint/schedule eval work.
-// The hot/warm liveness signatures and eval generations remain graph-stream's canonical event-owned axes.
-function sessionInputRevision(): SessionInputRevision {
-  const ids = listSessionIds().sort()
-  // listSessions projects both the structured record and the separately-stored originating prompt into each
-  // board row. Fold both exact artifacts so a missed store event cannot leave a stale label/prompt forever.
-  const sessionInputs = ids.map((id) => [
-    id,
-    textOrNull(sessionRecordPath(id)),
-    textOrNull(sessionArtifactPath(id, 'prompt')),
-  ] as const)
-  const projections = digest(ids.map((id) => [id, sessionEvalProjection(id)]))
-  return { sessions: digest(sessionInputs), projections, projectionIds: ids }
-}
-
-function boardInputRevision(board: Board | null): BoardInputRevision {
-  const root = repoRoot()
-  const session = sessionInputRevision()
-  const records = listSessionIds().map(readPublicRecordEntry).flatMap((entry) => entry.kind === 'ok' ? [entry.raw] : [])
-  const governed = records.filter((record) => record.governed).sort((a, b) => a.session_id.localeCompare(b.session_id))
-  const activeRoots = [...new Set(governed.filter((record) => !record.archived).map((record) => record.worktree_path))].sort()
-  const main = mainCheckout()
-  const base = mainBranch()
-  const mainTip = refSha(main, base)
-  const nodeIds = (board?.nodes ?? []).map((node) => node.id)
-  const issuesStamp = boardThreads({ host: resolveForgeHost(), state: residentForgeState() }, nodeIds).stamp
-  const fullInputs = {
-    root: worktreeRevision(root),
-    config: [
-      [join(root, 'spexcode.json'), textOrNull(join(root, 'spexcode.json'))],
-      [join(root, 'spexcode.local.json'), textOrNull(join(root, 'spexcode.local.json'))],
-      [join(main, 'spexcode.json'), textOrNull(join(main, 'spexcode.json'))],
-      [join(main, 'spexcode.local.json'), textOrNull(join(main, 'spexcode.local.json'))],
-    ],
-    main: { root: main, branch: base, tip: mainTip },
-    worktrees: activeRoots.map((worktree) => worktreeRevision(worktree)),
-    issuesStamp,
-    identity: resolveProjectIdentity(root, root),
-  }
-  const fullParts = Object.fromEntries(Object.entries(fullInputs).map(([key, value]) => [key, digest(value)]))
-  const full = digest(fullParts)
-  return {
-    full,
-    ...session,
-    combined: digest([full, session.sessions, session.projections]),
-    fullParts,
-  }
-}
-
-// Bind an input sample to what the completed board actually carries. The sample supplies the graph/session
-// revision observed immediately after the producer; issue and projection values come from the returned board
-// itself. Re-reading all inputs here would create a certification race: a blind change after the producer's
-// after-sample could otherwise be mistaken for an input the already-built board contains.
-function revisionCarriedByBoard(sample: BoardInputRevision, board: Board): BoardInputRevision {
-  const fullParts = { ...sample.fullParts, issuesStamp: digest(board.issuesStamp) }
-  const full = digest(fullParts)
-  const boardProjections = new Map(board.sessions.map((session) => [session.id, session.evalSummary ?? null]))
-  const projections = digest(sample.projectionIds.map((id) => [id, boardProjections.get(id) ?? null]))
-  return {
-    full,
-    sessions: sample.sessions,
-    projections,
-    combined: digest([full, sample.sessions, projections]),
-    fullParts,
-    projectionIds: sample.projectionIds,
-  }
-}
-
-// A sessions splice reuses its base topology. It may sample fresh record/projection inputs, but it must never
-// certify that those old nodes carry a full revision sampled after the base was built.
-function revisionCarriedBySessionSplice(base: BoardInputRevision, sample: SessionInputRevision, board: Board, stable: boolean): BoardInputRevision {
-  const boardProjections = new Map(board.sessions.map((session) => [session.id, session.evalSummary ?? null]))
-  const projections = stable
-    ? digest(sample.projectionIds.map((id) => [id, boardProjections.get(id) ?? null]))
-    : sample.projections
-  return {
-    full: base.full,
-    sessions: sample.sessions,
-    projections,
-    combined: digest([base.full, sample.sessions, projections]),
-    fullParts: base.fullParts,
-    projectionIds: sample.projectionIds,
-  }
-}
-
-// The full producer's topology may be newer than the last published session projection. When completion
-// re-bases that already-visible projection onto the new topology, keep the full carrier from the producer and
-// only the sessions/projections carrier from the published rows. Do not sample current inputs here: that would
-// certify a write that neither producer actually carried.
-function revisionCarriedByPublishedSessionRebase(full: BoardInputRevision, published: BoardInputRevision): BoardInputRevision {
-  return {
-    full: full.full,
-    sessions: published.sessions,
-    projections: published.projections,
-    combined: digest([full.full, published.sessions, published.projections]),
-    fullParts: full.fullParts,
-    projectionIds: published.projectionIds,
-  }
-}
-
-// a build slower than this is LOGGED, never silently tolerated — the fail-loud regression alarm. Sized
-// above a warm build (~sub-second once the fs walks yield) but below the cold two-walk first build, so a
-// genuinely-degraded hot path shouts while an ordinary cold start stays quiet-ish.
-const BUDGET_MS = Number(process.env.SPEXCODE_BOARD_BUDGET_MS || 1500)
-
-// a build that NEVER settles is a different animal from a slow one: `inflight` clears only in the finally
-// below, so a never-settling buildBoard() would pin the single-flight forever — every later read (even of a
-// perfectly good cached board) short-circuits into the pinned promise before `valid` is consulted,
-// invalidation can't help, no log ever fires, and only a restart cures it (the live wedge: hung git
-// children → /api/graph 503 forever, silently). So the build races a generous watchdog that REJECTS loudly;
-// the rejection flows through the SAME finally → inflight clears → the next read retries fresh. Sitting at
-// the single-flight boundary, this one wall bounds every never-settle cause — including ones with no child
-// process at all (fs/promises under libuv threadpool starvation); git.ts's per-child timeouts merely make
-// the common cause die sooner. Generous: well above the slowest legitimate cold build, so it only ever
-// fires on a genuine wedge.
-const BUILD_TIMEOUT_MS = Number(process.env.SPEXCODE_BOARD_BUILD_TIMEOUT_MS || 120000)
-const RETRY_BACKOFF_MS = Number(process.env.SPEXCODE_BOARD_RETRY_BACKOFF_MS || 1000)
-const BACKGROUND_START_DELAY_MS = Number(process.env.SPEXCODE_BOARD_BACKGROUND_START_DELAY_MS || 300)
-
-// The structural/full and sessions obligations are deliberately separate. A full build can take seconds;
-// a persisted session row cannot be silently converted into time behind that unrelated topology work.
-type Scope = 'sessions' | 'full'
-let cached: Board | null = null   // last completed build; served while `dirty === 'none'`
-let cachedJson: string | null = null   // JSON.stringify(cached), serialized ONCE per build (see getBoardJson)
-let cachedRevision: BoardInputRevision | null = null // input revision represented by `cached`
-let dirty: Scope | 'none' = 'full'   // no cached board yet → the first read builds fully
-type Flight = { wait: Promise<Board>; settle: Promise<Board> }
-let inflight: Flight | null = null
-let sessionFlight: Flight | null = null
-let sessionOwed = false
-let sessionGeneration = 0
-let sessionProjectionPublication = 0
-let topologyGeneration = 0
-let gen = 0                       // bumped on invalidation so patrol validation cannot certify across an event
-let retryAt = 0
-let lastFailure: Error | null = null
-
-// mark the cache stale at a SCOPE. Called by every board-stream freshness source (see
-// boardStream.fireChanged), so a real change forces the next getBoard() to rebuild while a quiet poll storm
-// keeps hitting the cache. `dirty` is the structural producer's scope; `sessionOwed` is intentionally not
-// folded into it, because full+sessions owes both a full convergence and a cheap first projection.
-function mergeDirty(scope: Scope): void {
-  if (scope === 'full' || dirty === 'full') dirty = 'full'
-  else dirty = 'sessions'
-}
-
-export function invalidateBoard(scope: Scope = 'full'): void {
-  gen++
-  if (scope === 'sessions') { sessionOwed = true; sessionGeneration++ }
-  mergeDirty(scope)
-  retryAt = 0
-  lastFailure = null
-}
-
-function traceCacheCommit(scope: Scope, startedAt: number): void {
-  if (!DEBUG) return
-  const at = Date.now()
-  console.warn(`spec-cli: graph cache ${JSON.stringify({ at, stage: 'cache-commit', scope, buildMs: at - startedAt })}`)
-}
-
-function startSessionSplice(): Flight | null {
-  if (!cached || !cachedRevision || !sessionOwed) return null
-  if (sessionFlight) return sessionFlight
-  sessionOwed = false
-  if (dirty === 'sessions') dirty = 'none'
-  let timedOut = false
-  const startedAt = Date.now()
-  let watchdog: ReturnType<typeof setTimeout> | undefined
-  const timeoutError = () => new Error(`graph session splice did not settle within ${BUILD_TIMEOUT_MS}ms`)
-  const producer = Promise.resolve().then(async () => {
-    // A full completion may replace the topology while listSessions is in flight. Rebase before publishing;
-    // the splice is a projection over whatever last-good structure is current, never a whole-board write race.
-    while (true) {
-      const base = cached, revision = cachedRevision, generation = topologyGeneration
-      if (!base || !revision) throw new Error('graph session splice lost its cached topology')
-      const before = sessionInputRevision()
-      const board = await spliceSessions(base)
-      const after = sessionInputRevision()
-      if (base !== cached || revision !== cachedRevision || generation !== topologyGeneration) continue
-      const stable = before.sessions === after.sessions && before.projections === after.projections
-      cached = board
-      cachedJson = null
-      cachedRevision = revisionCarriedBySessionSplice(revision, before, board, stable)
-      sessionProjectionPublication++
-      if (!stable) {
-        sessionOwed = true
-        sessionGeneration++
-        mergeDirty('sessions')
-      }
-      return board
-    }
-  })
-    .then((board) => {
-      if (timedOut) throw timeoutError()
-      traceCacheCommit('sessions', startedAt)
-      return board
-    })
-    .catch((error) => {
-      sessionOwed = true
-      mergeDirty('sessions')
-      throw error
-    })
-  let settle!: Promise<Board>
-  settle = producer.finally(() => {
-    clearTimeout(watchdog)
-    if (sessionFlight?.settle === settle) sessionFlight = null
-  })
-  const wait = new Promise<Board>((resolve, reject) => {
-    watchdog = setTimeout(() => {
-      timedOut = true
-      console.warn(`spec-cli: graph session splice did not settle within ${BUILD_TIMEOUT_MS}ms`)
-      reject(timeoutError())
-    }, BUILD_TIMEOUT_MS)
-    watchdog.unref?.()
-    settle.then((board) => { if (!timedOut) resolve(board) }, (error) => { if (!timedOut) reject(error) })
-  })
-  const flight = { wait, settle }
-  sessionFlight = flight
-  void wait.catch(() => {})
-  void settle.catch(() => {})
-  return flight
-}
-
-// One flight owns BOTH validation and a producer. Every refresh — patrol or watcher-signalled — first folds
-// the cheap input revision; an exact match resolves to `cached` without calling either producer. A mismatch
-// derives the changed domain and falls through to the build path. An invalidation during validation also falls
-// through under this flight, so validation can never race a second producer into existence. `mode` no longer
-// selects who validates; it only says whether a stale HTTP response is waiting for a turn to flush first.
-type FlightMode = 'dirty' | 'patrol'
-function startBuild(mode: FlightMode = 'dirty'): Flight | null {
-  if (inflight) return inflight
-  if (Date.now() < retryAt) return null
-  const controller = new AbortController()
-  let watchdog: ReturnType<typeof setTimeout> | undefined
-  let timedOut = false
-  let built = false
-  let buildStartedAt = 0
-  let buildScope: Scope = 'full'
-  let buildFullStable = true
-  let buildSessionsStable = true
-  let buildSessionGeneration = sessionGeneration
-  let buildSessionProjectionPublication = sessionProjectionPublication
-  let buildStartedWithSessionOwed = false
-  let completedRevision: BoardInputRevision | null = null
-  // Do not invoke the producer inline. buildBoard() has an asynchronous signature but performs a sizeable
-  // synchronous setup before its first await (Promise.all evaluates its arguments immediately). A stale HTTP
-  // caller must be able to return its last-good bytes before that setup runs; first-cold/fresh callers still
-  // await the same deferred promise below.
-  let resolveBuild!: (board: Board) => void
-  let rejectBuild!: (error: unknown) => void
-  const build = new Promise<Board>((resolve, reject) => {
-    resolveBuild = resolve
-    rejectBuild = reject
-  })
-  // Give a stale HTTP response a turn to flush before the producer's synchronous setup occupies the event
-  // loop. Fresh callers simply absorb this small scheduling window while waiting on the same flight.
-  setTimeout(() => {
-    if (controller.signal.aborted) {
-      rejectBuild(Object.assign(new Error('graph build aborted before start'), { name: 'AbortError' }))
-      return
-    }
-    try {
-      Promise.resolve(withGitAbortSignal(controller.signal, async () => {
-        const prev = cached
-        const anchor = cachedRevision
-        const sampledGen = gen
-        const before = await boardInputRevision(prev)
-        if (controller.signal.aborted)
-          throw Object.assign(new Error('graph build aborted before producer start'), { name: 'AbortError' })
-        // ONE rule for every refresh: the domain a producer runs is DERIVED from the inputs that actually
-        // moved, never assigned by whoever signalled. A watcher names the leaf it saw, not what the board
-        // reads — a generated harness artifact rewritten inside a live worktree, or a linked worktree no
-        // governed record names, moves no board input at all, and used to buy a whole structural assembly
-        // anyway. The revision sampled here is the complete full-domain contract, so an unmoved full
-        // obligation is DISCHARGED without assembly. The session projection is deliberately NOT
-        // dischargeable: liveness lives on graph-stream's poller axis, outside this revision, so a claimed
-        // sessions obligation always survives and takes its splice. A sample taken after the write is what
-        // the watcher event was about; an invalidation arriving after the sample keeps its own dirty window.
-        if (prev && anchor && gen === sampledGen) {
-          const fullMoved = before.full !== anchor.full
-          const projectionMoved = before.sessions !== anchor.sessions || before.projections !== anchor.projections
-          // A projection move nobody signalled is this validation doing the patrol's repair job.
-          if (projectionMoved && !sessionOwed && dirty !== 'sessions') {
-            gen++
-            sessionOwed = true
-            sessionGeneration++
-          }
-          const owed = fullMoved ? 'full' : (sessionOwed || dirty === 'sessions') ? 'sessions' : 'none'
-          if (DEBUG && owed !== 'none') {
-            const moved = Object.keys(before.fullParts).filter((key) => before.fullParts[key] !== anchor.fullParts[key])
-            console.warn(`spec-cli: graph refresh revision moved — signalled=${dirty} scope=${owed} inputs=[${moved.join(', ')}]`)
-          } else if (DEBUG && dirty !== 'none') {
-            console.warn(`spec-cli: graph refresh discharged a ${dirty} signal — no board input moved`)
-          }
-          if (fullMoved) dirty = 'full'
-          else if (sessionOwed || dirty === 'sessions') dirty = 'sessions'
-          // Discharging CONSUMES the claim. Leaving it standing would make every later read re-enter this
-          // validation, hold the board permanently stale/refreshing, and never converge.
-          else { dirty = 'none'; return prev }
-        }
-        const sessionsOnly = dirty === 'sessions' && prev !== null
-        buildScope = sessionsOnly ? 'sessions' : 'full'
-        // Consume the scope this producer is satisfying. Invalidation after this point starts a NEW dirty
-        // window with its own domain: a session completion during a long full build owes one splice, not
-        // another full build. The occupied `inflight` slot keeps fresh/stale readers joined while dirty is clean.
-        dirty = 'none'
-        if (sessionsOnly) sessionOwed = false
-        built = true
-        buildSessionGeneration = sessionGeneration
-        buildSessionProjectionPublication = sessionProjectionPublication
-        buildStartedWithSessionOwed = sessionOwed
-        buildStartedAt = Date.now()
-        const board = await (sessionsOnly ? spliceSessions(prev!) : buildBoard())
-        const after = await boardInputRevision(prev)
-        const movedFull = Object.keys(after.fullParts)
-          .filter((key) => after.fullParts[key] !== before.fullParts[key])
-        // The first build can initialize the resident forge carrier that it then returns. That movement is
-        // stable only when the finished board carries the after-sample's exact issue stamp. Every other cold
-        // movement remains dirty just like a warm one; cold start is not a blanket race exemption.
-        const coldIssueInitialization = prev === null
-          && movedFull.every((key) => key === 'issuesStamp')
-          && after.fullParts.issuesStamp === digest(board.issuesStamp)
-        buildFullStable = before.full === after.full || coldIssueInitialization
-        buildSessionsStable = before.sessions === after.sessions
-        if (DEBUG && (!buildFullStable || !buildSessionsStable)) {
-          console.warn(`spec-cli: graph inputs moved during ${buildScope} producer — next=${buildFullStable ? 'sessions' : 'full'} inputs=[${movedFull.join(', ')}] sessions=${buildSessionsStable ? 'stable' : 'moved'}`)
-        }
-        // The anchor must name the sample this board is KNOWN to have read, because validation now discharges
-        // an unmoved obligation for every refresh, not only the patrol's. An input that moved DURING the
-        // producer leaves the board built from the pre-move value while the after-sample already names the
-        // post-move one; anchoring on `after` would let the next validation discharge the re-owed dirty scope
-        // against a revision this board never carried, and the cache would converge on nothing. So a moved
-        // half anchors on `before` — the conservative direction, which costs at most one extra rebuild and can
-        // never certify unread bytes.
-        completedRevision = revisionCarriedByBoard(buildFullStable && buildSessionsStable ? after : before, board)
-        return board
-      }))
-        .then(resolveBuild, rejectBuild)
-    } catch (error) {
-      rejectBuild(error)
-    }
-  }, mode === 'patrol' ? 0 : BACKGROUND_START_DELAY_MS).unref?.()
-  const timeoutError = () => new Error(`graph build did not settle within ${BUILD_TIMEOUT_MS}ms`)
-
-  // `settle` owns the real builder. The watchdog only rejects `wait`; the slot remains occupied until this
-  // promise settles, so a next read can never overlap an abandoned git/fs build.
-  let settle!: Promise<Board>
-  settle = build.then(async (board) => {
-    if (timedOut) throw timeoutError()
-    if (built) {
-      // A full build's session snapshot may predate a session projection that clients already saw. Rebase those
-      // published rows in memory on the new topology. This completion path must stay bounded: a later/unpublished
-      // session generation remains owed to the independent cheap splice rather than making full wait for quiet.
-      const publishedDuringBuild = sessionProjectionPublication !== buildSessionProjectionPublication
-      if (buildScope === 'full' && publishedDuringBuild && cached && cachedRevision) {
-        board = rebasePublishedSessions(board, cached)
-        completedRevision = revisionCarriedByPublishedSessionRebase(completedRevision!, cachedRevision)
-      }
-      const sessionStillOwed = sessionOwed || (!publishedDuringBuild && (
-        buildStartedWithSessionOwed || !buildSessionsStable || buildSessionGeneration !== sessionGeneration
-      ))
-      if (sessionStillOwed) {
-        sessionOwed = true
-        mergeDirty('sessions')
-      }
-      cached = board
-      cachedJson = null
-      cachedRevision = completedRevision
-      if (buildScope === 'full') topologyGeneration++
-      else sessionProjectionPublication++
-      if (!buildFullStable) mergeDirty('full')
-      traceCacheCommit(buildScope, buildStartedAt)
-    }
-    retryAt = 0
-    lastFailure = null
-    return board
-  }).catch((error) => {
-    const failure = error instanceof Error ? error : new Error(String(error))
-    if (built) mergeDirty(buildScope)
-    lastFailure = failure
-    retryAt = Date.now() + RETRY_BACKOFF_MS
-    console.warn(`spec-cli: /api/graph build failed — ${failure.message}`)
-    throw failure
-  }).finally(() => {
-    clearTimeout(watchdog)
-    if (inflight?.settle === settle) inflight = null
-    const ms = built ? Date.now() - buildStartedAt : 0
-    if (built && ms > BUDGET_MS)
-      console.warn(`spec-cli: /api/graph build took ${ms}ms (budget ${BUDGET_MS}ms) — ${buildScope} path is slow`)
-  })
-
-  const wait = new Promise<Board>((resolve, reject) => {
-    watchdog = setTimeout(() => {
-      timedOut = true
-      console.warn(`spec-cli: /api/graph build did not settle within ${BUILD_TIMEOUT_MS}ms — aborting the single-flight build`)
-      controller.abort()
-      reject(timeoutError())
-    }, BUILD_TIMEOUT_MS)
-    watchdog.unref?.()
-    settle.then((board) => {
-      if (!timedOut) resolve(board)
-    }, (error) => {
-      if (!timedOut) reject(error)
-    })
-  })
-  const flight = { wait, settle }
-  inflight = flight
-  // Background stale readers intentionally do not await these promises. Observe both rejection paths so a
-  // failed build is loud without becoming an unhandled rejection.
-  void wait.catch(() => {})
-  void settle.catch(() => {})
-  return flight
-}
-
-export function getBoard(): Promise<Board> {
-  // A clean-looking cache can be under patrol validation. Fresh readers join that flight before taking the
-  // cache fast path, otherwise one can return stale bytes while the flight is discovering a missed change.
-  if (inflight) return inflight.wait
-  if (dirty === 'full') {
-    const flight = startBuild('dirty')
-    if (flight) return flight.wait
-  }
-  if (sessionFlight) return sessionFlight.wait
-  if (dirty === 'none' && cached) return Promise.resolve(cached)
-  const flight = startBuild('dirty')
-  if (flight) return flight.wait
-  return Promise.reject(lastFailure ?? new Error('graph build retry is temporarily backing off'))
-}
-
-export async function waitForPublishedRevision(required: number, publication: RevisionPublication): Promise<void> {
-  while (publication.revision() < required) {
-    publication.invalidate()
-    await publication.wait()
-  }
-}
-
-// A board flight can have captured a resident forge slice before its reconcile publishes a newer revision.
-// That older flight may settle, but cannot discharge this request: its invalidation stays owed and the fence
-// consumes the next publication instead of letting a fresh /api/issues read return the old review snapshot.
-export async function getBoardForForgeRevision(required: number): Promise<Board> {
-  await waitForPublishedRevision(required, {
-    revision: () => readReviewSnapshot().forgeRevision,
-    invalidate: () => invalidateBoard('full'),
-    wait: async () => {
-      const current = inflight
-      if (current) await current.settle
-      else await getBoard()
-    },
-  })
-  return cached ?? getBoard()
-}
-
-// Delta delivery may choose the sessions obligation while a route-owned full is still in flight. Starting
-// the full first preserves structural convergence; returning the splice first keeps the lifecycle surface live.
-export function getBoardForSessionRefresh(): Promise<Board> {
-  if (cached && sessionOwed) {
-    if (!inflight && dirty === 'full') startBuild('dirty')
-    const flight = startSessionSplice()
-    if (flight) return flight.wait
-  }
-  return getBoard()
-}
-
-// The delta-gated cold tick calls this instead of invalidating. Equal inputs resolve to the cached object;
-// changed inputs repair through the same flight and full producer as a watcher-owned invalidation.
-export function patrolBoard(): Promise<Board> {
-  if (!cached) return getBoard()
-  const flight = startBuild('patrol')
-  if (flight) return flight.wait
-  return Promise.reject(lastFailure ?? new Error('graph patrol retry is temporarily backing off'))
-}
-
-export async function readBoard(consistency: BoardConsistency = 'fresh'): Promise<BoardRead> {
-  if (consistency === 'stale-ok' && cached) {
-    const stale = dirty !== 'none' || inflight !== null || sessionFlight !== null || sessionOwed
-    // A held session splice already owns this refresh. Returning stale bytes must not manufacture a full
-    // producer beside it; a real full obligation still starts its one structural producer independently.
-    const flight = inflight
-      ?? (dirty === 'full' ? startBuild('dirty') : null)
-      ?? sessionFlight
-      ?? (sessionOwed ? startSessionSplice() : null)
-      ?? (dirty === 'sessions' ? startBuild('dirty') : null)
-    return { board: cached, freshness: stale ? 'stale' : 'fresh', refreshing: !!flight, ...(lastFailure ? { error: lastFailure.message } : {}) }
-  }
-  const board = await getBoard()
-  return { board, freshness: 'fresh', refreshing: false }
-}
-
-// the SERIALIZED board for the /api/graph route — JSON.stringify runs ONCE per build, not once per poll,
-// so a poll storm of cache hits costs zero serialization CPU (only the etag hash for the 304 path). The SSE
-// path still takes the object (getBoard) because it decomposes it into delta units ([[graph-delta]]).
-export async function getBoardJson(consistency: BoardConsistency = 'fresh'): Promise<BoardJsonRead> {
-  const result = await readBoard(consistency)
-  const board = result.board
-  if (board === cached && cachedJson !== null) return { ...result, json: cachedJson }
-  const json = JSON.stringify(board)
-  if (board === cached) cachedJson = json   // memoize only the CURRENT build's serialization
-  return { ...result, json }
-}