@staix/agent-research 0.0.0-stage → 0.2.1

package/src/mcp.ts

@@ -0,0 +1,113 @@
+import { once } from "node:events";
+import type { Readable, Writable } from "node:stream";
+
+/** Newline-delimited JSON-RPC stdio transport (MCP basic + tools). Sequential, bounded, no timers. */
+export const FRAME_BYTES = 128 * 1024, RESULT_BYTES = 2 * 1024 * 1024;
+export const DEFAULT_STRING_LENGTH = 65_536;
+export interface McpTool { name: string; description: string; inputSchema: Record<string, unknown>; annotations: Record<string, boolean> }
+export type McpHandler = (args: Record<string, unknown>) => unknown | Promise<unknown>;
+export interface McpServerOptions { tools: readonly McpTool[]; handlers: Record<string, McpHandler>; input?: Readable; output?: Writable; name?: string; version?: string }
+const protocols = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const plain = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+
+/** Runtime validation for the small schema vocabulary the tools use. Unknown keywords never widen acceptance. */
+export function validArguments(value: unknown, raw: unknown): boolean {
+  // An empty JSON schema delegates a frame-bounded field (watch version) to the shared validator.
+  if (plain(raw) && Object.keys(raw).length === 0) return true;
+  const s = raw as Record<string, any>, type = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+  const types: unknown[] = Array.isArray(s.type) ? s.type : [s.type];
+  if (!types.includes(type) && !(type === "number" && Number.isSafeInteger(value) && types.includes("integer"))) return false;
+  if (type === "number" && !types.includes("number") && !Number.isSafeInteger(value)) return false;
+  if (s.enum && !s.enum.includes(value)) return false;
+  if (typeof value === "string" && (value.length < (s.minLength ?? 0) || value.length > (s.maxLength ?? DEFAULT_STRING_LENGTH) || value.includes("\0"))) return false;
+  if (typeof value === "number" && (!Number.isFinite(value) || value < (s.minimum ?? -Infinity) || value > (s.maximum ?? Infinity))) return false;
+  if (Array.isArray(value)) {
+    if (value.length < (s.minItems ?? 0) || value.length > (s.maxItems ?? 64) || !plain(s.items)) return false;
+    return value.every(item => validArguments(item, s.items));
+  }
+  if (plain(value)) {
+    const keys = Object.keys(value);
+    if (keys.length < (s.minProperties ?? 0) || keys.length > (s.maxProperties ?? 64)) return false;
+    if ((s.required ?? []).some((key: string) => !Object.hasOwn(value, key))) return false;
+    for (const key of keys) {
+      if (["__proto__", "prototype", "constructor"].includes(key) || key.length > 200) return false;
+      if (Object.hasOwn(s.properties ?? {}, key)) { if (!validArguments(value[key], s.properties[key])) return false; }
+      else if (s.additionalProperties === false || !plain(s.additionalProperties) || !validArguments(value[key], s.additionalProperties)) return false;
+    }
+  } else if (type === "object") return false;
+  return true;
+}
+
+/** Serve until input ends. stdout carries protocol messages only; nothing else is written to `output`. */
+export async function serveMcp(options: McpServerOptions): Promise<void> {
+  const input = options.input ?? process.stdin, output = options.output ?? process.stdout;
+  let phase: "new" | "initializing" | "ready" = "new";
+  const send = async (response: unknown) => { if (!output.write(JSON.stringify(response) + "\n")) await once(output, "drain"); };
+  const error = (id: unknown, code: number, message: string) => send({ jsonrpc: "2.0", id, error: { code, message } });
+  const handle = async (line: string) => {
+    let msg: unknown;
+    try { msg = JSON.parse(line); } catch { await error(null, -32700, "Parse error"); return; }
+    if (!plain(msg) || msg.jsonrpc !== "2.0" || typeof msg.method !== "string") { await error(null, -32600, "Invalid request"); return; }
+    if (!Object.hasOwn(msg, "id")) {
+      if (msg.method === "notifications/initialized" && phase === "initializing") phase = "ready";
+      return; // Notifications never invoke a handler.
+    }
+    const id = msg.id;
+    if (!(typeof id === "string" && id.length <= 200 || typeof id === "number" && Number.isSafeInteger(id))) { await error(null, -32600, "Invalid request id"); return; }
+    if (msg.method === "ping") { await send({ jsonrpc: "2.0", id, result: {} }); return; }
+    if (msg.method === "initialize") {
+      if (phase !== "new" || !plain(msg.params) || typeof msg.params.protocolVersion !== "string" || !plain(msg.params.capabilities) || !plain(msg.params.clientInfo)) { await error(id, -32602, "Invalid initialization"); return; }
+      phase = "initializing";
+      await send({ jsonrpc: "2.0", id, result: { protocolVersion: protocols.includes(msg.params.protocolVersion) ? msg.params.protocolVersion : protocols[0],
+        capabilities: { tools: { listChanged: false } }, serverInfo: { name: options.name ?? "ares", version: options.version ?? "unreleased" } } });
+      return;
+    }
+    if (phase !== "ready") { await error(id, -32002, "Initialize the session first"); return; }
+    if (msg.method === "tools/list") {
+      const params = msg.params;
+      if (params !== undefined && params !== null && (!plain(params) || Object.keys(params).some(key => key !== "cursor" && key !== "_meta") || params.cursor !== undefined && params.cursor !== null)) { await error(id, -32602, "Invalid tool listing arguments"); return; }
+      await send({ jsonrpc: "2.0", id, result: { tools: options.tools } }); return;
+    }
+    if (msg.method !== "tools/call") { await error(id, -32601, "Method not found"); return; }
+    const params = msg.params;
+    if (!plain(params) || Object.keys(params).some(k => !["name", "arguments", "_meta"].includes(k)) || typeof params.name !== "string") { await error(id, -32602, "Invalid tool call"); return; }
+    const definition = options.tools.find(t => t.name === params.name), args = params.arguments ?? {};
+    const handler = definition && options.handlers[definition.name];
+    if (!definition || !handler || !validArguments(args, definition.inputSchema)) { await error(id, -32602, "Invalid tool name or arguments"); return; }
+    let result: unknown;
+    try {
+      const text = JSON.stringify(await handler(args as Record<string, unknown>));
+      if (text === undefined) throw new Error("tool returned no result");
+      result = Buffer.byteLength(text) > RESULT_BYTES
+        ? { isError: true, content: [{ type: "text", text: JSON.stringify({ refused: true, issues: [{ code: "LIMIT", severity: "error", message: "result exceeds 2 MiB; narrow filters, lower the list limit or select fewer log streams" }] }) }] }
+        : { content: [{ type: "text", text }] };
+    } catch (failure) {
+      // Handlers return structured refusals; anything thrown is reported without stack or content.
+      const message = failure instanceof Error ? failure.message.slice(0, 500) : "operation failed";
+      result = { isError: true, content: [{ type: "text", text: JSON.stringify({ refused: true, issues: [{ code: "ERROR", severity: "error", message }] }) }] };
+    }
+    await send({ jsonrpc: "2.0", id, result });
+  };
+  let pending = "", overflow = false;
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  const consume = async (chunk: string) => {
+    let start = 0;
+    for (;;) {
+      const newline = chunk.indexOf("\n", start), part = chunk.slice(start, newline < 0 ? undefined : newline);
+      if (!overflow) {
+        if (Buffer.byteLength(pending) + Buffer.byteLength(part) > FRAME_BYTES) { overflow = true; pending = ""; }
+        else pending += part;
+      }
+      if (newline < 0) return;
+      if (overflow) await error(null, -32600, "Request exceeds the 128 KiB frame bound; shorten the request and retry");
+      else if (pending.trim()) await handle(pending);
+      pending = ""; overflow = false; start = newline + 1;
+    }
+  };
+  try {
+    for await (const chunk of input) await consume(typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true }));
+  } catch { await error(null, -32700, "Invalid UTF-8 input"); return; }
+  await consume(decoder.decode());
+  // A truncated frame at EOF is never executed.
+  if (pending.trim() || overflow) await error(null, -32700, "Incomplete request at EOF");
+}

