@staix/agent-hub 0.30.0 → 0.32.0

package/src/hub/questions.ts

@@ -0,0 +1,260 @@
+import { randomUUID } from "node:crypto";
+import { openHubDatabase, type Database } from "./db-schema.ts";
+
+/**
+ * #1053 T2: structured questions a peer asks the person. A row is the one record that the waiting tool call, the late-answer envelope and the inbox all read.
+ * This module knows the row shape and its state machine only: it never learns what `hub_ask` is, never touches a bus, a socket or a timer, and never logs.
+ * Question and answer text are stored here and nowhere else (hub.db, like a task title): the daemon keeps them out of logs, events and memory capture.
+ */
+
+export const QUESTION_STATES = ["open", "answered", "superseded", "cancelled", "expired"] as const;
+export type QuestionState = (typeof QUESTION_STATES)[number];
+/** Why a row left `open` without an answer; a closed list, so a reason can be shown and counted without any text. */
+export const QUESTION_REASONS = ["superseded", "stopped", "turn_aborted", "session_changed", "expired", "unattended"] as const;
+export type QuestionReason = (typeof QUESTION_REASONS)[number];
+/** Where an answer came from. `acon` is the plugin action of T5; the others are the console's own surfaces. */
+export const QUESTION_SURFACES = ["terminal", "console", "dashboard", "acon"] as const;
+export type QuestionSurface = (typeof QUESTION_SURFACES)[number];
+
+export const MAX_QUESTIONS = 4, MAX_OPTIONS = 8, MIN_OPTIONS = 2;
+export const MAX_PROMPT = 500, MAX_LABEL = 80, MAX_DESCRIPTION = 240, MAX_OTHER = 500;
+/** Bounds on rows that can wait at once: one peer cannot fill the inbox, and the whole table stays small. */
+export const MAX_OPEN_PER_PEER = 8, MAX_OPEN_TOTAL = 64;
+const ID = /^[A-Za-z0-9_.-]{1,64}$/;
+export const QUESTION_SET = /^qs-[a-f0-9]{12}$/;
+/** Controls other than tab and newline: they never reach a person's screen or another agent's prompt. */
+const CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f\u2028\u2029]/;
+
+export interface AskOption { id: string; label: string; description?: string }
+export interface AskQuestion { id: string; prompt: string; options: AskOption[]; multi?: boolean; allowOther?: boolean }
+export interface QuestionAnswer { questionId: string; optionIds: string[]; other?: string }
+export interface AskInput { questions: AskQuestion[]; task?: number }
+
+export interface QuestionRow {
+  set: string;
+  peer: string;
+  /** The peer's native session when it asked; "" when the adapter reports none (unknown never cancels). */
+  session: string;
+  task?: number;
+  /** Asked in a PII turn or about a PII task: surfaces show a stub title and the late envelope is private. */
+  private: boolean;
+  state: QuestionState;
+  created: number;
+  settled?: number;
+  reason?: QuestionReason;
+  surface?: QuestionSurface;
+  /** The console's verified identity (`ActionMeta.identity`) of an answer given in the acon panel; absent for the terminal and the hub's own console, whose person is the local user. */
+  person?: string;
+  questions: AskQuestion[];
+  answers?: QuestionAnswer[];
+  /** 0 nothing to publish, 1 a hub envelope (late answer or expiry notice) is owed to the peer, 2 it was published. */
+  envelope: 0 | 1 | 2;
+}
+
+type Parsed<T> = { ok: true; value: T } | { ok: false; error: string };
+const fail = (error: string): { ok: false; error: string } => ({ ok: false, error });
+const plain = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const length = (text: string): number => Array.from(text).length;
+const closed = (value: Record<string, unknown>, keys: readonly string[]): boolean => Object.keys(value).every(key => keys.includes(key));
+/** Text a person reads: no controls, trimmed, bounded by code points. Messages name the field, never the value. */
+function text(value: unknown, field: string, max: number, optional = false): Parsed<string | undefined> {
+  if (value === undefined && optional) return { ok: true, value: undefined };
+  if (typeof value !== "string") return fail(`${field} must be a string`);
+  const trimmed = value.trim();
+  if (!trimmed) return fail(`${field} must not be empty`);
+  if (length(trimmed) > max) return fail(`${field} is longer than ${max} characters`);
+  if (CONTROL.test(trimmed)) return fail(`${field} holds a control character`);
+  return { ok: true, value: trimmed };
+}
+
+/** The `hub_ask` input, closed and bounded exactly as the spec's Design section. Never echoes a value. */
+export function parseAsk(input: unknown): Parsed<AskInput> {
+  if (!plain(input) || !closed(input, ["questions", "task"])) return fail("hub_ask takes questions and an optional task");
+  if (!Array.isArray(input.questions) || input.questions.length < 1 || input.questions.length > MAX_QUESTIONS) return fail(`questions must hold 1 to ${MAX_QUESTIONS} questions`);
+  let task: number | undefined;
+  if (input.task !== undefined) {
+    if (typeof input.task !== "number" || !Number.isSafeInteger(input.task) || input.task < 1) return fail("task must be a positive task number");
+    task = input.task;
+  }
+  const questions: AskQuestion[] = [], seen = new Set<string>();
+  for (const [index, raw] of input.questions.entries()) {
+    const at = `questions[${index}]`;
+    if (!plain(raw) || !closed(raw, ["id", "prompt", "options", "multi", "allowOther"])) return fail(`${at} takes id, prompt, options, multi and allowOther`);
+    if (typeof raw.id !== "string" || !ID.test(raw.id)) return fail(`${at}.id must be 1 to 64 characters of letters, digits, dot, dash or underscore`);
+    if (seen.has(raw.id)) return fail(`${at}.id repeats an earlier question id`);
+    seen.add(raw.id);
+    const prompt = text(raw.prompt, `${at}.prompt`, MAX_PROMPT);
+    if (!prompt.ok) return prompt;
+    if (!Array.isArray(raw.options) || raw.options.length < MIN_OPTIONS || raw.options.length > MAX_OPTIONS) return fail(`${at}.options must hold ${MIN_OPTIONS} to ${MAX_OPTIONS} options`);
+    if (raw.multi !== undefined && typeof raw.multi !== "boolean") return fail(`${at}.multi must be a boolean`);
+    if (raw.allowOther !== undefined && typeof raw.allowOther !== "boolean") return fail(`${at}.allowOther must be a boolean`);
+    const options: AskOption[] = [], ids = new Set<string>();
+    for (const [position, option] of raw.options.entries()) {
+      const where = `${at}.options[${position}]`;
+      if (!plain(option) || !closed(option, ["id", "label", "description"])) return fail(`${where} takes id, label and description`);
+      if (typeof option.id !== "string" || !ID.test(option.id)) return fail(`${where}.id must be 1 to 64 characters of letters, digits, dot, dash or underscore`);
+      if (ids.has(option.id)) return fail(`${where}.id repeats an earlier option id`);
+      ids.add(option.id);
+      const label = text(option.label, `${where}.label`, MAX_LABEL);
+      if (!label.ok) return label;
+      const description = text(option.description, `${where}.description`, MAX_DESCRIPTION, true);
+      if (!description.ok) return description;
+      options.push({ id: option.id, label: label.value!, ...(description.value !== undefined ? { description: description.value } : {}) });
+    }
+    questions.push({ id: raw.id, prompt: prompt.value!, options, ...(raw.multi === true ? { multi: true } : {}), ...(raw.allowOther === true ? { allowOther: true } : {}) });
+  }
+  return { ok: true, value: { questions, ...(task !== undefined ? { task } : {}) } };
+}
+
+/**
+ * A person's answers against the stored row: every question answered once, only known option ids, one option unless `multi`, free text only where
+ * `allowOther` and at most 500 characters. Accepts the array form (`[{ questionId, optionIds, other? }]`, the tool result's) and the record form acon
+ * submits (`{ [questionId]: { selected, other? } }`). A reason names a question by position, never its text or the offered value.
+ */
+export function validateAnswers(questions: readonly AskQuestion[], input: unknown): Parsed<QuestionAnswer[]> {
+  let rows: unknown[];
+  // The record form is rewritten into the array form; a malformed record entry is remembered by position, never by a marker key a caller could also send.
+  const malformed = new Set<number>();
+  if (Array.isArray(input)) rows = input;
+  else if (plain(input)) rows = Object.entries(input).map(([questionId, value], position) => {
+    if (!plain(value) || !closed(value, ["selected", "other"])) { malformed.add(position); return { questionId }; }
+    return { questionId, optionIds: value.selected, ...(value.other !== undefined ? { other: value.other } : {}) };
+  });
+  else return fail("answers must be a list or a map of question ids");
+  if (rows.length > MAX_QUESTIONS) return fail("answers name more questions than were asked");
+  const byId = new Map(questions.map((question, index) => [question.id, { question, index }])), answers = new Map<string, QuestionAnswer>();
+  for (const [position, raw] of rows.entries()) {
+    if (malformed.has(position) || !plain(raw) || !closed(raw, ["questionId", "optionIds", "other"]) || typeof raw.questionId !== "string") return fail(`answers[${position}] takes questionId, optionIds and other`);
+    const known = byId.get(raw.questionId);
+    if (!known) return fail(`answers[${position}] names a question that was not asked`);
+    if (answers.has(raw.questionId)) return fail(`answers[${position}] answers question ${known.index + 1} twice`);
+    const { question, index } = known, label = `question ${index + 1}`;
+    const chosen = raw.optionIds === undefined ? [] : raw.optionIds;
+    if (!Array.isArray(chosen) || chosen.some(id => typeof id !== "string")) return fail(`${label}: options must be a list of option ids`);
+    if (new Set(chosen).size !== chosen.length) return fail(`${label}: an option is chosen twice`);
+    const offered = new Set(question.options.map(option => option.id));
+    if (chosen.some(id => !offered.has(id as string))) return fail(`${label}: an option id was not offered`);
+    if (chosen.length > 1 && question.multi !== true) return fail(`${label}: takes one option`);
+    let other: string | undefined;
+    if (raw.other !== undefined) {
+      if (question.allowOther !== true) return fail(`${label}: does not take other text`);
+      const parsed = text(raw.other, `${label}: other text`, MAX_OTHER);
+      if (!parsed.ok) return parsed;
+      other = parsed.value;
+    }
+    if (!chosen.length && other === undefined) return fail(`${label}: choose an option${question.allowOther === true ? " or give other text" : ""}`);
+    answers.set(raw.questionId, { questionId: raw.questionId, optionIds: chosen as string[], ...(other !== undefined ? { other } : {}) });
+  }
+  const missing = questions.findIndex(question => !answers.has(question.id));
+  if (missing >= 0) return fail(`question ${missing + 1} has no answer`);
+  return { ok: true, value: questions.map(question => answers.get(question.id)!) };
+}
+
+interface RawRow {
+  set_id: string; peer: string; session: string; task: number | null; private: number; state: string; created: number; settled: number | null; reason: string | null;
+  surface: string | null; person: string | null; questions: string; answers: string | null; envelope: number;
+}
+function rowOf(raw: RawRow): QuestionRow {
+  return {
+    set: raw.set_id, peer: raw.peer, session: raw.session, ...(raw.task !== null ? { task: raw.task } : {}), private: raw.private === 1, state: raw.state as QuestionState,
+    created: raw.created, ...(raw.settled !== null ? { settled: raw.settled } : {}), ...(raw.reason !== null ? { reason: raw.reason as QuestionReason } : {}),
+    ...(raw.surface !== null ? { surface: raw.surface as QuestionSurface } : {}), ...(raw.person ? { person: raw.person } : {}), questions: JSON.parse(raw.questions) as AskQuestion[],
+    ...(raw.answers !== null ? { answers: JSON.parse(raw.answers) as QuestionAnswer[] } : {}), envelope: raw.envelope as 0 | 1 | 2,
+  };
+}
+
+export type AnswerResult = { ok: true; row: QuestionRow } | { ok: false; error: string; state?: QuestionState };
+
+/** `questions` in hub.db. Additive table (no format bump): an older hub ignores it, which `Daemon` guards for recovery with the `questions` feature. */
+export class QuestionStore {
+  private readonly db: Database;
+  constructor(dbPath: string) {
+    this.db = openHubDatabase(dbPath, { create: true });
+    this.db.run(`CREATE TABLE IF NOT EXISTS questions (
+      set_id TEXT PRIMARY KEY, peer TEXT NOT NULL, session TEXT NOT NULL DEFAULT '', task INTEGER, private INTEGER NOT NULL DEFAULT 0,
+      state TEXT NOT NULL CHECK (state IN ('open','answered','superseded','cancelled','expired')), created INTEGER NOT NULL, settled INTEGER, reason TEXT, surface TEXT,
+      questions TEXT NOT NULL, answers TEXT, envelope INTEGER NOT NULL DEFAULT 0)`);
+    // The verified person of an acon answer: an additive column, so a table made before it is altered in place and an older hub simply never reads it.
+    if (!(this.db.query("PRAGMA table_info(questions)").all() as { name: string }[]).some(column => column.name === "person")) this.db.run("ALTER TABLE questions ADD COLUMN person TEXT");
+    this.db.run("CREATE INDEX IF NOT EXISTS questions_by_state ON questions(state, peer)");
+  }
+  close(): void { try { this.db.close(); } catch { /* already closed */ } }
+
+  get(set: string): QuestionRow | undefined {
+    if (typeof set !== "string" || !QUESTION_SET.test(set)) return undefined;
+    const raw = this.db.query("SELECT * FROM questions WHERE set_id = ?").get(set) as RawRow | null;
+    return raw ? rowOf(raw) : undefined;
+  }
+  /** Oldest first, bounded. */
+  list(filter: { state?: QuestionState; peer?: string } = {}, limit = 200): QuestionRow[] {
+    const where: string[] = [], args: (string | number)[] = [];
+    if (filter.state) { where.push("state = ?"); args.push(filter.state); }
+    if (filter.peer) { where.push("peer = ?"); args.push(filter.peer); }
+    return (this.db.query(`SELECT * FROM questions ${where.length ? `WHERE ${where.join(" AND ")}` : ""} ORDER BY created, set_id LIMIT ?`).all(...args, limit) as RawRow[]).map(rowOf);
+  }
+  openCount(peer?: string): number {
+    const row = (peer === undefined ? this.db.query("SELECT COUNT(*) AS n FROM questions WHERE state = 'open'").get() : this.db.query("SELECT COUNT(*) AS n FROM questions WHERE state = 'open' AND peer = ?").get(peer)) as { n: number };
+    return row.n;
+  }
+  /** Any row an older daemon would silently orphan: an open question, or an envelope still owed. */
+  hasPending(): boolean {
+    return (this.db.query("SELECT EXISTS(SELECT 1 FROM questions WHERE state = 'open' OR envelope = 1) AS present").get() as { present: number }).present === 1;
+  }
+
+  /** A new open row. Refuses past the per-peer and total bounds, so a loop cannot flood the inbox. */
+  ask(input: { peer: string; session: string; task?: number; private: boolean; questions: AskQuestion[] }, now: number): QuestionRow | { error: string } {
+    if (this.openCount(input.peer) >= MAX_OPEN_PER_PEER) return { error: `${MAX_OPEN_PER_PEER} questions from this peer are already waiting for the person; wait for an answer before asking more` };
+    if (this.openCount() >= MAX_OPEN_TOTAL) return { error: "too many questions are waiting for the person; try again later" };
+    const set = `qs-${randomUUID().replaceAll("-", "").slice(0, 12)}`;
+    this.db.query("INSERT INTO questions(set_id, peer, session, task, private, state, created, questions) VALUES(?, ?, ?, ?, ?, 'open', ?, ?)")
+      .run(set, input.peer, input.session, input.task ?? null, input.private ? 1 : 0, now, JSON.stringify(input.questions));
+    return this.get(set)!;
+  }
+
+  /**
+   * The one terminal transition: a compare-and-set on `state = 'open'`. Of any number of concurrent callers (a person's answer, a stop, an expiry) exactly one
+   * sees `changes === 1`; every other gets the row's real terminal state back. `late` says no waiting call will carry the result, so an envelope is owed.
+   */
+  answer(set: string, raw: unknown, surface: QuestionSurface, now: number, late: boolean, person?: string): AnswerResult {
+    const row = this.get(set);
+    if (!row) return { ok: false, error: "no such question" };
+    if (row.state !== "open") return { ok: false, error: `question is already ${row.state}`, state: row.state };
+    const parsed = validateAnswers(row.questions, raw);
+    if (!parsed.ok) return { ok: false, error: parsed.error };
+    const result = this.db.query("UPDATE questions SET state = 'answered', settled = ?, surface = ?, person = ?, answers = ?, envelope = ? WHERE set_id = ? AND state = 'open'")
+      .run(now, surface, person ?? null, JSON.stringify(parsed.value), late ? 1 : 0, set);
+    if (result.changes !== 1) { const now_ = this.get(set); return { ok: false, error: `question is already ${now_?.state ?? "settled"}`, ...(now_ ? { state: now_.state } : {}) }; }
+    return { ok: true, row: this.get(set)! };
+  }
+  /** Leave `open` for `superseded`, `cancelled` or `expired`. Returns the row only when this call made the transition. */
+  settle(set: string, state: "superseded" | "cancelled" | "expired", reason: QuestionReason, now: number, notify = false): QuestionRow | undefined {
+    if (typeof set !== "string" || !QUESTION_SET.test(set)) return undefined;
+    const result = this.db.query("UPDATE questions SET state = ?, settled = ?, reason = ?, envelope = ? WHERE set_id = ? AND state = 'open'").run(state, now, reason, notify ? 1 : 0, set);
+    return result.changes === 1 ? this.get(set) : undefined;
+  }
+  /** Every open row of one peer, each through `settle`; the rows this call settled. */
+  settleFor(peer: string, state: "superseded" | "cancelled", reason: QuestionReason, now: number, only?: (row: QuestionRow) => boolean): QuestionRow[] {
+    const settled: QuestionRow[] = [];
+    for (const row of this.list({ state: "open", peer }, MAX_OPEN_PER_PEER * 4)) {
+      if (only && !only(row)) continue;
+      const done = this.settle(row.set, state, reason, now);
+      if (done) settled.push(done);
+    }
+    return settled;
+  }
+  /** Open rows older than the ttl become `expired` with a notice owed; the caller marks it published when a waiting call carried the result instead. */
+  expireDue(now: number, ttlMs: number): QuestionRow[] {
+    const expired: QuestionRow[] = [];
+    for (const row of this.list({ state: "open" }, MAX_OPEN_TOTAL * 2)) if (now - row.created >= ttlMs) { const done = this.settle(row.set, "expired", "expired", now, true); if (done) expired.push(done); }
+    return expired;
+  }
+  /** Rows whose envelope is owed (a late answer or an expiry notice that a crash or an offline peer kept from going out). */
+  owed(): QuestionRow[] {
+    return (this.db.query("SELECT * FROM questions WHERE envelope = 1 ORDER BY settled, set_id LIMIT 200").all() as RawRow[]).map(rowOf);
+  }
+  published(set: string): void { this.db.query("UPDATE questions SET envelope = 2 WHERE set_id = ? AND envelope = 1").run(set); }
+  /** Settled rows older than `keepMs` go; open and owed rows never do. */
+  prune(now: number, keepMs: number): number {
+    return this.db.query("DELETE FROM questions WHERE state != 'open' AND envelope != 1 AND settled IS NOT NULL AND settled < ?").run(now - keepMs).changes;
+  }
+}

