@staix/agent-mem 0.2.0 → 0.3.0

package/src/memory/prune.ts

@@ -0,0 +1,259 @@
+import { canonicalJSON, hashJSON, validGeneration } from "./generation.ts";
+import { entryId, type Entry, type NoteEntry } from "./store.ts";
+
+export const PRUNE_ROW_MAX_BYTES = 16_384, PRUNE_PLAN_MAX_BYTES = 262_144;
+export const PRUNE_ROW_MAX_TARGETS = 32, PRUNE_PLAN_MAX_ROWS = 16, PRUNE_PLAN_MAX_TARGETS = 256;
+export type PrunePlacement = "local" | "synced";
+export interface PruneTarget {
+  id: string; rowHash: string; expiredAt: string;
+  basis: { kind: "note" | "demote" | "settle"; id: string; rowHash: string };
+}
+export interface PruneRow {
+  schema: "agent-mem.prune/v1"; op: "prune"; generation: string; at: string; machine: string; actor: "person";
+  placement: PrunePlacement; cutoff: string; targets: PruneTarget[]; id: string;
+}
+export interface PrunePlan {
+  schema: "agent-mem.prune-plan/v1"; generation: string; selectorRevision: string; project: string; policyRevision: string;
+  rows: { placement: PrunePlacement; payload: PruneRow }[];
+  counts: { eligible: number; selected: number; local: number; synced: number }; hasMore: boolean; seal: string;
+}
+export interface PruneSourceRow { row: Entry; placement: PrunePlacement; publicWitness: boolean; own?: boolean; legacy?: boolean }
+export interface PruneExpiry { targetId: string; basisId: string; expiredAt: string }
+export interface PruneSnapshot {
+  rows: readonly PruneSourceRow[];
+  /** Effective, explicit serialized deadlines only; implicit TTL/backstop expiry is never eligible. */
+  expiries: readonly PruneExpiry[];
+  pruned?: readonly string[];
+  durablePruneIds?: readonly string[];
+}
+export interface PruneStorePort {
+  generation: string; machine: string;
+  selectorRevision(): string;
+  now(): number;
+  snapshot(): PruneSnapshot;
+  withMutation<T>(work: () => T): T;
+  /** Must persist/fsync exactly this local plan before append, refusing mismatched existing journals. */
+  persistPrunePlan(plan: PrunePlan): void;
+  /** Must fsync complete bytes; resume only an exact persisted-plan prefix, never rewrite a complete line. */
+  appendPrune(row: PruneRow, line: string, planSeal: string): "written" | "already-durable";
+  refresh(): void;
+}
+export interface PrunePolicyBinding { generation: string; project: string; payloadHash: string; policyRevision: string }
+export interface PruneAuthorization {
+  project: string; actor: "person" | "agent";
+  /** The host authenticates intent. Neither this boolean nor actor is an authentication token. */
+  authorize: () => boolean;
+  policy?: {
+    revision: () => string;
+    classify: (row: PruneSourceRow) => "public" | "private" | "unknown";
+    attest: (binding: PrunePolicyBinding) => boolean;
+  };
+}
+const bytes = (value: unknown) => Buffer.byteLength(canonicalJSON(value), "utf8");
+const fullId = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{32}$/.test(value);
+const sha = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+const revision = (value: unknown): value is string => value === "absent" || sha(value);
+const utc = (value: unknown): value is string => typeof value === "string" && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+const object = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+const exact = (value: Record<string, unknown>, keys: readonly string[]) => Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+const fail = (): never => { throw new Error("prune unavailable: invalid, unavailable or withheld request"); };
+function guard(condition: unknown): asserts condition { if (!condition) fail(); }
+/** Full canonical authored row INCLUDING id, unlike the v1 entry-id hash which excludes id. */
+export const pruneRowHash = (row: Entry): string => hashJSON(row);
+export const prunePayloadHash = (row: PruneRow): string => hashJSON(row);
+export function pruneId(row: Omit<PruneRow, "id">): string { return hashJSON(row).slice(0, 32); }
+function protectedCall<T>(work: () => T): T { try { return work(); } catch { return fail(); } }
+
+export function validatePruneRow(input: unknown, generation?: string, placement?: PrunePlacement): PruneRow {
+  return protectedCall(() => {
+    guard(object(input) && bytes(input) <= PRUNE_ROW_MAX_BYTES);
+    const row = input as Record<string, unknown>;
+    guard(exact(row, ["schema", "op", "generation", "at", "machine", "actor", "placement", "cutoff", "targets", "id"]));
+    guard(row.schema === "agent-mem.prune/v1" && row.op === "prune" && validGeneration(row.generation) && utc(row.at) && utc(row.cutoff));
+    guard(typeof row.machine === "string" && /^[a-f0-9]{16}$/.test(row.machine) && row.actor === "person" && ["local", "synced"].includes(String(row.placement)));
+    guard((generation === undefined || row.generation === generation) && (placement === undefined || row.placement === placement));
+    guard(String(row.cutoff) <= String(row.at));
+    guard(Array.isArray(row.targets) && row.targets.length >= 1 && row.targets.length <= PRUNE_ROW_MAX_TARGETS);
+    let previous = "";
+    for (const value of row.targets as unknown[]) {
+      guard(object(value) && exact(value, ["id", "rowHash", "expiredAt", "basis"]));
+      const target = value as Record<string, unknown>, basis = target.basis;
+      guard(fullId(target.id) && sha(target.rowHash) && utc(target.expiredAt) && target.id > previous && String(target.expiredAt) <= String(row.cutoff));
+      guard(object(basis) && exact(basis, ["kind", "id", "rowHash"]) && ["note", "demote", "settle"].includes(String(basis.kind)) && fullId(basis.id) && sha(basis.rowHash));
+      previous = target.id as string;
+    }
+    guard(fullId(row.id));
+    const { id, ...body } = row;
+    guard(pruneId(body as Omit<PruneRow, "id">) === id);
+    return structuredClone(row) as unknown as PruneRow;
+  });
+}
+function sources(snapshot: PruneSnapshot): Map<string, PruneSourceRow> {
+  const result = new Map<string, PruneSourceRow>();
+  for (const source of snapshot.rows) {
+    const row = source.row, previous = result.get(row.id);
+    guard(fullId(row.id) && utc(row.at) && row.schema === "agent-hub.memory/v1");
+    const { id, ...body } = row;
+    guard(entryId(body) === id);
+    guard(!previous || canonicalJSON(previous.row) === canonicalJSON(row));
+    // Any verified public occurrence establishes provenance; local-only occurrences never establish it.
+    if (!previous || source.publicWitness && source.placement === "synced") result.set(row.id, source);
+  }
+  return result;
+}
+function proof(target: PruneTarget, row: PruneRow, all: Map<string, PruneSourceRow>): "valid" | "pending" | "invalid" {
+  const note = all.get(target.id)?.row, basis = all.get(target.basis.id)?.row;
+  if (!note || !basis) return "pending";
+  if (note.op !== "note" || pruneRowHash(note) !== target.rowHash || pruneRowHash(basis) !== target.basis.rowHash || note.at > row.cutoff || basis.at > row.cutoff || basis.op !== target.basis.kind) return "invalid";
+  if (basis.op === "note") return basis.id === note.id && utc(basis.expires) && basis.expires === target.expiredAt ? "valid" : "invalid";
+  if (basis.op === "demote") return basis.target === note.id && utc(basis.by) && basis.by === target.expiredAt ? "valid" : "invalid";
+  if (basis.op === "settle") return !!note.task && basis.target === note.task && utc(basis.by) && basis.by === target.expiredAt ? "valid" : "invalid";
+  return "invalid";
+}
+/** Pure exact-entry reducer. No clock, writer policy, ancestry traversal, append or mutation occurs here. */
+export function reducePruneRows(rows: readonly { row: unknown; placement: PrunePlacement }[], snapshot: PruneSnapshot, generation: string): { targets: Set<string>; pending: string[]; invalid: number } {
+  const targets = new Set<string>(), pending: string[] = [];
+  let invalid = 0;
+  const all = sources(snapshot);
+  for (const input of rows) {
+    let row: PruneRow;
+    try { row = validatePruneRow(input.row, generation, input.placement); } catch { invalid++; continue; }
+    const states = row.targets.map(target => proof(target, row, all));
+    if (states.includes("invalid")) { invalid++; continue; }
+    if (states.includes("pending")) { pending.push(row.id); continue; }
+    if (row.placement === "synced" && row.targets.some(target => [target.id, target.basis.id].some(id => !all.get(id)?.publicWitness || all.get(id)?.placement !== "synced"))) { invalid++; continue; }
+    for (const target of row.targets) targets.add(target.id);
+  }
+  return { targets, pending: [...new Set(pending)].sort(), invalid };
+}
+function authenticate(port: PruneStorePort, auth: PruneAuthorization): void {
+  guard(validGeneration(port.generation) && /^[a-f0-9]{16}$/.test(port.machine) && revision(port.selectorRevision()));
+  guard(auth.actor === "person" && typeof auth.authorize === "function" && auth.authorize() === true && typeof auth.project === "string" && auth.project.length > 0);
+}
+function policyRevision(auth: PruneAuthorization): string {
+  if (!auth.policy) return "local-only";
+  const current = auth.policy.revision();
+  guard(typeof current === "string" && current.length > 0 && Buffer.byteLength(current, "utf8") <= 1024 && current !== "local-only");
+  return current;
+}
+function visible(note: NoteEntry, project: string): boolean { return note.project === project || note.scope === "shared"; }
+function targetFor(id: string, snapshot: PruneSnapshot, all: Map<string, PruneSourceRow>, cutoff: string, project: string): PruneTarget | undefined {
+  const found = all.get(id), expiry = snapshot.expiries.find(item => item.targetId === id);
+  if (!found || found.row.op !== "note" || !visible(found.row, project) || !expiry || !utc(expiry.expiredAt) || expiry.expiredAt > cutoff) return undefined;
+  const basis = all.get(expiry.basisId)?.row;
+  if (!basis || !["note", "demote", "settle"].includes(basis.op)) return undefined;
+  const target: PruneTarget = { id, rowHash: pruneRowHash(found.row), expiredAt: expiry.expiredAt, basis: { kind: basis.op as "note" | "demote" | "settle", id: basis.id, rowHash: pruneRowHash(basis) } };
+  const shell = { cutoff } as PruneRow;
+  return proof(target, shell, all) === "valid" ? target : undefined;
+}
+function placementFor(target: PruneTarget, all: Map<string, PruneSourceRow>, auth: PruneAuthorization): PrunePlacement {
+  if (!auth.policy) return "local";
+  const sources = [all.get(target.id)!, all.get(target.basis.id)!];
+  const verdicts = sources.map(source => auth.policy!.classify(structuredClone(source)));
+  guard(verdicts.every(value => ["public", "private", "unknown"].includes(value)));
+  return sources.every(source => source.placement === "synced" && source.publicWitness) && verdicts.every(verdict => verdict === "public") ? "synced" : "local";
+}
+function attest(row: PruneRow, auth: PruneAuthorization, expectedRevision: string): void {
+  guard(policyRevision(auth) === expectedRevision);
+  if (row.placement === "synced") guard(!!auth.policy && auth.policy.attest({ generation: row.generation, project: auth.project, payloadHash: prunePayloadHash(row), policyRevision: expectedRevision }) === true);
+  guard(policyRevision(auth) === expectedRevision);
+}
+function sealPlan(plan: Omit<PrunePlan, "seal">): PrunePlan { return { ...plan, seal: hashJSON(plan) }; }
+function checkPlanSize(plan: PrunePlan): boolean { return bytes(plan) <= PRUNE_PLAN_MAX_BYTES && plan.rows.length <= PRUNE_PLAN_MAX_ROWS && plan.counts.selected <= PRUNE_PLAN_MAX_TARGETS; }
+
+export function planPrune(port: PruneStorePort, input: { cutoff: string; targets?: readonly string[] }, auth: PruneAuthorization): PrunePlan {
+  return protectedCall(() => {
+    authenticate(port, auth); guard(utc(input.cutoff) && input.cutoff <= new Date(port.now()).toISOString());
+    const explicit = input.targets !== undefined;
+    if (explicit) guard(Array.isArray(input.targets) && input.targets!.length >= 1 && input.targets!.length <= PRUNE_PLAN_MAX_TARGETS && input.targets!.every(fullId) && new Set(input.targets).size === input.targets!.length);
+    const snapshot = port.snapshot(), all = sources(snapshot), already = new Set(snapshot.pruned ?? []);
+    const ids = explicit ? [...input.targets!] : snapshot.expiries.map(expiry => expiry.targetId).filter(id => !already.has(id));
+    const candidates: { target: PruneTarget; placement: PrunePlacement }[] = [];
+    for (const id of [...new Set(ids)].sort()) {
+      const target = targetFor(id, snapshot, all, input.cutoff, auth.project);
+      if (!target || already.has(id)) { if (explicit) fail(); else continue; }
+      guard(target !== undefined);
+      candidates.push({ target, placement: placementFor(target, all, auth) });
+    }
+    const currentPolicy = policyRevision(auth), selector = port.selectorRevision(), at = new Date(port.now()).toISOString();
+    const build = (selected: typeof candidates): PrunePlan => {
+      const rows: PrunePlan["rows"] = [];
+      for (const placement of ["local", "synced"] as const) {
+        const targets = selected.filter(item => item.placement === placement).map(item => item.target);
+        for (let index = 0; index < targets.length; index += PRUNE_ROW_MAX_TARGETS) {
+          const body: Omit<PruneRow, "id"> = { schema: "agent-mem.prune/v1", op: "prune", generation: port.generation, at, machine: port.machine, actor: "person", placement, cutoff: input.cutoff, targets: targets.slice(index, index + PRUNE_ROW_MAX_TARGETS) };
+          const payload = validatePruneRow({ ...body, id: pruneId(body) }); rows.push({ placement, payload });
+        }
+      }
+      return sealPlan({ schema: "agent-mem.prune-plan/v1", generation: port.generation, selectorRevision: selector, project: auth.project, policyRevision: currentPolicy, rows,
+        counts: { eligible: candidates.length, selected: selected.length, local: selected.filter(item => item.placement === "local").length, synced: selected.filter(item => item.placement === "synced").length }, hasMore: selected.length < candidates.length });
+    };
+    let selected = candidates.slice(0, PRUNE_PLAN_MAX_TARGETS), plan = build(selected);
+    while (!checkPlanSize(plan) && selected.length) { if (explicit) fail(); selected = selected.slice(0, -1); plan = build(selected); }
+    guard(checkPlanSize(plan));
+    for (const row of plan.rows) attest(row.payload, auth, currentPolicy);
+    guard(port.selectorRevision() === selector && policyRevision(auth) === currentPolicy);
+    return plan;
+  });
+}
+
+export function validatePrunePlan(input: unknown): PrunePlan {
+  return protectedCall(() => {
+    if (typeof input === "string") { guard(Buffer.byteLength(input, "utf8") <= PRUNE_PLAN_MAX_BYTES); input = JSON.parse(input); }
+    guard(object(input) && bytes(input) <= PRUNE_PLAN_MAX_BYTES);
+    const p = input as Record<string, unknown>;
+    guard(exact(p, ["schema", "generation", "selectorRevision", "project", "policyRevision", "rows", "counts", "hasMore", "seal"]));
+    guard(p.schema === "agent-mem.prune-plan/v1" && validGeneration(p.generation) && revision(p.selectorRevision) && typeof p.project === "string" && p.project.length > 0 && typeof p.policyRevision === "string" && p.policyRevision.length > 0 && typeof p.hasMore === "boolean" && sha(p.seal));
+    guard(Array.isArray(p.rows) && p.rows.length <= PRUNE_PLAN_MAX_ROWS && object(p.counts) && exact(p.counts, ["eligible", "selected", "local", "synced"]));
+    const counts = p.counts as Record<string, unknown>;
+    guard(Object.values(counts).every(value => Number.isSafeInteger(value) && Number(value) >= 0));
+    let total = 0, local = 0, previous = "";
+    const seen = new Set<string>();
+    for (const value of p.rows as unknown[]) {
+      guard(object(value) && exact(value, ["placement", "payload"]) && ["local", "synced"].includes(String(value.placement)));
+      const row = validatePruneRow(value.payload, p.generation as string, value.placement as PrunePlacement);
+      const order = `${row.placement === "local" ? "0" : "1"}:${row.targets[0]!.id}`; guard(order > previous); previous = order;
+      for (const target of row.targets) { guard(!seen.has(target.id)); seen.add(target.id); }
+      total += row.targets.length; if (row.placement === "local") local += row.targets.length;
+    }
+    guard(total <= PRUNE_PLAN_MAX_TARGETS && total === counts.selected && local === counts.local && total - local === counts.synced && Number(counts.eligible) >= total && p.hasMore === (Number(counts.eligible) > total));
+    const { seal, ...body } = p; guard(hashJSON(body) === seal);
+    return structuredClone(p) as unknown as PrunePlan;
+  });
+}
+export function applyPrune(port: PruneStorePort, input: unknown, auth: PruneAuthorization): { completed: string[] } {
+  return protectedCall(() => {
+    authenticate(port, auth);
+    const plan = validatePrunePlan(input);
+    return port.withMutation(() => {
+      authenticate(port, auth);
+      guard(plan.generation === port.generation && plan.project === auth.project && plan.selectorRevision === port.selectorRevision() && plan.policyRevision === policyRevision(auth));
+      const verify = () => {
+        const snapshot = port.snapshot(), all = sources(snapshot), durable = new Set(snapshot.durablePruneIds ?? []);
+        for (const item of plan.rows) {
+          guard(item.payload.machine === port.machine);
+          if (durable.has(item.payload.id)) continue;
+          for (const target of item.payload.targets) {
+            const current = targetFor(target.id, snapshot, all, item.payload.cutoff, auth.project);
+            guard(!!current && canonicalJSON(current) === canonicalJSON(target) && placementFor(target, all, auth) === item.placement);
+          }
+          guard(item.payload.at <= new Date(port.now()).toISOString());
+          attest(item.payload, auth, plan.policyRevision);
+        }
+        guard(plan.selectorRevision === port.selectorRevision() && plan.policyRevision === policyRevision(auth));
+        return durable;
+      };
+      verify(); verify(); // A policy callback can mutate external state; re-read immutable proofs before effects.
+      port.persistPrunePlan(plan);
+      const completed: string[] = [];
+      for (const item of plan.rows) {
+        verify();
+        // Parsed complete bytes are not proof of a successful fsync; the backend must reconfirm durability.
+        port.appendPrune(item.payload, canonicalJSON(item.payload) + "\n", plan.seal);
+        completed.push(item.payload.id);
+      }
+      port.refresh();
+      return { completed };
+    });
+  });
+}