package/src/memory/amem.ts

@@ -0,0 +1,97 @@
+import { PROCESS_CONTEXT_ENV_KEYS, spawnRunner, type ProcessRunner } from "../exp/executor.ts";
+import { plain } from "../study.ts";
+
+export const AMEM_OUTPUT_BYTES = 262_144;
+export const AMEM_BRIEF_BYTES = 8192;
+export type AmemKind = "fail" | "finding" | "decision" | "contract";
+export interface AmemNote {
+  text: string; kind: AmemKind; title?: string;
+  approach?: string; symptom?: string; cause?: string; evidence?: string[]; retryWhen?: string;
+}
+export interface AmemHit { id: string; kind: AmemKind; title: string | null; at: string; relevance: number; about: string[] }
+export interface AmemBrief { brief: string; bytes: number; truncated: boolean; state: string }
+export interface AmemClient {
+  add(note: AmemNote): Promise<string>;
+  search(words: string, kind?: AmemKind, limit?: number): Promise<AmemHit[]>;
+  brief(text: string, bytes: number): Promise<AmemBrief>;
+}
+const kindOf = (value: unknown): value is AmemKind => ["fail", "finding", "decision", "contract"].includes(value as string);
+const identifier = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{32}$/.test(value);
+function invalid(): never { throw new Error("amem bad JSON: invalid response shape; check amem --version and inspect --json output in the study directory"); }
+function input(text: string): void {
+  if (!text.trim() || text.includes("\0")) throw new Error("amem input: provide non-empty text without NUL; correct the input and retry");
+}
+function optionValue(value: string): string {
+  input(value);
+  // ponytail: amem 0.20.3 cannot escape -- values; one leading space works until its parser supports literal option values.
+  return value.startsWith("--") ? ` ${value}` : value;
+}
+function hit(raw: unknown): AmemHit {
+  if (!plain(raw) || !identifier(raw.id) || !kindOf(raw.kind) || (raw.title !== null && typeof raw.title !== "string")
+    || typeof raw.at !== "string" || !Number.isFinite(Date.parse(raw.at))
+    || !Array.isArray(raw.about) || !raw.about.every(node => typeof node === "string")) invalid();
+  const details = raw.scoreDetails;
+  if (!plain(details) || typeof details.finalScore !== "number" || !Number.isFinite(details.finalScore) || details.finalScore <= 0
+    || typeof details.recencyFactor !== "number" || !Number.isFinite(details.recencyFactor) || details.recencyFactor <= 0) scoreUnavailable();
+  const relevance = details.finalScore / details.recencyFactor;
+  if (!Number.isFinite(relevance) || relevance <= 0) scoreUnavailable();
+  return { id: raw.id, kind: raw.kind, title: raw.title, at: raw.at, relevance, about: [...raw.about] as string[] };
+}
+function scoreUnavailable(): never {
+  throw new Error("amem score unavailable: finite positive finalScore and recencyFactor required; inspect amem search <words> --json --explain in the study directory");
+}
+async function readAmem(args: string[], cwd: string, runner: ProcessRunner, context: NodeJS.ProcessEnv, stdin?: Uint8Array): Promise<unknown> {
+  let result;
+  try { result = await runner({ command: "amem", args, cwd, env: context, ...(stdin === undefined ? {} : { stdin }), maxOutputBytes: AMEM_OUTPUT_BYTES, timeoutMs: 30_000 }); }
+  catch { throw new Error("amem spawn failure; check amem is on PATH (amem --version)"); }
+  if (result.truncated || Buffer.byteLength(result.stdout) > AMEM_OUTPUT_BYTES) throw new Error("amem over-bound output; reduce the search limit or brief bytes and retry");
+  if (result.timedOut) throw new Error("amem timeout; check amem --version and retry in the study directory");
+  if (result.exitCode !== 0) throw new Error("amem nonzero exit; run amem search <words> --json in the study directory to see the cause");
+  try { return JSON.parse(result.stdout); } catch { throw new Error("amem bad JSON; check amem --version and inspect --json output in the study directory"); }
+}
+function searchRows(raw: unknown): unknown[] {
+  if (Array.isArray(raw)) return raw;
+  if (!plain(raw) || !Array.isArray(raw.hits)) invalid();
+  return raw.hits.flatMap(item => {
+    if (!plain(item)) invalid();
+    if (item.source !== "curated" || item.view === undefined) return [];
+    if (!plain(item.view)) invalid();
+    return [{ ...item.view, scoreDetails: item.scoreDetails }];
+  });
+}
+/** The process boundary returns projections only; raw diagnostics never escape in errors. */
+export function createAmemClient(cwd: string, runner: ProcessRunner = spawnRunner, env: NodeJS.ProcessEnv = process.env): AmemClient {
+  const context = Object.fromEntries([...PROCESS_CONTEXT_ENV_KEYS, "HOME"].flatMap(key => env[key] === undefined ? [] : [[key, env[key]!]]));
+  const read = (args: string[], stdin?: Uint8Array) => readAmem(args, cwd, runner, context, stdin);
+  return {
+    async add(note) {
+      input(note.text);
+      if (!kindOf(note.kind)) throw new Error("amem input: invalid kind; use fail, finding, decision or contract");
+      if (note.evidence && note.evidence.length > 16) throw new Error("amem input: at most 16 evidence refs; reduce evidence refs and retry");
+      const args = ["note", "add", "-", "--kind", note.kind];
+      for (const [flag, value] of [["--approach", note.approach], ["--symptom", note.symptom], ["--cause", note.cause],
+        ... (note.evidence ?? []).map(ref => ["--evidence", ref]), ["--retry-when", note.retryWhen], ["--title", note.title]]) {
+        if (value !== undefined) args.push(flag!, optionValue(value));
+      }
+      const raw = await read([...args, "--json"], Buffer.from(note.text, "utf8"));
+      if (!plain(raw) || !identifier(raw.id)) invalid();
+      return raw.id;
+    },
+    async search(words, kind, limit = 100) {
+      input(words);
+      if (kind !== undefined && !kindOf(kind)) throw new Error("amem input: invalid kind; use fail, finding, decision or contract");
+      if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw new Error("amem input: search limit must be 1..100; choose an integer in this range");
+      const raw = await read(["search", optionValue(words), "--json", "--explain", "--limit", String(limit)]);
+      const rows = searchRows(raw);
+      return rows.filter(row => kind === undefined || plain(row) && row.kind === kind).map(hit);
+    },
+    async brief(text, bytes) {
+      input(text);
+      if (!Number.isSafeInteger(bytes) || bytes < 1 || bytes > AMEM_BRIEF_BYTES) throw new Error("amem input: brief bytes must be 1..8192; choose an integer in this range");
+      const raw = await read(["brief", "--for", optionValue(text), "--json", "--bytes", String(bytes)]);
+      if (!plain(raw) || typeof raw.brief !== "string" || !Number.isSafeInteger(raw.bytes) || (raw.bytes as number) < 0
+        || (raw.bytes as number) > bytes || Buffer.byteLength(raw.brief) > bytes || typeof raw.truncated !== "boolean" || typeof raw.state !== "string") invalid();
+      return { brief: raw.brief, bytes: raw.bytes as number, truncated: raw.truncated, state: raw.state };
+    },
+  };
+}

