@staix/agent-mem 0.6.0 → 0.8.0

package/src/memory/consolidation-clusters.ts

@@ -0,0 +1,56 @@
+import { SearchIndex } from "./search-fts.ts";
+import { recallViewIsLive } from "./recall.ts";
+import { ACCEPTED_CONSOLIDATION_PREFIX } from "./candidates.ts";
+import type { View } from "./store.ts";
+
+export type ConsolidationAction = "merge" | "supersession" | "recurring-fix";
+export interface ConsolidationCluster { action: ConsolidationAction; sources: View[]; reason: string }
+export const CONSOLIDATION_SOURCE_LIMIT = 256, CONSOLIDATION_PROPOSAL_LIMIT = 32;
+const words = (row: View) => new Set((`${row.title ?? ""} ${row.text}`.toLowerCase().match(/[\p{L}\p{N}_]{3,}/gu) ?? []).filter(word => !["the", "and", "for", "with", "from", "this", "that", "approach", "symptom", "cause", "evidence", "retry", "when"].includes(word)).slice(0, 128));
+/** A note written by accepting a consolidation candidate. Proposing over one would be a summary of summaries. */
+export const isAcceptedConsolidation = (row: Pick<View, "text">): boolean => row.text.startsWith(ACCEPTED_CONSOLIDATION_PREFIX);
+/** An accepted recurring-fix summary keeps its sources live and quotes them whole, so it overlaps each of them. */
+const isAcceptedRecurringFix = (row: Pick<View, "text">): boolean => isAcceptedConsolidation(row) && /^Action: recurring-fix$/m.test(row.text.split("\n\n", 1)[0] ?? "");
+const paths = (row: View) => row.about.filter(node => node.startsWith("path:"));
+const sharedPath = (a: View, b: View) => paths(a).some(node => paths(b).includes(node));
+const overlap = (a: Set<string>, b: Set<string>) => [...a].filter(word => b.has(word)).length / Math.max(1, Math.min(a.size, b.size));
+
+/** Bounded deterministic proposals over already-screened rows. Never mutates a note or runs a model. */
+export function consolidationClusters(input: readonly View[], project: string, now: number): { clusters: ConsolidationCluster[]; truncated: boolean; engine: "fts5" | "substring" } {
+  if (!project.trim() || !Number.isFinite(now)) throw Error("consolidation context unavailable");
+  const eligible = input.filter(row => row.project === project && recallViewIsLive(row, now))
+    .sort((a, b) => b.at.localeCompare(a.at) || a.id.localeCompare(b.id));
+  const rows = [...new Map(eligible.map(row => [row.id, row])).values()].slice(0, CONSOLIDATION_SOURCE_LIMIT);
+  const index = new SearchIndex(":memory:"), clusters: ConsolidationCluster[] = [], seen = new Set<string>();
+  let truncated = eligible.length > rows.length;
+  const add = (action: ConsolidationAction, sources: View[], reason: string) => {
+    const key = `${action}:${sources.map(row => row.id).sort().join(":")}`;
+    if (seen.has(key)) return; seen.add(key);
+    if (clusters.length === CONSOLIDATION_PROPOSAL_LIMIT) { truncated = true; return; }
+    clusters.push({ action, sources, reason });
+  };
+  try {
+    index.resync(() => rows.map(row => ({ id: row.id, at: row.at, project, tier: row.tier, scope: row.scope, body: `${row.title ?? ""}\n${row.text}` })));
+    if (index.available && index.needsResync(rows.length)) throw Error("consolidation index unavailable");
+    const terms = new Map(rows.map(row => [row.id, words(row)]));
+    for (let i = 0; i < rows.length; i++) {
+      const row = rows[i]!, candidates = index.available ? new Set(index.query([...terms.get(row.id)!].slice(0, 32).join(" "), rows.length, project).map(hit => hit.ref)) : undefined;
+      for (const peer of rows.slice(i + 1)) {
+        if (row.kind !== peer.kind || isAcceptedRecurringFix(row) || isAcceptedRecurringFix(peer)) continue;
+        const lexical = overlap(terms.get(row.id)!, terms.get(peer.id)!);
+        if (row.text === peer.text) add("supersession", [row, peer], "Identical text; review one replacement for both originals.");
+        else if ((!candidates || candidates.has(peer.id)) && lexical >= 0.5 && sharedPath(row, peer)) add("merge", [row, peer], "Shared path and overlapping indexed terms; no equivalence is assumed.");
+      }
+      // A retained supersession chain is context, never a reason to resurrect an old body.
+      if (row.supersedes.length >= 2 && !isAcceptedConsolidation(row)) add("merge", [row], "Current head already replaces multiple originals; review a chain summary.");
+    }
+    const failRows = rows.filter(row => row.kind === "fail" && !isAcceptedConsolidation(row)), decisions = rows.filter(row => row.kind === "decision" || row.kind === "contract");
+    for (let i = 0; i < failRows.length; i++) for (const peer of failRows.slice(i + 1)) {
+      const fail = failRows[i]!;
+      if (!sharedPath(fail, peer) || overlap(terms.get(fail.id)!, terms.get(peer.id)!) < 0.5) continue;
+      const fix = decisions.find(row => sharedPath(row, fail) && overlap(terms.get(row.id)!, terms.get(fail.id)!) >= 0.25);
+      if (fix) add("recurring-fix", [fail, peer, fix], "Repeated fail notes and a related decision on the same path; review whether the decision addresses the failures.");
+    }
+    return { clusters, truncated, engine: index.available ? "fts5" : "substring" };
+  } finally { index.close(); }
+}

