@staix/agent-hub 0.34.0 → 0.35.0

package/src/hub/research-memory.ts

@@ -0,0 +1,68 @@
+import type { Counter, View } from "@staix/agent-mem";
+
+/**
+ * #1279: the `memory` block's counter figures for one task, derived from agent-mem's own machine-local counter rows (`CandidateStore.counters`) and the entries they name. The hub stores nothing for
+ * them: the sidecar already holds `rendered`, `delivered` and `cited` per `{entry, task, delivery}`. A figure is a number of distinct entries, never a note id or text.
+ *
+ * Unknown is null, never 0:
+ * - With no counter row for the task at all, nothing was observed (the sidecar was off or unreadable, the task was private, or the rows aged out), and every figure is null. "None rendered" and
+ *   "never observed" cannot be told apart from rows alone, so the first is not claimed.
+ * - `rendered`: distinct entries put into a delivery attributed to the task (briefs, recall prefaces).
+ * - `delivered`: of those, the ones whose delivery completed (journal acknowledgement). Null while none is known to have completed: a brief that never completes leaves it null.
+ * - `cited`: of the rendered entries, the ones a hub-screened done summary, message or `hub_remember` text named by `mem:<id>`. An id that was not rendered for the task is not counted. 0 is known
+ *   once something was rendered, because the citation paths ran over the same task.
+ * - `failsExposed`, `failsCited`: the same two over entries of kind `fail`; null when a rendered entry can no longer be read, since its kind is then unknown.
+ * - `failRetrySignal`: exposed fail notes whose `about` intersects the task's plan and that were not cited by approval. A signal for a reviewer to read, never an outcome: it does not say the
+ *   approach was retried.
+ * Ceiling: the sidecar keeps 10,000 counters per project for 90 days, so an old task can have lost rows (read as unknown); a citation outside the screened paths is not seen.
+ */
+export interface MemoryFigures {
+  rendered: number | null; delivered: number | null; cited: number | null;
+  failsExposed: number | null; failsCited: number | null; failRetrySignal: number | null;
+}
+export const UNKNOWN_MEMORY_FIGURES: Readonly<MemoryFigures> = Object.freeze({ rendered: null, delivered: null, cited: null, failsExposed: null, failsCited: null, failRetrySignal: null });
+
+export interface MemoryFigurePorts {
+  /** The counter rows of the project. */
+  counters: readonly Pick<Counter, "key" | "rendered" | "delivered" | "cited">[];
+  /** The task's key as the rows carry it (`taskKey(project, task)`). */
+  taskKey: string;
+  /** One entry's view, or undefined when it is hidden, gone or unreadable. */
+  view: (entryId: string) => Pick<View, "id" | "kind" | "about" | "supersededBy"> | undefined;
+  /** Of these fail notes, the ones whose `about` intersects the task's plan: the library's own `matchingPlanFails`. */
+  matchingPlan: <T extends Pick<View, "kind" | "about" | "supersededBy">>(fails: readonly T[]) => readonly T[];
+}
+
+const positive = (n: number | null | undefined): boolean => typeof n === "number" && n > 0;
+
+export function memoryFigures(ports: MemoryFigurePorts): MemoryFigures {
+  const mine = ports.counters.filter(row => row.key.task === ports.taskKey);
+  const entries = (field: "rendered" | "delivered" | "cited") => new Set(mine.filter(row => positive(row[field])).map(row => row.key.entryId));
+  const rendered = entries("rendered");
+  if (!rendered.size) return { ...UNKNOWN_MEMORY_FIGURES };
+  // A delivery or a citation of an entry the task was never shown is not part of the task's exposure.
+  const delivered = [...entries("delivered")].filter(id => rendered.has(id)).length;
+  const cited = new Set([...entries("cited")].filter(id => rendered.has(id)));
+  const views = [...rendered].map(id => ({ id, view: ports.view(id) }));
+  const readable = views.filter((v): v is { id: string; view: NonNullable<typeof v.view> } => v.view !== undefined);
+  const complete = readable.length === views.length;
+  const fails = readable.filter(v => v.view.kind === "fail");
+  const uncited = fails.filter(v => !cited.has(v.id)).map(v => v.view);
+  return {
+    rendered: rendered.size,
+    delivered: delivered || null,
+    cited: cited.size,
+    failsExposed: complete ? fails.length : null,
+    failsCited: complete ? fails.filter(v => cited.has(v.id)).length : null,
+    failRetrySignal: complete ? ports.matchingPlan(uncited).length : null,
+  };
+}
+
+/**
+ * The evidence port of the LIVE writer: it answers for the task being recorded and says unknown for every other task. `taskRecords` builds a record for every terminal task in the log and the live
+ * writer keeps one, so without this each approval would compute (terminal tasks in the log) figures, each reading the sidecar and the store, on the daemon thread (#1297 review). `read` is called
+ * at most once per port, for `only`. A backfill passes its reader directly: it wants every task.
+ */
+export function onlyTaskMemory(only: number, read: (task: number) => MemoryFigures): (task: number) => MemoryFigures {
+  return task => task === only ? read(task) : { ...UNKNOWN_MEMORY_FIGURES };
+}

