spexcode 0.1.6 → 0.2.1

package/spec-yatsu/src/scenariofresh.ts

@@ -0,0 +1,92 @@
+import { gitA, headSha } from '../../spec-cli/src/git.js'
+import { parseScenarios } from './yatsu.js'
+
+// @@@ per-scenario content freshness — the SCENARIO axis, sub-file
+// A yatsu.md holds many scenarios, but a reading measures ONE. yatsu-core's contract says "a scenario is the
+// unit of measurement, so its freshness is its OWN — two scenarios stale independently." Git has no sub-file
+// history, so we build it: for each scenario NAME in a yatsu.md, the commits where THAT scenario's block
+// content changed (added / removed / edited), rename-followed. `scenarioMoved` then reads exactly like the
+// code axis's `changedSince` — a pure ancestry lookup over this per-scenario commit list — so editing one
+// scenario never re-stales its siblings (the file-granular bug this replaces).
+
+const RS = '\x1e'
+
+// yatsuPath (head path) -> scenario name -> commit hashes that changed that scenario's block (newest-first)
+export type ScenarioIndex = Map<string, Map<string, string[]>>
+
+// the block content that stales a reading: everything a measurement is taken AGAINST, minus the name (the
+// join key — a renamed scenario is a remove+add, surfaced as a change-commit on each name). parseScenarios
+// already folds YAML block scalars, so a pure prose re-wrap yields the same string and does NOT stale.
+function blockContent(src: string): Map<string, string> {
+  const m = new Map<string, string>()
+  for (const s of parseScenarios(src)) {
+    m.set(s.name, JSON.stringify({ d: s.description, e: s.expected, t: s.tags ?? [], c: s.code ?? [], r: s.related ?? [], x: s.test ?? '' }))
+  }
+  return m
+}
+
+// the file's content-versions newest-first, each { hash, blocks }. Skips a version we can't read (git show
+// '') so an unreadable blob never fabricates a remove+re-add diff.
+async function fileVersions(root: string, headPath: string): Promise<{ hash: string; blocks: Map<string, string> }[]> {
+  // --follow + --name-only pairs each commit with the path the file had THERE, so `git show <hash>:<pathAtCommit>`
+  // works across reparents (yatsu.md moves when its node does). `-M` keeps a rename+edit's content.
+  const log = await gitA(['-C', root, '-c', 'core.quotePath=false', 'log', '-M', '--follow', `--format=${RS}%H`, '--name-only', '--', headPath])
+  const out: { hash: string; blocks: Map<string, string> }[] = []
+  for (const rec of log.split(RS)) {
+    const lines = rec.split('\n').map((l) => l.trim()).filter(Boolean)
+    if (!lines.length) continue
+    const hash = lines[0]
+    const pathAt = lines.slice(1).find((l) => l.endsWith('/yatsu.md') || l === 'yatsu.md') ?? headPath
+    const content = await gitA(['-C', root, 'show', `${hash}:${pathAt}`])
+    if (!content) continue
+    out.push({ hash, blocks: blockContent(content) })
+  }
+  return out
+}
+
+// per-scenario change-commits for one file: walk versions newest->oldest, attribute a commit to every
+// scenario whose block differs from the next-older version (undefined on either side = add/remove = a change).
+async function scenarioCommits(root: string, headPath: string): Promise<Map<string, string[]>> {
+  const versions = await fileVersions(root, headPath)
+  const commits = new Map<string, string[]>()
+  const push = (name: string, hash: string) => { const a = commits.get(name); if (a) a.push(hash); else commits.set(name, [hash]) }
+  for (let i = 0; i < versions.length; i++) {
+    const cur = versions[i].blocks
+    const older = versions[i + 1]?.blocks ?? new Map<string, string>()
+    for (const name of new Set([...cur.keys(), ...older.keys()])) {
+      if (cur.get(name) !== older.get(name)) push(name, versions[i].hash)
+    }
+  }
+  return commits
+}
+
+async function build(root: string, yatsuPaths: string[]): Promise<ScenarioIndex> {
+  const idx: ScenarioIndex = new Map()
+  const CONC = 8   // bound the git-show fan-out; the whole index is built once per HEAD then cached
+  for (let i = 0; i < yatsuPaths.length; i += CONC) {
+    const batch = yatsuPaths.slice(i, i + CONC)
+    const done = await Promise.all(batch.map((p) => scenarioCommits(root, p)))
+    batch.forEach((p, j) => idx.set(p, done[j]))
+  }
+  return idx
+}
+
+// HEAD-keyed LRU, mirroring historyIndex/driftIndex in git.ts: same head ⇒ same per-scenario history,
+// whatever the caller. Holds the in-flight promise so concurrent board builds share one build.
+const SLOTS = 16
+const cache = new Map<string, Promise<ScenarioIndex>>()
+export function scenarioIndex(root: string, yatsuPaths: string[]): Promise<ScenarioIndex> {
+  let head: string
+  try { head = headSha(root) } catch { return build(root, yatsuPaths) }
+  const hit = cache.get(head)
+  if (hit) { cache.delete(head); cache.set(head, hit); return hit }
+  const p = build(root, yatsuPaths)
+  p.catch(() => cache.delete(head))
+  cache.set(head, p)
+  while (cache.size > SLOTS) cache.delete(cache.keys().next().value!)
+  return p
+}
+
+export function scenarioChangeCommits(idx: ScenarioIndex, yatsuPath: string, scenario: string): string[] {
+  return idx.get(yatsuPath)?.get(scenario) ?? []
+}