package/src/memory/archive.ts

@@ -0,0 +1,66 @@
+import { ACCEPT_ARTIFACTS } from "../autonomy.ts";
+import { requireCopilotAccept } from "../copilot.ts";
+import { commit, prepareCommit, openStudy, plain, sha256, type Actor, type LedgerEvent } from "../study.ts";
+import { canonical } from "../plan/state.ts";
+import { createAmemClient, type AmemNote } from "./amem.ts";
+import { deriveLessons, readLessonSources } from "./lessons.ts";
+import type { ProcessRunner } from "../exp/executor.ts";
+
+export const ARCHIVE_NOTES = 200;
+export interface ArchiveReceipt { sha256: string; id: string }
+export interface ArchivePreview { fingerprint: string; notes: { sha256: string; note: AmemNote }[] }
+export interface ArchiveResult extends ArchivePreview { written: ArchiveReceipt[]; remaining: number }
+/** Carries receipt progress for adapters; CLI/MCP retain the existing retry instruction verbatim. */
+export class ArchivePartialError extends Error {
+  readonly failureMessage: string;
+  constructor(readonly exportedCount: number, failure: unknown) {
+    const detail = failure instanceof Error ? failure.message : "amem failure; check amem --version before retrying";
+    super(`archive: ${exportedCount} note(s) written and receipted; rerun with the same --confirm to continue; ${detail}`);
+    this.failureMessage = detail;
+  }
+}
+function hex(value: unknown, length: 32 | 64): value is string {
+  return typeof value === "string" && value.length === length && /^[a-f0-9]+$/.test(value);
+}
+function badReceipt(): never { throw new Error("archive receipt: malformed or conflicting exported notes; restore the last valid archive.exported ledger event before retrying ares archive"); }
+function exported(events: LedgerEvent[]): Set<string> {
+  const known = new Map<string, string>();
+  for (const event of events) if (event.type === "archive.exported") {
+    if (!hex(event.data.fingerprint, 64) || !Array.isArray(event.data.notes) || event.data.notes.length > ARCHIVE_NOTES) badReceipt();
+    for (const row of event.data.notes) {
+      if (!plain(row) || !hex(row.sha256, 64) || !hex(row.id, 32)) badReceipt();
+      if (known.has(row.sha256) && known.get(row.sha256) !== row.id) badReceipt();
+      known.set(row.sha256, row.id);
+    }
+  }
+  return new Set(known.keys());
+}
+/** No lock, subprocess or write: confirmation binds the full list, receipts only narrow pending writes. */
+export function previewArchive(dir: string): ArchivePreview {
+  for (const artifact of ACCEPT_ARTIFACTS) requireCopilotAccept(dir, artifact);
+  const sources = readLessonSources(dir), notes = deriveLessons(sources), known = exported(sources.events);
+  const unique = new Map(notes.map(note => [sha256(canonical(note)), note]));
+  const pending = [...unique].filter(([hash]) => !known.has(hash)).map(([sha256, note]) => ({ sha256, note }));
+  return { fingerprint: sha256(canonical(notes)), notes: pending };
+}
+/** Caller holds the study lock across the confirmed write and its single receipt commit. */
+export async function exportArchive(dirArg: string, fingerprint: string, actor: Actor, runner?: ProcessRunner, env: NodeJS.ProcessEnv = process.env): Promise<ArchiveResult> {
+  const { dir } = openStudy(dirArg), preview = previewArchive(dir);
+  if (!hex(fingerprint, 64) || fingerprint !== preview.fingerprint) throw new Error("archive: stale fingerprint; run ares archive <dir> again and confirm its current fingerprint");
+  const batch = preview.notes.slice(0, ARCHIVE_NOTES);
+  if (batch.length) {
+    try { prepareCommit(dir, [], [{ actor, type: "archive.exported", data: {
+      fingerprint, notes: batch.map(note => ({ sha256: note.sha256, id: "f".repeat(32) })),
+    } }]); }
+    catch { throw new Error("archive receipt: capacity check failed; restore a valid bounded ledger or start a new study before exporting"); }
+  }
+  const client = createAmemClient(dir, runner, env), written: ArchiveReceipt[] = [];
+  let failure: unknown;
+  for (const item of batch) {
+    try { written.push({ sha256: item.sha256, id: await client.add(item.note) }); }
+    catch (error) { failure = error; break; }
+  }
+  if (written.length) commit(dir, [], [{ actor, type: "archive.exported", data: { fingerprint, notes: written } }]);
+  if (failure) throw new ArchivePartialError(written.length, failure);
+  return { ...preview, written, remaining: preview.notes.length - written.length };
+}