package/src/hub/research-evidence.ts

@@ -0,0 +1,106 @@
+import { createHash } from "node:crypto";
+import { types } from "node:util";
+import { validSourceId } from "./sources.ts";
+
+export const EVIDENCE_RELATIONS = ["supports", "contradicts", "context"] as const;
+export const MAX_EVIDENCE_LOCATOR_SPAN = 4096;
+export const MAX_EVIDENCE_RECORD_BYTES = 4096;
+
+/** Proposed zero-based, half-open scalar-value offsets. T1 stores bounds; T2 resolves and verifies them. */
+export interface EvidenceLocatorV1 { start: number; end: number }
+/** #931 provenance only: a relation never creates a #901 person verdict or verifies entailment. */
+export interface EvidenceLinkV1 {
+  id: string;
+  claimId: string;
+  claimRevision: string;
+  sourceId: string;
+  rawSha256: string;
+  projectionSha256: string;
+  projectionVersion: string;
+  locator: EvidenceLocatorV1;
+  relation: (typeof EVIDENCE_RELATIONS)[number];
+  recordedBy: string;
+  taskId: number;
+  revision: number;
+}
+/** The actor is host-stamped. Revision defaults to 1; a later revision names an existing link explicitly. */
+export type EvidenceRecordInput = Omit<EvidenceLinkV1, "id" | "recordedBy"> & { id?: string };
+export type EvidenceReceipt = Pick<EvidenceLinkV1, "id" | "revision" | "taskId">;
+
+const FIELDS = ["id", "claimId", "claimRevision", "sourceId", "rawSha256", "projectionSha256", "projectionVersion", "locator", "relation", "recordedBy", "taskId", "revision"] as const;
+const INPUT_FIELDS = FIELDS.filter(field => field !== "recordedBy");
+const HASH = /^[0-9a-f]{64}$/;
+const LINK_ID = /^ev:[0-9a-f]{32}$/;
+function fail(field: string, cause: string): never {
+  throw new Error(`evidence ${field}: ${cause}; correct this field using the hub_evidence_record schema and retry`);
+}
+function dataObject(value: unknown, allowed: readonly string[], field: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value) || types.isProxy(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+    || Object.getOwnPropertySymbols(value).length
+    || Object.values(Object.getOwnPropertyDescriptors(value)).some(descriptor => !Object.hasOwn(descriptor, "value"))) fail(field, "expected an inert plain data object");
+  if (Object.getOwnPropertyNames(value).some(key => !allowed.includes(key))) fail(field, "unknown field");
+  return value as Record<string, unknown>;
+}
+function integer(value: unknown, field: string, minimum = 1): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum) fail(field, `expected a safe integer >= ${minimum}`);
+  return value;
+}
+function token(value: unknown, field: string, expression: RegExp): string {
+  if (typeof value !== "string" || !expression.test(value)) fail(field, "invalid identifier or hash");
+  return value;
+}
+function claimId(value: unknown): string {
+  const id = token(value, "claimId", /^claim:[1-9][0-9]{0,15}:(?:0|[1-9][0-9]{0,15}):[1-9][0-9]?$/);
+  const [, task, created, slot] = id.split(":");
+  if (!Number.isSafeInteger(Number(task)) || !Number.isSafeInteger(Number(created)) || Number(slot) > 50) fail("claimId", "invalid task incarnation or claim slot");
+  return id;
+}
+function locator(value: unknown): EvidenceLocatorV1 {
+  const row = dataObject(value, ["start", "end"], "locator");
+  const start = integer(row.start, "locator.start", 0), end = integer(row.end, "locator.end");
+  if (end <= start || end - start > MAX_EVIDENCE_LOCATOR_SPAN) fail("locator", `expected a nonempty range of at most ${MAX_EVIDENCE_LOCATOR_SPAN} scalar values`);
+  return { start, end };
+}
+function parsed(value: unknown, stored: boolean): EvidenceRecordInput | EvidenceLinkV1 {
+  const row = dataObject(value, stored ? FIELDS : INPUT_FIELDS, "record");
+  const taskId = integer(row.taskId, "taskId"), revision = row.revision === undefined && !stored ? 1 : integer(row.revision, "revision");
+  const id = row.id === undefined && !stored ? undefined : token(row.id, "id", LINK_ID);
+  if (revision > 1 && id === undefined) fail("id", "a later revision must name its existing link");
+  const sourceId = row.sourceId;
+  if (!validSourceId(sourceId)) fail("sourceId", "expected a registered src:<16 hex> id");
+  const relation = row.relation;
+  if (typeof relation !== "string" || !(EVIDENCE_RELATIONS as readonly string[]).includes(relation)) fail("relation", "expected supports, contradicts or context");
+  const common: EvidenceRecordInput = {
+    ...(id === undefined ? {} : { id }),
+    claimId: claimId(row.claimId),
+    claimRevision: token(row.claimRevision, "claimRevision", /^[0-9a-f]{16}$/),
+    sourceId,
+    rawSha256: token(row.rawSha256, "rawSha256", HASH),
+    projectionSha256: token(row.projectionSha256, "projectionSha256", HASH),
+    projectionVersion: token(row.projectionVersion, "projectionVersion", /^[A-Za-z0-9][A-Za-z0-9._:/@+-]{0,63}$/),
+    locator: locator(row.locator),
+    relation: relation as EvidenceLinkV1["relation"],
+    taskId, revision,
+  };
+  const result = stored ? { ...common, id: id!, recordedBy: token(row.recordedBy, "recordedBy", /^[A-Za-z0-9][A-Za-z0-9._:@~+-]{0,127}$/) } : common;
+  if (Buffer.byteLength(JSON.stringify(result), "utf8") > MAX_EVIDENCE_RECORD_BYTES) fail("record", `expected at most ${MAX_EVIDENCE_RECORD_BYTES} bytes`);
+  return result;
+}
+export function parseEvidenceRecord(value: unknown): EvidenceRecordInput { return parsed(value, false) as EvidenceRecordInput; }
+export function parseEvidenceLink(value: unknown): EvidenceLinkV1 { return parsed(value, true) as EvidenceLinkV1; }
+
+/** Stable local identity for an identical initial write, without consulting a clock or creating a claim store. */
+export function evidenceLinkId(input: EvidenceRecordInput, recordedBy: string): string {
+  const parsed = parseEvidenceRecord(input);
+  if (parsed.id !== undefined) return parsed.id;
+  const actor = token(recordedBy, "recordedBy", /^[A-Za-z0-9][A-Za-z0-9._:@~+-]{0,127}$/);
+  return `ev:${createHash("sha256").update(JSON.stringify({ ...parsed, recordedBy: actor })).digest("hex").slice(0, 32)}`;
+}
+/** Fixed field order; parsing first prevents accessors, toJSON or unknown narrative fields from being serialized. */
+export function evidenceLinkCanonical(value: EvidenceLinkV1): string {
+  const row = parseEvidenceLink(value);
+  return JSON.stringify({ id: row.id, claimId: row.claimId, claimRevision: row.claimRevision, sourceId: row.sourceId,
+    rawSha256: row.rawSha256, projectionSha256: row.projectionSha256, projectionVersion: row.projectionVersion,
+    locator: row.locator, relation: row.relation, recordedBy: row.recordedBy, taskId: row.taskId, revision: row.revision });
+}