package/src/memory/consolidation-model.ts

@@ -0,0 +1,97 @@
+import { types } from "node:util";
+import { candidateTargetRevision, type CandidateInput, type CandidateStore } from "./candidates.ts";
+import { memoryPolicySnapshot, type StandalonePolicy } from "./policy.ts";
+import { realPath } from "./platform.ts";
+import { recallViewIsLive } from "./recall.ts";
+import type { MemoryStore, View } from "./store.ts";
+
+export interface ModelConsolidationNote extends View { revision: string }
+export interface ModelConsolidationInput { project: string; notes: ModelConsolidationNote[] }
+export interface ModelConsolidationOptions {
+  enabled: true;
+  run: (input: ModelConsolidationInput, signal: AbortSignal) => Promise<{ text: string } | null>;
+}
+export interface ModelConsolidationGuard { project: string; actor: "person" | "agent"; check(): void; policy: StandalonePolicy }
+export interface ModelConsolidationReport {
+  state: "disabled" | "known" | "unknown"; ids: string[]; calls: number; nonAnswers: number; rejected: number; oversized: number;
+  limited: boolean; timedOut: boolean; truncated: boolean;
+}
+const TIMEOUT_MS = 10_000, MAX_INPUT_BYTES = 8192, MAX_OUTPUT_BYTES = 4096, PREFIX = "Model answer:\n";
+async function invoke(model: ModelConsolidationOptions, input: ModelConsolidationInput, before: () => void): Promise<{ state: "value"; value: unknown } | { state: "timeout" } | { state: "error" }> {
+  const controller = new AbortController(), deadline = performance.now() + TIMEOUT_MS; let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const timeout = new Promise<{ state: "timeout" }>(resolve => { timer = setTimeout(() => { controller.abort(); resolve({ state: "timeout" }); }, TIMEOUT_MS); });
+    const result = await Promise.race([Promise.resolve().then(() => { before(); return model.run(structuredClone(input), controller.signal); }).then(value => ({ state: "value" as const, value }), () => ({ state: "error" as const })), timeout]);
+    if (performance.now() >= deadline) { controller.abort(); return { state: "timeout" }; }
+    return result;
+  } finally { if (timer) clearTimeout(timer); }
+  // ponytail: an injected host callback must honor AbortSignal to stop its own work. The library cannot
+  // terminate arbitrary host work, but the expired race has no late candidate-writing continuation.
+}
+/** Already-screened public rows only; guard.check retains the caller's current policy/source binding.
+ * Optional injected callback only, never a built-in provider, automatic pass or curated writer. */
+export async function proposeModelConsolidations(store: MemoryStore, candidates: CandidateStore, rows: readonly View[], model: ModelConsolidationOptions | undefined, guard: ModelConsolidationGuard): Promise<ModelConsolidationReport> {
+  const report: ModelConsolidationReport = { state: model === undefined ? "disabled" : "known", ids: [], calls: 0, nonAnswers: 0, rejected: 0, oversized: 0, limited: false, timedOut: false, truncated: false };
+  if (model === undefined) return report;
+  if (guard.actor !== "person") throw Error("model consolidation requires person intent");
+  try {
+    if (!model || model.enabled !== true || typeof model.run !== "function" || !guard.project.trim() || guard.project.length > 400) throw Error("model consolidation unavailable");
+    guard.check();
+    if (realPath(candidates.dir) !== realPath(store.profile.home)) throw Error("model consolidation home mismatch");
+    if (types.isProxy(rows) || !Array.isArray(rows) || rows.length > 256) throw Error("model consolidation source bound exceeded");
+    const project = guard.project, sourceCurrent = store.beginRecallRead(), sources: ModelConsolidationNote[] = [], seen = new Set<string>();
+    const check = (batch: readonly ModelConsolidationNote[]) => {
+      guard.check(); sourceCurrent();
+      if (guard.actor !== "person" || guard.project !== project) throw Error("model consolidation context changed");
+      const placements = batch.length ? store.entryPlacements(batch.map(row => row.id), project) : new Map<string, "local" | "synced">();
+      store.withDeferredPromotions(() => {
+        for (const row of batch) {
+          const current = store.get(row.id, project);
+          if (!current || current.id !== row.id || current.project !== project || !recallViewIsLive(current, store.readNow()) || candidateTargetRevision(current) !== row.revision || placements.get(row.id) !== "synced") throw Error("model consolidation sources changed");
+        }
+      });
+      guard.check(); sourceCurrent();
+    };
+    for (let index = 0; index < rows.length; index++) {
+      const descriptor = Object.getOwnPropertyDescriptor(rows, String(index));
+      if (!descriptor || !("value" in descriptor)) throw Error("model consolidation source unavailable");
+      const row = memoryPolicySnapshot(descriptor.value as View);
+      if (!row || !/^[a-f0-9]{32}$/.test(row.id) || row.project !== project || !recallViewIsLive(row, store.readNow()) || row.peer === "amem-model" || row.text.startsWith("Model answer:")) throw Error("model consolidation source unavailable");
+      if (seen.has(row.id)) continue; seen.add(row.id); sources.push({ ...row, revision: candidateTargetRevision(row) });
+    }
+    check(sources);
+    const batches: ModelConsolidationNote[][] = []; let pending: ModelConsolidationNote[] = [];
+    for (const row of sources) {
+      if (Buffer.byteLength(JSON.stringify({ project, notes: [row] })) > MAX_INPUT_BYTES) { report.oversized++; report.truncated = true; continue; }
+      if (pending.length === 8 || Buffer.byteLength(JSON.stringify({ project, notes: [...pending, row] })) > MAX_INPUT_BYTES) { batches.push(pending); pending = []; }
+      pending.push(row);
+    }
+    if (pending.length) batches.push(pending);
+    report.truncated ||= batches.length > 2;
+    for (const batch of batches.slice(0, 2)) {
+      check(batch);
+      const input: ModelConsolidationInput = { project, notes: batch }, inputBytes = Buffer.byteLength(JSON.stringify(input));
+      // Exported callers must not be able to forward an unscreened row merely by claiming it was screened.
+      const inputPermitted = await guard.policy.screen(input); check(batch);
+      if (!inputPermitted) { report.rejected++; continue; }
+      if (!candidates.reserveConsolidationModel(inputBytes)) { report.limited = true; report.truncated = true; break; }
+      report.calls++;
+      const result = await invoke(model, input, () => check(batch)); check(batch);
+      if (result.state === "timeout") { report.state = "unknown"; report.timedOut = true; break; }
+      if (result.state === "error") { report.state = "unknown"; report.rejected++; break; }
+      const value = memoryPolicySnapshot(result.value);
+      if (value === null) { report.nonAnswers++; continue; }
+      if (!value || typeof value !== "object" || !("text" in value) || typeof value.text !== "string") { report.rejected++; continue; }
+      if (Buffer.byteLength(value.text) > MAX_OUTPUT_BYTES) { report.oversized++; continue; }
+      const body = value.text.trim(); if (!body) { report.nonAnswers++; continue; }
+      const text = PREFIX + body;
+      if (text.length > 3000) { report.oversized++; continue; }
+      const candidate: Extract<CandidateInput, { kind: "model-answer" }> = { project, kind: "model-answer", marker: "model-answer", targets: batch.map(row => ({ id: row.id, revision: row.revision })), text };
+      guard.check();
+      const permitted = await guard.policy.screen({ project, output: value, candidate }); check(batch);
+      if (!permitted) { report.rejected++; continue; }
+      report.ids.push(candidates.put(candidate, "public"));
+    }
+    return report;
+  } catch { report.state = "unknown"; report.rejected++; return report; }
+}

