@staix/agent-mem 0.1.1 → 0.3.0

package/src/memory/store.ts

@@ -3,7 +3,14 @@ import { createHash, randomBytes } from "node:crypto";
 import { appendFileSync, chmodSync, closeSync, existsSync, fstatSync, linkSync, 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 { mutationDatabase } from "./mutation.ts";
 import { memoryHome } from "./home.ts";
+import { assertSharedV1Op } from "./ops-contract.ts";
+import { generationDescriptor, generationDir, canonicalJSON, readProfileJSON, resolveProfile, type BoundProfile, type ProfileInput } from "./generation.ts";
+import { GenerationIndex, explicitExpirySnapshot, GENERATION_TABLES } from "./generation-index.ts";
+import { legacyEntries, type LegacyCheckpoint } from "./bridge.ts";
+import type { PruneStorePort } from "./prune.ts";
+import { isDeepStrictEqual } from "node:util";
 
 /**
  * #258: the hub's own memory. Append-only JSONL logs are the truth: `log/<machine>.jsonl` holds long-term entries and
@@ -173,18 +180,34 @@ export type PromotionScreen = (v: View) => "promote" | "keep" | "skip";
  * `screen`: applied to every promotion. Without one, automatic promotions (a settlement, a held note whose replacement
  * went) wait for a process that has one; a person's explicit promote goes through.
  */
-export interface StoreOptions { home?: string; ttlMs?: number; now?: () => number; log?: (line: string) => void; screen?: PromotionScreen }
+export interface StoreOptions { home?: string; ttlMs?: number; now?: () => number; log?: (line: string) => void; screen?: PromotionScreen; deferPromotions?: boolean; profile?: ProfileInput;
+}
 
+const MIGRATION_BOOTSTRAP = Symbol("migration index bootstrap");
+interface BootstrapBinding { token: typeof MIGRATION_BOOTSTRAP; profile: BoundProfile; limits: readonly LegacyCheckpoint[]; commit?: string }
 export class MemoryStore {
   readonly dir: string;
+  readonly profile: BoundProfile;
+  private readonly generationIndex?: GenerationIndex;
+  private readonly bootstrapOnly: boolean;
   readonly machine: Machine;
   private readonly db: Database;
+  private readonly mutationDb: Database;
   private readonly ttl: number;
   private readonly now: () => number;
   private readonly log: (line: string) => void;
-
-  constructor(opts: StoreOptions = {}) {
-    this.dir = opts.home === undefined ? memoryHome() : join(opts.home, "memory");
+  private readonly deferPromotions: boolean;
+
+  constructor(opts: StoreOptions = {}, bootstrap?: BootstrapBinding) {
+    if (bootstrap && bootstrap.token !== MIGRATION_BOOTSTRAP) throw new Error("invalid migration bootstrap");
+    this.bootstrapOnly = bootstrap !== undefined;
+    const home = opts.home === undefined ? memoryHome() : join(opts.home, "memory");
+    this.profile = bootstrap?.profile ?? resolveProfile(home, opts.profile);
+    if (bootstrap && (this.profile.kind !== "generation" || !this.profile.generation
+      || this.profile.dir !== generationDir(this.profile.home, this.profile.generation)
+      || canonicalJSON(readProfileJSON(join(this.profile.dir, "generation.json"))) !== canonicalJSON(generationDescriptor(this.profile.generation)))) throw new Error("invalid migration profile binding");
+    // Shared-v1 preserves its historical lexical dir API; profile.home is still canonical for selector identity.
+    this.dir = this.profile.kind === "shared-v1" ? home : this.profile.dir;
     mkdirSync(join(this.dir, "log"), { recursive: true, mode: 0o700 });
     mkdirSync(join(this.dir, "local"), { recursive: true, mode: 0o700 });
     chmodSync(this.dir, 0o700); // mkdir's mode applies only when it creates the directory
@@ -193,6 +216,7 @@ export class MemoryStore {
     this.now = opts.now ?? Date.now;
     this.log = opts.log ?? (() => {});
     this.screen = opts.screen;
+    this.deferPromotions = opts.deferPromotions ?? false;
     const db = new Database(join(this.dir, "index.db"), { create: true });
     db.run(`PRAGMA busy_timeout = ${MEMORY_DB_BUSY_TIMEOUT_MS}`);
     db.run("PRAGMA journal_mode = WAL");
@@ -210,11 +234,66 @@ export class MemoryStore {
     db.run("CREATE TABLE IF NOT EXISTS edges (src TEXT NOT NULL, dst TEXT NOT NULL, PRIMARY KEY (src, dst))");
     db.run("CREATE INDEX IF NOT EXISTS edges_dst ON edges (dst)");
     this.db = db;
+    this.mutationDb = mutationDatabase(this.dir);
     try { chmodSync(join(this.dir, "index.db"), 0o600); } catch { /* best effort */ }
+    if (this.profile.kind === "generation") this.generationIndex = new GenerationIndex({ profile: this.profile, db, now: this.now,
+      apply: (line, source) => this.apply(line, source), withMutation: work => this.withMutation(work),
+      ...(bootstrap ? { limits: bootstrap.limits } : {}), ...(bootstrap?.commit ? { commit: bootstrap.commit } : {}) });
     this.refresh();
   }
 
-  close(): void { this.db.close(); }
+  /** The host must authenticate person intent before authorizing plan/apply through this port. */
+  prunePort(): PruneStorePort {
+    if (this.bootstrapOnly || !this.generationIndex) throw new Error("durable prune requires an active generation handle");
+    return this.generationIndex.port(this.machine.id);
+  }
+
+  /** Full derived receipt for golden replay; raw debug data, never model evidence. */
+  derivedTables(): Record<string, unknown[]> {
+    const tables = this.db.query("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name").all() as { name: string }[];
+    return Object.fromEntries(tables.map(({ name }) => [name, (this.db.query(`SELECT * FROM "${name.replaceAll('"', '""')}"`).all() as unknown[]).sort((a, b) => canonicalJSON(a).localeCompare(canonicalJSON(b)))]));
+  }
+
+  close(): void { this.db.close(); this.mutationDb.close(); }
+
+  /** 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; }
+  }
+
+  private withMutation<T>(work: () => T): T {
+    return this.mutationDb.transaction(work).immediate();
+  }
+
+  /** 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 {
+    try { return this.withMutation(() => {
+      // 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) } : {}),
+        ...(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,
+        task: normalized.task ?? null, about: [...normalized.about], supersededBy: null,
+        supersedes: normalized.supersedes ? [normalized.supersedes] : [], promotedFrom: normalized.promotedFrom ?? null,
+        expiresAt: normalized.expires ?? null, local: normalized.tier === "short" };
+      if (this.screen?.(view) !== "promote") throw new Error("candidate refused by current promotion screen");
+      let appended = false;
+      return work(() => {
+        if (appended) throw new Error("accepted note already appended");
+        appended = true;
+        return this.appendBody(body, normalized.tier === "short");
+      });
+    }); } catch (error) {
+      // A callback can fail after a durable JSONL append; ensure the derived index catches up.
+      this.stale = true;
+      throw error;
+    }
+  }
 
   /** When a short-term entry written now leaves the index. */
   private until(): string { return new Date(this.now() + this.ttl).toISOString(); }
@@ -223,12 +302,21 @@ export class MemoryStore {
   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;
     const body = { schema: MEMORY_SCHEMA, at, machine, ...capped } as Omit<Entry, "id">;
-    const id = entryId(body);
-    appendFileSync(join(this.dir, local ? "local" : "log", `${this.machine.id}.jsonl`), JSON.stringify({ ...body, id }) + "\n", { mode: 0o600 });
-    // The line is written, so the entry is saved: an index that cannot be updated now (a busy database) catches up on the
-    // next read, and the caller is never told it failed.
-    try { this.refresh(); } catch (e) { this.stale = true; this.log(`hub memory index not updated yet: ${(e as Error).message}`); }
-    return id;
+    return this.appendBody(body, local);
+  }
+
+  private appendBody(body: Omit<Entry, "id">, local: boolean): string {
+    if (this.bootstrapOnly) throw new Error("migration bootstrap cannot author memory");
+    assertSharedV1Op(body.op);
+    // Lock the authoritative log independently: a busy derived index must never prevent an ordinary append.
+    return this.withMutation(() => {
+      this.generationIndex?.assertAppendable(local, this.machine.id);
+      const id = entryId(body);
+      appendFileSync(join(this.dir, local ? "local" : "log", `${this.machine.id}.jsonl`), JSON.stringify({ ...body, id }) + "\n", { mode: 0o600 });
+      // The line is durable even if indexing fails; the next refresh catches up from the authoritative log.
+      try { this.refresh(); } catch (e) { this.stale = true; this.log(`hub memory index not updated yet: ${(e as Error).message}`); }
+      return id;
+    });
   }
 
   /** A note: short-term ones stay on this machine, long-term ones go to the synced log. The caller has screened it. */
@@ -241,14 +329,19 @@ export class MemoryStore {
    * the same id, so a second import writes nothing. Returns the id and whether it was new.
    */
   importNote(n: NoteInput, at: string): { id: string; added: boolean } {
+    if (this.bootstrapOnly) throw new Error("migration bootstrap cannot import memory");
+    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 id = entryId(body);
-    // 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;
-    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 };
+    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;
+      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 };
+    });
   }
 
   /** A person's or the hub's op on an entry; it goes where the entry lives, so forgetting a long-term entry syncs. */
@@ -326,6 +419,7 @@ export class MemoryStore {
    */
   promote(id: string, actor: string, project?: string, auto = false): string | undefined {
     const v = this.get(id, project);
+    if (v && this.generationIndex && !this.generationIndex.own(v.id)) return undefined;
     if (!v || v.tier !== "short") return v?.id;
     if (v.supersededBy) return undefined;
     // Screened here, whatever asked: a note saved under an older policy must not reach the synced log under a newer one.
@@ -354,11 +448,15 @@ export class MemoryStore {
   }
   private promoteSettled(task: string, actor: string): number {
     // Only the notes held for promotion (no deadline): one saved short-term after the settlement stays short-term.
-    const moving = this.views().filter((v) => v.task === task && v.tier === "short" && v.local && !v.supersededBy && v.expiresAt === null && PROMOTED_KINDS.includes(v.kind));
+    const moving = this.views().filter((v) => (!this.generationIndex || this.generationIndex.own(v.id)) && v.task === task && v.tier === "short" && v.local && !v.supersededBy && v.expiresAt === null && PROMOTED_KINDS.includes(v.kind));
     return moving.filter((v) => this.promote(v.id, actor, undefined, true) !== undefined).length;
   }
   /** Whether a task was ever settled, for the hub's reconciliation of approvals a crash cut off before their settle entry. */
-  settled(task: string): boolean { return !!this.db.query("SELECT 1 FROM ops WHERE op = 'settle' AND target = ?").get(task); }
+  settled(task: string): boolean {
+    return !!this.db.query(this.generationIndex
+      ? "SELECT 1 FROM ops JOIN generation_rows ON generation_rows.id=ops.id WHERE op='settle' AND target=? AND own=1"
+      : "SELECT 1 FROM ops WHERE op = 'settle' AND target = ?").get(task);
+  }
   /** Whether any entry was saved against the task. */
   hasTask(task: string): boolean { return !!this.db.query("SELECT 1 FROM entries WHERE task = ?").get(task); }
   private promoting = false;
@@ -368,12 +466,15 @@ export class MemoryStore {
    * settlement a crash cut short, or a replacement that was forgotten or expired).
    */
   private promoteHeld(): void {
-    if (this.promoting) return;
+    if (this.promoting || this.deferPromotions) return;
     this.promoting = true;
     try {
-      const settled = new Set((this.db.query("SELECT target FROM ops WHERE op = 'settle'").all() as { target: string }[]).map((r) => r.target));
+      const settled = new Set((this.db.query(this.generationIndex
+        ? "SELECT target FROM ops JOIN generation_rows ON generation_rows.id=ops.id WHERE op='settle' AND own=1"
+        : "SELECT target FROM ops WHERE op = 'settle'").all() as { target: string }[]).map((r) => r.target));
       if (!settled.size) return;
       for (const v of this.views()) {
+        if (this.generationIndex && !this.generationIndex.own(v.id)) continue; // The bridge never auto-promotes legacy inputs.
         if (v.task && settled.has(v.task) && v.tier === "short" && v.local && !v.supersededBy && v.expiresAt === null && PROMOTED_KINDS.includes(v.kind)) {
           try { this.promote(v.id, "hub", undefined, true); } catch { /* fail-open: tried again at the next read */ }
         }
@@ -383,6 +484,7 @@ export class MemoryStore {
 
   /** Index what the segments gained since the last read. A line still being written (no newline yet) waits for the next read. */
   refresh(attempt = 0): void {
+    if (this.generationIndex) { this.generationIndex.refresh(); return; }
     const files = [...this.segments("log"), ...this.segments("local")];
     const seen = this.shape(files); // taken before reading: a line written meanwhile changes it again
     // One statement, one snapshot: an offset and a head from two different commits would look like a rewrite.
@@ -444,6 +546,7 @@ export class MemoryStore {
 
   /** Drop the index and read every segment again: the same rows as the incremental index. */
   rebuild(): void {
+    if (this.generationIndex) { this.generationIndex.rebuild(); return; }
     // One transaction: no reader sees the index empty, and no other process commits an offset in between.
     this.db.transaction(() => { for (const t of ["segments", "heads", "entries", "ops", "edges", "goals"]) this.db.run(`DELETE FROM ${t}`); this.refresh(); }).immediate();
   }
@@ -487,18 +590,39 @@ export class MemoryStore {
 
   /**
    * Every live note with its derived state; an expired one is left out as soon as its deadline passes, before any
-   * prune. ponytail: computed in memory over all rows; push the filters into SQL when the store grows.
+   * prune. Lifecycle relations still fold globally; SQL selects full rows before View/JSON materialization.
+   * ponytail: lifecycle metadata is still scanned on every read; measure before adding a revision cache.
    */
-  private views(expired = false): View[] {
-    const now = this.now();
-    const rows = this.db.query("SELECT * FROM entries").all() as Record<string, string | null>[];
-    const ops = this.db.query("SELECT op, at, target, by FROM ops ORDER BY at, id").all() as { op: string; at: string; target: string; by: string | null }[];
+  private views(expired = false, selection?: Filter, expiredOnly = false): View[] {
+    // Metadata, ops and candidate bodies must describe one WAL snapshot, even if another process indexes a copy.
+    return this.db.transaction(() => this.viewRows(expired, selection, expiredOnly)).deferred();
+  }
+
+  private viewRows(expired: boolean, selection: Filter | undefined, expiredOnly: boolean): View[] {
+    const now = this.now(), selecting = selection !== undefined || expiredOnly;
+    const pruned = this.generationIndex ? new Set((this.db.query("SELECT id FROM generation_targets").all() as { id: string }[]).map(row => row.id)) : undefined;
+    if (this.generationIndex && pruned) this.generationIndex.pruned = pruned;
+    // Relations may cross projects and promoted copies: fold their small metadata globally, never filtered bodies.
+    const rows = this.db.query(selecting
+      ? "SELECT id, at, tier, kind, task, expires, supersedes, promoted_from FROM entries"
+      : "SELECT * FROM entries").all() as Record<string, string | null>[];
+    const ops = this.db.query("SELECT id, op, at, target, by FROM ops ORDER BY at, id").all() as { id: string; op: string; at: string; target: string; by: string | null }[];
+    const realms = this.generationIndex ? new Map((this.db.query("SELECT id,own,legacy FROM generation_rows").all() 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));
     // 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)]));
     const settled = new Map<string, string>();
-    for (const o of ops) if (o.op === "settle" && !settled.has(o.target)) settled.set(o.target, deadline(o));
+    const settlementKey = (id: string, task: string) => born ? `${born.has(id)}:${task}` : task;
+    for (const o of ops) if (o.op === "settle") {
+      const source = realms?.get(o.id);
+      const keys = !realms ? [o.target] : [
+        ...(source?.own ? [`true:${o.target}`] : []),
+        ...(source?.legacy || !source?.own ? [`false:${o.target}`] : []),
+      ];
+      for (const key of keys) if (!settled.has(key)) settled.set(key, deadline(o));
+    }
     const superseded = new Map<string, string>(), supersededAt = new Map<string, string>();
     // Relations from ops and from notes' own `supersedes` fold together by write time (then id): the latest intent wins.
     const relate = (old: string, newer: string, when: string) => { if (!(when < (supersededAt.get(old) ?? ""))) { superseded.set(old, newer); supersededAt.set(old, when); } };
@@ -511,15 +635,17 @@ export class MemoryStore {
       // A decision, contract or fail of a settled task not yet copied to long-term waits for its promotion, never expires
       // first; a note saved short-term after the settlement carries its own deadline and stays short-term.
       // A superseded one is held too: if its replacement goes, it shows again, and a rebuild must find it the same way.
-      if (r.tier === "short" && !demoted.has(id) && !r.expires && r.task && settled.has(r.task) && PROMOTED_KINDS.includes(r.kind as Kind)) return null;
+      const taskDeadline = r.task ? settled.get(settlementKey(id, r.task)) : undefined;
+      if (r.tier === "short" && !demoted.has(id) && !r.expires && taskDeadline && PROMOTED_KINDS.includes(r.kind as Kind)) return null;
       // A deadline written into the note (no task, a late note, an explicit short horizon) is its own, whatever the task does.
-      return demoted.get(id) ?? r.expires ?? (r.task ? settled.get(r.task) ?? new Date(Date.parse(r.at!) + UNSETTLED_MS).toISOString() : new Date(Date.parse(r.at!) + this.ttl).toISOString());
+      return demoted.get(id) ?? r.expires ?? (r.task ? taskDeadline ?? new Date(Date.parse(r.at!) + UNSETTLED_MS).toISOString() : new Date(Date.parse(r.at!) + this.ttl).toISOString());
     };
     // A newer entry that was forgotten, expired or pruned no longer replaces anything: the older one shows again. A
     // promoted source lives on as its copy.
     const byId = new Map(rows.map((r) => [r.id!, r]));
     const copyOf = new Map(rows.filter((r) => r.promoted_from).map((r) => [r.promoted_from!, r.id!]));
     const gone = (id: string): boolean => {
+      if (pruned?.has(id)) return true;
       const r = byId.get(id);
       if (!r || forgotten.has(id) || (r.promoted_from && forgotten.has(r.promoted_from))) return true;
       const copy = copyOf.get(id);
@@ -550,11 +676,40 @@ export class MemoryStore {
     }
     const supersedes = new Map<string, string[]>(); // the reverse: what each newer entry replaced
     for (const [old, newer] of superseded) supersedes.set(newer, [...(supersedes.get(newer) ?? []), old]);
+    let candidates = rows;
+    if (selecting) {
+      const hidden: string[] = [], expiredIds: string[] = [];
+      for (const r of rows) {
+        const id = r.id!;
+        if (pruned?.has(id) || forgotten.has(id) || (r.promoted_from && forgotten.has(r.promoted_from)) || promoted.has(id)) { hidden.push(id); continue; }
+        const at = expiry(r);
+        if (at !== null && Date.parse(at) <= now) expiredIds.push(id);
+      }
+      const where: string[] = [], bind: string[] = [];
+      const ids = (values: Iterable<string>, exclude: boolean) => {
+        const entries = [...values];
+        if (entries.length || !exclude) { where.push(`id ${exclude ? "NOT IN" : "IN"} (SELECT value FROM json_each(?))`); bind.push(JSON.stringify(entries)); }
+      };
+      ids(hidden, true);
+      if (expiredOnly) ids(expiredIds, false); else if (!expired) ids(expiredIds, true);
+      if (selection) {
+        if (selection.project) { where.push("(project = ? OR scope = 'shared')"); bind.push(selection.project); }
+        if (selection.tier) {
+          if (demoted.size) { where.push("CASE WHEN id IN (SELECT value FROM json_each(?)) THEN 'short' ELSE tier END = ?"); bind.push(JSON.stringify([...demoted.keys()]), selection.tier); }
+          else { where.push("tier = ?"); bind.push(selection.tier); }
+        }
+        for (const key of ["kind", "peer", "machine"] as const) if (selection[key]) { where.push(`${key} = ?`); bind.push(selection[key]!); }
+        if (!selection.includeSuperseded) ids(superseded.keys(), true);
+      }
+      // No SQL LIMIT: a host may screen the complete matching set before its own caps or visible counts.
+      // Date parsing, Unicode query matching, locale order and slice semantics stay in JavaScript.
+      candidates = this.db.query(`SELECT * FROM entries${where.length ? ` WHERE ${where.join(" AND ")}` : ""}`).all(...bind) as Record<string, string | null>[];
+    }
     const out: View[] = [];
-    for (const r of rows) {
+    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 (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)) 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;
@@ -570,8 +725,9 @@ export class MemoryStore {
    * the clock passes it once more. A durable prune entry in the log would close that gap.
    */
   prune(): number {
+    if (this.generationIndex) return 0; // Generation raw rows remain authoritative; only explicit durable prune masks them.
     const now = this.now();
-    const expired = this.views(true).filter((v) => v.expiresAt !== null && Date.parse(v.expiresAt) <= now);
+    const expired = this.views(true, undefined, true).filter((v) => v.expiresAt !== null && Date.parse(v.expiresAt) <= now);
     // A copy that expires (it was demoted) takes its whole hidden promotion ancestry with it, or an ancestor would reappear.
     const parent = new Map((this.db.query("SELECT id, promoted_from FROM entries WHERE promoted_from IS NOT NULL").all() as { id: string; promoted_from: string }[]).map((r) => [r.id, r.promoted_from]));
     const gone = new Set<string>();
@@ -583,6 +739,7 @@ export class MemoryStore {
 
   /** Index deferred writes before any note, goal or suggestion read. */
   private ensureFresh(): void {
+    if (this.generationIndex) { this.generationIndex.refresh(); return; }
     // Another process (a CLI, another project's hub, a sync) may have written since this one last read the segments.
     if (this.stale || this.shape() !== this.seen) try { this.stale = false; this.refresh(); } catch { this.stale = true; /* still busy: the next read tries again */ }
   }
@@ -591,9 +748,9 @@ export class MemoryStore {
    * What a read sees: rows that expired and promotions that became due while the store sat idle are settled first, so a
    * read, and the index after it, never differ from a rebuild.
    */
-  private live(): View[] {
+  private live(selection?: Filter): View[] {
     this.ensureFresh();
-    this.prune(); this.promoteHeld(); return this.views();
+    this.prune(); this.promoteHeld(); return this.views(false, selection);
   }
   /** A write whose index update failed: the next read refreshes first. */
   private stale = false;
@@ -601,7 +758,7 @@ export class MemoryStore {
   /** Entries visible from `project` (its own, and `shared` ones of any project), newest first, filtered. */
   list(f: Filter = {}): View[] {
     const q = f.q?.toLowerCase().split(/\s+/).filter(Boolean) ?? [];
-    return this.live().filter((v) => (!f.project || v.project === f.project || v.scope === "shared") && (!f.tier || v.tier === f.tier) && (!f.kind || v.kind === f.kind)
+    return this.live(f).filter((v) => (!f.project || v.project === f.project || v.scope === "shared") && (!f.tier || v.tier === f.tier) && (!f.kind || v.kind === f.kind)
       && (!f.peer || v.peer === f.peer) && (!f.machine || v.machine === f.machine) && (!f.since || Date.parse(v.at) >= Date.parse(f.since)) && (f.includeSuperseded || !v.supersededBy)
       && q.every((w) => `${v.title ?? ""}\n${v.text}\n${v.about.join(" ")}`.toLowerCase().includes(w)))
       .sort((a, b) => b.at.localeCompare(a.at) || a.id.localeCompare(b.id)).slice(0, f.limit ?? 200);
@@ -612,12 +769,13 @@ export class MemoryStore {
     id = id.replace(/^mem:/, ""); // briefs and recall print `mem:<id>`
     const all = this.live().filter((v) => !project || v.project === project || v.scope === "shared");
     const pick = <T extends { id: string }>(rows: T[]) => rows.find((v) => v.id === id) ?? (id.length >= 6 ? (() => { const m = rows.filter((v) => v.id.startsWith(id)); return m.length === 1 ? m[0] : undefined; })() : undefined);
+    if (this.generationIndex?.pruned.has(id)) return undefined;
     const found = pick(all);
     if (found) return found;
     // A short-term id an agent kept after its task was approved names the promoted copy now, here or on another machine
     // that has only the synced copy (which names its source).
     let at = pick(this.db.query("SELECT id FROM entries UNION SELECT promoted_from FROM entries WHERE promoted_from IS NOT NULL").all() as { id: string }[])?.id;
-    for (let copy = at; copy; copy = (this.db.query("SELECT id FROM entries WHERE promoted_from = ?").get(copy) as { id: string } | null)?.id) at = copy;
+    for (let copy = at; copy; copy = (this.db.query("SELECT id FROM entries WHERE promoted_from = ?").get(copy) as { id: string } | null)?.id) { if (this.generationIndex?.pruned.has(copy)) return undefined; at = copy; }
     return at ? all.find((v) => v.id === at) : undefined;
   }
 
@@ -652,12 +810,15 @@ 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 {
+    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 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");
     const taskNode = (key: string) => `task:${key}`; // a link's task key is the task node's own (id and proposal time)
     const node = (id: Node) => {
+      if (id.startsWith("mem:") && this.generationIndex?.pruned.has(id.slice(4))) return false;
       if (nodes.has(id) || nodes.size >= cap) return nodes.has(id);
       const v = live.get(id), g = goals.get(id);
       nodes.set(id, v ? { id, type: "memory", label: (v.title ?? v.text).slice(0, 60), kind: v.kind, tier: v.tier } : g ? { id, type: "goal", label: g.title.slice(0, 60), kind: g.state } : { id, type: id.slice(0, id.indexOf(":")), label: id.slice(id.indexOf(":") + 1) });
@@ -792,10 +953,18 @@ export class MemoryStore {
     });
   }
 
+  /** Person-local diagnostic receipt; malformed legacy bodies are never included. */
+  bridgeStatus(): { skippedRows: number } | undefined {
+    return this.generationIndex ? { skippedRows: this.generationIndex.skippedRows() } : undefined;
+  }
+
   /** What the segments hold, for `ahub memory` and the dashboard header. */
   counts(project?: string): { short: number; long: number; segments: number; machine: Machine } {
     const all = this.list({ ...(project ? { project } : {}), limit: Number.MAX_SAFE_INTEGER, includeSuperseded: true });
-    return { short: all.filter((v) => v.tier === "short").length, long: all.filter((v) => v.tier === "long").length, segments: this.segments("log").length + this.segments("local").length, machine: this.machine };
+    const segments = this.generationIndex
+      ? (this.db.query("SELECT COUNT(*) AS n FROM generation_segments").get() as { n: number }).n
+      : this.segments("log").length + this.segments("local").length;
+    return { short: all.filter((v) => v.tier === "short").length, long: all.filter((v) => v.tier === "long").length, segments, machine: this.machine };
   }
 
   /** The index's rows in a fixed order: what a rebuild must reproduce. */
@@ -803,3 +972,33 @@ export class MemoryStore {
     return JSON.stringify(["entries", "ops", "edges", "goals"].map((t) => this.db.query(`SELECT * FROM ${t} ORDER BY 1, 2`).all()));
   }
 }
+
+/** Migration builds only its generation-owned index over exact captured source prefixes. */
+export function buildGenerationIndex(profile: BoundProfile, sources: readonly LegacyCheckpoint[], legacyCommit?: string): void {
+  const store = new MemoryStore({ deferPromotions: true }, { token: MIGRATION_BOOTSTRAP, profile, limits: sources, ...(legacyCommit ? { commit: legacyCommit } : {}) });
+  try { const before = store.derivedTables(); store.rebuild(); if (!isDeepStrictEqual(before, store.derivedTables())) throw new Error("generation rebuild differs from incremental index"); }
+  finally { store.close(); }
+}
+
+/** Person-only migration receipt; this inspector reads raw rows without opening a store or writing any index. */
+export function summarizeRawExpiry(rawLines: string[], now: number, tailBytes: number): import("./migrate.ts").MigrationCounts {
+  const bytes = Buffer.from(rawLines.filter(Boolean).join("\n") + (rawLines.length ? "\n" : ""));
+  let malformed = 0;
+  const rows = legacyEntries([{ source: "legacy-local", path: "log/inspection.jsonl", bytes, offset: bytes.length, hash: createHash("sha256").update(bytes).digest("hex"), local: false, tailBytes: 0 }], { onMalformed: () => malformed++ });
+  const byOp: Record<string, number> = {}, byTier: Record<string, number> = {};
+  for (const row of rows) { byOp[row.op] = (byOp[row.op] ?? 0) + 1; if (row.op === "note") byTier[row.tier] = (byTier[row.tier] ?? 0) + 1; }
+  // Explicit proof eligibility is shared with prune planning; implicit TTL is reported but never used as a prune proof.
+  const located = rows.map(row => ({ row, placement: "local" as const, publicWitness: false }));
+  const explicit = explicitExpirySnapshot(located).filter(e => Date.parse(e.expiredAt) <= now);
+  const proved = new Map(explicitExpirySnapshot(located).map(e => [e.targetId, e.expiredAt]));
+  const settled = new Set(rows.flatMap(e => e.op === "settle" ? [e.target] : []));
+  const expiredRows = rows.filter(row => {
+    if (row.op !== "note") return false;
+    const fixed = proved.get(row.id);
+    if (fixed) return Date.parse(fixed) <= now;
+    if (row.tier !== "short" || row.task && settled.has(row.task) && PROMOTED_KINDS.includes(row.kind)) return false;
+    // Diagnostic only, at the CLI's default TTL. Such derived expiry is never a durable-prune witness.
+    return Date.parse(row.at) + (row.task ? UNSETTLED_MS : DEFAULT_TTL_MS) <= now;
+  }).length;
+  return { validRows: rows.length, expiredRows, eligibleRows: explicit.length, skippedRows: malformed, tailBytes, byOp, byTier };
+}

package/src/memory/sync.ts

@@ -1,7 +1,9 @@
 import { closeSync, existsSync, openSync, readFileSync, rmSync, writeFileSync, writeSync } from "node:fs";
 import { join } from "node:path";
 import { memoryGitArgv, memoryGitEnv, processLiveness, processSignature } from "./platform.ts";
+import { acquireMutation } from "./mutation.ts";
 import type { MemoryStore } from "./store.ts";
+import { syncGenerationMemory } from "./generation-sync.ts";
 
 /**
  * #258 phase 2: hub memory between a person's machines through a git remote they configure. The memory directory is a
@@ -28,6 +30,26 @@ async function git(dir: string, args: string[], signal?: AbortSignal, ms = STEP_
   } finally { clearTimeout(timer); if (hard) clearTimeout(hard); signal?.removeEventListener("abort", kill); }
 }
 
+export { git as syncGit };
+
+/** Generation-only process isolation; shared-v1 above retains its pre-P9 spawn and environment contract. */
+export async function generationSyncGit(dir: string, args: string[], signal?: AbortSignal, ms = STEP_MS): Promise<{ code: number; out: string; err: string }> {
+  if (signal?.aborted) return { code: -1, out: "", err: "stopped" };
+  // A fixed child-only umask keeps Git-created metadata private without changing the daemon's process umask.
+  // Args are positional shell parameters, never interpolated or evaluated as shell code.
+  const p = Bun.spawn(["/bin/sh", "-c", 'umask 077; exec "$@"', "amem-git", ...memoryGitArgv(["-C", dir, ...args], { credentials: true })], { stdout: "pipe", stderr: "pipe", stdin: "ignore", env: memoryGitEnv(process.env, { repositoryIsolation: true }) });
+  // SIGTERM first, so git removes its lock files; SIGKILL only if it is still there after a grace period.
+  let hard: ReturnType<typeof setTimeout> | undefined;
+  const kill = () => { p.kill("SIGTERM"); hard ??= setTimeout(() => p.kill("SIGKILL"), 2_000); };
+  const timer = setTimeout(kill, ms);
+  signal?.addEventListener("abort", kill, { once: true });
+  try {
+    const [code, out, err] = await Promise.all([p.exited, new Response(p.stdout).text(), new Response(p.stderr).text()]);
+    return { code, out: out.trim(), err: err.trim() };
+  } finally { clearTimeout(timer); if (hard) clearTimeout(hard); signal?.removeEventListener("abort", kill); }
+}
+
+
 /** GitHub remotes are asked through `gh`; any other host, or a `gh` that cannot answer, is unknown. */
 export async function remoteVisibility(url: string): Promise<Visibility> {
   const repo = /github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?\/?$/.exec(url)?.[1];
@@ -71,6 +93,7 @@ export interface SyncOptions {
 }
 
 export async function syncMemory(store: MemoryStore, opts: SyncOptions = {}): Promise<SyncResult> {
+  if (store.profile.kind === "generation") return syncGenerationMemory(store, opts);
   const dir = store.dir;
   const fail = (error: string): SyncResult => ({ ok: false, pushed: false, entries: 0, error });
   if (opts.signal?.aborted) return fail("stopped");
@@ -78,7 +101,10 @@ export async function syncMemory(store: MemoryStore, opts: SyncOptions = {}): Pr
   if (!opts.remote && !existsSync(join(dir, ".git"))) return fail(noRemote); // never set up: nothing to do, nothing created
   const release = lock(dir);
   if (!release) return fail("another sync is running on this machine");
+  let releaseMutation: (() => void) | undefined;
   try {
+    releaseMutation = acquireMutation(dir);
+    if (!releaseMutation) return fail("another memory mutation is running on this machine");
     // Holding sync.lock, no other git runs in this repository: what a killed one left behind is stale.
     rmSync(join(dir, ".git", "index.lock"), { force: true });
     if (existsSync(join(dir, ".git", "MERGE_HEAD"))) await git(dir, ["merge", "--abort"]);
@@ -136,9 +162,11 @@ export async function syncMemory(store: MemoryStore, opts: SyncOptions = {}): Pr
       pushed = true;
     }
     if (opts.signal?.aborted) return fail("stopped");
-    store.refresh();
-    return { ok: true, pushed, entries: store.counts().long, ...(warning ? { warning } : {}) };
+    return store.withDeferredPromotions(() => {
+      store.refresh();
+      return { ok: true, pushed, entries: store.counts().long, ...(warning ? { warning } : {}) };
+    });
   } catch (e) {
     return fail((e as Error).message.slice(0, 200));
-  } finally { release(); }
+  } finally { try { releaseMutation?.(); } finally { release(); } }
 }