package/src/hub/restart.ts

@@ -54,6 +54,8 @@ export interface RestartSnapshot {
     researchExperiments?: { protocols: number; attempts: number; events: number; observations: number; digest: string };
     researchComparisons?: { plans: number; approvals: number; contexts: number; digest: string };
     researchRunners?: { count: number; digest: string };
+    researchEvidence?: { links: number; revisions: number; digest: string };
+    reviewComments?: { comments: number; packages: number; digest: string };
   };
 }
 
@@ -130,6 +132,18 @@ export function readRestartSnapshot(stateDir: string, expected: RestartReadExpec
     if (!value || typeof value !== "object" || Array.isArray(value) || !Number.isSafeInteger(value.count) || value.count < 0
       || typeof value.digest !== "string" || !/^[a-f0-9]{64}$/.test(value.digest)) return undefined;
   }
+  if (s.integrity && Object.hasOwn(s.integrity, "researchEvidence")) {
+    const value = s.integrity.researchEvidence;
+    if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some(key => !["links", "revisions", "digest"].includes(key))
+      || ![value.links, value.revisions].every(count => Number.isSafeInteger(count) && count >= 0)
+      || typeof value.digest !== "string" || !/^[a-f0-9]{64}$/.test(value.digest)) return undefined;
+  }
+  if (s.integrity && Object.hasOwn(s.integrity, "reviewComments")) {
+    const value = s.integrity.reviewComments;
+    if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some(key => !["comments", "packages", "digest"].includes(key))
+      || ![value.comments, value.packages].every(count => Number.isSafeInteger(count) && count >= 0)
+      || typeof value.digest !== "string" || !/^[a-f0-9]{64}$/.test(value.digest)) return undefined;
+  }
   if (bus.journal !== undefined) { try { validateJournalSnapshot(bus.journal); } catch { return undefined; } }
   return s as RestartSnapshot;
 }