package/src/memory/lessons.ts

@@ -0,0 +1,88 @@
+import { openStudy, readLedger, type LedgerEvent, type Study } from "../study.ts";
+import { foldIdeas } from "../exp/ideas.ts";
+import { readProtocol } from "../exp/protocol.ts";
+import { readSelection, selectionHash, type Selection } from "../exp/selection.ts";
+import { readClosedInvestigation, type InvestigateResult } from "../exp/investigate.ts";
+import { readClosedFinal, readFinalSeeds, finalSeedsHash, type FinalResult, type FinalSeeds } from "../exp/final.ts";
+import { foldReviews } from "../paper/review.ts";
+import type { AmemNote, AmemHit } from "./amem.ts";
+
+export interface LessonSources {
+  study: Pick<Study, "id" | "question">; events: LedgerEvent[];
+  investigation?: InvestigateResult; final?: FinalResult; selection?: Selection; finalSeeds?: FinalSeeds;
+}
+export const LESSON_EVIDENCE_REFS = 16;
+/** Read current committed sources only. An absent close yields no lesson; an invalid close refuses. */
+export function readLessonSources(dirArg: string): LessonSources {
+  const { dir, study } = openStudy(dirArg), events = readLedger(dir), protocol = readProtocol(dir);
+  const sources: LessonSources = { study, events };
+  if (protocol) {
+    sources.selection = readSelection(dir, protocol);
+    sources.finalSeeds = readFinalSeeds(dir, protocol);
+    for (const [type, value, hash] of [["selection.set", sources.selection, selectionHash(dir, protocol)], ["final.seeds.set", sources.finalSeeds, finalSeedsHash(dir, protocol)]]) {
+      if (value && events.findLast(event => event.type === type)?.data.sha256 !== hash) throw new Error("lessons: design file lacks a matching receipt; restore the committed selection/final seeds with ares selection or ares final seeds");
+    }
+  }
+  if (sources.selection && events.some(event => event.type === "investigate.closed" && event.data.run === sources.selection!.run)) sources.investigation = readClosedInvestigation(dir).result;
+  if (events.some(event => event.type === "final.closed")) sources.final = readClosedFinal(dir).result;
+  return sources;
+}
+/** Pure derivation. Ledger order, fixed source order and evidence chunks keep export fingerprints stable. */
+export function deriveLessons(sources: LessonSources): AmemNote[] {
+  const { study, events } = sources, notes: AmemNote[] = [], prefix = `${study.id}: ${study.question}\n`;
+  const attemptRef = (id: string) => `ares:${study.id}/attempt:${id}`;
+  const runRef = (run: string) => `ares:${study.id}/run:${run}`;
+  const add = (note: AmemNote) => {
+    const refs = [...new Set(note.evidence ?? [])];
+    // Split long evidence lists rather than silently dropping cited attempts.
+    for (let index = 0; index < Math.max(1, refs.length); index += LESSON_EVIDENCE_REFS) {
+      notes.push({ ...note, text: prefix + note.text, evidence: refs.slice(index, index + LESSON_EVIDENCE_REFS) });
+    }
+  };
+  for (const idea of foldIdeas(events)) {
+    for (const decision of idea.decisions) if (decision.decision === "pivot") add({ kind: "fail", title: idea.title,
+      text: `Pivot ${idea.id}: ${decision.reason}`, approach: `${idea.title}\n${idea.hypothesis}`, symptom: decision.reason,
+      cause: decision.cause ?? "not recorded", retryWhen: decision.retryWhen ?? "not recorded", evidence: decision.attempts.map(attemptRef) });
+  }
+  const investigation = sources.investigation;
+  if (investigation) {
+    const winner = investigation.winner, candidate = investigation.candidates.find(row => row.commit === winner?.commit);
+    add({ kind: "finding", title: `Investigation ${investigation.run}`,
+      text: winner ? `Investigation ${investigation.run}: winner ${winner.commit}; paired delta ${winner.delta}; seeds ${JSON.stringify(candidate?.pairedSeeds ?? [])}`
+        : `Investigation ${investigation.run}: no winner; reason ${investigation.reason}`,
+      evidence: [runRef(investigation.run), ...(winner?.attempts ?? []).map(attemptRef)] });
+  }
+  const final = sources.final;
+  if (final) add({ kind: "finding", title: `Final ${final.status}`,
+    text: `Final ${final.status}: winner ${final.winner}; baseline ${final.baseline}; reason ${final.reason ?? "qualified"}; paired delta ${final.delta}; seeds ${JSON.stringify(final.seeds)}`,
+    evidence: [runRef("final"), ...final.decisive.map(row => attemptRef(row.id))] });
+  if (sources.selection) add({ kind: "decision", title: "Selection rule", text: `Selection rule: ${JSON.stringify(sources.selection)}`, evidence: [runRef(sources.selection.run)] });
+  if (sources.finalSeeds) add({ kind: "decision", title: "Final seeds", text: `Final seeds: ${JSON.stringify(sources.finalSeeds.seeds)}`, evidence: [runRef("final")] });
+  for (const review of foldReviews(events)) {
+    for (const finding of review.report.findings) {
+      const resolution = review.resolutions[finding.id];
+      if (finding.kind === "contradiction" && resolution) add({ kind: "finding", title: `Review ${review.id}/${finding.id}`,
+        text: `Review contradiction ${review.id}/${finding.id}: ${finding.text}; resolution: ${resolution.reason}`, evidence: [] });
+    }
+  }
+  return notes;
+}
+
+export interface LessonRankOptions { halfLife?: number; limit?: number }
+export interface RankedLesson { id: string; kind: AmemHit["kind"]; title: string | null; age: number; relevance: number; score: number; rank: number }
+export const LESSON_HALF_LIFE = 180, LESSON_LIMIT = 50;
+const DAY_MS = 86_400_000;
+/** Pure ranking: age is days, relevance excludes amem recency, score is decayed and rank is 1-based. */
+export function rankLessons(hits: readonly AmemHit[], now: number, options: LessonRankOptions = {}): RankedLesson[] {
+  const halfLife = options.halfLife ?? LESSON_HALF_LIFE, limit = options.limit ?? LESSON_LIMIT;
+  if (!Number.isFinite(now)) throw new Error("lessons clock: finite timestamp required; supply a valid current time and retry");
+  if (!Number.isFinite(halfLife) || halfLife < 1 || halfLife > 3650) throw new Error("lessons half-life: outside 1..3650 days; pass --half-life DAYS within that range");
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > LESSON_LIMIT) throw new Error("lessons limit: outside 1..50; pass --limit with an integer in that range");
+  const ranked = hits.map(hit => {
+    const at = Date.parse(hit.at);
+    if (!Number.isFinite(at) || !Number.isFinite(hit.relevance) || hit.relevance <= 0) throw new Error("lessons score unavailable: invalid timestamp or relevance; inspect amem search --json --explain in the study directory before retrying");
+    const age = Math.max(0, (now - at) / DAY_MS), score = hit.relevance * 0.5 ** (age / halfLife);
+    return { id: hit.id, kind: hit.kind, title: hit.title, age, relevance: hit.relevance, score };
+  });
+  return ranked.sort((a, b) => b.score - a.score || Number(b.kind === "fail") - Number(a.kind === "fail") || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)).slice(0, limit).map((row, index) => ({ ...row, rank: index + 1 }));
+}

