spexcode 0.6.2 → 0.6.6

package/spec-eval/src/evaltab.ts

@@ -1,264 +0,0 @@
-import { relative, dirname } from 'node:path'
-import { repoRoot, driftIndex, historyIndex, commitReachable, 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 { evalNodes, scenarioCodeAxis, type EvalNode, type ScenarioTestReference } from './scenarios.js'
-import { readSidecar, applyRetractions, evidenceOf, isJsonBlob, humanOkFor, type Verdict, type EvidenceKind, type Retraction, type Reading, type HumanOk } from './sidecar.js'
-import type { RelationEntry } from '../../spec-cli/src/anchors.js'
-import { staleAxes, codeDrift, contentProbeFor, anchorProbeFor, type StaleAxis } from './freshness.js'
-import { scenarioIndex, type ScenarioIndex } from './scenariofresh.js'
-import { hasBlob, getBlob, MISS_BLOB } from './cache.js'
-
-export type EvidenceView = { hash: string; kind: EvidenceKind; state: 'present' | 'miss' }
-
-export type RemarkView = {
-  rid: string
-  ref: string             // `<thread-id>#<rid>` — the address `spex remark resolve`/`spex remark 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
-  evidence?: EvidenceView[]
-  blob: string | null
-  blobKind?: EvidenceKind
-  timelineBlob?: string
-  evaluator?: string
-  by?: string
-  verdict?: Verdict
-  ts: string
-  fresh: boolean
-  staleAxes: StaleAxis[]
-  // set by an order-only read, whose `fresh`/`staleAxes` are placeholders it never computed. A consumer
-  // that ignores the flag reads the CONSERVATIVE direction (stale), and evalReviewState refuses the row
-  // outright — so a deferred verdict can neither be published as fresh nor pass silently.
-  freshnessDeferred?: true
-  blobState: 'present' | 'miss' | 'none'
-  codeDrift?: { file: string; behind: number }[]
-  remarks?: RemarkView[]
-  thread?: Issue
-  humanOk?: { by: string; ts: string }
-}
-
-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 DanglingTrack = { scenario: string; threadId: string; thread: Issue; remarks: RemarkView[] }
-
-export type ScenarioInfo = { name: string; expected: string; tags?: string[]; test?: ScenarioTestReference; code?: string[] }
-
-export type EvalTimeline = {
-  node: string
-  hasEvalFile: boolean
-  scenarios: ScenarioInfo[]
-  readings: EvalEntry[]
-  retractions: Retraction[]
-  dangling: DanglingTrack[]
-}
-
-export type EvalContext = {
-  root: string
-  specs: Awaited<ReturnType<typeof loadSpecs>>
-  idx: DriftIndex
-  hidx: HistoryIndex
-  scidx: ScenarioIndex
-  ynodes: EvalNode[]
-  remarks: Map<string, RemarkTrack>
-}
-
-export async function evalContext(
-  root: string,
-  specs: Awaited<ReturnType<typeof loadSpecs>>,
-  idx: DriftIndex,
-  hidx: HistoryIndex,
-  remarks?: Map<string, RemarkTrack>,
-  ynodes?: EvalNode[],
-): Promise<EvalContext> {
-  const nodes = ynodes ?? evalNodes(root)
-  const scidx = await scenarioIndex(root, nodes.map((n) => n.evalPath))
-  return { root, specs, idx, hidx, scidx, ynodes: nodes, remarks: remarks ?? loadEvalRemarkTracks() }
-}
-
-// @@@ one read, one batch - the freshness engine's Git work is immutable-object work, so it is owned ONCE
-// per read rather than once per reading. evalTimelines is the plural the graph build actually wants: it
-// plans every node's rows first (pure fs + in-memory projection), primes the content and anchor probes with
-// the WHOLE demand set, then assembles. Singular evalTimeline is the one-id case of the same path.
-// @@@ `order` skips the FRESHNESS pass, not the rows - a caller that only needs to know WHICH scenarios are
-// in play and in what sequence (identity, filed time, measured-or-blind) pays for none of the probes: on a
-// 415-node scope the freshness pass is 25s and 1476 git children, the rows themselves are milliseconds.
-// Rows returned this way carry `freshnessDeferred` INSTEAD of `fresh`/`staleAxes`, and evalReviewState
-// refuses them loudly — an order row can never be mistaken for a measured verdict.
-export async function evalTimelines(ids: readonly string[], ctx?: EvalContext, opts: { order?: boolean } = {}): Promise<EvalTimeline[]> {
-  const root = ctx?.root ?? repoRoot()
-  const ynodes = ctx?.ynodes ?? evalNodes(root)
-  const specs = ctx?.specs ?? await loadSpecs()
-  const idx = ctx?.idx ?? await driftIndex(root)
-  const hidx = ctx?.hidx ?? await historyIndex(root)
-  const scidx = ctx?.scidx ?? await scenarioIndex(root, ynodes.map((n) => n.evalPath))
-  const tracks = ctx?.remarks ?? loadEvalRemarkTracks()
-  const probe = contentProbeFor(root)
-  const anchors = anchorProbeFor(root, idx)
-
-  type Row = { reading: Reading; axis: ReturnType<typeof scenarioCodeAxis> }
-  type Plan = { id: string; ynode?: EvalNode; codeEntries: RelationEntry[]; rows: Row[]; retractions: Retraction[]; oks: HumanOk[] }
-  const plans: Plan[] = ids.map((id) => {
-    const ynode = ynodes.find((n) => n.id === id)
-    if (!ynode) return { id, codeEntries: [], rows: [], retractions: [], oks: [] }
-    const codeEntries = specs.find((s) => dirname(s.path) === relative(root, ynode.dir))?.codeEntries ?? []
-    const byName = new Map(ynode.scenarios.map((s) => [s.name, s]))
-    const { readings, retractions, oks } = readSidecar(ynode.sidecarPath)
-    const rows = applyRetractions(readings, retractions).map((reading) => ({
-      reading, axis: scenarioCodeAxis(byName.get(reading.scenario)?.code, codeEntries),
-    }))
-    return { id, ynode, codeEntries, rows, retractions, oks }
-  })
-
-  // an order-only read stops HERE, before a single probe: the rows above are already the whole answer.
-  if (opts.order)
-    return plans.map((plan) => assembleTimeline(plan.id, plan.ynode, plan.rows, plan.retractions, plan.oks, {
-      idx, scidx, tracks, probe, anchors, order: true,
-    }))
-
-  // An off-history anchor is the only reading that needs a content verdict. Plan the population first so the
-  // probe can answer many anchor/HEAD pairs through bounded plural children instead of one child per anchor.
-  const contentDemands = plans.flatMap((plan) => plan.ynode
-    ? plan.rows.filter((row) => !commitReachable(idx, row.reading.codeSha))
-        .map((row) => ({ anchorSha: row.reading.codeSha, paths: row.axis.paths, evalPath: plan.ynode!.evalPath }))
-    : [])
-  if (probe.primeMany) await probe.primeMany(contentDemands)
-  else await Promise.all(contentDemands.map((row) => probe.prime?.(row.anchorSha, [...row.paths], row.evalPath)))
-  await anchors.prime?.(plans.flatMap((plan) => plan.rows.map((row) => ({ sinceSha: row.reading.codeSha, entries: row.axis.entries }))))
-  // the primes above only RECORDED which eval.md blocks the assemble step will compare; one batched pair of
-  // children answers the whole read's worth, the same shape the anchor prime above already has.
-  await probe.primeBlocks?.()
-
-  return plans.map((plan) => assembleTimeline(plan.id, plan.ynode, plan.rows, plan.retractions, plan.oks, {
-    idx, scidx, tracks, probe, anchors,
-  }))
-}
-
-export async function evalTimeline(id: string, ctx?: EvalContext): Promise<EvalTimeline> {
-  return (await evalTimelines([id], ctx))[0]
-}
-
-type AssembleDeps = {
-  idx: DriftIndex; scidx: ScenarioIndex; tracks: Map<string, RemarkTrack>
-  probe: ReturnType<typeof contentProbeFor>; anchors: ReturnType<typeof anchorProbeFor>
-  order?: boolean   // identity/sequence only — emit no freshness claim
-}
-function assembleTimeline(
-  id: string,
-  ynode: EvalNode | undefined,
-  rows: { reading: Reading; axis: ReturnType<typeof scenarioCodeAxis> }[],
-  retractions: Retraction[],
-  oks: HumanOk[],
-  { idx, scidx, tracks, probe, anchors, order }: AssembleDeps,
-): EvalTimeline {
-  if (!ynode) return { node: id, hasEvalFile: false, scenarios: [], readings: [], retractions: [], dangling: [] }
-  const byName = new Map(ynode.scenarios.map((s) => [s.name, s]))
-  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.tags?.length ? { tags: s.tags } : {}), ...(s.test ? { test: s.test } : {}),
-    ...(s.code?.length ? { code: s.code } : {}),
-  }))
-  const readings: EvalEntry[] = []
-  for (const { reading: r, axis } of rows) {
-    const sc = byName.get(r.scenario)
-    const axes = order ? [] : staleAxes(r, axis.entries, ynode.evalPath, idx, scidx,
-      remarksFor(r.scenario).map((rm) => ({ resolved: !!rm.resolved, resolvedAt: rm.resolvedAt })), probe, sc, anchors)
-    const drift = !order && axes.includes('code') ? codeDrift(idx, r.codeSha, axis.entries, probe) : []
-    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]
-    const okRow = humanOkFor(oks, r.scenario, r.ts)
-    readings.push({
-      scenario: r.scenario,
-      expected: byName.get(r.scenario)?.expected ?? '',
-      codeSha: r.codeSha,
-      ...(evidence.length ? { evidence } : {}),
-      blob: primary?.hash ?? null,
-      ...(primary ? { blobKind: primary.kind } : {}),
-      ...(r.timelineBlob ? { timelineBlob: r.timelineBlob } : {}),
-      ...(r.evaluator ? { evaluator: r.evaluator } : {}),
-      ...(r.by ? { by: r.by } : {}),
-      ...(r.verdict ? { verdict: r.verdict } : {}),
-      ts: r.ts,
-      fresh: !order && axes.length === 0,
-      staleAxes: axes,
-      ...(order ? { freshnessDeferred: true as const } : {}),
-      ...(drift.length ? { codeDrift: drift } : {}),
-      blobState: primary ? primary.state : 'none',
-      ...(threadFor(r.scenario) ? { thread: threadFor(r.scenario) } : {}),
-      ...(okRow ? { humanOk: { by: okRow.by, ts: okRow.ts } } : {}),
-    })
-  }
-  readings.reverse()
-  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 hosts = readings.filter((r) => r.scenario === track.scenario)
-    if (!hosts.length) {
-      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 = hosts[0]
-    for (const rm of track.remarks) {
-      const target = hosts.find((r) => r.codeSha === rm.targetCodeSha)
-      const host = target ?? latest
-      ;(host.remarks ??= []).push(toRemarkView(rm, track.threadId, !target))
-    }
-  }
-  return { node: id, hasEvalFile: true, scenarios, readings, retractions: [...retractions].reverse(), dangling }
-}
-
-const HEX64 = /^[0-9a-f]{64}$/
-
-export type BlobResult =
-  | { ok: true; bytes: Buffer; mime: string }
-  | { ok: false; reason: 'invalid' | 'miss'; message: string }
-
-export function readBlobByHash(hash: string, dir?: string): BlobResult {
-  if (!HEX64.test(hash)) return { ok: false, reason: 'invalid', message: 'bad evidence hash' }
-  const bytes = getBlob(hash, dir)   // undefined dir → the live cache (cache.ts default); a temp dir in tests
-  if (!bytes) return { ok: false, reason: 'miss', message: MISS_BLOB }
-  return { ok: true, bytes, mime: sniffBlobMime(bytes) }
-}
-
-export 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 isJsonBlob(b) ? 'application/json' : 'text/plain; charset=utf-8'
-  return 'application/octet-stream'
-}