package/src/memory/cross-project.ts

@@ -0,0 +1,75 @@
+import { captureSearch } from "./search-fts.ts";
+import { readCaptureConfig, type CaptureRow } from "./capture.ts";
+import { walkShards } from "./catalog.ts";
+import { openCuratedForRead } from "./curated-read.ts";
+import { lifecycleResolver } from "./lifecycle.ts";
+import type { MemoryPolicy } from "./policy.ts";
+import type { SearchHit, View } from "./store.ts";
+import { vaultCandidates } from "./vault.ts";
+
+/**
+ * #15 T5 / D4 and D8: the two reads that deliberately cross project boundaries, each one project at a time.
+ *
+ * - `searchAllProjects` (`amem search --all-projects`): one ordinary project-scoped search per active project, merged by score. Every hit names its project and
+ *   the reply says `crossedProjects: true` with the projects it read, so a caller can never mistake it for a single-project answer. An archived project is
+ *   read only with `includeArchived`; a forgotten one never. It changes no content file of the home (only derived indexes and sidecars may refresh, as for any read).
+ * - `vaultCandidatesAll` (`amem vault-candidates --all-projects | --project <key>`): the existing durable-candidate selection (`vaultCandidates`), under the
+ *   caller's policy, run per project and grouped by project. amem lists; it never writes the vault or a vault link (D8).
+ *
+ * Both are person reads at the CLI: agents reach memory through MCP, which stays bound to one project and has no all-projects argument (D4).
+ */
+
+export interface CrossHit extends SearchHit { project: string }
+export interface CrossSearchResult { crossedProjects: true; projects: string[]; hits: CrossHit[]; engine: "fts5" | "substring" }
+
+function readableProjects(base: string, opts: { includeArchived?: boolean }): { key: string; machineDirs: string[] }[] {
+  const stateOf = lifecycleResolver(base);
+  return walkShards(base).filter(shard => { const state = stateOf(shard.key); return state === "active" || state === "archived" && opts.includeArchived === true; });
+}
+
+export function searchAllProjects(base: string, query: string, opts: { limit?: number; includeArchived?: boolean; includeCapture?: boolean; now?: () => number } = {}): CrossSearchResult {
+  const limit = opts.limit ?? 50;
+  if (!query.trim()) throw new Error("usage: amem search --all-projects <words>");
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 500) throw new Error("--limit takes a number from 1 to 500");
+  const now = (opts.now ?? Date.now)(), hits: CrossHit[] = [], projects: string[] = [];
+  let engine: "fts5" | "substring" = "fts5";
+  for (const shard of readableProjects(base, opts)) {
+    projects.push(shard.key);
+    const store = openCuratedForRead(base, shard.key);
+    try {
+      if (store) {
+        const found = store.search(query, { project: shard.key, includeCapture: false, limit });
+        if (found.engine === "substring") engine = "substring";
+        for (const hit of found.hits) if (hit.view && hit.view.project === shard.key) hits.push({ ...hit, project: shard.key });
+      }
+    } finally { store?.close(); }
+    if (opts.includeCapture !== false) {
+      for (const dir of shard.machineDirs) {
+        const days = readCaptureConfig(dir, base).retentionDays, cutoff = new Date(now - days * 24 * 3600_000);
+        for (const { row, rank } of captureSearch(dir, query, Math.max(limit * 4, 32), Number.isFinite(cutoff.getTime()) ? cutoff.toISOString() : undefined)) {
+          hits.push({ source: "capture", score: -rank * 0.5, capture: row as CaptureRow, project: shard.key });
+        }
+      }
+    }
+  }
+  const ref = (h: CrossHit): string => `${h.project}:${h.view?.id ?? String(h.capture?.id ?? 0).padStart(12, "0")}`;
+  hits.sort((a, b) => b.score - a.score || ref(a).localeCompare(ref(b)));
+  return { crossedProjects: true, projects: projects.sort(), hits: hits.slice(0, limit), engine };
+}
+
+export interface VaultCandidatesAll { crossedProjects: boolean; projects: { project: string; candidates: View[] }[] }
+
+export async function vaultCandidatesAll(base: string, opts: { policy: MemoryPolicy; project?: string; limit?: number; includeArchived?: boolean }): Promise<VaultCandidatesAll> {
+  const shards = readableProjects(base, opts).filter(shard => opts.project === undefined || shard.key === opts.project);
+  if (opts.project !== undefined && !shards.length) throw new Error(`no readable project shard for ${opts.project}`);
+  const projects: { project: string; candidates: View[] }[] = [];
+  for (const shard of shards.sort((a, b) => a.key.localeCompare(b.key))) {
+    const store = openCuratedForRead(base, shard.key);
+    if (!store) continue;
+    try {
+      const candidates = await vaultCandidates(store, { project: shard.key, policy: opts.policy, ...(opts.limit !== undefined ? { limit: opts.limit } : {}) });
+      if (candidates.length) projects.push({ project: shard.key, candidates });
+    } finally { store.close(); }
+  }
+  return { crossedProjects: opts.project === undefined, projects };
+}

