@staix/agent-mem 0.2.0 → 0.3.1

package/src/memory/generation-index.ts

@@ -0,0 +1,245 @@
+import type { Database } from "bun:sqlite";
+import { createHash } from "node:crypto";
+import { closeSync, constants, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { canonicalJSON, fsyncDirectory, readProfileJSON, selectorRevision, writeProfileJSON, type BoundProfile } from "./generation.ts";
+import { legacyEntries, legacyHead, readLegacySnapshot, SegmentReader, type LegacyCheckpoint, type LegacySegment } from "./bridge.ts";
+import { reducePruneRows, validatePruneRow, type PrunePlan, type PruneRow, type PruneSnapshot, type PruneSourceRow, type PruneStorePort } from "./prune.ts";
+import { PROMOTED_KINDS, type Entry } from "./store.ts";
+
+const digest = (bytes: Uint8Array) => createHash("sha256").update(bytes).digest("hex");
+const fail = (): never => { throw new Error("generation input unavailable or changed; person inspection required"); };
+export const GENERATION_TABLES = ["generation_rows", "generation_prunes", "generation_targets", "generation_segments", "generation_state"] as const;
+export interface GenerationIndexOptions {
+  profile: BoundProfile; db: Database; now: () => number;
+  apply: (line: string, source: string) => void;
+  withMutation: <T>(work: () => T) => T;
+  limits?: readonly LegacyCheckpoint[]; commit?: string;
+}
+/** Pure deadline summary shared by migration and prune: no live index or host TTL is a proof. */
+export function explicitExpirySnapshot(rows: readonly PruneSourceRow[]): PruneSnapshot["expiries"] {
+  const ops = rows.filter(source => source.row.op !== "note" && source.row.op !== "goal").sort((a, b) => a.row.at.localeCompare(b.row.at) || a.row.id.localeCompare(b.row.id));
+  const demotes = new Map<string, Entry>(), settles = new Map<string, Entry>();
+  const forgotten = new Set(ops.flatMap(({ row }) => row.op === "forget" ? [row.target] : []));
+  for (const source of ops) {
+    const op = source.row;
+    if (op.op === "demote") demotes.set(op.target, op);
+    if (op.op === "settle") {
+      const realms = [...(source.own === true ? [true] : []), ...((source.legacy ?? source.own !== true) ? [false] : [])];
+      for (const own of realms) { const task = `${own}:${op.target}`; if (!settles.has(task)) settles.set(task, op); }
+    }
+  }
+  return rows.flatMap(({ row, own }) => {
+    if (row.op !== "note" || forgotten.has(row.id)) return [];
+    const demote = demotes.get(row.id);
+    if (row.tier !== "short" && !demote) return [];
+    const settled = row.task ? settles.get(`${own === true}:${row.task}`) : undefined;
+    // A held decision/contract/fail waits for promotion, not expiry, unless explicitly demoted or dated.
+    if (row.tier === "short" && !demote && !row.expires && settled && PROMOTED_KINDS.includes(row.kind)) return [];
+    const basis = demote ?? (row.expires ? row : settled);
+    const expiredAt = basis?.op === "note" ? basis.expires : basis && "by" in basis ? basis.by : undefined;
+    if (!basis || !expiredAt || !Number.isFinite(Date.parse(expiredAt)) || new Date(expiredAt).toISOString() !== expiredAt) return [];
+    return [{ targetId: row.id, basisId: basis.id, expiredAt }];
+  });
+}
+
+/** Generation-owned derived state. Legacy files are inputs, never opened as a MemoryStore. */
+export class GenerationIndex {
+  readonly profile: BoundProfile;
+  pruned = new Set<string>();
+  private readonly reader = new SegmentReader();
+  private fullCapture = false;
+  private replayProvenance = false;
+  constructor(private readonly options: GenerationIndexOptions) {
+    this.profile = options.profile;
+    const db = options.db;
+    db.run("CREATE TABLE IF NOT EXISTS generation_rows (id TEXT PRIMARY KEY, line TEXT NOT NULL, local INTEGER NOT NULL, public INTEGER NOT NULL, own INTEGER NOT NULL, legacy INTEGER NOT NULL)");
+    if (!(db.query("PRAGMA table_info(generation_rows)").all() as { name: string }[]).some(row => row.name === "legacy")) { db.run("ALTER TABLE generation_rows ADD COLUMN legacy INTEGER NOT NULL DEFAULT 0"); this.replayProvenance = true; }
+    db.run("CREATE TABLE IF NOT EXISTS generation_prunes (id TEXT PRIMARY KEY, line TEXT NOT NULL, local INTEGER NOT NULL)");
+    db.run("CREATE TABLE IF NOT EXISTS generation_targets (id TEXT PRIMARY KEY)");
+    db.run("CREATE TABLE IF NOT EXISTS generation_segments (source TEXT NOT NULL, path TEXT NOT NULL, offset INTEGER NOT NULL, hash TEXT NOT NULL, commit_id TEXT, stamp TEXT, PRIMARY KEY(source,path))");
+    if (!(db.query("PRAGMA table_info(generation_segments)").all() as { name: string }[]).some(row => row.name === "stamp")) db.run("ALTER TABLE generation_segments ADD COLUMN stamp TEXT");
+    db.run("CREATE TABLE IF NOT EXISTS generation_state (key TEXT PRIMARY KEY, value TEXT NOT NULL)");
+  }
+  private ownSegments(): LegacySegment[] {
+    const prior = this.options.db.query("SELECT source,path,offset,hash,commit_id,stamp FROM generation_segments WHERE source='generation'").all() as (LegacyCheckpoint & { stamp: string | null })[];
+    return ["log", "local"].flatMap(folder => {
+      const dir = join(this.profile.dir, folder);
+      if (lstatSync(dir).isSymbolicLink() || !lstatSync(dir).isDirectory()) return fail();
+      return readdirSync(dir).sort().filter(name => name.endsWith(".jsonl")).map(name => {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*\.jsonl$/.test(name)) return fail();
+        const path = `${folder}/${name}`, checkpoint = prior.find(row => row.path === path);
+        const data = this.reader.read(join(dir, name), checkpoint ? { ...checkpoint, stamp: checkpoint.stamp ?? undefined } : undefined, this.fullCapture);
+        return { ...data, source: "generation", path, local: folder === "local" };
+      });
+    });
+  }
+  private capture(): { segments: LegacySegment[]; commit?: string } {
+    const db = this.options.db;
+    const previous = db.query("SELECT source,path,offset,hash,commit_id,stamp FROM generation_segments WHERE source != 'generation'").all() as (LegacyCheckpoint & { commit_id: string | null; stamp: string | null })[];
+    const initial = readProfileJSON(join(this.profile.dir, "migration-sources.json")) as { sources?: LegacyCheckpoint[]; legacyCommit?: string } | undefined;
+    const bySource = new Map((initial?.sources ?? []).map(row => [`${row.source}:${row.path}`, row]));
+    for (const { commit_id, stamp, ...row } of previous) bySource.set(`${row.source}:${row.path}`, { ...row, ...(stamp ? { stamp } : {}), ...(commit_id ? { commit: commit_id } : {}) });
+    const checkpoints = [...bySource.values()];
+    const persisted = new Set(previous.map(row => `${row.source}:${row.path}`));
+    const completeFrontier = checkpoints.every(row => persisted.has(`${row.source}:${row.path}`));
+    const prior = (db.query("SELECT value FROM generation_state WHERE key='legacyCommit'").get() as { value: string } | null)?.value ?? initial?.legacyCommit;
+    const commit = this.options.commit ?? legacyHead(this.profile.home, this.profile.generation!);
+    const legacy = readLegacySnapshot(this.profile.home, { generation: this.profile.generation, ...(commit ? { commit } : {}), checkpoints, ...(prior ? { previousCommit: prior } : {}), ...(this.options.limits ? { limits: this.options.limits } : {}), reader: this.reader, incremental: !this.fullCapture && !this.options.limits && completeFrontier });
+    const own = this.ownSegments();
+    for (const old of db.query("SELECT path,offset,hash FROM generation_segments WHERE source='generation'").all() as { path: string; offset: number; hash: string }[]) {
+      const segment = own.find(s => s.path === old.path);
+      if (!segment || segment.offset < old.offset) fail();
+    }
+    return { segments: [...legacy, ...own], ...(commit ? { commit } : {}) };
+  }
+  private index(captured: { segments: LegacySegment[]; commit?: string }): void {
+    const db = this.options.db;
+    for (const segment of captured.segments) {
+      const consumed = (db.query("SELECT offset FROM generation_segments WHERE source=? AND path=?").get(segment.source, segment.path) as { offset: number } | null)?.offset ?? 0;
+      if ((segment.start ?? 0) > consumed) return fail();
+      for (const line of segment.bytes.subarray(Math.max(0, consumed - (segment.start ?? 0))).toString("utf8").split("\n").filter(Boolean)) {
+        let parsed: unknown;
+        try { parsed = JSON.parse(line); } catch { if (segment.source === "generation") return fail(); this.recordSkipped(segment); continue; }
+        if (segment.source === "generation" && parsed && typeof parsed === "object" && (parsed as { op?: string }).op === "prune") {
+          const row = validatePruneRow(parsed, this.profile.generation, segment.local ? "local" : "synced");
+          if (segment.path !== `${segment.local ? "local" : "log"}/${row.machine}.jsonl`) fail();
+          db.query("INSERT OR IGNORE INTO generation_prunes VALUES (?,?,?)").run(row.id, canonicalJSON(row), Number(segment.local));
+          continue;
+        }
+        const bytes = Buffer.from(line + "\n");
+        const row = legacyEntries([{ ...segment, bytes, offset: bytes.length, hash: digest(bytes) }], { strict: segment.source === "generation", onMalformed: () => this.recordSkipped(segment) })[0];
+        if (!row) continue;
+        const canonical = canonicalJSON(row), old = db.query("SELECT line,own,legacy FROM generation_rows WHERE id=?").get(row.id) as { line: string; own: number; legacy: number } | null;
+        if (old && old.line !== canonical) fail();
+        this.options.apply(line, segment.path);
+        const local = segment.local || row.op === "settle" || row.op === "note" && row.tier === "short";
+        const publicWitness = !local && segment.source !== "legacy-local";
+        const own = segment.source === "generation", legacy = !own;
+        // Notes retain legacy birth when duplicated; ops can independently occur in both birth realms.
+        const ownPresence = old ? row.op === "note" ? !!old.own && own : !!old.own || own : own;
+        db.query("INSERT INTO generation_rows VALUES (?,?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET local=MIN(local,excluded.local), public=MAX(public,excluded.public), own=excluded.own, legacy=excluded.legacy")
+          .run(row.id, canonical, Number(local), Number(publicWitness), Number(ownPresence), Number(!!old?.legacy || legacy));
+      }
+      db.query("INSERT INTO generation_segments VALUES (?,?,?,?,?,?) ON CONFLICT(source,path) DO UPDATE SET offset=excluded.offset,hash=excluded.hash,commit_id=excluded.commit_id,stamp=excluded.stamp")
+        .run(segment.source, segment.path, segment.offset, segment.hash, segment.commit ?? null, segment.stamp ?? null);
+    }
+    if (captured.commit) db.query("INSERT INTO generation_state VALUES ('legacyCommit',?) ON CONFLICT(key) DO UPDATE SET value=excluded.value").run(captured.commit);
+    const snapshot = this.snapshot(false);
+    const prunes = (db.query("SELECT line,local FROM generation_prunes ORDER BY id").all() as { line: string; local: number }[]).map(row => ({ row: JSON.parse(row.line), placement: row.local ? "local" as const : "synced" as const }));
+    const reduced = reducePruneRows(prunes, snapshot, this.profile.generation!);
+    db.run("DELETE FROM generation_targets");
+    for (const id of [...reduced.targets].sort()) db.query("INSERT INTO generation_targets VALUES (?)").run(id);
+    this.pruned = reduced.targets;
+  }
+  private recordSkipped(segment: LegacySegment): void {
+    this.options.db.query("INSERT INTO generation_state VALUES (?,'1') ON CONFLICT(key) DO UPDATE SET value=CAST(CAST(value AS INTEGER)+1 AS TEXT)").run(`skipped:${segment.source}:${segment.path}`);
+  }
+  skippedRows(): number {
+    return (this.options.db.query("SELECT COALESCE(SUM(CAST(value AS INTEGER)),0) AS n FROM generation_state WHERE key LIKE 'skipped:%'").get() as { n: number }).n;
+  }
+  private frontier(): string {
+    const db = this.options.db;
+    return db.transaction(() => canonicalJSON({
+      segments: db.query("SELECT * FROM generation_segments ORDER BY source,path").all(),
+      state: db.query("SELECT * FROM generation_state ORDER BY key").all(),
+    })).deferred();
+  }
+  refresh(attempt = 0): void {
+    if (this.replayProvenance) { this.rebuild(); return; }
+    const before = this.frontier(), db = this.options.db;
+    let input: ReturnType<GenerationIndex["capture"]>;
+    try { input = this.capture(); }
+    catch (error) { if (attempt < 5 && this.frontier() !== before) return this.refresh(attempt + 1); throw error; }
+    if (this.frontier() !== before) { if (attempt < 5) return this.refresh(attempt + 1); return fail(); }
+    const known = db.query("SELECT source,path,offset,hash,commit_id,stamp FROM generation_segments").all() as { source: string; path: string; offset: number; hash: string; commit_id: string | null; stamp: string | null }[];
+    const currentCommit = (db.query("SELECT value FROM generation_state WHERE key='legacyCommit'").get() as { value: string } | null)?.value;
+    const unchanged = known.length === input.segments.length && currentCommit === input.commit && input.segments.every(segment => known.some(row => row.source === segment.source && row.path === segment.path && row.offset === segment.offset && row.hash === segment.hash && row.commit_id === (segment.commit ?? null) && row.stamp === (segment.stamp ?? null)));
+    if (unchanged) { this.pruned = new Set((db.query("SELECT id FROM generation_targets").all() as { id: string }[]).map(row => row.id)); return; }
+    const committed = db.transaction(() => { if (this.frontier() !== before) return false; this.index(input); return true; }).immediate();
+    if (!committed) { if (attempt < 5) return this.refresh(attempt + 1); return fail(); }
+  }
+  rebuild(attempt = 0): void {
+    const before = this.frontier();
+    let input: ReturnType<GenerationIndex["capture"]>;
+    try { this.fullCapture = true; input = this.capture(); }
+    catch (error) { this.fullCapture = false; if (attempt < 5 && this.frontier() !== before) return this.rebuild(attempt + 1); throw error; }
+    finally { this.fullCapture = false; }
+    const committed = this.options.db.transaction(() => {
+      if (this.frontier() !== before) return false;
+      for (const table of ["entries", "ops", "edges", "goals", "segments", "heads", ...GENERATION_TABLES]) this.options.db.run(`DELETE FROM ${table}`);
+      this.index(input); return true;
+    }).immediate();
+    if (!committed) { if (attempt < 5) return this.rebuild(attempt + 1); return fail(); }
+    this.replayProvenance = false;
+  }
+  own(id: string): boolean { return !!(this.options.db.query("SELECT own FROM generation_rows WHERE id=?").get(id) as { own: number } | null)?.own; }
+  snapshot(refresh = true): PruneSnapshot {
+    if (refresh) this.refresh();
+    return this.options.db.transaction(() => {
+      const rows = (this.options.db.query("SELECT line,local,public,own,legacy FROM generation_rows ORDER BY id").all() as { line: string; local: number; public: number; own: number; legacy: number }[]).map(r => ({ row: JSON.parse(r.line) as Entry, placement: r.local ? "local" as const : "synced" as const, publicWitness: !!r.public, own: !!r.own, legacy: !!r.legacy }));
+      const pruned = (this.options.db.query("SELECT id FROM generation_targets ORDER BY id").all() as { id: string }[]).map(row => row.id);
+      return { rows, expiries: explicitExpirySnapshot(rows), pruned, durablePruneIds: (this.options.db.query("SELECT id FROM generation_prunes ORDER BY id").all() as { id: string }[]).map(r => r.id) };
+    }).deferred();
+  }
+  port(machine: string): PruneStorePort {
+    return { generation: this.profile.generation!, machine, now: this.options.now,
+      selectorRevision: () => selectorRevision(this.profile.home), snapshot: () => this.snapshot(),
+      withMutation: work => this.options.withMutation(work), refresh: () => this.refresh(),
+      persistPrunePlan: plan => this.persistPlan(plan), appendPrune: (row, line, seal) => this.append(row, line, seal) };
+  }
+  private pendingPath(local: boolean, machine: string): string { return join(this.profile.dir, "prune-plans", `pending-${local ? "local" : "log"}-${machine}.json`); }
+  /** Every ordinary writer must refuse to append unrelated JSON after a prune crash tail. */
+  assertAppendable(local: boolean, machine: string): void {
+    if (readProfileJSON(this.pendingPath(local, machine)) !== undefined) fail();
+    const file = join(this.profile.dir, local ? "local" : "log", `${machine}.jsonl`);
+    if (!existsSync(file)) return;
+    if (lstatSync(file).isSymbolicLink() || !lstatSync(file).isFile()) fail();
+    const bytes = readFileSync(file);
+    if (bytes.length && bytes.at(-1) !== 10) fail();
+  }
+  private persistPlan(plan: PrunePlan): void {
+    const dir = join(this.profile.dir, "prune-plans");
+    if (existsSync(dir) && (lstatSync(dir).isSymbolicLink() || !lstatSync(dir).isDirectory())) fail();
+    mkdirSync(dir, { mode: 0o700, recursive: true });
+    fsyncDirectory(this.profile.dir);
+    const file = join(dir, `${plan.seal}.json`), existing = readProfileJSON(file);
+    if (existing && canonicalJSON(existing) !== canonicalJSON(plan)) fail();
+    if (!existing) writeProfileJSON(file, plan);
+  }
+  private append(row: PruneRow, line: string, seal: string): "written" | "already-durable" {
+    const plan = readProfileJSON(join(this.profile.dir, "prune-plans", `${seal}.json`)) as PrunePlan | undefined;
+    if (!plan?.rows.some(item => canonicalJSON(item.payload) === canonicalJSON(row)) || line !== canonicalJSON(row) + "\n") return fail();
+    this.refresh();
+    const already = this.snapshot(false).durablePruneIds?.includes(row.id);
+    const path = join(this.profile.dir, row.placement === "local" ? "local" : "log", `${row.machine}.jsonl`);
+    const fd = openSync(path, constants.O_RDWR | (already ? 0 : constants.O_CREAT) | constants.O_APPEND | constants.O_NOFOLLOW, 0o600);
+    try {
+      const data = readFileSync(fd), tail = data.subarray(data.lastIndexOf(10) + 1), bytes = Buffer.from(line);
+      const pending = this.pendingPath(row.placement === "local", row.machine);
+      const prior = readProfileJSON(pending) as { schema?: string; seal?: string; rowId?: string; lineHash?: string; offset?: number; prefixHash?: string } | undefined;
+      if (prior) {
+        if (prior.schema !== "agent-mem.prune-append/v1" || prior.seal !== seal || prior.rowId !== row.id || prior.lineHash !== digest(bytes)
+          || !Number.isSafeInteger(prior.offset) || prior.offset! < 0 || prior.offset! > data.length || digest(data.subarray(0, prior.offset)) !== prior.prefixHash) return fail();
+        if (already ? !data.subarray(prior.offset, prior.offset! + bytes.length).equals(bytes) : prior.offset !== data.length - tail.length) return fail();
+      } else if (!already) {
+        if (tail.length) return fail();
+        writeProfileJSON(pending, { schema: "agent-mem.prune-append/v1", seal, rowId: row.id, lineHash: digest(bytes), offset: data.length, prefixHash: digest(data) });
+      }
+      if (already) {
+        const complete = data.subarray(0, data.lastIndexOf(10) + 1).toString("utf8").split("\n").filter(Boolean);
+        if (!complete.some(value => canonicalJSON(JSON.parse(value)) === canonicalJSON(row))) return fail();
+      } else {
+        if (!bytes.subarray(0, tail.length).equals(tail)) return fail();
+        let offset = tail.length;
+        while (offset < bytes.length) { const wrote = writeSync(fd, bytes, offset, bytes.length - offset); if (wrote <= 0) fail(); offset += wrote; }
+      }
+      // A parsed complete line is not proof of fsync. Resume must cross this fence too.
+      fsyncSync(fd);
+      fsyncDirectory(join(this.profile.dir, row.placement === "local" ? "local" : "log"));
+      if (readProfileJSON(pending) !== undefined) { unlinkSync(pending); fsyncDirectory(join(this.profile.dir, "prune-plans")); }
+    } finally { closeSync(fd); }
+    this.refresh();
+    return already ? "already-durable" : "written";
+  }
+}

