@staix/agent-mem 0.6.0 → 0.8.0

package/src/memory/candidates.ts

@@ -2,11 +2,16 @@ import { Database } from "bun:sqlite";
 import { createHash } from "node:crypto";
 import { chmodSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { CANDIDATE_SHOWN_GRACE_MS, hasShownColumn } from "./candidate-pending.ts";
+import { oneLine } from "./note-add.ts";
 import { memoryHome } from "./home.ts";
 import { realPath } from "./platform.ts";
-import { MemoryStore, type NoteInput, type View } from "./store.ts";
+import { stripPrivateDeep } from "./private-spans.ts";
+import { MemoryStore, type GoalView, type NoteInput, type View } from "./store.ts";
 
 export const CANDIDATE_DB_BUSY_TIMEOUT_MS = 3000;
+/** First line of every note written by accepting a consolidation candidate; `consolidationClusters` reads it to avoid proposing summaries of its own summaries. */
+export const ACCEPTED_CONSOLIDATION_PREFIX = "Accepted consolidation candidate: ";
 export const CANDIDATE_RETENTION = { count: 500, ageMs: 30 * 86400_000 } as const;
 export const COUNTER_RETENTION = { count: 10_000, ageMs: 90 * 86400_000 } as const;
 export type CandidateVerdict = "public" | "private" | "pii" | "unknown";
@@ -16,6 +21,9 @@ export type CandidateInput = { project: string } & (
   | { kind: "fail"; target?: CandidateTarget; approach: string; symptom: string; cause: string; evidenceRefs: string[]; retryWhen: string }
   | { kind: "memory"; text: string; title?: string; noteKind?: "decision" | "finding" | "contract" | "fail" }
   | { kind: "decay"; target: CandidateTarget; reason: string }
+  | { kind: "promotion"; target: CandidateTarget; goalId: string }
+  | { kind: "consolidation"; action: "merge" | "supersession" | "recurring-fix"; targets: CandidateTarget[]; text: string; about: string[]; noteKind: "decision" | "finding" | "contract" | "fail" }
+  | { kind: "model-answer"; marker: "model-answer"; targets: CandidateTarget[]; text: string }
 );
 export type CandidateStatus = "pending" | "accepting" | "accepted" | "rejected";
 export interface Candidate { id: string; createdAt: string; status: CandidateStatus; input: CandidateInput; acceptedNoteId: string | null }
@@ -29,7 +37,9 @@ export interface CandidateAcceptance {
   actor: "person" | "agent";
   verdict: CandidateVerdict;
   store: MemoryStore;
-  policy: (candidate: Candidate, target: View | undefined, note: NoteInput) => boolean;
+  policy: (candidate: Candidate, target: View | undefined, note: NoteInput, goal?: GoalView) => boolean;
+  /** Required for multi-source consolidation; must change with the effective host policy. */
+  policyVersion?: () => string;
 }
 export interface CandidateAcceptanceResult { candidateId: string; noteId: string; alreadyAccepted: boolean }
 
@@ -53,12 +63,35 @@ function validate(input: CandidateInput): void {
     if (input.target !== undefined && !validTarget(input.target) || ![input.approach, input.symptom, input.cause, input.retryWhen].every(x => text(x)) || !Array.isArray(input.evidenceRefs) || input.evidenceRefs.length < 1 || input.evidenceRefs.length > 16 || !input.evidenceRefs.every(x => text(x, 400))) throw new Error("invalid fail candidate");
   } else if (input.kind === "memory") {
     if (!text(input.text, 3000) || input.title !== undefined && !text(input.title, 200) || input.noteKind !== undefined && !["decision", "finding", "contract", "fail"].includes(input.noteKind)) throw new Error("invalid memory candidate");
+  } else if (input.kind === "promotion") {
+    if (!validTarget(input.target) || !entryId(input.goalId)) throw new Error("invalid promotion candidate");
+  } else if (input.kind === "consolidation") {
+    if (!["merge", "supersession", "recurring-fix"].includes(input.action) || !Array.isArray(input.targets) || input.targets.length < 1 || input.targets.length > 8 || !input.targets.every(validTarget)
+      || new Set(input.targets.map(target => target.id)).size !== input.targets.length || !text(input.text, 3000) || !["decision", "finding", "contract", "fail"].includes(input.noteKind)
+      || !Array.isArray(input.about) || input.about.length > 32 || !input.about.every(node => text(node, 400))) throw Error("invalid consolidation candidate");
+  } else if (input.kind === "model-answer") {
+    if (input.marker !== "model-answer" || !text(input.text, 3000) || !input.text.startsWith("Model answer:\n") || !input.text.slice("Model answer:\n".length).trim() || !Array.isArray(input.targets) || input.targets.length < 1 || input.targets.length > 8 || !input.targets.every(validTarget)
+      || new Set(input.targets.map(target => target.id)).size !== input.targets.length) throw Error("invalid model answer candidate");
   } else if (input.kind === "decay") {
     if (!validTarget(input.target) || !text(input.reason)) throw new Error("invalid decay candidate");
   } else throw new Error("invalid candidate kind");
   if (Buffer.byteLength(canonical(input), "utf8") > 16_384) throw new Error("candidate payload exceeds 16 KiB");
 }
 