package/src/memory/curated-read.ts

@@ -0,0 +1,29 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { MemoryStore, machineId, openShardStore } from "./store.ts";
+import { aliasedKeys, readShardedSelection, resolveAlias, shardDir, shardKeyHash, readShardDescriptor } from "./shard.ts";
+
+/**
+ * Opens the curated store that holds one project's notes, without initializing anything (#15 T5 reads, never creates):
+ * an unsplit home has one shared store (the project filter selects), a split home has one shard per project. A split home's
+ * capture-only shard (no `generation.json` yet) has no curated store, and the answer is `undefined`, never an empty one made on the spot.
+ */
+export function openCuratedForRead(base: string, key: string): MemoryStore | undefined {
+  const aliases = aliasedKeys(base, key), reconcile = aliases.length ? { canonical: key, aliases } : undefined;
+  if (existsSync(join(base, "shards.json"))) {
+    readShardedSelection(base);
+    if (!existsSync(join(shardDir(base, key), "generation.json"))) return undefined;
+    return openShardStore({ memoryDir: base, project: key, deferPromotions: true, lifecycle: "ignore", ...(reconcile ? { reconcile } : {}) });
+  }
+  if (!existsSync(join(base, "log")) && !existsSync(join(base, "local")) && !existsSync(join(base, "generations"))) return undefined;
+  return new MemoryStore({ memoryDir: base, deferPromotions: true, ...(reconcile ? { reconcile } : {}) });
+}
+
+/** The canonical key of `key`, refused unless a shard of it exists. */
+export function requireShard(base: string, key: string): string {
+  const canonical = resolveAlias(base, key.trim());
+  if (!canonical || !readShardDescriptor(base, shardKeyHash(canonical))) throw new Error(`no project shard for ${canonical || key}`);
+  return canonical;
+}
+
+export const thisMachine = (base: string): string => machineId(base).id;

