spexcode 0.1.6 → 0.2.0

package/spec-yatsu/src/evaltab.ts

@@ -1,26 +1,92 @@
 import { relative, dirname } from 'node:path'
 import { repoRoot, driftIndex, historyIndex, type DriftIndex, type HistoryIndex } from '../../spec-cli/src/git.js'
 import { loadSpecs } from '../../spec-cli/src/specs.js'
+import { loadEvalRemarkTracks, trackKey, type RemarkTrack, type Issue, type Reply } from '../../spec-cli/src/issues.js'
 import { yatsuNodes, type YatsuNode } from './yatsu.js'
-import { readReadings, type Verdict } from './sidecar.js'
-import { staleAxes, type StaleAxis } from './freshness.js'
+import { readSidecar, applyRetractions, evidenceOf, type Verdict, type EvidenceKind, type Retraction } from './sidecar.js'
+import { staleAxes, codeDrift, type StaleAxis } from './freshness.js'
+import { scenarioIndex, type ScenarioIndex } from './scenariofresh.js'
 import { hasBlob, getBlob, MISS_BLOB } from './cache.js'
 
+// one evidence entry as the tab renders it: the content hash, its kind, and its LIVE blob state (present, or
+// miss when the bytes were pruned). The whole list is the gallery the dashboard maps.
+export type EvidenceView = { hash: string; kind: EvidenceKind; state: 'present' | 'miss' }
+
+// a remark overlaid onto the reading it judged ([[remark-teeth]] R2): the resolvable fields the eval
+// surfaces read, plus `dangling` when its targetCodeSha matched no reading (so it was attached to the
+// scenario's latest as a fallback, never hidden). The teeth read the whole scenario track; THIS is the
+// per-reading display attachment.
+export type RemarkView = {
+  rid: string
+  ref: string             // `<thread-id>#<rid>` — the address `spex resolve`/`spex retract` take
+  by: string
+  at: string
+  body: string
+  targetCodeSha: string
+  resolved: boolean
+  resolvedAt?: string
+  resolvedBy?: string
+  dangling: boolean
+}
+
 export type EvalEntry = {
   scenario: string
   expected: string
   codeSha: string
+  // the reading's whole evidence list (N images and/or a video and/or a transcript). Always populated —
+  // a legacy scalar reading normalizes to a one-entry list — so every read surface sees a gallery.
+  evidence?: EvidenceView[]
+  // primary scalar view (the video entry if any, else the first) — the single-evidence compat face for
+  // consumers that still read one blob (the session proof, the board fold's kind hint).
   blob: string | null
-  blobKind?: 'image' | 'transcript'
+  blobKind?: EvidenceKind
+  timelineBlob?: string
   evaluator: string
+  // the SESSION that filed this reading ([[event-detail]] originator liveness / [[mentions]] loop-in): the
+  // reachable actor an un-@'d eval remark courtesy-delivers to (the latest reading's filer is the chain's
+  // first link). Surfaced so the eval detail can show whether that session is still alive. Absent on a legacy
+  // reading (no `by`) — the pane simply shows no originator, exactly as the offline chain runs dry silently.
+  by?: string
   verdict?: Verdict
   ts: string
   fresh: boolean
   staleAxes: StaleAxis[]
   blobState: 'present' | 'miss' | 'none'
+  // the code axis's drift detail for a code-stale reading ([[yatsu-core]]'s codeDrift): each governed file
+  // that moved since this reading + how many commits behind, so the eval detail can EXPLAIN the staleness
+  // ("EvalsFeed.jsx +3") rather than just flag it. Absent when the reading isn't code-stale.
+  codeDrift?: { file: string; behind: number }[]
+  // the trunk remark track overlaid onto THIS reading ([[remark-teeth]]): the remarks whose targetCodeSha
+  // pins here (or the latest reading, for a dangling target). Absent when the scenario has no remark.
+  remarks?: RemarkView[]
+  // the (node, scenario) eval-remark THREAD ([[eval-issue-split]]): the SAME join the teeth read, attached
+  // so the eval detail pane reads its whole comment thread from the reading overlay — the counterpart to
+  // splitting eval-remark threads OUT of the issue surfaces (mergedIssues). Absent until the first remark.
+  thread?: Issue
+}
+
+// a remark overlaid onto its display host (a reading, above) → the RemarkView the surfaces read.
+function toRemarkView(rm: Reply, threadId: string, dangling: boolean): RemarkView {
+  return {
+    rid: rm.rid!,
+    ref: `${threadId}#${rm.rid}`,
+    by: rm.by, at: rm.at, body: rm.body,
+    targetCodeSha: rm.targetCodeSha ?? '',
+    resolved: !!rm.resolved,
+    ...(rm.resolvedAt ? { resolvedAt: rm.resolvedAt } : {}),
+    ...(rm.resolvedBy ? { resolvedBy: rm.resolvedBy } : {}),
+    dangling,
+  }
 }
 