package/src/hub/review-anchor.ts

@@ -0,0 +1,181 @@
+import { types } from "node:util";
+import type { ReviewAnchor, ReviewSelector } from "@staix/agent-console/contract";
+import { sanitize } from "./envelope.ts";
+import { projectionPath } from "./projected-diff.ts";
+import type { ReviewMaterial } from "./review-material.ts";
+export type { ReviewAnchor, ReviewSelector, ReviewThread } from "@staix/agent-console/contract";
+
+/** Conformance bounds belong to the published acon contract; hub write byte bounds are a separate layer below. */
+const CONTRACT = { exact: 2000, context: 64, body: 4000, threads: 200, selectors: 4 };
+function data(value: unknown, keys: readonly string[]): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value) || types.isProxy(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value)) || Object.getOwnPropertySymbols(value).length) return undefined;
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (Object.keys(descriptors).some(key => !keys.includes(key)) || Object.values(descriptors).some(field => !Object.hasOwn(field, "value") || !field.enumerable)) return undefined;
+  return value as Record<string, unknown>;
+}
+function list(value: unknown, max: number): value is unknown[] {
+  if (!Array.isArray(value) || types.isProxy(value) || Object.getPrototypeOf(value) !== Array.prototype || value.length > max || Object.getOwnPropertySymbols(value).length) return false;
+  const fields = Object.getOwnPropertyDescriptors(value);
+  return Object.keys(fields).length === value.length + 1 && Object.entries(fields).every(([key, field]) => key === "length"
+    || /^(0|[1-9][0-9]*)$/.test(key) && Number(key) < value.length && Object.hasOwn(field, "value") && field.enumerable);
+}
+const text = (value: unknown): value is string => typeof value === "string" && value.length > 0;
+const positive = (value: unknown): value is number => typeof value === "number" && Number.isInteger(value) && value >= 1;
+const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value >= 0;
+
+function selectorProblems(value: unknown, at: string): string[] {
+  const row = data(value, ["kind", "startLine", "endLine", "exact", "prefix", "suffix", "hunkHeader", "scheme", "ref", "x", "y", "width", "height", "page"]);
+  if (!row) return [`${at}: inert closed selector required`];
+  const allowed: Record<string, string[]> = {
+    lineRange: ["kind", "startLine", "endLine"], textQuote: ["kind", "exact", "prefix", "suffix"],
+    diffHunk: ["kind", "hunkHeader"], structural: ["kind", "scheme", "ref"], region: ["kind", "x", "y", "width", "height", "page"],
+  };
+  if (typeof row.kind !== "string" || !Object.hasOwn(allowed, row.kind)) return [`${at}.kind is unsupported`];
+  if (Object.keys(row).some(key => !allowed[row.kind as string]!.includes(key))) return [`${at}: unknown selector fields`];
+  switch (row.kind) {
+    case "lineRange": return positive(row.startLine) && positive(row.endLine) && row.startLine <= row.endLine ? [] : [`${at}: invalid startLine/endLine`];
+    case "textQuote": return text(row.exact) && row.exact.length <= CONTRACT.exact && typeof row.prefix === "string" && row.prefix.length <= CONTRACT.context
+      && typeof row.suffix === "string" && row.suffix.length <= CONTRACT.context ? [] : [`${at}: invalid exact/prefix/suffix bounds`];
+    case "diffHunk": return typeof row.hunkHeader === "string" && row.hunkHeader.startsWith("@@") ? [] : [`${at}.hunkHeader must start with @@`];
+    case "structural": return text(row.scheme) && text(row.ref) ? [] : [`${at}: scheme and ref are required`];
+    case "region": return [row.x, row.y, row.width, row.height].every(finite) && (row.page === undefined || positive(row.page)) ? [] : [`${at}: invalid region coordinates or page`];
+    default: return [`${at}.kind is unsupported`];
+  }
+}
+
+export function reviewAnchorContractProblems(value: unknown): string[] {
+  const row = data(value, ["path", "side", "contentHash", "projection", "selectors"]);
+  if (!row) return ["anchor: inert closed object required"];
+  const problems: string[] = [];
+  if (!text(row.path)) problems.push("anchor.path must be nonempty");
+  if (row.side !== undefined && row.side !== "base" && row.side !== "head") problems.push("anchor.side must be base or head");
+  if (row.contentHash !== undefined && (typeof row.contentHash !== "string" || !/^[a-f0-9]{64}$/.test(row.contentHash))) problems.push("anchor.contentHash must be lowercase sha256");
+  if (row.projection !== undefined) {
+    const projection = data(row.projection, ["name", "version"]);
+    if (!projection || !text(projection.name) || !text(projection.version)) problems.push("anchor.projection needs name and version");
+  }
+  if (!list(row.selectors, CONTRACT.selectors) || !row.selectors.length) problems.push("anchor.selectors needs 1-4 inert selectors");
+  else row.selectors.forEach((selector, index) => problems.push(...selectorProblems(selector, `anchor.selectors[${index}]`)));
+  return problems;
+}
+export function reviewThreadContractProblems(value: unknown): string[] {
+  const row = data(value, ["id", "anchor", "body", "author", "at", "state"]);
+  if (!row) return ["thread: inert closed object required"];
+  const problems: string[] = [];
+  for (const field of ["id", "author"]) if (!text(row[field])) problems.push(`thread.${field} must be nonempty`);
+  if (!text(row.body) || row.body.length > CONTRACT.body) problems.push("thread.body must contain 1-4000 characters");
+  if (typeof row.at !== "string" || Number.isNaN(Date.parse(row.at))) problems.push("thread.at must be a valid timestamp");
+  if (row.state !== undefined && row.state !== "open" && row.state !== "resolved") problems.push("thread.state must be open or resolved");
+  problems.push(...reviewAnchorContractProblems(row.anchor).map(problem => `thread.${problem}`));
+  return problems;
+}
+export function reviewThreadsContractProblems(value: unknown): string[] {
+  if (!list(value, CONTRACT.threads)) return ["threads must be an inert array of at most 200 entries"];
+  const problems: string[] = [], ids = new Set<string>();
+  value.forEach((thread, index) => {
+    problems.push(...reviewThreadContractProblems(thread).map(problem => `threads[${index}]: ${problem}`));
+    const row = data(thread, ["id", "anchor", "body", "author", "at", "state"]);
+    if (row && typeof row.id === "string") { if (ids.has(row.id)) problems.push(`threads[${index}].id repeats`); ids.add(row.id); }
+  });
+  return problems;
+}
+
+export class ReviewAnchorError extends Error {
+  constructor(readonly field: string, readonly maxBytes?: number, readonly shapeFields?: readonly string[]) {
+    super("review anchor validation failed");
+    this.name = "ReviewAnchorError";
+    this.message = this.safeMessage + (maxBytes === undefined ? "" : " (hub bound)");
+    Object.freeze(this);
+  }
+  get safeMessage(): string {
+    if (this.shapeFields) return `review anchor fields ${this.shapeFields.join(", ")} do not match the acon contract; correct those fields and retry`;
+    if (this.maxBytes !== undefined) return `review anchor ${this.field} exceeds ${this.maxBytes} UTF-8 bytes; shorten that field and retry`;
+    return `review anchor ${this.field} is invalid; correct that field and retry`;
+  }
+}
+/** Returns only messages assembled by the anchor validator; arbitrary caught errors are never reflected. */
+export function reviewAnchorErrorMessage(error: unknown): string {
+  return error instanceof ReviewAnchorError ? error.safeMessage : "review anchor is invalid; correct its fields and retry";
+}
+function fail(field: string, maxBytes?: number): never { throw new ReviewAnchorError(field, maxBytes); }
+function contractField(problem: string): string {
+  const selector = /^anchor\.selectors\[(\d+)\]/.exec(problem);
+  if (selector) {
+    const prefix = `anchor.selectors[${selector[1]}]`;
+    const member = /^\.([A-Za-z]+)/.exec(problem.slice(prefix.length))?.[1];
+    if (member) return `selectors[${selector[1]}].${member}`;
+    if (problem.includes("startLine/endLine")) return `selectors[${selector[1]}].startLine/endLine`;
+    if (problem.includes("exact/prefix/suffix")) return `selectors[${selector[1]}].exact/prefix/suffix`;
+    if (problem.includes("region coordinates or page")) return `selectors[${selector[1]}].x/y/width/height/page`;
+    if (problem.includes("scheme and ref")) return `selectors[${selector[1]}].scheme/ref`;
+    return `selectors[${selector[1]}]`;
+  }
+  const field = /^anchor\.(path|side|contentHash|projection|selectors)\b/.exec(problem)?.[1];
+  return field ?? "anchor";
+}
+function failShape(problems: readonly string[]): never {
+  const fields = [...new Set(problems.map(contractField))];
+  throw new ReviewAnchorError("anchor", undefined, fields.length ? fields : ["anchor"]);
+}
+function writeQuoteText(value: string, maxBytes: number, field: string): string {
+  if (value.includes("\0")) return fail(field);
+  if (Buffer.byteLength(value, "utf8") > maxBytes) return fail(field, maxBytes);
+  return value;
+}
+function writeText(value: string, maxBytes: number, field: string): string {
+  if (value.includes("\0")) return fail(field);
+  if (Buffer.byteLength(value, "utf8") > maxBytes) return fail(field, maxBytes);
+  const safe = sanitize(value);
+  if (Buffer.byteLength(safe, "utf8") > maxBytes) return fail(field, maxBytes);
+  return safe;
+}
+/** The hub write boundary. Quote selector text stays byte-bounded and exact; other stored text is sanitized here. */
+export function parseReviewAnchor(value: unknown): ReviewAnchor {
+  const problems = reviewAnchorContractProblems(value);
+  if (problems.length) return failShape(problems);
+  const row = value as ReviewAnchor, path = writeText(row.path, 4096, "path");
+  if (/[\p{Cc}\p{Cf}\\]/u.test(path) || /^[a-z]:/i.test(path) || !projectionPath({ top: "", dir: "", prefix: "" }, path)) return fail("path");
+  const selectors = row.selectors.map((selector, index): ReviewSelector => {
+    switch (selector.kind) {
+      case "lineRange":
+        if (!Number.isSafeInteger(selector.startLine) || !Number.isSafeInteger(selector.endLine)) return fail(`selectors[${index}].startLine/endLine`);
+        return { ...selector };
+      case "textQuote": return { kind: "textQuote", exact: writeQuoteText(selector.exact, 512, `selectors[${index}].exact`), prefix: writeQuoteText(selector.prefix, 64, `selectors[${index}].prefix`), suffix: writeQuoteText(selector.suffix, 64, `selectors[${index}].suffix`) };
+      case "diffHunk": return { kind: "diffHunk", hunkHeader: writeText(selector.hunkHeader, 256, `selectors[${index}].hunkHeader`) };
+      case "structural": return { kind: "structural", scheme: writeText(selector.scheme, 128, `selectors[${index}].scheme`), ref: writeText(selector.ref, 512, `selectors[${index}].ref`) };
+      case "region":
+        if (selector.page !== undefined && !Number.isSafeInteger(selector.page)) return fail(`selectors[${index}].page`);
+        return { ...selector };
+    }
+  });
+  return { path, ...(row.side === undefined ? {} : { side: row.side }), ...(row.contentHash === undefined ? {} : { contentHash: row.contentHash }),
+    ...(row.projection ? { projection: { name: writeText(row.projection.name, 128, "projection.name"), version: writeText(row.projection.version, 128, "projection.version") } } : {}), selectors };
+}
+
+export interface ReviewAnchorStatus { status: "anchored" | "moved" | "outdated" | "unavailable"; range?: { startLine: number; endLine: number } }
+function quotePosition(text: string, quote: Extract<ReviewSelector, { kind: "textQuote" }>): number | undefined {
+  let count = 0, contextual = 0, first = -1, contextualAt = -1;
+  if (!quote.exact) return undefined;
+  for (let at = text.indexOf(quote.exact); at !== -1; at = text.indexOf(quote.exact, at + 1)) {
+    count++; first = at;
+    const end = at + quote.exact.length;
+    if (at >= quote.prefix.length && text.slice(at - quote.prefix.length, at) === quote.prefix
+      && text.slice(end, end + quote.suffix.length) === quote.suffix) { contextual++; contextualAt = at; }
+  }
+  return count === 1 ? first : contextual === 1 ? contextualAt : undefined;
+}
+/** Placement only. Projection identity precedes byte equality; no stored selector or hash is rewritten. */
+export function anchorStatus(anchor: ReviewAnchor, material: ReviewMaterial): ReviewAnchorStatus {
+  if (material.state !== "available" || material.path !== anchor.path || material.side !== (anchor.side ?? "head")) return { status: "unavailable" };
+  if (anchor.projection?.name !== material.projection?.name || anchor.projection?.version !== material.projection?.version) return { status: "outdated" };
+  if (anchor.contentHash !== undefined && anchor.contentHash === material.contentHash) return { status: "anchored" };
+  for (const selector of anchor.selectors) if (selector.kind === "textQuote") {
+    const at = quotePosition(material.text, selector);
+    if (at === undefined) continue;
+    const startLine = material.text.slice(0, at).split("\n").length;
+    const endLine = material.text.slice(0, at + selector.exact.length - 1).split("\n").length;
+    return { status: "moved", range: { startLine, endLine } };
+  }
+  return { status: "outdated" };
+}