package/spec-yatsu/src/sidecar.ts

@@ -1,32 +1,90 @@
 import { readFileSync, appendFileSync, existsSync } from 'node:fs'
 
-export type Verdict = { status: 'pass' | 'fail' | 'note'; note?: string }
+// 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 }
 
-// blobKind absent on a legacy reading → rendered as an image (every legacy capture was one)
+export type EvidenceKind = 'image' | 'transcript' | 'video'
+// one piece of a reading's evidence: a content-addressed blob (`hash`) tagged by `kind`. `video` is a
+// screenshot with a time axis — the same content-addressed blob, distinguished only by this tag.
+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. `evaluator` is WHO/WHAT measured (a tag like `manual@1`); `by` is the reachable
+// session behind the filing — two different axes.
 export type Reading = {
   scenario: string
   codeSha: string
-  blob: string | null
-  blobKind?: 'image' | 'transcript'
+  evidence?: Evidence[]
+  // legacy scalar evidence — read for old readings, never written by new filings.
+  blob?: string | null
+  blobKind?: EvidenceKind
+  timelineBlob?: string
   evaluator: string
+  by?: string
   verdict?: Verdict
   ts: string
 }
 
-// parse the sidecar: one Reading per non-blank line. 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 readReadings(sidecarPath: string): Reading[] {
-  if (!existsSync(sidecarPath)) return []
-  const out: Reading[] = []
+// 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 []
+}
+
+// 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). Deliberately NO `evaluator` field: an old reader's line filter
+// (which requires an evaluator string) skips a retraction entirely, so version skew degrades to "the
+// retraction isn't applied yet", never to a mis-rendered reading. `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[] } {
+  const readings: Reading[] = []
+  const retractions: Retraction[] = []
+  if (!existsSync(sidecarPath)) return { readings, retractions }
   for (const line of readFileSync(sidecarPath, 'utf8').split('\n')) {
     const t = line.trim()
     if (!t) continue
     try {
       const r = JSON.parse(t)
-      if (r && typeof r.scenario === 'string' && typeof r.evaluator === 'string') out.push(r as Reading)
+      if (!r || typeof r.scenario !== 'string') continue
+      if (typeof r.retracts === 'string') retractions.push(r as Retraction)
+      else if (typeof r.evaluator === 'string') readings.push(r as Reading)
     } catch { /* skip a malformed line */ }
   }
