@staix/agent-mem 0.6.0 → 0.7.0

package/src/memory/config.ts

@@ -0,0 +1,167 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createStandalonePolicy, type StandalonePolicy, type StandalonePolicyOptions } from "./policy.ts";
+
+/**
+ * F4 (agent-mem#40): standalone policy configuration, with no host. Two files, both plain JSON:
+ *
+ * - the machine-local `amem.config.json` in the memory home: the person's own policy (deny paths, PII patterns, the SessionStart brief byte
+ *   budget, the capture excerpt and path caps, the capture size cap and retention, and where the home lives);
+ * - an optional `<repository>/.amem/config`: a repository may only NARROW. It adds deny paths and PII patterns and may lower a byte or count
+ *   budget; it can never remove a machine entry, raise a budget, or move the home. A stricter host policy passed through the library wins over both.
+ *
+ * Either file that exists but is not a bounded plain JSON object of known keys is an error that names it, never a silent default: an unreadable
+ * policy must not read as "no policy". Reading is synchronous and does no model, network or storage work.
+ */
+export const CONFIG_FILE = "amem.config.json";
+export const REPO_CONFIG_DIR = ".amem";
+export const REPO_CONFIG_FILE = "config";
+const MAX_CONFIG_BYTES = 64 * 1024;
+const MACHINE_KEYS = ["home", "denyPaths", "piiPatterns", "briefBytes", "excerptBytes", "capturePaths", "capture"] as const;
+const REPO_KEYS = ["denyPaths", "piiPatterns", "briefBytes", "excerptBytes", "capturePaths"] as const;
+
+export interface AmemConfig {
+  /** The memory home, when the file moves it (a pointer file: see `configuredHome`). `AMEM_HOME` still wins. Machine file only. */
+  home?: string;
+  denyPaths: string[];
+  piiPatterns: string[];
+  /** SessionStart brief byte budget; the built-in hook cap is the ceiling. */
+  briefBytes?: number;
+  /** Capture excerpt cap in bytes-as-characters; the built-in cap is the ceiling. */
+  excerptBytes?: number;
+  /** Capture path-count cap; the built-in cap is the ceiling. */
+  capturePaths?: number;
+  /** The capture tier's own R6 bounds. Machine file only (a repository cannot widen the machine's disk use). */
+  capture: { capMb?: number; retentionDays?: number };
+}
+export interface ConfigSource { machine: string | null; repo: string | null }
+export interface LoadedConfig { config: AmemConfig; source: ConfigSource }
+
+const fail = (file: string, why: string): never => { throw new Error(`${file}: ${why}; fix or remove it (an unreadable policy is never treated as no policy)`); };
+
+/** One bounded read through one descriptor: a link, a non-file or a growing file refuses, and a missing file is `undefined`. */
+function readPlain(path: string, label: string): unknown | undefined {
+  let fd: number;
+  try { fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+  catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") return undefined;
+    return fail(label, code === "ELOOP" ? "is a symbolic link" : "cannot be read");
+  }
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > MAX_CONFIG_BYTES) return fail(label, `is not a plain file within ${MAX_CONFIG_BYTES} bytes`);
+    const text = readFileSync(fd, "utf8");
+    if (Buffer.byteLength(text) > MAX_CONFIG_BYTES) return fail(label, `is not a plain file within ${MAX_CONFIG_BYTES} bytes`);
+    try { return JSON.parse(text) as unknown; } catch { return fail(label, "does not parse as JSON"); }
+  } finally { closeSync(fd); }
+}
+
+function listOf(value: unknown, key: string, label: string): string[] {
+  if (value === undefined) return [];
+  // The standalone policy takes at most 64 literals of 256 bytes without control characters: say so here, by name.
+  if (!Array.isArray(value) || value.length > 64 || !value.every(item => typeof item === "string" && item.trim() !== "" && Buffer.byteLength(item) <= 256 && !/[\x00-\x1f\x7f]/.test(item)))
+    return fail(label, `${key} is not a list of at most 64 non-empty strings of at most 256 bytes without control characters`);
+  return [...new Set(value as string[])];
+}
+function countOf(value: unknown, key: string, label: string, max: number): number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 || value > max) return fail(label, `${key} is not a whole number from 1 to ${max}`);
+  return value;
+}
+
+function parseFile(raw: unknown, label: string, keys: readonly string[]): Partial<AmemConfig> & { capture?: AmemConfig["capture"] } {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return fail(label, "is not a JSON object");
+  const body = raw as Record<string, unknown>;
+  for (const key of Object.keys(body)) if (!keys.includes(key)) fail(label, `unknown key "${key}" (known: ${keys.join(", ")})`);
+  const out: Partial<AmemConfig> & { capture?: AmemConfig["capture"] } = {
+    denyPaths: listOf(body.denyPaths, "denyPaths", label), piiPatterns: listOf(body.piiPatterns, "piiPatterns", label),
+  };
+  const briefBytes = countOf(body.briefBytes, "briefBytes", label, 1_000_000); if (briefBytes !== undefined) out.briefBytes = briefBytes;
+  const excerptBytes = countOf(body.excerptBytes, "excerptBytes", label, 100_000); if (excerptBytes !== undefined) out.excerptBytes = excerptBytes;
+  const capturePaths = countOf(body.capturePaths, "capturePaths", label, 1000); if (capturePaths !== undefined) out.capturePaths = capturePaths;
+  if (body.home !== undefined) {
+    if (typeof body.home !== "string" || !body.home.trim() || body.home.includes("\0") || !body.home.startsWith("/")) return fail(label, "home is not an absolute path");
+    // A file that moves the home is a pointer: the policy is read from the file IN the home it names, so any policy key beside `home` here would be silently lost.
+    const beside = Object.keys(body).filter(key => key !== "home");
+    if (beside.length) return fail(label, `names a home, so it is only a pointer; put ${beside.join(", ")} in ${join(body.home, CONFIG_FILE)}`);
+    out.home = body.home;
+  }
+  if (body.capture !== undefined) {
+    const capture = body.capture;
+    if (!capture || typeof capture !== "object" || Array.isArray(capture) || Object.keys(capture).some(key => !["capMb", "retentionDays"].includes(key))) return fail(label, "capture takes only capMb and retentionDays");
+    const c = capture as Record<string, unknown>;
+    out.capture = {};
+    const capMb = countOf(c.capMb, "capture.capMb", label, 1_048_576), retentionDays = countOf(c.retentionDays, "capture.retentionDays", label, 36_500);
+    if (capMb !== undefined) out.capture.capMb = capMb;
+    if (retentionDays !== undefined) out.capture.retentionDays = retentionDays;
+  }
+  return out;
+}
+
+/** The machine file's `home` before any store exists: the one key read ahead of the home itself. `AMEM_HOME` and the config's `home` name different homes only when the person sets both, and `AMEM_HOME` wins. */
+export function machineConfigPath(base: string): string { return join(base, CONFIG_FILE); }
+export function repoConfigPath(root: string): string { return join(root, REPO_CONFIG_DIR, REPO_CONFIG_FILE); }
+
+/**
+ * The nearest ancestor of `cwd` that holds a `.git` entry, by `lstat` alone: no `git` process, so a hook inside its 150 ms budget can call it.
+ * Bounded to 32 levels. Its `.amem/config` (if any) is the repository's narrowing file.
+ */
+export function repoConfigRoot(cwd: string): string | undefined {
+  try {
+    for (let dir = cwd, depth = 0; depth < 32; dir = dirname(dir), depth++) {
+      if (lstatSync(join(dir, ".git"), { throwIfNoEntry: false })) return dir;
+      if (dir === dirname(dir)) return undefined;
+    }
+  } catch { /* unreadable: no repository file */ }
+  return undefined;
+}
+
+/**
+ * The home the machine configuration redirects to, read from the DEFAULT home's `amem.config.json` only (one level: a redirected home's own file
+ * cannot redirect again, so there is no chain and no loop). Undefined when there is no file or it names no `home`. A malformed file throws.
+ * That file is a pointer: it carries `home` and nothing else, and the policy lives in the file inside the home it names.
+ */
+export function configuredHome(defaultHome: string): string | undefined {
+  const file = machineConfigPath(defaultHome), raw = readPlain(file, file);
+  return raw === undefined ? undefined : parseFile(raw, file, MACHINE_KEYS).home;
+}
+
+const lower = (machine: number | undefined, repo: number | undefined) => machine === undefined ? repo : repo === undefined ? machine : Math.min(machine, repo);
+
+/**
+ * The effective configuration. The repository file can only narrow: its lists are added to the machine's, and a number counts only when it is
+ * lower than the machine's (or the machine has none). It never carries `home` or `capture` (unknown key: an error), so it cannot move the
+ * store or widen the disk bounds.
+ */
+export function loadAmemConfig(base: string, repoRoot?: string): LoadedConfig {
+  const machinePath = machineConfigPath(base);
+  const machineRaw = readPlain(machinePath, machinePath);
+  const machine = machineRaw === undefined ? undefined : parseFile(machineRaw, machinePath, MACHINE_KEYS);
+  let repo: ReturnType<typeof parseFile> | undefined, repoPath: string | null = null;
+  if (repoRoot !== undefined) {
+    const file = repoConfigPath(repoRoot), raw = readPlain(file, file);
+    if (raw !== undefined) { repo = parseFile(raw, file, REPO_KEYS); repoPath = file; }
+  }
+  const union = (a: string[] | undefined, b: string[] | undefined) => [...new Set([...(a ?? []), ...(b ?? [])])];
+  const denyPaths = union(machine?.denyPaths, repo?.denyPaths), piiPatterns = union(machine?.piiPatterns, repo?.piiPatterns);
+  if (denyPaths.length > 64) fail(machinePath, "denyPaths and the repository's denyPaths name more than 64 entries together");
+  if (piiPatterns.length > 64) fail(machinePath, "piiPatterns and the repository's piiPatterns name more than 64 entries together");
+  const config: AmemConfig = { denyPaths, piiPatterns, capture: { ...(machine?.capture ?? {}) } };
+  if (machine?.home !== undefined) config.home = machine.home;
+  for (const key of ["briefBytes", "excerptBytes", "capturePaths"] as const) { const value = lower(machine?.[key], repo?.[key]); if (value !== undefined) config[key] = value; }
+  return { config, source: { machine: machineRaw === undefined ? null : machinePath, repo: repoPath } };
+}
+
+/**
+ * The standalone policy as configured. A host policy passed through the library still wins: it is composed in, never replaced, so the result
+ * declines whatever either declines (`createStandalonePolicy` screens the config, then asks the host).
+ */
+export function configuredPolicyOptions(base: string, cwd?: string, options: StandalonePolicyOptions = {}): StandalonePolicyOptions {
+  const { config } = loadAmemConfig(base, cwd === undefined ? undefined : repoConfigRoot(cwd));
+  const merge = (a: readonly string[] | undefined, b: readonly string[]) => [...new Set([...(a ?? []), ...b])];
+  return { ...options, denyPaths: merge(options.denyPaths, config.denyPaths), piiPatterns: merge(options.piiPatterns, config.piiPatterns) };
+}
+export function configuredPolicy(base: string, cwd?: string, options: StandalonePolicyOptions = {}): StandalonePolicy {
+  return createStandalonePolicy(configuredPolicyOptions(base, cwd, options));
+}

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 };
+  });
+}