@spexcode/spec-core 0.6.2 → 0.6.3

package/src/process-identity.ts

@@ -1,207 +0,0 @@
-import { randomUUID } from 'node:crypto'
-import { execFileSync } from 'node:child_process'
-import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
-import { platform } from 'node:os'
-import { dirname, join } from 'node:path'
-
-export type ProcessIdentity = { pid: number; startToken: string }
-
-export type ProcessAdapter = Readonly<{
-  platform: NodeJS.Platform
-  startToken(pid: number): string | null
-  processGroupId(pid: number): number | null
-  linuxSessionId(pid: number): number | null
-}>
-
-export type VerifiedDetachedRuntime = Readonly<ProcessIdentity & {
-  receiptVersion: 4
-  processGroupId: number
-  linuxSessionId?: number
-}>
-
-export type DetachedRuntimeVerification =
-  | { ok: true; identity: VerifiedDetachedRuntime }
-  | { ok: false; reason: string }
-
-type DetachedLaunchReceiptV4 = {
-  version: 4
-  kind: 'spexcode-detached-runtime'
-  pid: number
-  startToken: string
-  processGroupId: number
-  linuxSessionId?: number
-}
-
-export function parseProcStat(text: string): { ppid: number; processGroupId: number; sessionId: number; ticks: number; startToken: string; rssPages: number } {
-  const end = text.lastIndexOf(')')
-  if (end < 0) throw new Error('malformed proc stat')
-  const fields = text.slice(end + 2).trim().split(/\s+/)
-  if (fields.length < 22) throw new Error('short proc stat')
-  return {
-    ppid: Number(fields[1]),
-    processGroupId: Number(fields[2]),
-    sessionId: Number(fields[3]),
-    ticks: Number(fields[11]) + Number(fields[12]),
-    startToken: fields[19],
-    rssPages: Number(fields[21]),
-  }
-}
-
-export function processStartToken(pid: number, procRoot = '/proc'): string | null {
-  if (platform() === 'linux' || procRoot !== '/proc') {
-    try { return parseProcStat(readFileSync(join(procRoot, String(pid), 'stat'), 'utf8')).startToken }
-    catch { return null }
-  }
-  try {
-    const started = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], { encoding: 'utf8' }).trim()
-    return started || null
-  } catch { return null }
-}
-
-const procField = (pid: number, field: 'processGroupId' | 'sessionId'): number | null => {
-  try {
-    const stat = parseProcStat(readFileSync(join('/proc', String(pid), 'stat'), 'utf8'))
-    return stat[field]
-  } catch { return null }
-}
-
-const psProcessGroupId = (pid: number): number | null => {
-  try {
-    const value = Number(execFileSync('ps', ['-o', 'pgid=', '-p', String(pid)], { encoding: 'utf8' }).trim())
-    return Number.isInteger(value) && value > 0 ? value : null
-  } catch { return null }
-}
-
-export const hostProcessAdapter: ProcessAdapter = Object.freeze({
-  platform: platform(),
-  startToken: (pid) => processStartToken(pid),
-  processGroupId: (pid) => platform() === 'linux' ? procField(pid, 'processGroupId') : psProcessGroupId(pid),
-  linuxSessionId: (pid) => platform() === 'linux' ? procField(pid, 'sessionId') : null,
-})
-
-const exactKeys = (value: Record<string, unknown>, expected: string[]) => {
-  const actual = Object.keys(value).sort()
-  return actual.length === expected.length && actual.every((key, index) => key === expected[index])
-}
-
-const parseDetachedLaunchReceipt = (text: string, hostPlatform: NodeJS.Platform): DetachedLaunchReceiptV4 | null => {
-  let value: unknown
-  try { value = JSON.parse(text) } catch { return null }
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
-  const receipt = value as Record<string, unknown>
-  const keys = ['kind', 'pid', 'processGroupId', 'startToken', 'version', ...(hostPlatform === 'linux' ? ['linuxSessionId'] : [])].sort()
-  if (!exactKeys(receipt, keys) || receipt.version !== 4 || receipt.kind !== 'spexcode-detached-runtime' ||
-    !Number.isInteger(receipt.pid) || Number(receipt.pid) <= 0 || typeof receipt.startToken !== 'string' || !receipt.startToken ||
-    !Number.isInteger(receipt.processGroupId) || Number(receipt.processGroupId) <= 0 ||
-    (hostPlatform === 'linux' && (!Number.isInteger(receipt.linuxSessionId) || Number(receipt.linuxSessionId) <= 0))) return null
-  return receipt as DetachedLaunchReceiptV4
-}
-
-const observeDetachedRuntime = (pid: number, adapter: ProcessAdapter): DetachedRuntimeVerification => {
-  if (adapter.platform === 'win32') return { ok: false, reason: 'detached runtime identity is unsupported on win32' }
-  const startBefore = adapter.startToken(pid)
-  if (!startBefore) return { ok: false, reason: `PID ${pid} has no readable process-start identity` }
-  const processGroupId = adapter.processGroupId(pid)
-  if (processGroupId !== pid) return { ok: false, reason: `PID ${pid} is not its own process-group leader (pgrp=${processGroupId ?? 'unknown'})` }
-  let linuxSessionId: number | undefined
-  if (adapter.platform === 'linux') {
-    const sessionId = adapter.linuxSessionId(pid)
-    if (sessionId !== pid) return { ok: false, reason: `Linux PID ${pid} is not its own session leader (session=${sessionId ?? 'unknown'})` }
-    linuxSessionId = sessionId
-  }
-  const startAfter = adapter.startToken(pid)
-  if (!startAfter || startAfter !== startBefore)
-    return { ok: false, reason: `PID ${pid} process-start identity changed during detached-boundary verification` }
-  return {
-    ok: true,
-    identity: Object.freeze({
-      pid,
-      startToken: startAfter,
-      receiptVersion: 4,
-      processGroupId,
-      ...(linuxSessionId === undefined ? {} : { linuxSessionId }),
-    }),
-  }
-}
-
-export function verifyDetachedRuntime(pid: number, receiptFile: string, adapter: ProcessAdapter = hostProcessAdapter): DetachedRuntimeVerification {
-  let text: string
-  try { text = readFileSync(receiptFile, 'utf8') }
-  catch { return { ok: false, reason: 'detached launch receipt is missing or unreadable' } }
-  const receipt = parseDetachedLaunchReceipt(text, adapter.platform)
-  if (!receipt) return { ok: false, reason: 'detached launch receipt has the wrong version or shape' }
-  if (receipt.pid !== pid) return { ok: false, reason: `detached launch receipt names PID ${receipt.pid}, not ${pid}` }
-  if (receipt.processGroupId !== pid)
-    return { ok: false, reason: `detached launch receipt has wrong process group ${receipt.processGroupId} for PID ${pid}` }
-  if (adapter.platform === 'linux' && receipt.linuxSessionId !== pid)
-    return { ok: false, reason: `detached launch receipt has wrong Linux session ${receipt.linuxSessionId ?? 'missing'} for PID ${pid}` }
-  const live = observeDetachedRuntime(pid, adapter)
-  if (!live.ok) return live
-  if (live.identity.startToken !== receipt.startToken)
-    return { ok: false, reason: `PID ${pid} process-start identity does not match its detached launch receipt` }
-  return live
-}
-
-// The inverse question of verifyDetachedRuntime: not "is the recorded process running right now" but "is it
-// provably GONE". The two are not complements — a missing receipt, an unreadable identity, or a PID we never
-// recorded answers neither, and a caller that treats "unproven" as "dead" would retire a live runtime it can
-// simply no longer address. Only a recorded start identity that the live PID no longer matches (including a
-// PID that is not running at all) is proof of death.
-export function detachedRuntimeIsGone(pid: number, receiptFile: string, adapter: ProcessAdapter = hostProcessAdapter): boolean {
-  let receipt: DetachedLaunchReceiptV4 | null
-  try { receipt = parseDetachedLaunchReceipt(readFileSync(receiptFile, 'utf8'), adapter.platform) }
-  catch { return false }
-  if (!receipt || receipt.pid !== pid) return false
-  return adapter.startToken(pid) !== receipt.startToken
-}
-
-// A v3 scope is only a migration witness when every recorded and live Linux identity agrees. Readers never
-// call this: minting a v4 receipt belongs to the write admission path that needs the shared runtime.
-export function migrateLegacyDetachedRuntimeReceipt(
-  pid: number,
-  legacyScopeFile: string,
-  receiptFile: string,
-  adapter: ProcessAdapter = hostProcessAdapter,
-): boolean {
-  if (adapter.platform !== 'linux' || verifyDetachedRuntime(pid, receiptFile, adapter).ok) return false
-  let fields: string[]
-  try { fields = readFileSync(legacyScopeFile, 'utf8').trim().split(/\s+/) }
-  catch { return false }
-  const observed = observeDetachedRuntime(pid, adapter)
-  if (!observed.ok || observed.identity.linuxSessionId === undefined) return false
-  const expected = ['detached-v3', String(pid), observed.identity.startToken, String(observed.identity.processGroupId), String(observed.identity.linuxSessionId)]
-  if (fields.length !== expected.length || fields.some((field, index) => field !== expected[index])) return false
-  try { writeDetachedRuntimeReceipt(pid, receiptFile, adapter); return true }
-  catch { return false }
-}
-
-export function writeDetachedRuntimeReceipt(pid: number, receiptFile: string, adapter: ProcessAdapter = hostProcessAdapter): VerifiedDetachedRuntime {
-  const observed = observeDetachedRuntime(pid, adapter)
-  if (!observed.ok) throw new Error(`cannot prove detached shared runtime: ${observed.reason}`)
-  const receipt: DetachedLaunchReceiptV4 = {
-    version: 4,
-    kind: 'spexcode-detached-runtime',
-    pid,
-    startToken: observed.identity.startToken,
-    processGroupId: observed.identity.processGroupId,
-    ...(observed.identity.linuxSessionId === undefined ? {} : { linuxSessionId: observed.identity.linuxSessionId }),
-  }
-  mkdirSync(dirname(receiptFile), { recursive: true })
-  const tmp = `${receiptFile}.${process.pid}.${randomUUID()}.tmp`
-  let published = false
-  try {
-    writeFileSync(tmp, `${JSON.stringify(receipt)}\n`, { mode: 0o600 })
-    renameSync(tmp, receiptFile)
-    published = true
-    const verified = verifyDetachedRuntime(pid, receiptFile, adapter)
-    if (!verified.ok) throw new Error(`cannot verify detached shared runtime receipt: ${verified.reason}`)
-    return verified.identity
-  } catch (error) {
-    rmSync(tmp, { force: true })
-    if (published) rmSync(receiptFile, { force: true })
-    throw error
-  }
-}
-
-export const detachedRuntimeGenerationToken = (identity: VerifiedDetachedRuntime) =>
-  `detached-v4|${identity.pid}|${identity.startToken}|${identity.processGroupId}|${identity.linuxSessionId ?? '-'}`