-  return out
+  return { readings, retractions }
+}
+
+// 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 yatsu-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
@@ -35,6 +93,12 @@ 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')
+}
+
 // 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/src/timeline.ts

@@ -0,0 +1,47 @@
+// step-timeline — the map from a moment in a video reading's clip 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); aligning the emitter's clock to the clip is the
+// emitter's own job. The timeline rides as a second content-addressed blob on the reading, never a new
+// ndjson column beyond the one hash.
+
+export type TimelineEvent = { tMs: number; step: string; node?: string }
+export type StepTimeline = { v: 1; events: TimelineEvent[] }
+
+const EVENT_KEYS = new Set(['tMs', 'step', 'node'])
+
+// validate LOUD — every violation named, [] when well-formed. The key set is closed (like the yatsu.md
+// scenario schema): a malformed timeline is rejected at filing time, never silently reshaped.
+export function validateTimeline(raw: unknown): string[] {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return ['timeline must be a JSON object { v, events }']
+  const errs: string[] = []
+  const o = raw as Record<string, unknown>
+  for (const k of Object.keys(o)) if (k !== 'v' && k !== 'events') errs.push(`unknown field \`${k}\` (allowed: v, events)`)
+  if (o.v !== 1) errs.push('`v` must be 1')
+  if (!Array.isArray(o.events)) { errs.push('`events` must be an array'); return errs }
+  let prev = -Infinity
+  o.events.forEach((e, i) => {
+    if (typeof e !== 'object' || e === null || Array.isArray(e)) { errs.push(`events[${i}] must be an object`); return }
+    const ev = e as Record<string, unknown>
+    for (const k of Object.keys(ev)) if (!EVENT_KEYS.has(k)) errs.push(`events[${i}]: unknown field \`${k}\` (allowed: tMs, step, node)`)
+    if (typeof ev.tMs !== 'number' || !Number.isFinite(ev.tMs) || ev.tMs < 0) {
+      errs.push(`events[${i}].tMs must be a finite number ≥ 0`)
+    } else {
+      if (ev.tMs < prev) errs.push(`events[${i}].tMs is out of order (the list is ordered by time)`)
+      prev = ev.tMs
+    }
+    if (typeof ev.step !== 'string' || !ev.step.trim()) errs.push(`events[${i}].step must be a non-empty string`)
+    if (ev.node !== undefined && (typeof ev.node !== 'string' || !ev.node.trim())) errs.push(`events[${i}].node must be a non-empty string when present`)
+  })
+  return errs
+}
+
+// the whole of "which step is this moment": the last event at or before T; null before the first event
+// (a plain player moment, no step to name — graceful, never an error).
+export function stepAt(events: TimelineEvent[], tMs: number): TimelineEvent | null {
+  let hit: TimelineEvent | null = null
+  for (const e of events) {
+    if (e.tMs <= tMs) hit = e
+    else break
+  }
+  return hit
+}

package/spec-yatsu/src/yatsu.ts

@@ -1,4 +1,5 @@
 import { readFileSync, readdirSync, existsSync } from 'node:fs'
+import { readFile, readdir } from 'node:fs/promises'
 import { join, relative, basename } from 'node:path'
 
 export const YATSU_FILE = 'yatsu.md'