-export type ScenarioInfo = { name: string; expected: string; code?: string[] }
+// a DANGLING track ([[remark-teeth]]'s dangling clause / directive 5): a (node, scenario) remark track whose
+// scenario no reading joins — the scenario was renamed or deleted, so today the track loads but surfaces
+// nowhere. It ages NOTHING (there is no reading to stale — the teeth read per-reading), but its remarks must
+// stay VISIBLE and resolvable/retractable via their refs, so evalTimeline emits one synthetic row per orphan
+// at NODE level. `scenario` is the orphaned name (rendered struck-through / gone); `remarks` are all dangling.
+export type DanglingTrack = { scenario: string; threadId: string; thread: Issue; remarks: RemarkView[] }
+
+export type ScenarioInfo = { name: string; expected: string; tags?: string[]; code?: string[] }
 
 // `hasYatsu` distinguishes a node that declares no scenarios (no yatsu.md) from one that declares some but
 // has no readings yet — the tab says different things for each. `scenarios` is the declared set; `readings`
@@ -31,6 +97,15 @@ export type EvalTimeline = {
   hasYatsu: boolean
   scenarios: ScenarioInfo[]
   readings: EvalEntry[]
+  // retraction events ([[yatsu-core]]'s retract verb), newest first — the sanctioned-undo TRACE. `readings`
+  // above is already the effective view (a retracted reading is dropped from the scoreboard everywhere);
+  // this list is how a surface still shows that the undo happened: which (scenario, ts) was withdrawn,
+  // by whom, why. Additive — a consumer that ignores it sees exactly the effective scoreboard.
+  retractions: Retraction[]
+  // orphaned remark tracks (renamed/deleted scenarios) — surfaced at node level so their remarks never vanish
+  // ([[remark-teeth]] dangling clause). SEPARATE from `readings` on purpose: a dangling track has no reading,
+  // so it must NOT flow into latestPerScenario / the board scoreboard — it ages nothing.
+  dangling: DanglingTrack[]
 }
 
 export type EvalContext = {
@@ -38,14 +113,28 @@ export type EvalContext = {
   specs: Awaited<ReturnType<typeof loadSpecs>>
   idx: DriftIndex
   hidx: HistoryIndex
+  scidx: ScenarioIndex   // per-scenario block-change history ([[scenariofresh]]) — the SCENARIO axis, built ONCE per build
   ynodes: YatsuNode[]
+  // the trunk remark tracks ([[remark-teeth]]), keyed (node, scenario) — loaded ONCE per board/proof build
+  // and reused for every node, so the fold never re-reads the issue store per node.
+  remarks: Map<string, RemarkTrack>
 }
 
 // build the shared context with ONE yatsu walk, reusing the caller's already-computed specs + the two
 // HEAD-keyed git indices (drift for the code axis, history for the rename-safe scenario axis — both warm
-// hits, loadSpecs already derived them).
-export function evalContext(root: string, specs: Awaited<ReturnType<typeof loadSpecs>>, idx: DriftIndex, hidx: HistoryIndex): EvalContext {
-  return { root, specs, idx, hidx, ynodes: yatsuNodes(root) }
+// hits, loadSpecs already derived them). The remark tracks are the fourth, non-git freshness input
+// ([[remark-teeth]]); a caller that omits them gets a live load, so a bare evalTimeline still has teeth.
+export async function evalContext(
+  root: string,
+  specs: Awaited<ReturnType<typeof loadSpecs>>,
+  idx: DriftIndex,
+  hidx: HistoryIndex,
+  remarks?: Map<string, RemarkTrack>,
+  ynodes?: YatsuNode[],   // the hot board build precomputes these off the event loop (yatsuNodesAsync); a bare caller walks sync
+): Promise<EvalContext> {
+  const nodes = ynodes ?? yatsuNodes(root)
+  const scidx = await scenarioIndex(root, nodes.map((n) => n.yatsuPath))
+  return { root, specs, idx, hidx, scidx, ynodes: nodes, remarks: remarks ?? loadEvalRemarkTracks() }
 }
 
 export async function evalTimeline(id: string, ctx?: EvalContext): Promise<EvalTimeline> {
@@ -53,37 +142,93 @@ export async function evalTimeline(id: string, ctx?: EvalContext): Promise<EvalT
   // short-circuit a non-yatsu node on the (short) yatsu walk — the board attaches `evals` to every node, so
   // this is the common case and must stay cheap (a list the size of the few yatsu nodes, not the whole tree).
   const ynode = (ctx?.ynodes ?? yatsuNodes(root)).find((n) => n.id === id)
-  if (!ynode) return { node: id, hasYatsu: false, scenarios: [], readings: [] }
+  if (!ynode) return { node: id, hasYatsu: false, scenarios: [], readings: [], retractions: [], dangling: [] }
   // the governed `code:` files are the freshness CODE axis; read them from the canonical spec loader so a
   // reparent/rename is seen the same way `spex lint` and `spex yatsu eval` see it (joined by directory).
   const specs = ctx?.specs ?? await loadSpecs()
   const codeFiles = specs.find((s) => dirname(s.path) === relative(root, ynode.dir))?.code ?? []
   const idx = ctx?.idx ?? await driftIndex(root)
   const hidx = ctx?.hidx ?? await historyIndex(root)
+  // the SCENARIO axis: per-scenario block-change history, built once per HEAD (cached). A bare call builds it
+  // for the WHOLE yatsu set (not just this node) so the shared HEAD-keyed cache is complete for later callers.
+  const scidx = ctx?.scidx ?? await scenarioIndex(root, (ctx?.ynodes ?? yatsuNodes(root)).map((n) => n.yatsuPath))
   const byName = new Map(ynode.scenarios.map((s) => [s.name, s]))   // join each reading to its scenario's expected + code
+  // the trunk remark track per scenario ([[remark-teeth]]) — the non-git freshness input, fed to the teeth.
+  const tracks = ctx?.remarks ?? loadEvalRemarkTracks()
+  const remarksFor = (scenario: string): RemarkTrack['remarks'] => tracks.get(trackKey(id, scenario))?.remarks ?? []
+  const threadFor = (scenario: string): Issue | undefined => tracks.get(trackKey(id, scenario))?.thread
   const scenarios: ScenarioInfo[] = ynode.scenarios.map((s) => ({
-    name: s.name, expected: s.expected, ...(s.code?.length ? { code: s.code } : {}),
+    name: s.name, expected: s.expected,
+    ...(s.tags?.length ? { tags: s.tags } : {}), ...(s.code?.length ? { code: s.code } : {}),
   }))
-  const readings: EvalEntry[] = readReadings(ynode.sidecarPath).map((r) => {
+  // one raw sidecar read: the effective readings feed the scoreboard rows below; the retraction events ride
+  // along as the undo trace (newest-first, like the readings).
+  const { readings: rawReadings, retractions } = readSidecar(ynode.sidecarPath)
+  const readings: EvalEntry[] = applyRetractions(rawReadings, retractions).map((r) => {
     // a scenario's own `code` is its freshness code axis when it declares one; else the whole node's list.
     const sc = byName.get(r.scenario)
-    const axes = staleAxes(r, sc?.code?.length ? sc.code : codeFiles, ynode.yatsuPath, idx, hidx)
+    // the teeth feed the WHOLE scenario track against THIS reading — an unresolved (or not-yet-out-run)
+    // remark makes it remark-stale (T1). Display attachment (which reading each remark pins to) is a separate
+    // read-time overlay below; freshness never depends on that pin.
+    const cf = sc?.code?.length ? sc.code : codeFiles
+    const axes = staleAxes(r, cf, ynode.yatsuPath, idx, scidx,
+      remarksFor(r.scenario).map((rm) => ({ resolved: !!rm.resolved, resolvedAt: rm.resolvedAt })))
+    // when the code axis is stale, explain it: which of THIS reading's governed files moved, by how many commits.
+    const drift = axes.includes('code') ? codeDrift(idx, r.codeSha, cf) : []
+    // the reading's evidence list, each entry resolved to its live blob state; the primary (video-first, else
+    // first) drives the scalar compat fields for single-evidence consumers.
+    const evidence: EvidenceView[] = evidenceOf(r).map((e) => ({ hash: e.hash, kind: e.kind, state: hasBlob(e.hash) ? 'present' : 'miss' }))
+    const primary = evidence.find((e) => e.kind === 'video') ?? evidence[0]
     return {
       scenario: r.scenario,
       expected: byName.get(r.scenario)?.expected ?? '',
       codeSha: r.codeSha,
-      blob: r.blob,
-      ...(r.blobKind ? { blobKind: r.blobKind } : {}),
+      ...(evidence.length ? { evidence } : {}),
+      blob: primary?.hash ?? null,
+      ...(primary ? { blobKind: primary.kind } : {}),
+      ...(r.timelineBlob ? { timelineBlob: r.timelineBlob } : {}),
       evaluator: r.evaluator,
+      ...(r.by ? { by: r.by } : {}),
       ...(r.verdict ? { verdict: r.verdict } : {}),
       ts: r.ts,
       fresh: axes.length === 0,
       staleAxes: axes,
-      blobState: r.blob == null ? 'none' : hasBlob(r.blob) ? 'present' : 'miss',
+      ...(drift.length ? { codeDrift: drift } : {}),
+      blobState: primary ? primary.state : 'none',
+      ...(threadFor(r.scenario) ? { thread: threadFor(r.scenario) } : {}),
     }
   })
-  readings.reverse()
-  return { node: id, hasYatsu: true, scenarios, readings }
+  readings.reverse()   // newest-first
+  // R2 display overlay ([[remark-teeth]]): pin each remark to the reading it JUDGED (targetCodeSha match),
+  // else the scenario's latest reading (first in newest-first order) — a dangling target never HIDES the
+  // remark. A track whose SCENARIO no reading joins (renamed/deleted) has no reading to attach to, so it
+  // becomes a synthetic DANGLING row at node level (directive 5) instead of vanishing — visible, its remarks
+  // resolvable/retractable via their refs, and ageing nothing (there is no reading for the teeth to stale).
+  const declared = new Set(ynode.scenarios.map((s) => s.name))
+  const dangling: DanglingTrack[] = []
+  for (const [, track] of tracks) {
+    if (track.node !== id || !track.remarks.length) continue
+    const rows = readings.filter((r) => r.scenario === track.scenario)
+    if (!rows.length) {
+      // no reading joins this track. If the scenario is still DECLARED it is just a blind spot (unmeasured),
+      // not orphaned — its remarks wait for a reading. Only a scenario that is BOTH gone from yatsu.md AND
+      // has no reading is truly dangling (renamed/deleted), and that is the one we surface at node level.
+      if (!declared.has(track.scenario)) {
+        dangling.push({
+          scenario: track.scenario, threadId: track.threadId, thread: track.thread,
+          remarks: track.remarks.map((rm) => toRemarkView(rm, track.threadId, true)),
+        })
+      }
+      continue
+    }
+    const latest = rows[0]
+    for (const rm of track.remarks) {
+      const target = rows.find((r) => r.codeSha === rm.targetCodeSha)
+      const host = target ?? latest
+      ;(host.remarks ??= []).push(toRemarkView(rm, track.threadId, !target))
+    }
+  }
+  return { node: id, hasYatsu: true, scenarios, readings, retractions: [...retractions].reverse(), dangling }
 }
 
 const HEX64 = /^[0-9a-f]{64}$/
@@ -99,13 +244,18 @@ export function readBlobByHash(hash: string, dir?: string): BlobResult {
   return { ok: true, bytes, mime: sniffBlobMime(bytes) }
 }
 
-// PNG/JPEG/GIF/WebP cover every screenshot (a manual --image); a transcript (--result) is text, so bytes
-// with no NUL and no image header sniff to text/plain; anything else falls back to a generic binary type so
-// it still downloads rather than being mislabeled.
+// PNG/JPEG/GIF/WebP cover every screenshot (a manual --image); MP4/WebM cover a recorded clip (--video), so
+// the blob route serves it with a playable Content-Type; a transcript (--result) is text, so bytes with no
+// NUL and no known header sniff to text/plain; anything else falls back to a generic binary type so it still
+// downloads rather than being mislabeled.
 function sniffBlobMime(b: Buffer): string {
   if (b.length >= 4 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47) return 'image/png'
   if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return 'image/jpeg'
   if (b.length >= 4 && b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46) return 'image/gif'
+  // WebM/Matroska begin with the EBML magic 1A 45 DF A3; disambiguate from a RIFF/WEBP image above.
+  if (b.length >= 4 && b[0] === 0x1a && b[1] === 0x45 && b[2] === 0xdf && b[3] === 0xa3) return 'video/webm'
+  // ISO-BMFF (MP4/MOV): a `ftyp` box type at bytes 4..8, after its 4-byte size.
+  if (b.length >= 12 && b.toString('ascii', 4, 8) === 'ftyp') return 'video/mp4'
   if (b.length >= 12 && b.toString('ascii', 0, 4) === 'RIFF' && b.toString('ascii', 8, 12) === 'WEBP') return 'image/webp'
   if (b.length && !b.includes(0)) return 'text/plain; charset=utf-8'
   return 'application/octet-stream'

package/spec-yatsu/src/filing.ts

@@ -0,0 +1,48 @@
+import { repoRoot, headSha } from '../../spec-cli/src/git.js'
+import { yatsuNodes } from './yatsu.js'
+import { appendReading, readReadings, type Reading } from './sidecar.js'
+import { putBlob } from './cache.js'
+
+export type FileResult = { ok: true; reading: Reading } | { ok: false; error: string }
+
+// the eval seam over DATA (no argv, no file paths): a caller with a verdict in hand — the HTTP eval route,
+// a programmatic filer — appends through the SAME seam the CLI uses. Optional evidence arrives as text (a
+// report referencing the clip by hash) → a transcript blob in the same content-addressed cache; the
+// evaluator is the human hand, manual@1. yatsu still runs nothing — this only records. The dashboard files
+// nothing through this: [[event-detail]] is read-side on readings.
+export function fileHumanReading(
+  nodeId: string,
+  input: { scenario: string; status: 'pass' | 'fail'; note?: string; transcript?: string; by?: string },
+): FileResult {
+  const root = repoRoot()
+  const node = yatsuNodes(root).find((n) => n.id === nodeId)
+  if (!node) return { ok: false, error: `no yatsu node '${nodeId}' (a node needs a yatsu.md)` }
+  const sc = node.scenarios.find((s) => s.name === input.scenario)
+  if (!sc) return { ok: false, error: `'${nodeId}' has no scenario '${input.scenario}'` }
+  if (input.status !== 'pass' && input.status !== 'fail') return { ok: false, error: 'status must be pass or fail' }
+  const blob = input.transcript ? putBlob(Buffer.from(input.transcript)) : null
+  const reading: Reading = {
+    scenario: sc.name,
+    codeSha: headSha(root),
+    ...(blob ? { evidence: [{ hash: blob, kind: 'transcript' as const }] } : {}),
+    evaluator: 'manual@1',
+    // the filing session (caller-passed — the human annotator has no reachable session, so it stays absent
+    // there and the eval-comment loop-in is silent, per [[mentions]])
+    ...(input.by ? { by: input.by } : {}),
+    verdict: { status: input.status, ...(input.note ? { note: input.note } : {}) },
+    ts: new Date().toISOString(),
+  }
+  appendReading(node.sidecarPath, reading)
+  return { ok: true, reading }
+}
+
+// The session that filed the LATEST reading for (node, scenario) — the ORIGINATOR an eval-comment thread
+// loops in on a reply ([[mentions]] implicit loop-in). Null when the node/scenario has no reading, or the
+// latest reading is legacy (no `by`). Store-agnostic: the caller resolves this id to a live session or nobody.
+export function evalReadingFiler(nodeId: string, scenario: string): string | null {
+  const root = repoRoot()
+  const node = yatsuNodes(root).find((n) => n.id === nodeId)
+  if (!node) return null
+  const forScenario = readReadings(node.sidecarPath).filter((r) => r.scenario === scenario)
+  return forScenario.length ? forScenario[forScenario.length - 1].by ?? null : null
+}

package/spec-yatsu/src/freshness.ts

@@ -1,29 +1,61 @@
-import { rowsFor, type DriftIndex, type HistoryIndex } from '../../spec-cli/src/git.js'
+import { ancestorsOf, inAncestors, type DriftIndex } from '../../spec-cli/src/git.js'
 import type { Reading } from './sidecar.js'
 import { isEvaluatorStale } from './evaluator.js'
+import { scenarioChangeCommits, type ScenarioIndex } from './scenariofresh.js'
 
 // the CODE axis is touch-based (DriftIndex), so a code-file rename is out of scope — the same blind spot lint's code-drift has
 
-export type StaleAxis = 'code' | 'scenario' | 'evaluator'
+export type StaleAxis = 'code' | 'scenario' | 'evaluator' | 'remark'
 
-// true iff some commit touched `path` strictly NEWER than `sinceSha`. An unknown `sinceSha` (a reading
-// taken off the current history — e.g. on a since-rebased commit) returns true: we can't prove freshness,
-// so we treat it as stale rather than silently pass.
+// the REMARK axis's input ([[remark-teeth]]): the teeth read only the resolvable bit + when it was resolved,
+// not the whole remark — so freshness stays a PURE function, fed the scenario's remark track at the call
+// sites (never reaching into the issue store). One signal per remark on the (node, scenario).
+export type RemarkSignal = { resolved: boolean; resolvedAt?: string }
+
+// the teeth (T1): a scenario is remark-stale unless EVERY remark is resolved AND this reading post-dates
+// every resolution. So an UNRESOLVED remark ages it; a RESOLVED remark keeps it stale until a reading taken
+// strictly after the resolve (reading.ts > resolvedAt) exists — you can't out-run a remark by re-measuring
+// before the resolve, nor clear it by passive receipt. A resolved bit with no timestamp stays conservatively
+// stale (defensive: resolveRemark always stamps one).
+export function remarkStale(reading: { ts: string }, remarks: RemarkSignal[]): boolean {
+  return remarks.some((r) => !r.resolved || !(r.resolvedAt && reading.ts > r.resolvedAt))
+}
+
+// true iff some commit touched `path` that is NOT an ancestor of `sinceSha` — i.e. it lies in
+// `sinceSha..HEAD` by true DAG reachability, never a log-position/date compare (which under-reports on
+// branchy history). ONE conservative rule for an off-history `sinceSha` — whether rebased away (orphan)
+// or on a reachable-but-unmerged branch: we can't prove freshness from HEAD's history, so it reads
+// stale rather than silently pass.
 export function changedSince(idx: DriftIndex, sinceSha: string, path: string): boolean {
-  const sp = idx.pos.get(sinceSha)
-  if (sp === undefined) return true
-  for (const h of idx.fileCommits.get(path) ?? []) {
-    const p = idx.pos.get(h)
-    if (p !== undefined && p < sp) return true   // smaller position = newer than the reading
+  const anc = ancestorsOf(idx, sinceSha)
+  if (!anc) return true
+  return (idx.fileCommits.get(path) ?? []).some((h) => !inAncestors(idx, anc, h))
+}
+
+// the code axis's DISPLAY detail: which governed files drifted since a reading, and by HOW MANY commits — so
+// a stale eval can say "EvalsFeed.jsx +3" instead of a bare "code moved". Same DAG reachability as
+// changedSince (a commit touching the file that is NOT an ancestor of the reading's sha lies in sinceSha..HEAD);
+// an off-history sinceSha counts every touch (conservative, matching changedSince's stale-rather-than-pass rule).
+// Reporting only — it never decides freshness (staleAxes does); it explains a decision already made.
+export function codeDrift(idx: DriftIndex, sinceSha: string, codeFiles: string[]): { file: string; behind: number }[] {
+  const anc = ancestorsOf(idx, sinceSha)
+  const out: { file: string; behind: number }[] = []
+  for (const f of codeFiles) {
+    const commits = idx.fileCommits.get(f) ?? []
+    const behind = anc ? commits.filter((h) => !inAncestors(idx, anc, h)).length : commits.length
+    if (behind > 0) out.push({ file: f, behind })
   }
-  return false
+  return out
 }
 
-// scenario freshness uses rowsFor (rename-followed content versions, like a spec node), not touch-based fileCommits, so a bare git-mv reparent isn't a change; off-history codeSha → stale
-function scenarioMoved(hidx: HistoryIndex, pos: Map<string, number>, sinceSha: string, yatsuPath: string): boolean {
-  const sp = pos.get(sinceSha)
-  if (sp === undefined) return true
-  return rowsFor(hidx, yatsuPath).some((v) => { const p = pos.get(v.hash); return p !== undefined && p < sp })
+// scenario freshness is PER-SCENARIO, not per-file: a reading stales only when ITS OWN scenario block moved
+// (edited/added/removed) in scenarioSha..HEAD, never when a sibling in the same yatsu.md did. Reads exactly
+// like the code axis's changedSince — the per-scenario change-commits ([[scenariofresh]], rename-followed so a
+// bare git-mv reparent isn't a change) tested for ancestry — off-history codeSha → conservatively stale.
+function scenarioMoved(scIdx: ScenarioIndex, didx: DriftIndex, sinceSha: string, yatsuPath: string, scenario: string): boolean {
+  const anc = ancestorsOf(didx, sinceSha)
+  if (!anc) return true
+  return scenarioChangeCommits(scIdx, yatsuPath, scenario).some((h) => !inAncestors(didx, anc, h))
 }
 
 export function staleAxes(
@@ -31,12 +63,14 @@ export function staleAxes(
   codeFiles: string[],
   yatsuPath: string,
   didx: DriftIndex,
-  hidx: HistoryIndex,
+  scIdx: ScenarioIndex,
+  remarks: RemarkSignal[] = [],
 ): StaleAxis[] {
   const axes: StaleAxis[] = []
   if (codeFiles.some((f) => changedSince(didx, reading.codeSha, f))) axes.push('code')
-  if (scenarioMoved(hidx, didx.pos, reading.codeSha, yatsuPath)) axes.push('scenario')
+  if (scenarioMoved(scIdx, didx, reading.codeSha, yatsuPath, reading.scenario)) axes.push('scenario')
   if (isEvaluatorStale(reading.evaluator)) axes.push('evaluator')
+  if (remarkStale(reading, remarks)) axes.push('remark')
   return axes
 }
 
@@ -45,7 +79,8 @@ export function isStale(
   codeFiles: string[],
   yatsuPath: string,
   didx: DriftIndex,
-  hidx: HistoryIndex,
+  scIdx: ScenarioIndex,
+  remarks: RemarkSignal[] = [],
 ): boolean {
-  return staleAxes(reading, codeFiles, yatsuPath, didx, hidx).length > 0
+  return staleAxes(reading, codeFiles, yatsuPath, didx, scIdx, remarks).length > 0
 }

package/spec-yatsu/src/proof.ts

@@ -23,6 +23,7 @@ export type ProofReading = {
   ts: string
   evidence:
     | { kind: 'image'; dataUri: string }
+    | { kind: 'video'; dataUri: string }
     | { kind: 'transcript'; text: string }
     | { kind: 'miss' }
     | { kind: 'none' }
@@ -78,7 +79,8 @@ export async function buildProofModel(id: string): Promise<ProofModel | null> {
   // root the eval context at the SESSION's worktree (its branch's readings/freshness), not the backend checkout which would show main's; specs stay backend-shared (paths/titles/hues), only readings + drift are per-worktree
   const wtPath = worktreePathForBranch(payload.branch)
   const ctxRoot = wtPath ?? repoRoot()
-  const ctx = evalContext(ctxRoot, specs, await driftIndex(ctxRoot), await historyIndex(ctxRoot))
+  const [didx, hidx] = await Promise.all([driftIndex(ctxRoot), historyIndex(ctxRoot)])
+  const ctx = await evalContext(ctxRoot, specs, didx, hidx)
 
   // enrich each changed file with its unified diff + full before/after content (derived from the session
   // worktree at the merge-base ↔ HEAD), so the proof can drill summary → diff → whole-file comparison with no
@@ -156,7 +158,6 @@ export async function buildProofModel(id: string): Promise<ProofModel | null> {
 function gateRows(p: NonNullable<Awaited<ReturnType<typeof reviewPayload>>>): ProofGate[] {
   const g = p.gates
   return [
-    { label: 'typecheck', ok: g.typecheck.ok, detail: g.typecheck.ok ? 'clean' : `${g.typecheck.errorCount} error(s)` },
     { label: 'lint', ok: g.lint.errorCount === 0, detail: `${g.lint.errorCount} error(s), ${g.lint.warningCount} warning(s)` },
     { label: 'merge', ok: !g.conflictsWithMain, detail: g.conflictsWithMain ? 'conflicts with main' : 'no conflict' },
     { label: 'ahead', ok: p.ahead > 0, detail: `${p.ahead} commit(s) ahead of main` },
@@ -198,6 +199,7 @@ async function toProofReading(r: EvalEntry): Promise<ProofReading> {
   const blob = readBlobByHash(r.blob)
   if (!blob.ok) return { ...base, evidence: { kind: 'miss' } }
   if (blob.mime.startsWith('image/')) return { ...base, evidence: { kind: 'image', dataUri: `data:${blob.mime};base64,${blob.bytes.toString('base64')}` } }
+  if (blob.mime.startsWith('video/')) return { ...base, evidence: { kind: 'video', dataUri: `data:${blob.mime};base64,${blob.bytes.toString('base64')}` } }
   return { ...base, evidence: { kind: 'transcript', text: blob.bytes.toString('utf8') } }
 }
 
@@ -306,11 +308,12 @@ function renderReading(r: ProofReading): string {
   const ev = r.evidence
   const body =
     ev.kind === 'image' ? `<img class="shot" src="${ev.dataUri}" alt="${esc(r.scenario)}">`
+    : ev.kind === 'video' ? `<video class="shot" src="${ev.dataUri}" controls preload="metadata"></video>`
     : ev.kind === 'transcript' ? `<pre class="transcript">${esc(ev.text)}</pre>`
     : ev.kind === 'miss' ? `<div class="noev">⌀ miss original file — the evidence bytes were pruned</div>`
     : `<div class="noev">attested without a capture</div>`
   const stale = r.fresh ? '' : `<span class="stale" title="${esc(r.staleAxes.join(', '))} changed since the reading">stale</span>`
-  const note = r.verdict?.status === 'note' && r.verdict.note ? `<div class="rnote"><b>note</b> ${esc(r.verdict.note)}</div>` : ''
+  const note = r.verdict?.note ? `<div class="rnote"><b>note</b> ${esc(r.verdict.note)}</div>` : ''
   return `<div class="reading">
     <div class="rhead">
       ${scoreBadge(r.score, r.fresh ? undefined : `stale: ${r.staleAxes.join(', ')}`)}
@@ -489,3 +492,86 @@ h2{margin:42px 0 16px;font-size:14px;letter-spacing:.14em;text-transform:upperca
 .glabel{font-weight:600;width:120px;color:#dbe6f2}.gdetail{color:var(--dim);font:12px/1 ui-monospace,monospace}
 footer{margin-top:48px;padding-top:20px;border-top:1px solid var(--line);color:var(--dim);font-size:12px;text-align:center}
 `
+
+// ---- the session EVAL model ([[review-proof]]'s interactive face) ----
+// The lean, TIERED counterpart of buildProofModel: the same worktree-rooted marshaling, but rows only —
+// no diff enrichment, no inlined evidence bytes (the dashboard's Eval tab rides the shared eval
+// components: blobs stream lazily from /api/yatsu/blob on open). Each reading carries `inSession`
+// (this session filed it, or its codeSha is one of the branch's own commits — a diagnostic session
+// that changed no code still owns the readings it filed at the merge-base) so the tab can lead with
+// what THIS session measured, ✦-marked, over the inherited baseline.
+export type SessionEvalNode = {
+  id: string
+  title: string
+  hue: number
+  desc: string
+  hasYatsu: boolean
+  uncoveredFrontend: boolean
+  scenarios: { name: string; expected: string; tags?: string[] }[]
+  // each reading carries the trunk eval-concern thread for its (node, scenario) ([[remark-teeth]] / directive
+  // 3): the server-side join (attached by evalTimeline as `EvalEntry.thread`), so the session tab's event
+  // detail reads the comment/remark track directly instead of re-matching a concern key client-side. Absent
+  // until the pair has its first remark.
+  evals: (EvalEntry & { inSession: boolean })[]
+}
+export type SessionEvals = {
+  id: string
+  node: string | null
+  branch: string | null
+  title: string
+  ahead: number
+  dirtyNonRuntime: number
+  gates: ProofGate[]
+  nodes: SessionEvalNode[]
+}
+
+export async function buildSessionEvals(id: string): Promise<SessionEvals | null> {
+  const payload = await reviewPayload(id)
+  if (!payload) return null
+  const specs = await loadSpecs()
+  const specById = new Map(specs.map((s) => [s.id, s]))
+  const wtPath = worktreePathForBranch(payload.branch)
+  const ctxRoot = wtPath ?? repoRoot()
+  const [didx, hidx] = await Promise.all([driftIndex(ctxRoot), historyIndex(ctxRoot)])
+  const ctx = await evalContext(ctxRoot, specs, didx, hidx)
+  // this session's own commits — the membership test behind `inSession`
+  const shas = wtPath ? new Set((await gitA(['-C', wtPath, 'rev-list', `${mainBranch()}..HEAD`])).split('\n').filter(Boolean)) : new Set<string>()
+
+  const ids = new Set<string>()
+  for (const f of payload.diff) { const nid = nodeForFile(f.path, specs, payload.node); if (nid) ids.add(nid) }
+  if (payload.node && specById.has(payload.node)) ids.add(payload.node)
+
+  const nodes: SessionEvalNode[] = []
+  for (const nid of ids) {
+    const spec = specById.get(nid)
+    const tl = await evalTimeline(nid, ctx)
+    nodes.push({
+      id: nid,
+      title: spec?.title ?? nid,
+      hue: spec?.hue ?? 210,
+      desc: spec?.desc ?? '',
+      hasYatsu: tl.hasYatsu,
+      uncoveredFrontend: !tl.hasYatsu && (spec?.code ?? []).some(isUiPath),
+      scenarios: tl.scenarios,
+      // the per-scenario trunk thread rides each reading as `EvalEntry.thread` (evalTimeline's overlay), so
+      // the event detail has the comment/remark track inline — no extra join here. A reading is the
+      // session's own when it filed it (`by`) OR when its codeSha is a branch commit — filing alone counts,
+      // else a session that measured without committing code reads as if it did nothing.
+      evals: tl.readings.map((r) => ({ ...r, inSession: r.by === id || shas.has(r.codeSha) })),
+    })
+  }
+  // nodes with in-session measurements lead, then the most-measured — the session's own evidence first.
+  nodes.sort((a, b) => (b.evals.filter((e) => e.inSession).length - a.evals.filter((e) => e.inSession).length) || (b.evals.length - a.evals.length))
+
+  const primary = payload.node && specById.has(payload.node) ? specById.get(payload.node)!.title : null
+  return {
+    id,
+    node: payload.node,
+    branch: payload.branch,
+    title: primary || payload.node || payload.branch || id.slice(0, 8),
+    ahead: payload.ahead,
+    dirtyNonRuntime: payload.dirtyNonRuntime,
+    gates: gateRows(payload),
+    nodes,
+  }
+}