package/src/project-identity.ts

@@ -1,73 +0,0 @@
-import { createHash } from 'node:crypto'
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
-import { basename, dirname, join } from 'node:path'
-import { spexcodeHome } from './project-store.js'
-import {
-  resolvedIdentityIcon, DEFAULT_GATEWAY_ICON, DEFAULT_PROJECT_ICON, requireIdentityChoice,
-} from './identity-presets.js'
-
-export type ResolvedIdentity = { title: string; icon: string }
-export type GatewayIdentitySource = { identity: ResolvedIdentity; revision: string }
-
-const revisionOf = (raw: string | null): string =>
-  createHash('sha256').update(raw === null ? 'missing' : `present\0${raw}`).digest('hex')
-
-function readObject(file: string): { value: Record<string, any>; raw: string | null } {
-  if (!existsSync(file)) return { value: {}, raw: null }
-  const raw = readFileSync(file, 'utf8')
-  let value: unknown
-  try { value = JSON.parse(raw) }
-  catch (e) { throw new Error(`malformed ${file}: ${(e as Error).message}`) }
-  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${file} must contain one top-level JSON object`)
-  return { value: value as Record<string, any>, raw }
-}
-
-export function resolveProjectIdentity(configRoot: string, canonicalRoot = configRoot): ResolvedIdentity {
-  const { value } = readObject(join(configRoot, 'spexcode.json'))
-  const dashboard = value.dashboard && typeof value.dashboard === 'object' && !Array.isArray(value.dashboard)
-    ? value.dashboard as Record<string, unknown>
-    : {}
-  const configuredTitle = typeof dashboard.title === 'string' ? dashboard.title.trim() : ''
-  return {
-    title: configuredTitle || basename(canonicalRoot),
-    icon: resolvedIdentityIcon(dashboard.icon, DEFAULT_PROJECT_ICON),
-  }
-}
-
-export const hostConfigPath = (): string => join(spexcodeHome(), 'config.json')
-
-export function readGatewayIdentity(): GatewayIdentitySource {
-  const { value, raw } = readObject(hostConfigPath())
-  const gateway = value.gateway && typeof value.gateway === 'object' && !Array.isArray(value.gateway)
-    ? value.gateway as Record<string, unknown>
-    : {}
-  return {
-    identity: { title: 'Projects', icon: resolvedIdentityIcon(gateway.icon, DEFAULT_GATEWAY_ICON) },
-    revision: revisionOf(raw),
-  }
-}
-
-export function writeGatewayIcon(icon: unknown, revision: string): GatewayIdentitySource {
-  const canonical = requireIdentityChoice(icon)
-  const file = hostConfigPath()
-  const current = readObject(file)
-  if (revision !== revisionOf(current.raw)) {
-    const error = new Error('host config changed on disk — reload before saving') as Error & { status?: number }
-    error.status = 409
-    throw error
-  }
-  const gateway = current.value.gateway && typeof current.value.gateway === 'object' && !Array.isArray(current.value.gateway)
-    ? current.value.gateway as Record<string, unknown>
-    : {}
-  const next = { ...current.value, gateway: { ...gateway, icon: canonical } }
-  const raw = `${JSON.stringify(next, null, 2)}\n`
-  mkdirSync(dirname(file), { recursive: true, mode: 0o700 })
-  const tmp = `${file}.${process.pid}.tmp`
-  try {
-    writeFileSync(tmp, raw, { mode: 0o600 })
-    renameSync(tmp, file)
-  } finally {
-    try { rmSync(tmp) } catch { /* rename consumed it / write never created it */ }
-  }
-  return { identity: { title: 'Projects', icon: canonical }, revision: revisionOf(raw) }
-}

package/src/project-store.ts

@@ -1,17 +0,0 @@
-import { homedir } from 'node:os'
-import { dirname, join } from 'node:path'
-
-// One pure identity seam for every project-scoped runtime consumer. Git discovery stays with callers;
-// once they have the shared common dir, sessions, materialize, history indexes, backends, and uninstall
-// all resolve the same top-level store.
-export function spexcodeHome(): string {
-  return process.env.SPEXCODE_HOME || join(homedir(), '.spexcode')
-}
-
-export function encodeProject(root: string): string {
-  return root.replace(/[/.]/g, '-')
-}
-
-export function projectRuntimeRoot(commonDir: string): string {
-  return join(spexcodeHome(), 'projects', encodeProject(dirname(commonDir)))
-}

package/src/resilience.ts

@@ -1,41 +0,0 @@
-import { existsSync } from 'node:fs'
-
-function describe(e: unknown): string {
-  return e instanceof Error ? e.message : String(e)
-}
-
-// run a per-worktree DETAIL read; on a throw, branch on whether the worktree DIRECTORY still exists.
-//   dir gone   → the worktree was genuinely removed mid-read → return null so the caller omits it.
-//   dir present → a flaky detail read (ENOENT race on a sibling file, or a git index/ref lock under a
-//                 concurrent merge) → return the caller's `degraded` row so an EXISTING worktree is NEVER
-//                 dropped from the board. read-failure != non-existence.
-// `dir` is the worktree path (the existence fact). Accepts a sync OR async fn — resolveLayout's overlay
-// read is async, listSessions' row read is sync; `degraded` is a sync raw-facts fallback.
-export async function guardWorktree<T>(dir: string, fn: () => T | Promise<T>, degraded: () => T): Promise<T | null> {
-  try {
-    return await fn()
-  } catch (e) {
-    if (!existsSync(dir)) {
-      console.warn(`spec-cli: worktree ${dir} gone from disk (removed mid-read), omitting: ${describe(e)}`)
-      return null
-    }
-    console.warn(`spec-cli: worktree ${dir} detail-read failed (transient/lock); serving degraded row: ${describe(e)}`)
-    return degraded()
-  }
-}
-
-// the last-resort process net: log an otherwise-fatal async throw and KEEP SERVING. Registering these
-// handlers is itself what overrides Node's default "print the stack and exit" — so the backend rides out
-// a transient race it didn't anticipate instead of dropping the public port. Idempotent (guarded) so a
-// double-install in one process can't stack duplicate handlers.
-let guardsInstalled = false
-export function installProcessGuards(): void {
-  if (guardsInstalled) return
-  guardsInstalled = true
-  process.on('unhandledRejection', (reason) => {
-    console.error(`spec-cli: unhandledRejection kept the server alive (investigate): ${reason instanceof Error ? reason.stack : describe(reason)}`)
-  })
-  process.on('uncaughtException', (err) => {
-    console.error(`spec-cli: uncaughtException kept the server alive (investigate): ${err?.stack || describe(err)}`)
-  })
-}

package/src/review/reviewFilters.js

@@ -1,324 +0,0 @@
-import { sessionHeadline, sessionPresent } from './session.js'
-import { effectiveTokens, tokenize } from './reviewQuery.js'
-
-// [[review-filters]]: one pure filter engine — the single home of Issues/Evals FIELD SEMANTICS. Domain
-// adapters below provide field values; surfaces provide only the state home and presentation: the
-// canonical pages parse their ONE visible token text ([[review-query]]) and bridge it here, the Spec
-// Information panes keep plain local state. Neither duplicates matching.
-
-const text = (value) => String(value ?? '').trim().toLocaleLowerCase()
-const values = (value) => (Array.isArray(value) ? value : value == null || value === '' ? [] : [value])
-const unique = (items) => [...new Set(items.flatMap(values).filter((value) => value != null && value !== '').map(String))]
-
-export const EVAL_FILTER_KIND = Object.freeze({
-  RESULT: 'result',
-  BLIND: 'blind',
-  UNMEASURED: 'unmeasured',
-  DANGLING: 'dangling',
-})
-
-export const evidenceList = (reading) =>
-  reading?.evidence?.length ? reading.evidence
-  : reading?.blob != null ? [{ hash: reading.blob, kind: reading.blobKind || 'image', state: reading.blobState || 'present' }]
-  : []
-
-export const kindsOf = (reading) => {
-  const evidence = evidenceList(reading)
-  if (!evidence.length) return ['note']
-  return ['video', 'image', 'transcript', 'data'].filter((kind) => evidence.some((item) => item.kind === kind))
-}
-
-const optionLabel = (t, key, fallback) => t ? t(key) : fallback
-const allOption = (t) => ({ value: '', label: optionLabel(t, 'reviewList.all', 'All') })
-const optionsFor = (items, facet, state, context, t) => {
-  const active = state[facet.key] != null && String(state[facet.key]) !== ''
-  // a fixed-value ENUM facet keeps its ACTIVE value as a real (checked) row even when no data carries
-  // it — an active facet must never hide its own off-switch; data-valued facets stay data-derived.
-  const found = facet.fixedValues
-    ? facet.fixedValues.filter((value) => facet.enumerateFixed
-      || (active && String(state[facet.key]) === String(value))
-      || items.some((item) => values(facet.values(item, context)).map(String).includes(String(value))))
-    : unique(items.map((item) => facet.values(item, context)))
-  const available = facet.available
-    ? facet.available(found, items, state, context)
-    : found.length >= (facet.minValues ?? 2)
-  if (!available && !active) return []
-  return [allOption(t), ...found.map((value) => ({
-    value,
-    label: facet.labelValue ? facet.labelValue(value, context) : value,
-  }))]
-}
-
-// A SPLIT section reports its count as two named buckets instead of one number. The predicate is BINARY
-// and applied to the section's own matched rows, so the buckets always re-add to that section's whole
-// population — a surface can lead with one half without the count quietly shrinking. The adapter alone
-// decides which sections split and on what axis; the engine invents no bucket.
-const splitCount = (matched, split, context) => {
-  const first = matched.filter((item) => split.is(item, context)).length
-  return { [split.keys[0]]: first, [split.keys[1]]: matched.length - first }
-}
-
-// the one reading rule for a section count, whichever shape the adapter declared.
-export const sectionTotal = (count) => (typeof count === 'number'
-  ? count
-  : Object.values(count ?? {}).reduce((sum, value) => sum + value, 0))
-
-export function filterReviewItems(items, state, config, context = {}) {
-  // `q` is one substring or an ARRAY of substrings (the token text's bare words/phrases), conjunctive;
-  // an `impossible` state (an unknown qualifier in the canonical text) honestly matches NOTHING.
-  const qs = values(state.q).map(text).filter(Boolean)
-  const faceted = state.impossible ? [] : items.filter((item) => (
-    qs.every((q) => config.search(item, context).some((value) => text(value).includes(q)))
-    && config.facets.every((facet) => {
-      const selected = state[facet.key]
-      return selected == null || selected === ''
-        || (facet.matches
-          ? facet.matches(item, selected, context)
-          : values(facet.values(item, context)).map(String).includes(String(selected)))
-    })
-  ))
-  const sectionValue = config.section && state[config.section.key]
-  const sectionMatch = (item, selected) => (config.section.matches
-    ? config.section.matches(item, selected, context)
-    : String(config.section.value(item, context)) === String(selected))
-  const shown = sectionValue == null || sectionValue === ''
-    ? faceted
-    : faceted.filter((item) => sectionMatch(item, sectionValue))
-  const sections = config.section
-    ? Object.fromEntries(config.section.options.map((option) => {
-      const matched = faceted.filter((item) => sectionMatch(item, option.value))
-      return [option.value, option.split && config.section.split
-        ? splitCount(matched, config.section.split, context)
-        : matched.length]
-    }))
-    : {}
-  const facets = Object.fromEntries(config.facets.map((facet) => [facet.key, {
-    key: facet.key,
-    label: optionLabel(context.t, facet.label, facet.key),
-    value: state[facet.key] || '',
-    options: optionsFor(items, facet, state, context, context.t),
-  }]))
-  return { state, faceted, shown, sections, facets }
-}
-
-export const reviewActorName = (actor) => String(actor || '').length > 22 ? `${String(actor).slice(0, 8)}…` : actor
-// the source-session PRESENCE join ([[live-session-filter]]): originator or any reply author still
-// resolves on the board — membership, never liveness.
-const issuePresent = (issue, sessions) => !!sessionPresent(sessions, issue.by)
-  || (Array.isArray(issue.replies) && issue.replies.some((reply) => sessionPresent(sessions, reply.by)))
-const presenceFacet = (valuesOf) => ({
-  key: 'session', label: 'reviewList.facetSession', fixedValues: ['present', 'missing'],
-  values: valuesOf,
-  labelValue: (value, { t }) => optionLabel(t, value === 'present' ? 'reviewList.sessionPresent' : 'reviewList.sessionMissing', value),
-})
-
-export function issueFilterState(raw = {}, { defaultSection = '' } = {}) {
-  const state = raw.state === 'closed' || raw.concluded === '1'
-    ? 'closed'
-    : raw.state || defaultSection
-  return {
-    q: raw.q || '', state, impossible: raw.impossible === true,
-    author: raw.author || '', store: raw.store || '', node: raw.node || '', label: raw.label || '',
-    session: raw.session || '',
-  }
-}
-
-const ISSUE_CONFIG = {
-  search: (issue) => [issue.id, issue.concern, issue.by, ...(issue.nodes || [])],
-  section: {
-    key: 'state',
-    value: (issue) => issue.status === 'open' ? 'open' : 'closed',
-    // open|closed are the lifecycle halves; a concrete concluded spelling (landed) matches that status
-    // honestly instead of pretending the enum is binary.
-    matches: (issue, selected) => (selected === 'open' ? issue.status === 'open'
-      : selected === 'closed' ? issue.status !== 'open' : issue.status === selected),
-    options: [{ value: 'open', label: 'reviewList.open' }, { value: 'closed', label: 'reviewList.closed' }],
-  },
-  facets: [
-    { key: 'author', label: 'reviewList.facetAuthor', values: (issue) => issue.by, labelValue: reviewActorName },
-    { key: 'store', label: 'reviewList.facetStore', values: (issue) => issue.store },
-    { key: 'node', label: 'reviewList.facetNode', values: (issue) => issue.nodes || [] },
-    { key: 'label', label: 'reviewList.facetLabel', values: (issue) => (issue.labels || []).map((label) => typeof label === 'string' ? label : label?.name), minValues: 1 },
-    presenceFacet((issue, { sessions }) => issuePresent(issue, sessions) ? 'present' : 'missing'),
-  ],
-}
-
-export function issueFilterModel(items, raw = {}, context = {}) {
-  const state = issueFilterState(raw, { defaultSection: context.defaultSection ?? '' })
-  const model = filterReviewItems(items, state, ISSUE_CONFIG, context)
-  model.section = {
-    key: 'state', label: optionLabel(context.t, 'reviewList.facetState', 'State'), value: state.state,
-    meaningful: Object.values(model.sections).filter((count) => sectionTotal(count) > 0).length > 1 || !!state.state,
-    options: [allOption(context.t), ...ISSUE_CONFIG.section.options.map((option) => ({
-      value: option.value,
-      label: optionLabel(context.t, option.label, option.value),
-      count: sectionTotal(model.sections[option.value]),
-    }))].filter((option, index, all) => index === 0 || option.count > 0 || option.value === state.state),
-  }
-  return model
-}
-
-const evalIsResult = (entry) => entry.filterKind === EVAL_FILTER_KIND.RESULT
-const verdictOf = (entry) => evalIsResult(entry)
-  ? (entry.verdict?.status || 'unscored')
-  : entry.filterKind === EVAL_FILTER_KIND.BLIND || entry.filterKind === EVAL_FILTER_KIND.UNMEASURED
-    ? 'unmeasured'
-    : 'unscored'
-const reviewStateOf = (entry) => (evalIsResult(entry) && entry.fresh && entry.humanOk ? 'reviewed' : 'current')
-// the ONE freshness axis of the Eval adapter — the facet's option values and the verdict sections' split
-// read it, so a chip and its Freshness menu can never disagree about what "stale" counts.
-const evalFresh = (entry) => entry.fresh === true
-const freshnessOf = (entry) => (evalIsResult(entry) ? (evalFresh(entry) ? 'fresh' : 'stale') : null)
-export const evalReviewState = (reading) => {
-  // an order-only row never had its freshness computed, so it has no verdict to report. Refuse it here
-  // rather than let its conservative placeholder be published as a measured `stalePass`/`staleFail`: the
-  // whole point of the deferred pass is that these rows exist only to establish sequence.
-  if (reading?.freshnessDeferred)
-    throw new Error(`eval row ${reading.scenario ?? '?'} has deferred freshness — it can order a list, never state a verdict`)
-  const status = reading?.verdict?.status
-  if (status !== 'pass' && status !== 'fail') return 'empty'
-  if (reading.fresh) return status
-  return status === 'pass' ? 'stalePass' : 'staleFail'
-}
-const shortSession = (value, sessions) => {
-  const session = sessions.find((item) => item.id === value)
-  if (session) return sessionHeadline(session)
-  return String(value || '').length > 22 ? `${String(value).slice(0, 8)}…` : value
-}
-
-export function evalFilterState(raw = {}, { defaultKind = 'all', defaultSection = '' } = {}) {
-  const legacyReview = raw.ok === '1' ? 'reviewed' : raw.ok
-  return {
-    q: raw.q || '', kind: raw.kind || defaultKind, impossible: raw.impossible === true,
-    verdict: raw.verdict || '', freshness: raw.freshness || '', node: raw.node || '', filer: raw.filer || '',
-    session: raw.session || '', review: raw.review || legacyReview || defaultSection,
-  }
-}
-
-const EVAL_CONFIG = {
-  search: (entry) => [entry.scenario, entry.node, entry.by, entry.evaluator],
-  section: {
-    key: 'verdict', value: verdictOf,
-    // A MEASURED verdict carries a reading, so it also carries freshness: its count splits into the fresh
-    // half and the stale half that still owes a re-measurement. The two halves re-add to the verdict's
-    // whole population — splitting reports the remeasurement debt, it never hides a row. `unmeasured` owns
-    // no reading and therefore no freshness axis, so it stays one honest number.
-    split: { keys: ['fresh', 'stale'], is: evalFresh },
-    options: [
-      { value: 'fail', label: 'reviewList.verdict.fail', split: true },
-      { value: 'pass', label: 'reviewList.verdict.pass', split: true },
-      { value: 'unmeasured', label: 'reviewList.verdict.unmeasured' },
-    ],
-  },
-  facets: [
-    {
-      key: 'review', label: 'reviewList.facetReview', fixedValues: ['current', 'reviewed'], enumerateFixed: true,
-      values: reviewStateOf,
-      labelValue: (value, { t }) => optionLabel(t, value === 'reviewed' ? 'reviewList.reviewed' : 'reviewList.needsReview', value),
-    },
-    {
-      key: 'freshness', label: 'reviewList.facetFreshness', minValues: 2,
-      values: (entry) => freshnessOf(entry) ?? [],
-      labelValue: (value, { t }) => optionLabel(t, `reviewList.freshness.${value}`, value),
-    },
-    {
-      key: 'kind', label: 'reviewList.facetKind', fixedValues: ['video', 'image'], minValues: 1,
-      values: (entry) => evalIsResult(entry) ? kindsOf(entry).filter((kind) => kind === 'video' || kind === 'image') : [],
-      matches: (entry, selected) => selected === 'all' || (evalIsResult(entry) && kindsOf(entry).includes(selected)),
-      labelValue: (value, { t }) => optionLabel(t, `evalsFeed.kind.${value}`, value),
-      available: (found, _items, state) => found.length > 0 || state.kind !== 'all',
-    },
-    { key: 'node', label: 'reviewList.facetNode', values: (entry) => entry.node },
-    {
-      key: 'filer', label: 'reviewList.facetFiler', values: (entry) => evalIsResult(entry) ? entry.by : [],
-      labelValue: (value, { sessions = [] }) => shortSession(value, sessions),
-    },
-    presenceFacet((entry, { sessions }) => (evalIsResult(entry)
-      ? (sessionPresent(sessions, entry.by) ? 'present' : 'missing')
-      : [])),
-  ],
-}
-
-export function evalFilterModel(items, raw = {}, context = {}) {
-  const state = evalFilterState(raw, {
-    defaultKind: context.defaultKind ?? 'all',
-    defaultSection: context.defaultSection ?? '',
-  })
-  const model = filterReviewItems(items, state, EVAL_CONFIG, context)
-  model.section = {
-    key: 'verdict', label: optionLabel(context.t, 'reviewList.facetVerdict', 'Verdict'), value: state.verdict,
-    meaningful: Object.values(model.sections).some((count) => sectionTotal(count) > 0) || !!state.verdict,
-    // the menu/popup face of the same sections keeps the verdict's WHOLE count: a compact radio row has no
-    // room for the split, and it must still agree with the list it filters.
-    options: [allOption(context.t), ...EVAL_CONFIG.section.options.map((option) => ({
-      value: option.value,
-      label: optionLabel(context.t, option.label, option.value),
-      count: sectionTotal(model.sections[option.value]),
-    }))].filter((option, index) => index === 0 || option.count > 0 || option.value === state.verdict),
-  }
-  const kindFacet = model.facets.kind
-  if (kindFacet.options.length) {
-    kindFacet.options = [
-      { value: 'all', label: optionLabel(context.t, 'evalsFeed.kind.all', 'All') },
-      ...kindFacet.options.filter((option) => option.value !== '').map((option) => ({ ...option })),
-    ]
-    kindFacet.value = state.kind
-  }
-  return model
-}
-
-export function filterMenuGroups(model, onChange, keys) {
-  return keys.map((key) => key === 'section' ? model.section : model.facets[key]).filter((facet) => (
-    facet?.meaningful !== false
-    && (facet?.options?.length > 1 || (facet?.value != null && facet.value !== '' && facet.value !== 'all'))
-  )).map((facet) => ({
-    key: facet.key,
-    label: facet.label,
-    value: facet.value,
-    active: facet.value != null && facet.value !== '' && facet.value !== 'all',
-    options: facet.options,
-    clearLabel: facet.value === 'all' ? null : undefined,
-    onChange: (value) => onChange({ [facet.key]: value || null }),
-  }))
-}
-
-// the CANONICAL pages' bridge ([[review-query]] → this engine): parse the ONE visible token text into
-// engine state. Bare words/phrases become conjunctive q substrings; duplicate qualifiers are last-wins;
-// a qualifier outside the page's map (or a wrong is: identity) marks the state IMPOSSIBLE — the token
-// stays verbatim in the text and the list honestly shows nothing. `scope:` maps to no filter: it picks
-// the DATA SOURCE upstream ([[evals-view]]), never a per-row predicate.
-const TOKEN_MAPS = {
-  issue: {
-    is: (v) => (v === 'issue' ? {} : null),
-    state: (v) => ({ state: v }),
-    store: (v) => ({ store: v }),
-    author: (v) => ({ author: v }),
-    node: (v) => ({ node: v }),
-    label: (v) => ({ label: v }),
-    session: (v) => ({ session: v }),
-  },
-  eval: {
-    is: (v) => (v === 'eval' ? {} : null),
-    state: (v) => ({ review: v }),
-    verdict: (v) => ({ verdict: v }),
-    freshness: (v) => ({ freshness: v }),
-    evidence: (v) => ({ kind: v }),
-    node: (v) => ({ node: v }),
-    filer: (v) => ({ filer: v }),
-    session: (v) => ({ session: v }),
-    scope: () => ({}),
-  },
-}
-
-export function tokenFilterState(text, domain) {
-  const map = TOKEN_MAPS[domain]
-  const state = { q: [] }
-  for (const token of effectiveTokens(tokenize(text))) {
-    if (token.key == null) { state.q.push(token.value); continue }
-    const toState = map[token.key]
-    const mapped = toState ? toState(token.value) : null
-    if (mapped == null) return { impossible: true, q: [] }
-    Object.assign(state, mapped)
-  }
-  return state
-}