package/src/memory/decay-review.ts

@@ -0,0 +1,136 @@
+import { Database } from "bun:sqlite";
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+import { hashJSON } from "./generation.ts";
+import { candidateTargetRevision, type CandidateTarget, type Counter } from "./candidates.ts";
+import { MemoryStore, type View } from "./store.ts";
+
+export const DECAY_DEFAULT_DAYS = 90, DECAY_PREVIEW_LIMIT = 64, DECAY_SCAN_LIMIT = 5000;
+export interface DecayEntry { target: CandidateTarget; view: View }
+export interface DecayPlan {
+  project: string; profile: string; days: number; at: string; cutoff: string; demoteExpiresAt: string;
+  entries: DecayEntry[]; withheld: number; citedExemptions: number | null; truncated: boolean;
+  /** Missing/zero observations do not prove the note was never cited. */
+  citationHistory: "unknown";
+}
+export interface DecayOptions {
+  now?: () => number; days?: number; ids?: readonly string[]; aliases?: readonly string[]; counters?: () => readonly Counter[] | undefined;
+  screen?: (view: View) => boolean; assertCurrent?: () => void;
+}
+function idsOf(ids: readonly string[]): string[] {
+  const normalized = ids.map(id => id.replace(/^mem:/, ""));
+  if (normalized.length > DECAY_PREVIEW_LIMIT || new Set(normalized).size !== normalized.length || normalized.some(id => !/^[a-f0-9]{32}$/.test(id))) throw Error("name up to 64 distinct exact entry ids");
+  return normalized;
+}
+/** Advisory telemetry without opening/pruning the candidate writer. Unavailable is unknown, never zero. */
+export function readDecayCounters(base: string, projects: readonly string[]): Counter[] | undefined {
+  const file = join(base, "candidates.db");
+  let db: Database | undefined;
+  try {
+    const stat = lstatSync(file, { throwIfNoEntry: false });
+    if (!stat || !stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) return undefined;
+    db = new Database(file, { readonly: true }); db.run("PRAGMA busy_timeout = 0");
+    const rows = db.query("SELECT id,payload,at,rendered,delivered,cited FROM counters WHERE project IN (SELECT value FROM json_each(?)) AND cited > 0 ORDER BY at DESC").all(JSON.stringify(projects)) as { id: string; payload: string; at: number; rendered: number | null; delivered: number | null; cited: number | null }[];
+    return rows.map(row => ({ id: row.id, key: JSON.parse(row.payload), createdAt: new Date(row.at).toISOString(), rendered: row.rendered, delivered: row.delivered, cited: row.cited }));
+  } catch { return undefined; }
+  finally { try { db?.close(); } catch { /* An unavailable telemetry close cannot authorize a mutation. */ } }
+}
+function citedIds(project: string, aliases: readonly string[], counters: readonly Counter[] | undefined): Set<string> {
+  const ids = new Set<string>();
+  for (const row of counters ?? []) {
+    if (!row?.key || ![project, ...aliases].includes(row.key.project) || !Number.isSafeInteger(row.cited) || !(row.cited! > 0)) continue;
+    // Counter timestamps describe delivery, not a later citation update. Any retained positive exempts.
+    ids.add(row.key.entryId);
+  }
+  return ids;
+}
+/** Age/goal selection is independent of telemetry; retained positive citations may only exempt entries. */
+export function decayPreview(store: MemoryStore, project: string, options: DecayOptions = {}): DecayPlan {
+  options.assertCurrent?.();
+  if (!project.trim() || store.profile.sharded && !store.profile.shardUser && store.profile.shardKey !== project) throw Error("decay project does not match the bound store");
+  const now = (options.now ?? Date.now)(), days = options.days ?? DECAY_DEFAULT_DAYS, cutoff = now - days * 86400_000;
+  if (!Number.isSafeInteger(days) || days < 1 || !Number.isFinite(now) || !Number.isFinite(cutoff) || Math.abs(cutoff) > 8_640_000_000_000_000) throw Error("decay days are outside the supported range");
+  const requested = options.ids === undefined ? undefined : idsOf(options.ids);
+  return store.withDeferredPromotions(() => {
+    const goals = store.goals(project).filter(goal => ["open", "active", "blocked"].includes(goal.state));
+    const tasks = new Set(goals.flatMap(goal => goal.links.map(link => link.task))), goalNodes = new Set(goals.map(goal => `goal:${goal.id}`));
+    let counters: readonly Counter[] | undefined;
+    try { counters = options.counters?.(); } catch { /* Telemetry is advisory; an unreadable snapshot is unknown. */ }
+    const cited = citedIds(project, options.aliases ?? [], counters);
+    // ponytail: list materializes the existing core corpus before slicing; a scoped pager is the upgrade for large homes.
+    const rows = requested ? requested.map(id => store.get(id, project)) : store.list({ project, tier: "long", limit: DECAY_SCAN_LIMIT + 1 });
+    if (rows.length > DECAY_SCAN_LIMIT) throw Error("decay preview scan bound exceeded; name exact ids to narrow it");
+    const entries: DecayEntry[] = []; let withheld = 0, citedExemptions = 0;
+    for (let index = 0; index < rows.length; index++) {
+      const view = rows[index];
+      const eligible = view && (!requested || view.id === requested[index]) && view.project === project && view.tier === "long" && !view.supersededBy && Number.isFinite(Date.parse(view.at)) && Date.parse(view.at) < cutoff
+        && !(view.task && tasks.has(view.task)) && !view.about.some(node => goalNodes.has(node) || node.startsWith("task:") && tasks.has(node.slice(5)));
+      if (!eligible) { if (requested) throw Error("requested entry is not eligible for decay"); continue; }
+      if (cited.has(view.id)) { citedExemptions++; if (requested) throw Error("requested entry has a retained recorded citation"); continue; }
+      if (options.screen && !options.screen(structuredClone(view))) { withheld++; if (requested) throw Error("requested entry is withheld by current policy"); continue; }
+      entries.push({ target: { id: view.id, revision: candidateTargetRevision(view) }, view: structuredClone(view) });
+    }
+    options.assertCurrent?.();
+    return { project, profile: hashJSON(store.profile), days, at: new Date(now).toISOString(), cutoff: new Date(cutoff).toISOString(), demoteExpiresAt: store.shortExpiry(), entries: entries.slice(0, DECAY_PREVIEW_LIMIT), withheld, citedExemptions: counters === undefined ? null : citedExemptions, truncated: entries.length > DECAY_PREVIEW_LIMIT, citationHistory: "unknown" };
+  });
+}
+/** Duplicate-group forgetting requires a separate person group review, never an implicit decay expansion. */
+export function assertExactDecayForget(store: MemoryStore, ids: readonly string[], project: string): void {
+  store.withDeferredPromotions(() => {
+    for (const id of ids) {
+      const targets = store.forgetTargets(id, project);
+      if (targets.length !== 1 || targets[0]?.id !== id) throw Error("decay forget expands beyond reviewed exact entries; review the imported copy group separately");
+    }
+  });
+}
+
+export interface DecayApplyOptions extends Omit<DecayOptions, "days"> {
+  actor: "person" | "agent"; confirmed?: boolean; forget?: boolean;
+}
+export interface DecayApplyReport { action: "demote" | "forget"; applied: string[]; failed: string; remaining: string[]; expiresAt?: string }
+export class DecayApplyError extends Error {
+  jsonOutput = false;
+  readonly failedMayHaveChanged = true;
+  constructor(readonly report: DecayApplyReport, cause: unknown) {
+    super("decay apply stopped; the failed target may have changed, inspect before retrying", { cause }); this.name = "DecayApplyError";
+  }
+  get applied(): readonly string[] { return this.report.applied; }
+  get failed(): string { return this.report.failed; }
+  get remaining(): readonly string[] { return this.report.remaining; }
+  render(): string {
+    if (this.jsonOutput) return JSON.stringify({ ok: false, ...this.report, failedMayHaveChanged: this.failedMayHaveChanged });
+    return `${this.message}; applied: ${this.report.applied.join(", ") || "none"}; failed: ${this.report.failed}; remaining: ${this.report.remaining.join(", ") || "none"}${this.report.expiresAt ? `; completed demotions expire: ${this.report.expiresAt}` : ""}`;
+  }
+}
+/** The host shows this exact plan; every selected revision/eligibility is rechecked before any append. */
+export function applyDecay(store: MemoryStore, plan: DecayPlan, options: DecayApplyOptions): { action: "demote" | "forget"; ids: string[]; expiresAt?: string } {
+  if (options.actor !== "person") throw Error("decay apply requires person authority");
+  options.assertCurrent?.();
+  const ids = options.ids === undefined ? plan.entries.map(entry => entry.target.id) : idsOf(options.ids);
+  if ((options.ids === undefined || options.forget) && options.confirmed !== true) throw Error("decay bulk/forget apply requires explicit person confirmation");
+  if (hashJSON(store.profile) !== plan.profile || ids.some(id => !plan.entries.some(entry => entry.target.id === id))) throw Error("decay preview binding changed or target was not previewed");
+  const action = options.forget ? "forget" : "demote";
+  if (!ids.length) return { action, ids };
+  if (!options.forget && (!Number.isFinite(Date.parse(plan.demoteExpiresAt)) || new Date(plan.demoteExpiresAt).toISOString() !== plan.demoteExpiresAt || Date.parse(plan.demoteExpiresAt) <= (options.now ?? Date.now)())) throw Error("decay demotion expiry is spent; preview again");
+  if (!options.forget) store.assertDemotionExpiry(plan.demoteExpiresAt);
+  return store.withCurrentEntries(ids, plan.project, current => {
+    const fresh = decayPreview(store, plan.project, { ...options, days: plan.days, ids });
+    for (const view of current) {
+      const expected = plan.entries.find(entry => entry.target.id === view.id)?.target.revision;
+      if (!expected || candidateTargetRevision(view) !== expected || !fresh.entries.some(entry => entry.target.id === view.id && entry.target.revision === expected)) throw Error("decay target changed since preview");
+    }
+    if (options.forget) assertExactDecayForget(store, ids, plan.project);
+    options.assertCurrent?.();
+    // All checks precede effects. The failed target may itself have appended before an I/O error.
+    const applied: string[] = [], expiry = options.forget ? {} : { expiresAt: plan.demoteExpiresAt };
+    for (let index = 0; index < ids.length; index++) {
+      const id = ids[index]!;
+      try {
+        const result = options.forget ? store.forget(id, "person", plan.project, true) : store.demote(id, "person", plan.project, plan.demoteExpiresAt);
+        if (!result) throw Error("decay target outcome unavailable");
+        applied.push(id);
+      } catch (error) { throw new DecayApplyError({ action, applied: [...applied], failed: id, remaining: ids.slice(index + 1), ...expiry }, error); }
+    }
+    return { action, ids, ...expiry };
+  });
+}