package/src/memory/store.ts

@@ -5,6 +5,12 @@ 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
@@ -174,10 +180,16 @@ 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; deferPromotions?: boolean }
+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;
@@ -186,8 +198,16 @@ export class MemoryStore {
   private readonly log: (line: string) => void;
   private readonly deferPromotions: boolean;
 
-  constructor(opts: StoreOptions = {}) {
-    this.dir = opts.home === undefined ? memoryHome() : join(opts.home, "memory");
+  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
@@ -216,9 +236,24 @@ export class MemoryStore {
     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();
   }
 
+  /** 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. */
@@ -271,8 +306,11 @@ export class MemoryStore {
   }
 
   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.
@@ -291,10 +329,13 @@ 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);
     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 };
@@ -378,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.
@@ -406,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;
@@ -423,9 +469,12 @@ export class MemoryStore {
     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 */ }
         }
@@ -435,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.
@@ -496,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();
   }
@@ -549,17 +600,29 @@ export class MemoryStore {
 
   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 op, at, target, by FROM ops ORDER BY at, id").all() as { op: string; at: string; target: string; by: 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); } };
@@ -572,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);
@@ -616,7 +681,7 @@ export class MemoryStore {
       const hidden: string[] = [], expiredIds: string[] = [];
       for (const r of rows) {
         const id = r.id!;
-        if (forgotten.has(id) || (r.promoted_from && forgotten.has(r.promoted_from)) || promoted.has(id)) { hidden.push(id); continue; }
+        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);
       }
@@ -644,7 +709,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 (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;
@@ -660,6 +725,7 @@ 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, 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.
@@ -673,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 */ }
   }
@@ -702,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;
   }
 
@@ -742,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) });
@@ -882,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. */
@@ -893,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

@@ -3,6 +3,7 @@ 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
@@ -29,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];
@@ -72,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");