spexcode 0.2.8 → 0.4.0

package/{spec-yatsu/src/yatsu.ts → spec-eval/src/scenarios.ts}

@@ -1,10 +1,11 @@
 import { readFileSync, readdirSync, existsSync } from 'node:fs'
 import { readFile, readdir } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
 import { join, relative, basename } from 'node:path'
 import { mintIds } from '../../spec-cli/src/specs.js'
 
-export const YATSU_FILE = 'yatsu.md'
-export const SIDECAR_FILE = 'yatsu.evals.ndjson'
+export const EVAL_FILE = 'eval.md'
+export const SIDECAR_FILE = 'evals.ndjson'
 
 export type Scenario = {
   name: string
@@ -16,11 +17,11 @@ export type Scenario = {
   related?: string[]
 }
 
-export type YatsuNode = {
+export type EvalNode = {
   id: string            // the node's CANONICAL spec id (leaf name, '_'-disambiguated on a leaf collision)
   dir: string           // absolute node directory
-  yatsuPath: string     // repo-relative path to yatsu.md — the SCENARIO freshness axis
-  sidecarPath: string   // absolute path to yatsu.evals.ndjson
+  evalPath: string     // repo-relative path to eval.md — the SCENARIO freshness axis
+  sidecarPath: string   // absolute path to evals.ndjson
   scenarios: Scenario[]
 }
 
@@ -32,7 +33,7 @@ const LIST_KEYS: readonly ScenarioKey[] = ['tags', 'code', 'related']
 // carried — kept (not dropped) so the validator can name a typo'd field instead of silently swallowing it.
 type RawItem = { fields: Partial<Record<ScenarioKey, string>>; unknownKeys: string[] }
 
-// tiny indentation parser for yatsu.md's frontmatter `scenarios:` block (no YAML dep), shared by parseScenarios and validateScenarios so they can't disagree; reports hasFrontmatter/hasKey so the validator can tell "none declared" from "malformed"
+// tiny indentation parser for eval.md's frontmatter `scenarios:` block (no YAML dep), shared by parseScenarios and validateScenarios so they can't disagree; reports hasFrontmatter/hasKey so the validator can tell "none declared" from "malformed"
 function walkScenarios(src: string): { hasFrontmatter: boolean; hasKey: boolean; items: RawItem[] } {
   const m = src.match(/^---\n([\s\S]*?)\n---/)
   if (!m) return { hasFrontmatter: false, hasKey: false, items: [] }
@@ -117,6 +118,20 @@ function assignField(cur: RawItem, kv: string, lines: string[], idx: number, key
 
 const unquote = (s: string) => s.replace(/^["'](.*)["']$/, '$1').trim()
 
+// @@@scenario contract hash - the deterministic content hash of a scenario's SEMANTIC text, stamped on each
+// reading at filing time ([[eval-core]]'s scenario freshness axis). Hashes ONLY the measurement contract —
+// description (what to measure) + expected (what zero loss looks like) — never name/tags/test/code/related.
+// Normalization (spec'd, don't drift): each field independently collapses every whitespace run (space, tab,
+// CR, LF) to a single space and trims its ends, so a prose re-wrap, an indent shift, CRLF churn or trailing
+// whitespace never changes the hash; the two normalized fields join with a single '\n' (neither can contain
+// one after normalization, so the join is unambiguous) and sha256-hex the UTF-8 bytes. The hash is pure text
+// over the parsed declaration — no git, no file position — so it is identical wherever and however the same
+// contract text is read.
+const normSemantic = (s: string) => s.replace(/\s+/g, ' ').trim()
+export function scenarioHash(s: Pick<Scenario, 'description' | 'expected'>): string {
+  return createHash('sha256').update(`${normSemantic(s.description)}\n${normSemantic(s.expected)}`, 'utf8').digest('hex')
+}
+
 // a scenario's optional list field (`code:`/`related:`) is a comma-separated path list (a YAML flow list
 // `[a, b]` or bare `a, b`, or a single path) — the tiny parser stays scalar-only, so it is split here.
 function parseCodeList(raw: string): string[] {
@@ -148,7 +163,7 @@ export function parseScenarios(src: string): Scenario[] {
 // disables only the membership check, never the ≥1-tag requirement.
 export function validateScenarios(src: string, tagLibrary: string[] = []): string[] {
   const { hasFrontmatter, hasKey, items } = walkScenarios(src)
-  if (!hasFrontmatter) return ['no frontmatter block — a yatsu.md must declare a `scenarios:` list']
+  if (!hasFrontmatter) return ['no frontmatter block — an eval.md must declare a `scenarios:` list']
   if (!hasKey) return ['frontmatter has no `scenarios:` key — declare at least one scenario']
   if (!items.length) return ['`scenarios:` declares no scenarios — add one (name + description + expected)']
   const errs: string[] = []
@@ -170,17 +185,17 @@ export function validateScenarios(src: string, tagLibrary: string[] = []): strin
     for (const u of it.unknownKeys) errs.push(`${label}: unknown field \`${u}\` (allowed: ${SCENARIO_KEYS.join(', ')})`)
     if (it.fields.name) counts.set(it.fields.name, (counts.get(it.fields.name) ?? 0) + 1)
   })
-  for (const [n, c] of counts) if (c > 1) errs.push(`duplicate scenario name '${n}' (${c}×) — names must be unique within a yatsu.md`)
+  for (const [n, c] of counts) if (c > 1) errs.push(`duplicate scenario name '${n}' (${c}×) — names must be unique within an eval.md`)
   return errs
 }
 
-// walk `.spec` for every dir holding a yatsu.md; the node id is its CANONICAL spec id ([[id-url-safe]]) —
+// walk `.spec` for every dir holding an eval.md; the node id is its CANONICAL spec id ([[id-url-safe]]) —
 // minted by the SAME rule as specs.ts's loader (mintIds: the leaf dir name, or on a leaf collision the
 // shortest globally-unique '_'-joined trailing suffix) over the SAME universe (every dir holding a spec.md,
-// not just the yatsu subset — a leaf that collides among spec nodes is disambiguated even when only one of
-// them measures). So the id yatsu answers to is exactly the id board/scan/search already print — never a
-// second, diverging bare-leaf scheme. A yatsu.md beside no spec.md keeps its leaf name (no spec id to align with).
-function assembleNodes(root: string, specDirs: string[], hits: { dir: string; src: string }[]): YatsuNode[] {
+// not just the eval subset — a leaf that collides among spec nodes is disambiguated even when only one of
+// them measures). So the id eval verbs answer to is exactly the id board/scan/search already print — never a
+// second, diverging bare-leaf scheme. An eval.md beside no spec.md keeps its leaf name (no spec id to align with).
+function assembleNodes(root: string, specDirs: string[], hits: { dir: string; src: string }[]): EvalNode[] {
   const specBase = join(root, '.spec')
   const ids = mintIds(specDirs.map((d) => relative(specBase, d).split(/[/\\]/)))
   const idByDir = new Map(specDirs.map((d, i) => [d, ids[i]]))
@@ -188,14 +203,14 @@ function assembleNodes(root: string, specDirs: string[], hits: { dir: string; sr
     .map(({ dir, src }) => ({
       id: idByDir.get(dir) ?? basename(dir),
       dir,
-      yatsuPath: relative(root, join(dir, YATSU_FILE)),
+      evalPath: relative(root, join(dir, EVAL_FILE)),
       sidecarPath: join(dir, SIDECAR_FILE),
       scenarios: parseScenarios(src),
     }))
     .sort((a, b) => a.id.localeCompare(b.id))
 }
 
-export function yatsuNodes(root: string): YatsuNode[] {
+export function evalNodes(root: string): EvalNode[] {
   const specDir = join(root, '.spec')
   const specDirs: string[] = []
   const hits: { dir: string; src: string }[] = []
@@ -205,17 +220,17 @@ export function yatsuNodes(root: string): YatsuNode[] {
     let ents
     try { ents = readdirSync(dir, { withFileTypes: true }) } catch { continue }
     if (existsSync(join(dir, 'spec.md'))) specDirs.push(dir)
-    if (existsSync(join(dir, YATSU_FILE))) hits.push({ dir, src: readFileSync(join(dir, YATSU_FILE), 'utf8') })
+    if (existsSync(join(dir, EVAL_FILE))) hits.push({ dir, src: readFileSync(join(dir, EVAL_FILE), 'utf8') })
     for (const e of ents) if (e.isDirectory()) stack.push(join(dir, e.name))
   }
   return assembleNodes(root, specDirs, hits)
 }
 
-// async twin of yatsuNodes for the HOT board build ([[board-cache]]): reading each yatsu.md through
+// async twin of evalNodes for the HOT board build ([[graph-cache]]): reading each eval.md through
 // fs/promises YIELDS the event loop between files, so the walk no longer stalls a `/health` probe in one
-// ~600ms uninterrupted stretch. Same output (canonical ids, id-sorted) as yatsuNodes; only buildBoard uses
+// ~600ms uninterrupted stretch. Same output (canonical ids, id-sorted) as evalNodes; only buildBoard uses
 // it, other callers keep the sync form.
-export async function yatsuNodesAsync(root: string): Promise<YatsuNode[]> {
+export async function evalNodesAsync(root: string): Promise<EvalNode[]> {
   const specDir = join(root, '.spec')
   const specDirs: string[] = []
   const hits: { dir: string; src: string }[] = []
@@ -225,25 +240,25 @@ export async function yatsuNodesAsync(root: string): Promise<YatsuNode[]> {
     let ents
     try { ents = await readdir(dir, { withFileTypes: true }) } catch { continue }
     if (existsSync(join(dir, 'spec.md'))) specDirs.push(dir)
-    if (existsSync(join(dir, YATSU_FILE))) hits.push({ dir, src: await readFile(join(dir, YATSU_FILE), 'utf8') })
+    if (existsSync(join(dir, EVAL_FILE))) hits.push({ dir, src: await readFile(join(dir, EVAL_FILE), 'utf8') })
     for (const e of ents) if (e.isDirectory()) stack.push(join(dir, e.name))
   }
   return assembleNodes(root, specDirs, hits)
 }
 
-export type YatsuResolution<T> = { ok: true; node: T } | { ok: false; ambiguous: boolean; error: string }
+export type EvalResolution<T> = { ok: true; node: T } | { ok: false; ambiguous: boolean; error: string }
 
-// resolve a user-supplied node ref against the yatsu set: an EXACT canonical id always wins; a bare leaf
-// name stays the convenience it always was while it names exactly ONE yatsu node; a leaf several nodes
+// resolve a user-supplied node ref against the measurable set: an EXACT canonical id always wins; a bare leaf
+// name stays the convenience it always was while it names exactly ONE measurable node; a leaf several nodes
 // share fails LOUD listing the candidate canonical ids — never an arbitrary first hit, so a reading can
 // only land on the node the caller actually named.
-export function resolveYatsuNode<T extends Pick<YatsuNode, 'id' | 'dir'>>(nodes: T[], ref: string): YatsuResolution<T> {
+export function resolveEvalNode<T extends Pick<EvalNode, 'id' | 'dir'>>(nodes: T[], ref: string): EvalResolution<T> {
   const exact = nodes.find((n) => n.id === ref)
   if (exact) return { ok: true, node: exact }
   const byLeaf = nodes.filter((n) => basename(n.dir) === ref)
   if (byLeaf.length === 1) return { ok: true, node: byLeaf[0] }
   if (byLeaf.length > 1) {
-    return { ok: false, ambiguous: true, error: `'${ref}' is ambiguous — ${byLeaf.length} yatsu nodes share that leaf name; use a canonical id: ${byLeaf.map((n) => n.id).sort().join(', ')}` }
+    return { ok: false, ambiguous: true, error: `'${ref}' is ambiguous — ${byLeaf.length} measurable nodes share that leaf name; use a canonical id: ${byLeaf.map((n) => n.id).sort().join(', ')}` }
   }
-  return { ok: false, ambiguous: false, error: `no yatsu node '${ref}' (a node needs a yatsu.md)` }
+  return { ok: false, ambiguous: false, error: `no measurable node '${ref}' (a node needs an eval.md)` }
 }

package/{spec-yatsu/src/proof.ts → spec-eval/src/sessioneval.ts}

@@ -10,9 +10,9 @@ import { isUiPath } from './cli.js'
 
 type ScoreState = 'pass' | 'fail' | 'stalePass' | 'staleFail' | 'empty' | null
 
-// one yatsu reading rendered for the proof: the latest measurement of one scenario, with its evidence
+// one eval reading rendered for the export: the latest measurement of one scenario, with its evidence
 // resolved to inline bytes (an image data-URI, or transcript text) so the document is self-contained.
-export type ProofReading = {
+export type ExportReading = {
   scenario: string
   expected: string
   verdict?: EvalEntry['verdict']
@@ -32,7 +32,7 @@ export type ProofReading = {
 }
 
 // patch ''/old·new null = nothing to show (added → no old, deleted → no new), past the enrichment cap (omitted), or too large (truncated)
-export type ProofFile = ReviewDiffFile & {
+export type ExportFile = ReviewDiffFile & {
   patch: string
   oldText: string | null
   newText: string | null
@@ -41,24 +41,24 @@ export type ProofFile = ReviewDiffFile & {
 }
 
 // one changed spec node: its diff slice (the files this node owns that the session touched) joined with its
-// measured loss (latest reading per scenario). A frontend node with no yatsu.md is an honest blind spot.
-export type ProofNode = {
+// measured loss (latest reading per scenario). A frontend node with no eval.md is an honest blind spot.
+export type ExportNode = {
   id: string
   title: string
   hue: number
   desc: string
-  files: ProofFile[]
+  files: ExportFile[]
   additions: number
   deletions: number
-  hasYatsu: boolean
+  hasEvalFile: boolean
   uncoveredFrontend: boolean
   score: ScoreState
-  readings: ProofReading[]
+  readings: ExportReading[]
 }
 
-export type ProofGate = { label: string; ok: boolean; detail: string }
+export type ExportGate = { label: string; ok: boolean; detail: string }
 
-export type ProofModel = {
+export type ExportModel = {
   id: string
   node: string | null
   branch: string | null
@@ -66,14 +66,14 @@ export type ProofModel = {
   generatedAt: string
   ahead: number
   dirtyNonRuntime: number
-  gates: ProofGate[]
-  score: { passed: number; total: number; fresh: number }   // the yatsu summary across all nodes
-  nodes: ProofNode[]
-  otherFiles: ProofFile[]        // changed files no spec node claims
+  gates: ExportGate[]
+  score: { passed: number; total: number; fresh: number }   // the eval summary across all nodes
+  nodes: ExportNode[]
+  otherFiles: ExportFile[]        // changed files no spec node claims
 }
 
 // null when no session has that id (route → 404).
-export async function buildProofModel(id: string): Promise<ProofModel | null> {
+export async function buildExportModel(id: string): Promise<ExportModel | null> {
   const payload = await reviewPayload(id)
   if (!payload) return null
   const specs = await loadSpecs()
@@ -89,7 +89,7 @@ export async function buildProofModel(id: string): Promise<ProofModel | null> {
   // extra fetch. Capped at MAX_ENRICHED_FILES so a huge changeset can't bloat the page; the rest keep their
   // row but say so (omitted), never silently blank.
   const base = wtPath ? (await gitA(['-C', wtPath, 'merge-base', mainBranch(), 'HEAD'])).trim() : ''
-  const enriched = new Map<string, ProofFile>()
+  const enriched = new Map<string, ExportFile>()
   let budget = MAX_ENRICHED_FILES
   for (const f of payload.diff) {
     if (wtPath && base && budget > 0) { enriched.set(f.path, await enrichFile(wtPath, base, f)); budget-- }
@@ -97,8 +97,8 @@ export async function buildProofModel(id: string): Promise<ProofModel | null> {
   }
 
   // group the session's real changes (merge-base diff) by the spec node that owns each file.
-  const byNode = new Map<string, ProofFile[]>()
-  const otherFiles: ProofFile[] = []
+  const byNode = new Map<string, ExportFile[]>()
+  const otherFiles: ExportFile[] = []
   for (const f of payload.diff) {
     const nid = nodeForFile(f.path, specs, payload.node)
     const pf = enriched.get(f.path)!
@@ -108,13 +108,13 @@ export async function buildProofModel(id: string): Promise<ProofModel | null> {
   // the session's primary node always appears, even if it has no file in the diff yet.
   if (payload.node && specById.has(payload.node) && !byNode.has(payload.node)) byNode.set(payload.node, [])
 
-  const nodes: ProofNode[] = []
+  const nodes: ExportNode[] = []
   let passed = 0, total = 0, fresh = 0
   for (const [nid, files] of byNode) {
     const spec = specById.get(nid)
     const tl = await evalTimeline(nid, ctx)
     const latest = declaredLatest(tl)
-    const readings = await Promise.all(latest.map(toProofReading))
+    const readings = await Promise.all(latest.map(toExportReading))
     for (const r of latest) {
       total++
       if (r.fresh) fresh++
@@ -128,9 +128,9 @@ export async function buildProofModel(id: string): Promise<ProofModel | null> {
       files,
       additions: files.reduce((a, f) => a + f.additions, 0),
       deletions: files.reduce((a, f) => a + f.deletions, 0),
-      hasYatsu: tl.hasYatsu,
-      uncoveredFrontend: !tl.hasYatsu && (spec?.code ?? []).some(isUiPath),
-      score: nodeScore(tl.hasYatsu, latest),
+      hasEvalFile: tl.hasEvalFile,
+      uncoveredFrontend: !tl.hasEvalFile && (spec?.code ?? []).some(isUiPath),
+      score: nodeScore(tl.hasEvalFile, latest),
       readings,
     })
   }
@@ -156,8 +156,8 @@ export async function buildProofModel(id: string): Promise<ProofModel | null> {
   }
 }
 
-// the gate checklist, derived from the cockpit payload's gates (the SAME numbers `spex review` prints).
-function gateRows(p: NonNullable<Awaited<ReturnType<typeof reviewPayload>>>): ProofGate[] {
+// the gate checklist, derived from the cockpit payload's gates (the SAME numbers `spex session review` prints).
+function gateRows(p: NonNullable<Awaited<ReturnType<typeof reviewPayload>>>): ExportGate[] {
   const g = p.gates
   return [
     { label: 'lint', ok: g.lint.errorCount === 0, detail: `${g.lint.errorCount} error(s), ${g.lint.warningCount} warning(s)` },
@@ -170,7 +170,7 @@ function gateRows(p: NonNullable<Awaited<ReturnType<typeof reviewPayload>>>): Pr
 // gitA returns '' for a missing path — exactly the added/deleted (and best-effort rename) side; each side capped to MAX_FILE_BYTES
 const MAX_ENRICHED_FILES = 60
 const MAX_FILE_BYTES = 200_000
-async function enrichFile(wtPath: string, base: string, f: ReviewDiffFile): Promise<ProofFile> {
+async function enrichFile(wtPath: string, base: string, f: ReviewDiffFile): Promise<ExportFile> {
   const run = (args: string[]) => gitA(['-C', wtPath, '-c', 'core.quotePath=false', ...args])
   const [patchRaw, oldRaw, newRaw] = await Promise.all([
     run(['diff', '-M', `${base}..HEAD`, '--', f.path]),
@@ -190,9 +190,9 @@ async function enrichFile(wtPath: string, base: string, f: ReviewDiffFile): Prom
 }
 
 // resolve a reading's evidence to inline bytes so the proof is a self-contained file: an image → a base64
-// data-URI; a transcript → its text; the cache miss / no-capture states pass through. yatsu owns the bytes
+// data-URI; a transcript → its text; the cache miss / no-capture states pass through. the eval cache owns the bytes
 // (the content-addressed cache) — the proof only asks for them by hash.
-async function toProofReading(r: EvalEntry): Promise<ProofReading> {
+async function toExportReading(r: EvalEntry): Promise<ExportReading> {
   const base = {
     scenario: r.scenario, expected: r.expected, verdict: r.verdict, fresh: r.fresh,
     staleAxes: r.staleAxes, score: readingScore(r), evaluator: r.evaluator, ts: r.ts,
@@ -223,7 +223,7 @@ function latestPerScenario(readings: EvalEntry[]): EvalEntry[] {
 
 // the DECLARED scenarios' latest reading — the SAME declared-bounded computation every other eval face reads
 // (score.jsx's scenarioStates for the node badge and the eval tab). A reading whose scenario is no longer in
-// yatsu.md is residual: the append-only sidecar still carries it, but it is not current loss, so it must not
+// eval.md is residual: the append-only sidecar still carries it, but it is not current loss, so it must not
 // become a proof reading card, a passed/total tick, or a node score. The proof was the one face driven by the
 // readings that happen to exist rather than the scenarios that are declared — this bounds it like the rest, so
 // a retired scenario's stale reading can't make the proof disagree with the dashboard (phantom card, off ribbon).
@@ -246,8 +246,8 @@ function readingScore(r: EvalEntry): ScoreState {
 
 // worst-first aggregate over the latest reading per scenario: any fresh fail → fail; else any stale → grey
 // (✗ if any stale last-failed, else ✓); else any unscored scenario → empty; else every scenario fresh-passes.
-export function nodeScore(hasYatsu: boolean, latest: EvalEntry[]): ScoreState {
-  if (!hasYatsu) return null
+export function nodeScore(hasEvalFile: boolean, latest: EvalEntry[]): ScoreState {
+  if (!hasEvalFile) return null
   if (!latest.length) return 'empty'
   if (latest.some((r) => r.fresh && verdictMark(r) === 'cross')) return 'fail'
   const stale = latest.filter((r) => !r.fresh && verdictMark(r))
@@ -258,9 +258,9 @@ export function nodeScore(hasYatsu: boolean, latest: EvalEntry[]): ScoreState {
 
 // ---- file → node mapping ----
 
-// which spec node owns a changed file: a file inside a node's directory (its spec.md / yatsu.md / sidecar)
+// which spec node owns a changed file: a file inside a node's directory (its spec.md / eval.md / sidecar)
 // belongs to the NEAREST such node; otherwise the node whose governed `code:` claims it (exact path,
-// directory prefix, or `*` glob — the same matching `spex yatsu scan --changed` uses). A shared file is
+// directory prefix, or `*` glob — the same matching `spex eval lint --changed` uses). A shared file is
 // governed by MANY nodes (ordinary composition); when the session has a primary node that also governs it,
 // attribute it THERE so a node/<id> session's stake in cli.ts/index.ts groups under its own node, not
 // whichever sibling sorts first.
@@ -324,7 +324,7 @@ function verdictBadge(v: EvalEntry['verdict']): string {
   return `<span class="verdict note" title="${esc(v.note ?? '')}">≈ note</span>`
 }
 
-function renderReading(r: ProofReading): string {
+function renderReading(r: ExportReading): string {
   const ev = r.evidence
   const body =
     ev.kind === 'image' ? `<img class="shot" src="${ev.dataUri}" alt="${esc(r.scenario)}">`
@@ -333,9 +333,9 @@ function renderReading(r: ProofReading): string {
     : ev.kind === 'data' ? `<pre class="transcript data">${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 stale = r.fresh ? '' : `<span class="stale" title="${esc(r.staleAxes.join(', '))} changed since this eval">stale</span>`
   const note = r.verdict?.note ? `<div class="rnote"><b>note</b> ${esc(r.verdict.note)}</div>` : ''
-  return `<div class="reading">
+  return `<div class="eval-entry">
     <div class="rhead">
       ${scoreBadge(r.score, r.fresh ? undefined : `stale: ${r.staleAxes.join(', ')}`)}
       <span class="scenario">${esc(r.scenario)}</span>
@@ -359,7 +359,7 @@ function renderPatch(patch: string): string {
   }).join('')
 }
 
-function renderFile(f: ProofFile): string {
+function renderFile(f: ExportFile): string {
   const row = `<span class="fstatus ${esc(f.status)}">${esc(f.status)}</span> <span class="fpath">${esc(f.path)}</span> <span class="fnum"><span class="add">+${f.additions}</span> <span class="del">−${f.deletions}</span></span>`
   if (f.omitted) return `<div class="file flat"><div class="frow">${row}<span class="note">diff omitted — large changeset</span></div></div>`
   if (!f.patch && f.oldText == null && f.newText == null) return `<div class="file flat"><div class="frow">${row}</div></div>`
@@ -372,14 +372,14 @@ function renderFile(f: ProofFile): string {
     <div class="file-body">${f.patch ? `<div class="patch">${renderPatch(f.patch)}</div>` : '<div class="note">no textual diff</div>'}${cmp}</div></details>`
 }
 
-function renderNode(n: ProofNode): string {
+function renderNode(n: ExportNode): string {
   const stat = `<span class="diffstat"><span class="add">+${n.additions}</span> <span class="del">−${n.deletions}</span> · ${n.files.length} file(s)</span>`
   const fileList = n.files.length ? `<div class="files">${n.files.map(renderFile).join('')}</div>` : ''
   let proof: string
   if (n.readings.length) proof = n.readings.map(renderReading).join('')
-  else if (n.uncoveredFrontend) proof = `<div class="blindspot">⚠ a frontend node with no yatsu.md — no loss signal measured. Give it a scenario so this change can be proven.</div>`
-  else if (n.hasYatsu) proof = `<div class="blindspot">declares scenarios but has no reading yet — measure with <code>spex yatsu eval ${esc(n.id)}</code></div>`
-  else proof = `<div class="noev">no measurable surface (no yatsu.md)</div>`
+  else if (n.uncoveredFrontend) proof = `<div class="blindspot">⚠ a frontend node with no eval.md — its loss is unmeasured. Give it a scenario so this change can be verified.</div>`
+  else if (n.hasEvalFile) proof = `<div class="blindspot">declares scenarios but has no eval yet — measure with <code>spex eval add ${esc(n.id)}</code></div>`
+  else proof = `<div class="noev">no measurable surface (no eval.md)</div>`
   return `<article class="node" style="--hue:${n.hue}">
     <div class="nhead">
       <span class="huedot"></span>
@@ -390,15 +390,15 @@ function renderNode(n: ProofNode): string {
     </div>
     ${n.desc ? `<div class="ndesc">${esc(n.desc)}</div>` : ''}
     ${fileList}
-    <div class="readings">${proof}</div>
+    <div class="eval-list">${proof}</div>
   </article>`
 }
 
-export function renderProofHtml(m: ProofModel): string {
+export function renderExportHtml(m: ExportModel): string {
   const idShort = m.id.slice(0, 8)
   const ribbon = [
     ...m.gates.map((g) => `<span class="chip ${g.ok ? 'ok' : 'bad'}" title="${esc(g.detail)}">${g.ok ? '✓' : '✗'} ${esc(g.label)}</span>`),
-    m.score.total ? `<span class="chip ${m.score.passed === m.score.total ? 'ok' : 'warn'}" title="scenarios fresh-passing (of those measured); ${m.score.fresh}/${m.score.total} fresh">★ ${m.score.passed}/${m.score.total} passing</span>` : `<span class="chip warn" title="no yatsu readings on the changed nodes">★ no measured loss</span>`,
+    m.score.total ? `<span class="chip ${m.score.passed === m.score.total ? 'ok' : 'warn'}" title="scenarios fresh-passing (of those measured); ${m.score.fresh}/${m.score.total} fresh">★ ${m.score.passed}/${m.score.total} passing</span>` : `<span class="chip warn" title="no evals filed on the changed nodes">★ no measured loss</span>`,
   ].join('')
   const gates = m.gates.map((g) => `<li class="${g.ok ? 'ok' : 'bad'}"><span class="gmark">${g.ok ? '✓' : '✗'}</span><span class="glabel">${esc(g.label)}</span><span class="gdetail">${esc(g.detail)}</span></li>`).join('')
   const otherBlock = m.otherFiles.length
@@ -409,12 +409,12 @@ export function renderProofHtml(m: ProofModel): string {
 <html lang="en"><head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<title>proof · ${esc(m.title)}</title>
+<title>evals · ${esc(m.title)}</title>
 <style>${STYLE}</style>
 </head><body>
-<main class="proof">
+<main class="evals">
   <header class="masthead">
-    <div class="eyebrow">SpexCode · review proof</div>
+    <div class="eyebrow">SpexCode · session eval export</div>
     <h1 class="claim">${esc(m.title)}</h1>
     <div class="meta">session <code>${esc(idShort)}</code>${m.branch ? ` · <code>${esc(m.branch)}</code>` : ''}${m.node ? ` · node <code>${esc(m.node)}</code>` : ''} · ${m.ahead} commit(s) · ${m.nodes.length} node(s) · <span class="ts">${esc(m.generatedAt)}</span></div>
     <div class="ribbon">${ribbon}</div>
@@ -428,12 +428,12 @@ export function renderProofHtml(m: ProofModel): string {
     <h2>Merge gates</h2>
     <ul class="gates">${gates}</ul>
   </section>
-  <footer>Generated by <code>spex review proof ${esc(idShort)}</code> — the optimizer's measured loss, presented for the merge decision. A spec is the loss; commits are the optimizer; yatsu is the evaluation.</footer>
+  <footer>Generated by <code>spex eval ls --session ${esc(idShort)} --export</code> — the optimizer's measured loss, presented for the merge decision. A spec is the loss; commits are the optimizer; eval keeps the score.</footer>
 </main>
 </body></html>`
 }
 
-// the document's inline stylesheet — dark, matching the board's palette and the yatsu score colours, so the
+// the document's inline stylesheet — dark, matching the board's palette and the eval score colours, so the
 // proof reads as one surface with the dashboard. Self-contained (no external font/asset).
 const STYLE = `
 :root{--bg:#0b0e14;--panel:#11161f;--panel2:#0e131b;--ink:#c9d4e3;--dim:#7c899c;--line:#1e2733;--accent:#4cc2a0;--green:#3fb950;--red:#f85149;--grey:#6e7b8c;--amber:#d29922}
@@ -441,7 +441,7 @@ const STYLE = `
 body{margin:0;background:var(--bg);color:var(--ink);font:15px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;-webkit-font-smoothing:antialiased}
 code,pre,.mono{font-family:ui-monospace,SFMono-Regular,"SF Mono",Menlo,Consolas,monospace}
 code{background:#0006;padding:.05em .35em;border-radius:4px;font-size:.88em;color:#aee1d2}
-.proof{max-width:920px;margin:0 auto;padding:40px 24px 80px}
+.evals{max-width:920px;margin:0 auto;padding:40px 24px 80px}
 .masthead{padding:30px 30px 26px;border:1px solid var(--line);border-radius:16px;background:radial-gradient(1200px 240px at 0% 0%,#16352c66,transparent),linear-gradient(160deg,#141b26,#0d121a);box-shadow:0 20px 60px -30px #000}
 .eyebrow{font:600 11px/1 ui-monospace,monospace;letter-spacing:.18em;text-transform:uppercase;color:var(--accent)}
 .claim{margin:14px 0 10px;font-size:30px;line-height:1.2;font-weight:700;color:#eef3fa;letter-spacing:-.01em}
@@ -485,8 +485,8 @@ h2{margin:42px 0 16px;font-size:14px;letter-spacing:.14em;text-transform:upperca
 .side-h{font:600 10px/1 ui-monospace,monospace;text-transform:uppercase;letter-spacing:.08em;color:var(--dim);padding:0 0 6px}
 .side pre{margin:0;padding:10px 12px;background:#05080d;border:1px solid var(--line);border-radius:8px;max-height:440px;overflow:auto;font:11px/1.5 ui-monospace,monospace;color:#aebccd;white-space:pre}
 .abs{color:var(--dim);font-style:italic}
-.readings{margin-top:8px}
-.reading{margin-top:14px;padding:14px 16px;border:1px solid var(--line);border-radius:10px;background:var(--panel2)}
+.eval-list{margin-top:8px}
+.eval-entry{margin-top:14px;padding:14px 16px;border:1px solid var(--line);border-radius:10px;background:var(--panel2)}
 .rhead{display:flex;align-items:center;gap:10px;flex-wrap:wrap}
 .scenario{font-weight:600;color:#dde7f1}
 .rmeta{margin-left:auto;font:11px/1 ui-monospace,monospace;color:var(--dim)}
@@ -515,10 +515,10 @@ h2{margin:42px 0 16px;font-size:14px;letter-spacing:.14em;text-transform:upperca
 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 —
+// ---- the session EVAL model ([[session-eval]]'s interactive face) ----
+// The lean, TIERED counterpart of buildExportModel: 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`
+// components: blobs stream lazily from /api/evidence 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.
@@ -527,7 +527,7 @@ export type SessionEvalNode = {
   title: string
   hue: number
   desc: string
-  hasYatsu: boolean
+  hasEvalFile: 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
@@ -543,7 +543,7 @@ export type SessionEvals = {
   title: string
   ahead: number
   dirtyNonRuntime: number
-  gates: ProofGate[]
+  gates: ExportGate[]
   nodes: SessionEvalNode[]
 }
 
@@ -572,8 +572,8 @@ export async function buildSessionEvals(id: string): Promise<SessionEvals | null
       title: spec?.title ?? nid,
       hue: spec?.hue ?? 210,
       desc: spec?.desc ?? '',
-      hasYatsu: tl.hasYatsu,
-      uncoveredFrontend: !tl.hasYatsu && (spec?.code ?? []).some(isUiPath),
+      hasEvalFile: tl.hasEvalFile,
+      uncoveredFrontend: !tl.hasEvalFile && (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

package/{spec-yatsu → spec-eval}/src/sidecar.ts

@@ -27,6 +27,12 @@ export type Evidence = { hash: string; kind: EvidenceKind }
 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
@@ -66,18 +72,28 @@ export function isJsonBlob(b: Buffer): boolean {
 
 // 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 two event kinds are told apart POSITIVELY — a retraction
-// carries `retracts`, a reading carries `codeSha`; neither is recognized by another field's absence. `by`
-// is the retracting session; `note` says why (a botched e2e filing, a wrong verdict).
+// `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 }
 
-// parse the sidecar RAW: one event per non-blank line — a Reading, or a Retraction (a line carrying a
-// string `retracts`). 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[] } {
+// 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[] = []
-  if (!existsSync(sidecarPath)) return { readings, retractions }
+  const oks: HumanOk[] = []
+  if (!existsSync(sidecarPath)) return { readings, retractions, oks }
   for (const line of readFileSync(sidecarPath, 'utf8').split('\n')) {
     const t = line.trim()
     if (!t) continue
@@ -85,10 +101,11 @@ export function readSidecar(sidecarPath: string): { readings: Reading[]; retract
       const r = JSON.parse(t)
       if (!r || typeof r.scenario !== 'string') continue
       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 */ }
   }
-  return { readings, retractions }
+  return { readings, retractions, oks }
 }
 
 // the retraction join, shared by every effective-view reader: drop each reading a retraction targets by
@@ -103,7 +120,7 @@ export function applyRetractions(readings: Reading[], retractions: Retraction[])
 // 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 yatsu-missing.
+// or the scenario honestly returns to eval-missing.
 export function readReadings(sidecarPath: string): Reading[] {
   const { readings, retractions } = readSidecar(sidecarPath)
   return applyRetractions(readings, retractions)
@@ -121,6 +138,21 @@ 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> {

package/{spec-yatsu → spec-eval}/src/timeline.ts

@@ -22,7 +22,7 @@ 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 yatsu.md
+// 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[] {