@@ -8,6 +9,7 @@ export type Scenario = {
   name: string
   description: string
   expected: string
+  tags?: string[]
   test?: string
   code?: string[]
   related?: string[]
@@ -21,9 +23,9 @@ export type YatsuNode = {
   scenarios: Scenario[]
 }
 
-const SCENARIO_KEYS = ['name', 'description', 'expected', 'test', 'code', 'related'] as const
+const SCENARIO_KEYS = ['name', 'description', 'expected', 'tags', 'test', 'code', 'related'] as const
 type ScenarioKey = (typeof SCENARIO_KEYS)[number]
-const LIST_KEYS: readonly ScenarioKey[] = ['code', 'related']
+const LIST_KEYS: readonly ScenarioKey[] = ['tags', 'code', 'related']
 
 // a raw scenario item straight off the frontmatter walk: the known fields it set, plus any UNKNOWN keys it
 // carried — kept (not dropped) so the validator can name a typo'd field instead of silently swallowing it.
@@ -123,12 +125,14 @@ function parseCodeList(raw: string): string[] {
 export function parseScenarios(src: string): Scenario[] {
   return walkScenarios(src).items
     .map((it): Scenario => {
+      const tags = it.fields.tags ? parseCodeList(it.fields.tags) : []
       const code = it.fields.code ? parseCodeList(it.fields.code) : []
       const related = it.fields.related ? parseCodeList(it.fields.related) : []
       return {
         name: it.fields.name ?? '',
         description: it.fields.description ?? '',
         expected: it.fields.expected ?? '',
+        ...(tags.length ? { tags } : {}),
         ...(it.fields.test ? { test: it.fields.test } : {}),
         ...(code.length ? { code } : {}),
         ...(related.length ? { related } : {}),
@@ -137,18 +141,31 @@ export function parseScenarios(src: string): Scenario[] {
     .filter((s) => s.name)   // a scenario with no name is malformed — drop it (validateScenarios reports it)
 }
 
-export function validateScenarios(src: string): string[] {
+// `tagLibrary` is the closed vocabulary a scenario's `tags:` must draw from (config's `lint.scenarioTags`).
+// Every scenario needs ≥1 tag; each tag must be IN the library — an out-of-library tag is rejected LOUD with
+// the repair the user owns: pick an existing tag, or extend the library. An empty library (none configured)
+// 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 (!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[] = []
   const counts = new Map<string, number>()
+  const lib = tagLibrary.length ? ` (library: ${tagLibrary.join(', ')})` : ''
   items.forEach((it, idx) => {
     const label = it.fields.name ? `scenario '${it.fields.name}'` : `scenario #${idx + 1}`
     for (const k of ['name', 'description', 'expected'] as const) {
       if (!it.fields[k]?.trim()) errs.push(`${label}: missing required field \`${k}\``)
     }
+    const tags = it.fields.tags ? parseCodeList(it.fields.tags) : []
+    if (!tags.length) {
+      errs.push(`${label}: missing required field \`tags\` — every scenario needs ≥1 tag from the library${lib}; pick one, or add a new tag to lint.scenarioTags in spexcode.json to create it`)
+    } else if (tagLibrary.length) {
+      for (const t of tags) if (!tagLibrary.includes(t)) {
+        errs.push(`${label}: tag \`${t}\` is not in the configured tag library${lib} — use an existing tag, or add \`${t}\` to lint.scenarioTags in spexcode.json to create it`)
+      }
+    }
     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)
   })
@@ -179,3 +196,30 @@ export function yatsuNodes(root: string): YatsuNode[] {
   }
   return out.sort((a, b) => a.id.localeCompare(b.id))
 }
+
+// async twin of yatsuNodes for the HOT board build ([[board-cache]]): reading each yatsu.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 (id-sorted) as yatsuNodes; only buildBoard uses it, other
+// callers keep the sync form.
+export async function yatsuNodesAsync(root: string): Promise<YatsuNode[]> {
+  const specDir = join(root, '.spec')
+  const out: YatsuNode[] = []
+  const stack = existsSync(specDir) ? [specDir] : []
+  while (stack.length) {
+    const dir = stack.pop()!
+    let ents
+    try { ents = await readdir(dir, { withFileTypes: true }) } catch { continue }
+    if (existsSync(join(dir, YATSU_FILE))) {
+      const yatsuPath = relative(root, join(dir, YATSU_FILE))
+      out.push({
+        id: basename(dir),
+        dir,
+        yatsuPath,
+        sidecarPath: join(dir, SIDECAR_FILE),
+        scenarios: parseScenarios(await readFile(join(dir, YATSU_FILE), 'utf8')),
+      })
+    }
+    for (const e of ents) if (e.isDirectory()) stack.push(join(dir, e.name))
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id))
+}

package/spec-cli/src/relay.ts

@@ -1,28 +0,0 @@
-import { searchSpecs } from './search.js'
-import { loadSpecs } from './specs.js'
-
-export type RelayHit = { id: string; title: string; path: string; score: number; code: string[] }
-
-export async function relaySearch(query: string, opts: { limit?: number } = {}): Promise<RelayHit[]> {
-  const limit = opts.limit ?? 3
-  const hits = await searchSpecs(query, { limit })
-  if (!hits.length) return []
-  // one spec-index read; per node: its frontmatter `code:` governed paths (files/dirs/globs) + the tree shape.
-  const specs = await loadSpecs()
-  const codeById = new Map(specs.map((s) => [s.id, (s.code as string[]) ?? []]))
-  const childrenOf = new Map<string, string[]>()
-  for (const s of specs) if (s.parent) childrenOf.set(s.parent, [...(childrenOf.get(s.parent) ?? []), s.id])
-  const subtreeCode = (id: string): string[] => {
-    const own = codeById.get(id) ?? []
-    if (own.length) return own
-    const acc: string[] = []
-    const stack = [...(childrenOf.get(id) ?? [])]
-    while (stack.length) {
-      const c = stack.pop()!
-      acc.push(...(codeById.get(c) ?? []))
-      stack.push(...(childrenOf.get(c) ?? []))
-    }
-    return [...new Set(acc)]
-  }
-  return hits.map((h) => ({ id: h.id, title: h.title, path: h.path, score: h.score, code: subtreeCode(h.id) }))
-}

package/spec-cli/templates/spec/project/.config/scenario/spec.md

@@ -1,32 +0,0 @@
----
-title: scenario
-surface: slash
-status: active
-hue: 160
-kind: mutating
-desc: Enter Scenario mode — author, refine, and re-measure a node's yatsu.md loss scenarios as first-class, file-scoped units.
----
-You are in **Scenario mode** — a focused flow for managing a node's yatsu.md **scenarios** as first-class
-units of loss. A scenario is one declared way to measure a node's loss: a `name`, a `description` of what to
-check, the `expected` result that is zero loss, and optionally a `test` (a co-located runnable file) and
-`code` (the concrete repo files THIS scenario depends on — its own freshness axis). Your job is to **edit,
-create, and manage** these scenarios for the target node(s) — nothing else; do not write feature code.
-
-Work through the real `spex` surface, never by reverse-engineering files:
-
-1. **Read the schema and the node.** Run `spex guide yatsu` for the exact yatsu.md format. Read the target
-   node's `spec.md` (its present intent) and its governed `code:` files, plus its existing `yatsu.md` if any.
-   A scenario must measure what the SPEC promises, through the real product surface (YATU — You As The User),
-   not an internal helper chosen to make the proof easy.
-2. **Author or refine scenarios.** For a node with no yatsu.md, create one with at least one scenario. For an
-   existing one, sharpen weak scenarios and add missing coverage. Give a scenario its own `code:` list when it
-   depends on a specific subset of the node's files, so it goes stale independently of its siblings. Keep
-   names unique and the schema valid — `spex yatsu scan <node>` reports violations (`yatsu-schema`), and the
-   pre-commit gate rejects a malformed file, so fix every finding before committing.
-3. **Re-measure when the change warrants it.** If you changed a scenario or the code it measures, file a fresh
-   reading: measure through the product, then `spex yatsu eval <node> --scenario <name> (--pass|--fail|--note)
-   [--image <png>|--result <txt>]`. Use `spex yatsu show <node>` to read the timeline.
-4. **Commit spec + yatsu.md together** on the node's branch, then report what scenarios now exist and their
-   satisfaction status. Do not bundle unrelated edits.
-
-The node(s) to manage scenarios for: {{targets}}