package/src/memory/skills.ts

@@ -0,0 +1,99 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { assertWritable, boundedText, commit, onlyKeys, openStudy, plain, readLedger, readTextBounded, sha256, type Actor, type LedgerEvent } from "../study.ts";
+
+export const SKILL_PROPOSAL_VERSION = 1, SKILL_PROPOSALS = 100, SKILL_BYTES = 16 * 1024, SKILL_EVIDENCE = 64;
+export interface SkillProposal { name: string; summary: string; steps: string[]; evidence: string[] }
+export type SkillDecision = "accept" | "reject" | "withdraw";
+export interface SkillRecord extends SkillProposal {
+  skillProposal: 1; state: "proposed" | "accepted" | "rejected" | "withdrawn"; sha256: string; actor: Actor; at: string;
+  decision?: { action: SkillDecision; reason: string; pr?: string; actor: Actor; at: string };
+}
+function bad(message: string): never { throw new Error(`skill: ${message}; inspect ares skill list, correct the input or restore the last valid proposal and retry`); }
+function nameOf(value: unknown): string {
+  if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(value)) bad("name must follow the run-name rule (1..64 letters, digits, underscores or hyphens)");
+  return value;
+}
+function text(value: unknown, field: string): string {
+  let result: string;
+  try { result = boundedText(value, `skill ${field}`, SKILL_BYTES); } catch { bad(`${field} must be nonblank text within 16 KiB`); }
+  if (result.includes("\0") || Buffer.byteLength(result) > SKILL_BYTES) bad(`${field} contains NUL or exceeds 16 KiB`);
+  return result;
+}
+function markdown(proposal: SkillProposal): string {
+  const list = (values: string[]) => values.map(value => `- ${value.replaceAll("\n", "\n  ")}`).join("\n");
+  return `---\nskillProposal: 1\nname: ${proposal.name}\n---\n\n# ${proposal.name}\n\n${proposal.summary}\n\n## Steps\n\n${list(proposal.steps)}\n\n## Evidence\n\n${list(proposal.evidence)}\n`;
+}
+/** Strict for new input, additive-field tolerant when replaying existing v1 records. */
+export function validateSkillProposal(raw: unknown, strict = true): SkillProposal {
+  if (!plain(raw)) bad("proposal object required");
+  if (strict) { try { onlyKeys(raw, ["name", "summary", "steps", "evidence"], "skill proposal"); } catch { bad("unknown proposal field; use only name, summary, steps and evidence"); } }
+  if (!Array.isArray(raw.steps) || !raw.steps.length || !Array.isArray(raw.evidence)) bad("steps must be a nonempty array and evidence an array");
+  if (raw.evidence.length < 1 || raw.evidence.length > SKILL_EVIDENCE) bad("evidence requires 1..64 refs; supply at least one recorded amem id or ares: reference");
+  if (raw.steps.length > SKILL_BYTES) bad("proposal arrays exceed the 16 KiB format ceiling; shorten steps or evidence");
+  const proposal: SkillProposal = { name: nameOf(raw.name), summary: text(raw.summary, "summary"), steps: raw.steps.map(value => text(value, "step")), evidence: raw.evidence.map(value => text(value, "evidence")) };
+  if (proposal.evidence.some(value => !/^[a-f0-9]{32}$/.test(value) && !/^ares:[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._:/-]*$/.test(value))) bad("evidence must contain 32-hex amem ids or ares:<study-id>/... refs");
+  try { assertWritable(markdown(proposal), SKILL_BYTES, "skill proposal"); } catch { bad("proposal Markdown exceeds 16 KiB; shorten summary, steps or evidence"); }
+  return proposal;
+}
+function decisionOf(value: unknown): SkillDecision {
+  if (value !== "accept" && value !== "reject" && value !== "withdraw") bad("decision must be accept, reject or withdraw");
+  return value;
+}
+function prOf(value: unknown, action: SkillDecision): string | undefined {
+  if (value === undefined) { if (action === "accept") bad("accept requires --pr URL for the reviewed PR"); return undefined; }
+  const result = text(value, "PR URL");
+  try { const url = new URL(result); if (!["https:", "http:"].includes(url.protocol) || url.username || url.password) bad("PR must be an HTTP(S) URL without credentials"); }
+  catch { bad("PR must be an HTTP(S) URL without credentials"); }
+  return result;
+}
+function version(event: LedgerEvent): void {
+  if (event.data.skillProposal !== 1) throw new Error("skill proposal: unsupported version; use an ares version supporting this journal and keep its files unchanged");
+}
+export function foldSkills(events: LedgerEvent[]): SkillRecord[] {
+  const rows = new Map<string, SkillRecord>();
+  for (const event of events) {
+    if (event.type === "skill.proposed") {
+      version(event); const proposal = validateSkillProposal(event.data.proposal, false), hash = sha256(markdown(proposal));
+      if (event.data.sha256 !== hash || rows.has(proposal.name) || rows.size >= SKILL_PROPOSALS) bad("journal has a mismatched hash, duplicate name or more than 100 proposals");
+      rows.set(proposal.name, { ...proposal, skillProposal: 1, state: "proposed", sha256: hash, actor: event.actor, at: event.at });
+    } else if (event.type === "skill.decided") {
+      version(event); const name = nameOf(event.data.name), row = rows.get(name), action = decisionOf(event.data.decision);
+      if (!row || row.state !== "proposed") bad("decision references a missing or already decided proposal");
+      const reason = text(event.data.reason, "reason"), pr = prOf(event.data.pr, action);
+      row.state = action === "accept" ? "accepted" : action === "reject" ? "rejected" : "withdrawn";
+      row.decision = { action, reason, ...(pr === undefined ? {} : { pr }), actor: event.actor, at: event.at };
+    }
+  }
+  return [...rows.values()];
+}
+function file(dir: string, name: string): string { return join(dir, "proposals", "skills", `${name}.md`); }
+/** Read only tracked proposals; every file is regular/bounded and bound to its original event. */
+function readSkills(dirArg: string) {
+  const { dir } = openStudy(dirArg), events = readLedger(dir), rows = foldSkills(events);
+  for (const row of rows) {
+    let content: string;
+    try { content = readTextBounded(file(dir, row.name), SKILL_BYTES); } catch { bad("proposal file missing, unreadable or larger than 16 KiB; restore its committed Markdown"); }
+    if (!content.startsWith("---\nskillProposal: 1\n")) throw new Error("skill proposal file: unsupported version; use an ares version supporting this file and keep it unchanged");
+    if (sha256(content) !== row.sha256) bad("proposal file differs from its receipt; restore the original Markdown");
+  }
+  return { dir, events, rows };
+}
+export function listSkills(dir: string): SkillRecord[] { return readSkills(dir).rows; }
+/** Caller holds the study lock. One bounded file and one event share the existing commit preflight. */
+export function proposeSkill(dirArg: string, raw: unknown, actor: Actor): SkillRecord {
+  const proposal = validateSkillProposal(raw), { dir, events, rows } = readSkills(dirArg);
+  if (rows.length >= SKILL_PROPOSALS) bad("100-proposal limit reached; start a new study for further proposals");
+  if (rows.some(row => row.name === proposal.name) || existsSync(file(dir, proposal.name))) bad("name or proposal file already exists; choose a new name without replacing prior work");
+  const content = markdown(proposal), hash = sha256(content);
+  const added = commit(dir, [[file(dir, proposal.name), content, SKILL_BYTES]], [{ actor, type: "skill.proposed", data: { skillProposal: 1, proposal, sha256: hash } }]);
+  return foldSkills([...events, ...added]).find(row => row.name === proposal.name)!;
+}
+/** Final actor-recorded decisions never open, inspect or merge a PR. */
+export function decideSkill(dirArg: string, name: string, decision: string, reason: string, pr: string | undefined, actor: Actor): SkillRecord {
+  const target = nameOf(name), action = decisionOf(decision), why = text(reason, "reason"), reference = prOf(pr, action), { dir, events, rows } = readSkills(dirArg);
+  const row = rows.find(row => row.name === target);
+  if (!row || row.state !== "proposed") bad("proposal is missing or already decided; decisions including withdrawal are final");
+  const added = commit(dir, [], [{ actor, type: "skill.decided", data: { skillProposal: 1, name: target, decision: action, reason: why, ...(reference === undefined ? {} : { pr: reference }) } }]);
+  return foldSkills([...events, ...added]).find(row => row.name === target)!;
+}