package/src/hub/research-quality.ts

@@ -0,0 +1,118 @@
+import type { StampedEvent } from "./events.ts";
+import { familyOf as builtinFamilyOf } from "../adapters/registry.ts";
+import { nearestRank } from "./research-record.ts";
+import { latestTaskRecords, type ResearchRecord, type TaskRecord } from "./research.ts";
+
+/**
+ * #1277 (#44 AC0): the telemetry quality report that lets a dataset carry its own coverage. Everything is a count, a share or a duration over the records and the event
+ * log of one window; the report holds no peer text, no model prose and no path. Peer ids are reduced to families where a family is known (the caller passes `familyOf`), and a
+ * value that cannot be derived is null, never 0, so a reader can tell "no data" from "none happened".
+ */
+export const QUALITY_SCHEMA = "agent-hub.research-quality/v1";
+/** A quota gap is a silence between two readings of one peer longer than this. */
+export const QUOTA_GAP_MS = 60 * 60 * 1000;
+
+export interface FieldCoverage { n: number; unknown: number }
+export interface QuotaCoverage { readings: number; gaps: number; gapMs: number; stalenessP95Ms: number | null; clock: { event: number; measured: number } }
+export interface OutcomeCounts { approved: number; cancelled: number; firstPass: number; changesRequested: number }
+export interface QualityReport {
+  schema: typeof QUALITY_SCHEMA;
+  window: { since: string | null; until: string | null };
+  records: number;
+  /** Per v2 field: how many records carry a value and how many are unknown (null or absent). Blocks count per leaf. */
+  fields: Record<string, FieldCoverage>;
+  /** Quota readings per peer family: how many, the gaps over an hour, the 95th percentile of the time between readings, and where the reading's time came from. */
+  quota: Record<string, QuotaCoverage>;
+  /**
+   * Pauses and resumes per family, and `handoffs`: the owner moves a budget pause drove (a `reassigned` task event whose board reason is `budget`), counted once per move, so a task handed off twice counts twice.
+   * A pause that found no taker moves nothing and counts nothing. Null when the window holds no task event at all, since then the log cannot say whether anything moved (#802).
+   */
+  budget: { pauses: number; resumes: number; handoffs: number | null; byFamily: Record<string, { pauses: number; resumes: number }> };
+  /** Task and review outcomes per (peer family, class), by the family of the task's last owner. */
+  outcomes: Record<string, Record<string, OutcomeCounts>>;
+  /** Every event type seen in the window with its count, and the types this report knows that did not occur. */
+  events: { present: Record<string, number>; absent: string[] };
+  /** The share of attributed token increments by the attribution rule (#200) and the total; null when no tokens were counted. */
+  tokenAttribution: { total: number; share: Record<"delivery" | "single_open" | "unattributed", number | null> };
+}
+
+const FAMILY_FALLBACK = "unknown";
+/** The event types the report reasons about: the ones whose absence in a window means something. */
+export const EXPECTED_EVENTS = ["task", "tokens", "usage", "turn_end", "quota", "budget_pause", "budget_resume", "envelope", "memory_brief", "hub_start"] as const;
+
+/** Fields counted as one value although they are objects: the findings tally is known or not as a whole. */
+const WHOLE = new Set(["review.findings"]);
+const leaves = (value: unknown, prefix: string, out: Map<string, unknown>): void => {
+  if (value !== null && typeof value === "object" && !Array.isArray(value) && !WHOLE.has(prefix)) { for (const [key, child] of Object.entries(value)) leaves(child, prefix ? `${prefix}.${key}` : key, out); return; }
+  out.set(prefix, value);
+};
+/** The v2 blocks whose leaves are counted; v1 fields predate the report and are not unknown by design. */
+const BLOCKS = ["review", "delivery", "merge", "specs", "memory", "person", "handoffs"] as const;
+const SCALARS = ["stalls", "cohort", "declines", "escalations", "cancelCause"] as const;
+
+/** `since` and `until` are epoch ms; a record counts when its terminal time falls inside. */
+export function buildResearchQuality(records: readonly ResearchRecord[], events: readonly StampedEvent[], window: { since?: number; until?: number } = {}, familyOf: (peer: string) => string | undefined = () => undefined): QualityReport {
+  const from = window.since ?? 0, to = window.until ?? Infinity;
+  const family = (peer: string | undefined) => (peer ? familyOf(peer) : undefined) ?? builtinFamilyOf(peer ?? "") ?? FAMILY_FALLBACK;
+  const inside = (at: string | undefined | null) => { const t = at ? Date.parse(at) : NaN; return Number.isFinite(t) && t >= from && t <= to; };
+  // Outcomes count every task (a v1 row is an approved one); the v2 fields are counted over v2 rows only, since a v1 row never had them.
+  const tasks = latestTaskRecords(records).filter(r => inside(r.closedAt ?? r.approvedAt));
+  const v2 = tasks.filter(r => r.schema === "agent-hub.research/v2");
+  const fields: Record<string, FieldCoverage> = {};
+  /** Unknown is null, absent, or a closed vocabulary's own `unknown` member. */
+  const note = (name: string, value: unknown) => { const f = fields[name] ??= { n: 0, unknown: 0 }; f.n++; if (value === null || value === undefined || value === "unknown") f.unknown++; };
+  for (const r of v2) {
+    const seen = new Map<string, unknown>();
+    for (const block of BLOCKS) leaves((r as unknown as Record<string, unknown>)[block] ?? null, block, seen);
+    // A block that is absent from the record counts as unknown at its own name.
+    for (const block of BLOCKS) if (![...seen.keys()].some(k => k.startsWith(`${block}.`) || k === block)) seen.set(block, null);
+    for (const key of SCALARS) seen.set(key, (r as unknown as Record<string, unknown>)[key] ?? (key === "cancelCause" && r.outcome !== "cancelled" ? undefined : null));
+    for (const [name, value] of seen) {
+      if (name === "cancelCause" && r.outcome !== "cancelled") continue;
+      note(name, value);
+    }
+  }
+  const windowEvents = events.filter(e => { const t = Date.parse(e.at); return Number.isFinite(t) && t >= from && t <= to; });
+  const present: Record<string, number> = {};
+  const quota: Record<string, { times: number[]; measured: number; event: number }> = {};
+  const budget: QualityReport["budget"] = { pauses: 0, resumes: 0, handoffs: null, byFamily: {} };
+  const attribution: Record<string, number> = { delivery: 0, single_open: 0, unattributed: 0 };
+  let tokenTotal = 0;
+  for (const e of windowEvents) {
+    present[e.type] = (present[e.type] ?? 0) + 1;
+    if (e.type === "task") {
+      budget.handoffs ??= 0;
+      if (e.event === "reassigned" && e.reason === "budget") budget.handoffs++;
+    } else if (e.type === "quota") {
+      const fam = family(e.peer), q = quota[fam] ??= { times: [], measured: 0, event: 0 };
+      const measured = typeof e.measuredAt === "string" ? Date.parse(e.measuredAt) : NaN;
+      if (Number.isFinite(measured)) { q.measured++; q.times.push(measured); } else { q.event++; q.times.push(Date.parse(e.at)); }
+    } else if (e.type === "budget_pause" || e.type === "budget_resume") {
+      const fam = family(e.peer), row = budget.byFamily[fam] ??= { pauses: 0, resumes: 0 };
+      if (e.type === "budget_pause") { budget.pauses++; row.pauses++; } else { budget.resumes++; row.resumes++; }
+    } else if (e.type === "tokens" && Number.isFinite(e.n) && e.n > 0) {
+      tokenTotal += e.n; const rule = e.attribution === "delivery" || e.attribution === "single_open" ? e.attribution : "unattributed"; attribution[rule]! += e.n;
+    }
+  }
+  const quotaOut: Record<string, QuotaCoverage> = {};
+  for (const [fam, q] of Object.entries(quota)) {
+    const times = q.times.filter(Number.isFinite).sort((a, b) => a - b), gaps: number[] = [];
+    for (let i = 1; i < times.length; i++) gaps.push(times[i]! - times[i - 1]!);
+    const over = gaps.filter(g => g > QUOTA_GAP_MS);
+    quotaOut[fam] = { readings: times.length, gaps: over.length, gapMs: over.reduce((sum, g) => sum + g, 0), stalenessP95Ms: nearestRank(gaps, 0.95), clock: { event: q.event, measured: q.measured } };
+  }
+  const outcomes: QualityReport["outcomes"] = {};
+  for (const r of tasks) {
+    const fam = family(r.owners.at(-1)), cls = r.class ?? "unknown", row = (outcomes[fam] ??= {})[cls] ??= { approved: 0, cancelled: 0, firstPass: 0, changesRequested: 0 };
+    row[r.outcome]++; if (r.firstPass) row.firstPass++; row.changesRequested += r.changesRequested;
+  }
+  const share = (n: number): number | null => tokenTotal > 0 ? n / tokenTotal : null;
+  return {
+    schema: QUALITY_SCHEMA,
+    window: { since: window.since !== undefined ? new Date(window.since).toISOString() : null, until: window.until !== undefined && Number.isFinite(window.until) ? new Date(window.until).toISOString() : null },
+    records: tasks.length, fields: Object.fromEntries(Object.entries(fields).sort(([a], [b]) => a.localeCompare(b))),
+    quota: Object.fromEntries(Object.entries(quotaOut).sort(([a], [b]) => a.localeCompare(b))), budget, outcomes,
+    events: { present: Object.fromEntries(Object.entries(present).sort(([a], [b]) => a.localeCompare(b))), absent: EXPECTED_EVENTS.filter(type => !(type in present)) },
+    tokenAttribution: { total: tokenTotal, share: { delivery: share(attribution.delivery!), single_open: share(attribution.single_open!), unattributed: share(attribution.unattributed!) } },
+  };
+}

