spexcode 0.5.7 → 0.5.9

package/spec-eval/src/sessioneval.ts

@@ -36,7 +36,7 @@ import {
   type RelationEntry,
   type Unit,
 } from '../../spec-cli/src/anchors.js'
-import { evalTimeline, evalContext, readBlobByHash, type EvalEntry, type EvalTimeline, type ScenarioInfo } from './evaltab.js'
+import { evalTimelines, evalContext, readBlobByHash, type EvalEntry, type EvalTimeline, type ScenarioInfo } from './evaltab.js'
 import { isUiPath } from './cli.js'
 import { readReadings } from './sidecar.js'
 import { parseScenarios, scenarioCodeAxis, scenarioHash, type Scenario } from './scenarios.js'
@@ -101,7 +101,7 @@ export type SessionImpactOverlay = {
 }
 
 export type SessionImpactSpecSnapshot = Pick<LoadedSpec,
-  'id' | 'path' | 'code' | 'codeScoped' | 'related' | 'relatedScoped' | 'relationProblems'>
+  'id' | 'path' | 'code' | 'codeEntries' | 'codeScoped' | 'related' | 'relatedEntries' | 'relatedScoped' | 'relationProblems'>
 
 export class SessionEvalUnavailableError extends Error {
   override name = 'SessionEvalUnavailableError'
@@ -166,12 +166,12 @@ async function revisionFile(root: string, revision: string, path: string): Promi
   return impactGit(root, ['show', `${revision}:${path}`], `read ${revision}:${path}`)
 }
 