package/src/memory/generation-sync.ts

@@ -0,0 +1,248 @@
+import { randomBytes } from "node:crypto";
+import { closeSync, existsSync, lstatSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { legacyEntries, legacyHead, readLegacyGitSnapshot, captureLegacyMain } from "./bridge.ts";
+import { canonicalJSON, generationDescriptor, generationDir, readProfileJSON, validateGeneration } from "./generation.ts";
+import { acquireMutation } from "./mutation.ts";
+import { processLiveness, processSignature, realPath } from "./platform.ts";
+import { validatePruneRow, pruneRowHash, type PruneRow } from "./prune.ts";
+import { remoteVisibility, generationSyncGit as syncGit, type SyncOptions, type SyncResult } from "./sync.ts";
+import type { MemoryStore } from "./store.ts";
+import { createHash } from "node:crypto";
+
+const IGNORE = "/*\n!/.gitignore\n!/generation.json\n!/log/\n/log/*\n!/log/*.jsonl\n";
+const zero = "0".repeat(40), oid = (value: string) => /^[a-f0-9]{40}$/.test(value);
+const segment = (path: string) => /^log\/[a-f0-9]{16}\.jsonl$/.test(path);
+const fail = (reason: string): never => { throw new Error(reason); };
+function regular(path: string): boolean {
+  if (!existsSync(path)) return false;
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink()) fail("generation sync refuses non-regular public files");
+  return true;
+}
+function ownRepository(dir: string): boolean {
+  const path = join(dir, ".git");
+  if (!existsSync(path)) return false;
+  const stat = lstatSync(path);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || existsSync(join(path, "commondir")) || existsSync(join(path, "objects", "info", "alternates"))) fail("generation sync requires its separate repository");
+  return true;
+}
+function lockSync(dir: string): (() => void) | undefined {
+  const signature = processSignature(process.pid);
+  if (!signature) return undefined;
+  const file = join(dir, "sync.lock"), value = canonicalJSON({ pid: process.pid, signature, token: randomBytes(16).toString("hex") });
+  // The generation mutation transaction is already held, serializing stale-lock reclamation across callers.
+  for (let attempt = 0; attempt < 2; attempt++) {
+    let fd: number;
+    try { fd = openSync(file, "wx", 0o600); }
+    catch {
+      try {
+        if (!regular(file)) continue;
+        const prior = readFileSync(file, "utf8"), owner = JSON.parse(prior) as { pid?: unknown; signature?: unknown };
+        if (typeof owner.signature !== "string" || !owner.signature || processLiveness(owner.pid, owner.signature) !== "gone" || readFileSync(file, "utf8") !== prior) return undefined;
+        rmSync(file); continue;
+      } catch { return undefined; }
+    }
+    try { writeFileSync(fd, value); } finally { closeSync(fd); }
+    return () => { if (regular(file) && readFileSync(file, "utf8") === value) rmSync(file); };
+  }
+  return undefined;
+}
+
+function validatePublic(bytes: string, generation: string, path: string, checkPrune?: (row: PruneRow) => void): void {
+  if (!bytes) return;
+  const legacy: string[] = [];
+  for (const line of bytes.split("\n").filter(Boolean)) {
+    let value: unknown; try { value = JSON.parse(line); } catch { return fail("generation public segment has malformed rows"); }
+    const row = value as { schema?: unknown; op?: unknown; tier?: unknown };
+    if (row.schema === "agent-mem.prune/v1") {
+      const prune = validatePruneRow(value, generation, "synced");
+      if (path !== `log/${prune.machine}.jsonl`) fail("generation prune author does not match its segment");
+      checkPrune?.(prune);
+    }
+    else {
+      if (row.op === "settle" || row.op === "note" && row.tier !== "long") fail("generation public segment contains local-only rows");
+      legacy.push(line);
+    }
+  }
+  const body = Buffer.from(legacy.join("\n") + (legacy.length ? "\n" : ""));
+  legacyEntries([{ source: "legacy-main", path, bytes: body, offset: body.length, hash: createHash("sha256").update(body).digest("hex"), local: false, tailBytes: 0 }], { strict: true });
+}
+
+/** Separate generation repository, fixed refs and a one-way legacy cache; failures are bounded result receipts. */
+export async function syncGenerationMemory(store: MemoryStore, opts: SyncOptions = {}): Promise<SyncResult> {
+  let pushed = false, releaseMutation: (() => void) | undefined, releaseSync: (() => void) | undefined;
+  const result = (error: string): SyncResult => ({ ok: false, pushed, entries: 0, error });
+  const profile = store.profile, generation = profile.generation, dir = store.dir;
+  const transientRefs: { cache?: string; ref: string }[] = [];
+  const git = (args: string[], signal = opts.signal) => syncGit(dir, args, signal);
+  const required = async (args: string[], reason: string, signal = opts.signal): Promise<string> => {
+    const run = await git(args, signal);
+    if (run.code !== 0) fail(opts.signal?.aborted ? "stopped" : reason);
+    return run.out;
+  };
+  try {
+    if (opts.signal?.aborted) return result("stopped");
+    if (profile.kind !== "generation" || !generation || dir !== generationDir(profile.home, generation) || validateGeneration(profile.home, generation) !== dir) return result("generation profile unavailable");
+    const repo = ownRepository(dir);
+    if (!opts.remote && !repo) return result("no generation sync remote configured");
+    const url = opts.remote ?? await required(["remote", "get-url", "origin"], "no generation sync remote configured");
+    if (typeof url !== "string" || !url || url.length > 4096 || url.startsWith("-") || /[\r\n\0]/.test(url)) return result("generation sync remote is invalid");
+    if (await (opts.visibility ?? remoteVisibility)(url) !== "private") return result("generation sync requires positively verified private remote visibility");
+    if (opts.signal?.aborted) return result("stopped");
+    releaseMutation = acquireMutation(dir);
+    if (!releaseMutation) return result("another generation mutation is running");
+    releaseSync = lockSync(dir);
+    if (!releaseSync) return result("another generation sync is running or its owner is unknown");
+    validateGeneration(profile.home, generation);
+    if (readProfileJSON(join(dir, "prune-plans", `pending-log-${store.machine.id}.json`)) !== undefined) fail("generation prune append requires its original plan to resume before sync");
+    const ref = `refs/heads/amem/gen/${generation}`, descriptor = canonicalJSON(generationDescriptor(generation)), own = `log/${store.machine.id}.jsonl`;
+    const sources = new Map(store.prunePort().snapshot().rows.map(source => [source.row.id, source]));
+    const ownPrune = (row: PruneRow): void => {
+      for (const target of row.targets) for (const witness of [{ id: target.id, hash: target.rowHash }, { id: target.basis.id, hash: target.basis.rowHash }]) {
+        const source = sources.get(witness.id);
+        if (!source || source.placement !== "synced" || !source.publicWitness || pruneRowHash(source.row) !== witness.hash) fail("generation own prune lacks verified public witnesses");
+      }
+    };
+    if (!repo) {
+      await required(["--git-dir", join(dir, ".git"), "--work-tree", dir, "init", "-q", dir], "generation repository initialization failed");
+      await required(["symbolic-ref", "HEAD", ref], "generation branch initialization failed");
+    }
+    ownRepository(dir);
+    if (realPath(await required(["rev-parse", "--show-toplevel"], "generation worktree unavailable")) !== realPath(dir)) fail("generation working tree is routed outside its directory");
+    if (await required(["symbolic-ref", "--quiet", "HEAD"], "generation sync refuses detached HEAD") !== ref) fail("generation sync refuses an unexpected HEAD branch");
+    rmSync(join(dir, ".git", "index.lock"), { force: true });
+    if (existsSync(join(dir, ".git", "MERGE_HEAD"))) await required(["merge", "--abort"], "generation interrupted merge needs inspection", undefined);
+    const who = ["-c", "user.name=agent-mem", "-c", `user.email=agent-mem@${store.machine.id}.invalid`];
+    const blob = async (commit: string, path: string): Promise<string> => {
+      const out = await required(["show", `${commit}:${path}`], "generation history blob unavailable");
+      const size = Number(await required(["cat-file", "-s", `${commit}:${path}`], "generation history size unavailable"));
+      if (size !== Buffer.byteLength(out) + 1 && !(size === 0 && out === "")) fail("generation history requires complete newline-terminated public files");
+      return out;
+    };
+    // ponytail: audit every reachable tree at sync; cache verified immutable commit digests if measurements justify it.
+    const audited = new Set<string>();
+    const history = async (tip: string): Promise<void> => {
+      const commits = (await required(["rev-list", tip], "generation history unavailable")).split("\n").filter(Boolean);
+      for (const commit of commits) {
+        if (!oid(commit)) fail("generation history identity is invalid");
+        if (audited.has(commit)) continue;
+        const entries = (await required(["ls-tree", "-r", "-z", commit], "generation tree unavailable")).split("\0").filter(Boolean);
+        const paths: string[] = [];
+        for (const entry of entries) {
+          const match = /^(100644) blob ([a-f0-9]{40})\t(.+)$/.exec(entry);
+          if (!match) return fail("generation history contains forbidden files or links");
+          if (![".gitignore", "generation.json"].includes(match[3]!) && !segment(match[3]!)) fail("generation history contains forbidden files or links");
+          const path = match[3]!; paths.push(path);
+          const text = await blob(commit, path);
+          if (path === "generation.json") { let value: unknown; try { value = JSON.parse(text); } catch { return fail("generation descriptor is invalid"); } if (canonicalJSON(value) !== descriptor) fail("generation history descriptor mismatch"); }
+          else if (path === ".gitignore") { if (text !== IGNORE.trim()) fail("generation ignore contract mismatch"); }
+          else validatePublic(text, generation, path, path === own ? ownPrune : undefined);
+        }
+        if (!paths.includes("generation.json") || !paths.includes(".gitignore")) fail("generation history inherits a non-generation commit");
+        audited.add(commit);
+      }
+    };
+    const localHead = await git(["rev-parse", "--verify", "--quiet", "HEAD"]);
+    if (localHead.code === 0) await history(localHead.out);
+    else if (localHead.code !== 1) fail("generation HEAD is unavailable");
+    const staged = await required(["diff", "--cached", "--name-only"], "generation index unavailable");
+    if (staged.split("\n").filter(Boolean).some(path => ![".gitignore", "generation.json", own].includes(path))) fail("generation index has unrelated staged files");
+    regular(join(dir, "generation.json"));
+    if (regular(join(dir, own))) {
+      const text = readFileSync(join(dir, own), "utf8");
+      if (text && !text.endsWith("\n")) fail("generation own segment has an incomplete tail");
+      validatePublic(text, generation, own, ownPrune);
+    }
+    if (existsSync(join(dir, ".gitignore"))) { if (!regular(join(dir, ".gitignore"))) fail("generation ignore unavailable"); }
+    writeFileSync(join(dir, ".gitignore"), IGNORE, { mode: 0o600 });
+    if (opts.remote) {
+      const existing = await git(["remote", "get-url", "origin"]);
+      if (existing.code === 0 && existing.out !== url) await required(["remote", "set-url", "origin", url], "generation remote replacement failed");
+      if (existing.code !== 0) await required(["remote", "add", "origin", url], "generation remote configuration failed");
+    }
+    // Bind the actual expanded destinations, including pushurl/insteadOf rules, to the verified private URL.
+    // Refuse user configuration that points elsewhere; never silently replace a push URL.
+    const fetchURLs = (await required(["remote", "get-url", "--all", "origin"], "generation fetch destination unavailable")).split("\n").filter(Boolean);
+    const pushURLs = (await required(["remote", "get-url", "--push", "--all", "origin"], "generation push destination unavailable")).split("\n").filter(Boolean);
+    if (fetchURLs.length !== 1 || fetchURLs[0] !== url || pushURLs.length !== 1 || pushURLs[0] !== url) fail("generation sync refuses differing or multiple remote destinations");
+    const remoteTip = async (branch: string): Promise<string | undefined> => {
+      const listed = await git(["ls-remote", "--exit-code", "--heads", "origin", branch]);
+      if (listed.code === 2) return undefined;
+      if (listed.code !== 0) return fail(opts.signal?.aborted ? "stopped" : "generation remote lookup failed");
+      const match = /^([a-f0-9]{40})\t(.+)$/.exec(listed.out);
+      if (!match || match[2] !== branch) return fail("generation remote branch identity mismatch");
+      return match[1];
+    };
+    const pull = async (): Promise<void> => {
+      const expected = await remoteTip(ref);
+      if (!expected) return;
+      const incoming = `refs/amem/incoming/${randomBytes(16).toString("hex")}`;
+      transientRefs.push({ ref: incoming });
+      await required(["fetch", "-q", "--no-tags", "origin", `${ref}:${incoming}`], "generation fetch failed");
+      const tip = await required(["rev-parse", "--verify", incoming], "generation fetched ref unavailable");
+      await history(tip);
+      // Append-only convergence: a remote must never require rewriting an existing segment prefix.
+      const names = (await required(["ls-tree", "-r", "--name-only", tip], "generation incoming tree unavailable")).split("\n").filter(segment);
+      for (const path of names) if (regular(join(dir, path))) {
+        const local = readFileSync(join(dir, path), "utf8"), remote = await blob(tip, path), complete = remote ? remote + "\n" : "";
+        if (!local.startsWith(complete) && !complete.startsWith(local)) fail("generation segment diverged; person inspection required");
+      }
+      const before = await git(["rev-parse", "--verify", "--quiet", "HEAD"]);
+      const merged = await git(before.code === 0 ? [...who, "merge", "-q", "--no-edit", "--no-verify", "--allow-unrelated-histories", incoming] : ["merge", "--ff-only", incoming]);
+      if (merged.code !== 0) {
+        await syncGit(dir, ["merge", "--abort"]); // cleanup deliberately ignores an already-aborted invocation signal
+        fail(opts.signal?.aborted ? "stopped" : "generation merge failed");
+      }
+    };
+    // Commit only this machine's append, plus the fixed public metadata. Never stage the bridge or other machines.
+    await required(["add", "--", ".gitignore", "generation.json", ...(existsSync(join(dir, own)) ? [own] : [])], "generation staging failed");
+    const dirty = await git(["diff", "--cached", "--quiet"]);
+    if (dirty.code === 1) await required([...who, "commit", "-q", "--no-verify", "-m", "memory: generation append"], "generation commit failed");
+    else if (dirty.code !== 0) fail("generation staged comparison failed");
+    await pull();
+    // Fetch legacy main into a separate bare cache; publish its fixed read ref only after FF and CAS validation.
+    const main = await remoteTip("refs/heads/main"), manifestHead = legacyHead(profile.home, generation);
+    const cache = join(dir, "bridge.git");
+    let prior: string | undefined;
+    const validateCache = async () => {
+      if (lstatSync(cache).isSymbolicLink() || !lstatSync(cache).isDirectory() || existsSync(join(cache, "commondir")) || existsSync(join(cache, "objects", "info", "alternates"))
+        || await required(["--git-dir", cache, "rev-parse", "--is-bare-repository"], "legacy cache identity unavailable") !== "true") fail("legacy cache must be an independent bare repository");
+    };
+    if (existsSync(cache)) {
+      await validateCache();
+      const pinned = await git(["--git-dir", cache, "rev-parse", "--verify", "--quiet", "refs/remotes/legacy/main"]);
+      if (pinned.code === 0 && oid(pinned.out)) prior = pinned.out;
+      else if (pinned.code !== 1) fail("legacy cache read ref unavailable");
+    }
+    if (!main && (prior || manifestHead)) fail("legacy main disappeared; person inspection required");
+    if (main) {
+      if (!existsSync(cache)) await required(["init", "-q", "--bare", cache], "legacy cache initialization failed");
+      await validateCache();
+      const temp = `refs/amem/legacy-fetch/${randomBytes(16).toString("hex")}`; transientRefs.push({ cache, ref: temp });
+      await required(["--git-dir", cache, "fetch", "-q", "--no-tags", "--", url, `refs/heads/main:${temp}`], "legacy cache fetch failed");
+      const head = await required(["--git-dir", cache, "rev-parse", "--verify", temp], "legacy cache fetched ref unavailable");
+      if (!oid(head)) fail("legacy cache commit identity invalid");
+      for (const previous of new Set([prior, manifestHead].filter((value): value is string => value !== undefined)))
+        await required(["--git-dir", cache, "merge-base", "--is-ancestor", previous, head], "legacy main history is not fast-forward");
+      readLegacyGitSnapshot(profile.home, generation, head, manifestHead ?? prior);
+      await required(["--git-dir", cache, "update-ref", "refs/remotes/legacy/main", head, prior ?? zero], "legacy cache ref changed concurrently");
+      // Publish plain-file captured blobs only here, after the Git CAS. Reads keep the prior manifest across a crash.
+      captureLegacyMain(profile.home, generation, head, manifestHead);
+    }
+    if (opts.signal?.aborted) return result("stopped");
+    await history(await required(["rev-parse", "--verify", "HEAD"], "generation final HEAD unavailable"));
+    let sent = await git(["push", "-q", "origin", `HEAD:${ref}`]);
+    if (sent.code !== 0 && !opts.signal?.aborted) { await pull(); await history(await required(["rev-parse", "--verify", "HEAD"], "generation retry HEAD unavailable")); sent = await git(["push", "-q", "origin", `HEAD:${ref}`]); }
+    if (sent.code !== 0) fail(opts.signal?.aborted ? "stopped" : "generation push failed");
+    pushed = true;
+    return store.withDeferredPromotions(() => { store.refresh(); return { ok: true, pushed, entries: store.counts().long }; });
+  } catch (error) {
+    const reason = error instanceof Error && /^(generation |legacy |stopped)/.test(error.message) ? error.message.slice(0, 200) : "generation sync unavailable";
+    return result(reason);
+  } finally {
+    for (const transient of transientRefs) { try { await syncGit(dir, [...(transient.cache ? ["--git-dir", transient.cache] : []), "update-ref", "-d", transient.ref]); } catch { /* local refs remain non-public if cleanup itself fails */ } }
+    try { releaseSync?.(); } catch { /* cleanup cannot turn an observed sync result into an uncaught error */ }
+    try { releaseMutation?.(); } catch { /* closed/broken derived lock is a local recovery concern */ }
+  }
+}