@staix/agent-mem 0.5.0 → 0.7.0

package/src/memory/store.ts

@@ -1,18 +1,22 @@
 import { Database } from "bun:sqlite";
-import { createHash, randomBytes } from "node:crypto";
-import { appendFileSync, chmodSync, closeSync, constants, existsSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { appendFileSync, chmodSync, closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, normalize } from "node:path";
-import { isDenied } from "./platform.ts";
+import { isDenied, realPath } from "./platform.ts";
+import { stripPrivateDeep, stripPrivateSpans } from "./private-spans.ts";
 import { looksSecret } from "./screen.ts";
 import { mutationDatabase } from "./mutation.ts";
 import { memoryHome } from "./home.ts";
+import { machineId, type Machine } from "./machine.ts";
+import { assertProjectActive } from "./lifecycle.ts";
+export { machineId, type Machine } from "./machine.ts";
 import { readWindowSql, readRef, type ReadWindow, type ReadRef, SearchIndex, captureSearch } from "./search-fts.ts";
-import { assertCuratedShardPaths, ensureShardDescriptor, readShardDescriptor, readShardedSelection, resolveAlias, resolveShardProfile, shardDir, shardKeyHash, shardMachineDir, userShardDir } from "./shard.ts";
+import { assertCuratedShardPaths, ensureShardDescriptor, readShardDescriptor, readShardedSelection, aliasedKeys, resolveAlias, resolveShardProfile, shardDir, shardKeyHash, shardMachineDir, userShardDir } from "./shard.ts";
 import { readCaptureConfig, type CaptureRow } from "./capture.ts";
 import { assertSharedV1Op } from "./ops-contract.ts";
-import { generationDescriptor, generationDir, fsyncDirectory, canonicalJSON, hashJSON, readProfileJSON, resolveProfile, writeProfileJSON, type BoundProfile, type ProfileInput, validateVaultLinkRow, vaultLinkId, type VaultLink, type VaultLinkRow } from "./generation.ts";
+import { generationDescriptor, generationDir, fsyncDirectory, canonicalJSON, hashJSON, readProfileJSON, resolveProfile, writeProfileJSON, readSelector, type BoundProfile, type ProfileInput, validateVaultLinkRow, vaultLinkId, type VaultLink, type VaultLinkRow } from "./generation.ts";
 import { GenerationIndex, explicitExpirySnapshot, GENERATION_TABLES } from "./generation-index.ts";
-import { legacyEntries, type LegacyCheckpoint } from "./bridge.ts";
+import { legacyEntries, readLegacySnapshot, SegmentReader, type LegacyCheckpoint } from "./bridge.ts";
 import { readMigrationSources } from "./migrate.ts";
 import type { PruneStorePort } from "./prune.ts";
 import { isDeepStrictEqual } from "node:util";
@@ -124,33 +128,6 @@ const oneLine = (text: string): string => text.replace(/\s+/g, " ").trim().slice
 /** A board task's key in hub memory: unique across `ahub reset --all`, which restarts the ids. */
 export const taskKey = (project: string, task: { id: number; created: number }): string => `${project}#${task.id}@${task.created}`;
 
-export interface Machine { id: string; label: string }
-/** Random per `~/.agenthub`, with a person-given label; created on first use. */
-export function machineId(dir: string): Machine {
-  const file = join(dir, "machine.json");
-  const read = (): Machine | undefined => {
-    try {
-      const m = JSON.parse(readFileSync(file, "utf8")) as Machine;
-      if (/^[0-9a-f]{16}$/.test(m?.id)) return { id: m.id, label: typeof m.label === "string" ? m.label : m.id };
-    } catch { /* none, or unreadable */ }
-    return undefined;
-  };
-  const found = read();
-  if (found) return found;
-  // Hubs of several projects can start at once on a fresh home: each writes its own temp file and links it into place,
-  // which fails if another got there first; then everyone reads the one identity that won.
-  const id = randomBytes(8).toString("hex");
-  mkdirSync(dir, { recursive: true, mode: 0o700 });
-  const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
-  writeFileSync(tmp, JSON.stringify({ id, label: id }) + "\n", { mode: 0o600 });
-  try { linkSync(tmp, file); } catch { /* another process created it: its identity wins */ } finally { rmSync(tmp, { force: true }); }
-  // A file that is there but holds no valid id is never overwritten (another process may be reading it): the store
-  // fails to open, so the hub says hub memory is unavailable instead of filing notes under no machine.
-  const won = read();
-  if (!won) throw new Error(`${file} holds no valid machine id; remove it and a new one is made`);
-  return won;
-}
-
 /** A person's name for this machine, shown beside its id. */
 export function setMachineLabel(dir: string, label: string): Machine {
   const m = machineId(dir);
@@ -167,6 +144,20 @@ export interface View {
   local: boolean;
 }
 export interface VaultEntry { view: View; /** Full authored hash in generation profiles; empty for read-only shared-v1. */ rowHash: string }
+export interface RecallStateOptions { person?: boolean; asOf?: string; history?: boolean; maxRows?: number; maxBytes?: number }
+export interface RecallRelation { from: string; to: string; at: string; kind: "supersede" | "promote" }
+export interface RetainedRecallState {
+  at: string; views: View[]; forgotten: { id: string; at: string }[]; relations: RecallRelation[];
+  malformed: number; incomplete: boolean; notices: string[];
+  /** Present only when retained source diagnostics independently make the result incomplete. */
+  sourceIncomplete?: true;
+}
+interface RecallViewProjection {
+  now: number; rows: Record<string, string | null>[];
+  ops: { id: string; op: string; at: string; target: string; by: string | null }[];
+  realms?: Map<string, { id: string; own: number; legacy: number }>;
+  pruned: Set<string>; forgotten: Set<string>; includePromoted: boolean;
+}
 export interface GoalView {
   id: string; at: string; machine: string; project: string; scope: Scope; title: string; milestones: string[]; dependsOn: string[];
   state: GoalState; links: { task: string; at: string; machine: string }[];
@@ -194,6 +185,8 @@ export type PromotionScreen = (v: View) => "promote" | "keep" | "skip";
  * went) wait for a process that has one; a person's explicit promote goes through.
  */
 export interface StoreOptions { home?: string; memoryDir?: string; ttlMs?: number; now?: () => number; log?: (line: string) => void; screen?: PromotionScreen; deferPromotions?: boolean; profile?: ProfileInput;
+  /** #15 T5: `openShardStore` refuses a project the person archived or forgot unless the caller says `ignore` (the catalog, `--include-archived` reads and export do, on purpose). */
+  lifecycle?: "enforce" | "ignore";
   /** #27: read the `aliases` keys' curated rows as part of the `canonical` project (CLI and MCP only); the library default reads the raw key. Rows are presented under `canonical`. */
   reconcile?: { canonical: string; aliases: readonly string[] };
 }
@@ -292,6 +285,11 @@ export class MemoryStore {
     return this.generationIndex.port(this.machine.id);
   }
 
+  /** Borrowed sync targets: the opened canonical shard plus its user overlay, never person-local aliases. Do not close these handles. */
+  openedSyncTargets(): readonly MemoryStore[] {
+    return [this, ...(this.userOverlay ? [this.userOverlay] : [])];
+  }
+
   /** Read-only project views, bounded before bodies or hashes; never promotes or authors a prune. */
   vaultEntries(project: string): VaultEntry[] {
     if (!project.trim() || this.profile.sharded && !this.profile.shardUser && this.profile.shardKey !== project) throw new Error("vault project does not match the bound store");
@@ -361,15 +359,38 @@ export class MemoryStore {
 
   /** A synchronous host-authorized mutation whose reads must not implicitly promote unrelated notes. */
   withDeferredPromotions<T>(work: () => T): T {
-    const previous = this.promoting;
-    this.promoting = true;
-    try { return work(); } finally { this.promoting = previous; }
+    const previous = this.readStores().map(store => [store, store.promoting] as const);
+    for (const [store] of previous) store.promoting = true;
+    try { return work(); } finally { for (const [store, promoting] of previous) store.promoting = promoting; }
   }
 
   private withMutation<T>(work: () => T): T {
     return this.mutationDb.transaction(work).immediate();
   }
 
+  /** Synchronous exact-target work under every opened shard's existing writer fence. No read-time promotions. */
+  withCurrentEntries<T>(ids: readonly string[], project: string, work: (entries: readonly View[]) => T): T {
+    if (!ids.length || ids.length > MAX_TARGETS || new Set(ids).size !== ids.length || ids.some(id => !/^[a-f0-9]{32}$/.test(id)) || !project.trim()) throw new Error("invalid exact-entry batch");
+    return this.withStoreFences(stores => {
+      assertProjectActive(this.profile.home, project);
+      for (const store of stores) store.ensureFresh();
+      const entries = ids.map(id => {
+        const view = this.get(id, project);
+        if (!view || view.id !== id || view.supersededBy) throw new Error("exact entry changed or unavailable");
+        return view;
+      });
+      return work(entries);
+    });
+  }
+  private withStoreFences<T>(work: (stores: readonly MemoryStore[]) => T): T {
+    const unique = new Map<string, MemoryStore>();
+    for (const store of this.readStores()) { const dir = realPath(store.dir); if (!unique.has(dir)) unique.set(dir, store); }
+    const stores = [...unique.keys()].sort().map(dir => unique.get(dir)!);
+    const lock = (index: number): T => index === stores.length ? work(stores) : stores[index]!.withMutation(() => lock(index + 1));
+    // Older/raw writers that bypass mutation-lock.db retain the existing mutation.ts ceiling.
+    return this.withDeferredPromotions(() => lock(0));
+  }
+
   /** Serialize current-store writers, screen one normalized body, and expose a one-shot append of that body. */
   withAcceptedNote<T>(note: NoteInput, work: (append: () => string) => T): T {
     if (this.userOverlay && note.scope === "shared") return this.userOverlay.withAcceptedNote(note, work);
@@ -377,8 +398,8 @@ export class MemoryStore {
       // Ordinary writes may defer indexing, but accepting an exact target revision must have a current index.
       this.db.transaction(() => this.refresh()).immediate();
       const at = new Date(this.now()).toISOString();
-      const normalized = structuredClone({ ...note, text: note.text.slice(0, MAX_TEXT),
-        ...(note.title ? { title: note.title.slice(0, MAX_TITLE) } : {}),
+      const normalized = structuredClone({ ...note, text: stripPrivateSpans(note.text).slice(0, MAX_TEXT),
+        ...(note.title ? { title: stripPrivateSpans(note.title).slice(0, MAX_TITLE) } : {}),
         ...(note.tier === "short" && !note.expires ? { expires: new Date(Date.parse(at) + this.ttl).toISOString() } : {}) });
       const body = { schema: MEMORY_SCHEMA, at, machine: this.machine.id, ...normalized } as const;
       const view: View = { ...normalized, id: entryId(body), at, machine: body.machine, title: normalized.title ?? null,
@@ -404,7 +425,9 @@ export class MemoryStore {
 
   /** Append one entry to this machine's long-term (synced) or local segment and index it. Returns its id. */
   private append(entry: NoteInput | OpInput | GoalInput, local: boolean, at = new Date(this.now()).toISOString(), machine = this.machine.id): string {
-    const capped = entry.op === "note" ? { ...entry, text: entry.text.slice(0, MAX_TEXT), ...(entry.title ? { title: entry.title.slice(0, MAX_TITLE) } : {}) } : entry;
+    // `<private>` spans are never stored, whoever writes (note, goal, promotion): dropped before the cap, the hash and the log line.
+    const capped = entry.op === "note" ? { ...entry, text: stripPrivateSpans(entry.text).slice(0, MAX_TEXT), ...(entry.title ? { title: stripPrivateSpans(entry.title).slice(0, MAX_TITLE) } : {}) }
+      : entry.op === "goal" ? stripPrivateDeep(entry) : entry;
     const body = { schema: MEMORY_SCHEMA, at, machine, ...capped } as Omit<Entry, "id">;
     return this.appendBody(body, local);
   }
@@ -444,12 +467,12 @@ export class MemoryStore {
     if (this.profile.sharded && (this.profile.shardUser ? n.scope !== "shared" : n.scope !== "project" || n.project !== this.profile.shardKey)) throw new Error("entry does not belong to this curated shard");
     assertSharedV1Op(n.op);
     // A fixed machine: the same observation imported on two machines is one entry once they sync.
-    const body = { schema: MEMORY_SCHEMA, at, machine: "claude-mem", ...n, text: n.text.slice(0, MAX_TEXT), ...(n.title ? { title: n.title.slice(0, MAX_TITLE) } : {}) } as Omit<Entry, "id">;
+    const body = { schema: MEMORY_SCHEMA, at, machine: "claude-mem", ...n, text: stripPrivateSpans(n.text).slice(0, MAX_TEXT), ...(n.title ? { title: stripPrivateSpans(n.title).slice(0, MAX_TITLE) } : {}) } as Omit<Entry, "id">;
     const id = entryId(body);
     return this.withMutation(() => {
       this.generationIndex?.assertAppendable(n.tier === "short", this.machine.id);
       // The source tuple also recognizes legacy ids whose nodes depended on the checkout or extractor version.
-      const known = this.db.query("SELECT id FROM entries WHERE id = ? OR (source = 'claude-mem' AND project = ? AND at = ? AND text = ?)").get(id, n.project, at, n.text.slice(0, MAX_TEXT)) as { id: string } | null;
+      const known = this.db.query("SELECT id FROM entries WHERE id = ? OR (source = 'claude-mem' AND project = ? AND at = ? AND text = ?)").get(id, n.project, at, stripPrivateSpans(n.text).slice(0, MAX_TEXT)) as { id: string } | null;
       if (known) return { id: known.id, added: false };
       appendFileSync(join(this.dir, n.tier === "short" ? "local" : "log", `${this.machine.id}.jsonl`), JSON.stringify({ ...body, id }) + "\n", { mode: 0o600 });
       return { id, added: true };
@@ -460,11 +483,19 @@ export class MemoryStore {
   private op(op: OpEntry["op"], target: View, actor: string, by?: string): string {
     return this.append({ op, target: target.id, actor, ...(by ? { by } : {}) }, target.local);
   }
-  forget(id: string, actor: string, project?: string): View | undefined {
+  /** Complete existing forget expansion, including superseded legacy-import copies. Reads author no ops. */
+  forgetTargets(id: string, project?: string): View[] {
+    const v = this.get(id, project); return v ? this.forgetGroup(v) : [];
+  }
+  private forgetGroup(v: View): View[] {
+    return v.source === "claude-mem" ? this.live().filter(x => x.source === v.source && x.project === v.project && x.at === v.at && x.text === v.text) : [v];
+  }
+  forget(id: string, actor: string, project?: string, exactOnly = false): View | undefined {
     const v = this.get(id, project);
     if (!v) return undefined;
-    // Legacy imports may have different node-derived ids. Forget every known copy, including hidden ones.
-    const group = v.source === "claude-mem" ? this.live().filter(x => x.source === v.source && x.project === v.project && x.at === v.at && x.text === v.text) : [v];
+    const group = this.forgetGroup(v);
+    if (exactOnly && (group.length !== 1 || group[0]?.id !== id)) throw Error("forget expands beyond the reviewed exact entry");
+    // Ordinary person forget retains its legacy-import copy expansion; reviewed decay is exact-only.
     for (const member of group) this.op("forget", member, actor);
     return v;
   }
@@ -511,7 +542,17 @@ export class MemoryStore {
   }
   /** A short-term note kept short-term: it expires like any other and is never promoted (its demote entry stays local). */
   keepShort(id: string, actor: string): void { const v = this.get(id); if (v?.tier === "short" && v.local && v.expiresAt === null) this.op("demote", v, actor, this.until()); } // once: a deadline is never pushed out
-  demote(id: string, actor: string, project?: string): View | undefined { const v = this.get(id, project); if (v?.tier === "long") this.op("demote", v, actor, this.until()); return v; }
+  /** The short-tier deadline to display before a person confirms a demotion. */
+  shortExpiry(): string { return this.until(); }
+  /** A confirmed deadline may be older than a fresh one, but cannot extend the configured TTL beyond one hour. */
+  assertDemotionExpiry(expiresAt: string): void {
+    const at = Date.parse(expiresAt), now = this.now();
+    if (!Number.isFinite(at) || new Date(at).toISOString() !== expiresAt || at <= now || at > now + this.ttl + 3600_000) throw Error("demotion expiry must be future UTC within the short-tier deadline plus one hour");
+  }
+  demote(id: string, actor: string, project?: string, expiresAt?: string): View | undefined {
+    if (expiresAt !== undefined) this.assertDemotionExpiry(expiresAt);
+    const v = this.get(id, project); if (v?.tier === "long") this.op("demote", v, actor, expiresAt ?? this.until()); return v;
+  }
   supersede(oldId: string, newId: string, actor: string, project?: string): boolean {
     const a = this.get(oldId, project), b = this.get(newId, project);
     if (!a || !b || a.id === b.id) return false;
@@ -759,18 +800,18 @@ export class MemoryStore {
     return nest(this.readStores());
   }
 
-  private viewRows(expired: boolean, selection: (Filter & { ids?: string[] }) | undefined, expiredOnly: boolean): View[] {
-    const now = this.now(), selecting = selection !== undefined || expiredOnly;
-    const pruned = this.generationIndex ? new Set((this.readRows("SELECT id FROM generation_targets") as { id: string }[]).map(row => row.id)) : undefined;
-    if (this.generationIndex) this.generationIndex.pruned = new Set((this.db.query("SELECT id FROM generation_targets").all() as { id: string }[]).map(row => row.id));
+  private viewRows(expired: boolean, selection: (Filter & { ids?: string[] }) | undefined, expiredOnly: boolean, projection?: RecallViewProjection): View[] {
+    const now = projection?.now ?? this.now(), selecting = selection !== undefined || expiredOnly;
+    const pruned = projection?.pruned ?? (this.generationIndex ? new Set((this.readRows("SELECT id FROM generation_targets") as { id: string }[]).map(row => row.id)) : undefined);
+    if (!projection && this.generationIndex) this.generationIndex.pruned = new Set((this.db.query("SELECT id FROM generation_targets").all() as { id: string }[]).map(row => row.id));
     // Relations may cross projects and promoted copies: fold their small metadata globally, never filtered bodies.
-    const rows = this.readRows(selecting
+    const rows = projection?.rows ?? this.readRows(selecting
       ? "SELECT id, at, tier, kind, task, expires, supersedes, promoted_from FROM entries"
       : "SELECT * FROM entries") as Record<string, string | null>[];
-    const ops = this.readRows("SELECT id, op, at, target, by FROM ops ORDER BY at, id") as { id: string; op: string; at: string; target: string; by: string | null }[];
-    const realms = this.generationIndex ? new Map((this.readRows("SELECT id,own,legacy FROM generation_rows") as { id: string; own: number; legacy: number }[]).map(row => [row.id, row])) : undefined;
+    const ops = projection?.ops ?? this.readRows("SELECT id, op, at, target, by FROM ops ORDER BY at, id") as { id: string; op: string; at: string; target: string; by: string | null }[];
+    const realms = projection ? projection.realms : this.generationIndex ? new Map((this.readRows("SELECT id,own,legacy FROM generation_rows") as { id: string; own: number; legacy: number }[]).map(row => [row.id, row])) : undefined;
     const born = realms ? new Set([...realms.values()].filter(row => row.own).map(row => row.id)) : undefined;
-    const forgotten = new Set(ops.filter((o) => o.op === "forget").map((o) => o.target));
+    const forgotten = new Set([...ops.filter((o) => o.op === "forget").map((o) => o.target), ...(projection?.forgotten ?? [])]);
     // Deadlines were fixed when the entries were written, so every process (whatever its own TTL) prunes the same rows.
     const deadline = (o: { at: string; by: string | null }) => o.by && !Number.isNaN(Date.parse(o.by)) ? o.by : new Date(Date.parse(o.at) + this.ttl).toISOString();
     const demoted = new Map(ops.filter((o) => o.op === "demote").map((o) => [o.target, deadline(o)]));
@@ -876,7 +917,7 @@ export class MemoryStore {
     for (const r of candidates) {
       const id = r.id!;
       // A forgotten entry is gone, and so is its promoted copy's source or copy: forgetting either forgets both.
-      if (pruned?.has(id) || forgotten.has(id) || (r.promoted_from && forgotten.has(r.promoted_from)) || promoted.has(id)) continue;
+      if (pruned?.has(id) || forgotten.has(id) || (r.promoted_from && forgotten.has(r.promoted_from)) || promoted.has(id) && !projection?.includePromoted) continue;
       const tier: Tier = demoted.has(id) ? "short" : r.tier as Tier;
       const expiresAt = expiry(r);
       if (!expired && expiresAt !== null && Date.parse(expiresAt) <= now) continue;
@@ -1028,6 +1069,191 @@ export class MemoryStore {
     });
   }
 
+  /** Metadata-only revision of the opened read set, never a note body or an unopened project shard. */
+  recallRevision(): string { return this.recallFingerprint(true); }
+  private recallFingerprint(databases: boolean): string {
+    const entries: unknown[] = [];
+    const stamp = (file: string, directory = false) => {
+      try {
+        const stat = lstatSync(file, { bigint: true });
+        if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile())) throw Error("recall input path unavailable");
+        entries.push([file, String(stat.dev), String(stat.ino), ...(directory ? [] : [String(stat.size), String(stat.mtimeNs), String(stat.ctimeNs)])]);
+        return true;
+      } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") { entries.push([file, "absent"]); return false; } throw error; }
+    };
+    const roots = new Set<string>(), fixed = new Set<string>();
+    for (const store of this.readStores()) {
+      roots.add(store.dir);
+      for (const name of ["profile.json", "shards.json", "aliases.jsonl", "lifecycle.jsonl", "machine.json"]) fixed.add(join(store.profile.home, name));
+      for (const name of ["generation.json", "generation-seal.json", "migration-sources.json", "machine.json"]) fixed.add(join(store.dir, name));
+      if (store.generationIndex) {
+        const legacy = store.profile.legacyHome ?? store.profile.home; roots.add(legacy);
+        if (store.profile.legacyMainHome) roots.add(store.profile.legacyMainHome);
+        if (!store.profile.sharded && store.profile.generation) {
+          const dir = generationDir(legacy, store.profile.generation), pointer = join(dir, "bridge-snapshot.json"); fixed.add(pointer);
+          // Only the small sealed pointer is parsed to locate its active archive; JSONL bodies are never read here.
+          const head = readProfileJSON(pointer, 4096) as { commit?: unknown } | undefined;
+          if (head !== undefined) {
+            if (typeof head.commit !== "string" || !/^[a-f0-9]{40,64}$/.test(head.commit)) throw Error("recall bridge pointer unavailable");
+            const archive = join(dir, "bridge-snapshots", head.commit); roots.add(archive); fixed.add(join(archive, "snapshot.json"));
+          }
+        }
+      }
+      if (databases) entries.push([store.dir, store.db.query("PRAGMA data_version").get(), store.db.query("SELECT total_changes() AS n").get()]);
+    }
+    for (const root of [...roots].sort()) {
+      if (!stamp(root, true)) continue;
+      fixed.add(join(root, "machine.json"));
+      for (const folder of ["log", "local"]) {
+        const dir = join(root, folder); if (!stamp(dir, true)) continue;
+        for (const name of readdirSync(dir).filter(name => name.endsWith(".jsonl")).sort()) stamp(join(dir, name));
+      }
+    }
+    for (const file of [...fixed].sort()) stamp(file);
+    return hashJSON(entries);
+  }
+  private prepareRecallRead(stores: readonly MemoryStore[]): void {
+    for (const store of stores) {
+      const active = readSelector(store.profile.home);
+      if (active.revision !== store.profile.selectorRevision) throw Error("recall profile changed");
+      if (store.profile.sharded) {
+        const selected = readShardedSelection(store.profile.home);
+        if (selected.generation !== store.profile.generation || selected.selectorRevision !== store.profile.selectorRevision) throw Error("recall shard binding changed");
+      } else if ((readProfileJSON(join(store.profile.home, "shards.json")) as { phase?: unknown } | undefined)?.phase === "active"
+        || (active.selector?.kind ?? "shared-v1") !== store.profile.kind || store.profile.kind === "generation" && active.selector?.generation !== store.profile.generation) throw Error("recall profile changed");
+      if (store.reconcile && (resolveAlias(store.profile.home, store.reconcile.canonical) !== store.reconcile.canonical || canonicalJSON(aliasedKeys(store.profile.home, store.reconcile.canonical).sort()) !== canonicalJSON([...store.reconcile.aliases].sort()))) throw Error("recall alias binding changed");
+      if (store.generationIndex) store.generationIndex.refresh();
+      else if (store.stale || store.shape() !== store.seen) {
+        store.stale = false; store.refresh();
+        if (store.stale || store.shape() !== store.seen) throw Error("recall refresh unavailable");
+      }
+    }
+  }
+  /** Strict preparation once; callers release the fences before awaiting policy or optional overlays. */
+  beginRecallRead(): () => void {
+    return this.withStoreFences(stores => {
+      const before = this.recallFingerprint(false);
+      this.prepareRecallRead(stores);
+      for (const store of stores) store.prune(); // readPage performs this too; settle its derived writes before the revision.
+      const captured = this.recallRevision();
+      if (this.recallFingerprint(false) !== before) throw Error("recall inputs changed during preparation");
+      return () => { if (this.recallRevision() !== captured) throw Error("recall inputs changed"); };
+    });
+  }
+  /** One lifecycle fold for a bounded exact-project set of useful intent-brief genres. */
+  intentSnapshot(project: string, limit = 5000): { rows: View[]; truncated: boolean; assertCurrent(): void } {
+    if (!project.trim() || project.length > 400 || !Number.isSafeInteger(limit) || limit < 1 || limit > 5000 || this.profile.sharded && !this.profile.shardUser && this.profile.shardKey !== project) throw Error("invalid intent snapshot scope or limit");
+    return this.withStoreFences(stores => {
+      const before = this.recallFingerprint(false);
+      assertProjectActive(this.profile.home, project); this.prepareRecallRead(stores);
+      const revision = this.recallRevision(), ids = new Map<string, { id: string; at: string }>();
+      if (this.recallFingerprint(false) !== before) throw Error("recall inputs changed during preparation");
+      for (const store of stores) {
+        const rows = store.db.query("SELECT id,at FROM entries WHERE project IN (SELECT value FROM json_each(?)) AND kind IN ('fail','decision','contract') ORDER BY at DESC,id LIMIT ?").all(JSON.stringify(this.scopeKeys(project)), limit + 1) as { id: string; at: string }[];
+        for (const row of rows) ids.set(row.id, row);
+      }
+      const refs = [...ids.values()].sort((a, b) => b.at.localeCompare(a.at) || a.id.localeCompare(b.id)), selected = refs.slice(0, limit);
+      const rows = selected.length ? this.views(false, { project, ids: selected.map(row => row.id) }).filter(view => view.project === project && !view.supersededBy && Number.isFinite(Date.parse(view.at))) : [];
+      const order = new Map(selected.map((row, index) => [row.id, index])); rows.sort((a, b) => order.get(a.id)! - order.get(b.id)!);
+      const assertCurrent = () => { if (this.recallRevision() !== revision) throw Error("recall inputs changed"); };
+      assertCurrent(); return { rows, truncated: refs.length > limit, assertCurrent };
+    });
+  }
+
+  /** The same injected clock used by validity, expiry and projection; callers must not substitute wall time. */
+  readNow(): number { return this.now(); }
+
+  /** Person historical recall over verified retained rows. Current removals always override past state. */
+  recallState(project: string, options: RecallStateOptions = {}): RetainedRecallState {
+    if ((options.history || options.asOf !== undefined) && options.person !== true) throw Error("historical recall requires authenticated person intent from the host");
+    if (!project.trim() || project.length > 400 || this.profile.sharded && !this.profile.shardUser && this.profile.shardKey !== project) throw Error("recall project does not match the bound store");
+    const maximumRows = options.maxRows ?? 50_000, maximumBytes = options.maxBytes ?? 32 * 1024 * 1024, present = this.now();
+    if (!Number.isSafeInteger(maximumRows) || maximumRows < 1 || maximumRows > 50_000 || !Number.isSafeInteger(maximumBytes) || maximumBytes < 1 || maximumBytes > 32 * 1024 * 1024) throw Error("invalid retained recall budget");
+    let time = present;
+    if (options.asOf !== undefined) {
+      const value = /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/.test(options.asOf) ? `${options.asOf}T00:00:00.000Z` : options.asOf;
+      time = Date.parse(value);
+      if (!Number.isFinite(time) || new Date(time).toISOString() !== value || time > present) throw Error("as-of must be a past canonical UTC date or timestamp");
+    }
+    const frontier = () => {
+      const active = readSelector(this.profile.home);
+      if (active.revision !== this.profile.selectorRevision) throw Error("recall profile changed or is not active");
+      if (this.profile.sharded) {
+        const shards = readShardedSelection(this.profile.home);
+        if (shards.generation !== this.profile.generation || shards.selectorRevision !== this.profile.selectorRevision) throw Error("recall shard binding changed");
+      } else if ((readProfileJSON(join(this.profile.home, "shards.json")) as { phase?: unknown } | undefined)?.phase === "active"
+        || (active.selector?.kind ?? "shared-v1") !== this.profile.kind || this.profile.kind === "generation" && active.selector?.generation !== this.profile.generation) throw Error("recall profile changed or is not active");
+      assertProjectActive(this.profile.home, project);
+    };
+    return this.withStoreFences(() => {
+      frontier();
+      const source = new Map<string, Entry>(), realm = new Map<string, { id: string; own: number; legacy: number }>(), pruned = new Set<string>();
+      const reader = new SegmentReader(maximumBytes); let records = 0, bytes = 0, malformed = 0, incomplete = false;
+      const add = (row: Entry, own: boolean, legacy: boolean) => {
+        const { id, ...body } = row;
+        if (row.schema !== MEMORY_SCHEMA || !/^[a-f0-9]{32}$/.test(id) || entryId(body as Omit<Entry, "id">) !== id) throw Error("retained recall row verification failed");
+        const canonical = canonicalJSON(row); records++; bytes += Buffer.byteLength(canonical);
+        if (records > maximumRows || bytes > maximumBytes) throw Error("retained recall budget exceeded");
+        const previous = source.get(id); if (previous && canonicalJSON(previous) !== canonical) throw Error("retained recall identity conflict");
+        source.set(id, row); realm.set(id, { id, own: Number(own), legacy: Number(legacy) });
+      };
+      // Same bound read handles as ordinary views. Never opens an unopened project's private shard.
+      for (const store of this.readStores()) {
+        if (store.generationIndex) {
+          store.generationIndex.refresh(0, reader);
+          store.db.transaction(() => {
+            const size = store.db.query("SELECT COUNT(*) AS n, COALESCE(SUM(length(CAST(line AS BLOB))),0) AS bytes FROM generation_rows").get() as { n: number; bytes: number };
+            if (size.n > maximumRows - records || size.bytes > maximumBytes - bytes) throw Error("retained recall budget exceeded");
+            const diagnostics = store.generationIndex!.recallDiagnostics(); malformed += diagnostics.malformed; incomplete ||= diagnostics.incomplete;
+            const state = store.generationIndex!.snapshot(false);
+            for (const item of state.rows) add(item.row, item.own === true, item.legacy ?? item.own !== true);
+            for (const id of state.pruned ?? []) pruned.add(id);
+          }).deferred();
+        } else {
+          const segments = readLegacySnapshot(store.dir, { reader });
+          incomplete ||= segments.some(segment => segment.tailBytes > 0);
+          for (const row of legacyEntries(segments, { onMalformed: () => { malformed++; } })) add(row, false, true);
+        }
+      }
+      frontier();
+      const all = [...source.values()].sort((a, b) => a.at.localeCompare(b.at) || a.id.localeCompare(b.id));
+      const notes = all.filter((row): row is NoteEntry => row.op === "note");
+      const removed = new Set(pruned), forgottenAt = new Map<string, string>();
+      for (const row of all) if (row.op === "forget") { removed.add(row.target); if (!forgottenAt.has(row.target)) forgottenAt.set(row.target, row.at); }
+      // Forgetting either end removes known promotion ancestry, in linear bounded graph work.
+      const ancestry = new Map<string, string[]>();
+      for (const note of notes) if (note.promotedFrom) {
+        ancestry.set(note.id, [...ancestry.get(note.id) ?? [], note.promotedFrom]);
+        ancestry.set(note.promotedFrom, [...ancestry.get(note.promotedFrom) ?? [], note.id]);
+      }
+      const queue = [...removed];
+      for (let index = 0; index < queue.length; index++) {
+        const id = queue[index]!, at = forgottenAt.get(id);
+        for (const next of ancestry.get(id) ?? []) {
+          const fresh = !removed.has(next);
+          if (fresh) { removed.add(next); queue.push(next); }
+          if (at && !forgottenAt.has(next)) { forgottenAt.set(next, at); if (!fresh) queue.push(next); }
+        }
+      }
+      const visible = (note: NoteEntry) => this.inScope(note.project, project) || note.scope === "shared";
+      const dated = notes.filter(note => options.asOf === undefined || Date.parse(note.at) <= time), retained = new Map(dated.filter(visible).map(note => [note.id, note]));
+      const rows = dated.map(note => ({ id: note.id, at: note.at, machine: note.machine, project: note.project, scope: note.scope, tier: note.tier, kind: note.kind, peer: note.peer, title: note.title ?? null, text: note.text,
+        task: note.task ?? null, about: JSON.stringify(note.about), source: note.source ?? "hub", supersedes: note.supersedes ?? null, promoted_from: note.promotedFrom ?? null, expires: note.expires ?? null }));
+      const ops = all.filter((row): row is OpEntry => row.op !== "note" && row.op !== "goal" && (options.asOf === undefined || Date.parse(row.at) <= time)).map(row => ({ id: row.id, op: row.op, at: row.at, target: row.target, by: row.by ?? null }));
+      const views = this.viewRows(options.history === true, undefined, false, { now: time, rows, ops, ...(this.generationIndex ? { realms: realm } : {}), pruned, forgotten: removed, includePromoted: options.history === true })
+        .filter(view => (this.inScope(view.project, project) || view.scope === "shared") && (options.history === true || !view.supersededBy));
+      const forgotten = [...forgottenAt].flatMap(([id, at]) => retained.has(id) ? [{ id, at }] : []).sort((a, b) => a.at.localeCompare(b.at) || a.id.localeCompare(b.id));
+      const relations: RecallRelation[] = [];
+      const link = (from: string, to: string, at: string, kind: RecallRelation["kind"]) => { if (retained.has(from) && retained.has(to) && !pruned.has(from) && !pruned.has(to)) relations.push({ from, to, at, kind }); };
+      for (const note of dated) { if (note.supersedes) link(note.supersedes, note.id, note.at, "supersede"); if (note.promotedFrom) link(note.promotedFrom, note.id, note.at, "promote"); }
+      for (const op of ops) if (op.op === "supersede" && op.by) link(op.target, op.by, op.at, "supersede");
+      const notices = (options.asOf !== undefined || options.history === true) && views.some(view => view.promotedFrom)
+        ? ["promotion time unknown: tier before promotion cannot be recovered"] : [];
+      frontier();
+      return { at: new Date(time).toISOString(), views, forgotten, relations, malformed, notices, incomplete: incomplete || malformed > 0 || notices.length > 0, ...(incomplete || malformed > 0 ? { sourceIncomplete: true as const } : {}) };
+    });
+  }
+
   /** One entry by id or unique id prefix; with `project`, only one that project may read (its own or shared). */
   get(id: string, project?: string): View | undefined {
     id = id.replace(/^mem:/, ""); // briefs and recall print `mem:<id>`
@@ -1073,10 +1299,10 @@ export class MemoryStore {
   }
 
   /** The neighbourhood of one node for the dashboard: up to `hops` (1 or 2) steps, at most `cap` nodes. */
-  graph(project: string, start: Node, hops = 1, cap = 200): Graph {
+  graph(project: string, start: Node, hops = 1, cap = 200, projection?: readonly View[]): Graph {
     this.ensureFresh();
     if (start.startsWith("mem:") && this.generationIndex?.pruned.has(start.slice(4))) return { nodes: [], edges: [] };
-    const live = new Map(this.list({ project, limit: Number.MAX_SAFE_INTEGER, includeSuperseded: true }).map((v) => [`mem:${v.id}`, v]));
+    const live = new Map((projection ?? this.list({ project, limit: Number.MAX_SAFE_INTEGER, includeSuperseded: true })).map((v) => [`mem:${v.id}`, v]));
     const nodes = new Map<Node, Graph["nodes"][number]>(), edges = new Map<string, Graph["edges"][number]>();
     const goals = new Map(this.goals(project).map((g) => [`goal:${g.id}`, g]));
     const suggestions = this.suggestions().filter((x) => x.status !== "rejected");
@@ -1123,6 +1349,8 @@ export class MemoryStore {
         return ids;
       }
       const ids = (this.db.query("SELECT src FROM edges WHERE dst = ?").all(id) as { src: string }[]).map((r) => `mem:${r.src}`).filter((m) => live.has(m));
+      // Retained expired rows may no longer have derived edges; only their verified authored about nodes supply them.
+      if (projection) for (const view of projection) if (view.about.includes(id) && !ids.includes(`mem:${view.id}`)) ids.push(`mem:${view.id}`);
       for (const m of ids) { const v2 = live.get(m)!; link(m, id, v2.kind === "fail" ? "rules_out" : "about"); }
       return [...ids, ...parts];
     };
@@ -1269,6 +1497,8 @@ export function openShardStore(opts: StoreOptions & { project?: string; user?: b
   if (opts.memoryDir !== undefined && (opts.home !== undefined || typeof opts.memoryDir !== "string" || !opts.memoryDir.trim())) throw new Error("choose a memory home or one explicit memory directory");
   const home = opts.memoryDir ?? (opts.home === undefined ? memoryHome() : join(opts.home, "memory"));
   assertCuratedShardPaths(home, opts);
+  // #15 T5: the one gate every recall path shares, checked before a shard can be created. The user shard has no lifecycle.
+  if (opts.user !== true && opts.lifecycle !== "ignore") assertProjectActive(home, opts.project!);
   const dir = opts.user === true ? userShardDir(home) : shardDir(home, opts.project!);
   const missing = !existsSync(join(dir, "generation.json"));
   if (missing) initializeShard(home, opts);

package/src/memory/sync-cadence.ts

@@ -0,0 +1,139 @@
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { generationDir, readSelector } from "./generation.ts";
+
+/**
+ * F16, `amem sync --if-due`: the person's own shell (an EXIT trap) asks amem to sync when it is due; amem itself runs nothing between sessions and never
+ * registers a hook for it. Like every mutating command it needs a terminal, so an unattended scheduler (cron, launchd) is not a caller (a hook may not do network work: AGENTS.md, test/hooks-network.test.ts). The only state is one small stamp beside the logs.
+ * The stamp holds times and a failure count, never an error text (a git error can carry a remote URL).
+ */
+export interface SyncState { lastAttemptAt: string | null; lastOkAt: string | null; failures: number }
+export const SYNC_STATE_FILE = "sync-state.json";
+/** After a success, the next attempt is due this long after the last one. */
+export const SYNC_INTERVAL_MS = 60 * 60_000;
+/** After a failure the wait starts here and doubles with each further failure. */
+export const SYNC_BACKOFF_BASE_MS = 15 * 60_000;
+export const SYNC_BACKOFF_CAP_MS = 24 * 60 * 60_000;
+const MAX_FAILURES = 30, MAX_BYTES = 4096;
+const EMPTY: SyncState = { lastAttemptAt: null, lastOkAt: null, failures: 0 };
+const iso = (value: unknown): string | null => typeof value === "string" && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value ? value : null;
+
+/** Never throws: a missing, oversized or malformed stamp is "no history", which makes a sync due. */
+export function readSyncState(home: string): SyncState {
+  let fd: number | undefined;
+  try {
+    fd = openSync(join(home, SYNC_STATE_FILE), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > MAX_BYTES) return { ...EMPTY };
+    const buffer = Buffer.alloc(stat.size), size = readSync(fd, buffer, 0, buffer.length, 0);
+    const value = JSON.parse(buffer.subarray(0, size).toString("utf8")) as Record<string, unknown>;
+    const failures = Number.isSafeInteger(value.failures) && (value.failures as number) >= 0 ? Math.min(value.failures as number, MAX_FAILURES) : 0;
+    return { lastAttemptAt: iso(value.lastAttemptAt), lastOkAt: iso(value.lastOkAt), failures };
+  } catch { return { ...EMPTY }; }
+  finally { if (fd !== undefined) try { closeSync(fd); } catch { /* nothing to close */ } }
+}
+
+/** The wait after the last attempt: the plain interval after a success, 15 minutes doubling to a day after failures. */
+export function syncWaitMs(failures: number): number {
+  return failures <= 0 ? SYNC_INTERVAL_MS : Math.min(SYNC_BACKOFF_BASE_MS * 2 ** (failures - 1), SYNC_BACKOFF_CAP_MS);
+}
+
+/** The earliest next attempt, or null when none was recorded (due now). */
+export function nextSyncAt(state: SyncState): number | null {
+  return state.lastAttemptAt === null ? null : Date.parse(state.lastAttemptAt) + syncWaitMs(state.failures);
+}
+
+/** `force` (`--force`) ignores the schedule and the backoff. */
+export function syncDue(state: SyncState, now: number, force = false): boolean {
+  const next = nextSyncAt(state);
+  return force || next === null || now >= next;
+}
+
+/** `--if-due` stops a running git step after this long, so a shell that runs it on exit is held for a bounded time. */
+export const SYNC_IF_DUE_DEADLINE_MS = 30_000;
+
+/**
+ * The stop signal of one `--if-due` run: the 30 second deadline, or any way the person ends it: Ctrl-C (SIGINT), SIGTERM, SIGHUP (the terminal closed, which is also how an
+ * EXIT trap's shell can go away) and SIGQUIT. git runs in its own process group while a stop signal is given (so the stop reaches its transport children), which also means a
+ * terminal's signals no longer reach git by themselves: amem turns each of them into the abort. `on`, not `once`: a second Ctrl-C must not fall back to the default action
+ * (which would end amem and strand git) while the first is still stopping git; the handlers stay until `dispose`. A process that dies some other way is covered by the exit
+ * handler in sync.ts, which signals every live git group. The emitter is a seam for tests; the CLI passes `process`.
+ */
+export const STOP_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"] as const;
+export type StopCause = "person" | "deadline";
+export function stopSignal(ms: number, emitter: { on(name: string, fn: () => void): unknown; off(name: string, fn: () => void): unknown }, names: readonly string[] = STOP_SIGNALS): { signal: AbortSignal; dispose: () => void; cause: () => StopCause | undefined } {
+  const controller = new AbortController(), deadline = AbortSignal.timeout(ms);
+  let cause: StopCause | undefined;
+  // The first thing that ends the run is its cause: a person who closes the terminal after the deadline already fired did not stop it.
+  const stop = () => { cause ??= "person"; controller.abort(); };
+  deadline.addEventListener("abort", () => { cause ??= "deadline"; }, { once: true });
+  for (const name of names) emitter.on(name, stop);
+  return { signal: AbortSignal.any([controller.signal, deadline]), dispose: () => { for (const name of names) emitter.off(name, stop); }, cause: () => cause };
+}
+
+/**
+ * The repository the active profile syncs through: a curated split keeps a private cache in `shard-sync/objects.git`, a generation home keeps its own `.git` inside the
+ * generation directory (the memory home's own `.git` is then only the legacy input), and shared-v1 keeps `.git` in the memory home. Undefined when the profile cannot be
+ * resolved (an unreadable selector): no remote is then reported rather than a guess.
+ */
+function syncRepository(home: string): string | undefined {
+  try {
+    if (lstatSync(join(home, "shards.json"), { throwIfNoEntry: false })) return join(home, "shard-sync", "objects.git", "config");
+    const { selector } = readSelector(home);
+    if (selector?.kind === "generation") return join(generationDir(home, selector.generation!), ".git", "config");
+    return join(home, ".git", "config");
+  } catch { return undefined; }
+}
+
+/**
+ * Whether the active profile has a sync remote configured, from its repository's own config file: no git process, and never the URL (it can carry a credential).
+ */
+export function remoteConfigured(home: string): boolean {
+  const file = syncRepository(home);
+  if (file === undefined) return false;
+  let fd: number | undefined;
+  try {
+    fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > 65536) return false;
+    const buffer = Buffer.alloc(stat.size), size = readSync(fd, buffer, 0, buffer.length, 0);
+    return /^\s*\[remote "origin"\]/m.test(buffer.subarray(0, size).toString("utf8"));
+  } catch { return false; }   // no such repository
+  finally { if (fd !== undefined) try { closeSync(fd); } catch { /* nothing to close */ } }
+}
+
+/** A stamp from the future (a clock set back, a hand edit) would block the sync until then plus the wait: it counts as no history, and so does a success it claims. */
+export function usableState(state: SyncState, now: number): SyncState {
+  const future = (value: string | null) => value !== null && Date.parse(value) > now;
+  if (future(state.lastAttemptAt)) return { lastAttemptAt: null, lastOkAt: future(state.lastOkAt) ? null : state.lastOkAt, failures: 0 };
+  return future(state.lastOkAt) ? { ...state, lastOkAt: null } : state;
+}
+
+/**
+ * What a finished sync means for the schedule. `ok` clears the backoff. `local` is a refusal that the schedule cannot fix and that no remote ever saw, or a run its person ended (another sync or
+ * mutation holds the lock, no remote is configured, the configured policy declines a note, the remote is public, a usage error): it is not stamped, so it neither
+ * backs the schedule off nor makes a contended run look like a failed one. Everything else is a `failed` transport or git step, and an error this module does not
+ * recognise counts as failed (the safe side: it waits instead of retrying every minute).
+ */
+export type SyncOutcome = "ok" | "failed" | "local";
+const LOCAL = /^(usage:|another (sync|memory mutation|generation|shard sync)|no (generation )?sync remote|the configured privacy policy|the sync remote is public|this (machine's|store's) long-term|a line of this machine's long-term|more than \d+ long-term)/;
+export function syncOutcome(error: string | undefined, cause?: StopCause): SyncOutcome {
+  if (error === undefined) return "ok";
+  // A run its person ended (Ctrl-C, a closing terminal) is not a failure of the remote: the same Ctrl-C reads "fetch failed" or "stopped" depending on which step it hit, so the cause,
+  // not the text, decides. Only the deadline (a remote that did not answer in time) stays a failure to back off from.
+  if (cause === "person") return "local";
+  return LOCAL.test(error.replace(/^amem sync: /, "")) ? "local" : "failed";
+}
+
+/** Records one attempt. A stamp that cannot be written never fails the sync it describes. */
+export function recordSyncAttempt(home: string, ok: boolean, at: number): SyncState {
+  const prior = readSyncState(home), when = new Date(at).toISOString();
+  const next: SyncState = { lastAttemptAt: when, lastOkAt: ok ? when : prior.lastOkAt, failures: ok ? 0 : Math.min(prior.failures + 1, MAX_FAILURES) };
+  const file = join(home, SYNC_STATE_FILE), temp = `${file}.${process.pid}.tmp`;
+  try {
+    mkdirSync(home, { recursive: true, mode: 0o700 });
+    writeFileSync(temp, JSON.stringify(next) + "\n", { mode: 0o600 });
+    renameSync(temp, file);
+  } catch { try { rmSync(temp, { force: true }); } catch { /* best effort */ } }
+  return next;
+}