spexcode 0.6.1 → 0.6.2

package/spec-eval/src/scenariofresh.ts

@@ -161,7 +161,7 @@ function oidAt(root: string, rev: string, path: string): string {
 
 // @@@ the memo holds SETTLED oids, so concurrent askers need a flight to join - primes run concurrently
 // across the whole scope, and every one of them missed the memo while the first child was still running:
-// measured on z-code's 415-node scope, 2695 `rev-parse` children resolved 1212 distinct (rev, path) pairs.
+// measured on adopter-a's 415-node scope, 2695 `rev-parse` children resolved 1212 distinct (rev, path) pairs.
 // `rev:path` under a full sha names an immutable object, so joining answers the same question; the LRU
 // write still happens once, on settle, exactly as the sync path does it.
 const oidFlight = new Map<string, Promise<string>>()
@@ -189,7 +189,7 @@ async function oidAtAsync(root: string, rev: string, path: string): Promise<stri
 // will ask about and TWO children answer them all: `cat-file --batch-check` for the object ids, then
 // `cat-file --batch` for the blobs. The singular form below is one demand's worth of the same thing, kept
 // for callers that genuinely learn their demand one at a time. Priming one at a time is what this replaces:
-// on z-code's 415-node scope it forked 1212 `rev-parse` children plus a `cat-file` each, and the batch
+// on adopter-a's 415-node scope it forked 1212 `rev-parse` children plus a `cat-file` each, and the batch
 // answers the identical set — same oids, same blocks, same verdicts, two children.
 export async function primeScenarioBlocks(root: string, demands: readonly { rev: string; path: string }[]): Promise<void> {
   const wanted = new Map<string, { rev: string; path: string }>()

package/spec-eval/src/sessioneval.ts

@@ -13,6 +13,8 @@ import {
   driftIndex,
   historyIndex,
   treeTextFiles,
+  withEventLedgerBuild,
+  withEventLedgerDemand,
   type DriftIndex,
   type DriftPathEvent,
   type ReviewDiffFile,
@@ -121,7 +123,7 @@ type LoadedSpec = Awaited<ReturnType<typeof loadSpecs>>[number]
 async function impactGit(root: string, args: string[], operation: string): Promise<string> {
   const result = await gitTry(['-C', root, ...args])
   if (!result.ok) {
-    const detail = result.stderr.trim() || `${result.failure ?? 'git'} failure`
+    const detail = result.failure ? `${result.failure} failure${result.stderr.trim() ? `: ${result.stderr.trim()}` : ''}` : result.stderr.trim() || 'git failure'
     throw new SessionImpactUnavailableError(`session impact cannot ${operation}: ${detail}`)
   }
   return result.stdout
@@ -130,7 +132,7 @@ async function impactGit(root: string, args: string[], operation: string): Promi
 async function impactIndexGit(root: string, indexFile: string, args: string[], operation: string): Promise<string> {
   const result = await gitTry(['-C', root, ...args], { indexFile })
   if (!result.ok) {
-    const detail = result.stderr.trim() || `${result.failure ?? 'git'} failure`
+    const detail = result.failure ? `${result.failure} failure${result.stderr.trim() ? `: ${result.stderr.trim()}` : ''}` : result.stderr.trim() || 'git failure'
     throw new SessionImpactUnavailableError(`session impact cannot ${operation}: ${detail}`)
   }
   return result.stdout
@@ -798,14 +800,23 @@ export type ExportModel = {
 
 // null when no session has that id (route → 404).
 export async function buildExportModel(id: string): Promise<ExportModel | null> {
-  const payload = await reviewPayload(id)
-  if (!payload) return null
+  const identity = reviewIdentity(id)
+  if (!identity) return null
   // root EVERYTHING at the SESSION's worktree — readings, freshness, AND the spec tree itself. The
   // worktree's .spec is the branch's pending proposal ([[source-of-truth]]): a node the branch ADDED
   // exists only there, so a trunk-rooted loadSpecs would silently drop it from the model (the 0fca
   // family's node-existence layer). No worktree → the backend checkout, unchanged.
-  const wtPath = worktreePathForBranch(payload.branch)
+  const wtPath = worktreePathForBranch(identity.branch)
   const ctxRoot = wtPath ?? repoRoot()
+  return withEventLedgerDemand(ctxRoot, async () => {
+    const payload = await reviewPayload(id)
+    return payload
+      ? withEventLedgerBuild(ctxRoot, () => buildExportModelInLedger(id, payload, wtPath, ctxRoot))
+      : null
+  })
+}
+
+async function buildExportModelInLedger(id: string, payload: ReviewPayloadValue, wtPath: string | null, ctxRoot: string): Promise<ExportModel> {
   const specs = await loadSpecs(ctxRoot)
   const specById = new Map(specs.map((s) => [s.id, s]))
   const [didx, hidx] = await Promise.all([driftIndex(ctxRoot), historyIndex(ctxRoot)])
@@ -1425,11 +1436,6 @@ export type SessionEvals = {
   // rather than publishing a fold over the window. `evalRevision.content` is the stronger identity anyway:
   // equal content revision IS the same evaluation cut, so a consumer fencing on it needs no counts.
   summary?: SessionEvalSummary
-  // the LIST page's chrome, and only its. A focused build renders no gates strip and no branch counters, so
-  // it does not buy them — see `order` below for what marks such a model partial.
-  gates?: ExportGate[]
-  ahead?: number
-  dirtyNonRuntime?: number
   evalRevision: SessionEvalRevision
   // present ONLY on a focused build: the whole population's identity+sequence facts, because `nodes` then
   // holds just the few the response will render. Its presence is exactly what marks a model as PARTIAL —
@@ -1618,13 +1624,23 @@ type SessionEvalModel = Omit<SessionEvals, 'summary' | 'evalRevision'>
 
 async function buildSessionEvalModel(
   id: string,
-  payload: ReviewPayloadValue | ReviewIdentity,
+  identity: ReviewIdentity,
   wtPath: string | null,
   pick?: SessionEvalFocus,
 ): Promise<SessionEvalModel> {
   // spec tree from the session worktree, same root as readings/indexes — a branch-NEW node must exist
   // in this model or the Eval tab/deep link can never reach its readings (see buildExportModel above).
   const ctxRoot = wtPath ?? repoRoot()
+  return withEventLedgerBuild(ctxRoot, () => buildSessionEvalModelInLedger(id, identity, wtPath, pick, ctxRoot))
+}
+
+async function buildSessionEvalModelInLedger(
+  id: string,
+  identity: ReviewIdentity,
+  wtPath: string | null,
+  pick: SessionEvalFocus | undefined,
+  ctxRoot: string,
+): Promise<SessionEvalModel> {
   const specs = await loadSpecs(ctxRoot)
   const specById = new Map(specs.map((s) => [s.id, s]))
   const [didx, hidx] = await Promise.all([driftIndex(ctxRoot), historyIndex(ctxRoot)])
@@ -1647,14 +1663,12 @@ async function buildSessionEvalModel(
   nodes.sort((a, b) => (b.evals.filter((e) => e.inSession).length - a.evals.filter((e) => e.inSession).length)
     || (b.scenarios.length - a.scenarios.length) || (b.unknownCoverage.length - a.unknownCoverage.length))
 
-  const primary = payload.node && specById.has(payload.node) ? specById.get(payload.node)!.title : null
-  const full = 'gates' in payload ? payload : null
+  const primary = identity.node && specById.has(identity.node) ? specById.get(identity.node)!.title : null
   return {
     id,
-    node: payload.node,
-    branch: payload.branch,
-    title: primary || payload.node || payload.branch || id.slice(0, 8),
-    ...(full ? { ahead: full.ahead, dirtyNonRuntime: full.dirtyNonRuntime, gates: gateRows(full) } : {}),
+    node: identity.node,
+    branch: identity.branch,
+    title: primary || identity.node || identity.branch || id.slice(0, 8),
     nodes,
     impact,
     ...(order ? { order } : {}),
@@ -1728,13 +1742,6 @@ type SummaryBuildResult =
 
 export type SessionEvalSummaryBuilder = (id: string, path: string) => Promise<SummaryBuildResult>
 
-type DemandJob<T> = {
-  id: string
-  run: () => Promise<T>
-  resolve: (value: T) => void
-  reject: (error: unknown) => void
-}
-
 type ProjectionEntry = {
   id: string
   path: string
@@ -1744,6 +1751,7 @@ type ProjectionEntry = {
   current?: { generation: number; revision: string; value: SessionEvalSummary }
   scheduled: number | null
   running: number | null
+  flight: Promise<void> | null
   demandCancelledGeneration: number | null
   observerHolds: Set<string>
 }
@@ -1758,27 +1766,16 @@ type ProjectionCohortRow = Pick<StagedProjection, 'entry' | 'generation'>
 
 type ProjectionTarget = 'all' | { id?: string; path?: string }
 
-// Summary builds touch a session worktree's diff, history, and eval sidecars. Running one job per row
-// multiplies those git children and their parsed indexes by the retained session count, so the shared
-// projection queue has one bounded capacity for every project. A deployment can tune the capacity, but the
-// default is deliberately serial: board assembly remains responsive and memory has a natural settle point.
-const configuredProjectionConcurrency = Number(process.env.SPEXCODE_SESSION_EVAL_CONCURRENCY || 1)
-const PROJECTION_CONCURRENCY = Number.isFinite(configuredProjectionConcurrency)
-  ? Math.max(1, Math.floor(configuredProjectionConcurrency))
-  : 1
-
-// Pure generation coordinator around an injected stable builder. Snapshot construction only serializes
-// entries and authorizes the newest dirty generations; the async batch runs after that snapshot has captured
-// `updating(lastKnown)`, then emits one completion nudge for all stable/error results in the batch.
+// Pure generation coordinator around an injected stable builder. Sessions have independent evaluation cuts,
+// so an entry launches and publishes independently; generation/revision fences remain per entry.
 export class SessionEvalProjectionCache {
   readonly epoch: string
   private readonly entries = new Map<string, ProjectionEntry>()
   private readonly observerHolds = new Map<string, ProjectionTarget>()
   private readonly observerWaiters = new Set<() => void>()
-  private batch: Promise<void> | null = null
+  private readonly flights = new Set<Promise<void>>()
   private notify: () => void
   private precompute: boolean
-  private readonly demandQueue: DemandJob<any>[] = []
   private readonly demands = new Map<string, Promise<unknown>>()
 
   constructor(
@@ -1806,7 +1803,7 @@ export class SessionEvalProjectionCache {
       }
       this.authorize(entry)
     }
-    if (enabled) queueMicrotask(() => this.startBatch())
+    if (enabled) queueMicrotask(() => this.startScheduled())
   }
 
   private authorize(entry: ProjectionEntry): void {
@@ -1831,6 +1828,7 @@ export class SessionEvalProjectionCache {
       phase: 'loading',
       scheduled: null,
       running: null,
+      flight: null,
       demandCancelledGeneration: null,
       observerHolds: new Set(),
     }
@@ -1854,6 +1852,7 @@ export class SessionEvalProjectionCache {
           phase: 'loading',
           scheduled: null,
           running: null,
+          flight: null,
           demandCancelledGeneration: null,
           observerHolds: new Set(),
         }
@@ -1873,7 +1872,7 @@ export class SessionEvalProjectionCache {
       this.authorize(entry)
       out.set(session.id, this.project(entry))
     }
-    queueMicrotask(() => this.startBatch())
+    queueMicrotask(() => this.startScheduled())
     return out
   }
 
@@ -1951,28 +1950,31 @@ export class SessionEvalProjectionCache {
     const existing = this.demands.get(id)
     if (existing) return existing as Promise<T>
     const entry = this.ensureEntry(id, path)
-    // A queued summary for this same generation is superseded by the full demand build. If that demand
-    // rejects, snapshots must not recreate the cancelled eager work until a later invalidation advances g.
-    // A running summary is left alone; the priority job waits for it to settle before taking the slot.
+    // An unstarted summary is superseded by the full demand build. A running summary stays the one flight for
+    // this entry; demand waits for it only, never for unrelated session work.
     if (entry.running == null && entry.scheduled === entry.generation) {
       entry.scheduled = null
       entry.demandCancelledGeneration = entry.generation
     }
-    let resolve!: (value: T) => void
-    let reject!: (error: unknown) => void
-    const promise = new Promise<T>((res, rej) => { resolve = res; reject = rej })
+    const priorFlight = entry.flight
+    const promise = (async () => {
+      if (priorFlight) await priorFlight
+      return run()
+    })()
     this.demands.set(id, promise)
-    this.demandQueue.push({ id, run, resolve, reject })
     promise.finally(() => {
       if (this.demands.get(id) === promise) this.demands.delete(id)
     }).catch(() => {})
-    queueMicrotask(() => this.startBatch())
     return promise
   }
 
   async idle(): Promise<void> {
-    await Promise.resolve()
-    while (this.batch) await this.batch
+    for (;;) {
+      await Promise.resolve()
+      const pending = [...this.flights, ...this.demands.values()]
+      if (!pending.length) return
+      await Promise.allSettled(pending)
+    }
   }
 
   accept(id: string, generation: number, revision: string, value: SessionEvalSummary): boolean {
@@ -2002,64 +2004,57 @@ export class SessionEvalProjectionCache {
     return target === 'all' || target.id === entry.id || target.path === entry.path
   }
 
-  private hasPending(): boolean {
-    return this.demandQueue.length > 0
-      || [...this.entries.values()].some((entry) => entry.scheduled != null && entry.running == null)
-  }
-
-  private publishCohort(staged: StagedProjection[]): boolean {
+  private publish(staged: StagedProjection): boolean {
     let changed = false
-    for (const { entry, generation, result } of staged) {
-      if (this.entries.get(entry.id) !== entry || entry.generation !== generation || entry.observerHolds.size) continue
-      if (result.kind === 'unstable') {
-        entry.generation++
-        entry.phase = 'updating'
-        entry.scheduled = null
-        entry.demandCancelledGeneration = null
-        this.authorize(entry)
-        changed = true
-        continue
-      }
-      if (result.kind === 'missing') {
-        changed = changed || entry.phase !== 'error'
-        entry.phase = 'error'
-        entry.scheduled = null
-        continue
-      }
-      changed = changed || entry.phase !== 'ready' || entry.current?.revision !== result.revision
-      entry.current = { generation, revision: result.revision, value: result.summary }
-      entry.phase = 'ready'
+    const { entry, generation, result } = staged
+    if (this.entries.get(entry.id) !== entry || entry.generation !== generation || entry.observerHolds.size) return false
+    if (result.kind === 'unstable') {
+      entry.generation++
+      entry.phase = 'updating'
+      entry.scheduled = null
+      entry.demandCancelledGeneration = null
+      this.authorize(entry)
+      return true
+    }
+    if (result.kind === 'missing') {
+      changed = entry.phase !== 'error'
+      entry.phase = 'error'
       entry.scheduled = null
+      return changed
     }
+    changed = entry.phase !== 'ready' || entry.current?.revision !== result.revision
+    entry.current = { generation, revision: result.revision, value: result.summary }
+    entry.phase = 'ready'
+    entry.scheduled = null
     return changed
   }
 
-  private startBatch(): void {
-    if (this.batch) return
-    if (!this.hasPending()) return
-    this.batch = (async () => {
-      const demand = this.demandQueue.shift()
-      if (demand) {
-        try { demand.resolve(await demand.run()) }
-        catch (error) { demand.reject(error) }
-        return
-      }
-      // Freeze this finite cohort. Inputs that arrive later remain scheduled for the next batch, so a
-      // busy stream cannot keep a completed cohort unpublished forever.
-      const cohort = [...this.entries.values()]
-        .filter((entry) => entry.scheduled != null && entry.running == null)
-        .map((entry) => ({ entry, generation: entry.scheduled! }))
-      const staged: StagedProjection[] = []
-      for (let offset = 0; offset < cohort.length && !this.demandQueue.length; offset += PROJECTION_CONCURRENCY) {
-        const chunk = cohort.slice(offset, offset + PROJECTION_CONCURRENCY)
-        const results = await Promise.all(chunk.map((row) => this.runEntry(row)))
-        for (const result of results) if (result) staged.push(result)
-      }
-      if (this.publishCohort(staged)) this.notify()
-    })().finally(() => {
-      this.batch = null
-      if (this.hasPending()) this.startBatch()
+  private startScheduled(): void {
+    for (const entry of this.entries.values()) {
+      if (entry.scheduled == null || entry.running != null) continue
+      this.startEntry({ entry, generation: entry.scheduled })
+    }
+  }
+
+  private startEntry(row: ProjectionCohortRow): void {
+    const flight = this.runEntry(row).then((staged) => {
+      if (staged && this.publish(staged)) this.notify()
     })
+    row.entry.flight = flight
+    this.flights.add(flight)
+    void flight.then(
+      () => {
+        this.flights.delete(flight)
+        if (row.entry.flight === flight) row.entry.flight = null
+        queueMicrotask(() => this.startScheduled())
+      },
+      (error) => {
+        this.flights.delete(flight)
+        if (row.entry.flight === flight) row.entry.flight = null
+        console.warn(`spec-eval: session summary runner failed for ${row.entry.id}: ${error instanceof Error ? error.message : String(error)}`)
+        queueMicrotask(() => this.startScheduled())
+      },
+    )
   }
 
   private async runEntry({ entry, generation }: ProjectionCohortRow): Promise<StagedProjection | null> {
@@ -2080,27 +2075,29 @@ export class SessionEvalProjectionCache {
 }
 
 async function buildSummaryAttempt(id: string, _path: string): Promise<SummaryBuildResult> {
-  const payload = await reviewPayload(id)
-  if (!payload) return { kind: 'missing' }
-  const wtPath = worktreePathForBranch(payload.branch)
+  const identity = reviewIdentity(id)
+  if (!identity) return { kind: 'missing' }
+  const wtPath = worktreePathForBranch(identity.branch)
   const ctxPath = wtPath ?? repoRoot()
-  const before = await sessionEvalContentRevision(ctxPath)
-  const cacheKey = `${id}\0${before}`
-  const cached = summaryByContent.get(cacheKey)
-  if (cached) {
+  return withEventLedgerDemand(ctxPath, async () => {
+    const before = await sessionEvalContentRevision(ctxPath)
+    const cacheKey = `${id}\0${before}`
+    const cached = summaryByContent.get(cacheKey)
+    if (cached) {
+      const after = await sessionEvalContentRevision(ctxPath)
+      return before === after
+        ? { kind: 'stable', revision: after, summary: cached.summary }
+        : { kind: 'unstable' }
+    }
+    const model = await buildSessionEvalModel(id, identity, wtPath)
     const after = await sessionEvalContentRevision(ctxPath)
-    return before === after
-      ? { kind: 'stable', revision: after, summary: cached.summary }
-      : { kind: 'unstable' }
-  }
-  const model = await buildSessionEvalModel(id, payload, wtPath)
-  const after = await sessionEvalContentRevision(ctxPath)
-  if (before !== after) return { kind: 'unstable' }
-  const summary = sessionEvalSummary(model.nodes)
-  // Keep one content-addressed stable value per session. Revisions, not elapsed time, decide reuse.
-  // This fold IS the demand's fold, so it deposits the model too and a later open replays it.
-  depositStableCut(id, after, { summary, model })
-  return { kind: 'stable', revision: after, summary }
+    if (before !== after) return { kind: 'unstable' }
+    const summary = sessionEvalSummary(model.nodes)
+    // Keep one content-addressed stable value per session. Revisions, not elapsed time, decide reuse.
+    // This fold IS the demand's fold, so it deposits the model too and a later open replays it.
+    depositStableCut(id, after, { summary, model })
+    return { kind: 'stable', revision: after, summary }
+  })
 }
 
 // ONE content-addressed cut per session, keyed by id + content revision, carrying the summary the graph
@@ -2163,16 +2160,14 @@ export async function awaitSessionEvalProjectionIdle(): Promise<void> { await pr
 // it never deposits — but it still prefers a cached FULL model when one exists, because a complete answer
 // already paid for beats a cheap incomplete one.
 export async function buildSessionEvals(id: string, pick?: SessionEvalFocus): Promise<SessionEvals | null> {
-  // A full model is demand-only, but it still runs through the projection queue. This gives a selected session
-  // priority over unrelated queued summaries without opening a second git/build lane.
+  // A full model is demand-only. It joins its session's current summary flight, but unrelated summaries never
+  // gate this demand; a cached stable cut then replays without re-deriving Git state.
+  const identity = reviewIdentity(id)
+  if (!identity) return null
+  const wtPath = worktreePathForBranch(identity.branch)
+  const ctxPath = wtPath ?? repoRoot()
   for (;;) {
-    const attempt = await projectionCache.demand(id, '', async () => {
-      // a focused open renders no gates strip, so it reads the session's IDENTITY (a free store read)
-      // instead of its review payload (ahead count + dirty scan + merge-tree conflict probe).
-      const payload = pick ? reviewIdentity(id) : await reviewPayload(id)
-      if (!payload) return { kind: 'missing' as const }
-      const wtPath = worktreePathForBranch(payload.branch)
-      const ctxPath = wtPath ?? repoRoot()
+    const attempt = await projectionCache.demand(id, '', () => withEventLedgerDemand(ctxPath, async () => {
       const known = projectionCache.get(id)
       const generation = known?.generation ?? 0
       await awaitObservableInputs(id, ctxPath)
@@ -2194,7 +2189,7 @@ export async function buildSessionEvals(id: string, pick?: SessionEvalFocus): Pr
         if (before !== settled) projectionCache.invalidate({ id })
         return { kind: 'retry' as const }
       }
-      const model = await buildSessionEvalModel(id, payload, wtPath, pick)
+      const model = await buildSessionEvalModel(id, identity, wtPath, pick)
       const after = await sessionEvalContentRevision(ctxPath)
       const current = projectionCache.get(id)
       if (before !== after || projectionCache.isObserverHeld(id, ctxPath)
@@ -2213,8 +2208,7 @@ export async function buildSessionEvals(id: string, pick?: SessionEvalFocus): Pr
       depositStableCut(id, after, { summary, model })
       if (current) projectionCache.accept(id, generation, after, summary)
       return { kind: 'ready' as const, model, summary, generation, revision: after }
-    })
-    if (attempt.kind === 'missing') return null
+    }))
     if (attempt.kind === 'retry') continue
     return {
       ...attempt.model,