package/src/paper/build.ts

@@ -0,0 +1,73 @@
+import { requireCopilotAccept } from "../copilot.ts";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { assertWritable, commit, openStudy, plain, readLedger, readTextBounded, sha256, type Actor } from "../study.ts";
+import { checkPaper, manuscriptPath } from "./check.ts";
+import { MANUSCRIPT_BYTES } from "./placeholders.ts";
+
+export const PAPER_EVIDENCE_BYTES = 8 * 1024 * 1024;
+export interface PaperEvidence {
+  v: 1;
+  manuscriptSha256: string;
+  placeholders: {
+    kind: "number" | "literal"; raw: string; start: number; end: number; line: number; column: number;
+    ref?: string; format?: number; value: string | number; rendered: string;
+    source: { file: string; sha256: string };
+  }[];
+}
+export function paperBuildPaths(dir: string) { return { manuscript: join(dir, "paper", "build", "manuscript.md"), evidence: join(dir, "paper", "build", "evidence.json") }; }
+function previous(file: string, bound: number): string | undefined {
+  if (!existsSync(file)) return undefined;
+  try { return readTextBounded(file, bound); }
+  catch { throw new Error(`paper build: previous output is unreadable, non-regular, invalid UTF-8 or oversized; restore the last valid ${file.endsWith("evidence.json") ? "paper/build/evidence.json" : "paper/build/manuscript.md"} before rebuilding`); }
+}
+function evidenceBytes(dir: string): string | undefined {
+  const oldEvidence = previous(paperBuildPaths(dir).evidence, PAPER_EVIDENCE_BYTES);
+  if (oldEvidence !== undefined) {
+    let raw: unknown;
+    try { raw = JSON.parse(oldEvidence); } catch { throw new Error("paper evidence: invalid JSON; restore the last valid paper/build/evidence.json before rebuilding"); }
+    if (!plain(raw) || raw.v !== 1) throw new Error("paper evidence: unsupported version; use an ares version that supports it, keeping paper/build/evidence.json unchanged");
+  }
+  return oldEvidence;
+}
+function calculatePaper(dir: string) {
+  const report = checkPaper(dir);
+  if (!report.ok) {
+    const reasons = report.findings.slice(0, 10).map(f => `${f.code} at ${f.line}:${f.column}`).join(", ");
+    throw new Error(`paper build: paper check found ${report.findings.length} finding(s): ${reasons}; run ares paper check <dir> --json and fix every finding before rebuilding`);
+  }
+  const evidence: PaperEvidence = { v: 1, manuscriptSha256: report.manuscriptSha256, placeholders: report.placeholders.map(entry => {
+    const token = entry.placeholder;
+    return { kind: token.kind, raw: token.raw, start: token.start, end: token.end, line: token.line, column: token.column,
+      ...(token.kind === "number" ? { ref: token.ref, ...(token.format === undefined ? {} : { format: token.format }) } : {}),
+      value: entry.value, rendered: entry.rendered,
+      source: entry.source ?? { file: "paper/manuscript.md", sha256: report.manuscriptSha256 },
+    };
+  }) };
+  const text = JSON.stringify(evidence, null, 2) + "\n";
+  assertWritable(report.rendered, MANUSCRIPT_BYTES, "rendered manuscript; shorten paper/manuscript.md before rebuilding");
+  assertWritable(text, PAPER_EVIDENCE_BYTES, "paper evidence; reduce paper/manuscript.md or its placeholders before rebuilding");
+  return { report, evidence, text, manuscriptSha256: sha256(report.rendered), evidenceSha256: sha256(text) };
+}
+/** Caller holds the study lock. Refusals precede the single output-and-receipt commit. */
+export function buildPaper(dirArg: string, actor: Actor) {
+  const { dir } = openStudy(dirArg);
+  requireCopilotAccept(dir, "hypotheses");
+  const paths = paperBuildPaths(dir), oldEvidence = evidenceBytes(dir);
+  const { report, text, manuscriptSha256, evidenceSha256 } = calculatePaper(dir), oldManuscript = previous(paths.manuscript, MANUSCRIPT_BYTES);
+  const receipt = readLedger(dir).findLast(event => event.type === "paper.built");
+  const changed = oldManuscript !== report.rendered || oldEvidence !== text || receipt?.data.manuscriptSha256 !== manuscriptSha256 || receipt.data.evidenceSha256 !== evidenceSha256;
+  if (sha256(readTextBounded(manuscriptPath(dir), MANUSCRIPT_BYTES)) !== report.manuscriptSha256) throw new Error("paper build: source manuscript changed during checking; rerun ares paper check and paper build on the current manuscript");
+  if (changed) commit(dir, [[paths.manuscript, report.rendered, MANUSCRIPT_BYTES], [paths.evidence, text, PAPER_EVIDENCE_BYTES]], [{ actor, type: "paper.built", data: { manuscriptSha256, evidenceSha256, sourceManuscriptSha256: report.manuscriptSha256 } }]);
+  return { manuscriptSha256, evidenceSha256, changed };
+}
+
+
+/** The exact fresh build and both output receipts must agree; never repairs or writes files. */
+export function readCurrentBuild(dirArg: string) {
+  const { dir } = openStudy(dirArg), paths = paperBuildPaths(dir), evidence = evidenceBytes(dir), manuscript = previous(paths.manuscript, MANUSCRIPT_BYTES);
+  if (evidence === undefined || manuscript === undefined) throw new Error("paper build: missing output; run ares paper build before reviewing");
+  const fresh = calculatePaper(dir), receipt = readLedger(dir).findLast(event => event.type === "paper.built");
+  if (evidence !== fresh.text || manuscript !== fresh.report.rendered || receipt?.data.manuscriptSha256 !== fresh.manuscriptSha256 || receipt.data.evidenceSha256 !== fresh.evidenceSha256 || receipt.data.sourceManuscriptSha256 !== fresh.report.manuscriptSha256) throw new Error("paper build: stale outputs or missing/mismatched receipt; run ares paper check and ares paper build before reviewing");
+  return { manuscriptSha256: fresh.manuscriptSha256, evidenceSha256: fresh.evidenceSha256, check: fresh.report };
+}