+/** The same normalized identity used by put(), without a sidecar write or a capped listing. */
+export function candidateInputId(rawInput: CandidateInput): string {
+  const input = stripPrivateDeep(rawInput); validate(input);
+  return hash({ schema: "agent-mem.candidate/v1", input });
+}
+/** Exact correction body shared by proposal validation and person acceptance. */
+export function acceptedCorrectionText(input: Extract<CandidateInput, { kind: "correction" }>, id = candidateInputId(input)): string {
+  const data = stripPrivateDeep(input);
+  return `Accepted candidate: ${id}\nTarget revision: ${data.target.revision}\nTarget entry: ${data.target.id}\n\n${data.proposedText}\n\nReason: ${data.reason}`;
+}
+export function goalPromotionLinked(view: Pick<View, "task" | "about">, goal: Pick<GoalView, "id" | "links">): boolean {
+  const tasks = new Set(goal.links.map(link => link.task));
+  return !!view.task && tasks.has(view.task) || view.about.some(node => node === `goal:${goal.id}` || node.startsWith("task:") && tasks.has(node.slice(5)));
+}
 /** Includes current lifecycle state, so a changed promotion, supersession or demotion makes a proposal stale. */
 export function candidateTargetRevision(target: View): string {
   return hash({ ...target, about: [...target.about].sort(), supersedes: [...target.supersedes].sort() });
@@ -71,6 +104,23 @@ function counterKey(key: CounterKey): CounterKey {
 }
 
 /** Explicitly opened machine-local data. Importing this module never opens a store or registers a consumer. */
+/** Run `work`, retrying only SQLite's "database is locked" for at most about two seconds; any other error, or the last lock error, is thrown. */
+function retryLocked(work: () => void): void {
+  const until = Date.now() + 2000;
+  for (let delay = 5;; delay = Math.min(delay * 2, 100)) {
+    try { work(); return; }
+    catch (error) {
+      if (!/database is locked|SQLITE_BUSY/i.test((error as Error).message) || Date.now() >= until) throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delay);
+    }
+  }
+}
+
+/** The queue holds the cap's worth of candidates nobody has seen. Named so a caller (the MCP tool) can map it; the message is worded for an agent, which cannot run the person-only commands itself. */
+export class CandidateQueueFull extends Error {
+  readonly code = "candidate_queue_full";
+  constructor(readonly waiting: number) { super(`${waiting} unshown candidates await the person's review; no more are accepted until they have run \`amem review\`. Ask the person to review them`); this.name = "CandidateQueueFull"; }
+}
 export class CandidateStore {
   readonly dir: string;
   readonly path: string;
@@ -88,18 +138,27 @@ export class CandidateStore {
     this.path = join(this.dir, "candidates.db");
     this.db = new Database(this.path, { create: true });
     this.db.run(`PRAGMA busy_timeout = ${CANDIDATE_DB_BUSY_TIMEOUT_MS}`);
-    chmodSync(this.path, 0o600); this.db.run("PRAGMA journal_mode = WAL");
+    chmodSync(this.path, 0o600);
+    // `journal_mode = WAL` takes a lock that busy_timeout does not always wait for, so several processes opening a brand-new home at once (every `amem mcp` builds this store at
+    // startup) can see "database is locked". It is retried for a bounded time: the first caller switches the mode, the others then find it already WAL.
+    retryLocked(() => this.db.run("PRAGMA journal_mode = WAL"));
     this.db.run("CREATE TABLE IF NOT EXISTS candidates (id TEXT PRIMARY KEY, project TEXT NOT NULL, kind TEXT NOT NULL, payload TEXT NOT NULL, at INTEGER NOT NULL, status TEXT NOT NULL, note_id TEXT)");
+    // F7 / AC4: when a candidate was first shown to the person. In place and nullable: an older database gains it here, and a reader without it treats every row as unshown.
+    // Several processes open this store at once (every `amem mcp` builds it at startup), so the check and the ALTER are one immediate transaction: the loser waits, then sees the column.
+    if (!hasShownColumn(this.db)) this.db.transaction(() => { if (!hasShownColumn(this.db)) this.db.run("ALTER TABLE candidates ADD COLUMN shown_at INTEGER"); }).immediate();
     this.db.run("CREATE TABLE IF NOT EXISTS counters (id TEXT PRIMARY KEY, project TEXT NOT NULL, payload TEXT NOT NULL, at INTEGER NOT NULL, rendered INTEGER, delivered INTEGER, cited INTEGER)");
     this.prune();
   }
   close(): void { this.db.close(); }
   private prune(): void {
     this.db.transaction(() => {
-      for (const [table, retention] of [["candidates", CANDIDATE_RETENTION], ["counters", COUNTER_RETENTION]] as const) {
-        this.db.query(`DELETE FROM ${table} WHERE at <= ?`).run(this.now() - retention.ageMs);
-        this.db.query(`DELETE FROM ${table} WHERE rowid IN (SELECT rowid FROM (SELECT rowid, row_number() OVER (PARTITION BY project ORDER BY at DESC, rowid DESC) AS rank FROM ${table}) WHERE rank > ?)`).run(retention.count);
-      }
+      const now = this.now();
+      // Candidates (AC4, no candidate expires unshown): by age only a decided one, or a pending one that was shown and has had its grace period, goes. By count three tiers decide who is
+      // kept: unshown pending first, then shown pending, then decided, so a cap eviction takes decided rows before a shown one (which is owed its grace) and shown ones before an unseen one.
+      this.db.query("DELETE FROM candidates WHERE at <= ? AND (status IN ('accepted', 'rejected') OR (shown_at IS NOT NULL AND shown_at <= ?))").run(now - CANDIDATE_RETENTION.ageMs, now - CANDIDATE_SHOWN_GRACE_MS);
+      this.db.query(`DELETE FROM candidates WHERE rowid IN (SELECT rowid FROM (SELECT rowid, row_number() OVER (PARTITION BY project ORDER BY CASE WHEN status IN ('pending', 'accepting') AND shown_at IS NULL THEN 2 WHEN status IN ('pending', 'accepting') THEN 1 ELSE 0 END DESC, at DESC, rowid DESC) AS rank FROM candidates) WHERE rank > ?)`).run(CANDIDATE_RETENTION.count);
+      this.db.query("DELETE FROM counters WHERE at <= ?").run(now - COUNTER_RETENTION.ageMs);
+      this.db.query("DELETE FROM counters WHERE rowid IN (SELECT rowid FROM (SELECT rowid, row_number() OVER (PARTITION BY project ORDER BY at DESC, rowid DESC) AS rank FROM counters) WHERE rank > ?)").run(COUNTER_RETENTION.count);
     }).immediate();
   }
   private decode(row: { id: string; payload: string; at: number; status: CandidateStatus; note_id: string | null }): Candidate {
@@ -107,11 +166,22 @@ export class CandidateStore {
     if (hash({ schema: "agent-mem.candidate/v1", input }) !== row.id) throw new Error("candidate content hash mismatch");
     return { id: row.id, createdAt: new Date(row.at).toISOString(), status: row.status, input, acceptedNoteId: row.note_id };
   }
-  put(input: CandidateInput, verdict: CandidateVerdict): string {
-    publicOnly(verdict); validate(input); this.prune();
-    const payload = canonical(input), id = hash({ schema: "agent-mem.candidate/v1", input });
-    this.db.query("INSERT OR IGNORE INTO candidates (id, project, kind, payload, at, status) VALUES (?, ?, ?, ?, ?, 'pending')").run(id, input.project, input.kind, payload, this.now());
-    this.prune(); return id;
+  put(rawInput: CandidateInput, verdict: CandidateVerdict): string {
+    // `<private>` spans are never stored: dropped before the input is validated, hashed (so the id) or written.
+    const input = stripPrivateDeep(rawInput);
+    publicOnly(verdict); validate(input);
+    const payload = canonical(input), id = candidateInputId(input);
+    // Prune, count, insert and prune again are ONE immediate transaction: concurrent proposers (several agents) cannot all pass the count and then let the cap evict an unseen candidate.
+    return this.db.transaction((): string => {
+      this.prune();
+      // AC4: a new candidate never pushes an unshown one out. With the cap's worth waiting the person has to review first, and the refusal says so (a named error an MCP tool can map).
+      const waiting = (this.db.query("SELECT COUNT(*) AS n FROM candidates WHERE project = ? AND status IN ('pending', 'accepting') AND shown_at IS NULL").get(input.project) as { n: number }).n;
+      const known = this.db.query("SELECT 1 FROM candidates WHERE id = ?").get(id);
+      if (!known && waiting >= CANDIDATE_RETENTION.count) throw new CandidateQueueFull(waiting);
+      this.db.query("INSERT OR IGNORE INTO candidates (id, project, kind, payload, at, status) VALUES (?, ?, ?, ?, ?, 'pending')").run(id, input.project, input.kind, payload, this.now());
+      this.prune();
+      return id;
+    }).immediate();
   }
   get(id: string, project: string): Candidate | undefined {
     if (!candidateId(id) || !text(project, 400)) throw new Error("invalid candidate identity");
@@ -120,7 +190,7 @@ export class CandidateStore {
     return row ? this.decode(row) : undefined;
   }
   list(filter: CandidateFilter): Candidate[] {
-    if (!text(filter.project, 400) || filter.status !== undefined && !["pending", "accepting", "accepted", "rejected", "all"].includes(filter.status) || filter.kind !== undefined && !["correction", "fail", "decay", "memory"].includes(filter.kind)) throw new Error("invalid candidate filter");
+    if (!text(filter.project, 400) || filter.status !== undefined && !["pending", "accepting", "accepted", "rejected", "all"].includes(filter.status) || filter.kind !== undefined && !["correction", "fail", "decay", "memory", "promotion", "consolidation", "model-answer"].includes(filter.kind)) throw new Error("invalid candidate filter");
     const limit = filter.limit ?? CANDIDATE_RETENTION.count;
     if (!Number.isSafeInteger(limit) || limit < 1 || limit > CANDIDATE_RETENTION.count) throw new Error("candidate limit must be 1..500");
     this.prune();
@@ -163,42 +233,153 @@ export class CandidateStore {
     if (!candidate) throw new Error("candidate unavailable");
     if (candidate.status === "accepted") return { candidateId: id, noteId: candidate.acceptedNoteId!, alreadyAccepted: true };
     if (candidate.status !== "pending") throw new Error("candidate is rejected or acceptance was interrupted; no automatic replay");
-    if (candidate.input.kind === "decay") throw new Error("decay candidates are listing-only; no automatic mutation is available");
+    const data = candidate.input;
+    if (data.kind === "model-answer") throw Error("model answers cannot become curated memory; use amem note add to author an independent note");
+    if (data.kind === "decay") throw new Error("decay candidates are listing-only; no automatic mutation is available");
+    if (data.kind === "promotion") return this.acceptPromotion(candidate, data, context);
+    if (data.kind === "consolidation") return this.acceptConsolidation(candidate, data, context);
+    const execute = () => {
+      const resolve = () => {
+        const target = data.kind === "memory" ? undefined : data.target;
+        if (!target) return undefined;
+        const current = context.store.get(target.id, context.project);
+        if (!current || current.id !== target.id || candidateTargetRevision(current) !== target.revision) throw new Error("candidate target revision is stale");
+        return current;
+      };
+      const target = resolve();
+      const body = data.kind === "memory" ? data.text : data.kind === "correction" ? `${data.proposedText}\n\nReason: ${data.reason}`
+        : `Approach: ${oneLine(data.approach)}\nSymptom: ${oneLine(data.symptom)}\nCause: ${oneLine(data.cause)}\nEvidence: ${data.evidenceRefs.map(oneLine).join(", ")}\nRetry when: ${oneLine(data.retryWhen)}`;
+      const note: NoteInput = { op: "note", ...(data.kind === "memory" && data.title ? { title: data.title } : {}), project: data.kind === "correction" ? target!.project : context.project,
+        scope: data.kind === "correction" ? target!.scope : "project",
+        // A demoted synced target is logically short, but replacing it locally would narrow its reach (X04).
+        tier: data.kind === "correction" && target!.local ? "short" : "long",
+        kind: data.kind === "fail" ? "fail" : data.noteKind ?? (target?.kind === "contract" || target?.kind === "fail" ? target.kind : "decision"), peer: "person", source: "person", about: [...target?.about ?? []],
+        text: data.kind === "correction" ? acceptedCorrectionText(data, id) : `Accepted candidate: ${id}\nTarget revision: ${(data.kind === "memory" ? undefined : data.target)?.revision ?? "none"}\nTarget entry: ${(data.kind === "memory" ? undefined : data.target)?.id ?? "none"}\n\n${body}` };
+      if (note.text.length > 4000) throw new Error("accepted candidate text exceeds the v1 note limit");
+      if (context.policy(structuredClone(candidate), target && structuredClone(target), structuredClone(note)) !== true) throw new Error("candidate refused by current host policy");
+      return context.store.withAcceptedNote(note, append => {
+        resolve(); // Recheck under the same mutation lock as the note and supersede appends.
+        const started = this.beginAcceptance(id, context.project);
+        if (started) return { candidateId: id, noteId: started, alreadyAccepted: true };
+        // ponytail: the sidecar receipt and v1 append are not one transaction. An interrupted 'accepting' row refuses
+        // automatic replay; add explicit person-audited recovery before offering background acceptance retries.
+        const noteId = append();
+        if (data.kind === "correction" && !context.store.supersede(target!.id, noteId, "person", context.project)) throw new Error("candidate replacement refused; inspect the accepted note before recovery");
+        this.db.query("UPDATE candidates SET status = 'accepted', note_id = ? WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(noteId, id, this.scope(context.project));
+        return { candidateId: id, noteId, alreadyAccepted: false };
+      });
+    };
+    const target = data.kind === "memory" ? undefined : data.target;
+    if (!target) return execute();
+    const current = context.store.get(target.id, context.project);
+    if (!current || current.id !== target.id || candidateTargetRevision(current) !== target.revision) throw new Error("candidate target revision is stale");
+    return context.store.withCurrentEntries([target.id], context.project, execute);
+  }
+  private acceptConsolidation(candidate: Candidate, data: Extract<CandidateInput, { kind: "consolidation" }>, context: CandidateAcceptance): CandidateAcceptanceResult {
+    if (typeof context.policyVersion !== "function") throw Error("consolidation requires a policy revision guard");
+    const boundStore = context.store, boundProject = context.project, boundPolicy = context.policy;
+    const policyVersion = context.policyVersion(); if (typeof policyVersion !== "string") throw Error("consolidation policy revision unavailable");
+    return context.store.withCurrentEntries(data.targets.map(target => target.id), context.project, () => {
+      const sourcePlacements = context.store.entryPlacements(data.targets.map(target => target.id), context.project);
+      if (data.targets.some(target => sourcePlacements.get(target.id) !== "synced")) throw Error("consolidation requires verified synced source placement");
+      const policyCurrent = () => {
+        if (context.actor !== "person" || context.store !== boundStore || context.project !== boundProject || context.policy !== boundPolicy) throw Error("consolidation acceptance context changed");
+        if (context.policyVersion!() !== policyVersion) throw Error("consolidation policy changed");
+      };
+      // One placement proof per locked section: `sourcePlacements` (read once inside withCurrentEntries, whose fences stay held) serves every check before the append section;
+      // the append section reads one fresh proof. Each proof re-reads the legacy snapshot (up to 32 MiB), so four per acceptance was the cost this removes.
+      const check = (fresh = false) => {
+        policyCurrent();
+        const current = data.targets.map(target => {
+          const row = context.store.get(target.id, context.project);
+          if (!row || row.id !== target.id || row.project !== context.project || row.supersededBy || candidateTargetRevision(row) !== target.revision) throw Error("consolidation source revision is stale");
+          return row;
+        });
+        const placements = fresh ? context.store.entryPlacements(data.targets.map(target => target.id), context.project) : sourcePlacements;
+        if (current.some(row => row.scope !== current[0]!.scope || placements.get(row.id) !== placements.get(current[0]!.id))) throw Error("consolidation sources must have the same placement and scope");
+        if (data.targets.some(target => placements.get(target.id) !== sourcePlacements.get(target.id))) throw Error("consolidation source placement changed");
+        policyCurrent(); // The proof scan can be long; fence policy changes after it, not only before it.
+        return current;
+      };
+      const sources = check(), first = sources[0]!;
+      const note: NoteInput = { op: "note", project: context.project, scope: first.scope, tier: "long", kind: data.noteKind, peer: "person", source: "person", about: [...data.about],
+        text: `${ACCEPTED_CONSOLIDATION_PREFIX}${candidate.id}\nAction: ${data.action}\nSources: ${data.targets.map(target => `mem:${target.id}`).join(", ")}\n\n${data.text}` };
+      if (note.text.length > 4000) throw Error("accepted consolidation exceeds the v1 note limit");
+      for (const source of sources) if (context.policy(structuredClone(candidate), structuredClone(source), structuredClone(note)) !== true) throw Error("consolidation refused by current host policy");
+      check();
+      return context.store.withAcceptedNote(note, append => {
+        check(true);
+        const replay = this.beginAcceptance(candidate.id, context.project, policyCurrent); if (replay) return { candidateId: candidate.id, noteId: replay, alreadyAccepted: true };
+        const noteId = append(), applied: string[] = [];
+        try {
+          if (data.action !== "recurring-fix") for (const target of data.targets) {
+            if (!context.store.supersede(target.id, noteId, "person", context.project)) throw Error("supersession refused");
+            applied.push(target.id);
+          }
+        } catch {
+          // ponytail: v1 appends cannot form an atomic multi-source replacement. Keep 'accepting' and
+          // report every confirmed effect; recovery requires person inspection before any replay.
+          throw Error(`consolidation interrupted: inspect note ${noteId}; superseded ${applied.join(", ") || "none"}; remaining or uncertain ${data.targets.filter(target => !applied.includes(target.id)).map(target => target.id).join(", ")}`);
+        }
+        this.db.query("UPDATE candidates SET status = 'accepted', note_id = ? WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(noteId, candidate.id, this.scope(context.project));
+        return { candidateId: candidate.id, noteId, alreadyAccepted: false };
+      });
+    });
+  }
+  private acceptPromotion(candidate: Candidate, data: Extract<CandidateInput, { kind: "promotion" }>, context: CandidateAcceptance): CandidateAcceptanceResult {
     const resolve = () => {
-      const target = candidate.input.kind === "memory" ? undefined : candidate.input.target;
-      if (!target) return undefined;
-      const current = context.store.get(target.id, context.project);
-      if (!current || current.id !== target.id || candidateTargetRevision(current) !== target.revision) throw new Error("candidate target revision is stale");
-      return current;
+      const target = context.store.get(data.target.id, context.project);
+      if (!target || target.id !== data.target.id || candidateTargetRevision(target) !== data.target.revision || target.tier !== "short" || target.supersededBy) throw Error("candidate target revision is stale");
+      const goal = context.store.goalOf(data.goalId, context.project);
+      if (!goal || goal.id !== data.goalId || goal.state !== "done" || !goalPromotionLinked(target, goal)) throw Error("promotion requires a current done goal and a linked short note");
+      return { target, goal };
     };
-    const target = resolve(), data = candidate.input;
-    const body = data.kind === "memory" ? data.text : data.kind === "correction" ? `${data.proposedText}\n\nReason: ${data.reason}`
-      : `Approach: ${data.approach}\nSymptom: ${data.symptom}\nCause: ${data.cause}\nEvidence: ${data.evidenceRefs.join(", ")}\nRetry when: ${data.retryWhen}`;
-    const note: NoteInput = { op: "note", ...(data.kind === "memory" && data.title ? { title: data.title } : {}), project: data.kind === "correction" ? target!.project : context.project,
-      scope: data.kind === "correction" ? target!.scope : "project",
-      // A demoted synced target is logically short, but replacing it locally would narrow its reach (X04).
-      tier: data.kind === "correction" && target!.local ? "short" : "long",
-      kind: data.kind === "fail" ? "fail" : data.noteKind ?? (target?.kind === "contract" || target?.kind === "fail" ? target.kind : "decision"), peer: "person", source: "person", about: [...target?.about ?? []],
-      text: `Accepted candidate: ${id}\nTarget revision: ${(data.kind === "memory" ? undefined : data.target)?.revision ?? "none"}\nTarget entry: ${(data.kind === "memory" ? undefined : data.target)?.id ?? "none"}\n\n${body}` };
-    if (note.text.length > 4000) throw new Error("accepted candidate text exceeds the v1 note limit");
-    if (context.policy(structuredClone(candidate), target && structuredClone(target), structuredClone(note)) !== true) throw new Error("candidate refused by current host policy");
-    return context.store.withAcceptedNote(note, append => {
-      resolve(); // Recheck under the same mutation lock as the note and supersede appends.
-      const started = this.db.transaction(() => {
-        const current = this.get(id, context.project);
-        if (!current) throw new Error("candidate unavailable");
-        if (current.status === "accepted") return current.acceptedNoteId!;
-        if (current.status !== "pending") throw new Error("candidate is rejected or acceptance was interrupted; no automatic replay");
-        this.db.query("UPDATE candidates SET status = 'accepting' WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(id, this.scope(context.project));
-        return undefined;
-      }).immediate();
-      if (started) return { candidateId: id, noteId: started, alreadyAccepted: true };
-      // ponytail: the sidecar receipt and v1 append are not one transaction. An interrupted 'accepting' row refuses
-      // automatic replay; add explicit person-audited recovery before offering background acceptance retries.
-      const noteId = append();
-      if (data.kind === "correction" && !context.store.supersede(target!.id, noteId, "person", context.project)) throw new Error("candidate replacement refused; inspect the accepted note before recovery");
-      this.db.query("UPDATE candidates SET status = 'accepted', note_id = ? WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(noteId, id, this.scope(context.project));
-      return { candidateId: id, noteId, alreadyAccepted: false };
+    resolve();
+    return context.store.withCurrentEntries([data.target.id], context.project, () => {
+      const { target, goal } = resolve();
+      const note: NoteInput = { op: "note", project: target.project, scope: target.scope, tier: "long", kind: target.kind, peer: target.peer, source: target.source as NoteInput["source"], text: target.text, about: [...target.about],
+        ...(target.title ? { title: target.title } : {}), ...(target.task ? { task: target.task } : {}), promotedFrom: target.id };
+      if (context.policy(structuredClone(candidate), structuredClone(target), structuredClone(note), structuredClone(goal)) !== true) throw Error("candidate refused by current host policy");
+      resolve();
+      const replay = this.beginAcceptance(candidate.id, context.project); if (replay) return { candidateId: candidate.id, noteId: replay, alreadyAccepted: true };
+      // A thrown append remains accepting: its authored-row outcome needs person-audited recovery.
+      const noteId = context.store.promote(target.id, "person", context.project);
+      if (noteId === undefined) {
+        this.db.query("UPDATE candidates SET status = 'pending' WHERE id = ? AND project IN (SELECT value FROM json_each(?)) AND status = 'accepting'").run(candidate.id, this.scope(context.project));
+        throw Error("promotion unavailable or declined; candidate remains pending");
+      }
+      const promoted = context.store.get(noteId, context.project);
+      if (noteId === target.id || !promoted || promoted.id !== noteId || promoted.tier !== "long" || promoted.promotedFrom !== target.id) throw Error("promotion outcome unconfirmed; inspect the accepting candidate");
+      this.db.query("UPDATE candidates SET status = 'accepted', note_id = ? WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(noteId, candidate.id, this.scope(context.project));
+      return { candidateId: candidate.id, noteId, alreadyAccepted: false };
     });
   }
+  /** Reserve before the optional callback, including failed attempts. No table is created on capture/MCP reads. */
+  reserveConsolidationModel(inputBytes: number): boolean {
+    if (!Number.isSafeInteger(inputBytes) || inputBytes < 1 || inputBytes > 8192) throw Error("invalid model input budget");
+    const at = this.now(); if (!Number.isFinite(at)) throw Error("model budget clock unavailable");
+    const day = new Date(at).toISOString().slice(0, 10);
+    return this.db.transaction(() => {
+      this.db.run("CREATE TABLE IF NOT EXISTS consolidation_budget (day TEXT PRIMARY KEY, calls INTEGER NOT NULL, input_bytes INTEGER NOT NULL)");
+      const latest = this.db.query("SELECT MAX(day) AS day FROM consolidation_budget").get() as { day: string | null };
+      if (latest.day && latest.day > day) return false;
+      const row = this.db.query("SELECT calls,input_bytes FROM consolidation_budget WHERE day = ?").get(day) as { calls: number; input_bytes: number } | null;
+      if (row && (!Number.isSafeInteger(row.calls) || row.calls < 0 || !Number.isSafeInteger(row.input_bytes) || row.input_bytes < 0)) throw Error("model budget state unavailable");
+      if (row && (row.calls >= 4 || row.input_bytes + inputBytes > 32768)) return false;
+      this.db.query("INSERT INTO consolidation_budget (day,calls,input_bytes) VALUES (?,1,?) ON CONFLICT(day) DO UPDATE SET calls = calls + 1, input_bytes = input_bytes + excluded.input_bytes").run(day, inputBytes);
+      this.db.query("DELETE FROM consolidation_budget WHERE day < ?").run(new Date(at - 30 * 86400_000).toISOString().slice(0, 10));
+      return true;
+    }).immediate();
+  }
+  private beginAcceptance(id: string, project: string, before?: () => void): string | undefined {
+    return this.db.transaction(() => {
+      const current = this.get(id, project);
+      if (!current) throw Error("candidate unavailable");
+      if (current.status === "accepted") return current.acceptedNoteId!;
+      if (current.status !== "pending") throw Error("candidate is rejected or acceptance was interrupted; no automatic replay");
+      before?.();
+      this.db.query("UPDATE candidates SET status = 'accepting' WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(id, this.scope(project));
+      return undefined;
+    }).immediate();
+  }
 }

package/src/memory/capacity-split.ts

@@ -0,0 +1,76 @@
+import { lstatSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { capacityReport, type ShardSplit } from "./capacity.ts";
+import { readCaptureConfigFile, writeCaptureConfigFile, type CaptureConfig } from "./capture.ts";
+import { walkShards } from "./catalog.ts";
+import { lifecycleResolver } from "./lifecycle.ts";
+import { machineId } from "./store.ts";
+
+/**
+ * #15 T5 / D7: `amem capacity apply --split`. Writes each shard's own capture config (`machine/<id>/config.json`, which overrides the home default) with its
+ * share of the global budget. Person-only like the other apply (the CLI refuses an agent marker and a missing terminal before this runs), and in two steps:
+ * a preview that records which shards, which current configs and which target values the person is shown, and a `--confirm` that writes exactly those
+ * target values and nothing recomputed. It refuses unless the set of shards and every shard's current config are unchanged, and unless the preview is younger
+ * than `PREVIEW_MAX_AGE_MS`: a week-old preview cannot write a cap the person never saw, and free disk drifting a little between the two steps changes nothing
+ * that is written. A forgotten shard is never written. This changes capture bounds only: gc and the capture path apply them later, in bounded
+ * batches (R2); nothing is evicted here, and no curated note, goal or work list is read or written.
+ */
+
+export interface SplitTarget { key: string; dir: string; current: Partial<CaptureConfig>; target: CaptureConfig; reason: string }
+export interface SplitPreview { at: number; split: SplitTarget[]; skipped: string[] }
+/** A preview older than this is refused: the person saw those values, but the readings behind them are stale. */
+export const PREVIEW_MAX_AGE_MS = 3600_000;
+
+const previewPath = (base: string): string => join(base, "capacity-split.preview.json");
+
+/**
+ * One target per non-forgotten shard that has a directory of this machine. A shard that only another machine has (a synced home) is never written here: that
+ * machine's config is its own, so the shard is left out and named in `skipped`. The directory is matched by its name, which is portable, not by a path suffix.
+ */
+function targets(base: string, split: ShardSplit[]): { targets: SplitTarget[]; skipped: string[] } {
+  const dirs = new Map(walkShards(base).map(shard => [shard.key, shard.machineDirs]));
+  const stateOf = lifecycleResolver(base);
+  const machine = machineId(base).id;
+  const out: SplitTarget[] = [], skipped: string[] = [];
+  for (const row of split) {
+    if (stateOf(row.key) === "forgotten") continue;
+    const dir = (dirs.get(row.key) ?? []).find(candidate => basename(candidate) === machine);
+    if (!dir) { skipped.push(row.key); continue; }
+    out.push({ key: row.key, dir, current: readCaptureConfigFile(join(dir, "config.json")), target: { capMb: row.capMb, retentionDays: row.retentionDays }, reason: row.reason });
+  }
+  return { targets: out, skipped };
+}
+
+export function previewSplit(base: string, opts: { diskShare?: number; now?: () => number } = {}): SplitPreview & { confirm: string } {
+  const report = capacityReport({ memoryDir: base, ...(opts.diskShare !== undefined ? { diskShare: opts.diskShare } : {}) });
+  if (report.splitRefused) throw new Error(`capacity apply --split: ${report.splitRefused}`);
+  const found = targets(base, report.split);
+  const preview: SplitPreview = { at: (opts.now ?? Date.now)(), split: found.targets, skipped: found.skipped };
+  writeFileSync(previewPath(base), JSON.stringify(preview) + "\n", { mode: 0o600 });
+  return { ...preview, confirm: "re-run with --confirm to write each shard's share" };
+}
+
+export function applySplit(base: string, opts: { diskShare?: number; now?: () => number } = {}): { split: SplitTarget[]; written: { key: string; cap_mb: number; retention_days: number }[] } {
+  const file = previewPath(base);
+  let approved: SplitPreview;
+  try {
+    const stat = lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024) throw new Error();
+    approved = JSON.parse(readFileSync(file, "utf8")) as SplitPreview;
+  } catch { throw new Error("capacity apply --split needs a preview first; re-run without --confirm"); }
+  const report = capacityReport({ memoryDir: base, ...(opts.diskShare !== undefined ? { diskShare: opts.diskShare } : {}) });
+  if (report.splitRefused) throw new Error(`capacity apply --split: ${report.splitRefused}`);
+  const live = targets(base, report.split).targets;
+  const age = (opts.now ?? Date.now)() - approved.at;
+  if (!Number.isFinite(age) || age < 0 || age > PREVIEW_MAX_AGE_MS) throw new Error("capacity preview is out of date (older than an hour); re-run without --confirm");
+  // What was previewed is what is written: the same shards, each with the config the person saw replaced by the target the person saw.
+  const identity = (rows: SplitTarget[]) => JSON.stringify(rows.map(({ key, dir, current }) => ({ key, dir, current })));
+  if (!Array.isArray(approved.split) || identity(approved.split) !== identity(live)) throw new Error("capacity preview changed (a shard appeared or went, or a shard's config moved); re-run without --confirm");
+  const written = approved.split.map(row => {
+    const next = writeCaptureConfigFile(join(row.dir, "config.json"), row.target);
+    return { key: row.key, cap_mb: next.capMb ?? row.target.capMb, retention_days: next.retentionDays ?? row.target.retentionDays };
+  });
+  rmSync(file, { force: true });
+  return { split: approved.split, written };
+}
+