-function loadedRelationRows(spec: SessionImpactSpecSnapshot | undefined, relation: 'code' | 'related'): string[] {
+// the snapshot already carries parsed entries; a caller wanting one relation just picks it. This used to mint
+// `path#selector` STRINGS from the split path/scoped pair and hand them back to the parser to be turned into
+// the entries the loader had all along — a serialize/reparse round-trip through a form nobody stored.
+function loadedRelationEntries(spec: SessionImpactSpecSnapshot | undefined, relation: 'code' | 'related'): readonly RelationEntry[] {
   if (!spec) return []
-  const paths = relation === 'code' ? spec.code : spec.related
-  const scoped = relation === 'code' ? spec.codeScoped : spec.relatedScoped
-  const selectors = new Map(scoped.map((entry) => [entry.path, entry.selectors]))
-  return paths.flatMap((path) => selectors.get(path)?.map((selector) => `${path}#${selector}`) ?? [path])
+  return relation === 'code' ? spec.codeEntries : spec.relatedEntries
 }
 
 function scenarioMetadata(scenario: Scenario, effectiveCode: readonly RelationEntry[]): string {
@@ -265,8 +265,8 @@ function selectorEntriesForSnapshot(
 ): RelationEntry[] {
   const entries: RelationEntry[] = []
   for (const spec of specs) {
-    entries.push(...parsedRelation(loadedRelationRows(spec, 'code'), 'code', `node '${spec.id}'`))
-    entries.push(...parsedRelation(loadedRelationRows(spec, 'related'), 'related', `node '${spec.id}'`))
+    entries.push(...loadedRelationEntries(spec, 'code'))
+    entries.push(...loadedRelationEntries(spec, 'related'))
     for (const scenario of scenariosById.get(spec.id) ?? []) {
       entries.push(...parsedRelation(scenario.code ?? [], 'code', `scenario '${spec.id} · ${scenario.name}'`))
       entries.push(...parsedRelation(scenario.related ?? [], 'related', `scenario '${spec.id} · ${scenario.name}'`))
@@ -277,20 +277,20 @@ function selectorEntriesForSnapshot(
   return [...unique.values()]
 }
 
-function primeSelectorSources(
+async function primeSelectorSources(
   context: ImpactReadContext,
   revision: string,
   paths: readonly string[],
   sourceView: 'base' | 'head',
-): void {
+): Promise<void> {
   const exactPaths = [...new Set(paths)].filter((path) => (
     !context.sources.has(`${revision}\0${path}`)
     && !(sourceView === 'head' && context.overlay && Object.hasOwn(context.overlay.files, path))
   )).sort()
   if (!exactPaths.length) return
   try {
-    const oids = batchRevisionOids(context.root, exactPaths.map((path) => `${revision}:${path}`))
-    const blobs = batchBlobTexts(context.root, oids.filter((oid): oid is string => !!oid))
+    const oids = await batchRevisionOids(context.root, exactPaths.map((path) => `${revision}:${path}`))
+    const blobs = await batchBlobTexts(context.root, oids.filter((oid): oid is string => !!oid))
     for (let index = 0; index < exactPaths.length; index++) {
       const path = exactPaths[index]
       const oid = oids[index]
@@ -497,8 +497,8 @@ export async function projectSessionImpact(root: string, options: SessionImpactO
   const headScenariosById = new Map(headSpecs.map((spec) => [spec.id, scenariosAt('head', spec)]))
   const baseSelectorEntries = selectorEntriesForSnapshot(baseSpecs, baseScenariosById)
   const headSelectorEntries = selectorEntriesForSnapshot(headSpecs, headScenariosById)
-  primeSelectorSources(context, base, baseSelectorEntries.map((entry) => entry.path), 'base')
-  primeSelectorSources(context, head, headSelectorEntries.map((entry) => entry.path), 'head')
+  await primeSelectorSources(context, base, baseSelectorEntries.map((entry) => entry.path), 'base')
+  await primeSelectorSources(context, head, headSelectorEntries.map((entry) => entry.path), 'head')
   await Promise.all([
     ...baseSelectorEntries.map((entry) => validateSelectorEntry(context, base, entry, 'base')),
     ...headSelectorEntries.map((entry) => validateSelectorEntry(context, head, entry, 'head')),
@@ -529,23 +529,18 @@ export async function projectSessionImpact(root: string, options: SessionImpactO
     const evalChanged = [...changedPaths].filter((path) => evalPaths.some((claim) => codeClaims([claim], path)))
     if (evalChanged.length) pushNodeCause(causes, 'eval', evalChanged)
 
-    const baseNodeCodeRows = loadedRelationRows(baseSpec, 'code')
-    const headNodeCodeRows = loadedRelationRows(headSpec, 'code')
-    const baseNodeCode = scenarioCodeAxis(undefined, baseNodeCodeRows)
-    const headNodeCode = scenarioCodeAxis(undefined, headNodeCodeRows)
-    if (baseNodeCode.problems.length || headNodeCode.problems.length) {
-      throw new SessionImpactUnavailableError(`session impact node '${id}' has invalid code: ${[
-        ...baseNodeCode.problems, ...headNodeCode.problems,
-      ].join('; ')}`)
-    }
+    // no second validity gate here: relationProblems above already threw for either side, and it is the
+    // SAME parse — a re-parse of rows minted from those entries cannot surface a problem the loader did not.
+    const baseNodeCodeEntries = loadedRelationEntries(baseSpec, 'code')
+    const headNodeCodeEntries = loadedRelationEntries(headSpec, 'code')
     const nodeCodeMoved = !!baseSpec && !!headSpec
-      && JSON.stringify(baseNodeCode.entries) !== JSON.stringify(headNodeCode.entries)
+      && JSON.stringify(baseNodeCodeEntries) !== JSON.stringify(headNodeCodeEntries)
     const nodeCodeReads = nodeCodeMoved
       ? await Promise.all([
-        impactForEntries(context, baseNodeCode.entries, { validateUnchanged: true, validationRevision: base, validationSide: 'base' }),
-        impactForEntries(context, headNodeCode.entries, { validateUnchanged: true, validationRevision: head, validationSide: 'head' }),
+        impactForEntries(context, baseNodeCodeEntries, { validateUnchanged: true, validationRevision: base, validationSide: 'base' }),
+        impactForEntries(context, headNodeCodeEntries, { validateUnchanged: true, validationRevision: head, validationSide: 'head' }),
       ])
-      : [await impactForEntries(context, (headSpec ? headNodeCode : baseNodeCode).entries, {
+      : [await impactForEntries(context, headSpec ? headNodeCodeEntries : baseNodeCodeEntries, {
         validateUnchanged: !baseSpec || !headSpec,
         validationRevision: headSpec ? head : base,
         validationSide: headSpec ? 'head' : 'base',
@@ -560,7 +555,7 @@ export async function projectSessionImpact(root: string, options: SessionImpactO
     // parsing one synthetic concatenated relation would turn two legitimate owners naming the same path into
     // a fake duplicate/mixed-form schema error.
     const relatedFor = (spec: SessionImpactSpecSnapshot | undefined, scenarios: readonly Scenario[]) => [
-      ...parsedRelation(loadedRelationRows(spec, 'related'), 'related', `node '${id}'`),
+      ...loadedRelationEntries(spec, 'related'),
       ...scenarios.flatMap((scenario) => (
         parsedRelation(scenario.related ?? [], 'related', `scenario '${id} · ${scenario.name}'`)
       )),
@@ -597,8 +592,8 @@ export async function projectSessionImpact(root: string, options: SessionImpactO
       const baseScenarioHash = before ? scenarioHash(before) : null
       const headScenarioHash = after ? scenarioHash(after) : null
       const semantic = !before || !after || baseScenarioHash !== headScenarioHash
-      const baseAxis = before ? scenarioCodeAxis(before.code, loadedRelationRows(baseSpec, 'code')) : { entries: [], paths: [], problems: [] }
-      const headAxis = after ? scenarioCodeAxis(after.code, loadedRelationRows(headSpec, 'code')) : { entries: [], paths: [], problems: [] }
+      const baseAxis = before ? scenarioCodeAxis(before.code, loadedRelationEntries(baseSpec, 'code')) : { entries: [], paths: [], problems: [] }
+      const headAxis = after ? scenarioCodeAxis(after.code, loadedRelationEntries(headSpec, 'code')) : { entries: [], paths: [], problems: [] }
       if (baseAxis.problems.length || headAxis.problems.length) {
         throw new SessionImpactUnavailableError(`session impact scenario '${id} · ${name}' has invalid code: ${[
           ...baseAxis.problems, ...headAxis.problems,
@@ -1107,8 +1102,10 @@ export async function sessionImpactOverlay(
     id: spec.id,
     path: spec.path,
     code: spec.code,
+    codeEntries: spec.codeEntries,
     codeScoped: spec.codeScoped,
     related: spec.related,
+    relatedEntries: spec.relatedEntries,
     relatedScoped: spec.relatedScoped,
     relationProblems: spec.relationProblems,
   }))
@@ -1458,6 +1455,14 @@ async function sessionScopeNodes(
   const specById = new Map(ctx.specs.map((spec) => [spec.id, spec]))
   const nodes: SessionEvalNode[] = []
 
+  // @@@one prime pass for the whole scope - evalTimelines unions the off-history content probes and the
+  // anchor probes across every id it is given, so asking it once per scope issues one child per probe kind
+  // instead of one per node. Reading the timelines inside the loop instead cost 74% of a warm open.
+  const timelineIds = impact.nodes
+    .filter((projected) => specById.has(projected.id) && evalById.has(projected.id))
+    .map((projected) => projected.id)
+  const timelineById = new Map((await evalTimelines(timelineIds, ctx)).map((timeline, i) => [timelineIds[i], timeline]))
+
   for (const projected of impact.nodes) {
     const spec = specById.get(projected.id)
     if (!spec) continue // removed nodes remain fully explained by impact.nodes; they have no live eval rows.
@@ -1482,7 +1487,7 @@ async function sessionScopeNodes(
       continue
     }
 
-    const timeline = await evalTimeline(spec.id, ctx)
+    const timeline = timelineById.get(spec.id)!
     // A reading is this session's own when the session filed it OR its anchor is a branch commit. This is
     // the same marker the UI and CLI render; measurement impact consumes that marker instead of inventing
     // another attribution rule.
@@ -1663,9 +1668,18 @@ type ProjectionEntry = {
   current?: { generation: number; revision: string; value: SessionEvalSummary }
   scheduled: number | null
   running: number | null
+  demandCancelledGeneration: number | null
   observerHolds: Set<string>
 }
 
+type StagedProjection = {
+  entry: ProjectionEntry
+  generation: number
+  result: SummaryBuildResult
+}
+
+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
@@ -1721,6 +1735,7 @@ export class SessionEvalProjectionCache {
 
   private authorize(entry: ProjectionEntry): void {
     if (!this.precompute || entry.liveness === 'offline' || entry.observerHolds.size) return
+    if (entry.demandCancelledGeneration === entry.generation) return
     if ((entry.phase === 'loading' || entry.phase === 'updating')
       && entry.running !== entry.generation && entry.scheduled !== entry.generation)
       entry.scheduled = entry.generation
@@ -1740,6 +1755,7 @@ export class SessionEvalProjectionCache {
       phase: 'loading',
       scheduled: null,
       running: null,
+      demandCancelledGeneration: null,
       observerHolds: new Set(),
     }
     this.entries.set(id, entry)
@@ -1762,6 +1778,7 @@ export class SessionEvalProjectionCache {
           phase: 'loading',
           scheduled: null,
           running: null,
+          demandCancelledGeneration: null,
           observerHolds: new Set(),
         }
         this.entries.set(session.id, entry)
@@ -1791,6 +1808,7 @@ export class SessionEvalProjectionCache {
       entry.generation++
       entry.phase = 'updating'
       entry.scheduled = null
+      entry.demandCancelledGeneration = null
       changed++
     }
     return changed
@@ -1805,6 +1823,7 @@ export class SessionEvalProjectionCache {
       entry.generation++
       entry.phase = 'updating'
       entry.scheduled = null
+      entry.demandCancelledGeneration = null
     }
     return true
   }
@@ -1816,6 +1835,7 @@ export class SessionEvalProjectionCache {
       entry.generation++
       entry.phase = 'updating'
       entry.scheduled = null
+      entry.demandCancelledGeneration = null
     }
     for (const check of [...this.observerWaiters]) check()
     return true
@@ -1855,9 +1875,13 @@ 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. A running
-    // summary is left alone; the priority job waits for it to settle before taking the slot.
-    if (entry.running == null) entry.scheduled = null
+    // 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.
+    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 })
@@ -1902,35 +1926,69 @@ 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 {
+    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'
+      entry.scheduled = null
+    }
+    return changed
+  }
+
   private startBatch(): void {
     if (this.batch) return
-    const hasPending = () => this.demandQueue.length > 0
-      || [...this.entries.values()].some((entry) => entry.scheduled != null && entry.running == null)
-    if (!hasPending()) return
+    if (!this.hasPending()) return
     this.batch = (async () => {
-      let publish = false
-      while (hasPending()) {
-        const demand = this.demandQueue.shift()
-        if (demand) {
-          try { demand.resolve(await demand.run()) }
-          catch (error) { demand.reject(error) }
-          continue
-        }
-        const jobs = [...this.entries.values()]
-          .filter((entry) => entry.scheduled != null && entry.running == null)
-          .slice(0, PROJECTION_CONCURRENCY)
-        const changed = await Promise.all(jobs.map((entry) => this.runEntry(entry)))
-        publish = publish || changed.some(Boolean)
+      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 (publish) this.notify()
+      if (this.publishCohort(staged)) this.notify()
     })().finally(() => {
       this.batch = null
-      if (hasPending()) this.startBatch()
+      if (this.hasPending()) this.startBatch()
     })
   }
 
-  private async runEntry(entry: ProjectionEntry): Promise<boolean> {
-    const generation = entry.scheduled!
+  private async runEntry({ entry, generation }: ProjectionCohortRow): Promise<StagedProjection | null> {
+    if (this.entries.get(entry.id) !== entry || entry.generation !== generation
+      || entry.scheduled !== generation || entry.running != null) return null
     entry.scheduled = null
     entry.running = generation
     let result: SummaryBuildResult
@@ -1940,21 +1998,8 @@ export class SessionEvalProjectionCache {
       result = { kind: 'missing' }
     }
     entry.running = null
-    if (this.entries.get(entry.id) !== entry || entry.generation !== generation) return false
-    if (result.kind === 'unstable') {
-      entry.generation++
-      entry.phase = 'updating'
-      entry.scheduled = null
-      this.notify()
-      return false
-    }
-    if (result.kind === 'missing') {
-      entry.phase = 'error'
-      return true
-    }
-    entry.current = { generation, revision: result.revision, value: result.summary }
-    entry.phase = 'ready'
-    return true
+    if (this.entries.get(entry.id) !== entry || entry.generation !== generation || entry.scheduled !== null) return null
+    return { entry, generation, result }
   }
 }
 
@@ -1969,20 +2014,37 @@ async function buildSummaryAttempt(id: string, _path: string): Promise<SummaryBu
   if (cached) {
     const after = await sessionEvalContentRevision(ctxPath)
     return before === after
-      ? { kind: 'stable', revision: after, summary: cached }
+      ? { kind: 'stable', revision: after, summary: cached.summary }
       : { kind: 'unstable' }
   }
   const model = await buildSessionEvalModel(id, payload, wtPath, true)
   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.
-  for (const key of summaryByContent.keys()) if (key.startsWith(`${id}\0`)) summaryByContent.delete(key)
-  summaryByContent.set(cacheKey, summary)
+  // Keep one content-addressed stable value per session. Revisions, not elapsed time, decide reuse. This
+  // fold is latestOnly, so it deposits no model — it only carries any model an earlier demand left here.
+  depositStableCut(id, after, { summary })
   return { kind: 'stable', revision: after, summary }
 }
 
-const summaryByContent = new Map<string, SessionEvalSummary>()
+// ONE content-addressed cut per session, keyed by id + content revision. It carries the summary the graph
+// reads and — only when the demand path built it — the derived full model a repeat open replays.
+// @@@the two builders do not produce the same model - buildSummaryAttempt folds latestOnly=true (latest
+// reading per scenario, enough for counts) while the demand path needs the complete A/B history. Only the
+// demand path may deposit `model`, and only a demand read may consume it; serving the summary path's fold
+// to a demand would silently truncate every scenario's history.
+type StableCut = { summary: SessionEvalSummary; model?: SessionEvalModel }
+const summaryByContent = new Map<string, StableCut>()
+
+// Content addressing IS the invalidation: a moved input yields a different key. Keeping only the newest key
+// per session bounds the map at one cut per session and drops summary and model together, so the two can
+// never disagree about which revision they describe.
+function depositStableCut(id: string, revision: string, cut: StableCut): void {
+  const key = `${id}\0${revision}`
+  const existing = summaryByContent.get(key)
+  for (const other of [...summaryByContent.keys()]) if (other.startsWith(`${id}\0`)) summaryByContent.delete(other)
+  summaryByContent.set(key, { summary: cut.summary, model: cut.model ?? existing?.model })
+}
 const projectionCache = new SessionEvalProjectionCache(buildSummaryAttempt, () => {}, randomUUID(), false)
 const OBSERVER_RECOVERY_TIMEOUT_MS = 10_000
 
@@ -2029,6 +2091,23 @@ export async function buildSessionEvals(id: string): Promise<SessionEvals | null
       const generation = known?.generation ?? 0
       await awaitObservableInputs(id, ctxPath)
       const before = await sessionEvalContentRevision(ctxPath)
+      // A repeat open at an unmoved revision replays the cut this same owner already published, instead of
+      // re-deriving it from Git. The stability, observer and generation fences below still decide whether the
+      // answer may be published, so a replay is certified exactly like a fresh fold.
+      // @@@a replay cannot hide a dead selector - the validation that raises 503 reads the declarations and
+      // trees the content revision already covers, so an identical revision has an identical verdict; and a
+      // failing fold deposits nothing, so an unavailable projection always re-derives and re-raises.
+      const replay = summaryByContent.get(`${id}\0${before}`)
+      if (replay?.model) {
+        const settled = await sessionEvalContentRevision(ctxPath)
+        const live = projectionCache.get(id)
+        if (before === settled && !projectionCache.isObserverHeld(id, ctxPath)
+          && !(live && live.generation !== generation)) {
+          return { kind: 'ready' as const, model: replay.model, summary: replay.summary, generation, revision: settled }
+        }
+        if (before !== settled) projectionCache.invalidate({ id })
+        return { kind: 'retry' as const }
+      }
       const model = await buildSessionEvalModel(id, payload, wtPath, false)
       const after = await sessionEvalContentRevision(ctxPath)
       const current = projectionCache.get(id)
@@ -2038,9 +2117,9 @@ export async function buildSessionEvals(id: string): Promise<SessionEvals | null
         return { kind: 'retry' as const }
       }
       const summary = sessionEvalSummary(model.nodes)
-      const cacheKey = `${id}\0${after}`
-      for (const key of summaryByContent.keys()) if (key.startsWith(`${id}\0`)) summaryByContent.delete(key)
-      summaryByContent.set(cacheKey, summary)
+      // Only a settled fold deposits, and only here does a model enter the cut — a thrown build reaches
+      // neither line, so a failure can never poison the entry.
+      depositStableCut(id, after, { summary, model })
       if (current) projectionCache.accept(id, generation, after, summary)
       return { kind: 'ready' as const, model, summary, generation, revision: after }
     })

package/spec-eval/src/sidecar.ts

@@ -1,66 +1,30 @@
 import { readFileSync, appendFileSync, existsSync } from 'node:fs'
 
-// the verdict is pass | fail; `note` is an OPTIONAL one-line annotation on either (why it failed, how far
-// a pass is from ideal) — not a third status. (Legacy readings filed when `note` was its own status survive
-// on disk with status:'note'; render stays tolerant of them, the CLI no longer mints them.)
 export type Verdict = { status: 'pass' | 'fail'; note?: string }
 
-// The evidence-kind taxonomy ([[evidence-kind-taxonomy]]) is a MEDIA/RENDER type — how a blob's bytes are
-// shown — kept ORTHOGONAL to the step-map AXIS (which is derived from the kind, not welded to it): `image`
-// (a still), `transcript` (free-form text), `video` (a screenshot with a time axis), `data` (a structured
-// machine export — a JSON/metrics dump — rendered as a validatable data block, not flattened into scrolling
-// transcript text). A `data` reading is honest about being structured: it can be parsed and checked, and it
-// is derived from CONTENT (isJsonBlob), never from which filing flag was used.
 export type EvidenceKind = 'image' | 'transcript' | 'video' | 'data'
-// one piece of a reading's evidence: a content-addressed blob (`hash`) tagged by `kind`.
 export type Evidence = { hash: string; kind: EvidenceKind }
 
-// A reading's evidence is a LIST of typed entries — N images and/or a video (with its step-timeline) and/or
-// a transcript, in filing order. New filings write `evidence`; the legacy scalar shape (`blob` + `blobKind`,
-// absent kind → image) is still READ and normalized to a one-entry list by `evidenceOf`, so old readings
-// still render. A video reading may carry `timelineBlob`: the content hash of its step-timeline sidecar
-// (timeline.ts) mapping clip moments to named steps — it anchors the reading's VIDEO evidence entry.
-// `by` is the SESSION that filed this reading (the filer, from envSessionId) — the ORIGINATOR an eval-comment
-// thread loops in on a reply ([[mentions]] implicit loop-in). Pure additive: a legacy reading without it simply
-// has no originator → silent. WHO measured is deliberately NOT a schema axis — the agent is the measuring
-// hand; the retired `evaluator` tag survives on old lines only, read-tolerated like the scalar blob.
 export type Reading = {
   scenario: string
   codeSha: string
-  // content hash of the scenario's semantic text (description+expected, normalized — scenarios.ts
-  // scenarioHash) as DECLARED at filing time: the record of which contract this measurement was taken
-  // against. When present it alone decides the scenario freshness axis (a pure compare against the current
-  // declaration's hash); a legacy reading without it is decided by the git-derived rule instead — one
-  // track per reading, never both ([[eval-core]]).
   scenarioHash?: string
   evidence?: Evidence[]
-  // legacy scalar evidence — read for old readings, never written by new filings.
   blob?: string | null
   blobKind?: EvidenceKind
   timelineBlob?: string
-  // legacy instrument tag (always 'manual@1') — read for old readings, never written by new filings.
   evaluator?: string
   by?: string
   verdict?: Verdict
   ts: string
 }
 
-// the one scalar→list bridge every evidence consumer passes through: the `evidence` list when present, else
-// the legacy scalar (blob + blobKind, absent kind → image) as a one-entry list, else empty.
 export function evidenceOf(r: { evidence?: Evidence[]; blob?: string | null; blobKind?: EvidenceKind }): Evidence[] {
   if (r.evidence?.length) return r.evidence
   if (r.blob) return [{ hash: r.blob, kind: r.blobKind ?? 'image' }]
   return []
 }
 
-// Is this blob STRUCTURED DATA (a machine export — a JSON object/array) rather than free-form transcript
-// text? The `data` evidence kind ([[evidence-kind-taxonomy]]) is derived from CONTENT, never from which
-// filing flag was used: a hyperfine `--export-json`, an API payload, a metrics dump is data, and flattening
-// it into a scrolling transcript loses that it can be structurally validated and rendered as a data block.
-// Sniffed cheaply and self-contained (no deps): a text blob (no NUL) whose trimmed body brackets as an
-// object/array AND parses to one; anything else (plain logs, terminal text) is not data. This is the ONE
-// predicate both the blob MIME sniff (application/json) and the CLI `--result` kind derive from, so the
-// stored kind and the served Content-Type always agree.
 export function isJsonBlob(b: Buffer): boolean {
   if (!b.length || b.includes(0)) return false           // empty or binary → not JSON text
   if (b.length > 4_000_000) return false                 // don't parse an unbounded blob just to sniff a type
@@ -70,25 +34,10 @@ export function isJsonBlob(b: Buffer): boolean {
   try { const v = JSON.parse(s); return v !== null && typeof v === 'object' } catch { return false }
 }
 
-// a RETRACTION is the sanctioned inverse of a filing — itself an appended event, never a deleted line
-// (the sidecar stays append-only; git shows who retracted what, when). `retracts` is the target reading's
-// `ts` within `scenario` (its natural key). The event kinds are told apart POSITIVELY — a retraction
-// carries `retracts`, a reading carries `codeSha`, a human-ok carries `kind: 'human-ok'`; none is ever
-// recognized by another field's absence. `by` is the retracting session; `note` says why (a botched e2e
-// filing, a wrong verdict).
 export type Retraction = { retracts: string; scenario: string; note?: string; by?: string; ts: string }
 
-// a HUMAN-OK ([[human-ok]]) is the human's sign-off on ONE immutable reading — an appended event like the
-// others, never a mutation. `okTs`+`okSha` anchor the blessed reading (its ts is the natural key within
-// `scenario`, exactly retraction's join; the sha rides for the human reader). The ok is MONOTONIC — there
-// is no un-ok event: a newer reading is a different object the ok never transfers to, and staleness is
-// computed live, so both automatically bring the scenario back. A pre-human-ok toolchain skips these lines
-// silently (no top-level `codeSha`, so its reading parse never claims them).
 export type HumanOk = { kind: 'human-ok'; scenario: string; okTs: string; okSha: string; by: string; ts: string }
 
-// parse the sidecar RAW: one event per non-blank line — a Reading, a Retraction (a line carrying a string
-// `retracts`), or a HumanOk (kind 'human-ok'). A malformed line is skipped (the file is append-only and
-// git-tracked, so a partial write or a hand-edit shouldn't sink the whole read) — fail soft per line.
 export function readSidecar(sidecarPath: string): { readings: Reading[]; retractions: Retraction[]; oks: HumanOk[] } {
   const readings: Reading[] = []
   const retractions: Retraction[] = []
@@ -103,58 +52,40 @@ export function readSidecar(sidecarPath: string): { readings: Reading[]; retract
       if (typeof r.retracts === 'string') retractions.push(r as Retraction)
       else if (r.kind === 'human-ok' && typeof r.okTs === 'string') oks.push(r as HumanOk)
       else if (typeof r.codeSha === 'string') readings.push(r as Reading)
-    } catch { /* skip a malformed line */ }
+    } catch { /* Keep earlier events readable after an incomplete append. */ }
   }
   return { readings, retractions, oks }
 }
 
-// the retraction join, shared by every effective-view reader: drop each reading a retraction targets by
-// (scenario, ts) — NUL-joined, since a scenario name may contain spaces. A retraction matching nothing is
-// inert: it excludes no reading and harms no read.
 export function applyRetractions(readings: Reading[], retractions: Retraction[]): Reading[] {
   if (!retractions.length) return readings
   const gone = new Set(retractions.map((x) => `${x.scenario}\0${x.retracts}`))
   return readings.filter((r) => !gone.has(`${r.scenario}\0${r.ts}`))
 }
 
-// the EFFECTIVE readings — what the scoreboard sees: every reading minus the retracted. Every score
-// consumer (freshness, scan, clean's referenced set, the eval tab, the proof) reads through here, so a
-// retract undoes a botched filing on ALL of them at once — the previous reading becomes the latest again,
-// or the scenario honestly returns to eval-missing.
 export function readReadings(sidecarPath: string): Reading[] {
   const { readings, retractions } = readSidecar(sidecarPath)
   return applyRetractions(readings, retractions)
 }
 
-// append ONE reading as a JSON line — the only mutation eval performs (a reading is an event, never an
-// overwrite; superseding readings are newer lines, freshness picks the latest per scenario).
 export function appendReading(sidecarPath: string, r: Reading): void {
   appendFileSync(sidecarPath, JSON.stringify(r) + '\n')
 }
 
-// append ONE retraction as a JSON line — the sanctioned undo writes through the same append-only surface
-// that filed the reading; the target line stays in place as history.
 export function appendRetraction(sidecarPath: string, r: Retraction): void {
   appendFileSync(sidecarPath, JSON.stringify(r) + '\n')
 }
 
-// append ONE human-ok as a JSON line — the sign-off writes through the same append-only surface; the
-// blessed reading stays untouched, the ok binds to it by (scenario, okTs).
 export function appendHumanOk(sidecarPath: string, r: HumanOk): void {
   appendFileSync(sidecarPath, JSON.stringify(r) + '\n')
 }
 
-// the ok that binds to a reading — the LAST ok row targeting (scenario, ts), or null. An ok anchored to a
-// retracted/superseded reading is inert history: it binds to nothing current, so the join is by exact
-// (scenario, okTs) against whichever readings the caller passes.
 export function humanOkFor(oks: HumanOk[], scenario: string, readingTs: string): HumanOk | null {
   let hit: HumanOk | null = null
   for (const o of oks) if (o.scenario === scenario && o.okTs === readingTs) hit = o
   return hit
 }
 
-// the latest reading per scenario (the file is chronological, so the LAST line for a name wins). clean's
-// --keep-latest uses it to decide which blob to keep.
 export function latestPerScenario(readings: Reading[]): Map<string, Reading> {
   const m = new Map<string, Reading>()
   for (const r of readings) m.set(r.scenario, r)   // later lines overwrite earlier → last wins

package/spec-eval/src/timeline.ts

@@ -1,30 +1,12 @@
-// step-timeline — the map from a POSITION on a piece of evidence's own axis to a named step. SpexCode owns
-// only this FORMAT (a tiny data contract any userland emitter satisfies — a Playwright reporter, a WebDriver
-// listener, a computer-use hand narrating as it drives, a CLI run stamping line numbers); aligning the
-// emitter's positions to the evidence is the emitter's own job. The map rides as a second content-addressed
-// blob on the reading, never a new ndjson column beyond the one hash.
-//
-// The step is anchored to the evidence's OWN axis, tagged by `axis`: `time` (ms, a video), `frame` (a still
-// SEQUENCE by index), `line` (a transcript by line number), `index` (a bare action ordinal). The set is
-// OPEN by convention — an unknown axis is legal and a reader renders its positions as bare numbers. `stepAt`
-// (last step at or before a position) is axis-agnostic and unchanged.
-
 export type TimelineEvent = { at: number; step: string; node?: string }
 export type StepTimeline = { v: 2; axis: string; events: TimelineEvent[] }
 
-// legacy v1 is the TIME axis with `tMs` as the position — read losslessly, normalized to the axis-tagged
-// shape (`axis: 'time'`, `at: tMs`). Kept forever: an emitter that only knew `{ v: 1, events: [{ tMs }] }`
-// still files a valid video step-map.
 export type LegacyTimelineEvent = { tMs: number; step: string; node?: string }
 export type LegacyStepTimeline = { v: 1; events: LegacyTimelineEvent[] }
 
 const V2_EVENT_KEYS = new Set(['at', 'step', 'node'])
 const V1_EVENT_KEYS = new Set(['tMs', 'step', 'node'])
 
-// validate LOUD — every violation named, [] when well-formed. Both schema versions are accepted: v1 (legacy
-// time axis, `tMs`) and v2 (axis-tagged, `at`). The key set is closed per version (like the eval.md
-// scenario schema): a malformed timeline is rejected at filing time, never silently reshaped. The `axis`
-// string itself is open — only its ABSENCE is an error, never an unrecognized value.
 export function validateTimeline(raw: unknown): string[] {
   if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return ['timeline must be a JSON object { v, axis, events }']
   const o = raw as Record<string, unknown>
@@ -55,9 +37,6 @@ export function validateTimeline(raw: unknown): string[] {
   return errs
 }
 
-// normalize any VALID timeline (v1 or v2) to the axis-tagged shape every reader uses: v1 IS the time axis
-// with `tMs` as the position. Call only on input `validateTimeline` accepted. This is the whole of the
-// lossless back-compat: an old v1 blob and a new `{ v: 2, axis: 'time' }` render identically.
 export function normalizeTimeline(raw: unknown): { axis: string; events: TimelineEvent[] } {
   const o = (raw ?? {}) as Record<string, any>
   const events: any[] = Array.isArray(o.events) ? o.events : []
@@ -65,8 +44,6 @@ export function normalizeTimeline(raw: unknown): { axis: string; events: Timelin
   return { axis: typeof o.axis === 'string' ? o.axis : 'time', events: events.map((e) => ({ at: e.at, step: e.step, ...(e.node ? { node: e.node } : {}) })) }
 }
 
-// the whole of "which step is this position": the last event at or before `pos`; null before the first event
-// (a plain moment, no step to name — graceful, never an error). Axis-agnostic — `pos` is on the events' axis.
 export function stepAt(events: TimelineEvent[], pos: number): TimelineEvent | null {
   let hit: TimelineEvent | null = null
   for (const e of events) {