package/src/hub/review-brief.ts

@@ -4,6 +4,19 @@ import { childEnv } from "./child-process.ts";
 import { hubGitSync } from "./git.ts";
 import { symbolsOverlap } from "./symbol-normalizer.ts";
 import type { SpecTaskReport } from "./board.ts";
+import type { ReviewFinding } from "./review-findings.ts";
+import type { ReviewAnchorStatus } from "./review-anchor.ts";
+
+/** Read-time placement only; the stored finding and its selectors remain unchanged. */
+export function renderFindingAnchor(finding: ReviewFinding, placement: ReviewAnchorStatus): string {
+  const anchor = finding.anchor;
+  if (!anchor) return "";
+  if (placement.status === "unavailable") return "Anchor: unavailable; reopen the task review to inspect current public material.";
+  const range = placement.status === "outdated" ? undefined : placement.range ?? anchor.selectors.find(selector => selector.kind === "lineRange");
+  const location = anchor.path + (range ? `:${range.startLine}-${range.endLine}` : "");
+  const quotes = anchor.selectors.flatMap(selector => selector.kind === "textQuote" ? [selector.exact] : []);
+  return sanitize([`Anchor: ${location} (${placement.status})`, ...quotes.map(quote => `> ${quote.replace(/\n/g, "\n> ")}`)].join("\n"));
+}
 
 /**
  * #520: the review brief ahub builds itself, in place of `ocr delegate preview` and `rule`. Every reviewer gets the same