package/spec-eval/src/filing.ts

@@ -1,39 +0,0 @@
-import { repoRoot, headSha } from '../../spec-cli/src/git.js'
-import { evalNodes, resolveEvalNode, scenarioHash } from './scenarios.js'
-import { appendReading, readReadings, isJsonBlob, type Reading, type EvidenceKind } from './sidecar.js'
-import { putBlob } from './cache.js'
-
-export type FileResult = { ok: true; reading: Reading } | { ok: false; error: string }
-
-export function fileHumanReading(
-  nodeId: string,
-  input: { scenario: string; status: 'pass' | 'fail'; note?: string; transcript?: string; by?: string },
-): FileResult {
-  const root = repoRoot()
-  const res = resolveEvalNode(evalNodes(root), nodeId)
-  if (!res.ok) return { ok: false, error: res.error }
-  const node = res.node
-  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 buf = input.transcript ? Buffer.from(input.transcript) : null
-  const blob = buf ? putBlob(buf) : null
-  const reading: Reading = {
-    scenario: sc.name,
-    codeSha: headSha(root),
-    scenarioHash: scenarioHash(sc),
-    ...(blob ? { evidence: [{ hash: blob, kind: (buf && isJsonBlob(buf) ? 'data' : 'transcript') as EvidenceKind }] } : {}),
-    ...(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 }
-}
-
-export function evalReadingFiler(nodeId: string, scenario: string, root: string = repoRoot()): string | null {
-  const res = resolveEvalNode(evalNodes(root), nodeId)
-  if (!res.ok) return null
-  const forScenario = readReadings(res.node.sidecarPath).filter((r) => r.scenario === scenario)
-  return forScenario.length ? forScenario[forScenario.length - 1].by ?? null : null
-}