package/src/hub/research-record.ts

@@ -0,0 +1,279 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { MemoryFigures } from "./research-memory.ts";
+import type { PersonFigures } from "./person-figures.ts";
+import { cleanMergeCost } from "./cost-governance.ts";
+import { openHubDatabase } from "./db-schema.ts";
+import { taskSample, type MetricTask } from "./sdlc-metrics.ts";
+
+/**
+ * #1277: the closed, text-free blocks research record v2 adds to a task record, and the evidence they are folded from.
+ * Everything here is a count, a duration, a boolean or a member of a closed vocabulary. A value that cannot be derived is `null`
+ * and is counted as unknown by the quality report, never 0. Nothing is copied from a title, note, path, rationale, message body or
+ * check output: the readers below pick named closed fields out of the board history and the delivery journal and drop the rest.
+ */
+export const FINDING_PASSES = ["bugs", "security", "compliance"] as const;
+export type FindingPass = (typeof FINDING_PASSES)[number];
+const SEVERITIES = ["important", "nit"] as const;
+const DISPOSITIONS = ["open", "fixed", "false_positive", "accepted"] as const;
+const PLANNED_SCOPES = ["none", "delta", "full"] as const;
+/** A peer family or any other id-like value from a store: anything else is untrusted text and reads as unknown. */
+const ID = /^[a-z][a-z0-9-]{0,63}$/;
+export const closedId = (value: unknown): string | null => typeof value === "string" && ID.test(value) ? value : null;
+const count = (value: unknown): number | null => typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+const member = <T extends string>(values: readonly T[], value: unknown): T | undefined => (values as readonly string[]).includes(value as string) ? value as T : undefined;
+
+export interface FindingTally { important: number; nit: number; open: number; fixed: number; falsePositive: number; accepted: number }
+export type ReviewScope = "code" | "full" | "delta" | "none" | "unknown";
+export interface ReviewBlock {
+  /** Substantive verdicts: approvals and change requests that are not evidence-only. (`reviewRounds` on the record counts times the task went to review; this counts what came back.) */
+  rounds: number | null;
+  firstPass: boolean | null;
+  /** Distinct findings by pass, each at its last disposition; null when no verdict carried a structured report. */
+  findings: Record<FindingPass, FindingTally> | null;
+  reviewerFamily: string | null;
+  ownerFamily: string | null;
+  scope: ReviewScope;
+  evidenceOnly: number | null;
+  context: "fresh" | "continuing" | "unknown";
+  staleHeadReReviews: number | null;
+}
+export interface Quantiles { p50: number | null; p95: number | null }
+export interface DeliveryBlock {
+  /** Envelopes that named the task, from the events. */
+  count: number | null;
+  firstDeliveryMs: Quantiles;
+  needsReview: number | null; failed: number | null; discarded: number | null;
+  dropped: { fyi: number | null; hop: number | null };
+}
+export interface MergeBlock { ciRuns: number | null; ciReruns: number | null; githubReviews: number | null; doneToApprovedMs: number | null; approvedToMergedMs: number | null }
+export interface SpecsBlock { covering: number | null; unchanged: number | null; acked: number | null; errors: number | null }
+/** `rendered`, `delivered` and `cited` stay null until #1279 reports them. */
+export interface MemoryBlock {
+  briefs: number | null; briefNotes: number | null; fails: number | null; rendered: number | null; delivered: number | null; cited: number | null;
+  /** #1279: fail notes among the entries rendered for the task, how many of them were cited, and the exposed ones the plan touches that were not cited. A signal to read, never an outcome. */
+  failsExposed: number | null; failsCited: number | null; failRetrySignal: number | null;
+}
+/** #1278: what the person was asked and did for the task (docs/research.md); every part is null when the log does not cover the task, never 0. Shape and rules: `src/hub/person-figures.ts`. */
+export type PersonBlock = PersonFigures;
+export interface HandoffsBlock { in: number | null; out: number | null }
+export type CohortKind = "silent" | "advisory" | "none";
+export const CANCEL_CAUSES = ["cancelled", "declined", "escalated", "stale", "unknown"] as const;
+export type CancelCause = (typeof CANCEL_CAUSES)[number];
+
+/** One board history entry, reduced to the closed fields v2 reads. */
+export interface EvidenceEntry {
+  at: number; event: string;
+  evidenceOnly?: true; withheld?: true; sweep?: true;
+  reviewScope?: "code"; reviewContext?: "fresh" | "continuing"; reviewerFamily?: string;
+  requestHead?: string; verdictHead?: string; plannedScope?: (typeof PLANNED_SCOPES)[number];
+  findings?: { id: string; pass: FindingPass; severity: "important" | "nit"; disposition: (typeof DISPOSITIONS)[number] }[];
+  spec?: { complete: boolean; errors: number; unchanged: number; changed: number; acked: number };
+  /** An explicit closed cause recorded on a cancellation, never inferred from its note. */
+  cause?: CancelCause;
+}
+export interface EvidenceMerge { mergedAt: number | null; ciRuns: number | null; ciReruns: number | null; reviews: number | null }
+export interface EvidenceTask { id: number; history: EvidenceEntry[]; merge?: EvidenceMerge; handoffs?: { in: number; out: number } }
+export interface JournalRow { task: number; state: string; createdAt: number; updatedAt: number }
+export interface ResearchEvidence {
+  tasks: ReadonlyMap<number, EvidenceTask>;
+  /** Absent: the journal was not read, so every journal-derived field is unknown. */
+  /**
+   * `coveredAfter`: a delivery created strictly after this time is in `rows` if it ever existed; null when that cannot be established. The journal prunes its oldest-updated terminal rows beyond a
+   * cap and keeps unresolved rows, review-package receipts and retry parents, so the oldest surviving row is no watermark (an old protected row survives while newer ones are gone).
+   */
+  journal?: { rows: readonly JournalRow[]; coveredAfter: number | null };
+  /** Whether the board was read at all: without it every board-derived field is unknown, also for a task the map lacks. */
+  board: boolean;
+  familyOf?: (peer: string) => string | undefined;
+  /** #1279: the counter figures of one task from agent-mem's sidecar; absent (backfill, no sidecar) leaves every counter figure unknown. */
+  memory?: (task: number) => MemoryFigures;
+}
+export const NO_EVIDENCE: ResearchEvidence = { tasks: new Map(), board: false };
+
+const text = (value: unknown): Record<string, unknown> | undefined => value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+
+/**
+ * The closed cause a cancelled entry carries, or none. Only an exact member of `CANCEL_CAUSES` in a `cause` field counts. Today the board retains no such field (`Tasks.cancel` stores a free-text note and
+ * nothing closed), so every cancelled record reads `unknown`; a cause is never inferred from the note, from an earlier decline or escalation, or from who cancelled (ruling 2026-11-07 on #778).
+ */
+export function cancelCauseOf(raw: unknown): CancelCause | undefined {
+  const cause = text(raw)?.cause;
+  return typeof cause === "string" && (CANCEL_CAUSES as readonly string[]).includes(cause) && cause !== "unknown" ? cause as CancelCause : undefined;
+}
+
+/** One history entry (a `HistoryEntry` or its parsed JSON) as closed evidence; undefined when it has no usable time or event. */
+export function evidenceEntry(raw: unknown): EvidenceEntry | undefined {
+  const e = text(raw);
+  if (!e || typeof e.at !== "number" || !Number.isFinite(e.at) || e.at < 0 || typeof e.event !== "string" || e.event.length > 80) return undefined;
+  const out: EvidenceEntry = { at: e.at, event: e.event };
+  if (e.evidenceOnly === true) out.evidenceOnly = true;
+  if (e.withheld === true) out.withheld = true;
+  if (text(e.sweep)) out.sweep = true;
+  if (e.reviewScope === "code") out.reviewScope = "code";
+  if (e.reviewContext === "fresh" || e.reviewContext === "continuing") out.reviewContext = e.reviewContext;
+  const family = closedId(e.reviewerFamily);
+  if (family) out.reviewerFamily = family;
+  const cost = text(e.reviewCost), findings = text(e.reviewFindings);
+  if (typeof cost?.head === "string" && /^[0-9a-f]{40}$/.test(cost.head)) out.requestHead = cost.head;
+  const planned = member(PLANNED_SCOPES, text(cost?.review)?.scope);
+  if (planned) out.plannedScope = planned;
+  if (typeof findings?.head === "string" && /^[0-9a-f]{40}$/.test(findings.head)) out.verdictHead = findings.head;
+  if (Array.isArray(findings?.items)) {
+    out.findings = (findings.items as unknown[]).flatMap(item => {
+      const f = text(item), pass = member(FINDING_PASSES, f?.pass), severity = member(SEVERITIES, f?.severity), disposition = member(DISPOSITIONS, f?.disposition);
+      return f && typeof f.id === "string" && f.id.length <= 96 && pass && severity && disposition ? [{ id: f.id, pass, severity, disposition }] : [];
+    });
+  }
+  const spec = text(e.specReport);
+  if (spec) {
+    const list = (value: unknown) => Array.isArray(value) ? value.map(text).filter((row): row is Record<string, unknown> => !!row) : [];
+    const unchanged = list(spec.unchanged), changed = list(spec.changed);
+    out.spec = { complete: spec.complete === true, errors: count(spec.errors) ?? 0, unchanged: unchanged.length, changed: changed.length,
+      acked: unchanged.filter(row => typeof row.reason === "string" && row.reason.length > 0).length };
+  }
+  const cause = e.event === "cancelled" ? cancelCauseOf(e) : undefined;
+  if (cause) out.cause = cause;
+  return out;
+}
+
+/** A board task (live `Task` or a parsed row) as closed evidence. The title, detail, plan, refs and every note stay behind. */
+export function evidenceTask(raw: { id: number; history?: unknown; sdlc?: unknown }, handoffs?: { in: number; out: number }): EvidenceTask {
+  const history = (Array.isArray(raw.history) ? raw.history : []).flatMap(entry => { const e = evidenceEntry(entry); return e ? [e] : []; }).sort((a, b) => a.at - b.at);
+  const merge = text(text(raw.sdlc)?.merge);
+  let mergeEvidence: EvidenceMerge | undefined;
+  if (merge?.state === "merged") {
+    const cost = cleanMergeCost(merge.cost), at = cost?.mergedAt ?? (typeof merge.at === "number" && Number.isSafeInteger(merge.at) ? merge.at : null);
+    mergeEvidence = { mergedAt: at, ciRuns: cost?.ciRuns ?? null, ciReruns: cost?.ciReruns ?? null, reviews: cost?.reviews ?? null };
+  }
+  return { id: raw.id, history, ...(mergeEvidence ? { merge: mergeEvidence } : {}), ...(handoffs ? { handoffs } : {}) };
+}
+
+/** Deliveries of one task from the journal rows: only their state and two times, never an envelope body. */
+export function journalRow(task: unknown, state: unknown, createdAt: unknown, updatedAt: unknown): JournalRow | undefined {
+  const id = typeof task === "string" && /^[1-9]\d{0,9}$/.test(task) ? Number(task) : typeof task === "number" && Number.isSafeInteger(task) && task > 0 ? task : undefined;
+  return id !== undefined && typeof state === "string" && ID.test(state.replaceAll("_", "-")) && typeof createdAt === "number" && typeof updatedAt === "number" && Number.isFinite(createdAt) && Number.isFinite(updatedAt)
+    ? { task: id, state, createdAt, updatedAt } : undefined;
+}
+
+/**
+ * The board and journal of one project, read without writing: `hub.db` opens read-only through the same compatibility check the hub uses, and the journal's envelope bodies are
+ * never decoded (SQLite hands back only each original's task reference). A store that cannot be read leaves its part unknown, never an empty one.
+ */
+export function readEvidence(stateDir: string, projectId: string, only?: number): ResearchEvidence {
+  const file = join(stateDir, "hub.db");
+  if (!existsSync(file)) return NO_EVIDENCE;
+  let db: ReturnType<typeof openHubDatabase> | undefined;
+  try { db = openHubDatabase(file, { readonly: true }); } catch { return NO_EVIDENCE; }
+  try {
+    const handoffIn = new Set<number>(), handoffOut = new Map<number, number>();
+    // `only` (the live writer, one task) narrows each read to that task; a backfill reads them all.
+    const one = only === undefined ? "" : " WHERE task_id = " + Number(only);
+    try { for (const r of db.query("SELECT task_id FROM task_handoff_origin" + one).all() as { task_id: number }[]) handoffIn.add(r.task_id); } catch { /* an older hub.db has no handoff table */ }
+    try { for (const r of db.query("SELECT local_task FROM task_handoff_outbound WHERE local_task IS NOT NULL" + (only === undefined ? "" : " AND local_task = " + Number(only))).all() as { local_task: number }[]) handoffOut.set(r.local_task, (handoffOut.get(r.local_task) ?? 0) + 1); } catch { /* same */ }
+    const tasks = new Map<number, EvidenceTask>();
+    let board = true;
+    try {
+      for (const row of db.query("SELECT id, history, sdlc FROM tasks" + (only === undefined ? "" : " WHERE id = " + Number(only))).all() as { id: number; history: string | null; sdlc: string | null }[]) {
+        const parse = (s: string | null) => { try { return s ? JSON.parse(s) : undefined; } catch { return undefined; } };
+        tasks.set(row.id, evidenceTask({ id: row.id, history: parse(row.history), sdlc: parse(row.sdlc) }, { in: handoffIn.has(row.id) ? 1 : 0, out: handoffOut.get(row.id) ?? 0 }));
+      }
+    } catch { board = false; }
+    let journal: ResearchEvidence["journal"];
+    try {
+      const rows = (db.query("SELECT d.state AS state, d.created_at AS createdAt, d.updated_at AS updatedAt, json_extract(e.value, '$.refs.task') AS task FROM deliveries d, json_each(d.originals) e WHERE d.project_id = ?" + (only === undefined ? "" : " AND CAST(json_extract(e.value, '$.refs.task') AS TEXT) = '" + Number(only) + "'")).all(projectId) as Record<string, unknown>[])
+        .flatMap(r => { const row = journalRow(r.task, r.state, r.createdAt, r.updatedAt); return row ? [row] : []; });
+      journal = { rows, coveredAfter: journalCoveredAfter(db, projectId) };
+    } catch { /* no journal table: delivery timing is unknown */ }
+    return { tasks, board, ...(journal ? { journal } : {}) };
+  } finally { db.close(); }
+}
+
+/**
+ * Why this bound is sound (#1290 review): pruning deletes only terminal rows, oldest `updated_at` first (ties by id), and never a protected one, so every pruned row's `updated_at` is at most the
+ * smallest `updated_at` among the terminal, unprotected rows that survive (W). A delivery is created no later than it is last updated, so a delivery created after W cannot be a pruned one.
+ * Protected rows are left out of W on purpose: including one (old, kept) would lower W and claim coverage the pruning did not keep. Unresolved rows are never pruned, so they need no bound.
+ * Unknown (null) when the journal's own review-input coverage is incomplete (legacy candidates are protected in memory only, where this reader cannot see them) or the tables cannot be read.
+ * No terminal row at all: nothing was kept and nothing needs bounding (-1, before any time).
+ */
+function journalCoveredAfter(db: ReturnType<typeof openHubDatabase>, projectId: string): number | null {
+  try {
+    const meta = db.query("SELECT review_input_coverage_complete AS ok FROM delivery_meta WHERE project_id = ?").get(projectId) as { ok: number } | null;
+    if (meta?.ok !== 1) return null;
+    const terminal = "d.project_id = ? AND d.state IN ('completed','discarded','failed')";
+    const any = db.query(`SELECT COUNT(*) AS n FROM deliveries d WHERE ${terminal}`).get(projectId) as { n: number };
+    if (any.n === 0) return -1;
+    const unprotected = db.query(`SELECT MIN(d.updated_at) AS w FROM deliveries d WHERE ${terminal}
+      AND NOT EXISTS (SELECT 1 FROM json_each(d.originals) e WHERE json_extract(e.value,'$.from')='hub' AND json_extract(e.value,'$.kind')='review' AND json_extract(e.value,'$.refs.reviewPackage') GLOB 'review-*')
+      AND NOT EXISTS (SELECT 1 FROM deliveries c WHERE c.project_id = d.project_id AND c.previous_id = d.id)`).get(projectId) as { w: number | null };
+    return typeof unprotected.w === "number" && Number.isFinite(unprotected.w) ? unprotected.w : null;
+  } catch { return null; }
+}
+
+/** Nearest-rank quantile of whole numbers, or null for none. */
+export function nearestRank(values: readonly number[], p: number): number | null {
+  if (!values.length) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(p * sorted.length) - 1))]!;
+}
+
+const EMPTY_TALLY = (): FindingTally => ({ important: 0, nit: 0, open: 0, fixed: 0, falsePositive: 0, accepted: 0 });
+
+/** The review block of a task. Board evidence missing (`task` undefined) leaves every board-derived field null. */
+export function reviewBlock(task: EvidenceTask | undefined, board: boolean, ownerFamily: string | null, pii: boolean): ReviewBlock {
+  const blank: ReviewBlock = { rounds: null, firstPass: null, findings: null, reviewerFamily: null, ownerFamily, scope: "unknown", evidenceOnly: null, context: "unknown", staleHeadReReviews: null };
+  if (!task) return blank;
+  const entries = task.history;
+  const verdicts = entries.filter(e => e.event === "approved" || e.event === "changes_requested");
+  const view: MetricTask = { id: task.id, history: entries.map(e => ({ at: e.at, event: e.event, ...(e.requestHead ? { requestHead: e.requestHead } : {}), ...(e.verdictHead ? { verdictHead: e.verdictHead } : {}), ...(e.evidenceOnly ? { evidenceOnly: true as const } : {}) })) };
+  const sample = taskSample(view);
+  let findings: ReviewBlock["findings"] = null;
+  const reported = entries.filter(e => !e.withheld && e.findings);
+  if (!pii && reported.length) {
+    const last = new Map<string, NonNullable<EvidenceEntry["findings"]>[number]>();
+    for (const entry of reported) for (const f of entry.findings!) last.set(f.id, f);
+    findings = { bugs: EMPTY_TALLY(), security: EMPTY_TALLY(), compliance: EMPTY_TALLY() };
+    for (const f of last.values()) {
+      const tally = findings[f.pass];
+      tally[f.severity]++;
+      if (f.disposition === "open") tally.open++; else if (f.disposition === "fixed") tally.fixed++; else if (f.disposition === "false_positive") tally.falsePositive++; else tally.accepted++;
+    }
+  }
+  const lastVerdict = verdicts.at(-1), lastDone = entries.findLast(e => e.event === "done");
+  const scope: ReviewScope = lastVerdict?.reviewScope === "code" ? "code" : lastDone?.plannedScope ?? "unknown";
+  return {
+    rounds: board ? verdicts.filter(e => e.evidenceOnly !== true).length : null,
+    firstPass: sample.first_pass_approval === null ? null : sample.first_pass_approval === 1,
+    findings,
+    reviewerFamily: entries.findLast(e => e.reviewerFamily)?.reviewerFamily ?? null,
+    ownerFamily, scope,
+    evidenceOnly: board ? verdicts.filter(e => e.evidenceOnly === true).length : null,
+    context: lastVerdict?.reviewContext ?? "unknown",
+    staleHeadReReviews: sample.stale_head_re_reviews,
+  };
+}
+
+/** The merge block. `doneToApprovedMs` is from the events' own times, so it needs no board; the CI and merge figures come from the receipt the guarded merge wrote. */
+export function mergeBlock(task: EvidenceTask | undefined, doneAt: number | null, approvedAt: number | null): MergeBlock {
+  const merge = task?.merge;
+  const gap = (from: number | null, to: number | null) => from !== null && to !== null && to >= from ? to - from : null;
+  return { ciRuns: merge?.ciRuns ?? null, ciReruns: merge?.ciReruns ?? null, githubReviews: merge?.reviews ?? null,
+    doneToApprovedMs: gap(doneAt, approvedAt), approvedToMergedMs: gap(approvedAt, merge?.mergedAt ?? null) };
+}
+
+/** The specs block from the latest done's report; an incomplete report is unknown, never zero. */
+export function specsBlock(task: EvidenceTask | undefined, pii: boolean): SpecsBlock {
+  const report = pii ? undefined : task?.history.findLast(e => e.spec)?.spec;
+  if (!report || !report.complete) return { covering: null, unchanged: null, acked: null, errors: null };
+  return { covering: report.unchanged + report.changed, unchanged: report.unchanged, acked: report.acked, errors: report.errors };
+}
+
+/** Delivery states and first-delivery times of one task from the journal rows in `[from, to]` (the task's life plus a settling hour); everything is null when the journal does not reach back that far. */
+export function journalFigures(evidence: ResearchEvidence, task: number, fromMs: number | null, toMs: number): Pick<DeliveryBlock, "firstDeliveryMs" | "needsReview" | "failed" | "discarded"> {
+  const journal = evidence.journal;
+  if (!journal || journal.coveredAfter === null || fromMs === null || fromMs <= journal.coveredAfter) return { firstDeliveryMs: { p50: null, p95: null }, needsReview: null, failed: null, discarded: null };
+  const rows = journal.rows.filter(r => r.task === task && r.createdAt >= fromMs && r.createdAt <= toMs + 3_600_000);
+  const latencies = rows.filter(r => r.state === "completed" && r.updatedAt >= r.createdAt).map(r => r.updatedAt - r.createdAt);
+  const n = (state: string) => rows.filter(r => r.state === state).length;
+  return { firstDeliveryMs: { p50: nearestRank(latencies, 0.5), p95: nearestRank(latencies, 0.95) }, needsReview: n("needs_review"), failed: n("failed"), discarded: n("discarded") };
+}