@staix/agent-mem 0.2.0 → 0.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 Curated memory with append-only JSONL logs, a derived SQLite index, short- and long-term tiers, a typed graph, goals with leases, and git sync between machines. Extracted from [agent-hub](https://github.com/STAIxBWLB/agent-hub), with compatible storage and entry IDs.
 
-Version: 0.2.0. Requires Bun 1.4.2 or later; no runtime dependencies.
+Version: 0.3.1. Requires Bun 1.4.2 or later; no runtime dependencies.
 
 ## Install
 
@@ -149,6 +149,53 @@ The root entry needs Bun (it loads `bun:sqlite`). Node hosts that need only the
 
 The entry point exports the store, types and identity helpers, sync and claude-mem import, project/home helpers, raw memory/goal command handlers, and platform helpers. Hosts inject their own privacy policy through `StoreOptions.screen`; CLI wrappers can supply screened reads and import policy through the raw command options.
 
+## Contracts
+
+Shared segments retain the `agent-hub.memory/v1` profile. `OP_CONTRACTS` and `V1_OPS` keep the shared-v1 operation contract; both shared append paths refuse unknown or truth-changing operations. The separate `GENERATION_OP_CONTRACTS` enables only `prune` after an explicit generation selection. `correct`, `lift`, `consolidate` and `group` remain blocked. Reader announcements cannot authorize a new operation or relax generation isolation.
+
+The shared-v1 contract suites run the published 0.1.1 reader and compare all six v1 derived tables after replay and rebuild; generation fixtures cover their expanded derived state separately. Privacy and evidence matrices test the core's actual callbacks and sidecar boundaries; model-facing reads, PII turns, staleness checks and capture remain the host's responsibility. Direct person reads remain unscreened. Expiry after a wall-clock rollback retains the existing C05 ceiling: a rebuild can restore a previously expired row until its deadline passes again. A generation can persist exact-entry prune; shared-v1 and unpruned entries retain their existing expiry limitations.
+
+See [the contract and coverage tables](https://github.com/STAIxBWLB/agent-mem/blob/main/docs/contracts.md) for the fixtures, host-owned rows and declared ceilings. These are automated synthetic checks, not proof of the separate multi-machine or managed-agent live legs.
+
+
+## Generation migration and exact-entry prune
+
+Available from 0.3.0. Do not migrate a memory home that agent-hub also uses until agent-hub pins a generation-capable agent-mem and binds the selected profile (rollout order in [#9](https://github.com/STAIxBWLB/agent-mem/issues/9)); until then a running hub keeps writing shared v1 and the person's notes would split.
+
+Shared v1 remains the default until a person explicitly migrates the memory home. A generation uses `M/generations/G/` and a separate Git repository/ref (`refs/heads/amem/gen/G`); legacy directories and `main` are unchanged. The one-way readonly bridge consumes complete validated legacy prefixes without using the old index or writing legacy notes. Old programs continue using their legacy view, and generation-created notes never flow back to it.
+
+Complete malformed legacy lines (invalid JSON, unknown operations or mismatched content IDs) are skipped and counted, matching shared-v1 handling. Migration dry-run/apply and the person's human CLI status report the skipped count without printing the bodies; JSON list output stays an array of notes. Prefix rewrites, truncation and non-fast-forward legacy history still refuse access. A generation never promotes a bridged note or applies its own settlement to one; only generation-born notes receive generation settlements and promotions.
+
+Generation bridge reads use plain-file snapshots captured during explicit legacy sync and never invoke Git. Unchanged segments use metadata checkpoints without reading or hashing the data, including after reopen. A seeded live handle hashes only the appended suffix, while comparing existing prefix bytes on changed input; the first changed read by a cold handle and an explicit rebuild verify the full prefix. These are read-path bounds, not a latency or speedup promise.
+
+The following interfaces are for a person's terminal and an already initialized synthetic memory home. They do not authorize real-data migration. Use the same current project directory throughout planning and apply:
+
+```sh
+AMEM_HOME=/path/to/synthetic-memory amem migrate --dry-run
+AMEM_HOME=/path/to/synthetic-memory amem migrate
+# If interrupted, resume the recorded generation rather than creating another:
+AMEM_HOME=/path/to/synthetic-memory amem migrate --resume
+umask 077
+AMEM_HOME=/path/to/synthetic-memory amem prune --cutoff 2026-10-01T00:00:00.000Z --dry-run > prune-plan.json
+AMEM_HOME=/path/to/synthetic-memory amem prune --apply --plan prune-plan.json
+# Explicitly select shared v1 again while preserving both histories:
+AMEM_HOME=/path/to/synthetic-memory amem migrate --deactivate
+```
+
+All migrate/prune modes, including dry-run, refuse agent markers and require stdin TTY. `--generation <32-hex-G>` selects an explicitly named generation during migration/join; it is never discovered and activated from a remote automatically. Invalid active metadata blocks access rather than silently opening shared v1. Existing handles remain bound to the profile they opened; a selector change does not restart or rebind a running hub.
+
+Explicit `--deactivate` is the recovery path even when the selected generation is corrupt or missing. It reads the selector under the home-wide profile lock, selects shared v1 and retains all generation and legacy data. Normal reads still refuse corrupt active state. Shared-v1 sync keeps its pre-generation Git invocation and caller environment; generation-only sync adds repository-environment isolation and a private child-process umask.
+
+A prune plan is a person-local JSON receipt containing exact target/basis hashes, selector/project/policy revisions, fixed row bytes, local counts and a seal. Apply commits that same receipt after revalidation; it is not an authorization token. Maximums are 256 KiB per plan, 16 rows, 256 targets, and 32 targets/16 KiB per row. Larger automatic selections report `hasMore`; another plan handles remaining targets. Keep redirected plans private and out of source control, model context and sync.
+
+Only explicit serialized expiry is eligible: a note's `expires`, or an exact demote/settle row's `by`. Implicit backstop or instance-TTL deadlines cannot prove prune eligibility. Exact pruned IDs stay unavailable after clock rollback, including get/alias/graph-start paths. A different later promotion or replacement ID remains an independent note; this is not text/family removal, log erasure or storage reclamation. Unpruned expiry still follows the clock.
+
+Standalone CLI prune is local-only, even over a synced target. No `--policy-free` escape enables public prune. A later policy-aware host integration must authenticate intent and attest the exact public payload and current policy revision; only verified public target/basis provenance may sync. Local masks, plans, journals, caches and sidecars never sync. Generation sync refuses public or unknown remote visibility. An interrupted apply resumes the same durable row IDs and exact partial tail; it never rewrites complete lines.
+
+Candidate/counter sidecars are not migrated. `amem review` currently refuses a selected generation rather than using an unbound legacy sidecar. A profile-aware host integration must handle that context explicitly.
+
+Real migration remains blocked until the separately reviewed generation-capable amem release and exact-pinned agent-hub integration are installed and their running stores prove the same home/G/selector revision. Synthetic cross-writes and exact prune readbacks precede separately confirmed real migration; known local handles must be quiesced/closed and reopened through the supported session-preserving lifecycle. Release, deployment, real migration, host evidence/capture receipts and real multi-machine sync are not established by these source changes. Deactivation omits generation-only notes/prunes from the v1 view and is not a lossless rollback.
+
 ## Development
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-mem",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Curated, shared memory for coding agents: append-only logs, a derived index, tiers and a typed graph.",
   "license": "MIT",
   "type": "module",
@@ -13,7 +13,9 @@
   },
   "devDependencies": {
     "@types/bun": "^1.3.0",
-    "typescript": "^5.8.0"
+    "typescript": "^5.8.0",
+    "@staix/agent-mem-v1": "npm:@staix/agent-mem@0.1.1",
+    "@staix/agent-mem-v02": "npm:@staix/agent-mem@0.2.0"
   },
   "exports": {
     ".": "./src/index.ts",

package/src/cli.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { closeSync, constants, fstatSync, openSync, readFileSync, readSync } from "node:fs";
 import { MemoryStore, looksSecret } from "./memory/store.ts";
 import { rawMemoryCommand, rawGoalCommand } from "./memory/commands.ts";
 import { memoryProjectKey } from "./memory/project.ts";
@@ -6,11 +6,50 @@ import { CandidateStore, type CandidateFilter } from "./memory/candidates.ts";
 
 import { commandHelp, parseCommand } from "./commands-table.ts";
 import { completionScript } from "./completion.ts";
+import { memoryHome } from "./memory/home.ts";
+import { resolveProfile } from "./memory/generation.ts";
+import { migrate } from "./memory/migrate.ts";
+import { applyPrune, planPrune, PRUNE_PLAN_MAX_BYTES } from "./memory/prune.ts";
 
 export const PERSON_ONLY = "amem is for the person; agents read memory through the hub's hub_memory_* tools";
 const VERSION = (JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string }).version;
 export interface CliContext { cwd?: string; env?: Readonly<Record<string, string | undefined>>; stdinTTY?: boolean }
 
+/** Narrow descriptor seam for deterministic race fixtures; the CLI always uses the native implementation. */
+export interface PrunePlanFileIO {
+  open(path: string, flags: number): number;
+  stat(fd: number): { size: number; isFile(): boolean };
+  read(fd: number, buffer: Buffer, offset: number, length: number, position: number): number;
+  close(fd: number): void;
+}
+const planFileIO: PrunePlanFileIO = {
+  open: (path, flags) => openSync(path, flags), stat: fd => fstatSync(fd),
+  read: (fd, buffer, offset, length, position) => readSync(fd, buffer, offset, length, position), close: fd => closeSync(fd),
+};
+
+/** Open once: pathname replacement cannot redirect the read and growth cannot exceed the fixed byte budget. */
+export function readPrunePlanFile(path: string, io: PrunePlanFileIO = planFileIO): string {
+  try {
+    const fd = io.open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+      const before = io.stat(fd);
+      if (!before.isFile() || !Number.isSafeInteger(before.size) || before.size < 0 || before.size > PRUNE_PLAN_MAX_BYTES) throw new Error();
+      const data = Buffer.alloc(PRUNE_PLAN_MAX_BYTES + 1);
+      let length = 0;
+      while (length < data.length) {
+        const n = io.read(fd, data, length, data.length - length, length);
+        if (!Number.isSafeInteger(n) || n < 0 || n > data.length - length) throw new Error();
+        if (n === 0) break;
+        length += n;
+      }
+      if (length > PRUNE_PLAN_MAX_BYTES) throw new Error();
+      const after = io.stat(fd);
+      if (!after.isFile() || after.size !== before.size || length !== before.size) throw new Error();
+      return new TextDecoder("utf-8", { fatal: true }).decode(data.subarray(0, length));
+    } finally { io.close(fd); }
+  } catch { throw new Error("prune plan unavailable or oversized"); }
+}
+
 /** Honest native-shell defaults, matching every marker detectCliIdentity treats as non-console (invalid included). */
 export function agentMarked(env: Readonly<Record<string, string | undefined>>): boolean {
   return ["AGENTHUB_PEER_ID", "CLAUDECODE", "CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID"].some(key => env[key] !== undefined);
@@ -40,7 +79,27 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
   if (definition.policyFree && !policyFree) {
     throw new Error(review ? "review accept requires --policy-free; use ahub memory to apply the host's privacy policy" : `${sub} requires --policy-free; use ahub memory ${sub} to apply the host's privacy policy`);
   }
+  if (sub === "migrate") {
+    const modes = ["--dry-run", "--resume", "--deactivate"].filter(key => options[key] === true);
+    if (modes.length > 1) throw new Error("migration modes are mutually exclusive");
+    const mode = options["--dry-run"] ? "dry-run" : options["--resume"] ? "resume" : options["--deactivate"] ? "deactivate" : "apply";
+    return JSON.stringify(await migrate({ memoryDir: memoryHome(), mode, ...(options["--generation"] ? { generation: String(options["--generation"]) } : {}), authorizedPerson: true, tty: true }), null, 2);
+  }
+  if (sub === "prune") {
+    const applying = options["--apply"] === true;
+    if (applying ? options["--dry-run"] || options["--cutoff"] || !options["--plan"] : !options["--dry-run"] || !options["--cutoff"] || options["--plan"]) throw new Error("usage: amem prune --cutoff <UTC> --dry-run | --apply --plan <file>");
+    let input: string | undefined;
+    if (applying) {
+      input = readPrunePlanFile(String(options["--plan"]));
+    }
+    const store = new MemoryStore({ deferPromotions: true });
+    try {
+      const auth = { project: memoryProjectKey(context.cwd ?? process.cwd()), actor: "person" as const, authorize: () => true };
+      return JSON.stringify(applying ? applyPrune(store.prunePort(), input, auth) : planPrune(store.prunePort(), { cutoff: String(options["--cutoff"]) }, auth), null, 2);
+    } finally { store.close(); }
+  }
   if (review) {
+    if (resolveProfile(memoryHome()).kind === "generation") throw new Error("candidate review is not yet integrated with this generation; use the profile-aware host after its integration");
     const id = parsed.positionals[0];
     if (sub !== "list" && (!id || !/^[a-f0-9]{64}$/.test(id))) throw new Error("review accept/reject requires a full 64-character candidate id");
     const project = memoryProjectKey(context.cwd ?? process.cwd()), candidates = new CandidateStore();
@@ -74,9 +133,12 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
   const open = () => new MemoryStore({ screen: note => !crosses ? "skip" : looksSecret(`${note.title ?? ""}\n${note.text}`) ? "keep" : "promote" });
   const cwd = context.cwd ?? process.cwd();
   // A person's reads are unscreened. Writes crossing the boundary remain secret-screened without host policy.
-  return goal
-    ? rawGoalCommand(args, cwd, { open, clean: (title, milestones) => !mutating || !looksSecret(`${title}\n${milestones.join("\n")}`) })
-    : rawMemoryCommand(args, cwd, { open, readable: notes => notes, importPolicy: () => () => false });
+  if (goal) return rawGoalCommand(args, cwd, { open, clean: (title, milestones) => !mutating || !looksSecret(`${title}\n${milestones.join("\n")}`) });
+  const receipt: { bridgeStatus?: { skippedRows: number } } = {};
+  const output = await rawMemoryCommand(args, cwd, { open, readable: notes => notes, importPolicy: () => () => false,
+    onBridgeStatus: status => { receipt.bridgeStatus = status; } });
+  return !options["--json"] && receipt.bridgeStatus
+    ? `${output}\n(legacy malformed lines skipped: ${receipt.bridgeStatus.skippedRows})` : output;
 }
 
 export async function main(argv = process.argv.slice(2)): Promise<void> {

package/src/commands-table.ts

@@ -55,6 +55,14 @@ export const COMMANDS: Record<string, CommandDefinition> = {
     accept: { description: "Accept one candidate through the current memory policy", options: policy, args: [{ name: "full-candidate-id" }], mutates: true, policyFree: true },
     reject: { description: "Reject one candidate", args: [{ name: "full-candidate-id" }], mutates: true },
   } },
+  migrate: { description: "Select a person-approved generation or deactivate it", mutates: true, options: {
+    ...json, "--dry-run": flag("Read-only migration receipt"), "--generation": text("Explicit 32-hex generation ID"),
+    "--resume": flag("Resume the recorded migration"), "--deactivate": flag("Select shared v1 without deleting a generation"),
+  } },
+  prune: { description: "Plan or apply exact-entry durable expiry in a generation", mutates: true, options: {
+    ...json, "--cutoff": text("Canonical UTC expiry cutoff"), "--dry-run": flag("Print a local sealed plan without writes"),
+    "--apply": flag("Apply the exact local plan"), "--plan": { description: "Sealed local plan JSON file", value: "path" },
+  } },
   completion: { description: "Print static shell completion", args: [{ name: "shell", values: ["zsh", "bash", "fish"] }] },
   help: { description: "Show help" }, version: { description: "Show version" },
 };

package/src/index.ts

@@ -6,3 +6,7 @@ export * from "./memory/home.ts";
 export * from "./memory/platform.ts";
 export * from "./memory/commands.ts";
 export * from "./memory/candidates.ts";
+export * from "./memory/ops-contract.ts";
+export * from "./memory/generation.ts";
+export * from "./memory/migrate.ts";
+export * from "./memory/prune.ts";

package/src/memory/bridge.ts

@@ -0,0 +1,376 @@
+import { createHash, randomBytes, type Hash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { closeSync, constants, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, unlinkSync, writeSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { memoryGitArgv, memoryGitEnv, realPath } from "./platform.ts";
+import { canonicalJSON, fsyncDirectory, readProfileJSON, writeProfileJSON } from "./generation.ts";
+import { OP_CONTRACTS } from "./ops-contract.ts";
+import { entryId, type Entry } from "./store.ts";
+
+export interface LegacyCheckpoint { source: string; path: string; offset: number; hash: string; commit?: string; tailBytes?: number; stamp?: string }
+export interface LegacySegment extends LegacyCheckpoint { bytes: Buffer; local: boolean; tailBytes: number; start?: number }
+export interface LegacySnapshotOptions {
+  generation?: string;
+  commit?: string;
+  previousCommit?: string;
+  /** Count skipped complete legacy lines; authoritative generation callers use legacyEntries strict mode. */
+  onMalformed?: () => void;
+  checkpoints?: readonly LegacyCheckpoint[];
+  reader?: SegmentReader;
+  incremental?: boolean;
+  /** A migration replay reads exactly these captured complete prefixes, ignoring later suffixes/new segments. */
+  limits?: readonly LegacyCheckpoint[];
+}
+const diskSource = "legacy-local", remoteSource = "legacy-main";
+const digest = (bytes: Uint8Array) => createHash("sha256").update(bytes).digest("hex");
+class LegacyInputError extends Error {
+  constructor(readonly malformed = false) { super("legacy bridge input changed or is invalid; person inspection required"); }
+}
+function failure(): never { throw new LegacyInputError(); }
+function malformed(): never { throw new LegacyInputError(true); }
+const key = (row: LegacyCheckpoint) => `${row.source}:${row.path}`;
+const segmentPath = (path: string) => /^(log|local)\/[A-Za-z0-9][A-Za-z0-9._-]*\.jsonl$/.test(path);
+const commitId = (value: string) => /^[a-f0-9]{40}$/.test(value);
+
+function directory(path: string, optional = false): boolean {
+  try { const stat = lstatSync(path); if (stat.isSymbolicLink() || !stat.isDirectory()) failure(); return true; }
+  catch (error) { if (optional && (error as NodeJS.ErrnoException).code === "ENOENT") return false; throw error; }
+}
+
+export interface SegmentReadMetrics { bytesRead: number; bytesHashed: number; coldChanged: number }
+interface PrefixState { offset: number; hash: string; hasher: Hash; bytes: Buffer }
+type SegmentBytes = Pick<LegacySegment, "bytes" | "offset" | "hash" | "tailBytes" | "stamp" | "start">;
+const statStamp = (stat: { dev: bigint | number; ino: bigint | number; size: bigint | number; mtimeNs?: bigint; ctimeNs?: bigint }) => JSON.stringify([String(stat.dev), String(stat.ino), String(stat.size), String(stat.mtimeNs), String(stat.ctimeNs)]);
+
+/** Handle-local SHA state: unchanged persisted metadata costs no data read or hashing, including reopen. */
+export class SegmentReader {
+  private readonly prefixes = new Map<string, PrefixState>();
+  private measured: SegmentReadMetrics = { bytesRead: 0, bytesHashed: 0, coldChanged: 0 };
+  metrics(): SegmentReadMetrics { return { ...this.measured }; }
+  resetMetrics(): void { this.measured = { bytesRead: 0, bytesHashed: 0, coldChanged: 0 }; }
+  read(path: string, prior?: LegacyCheckpoint, full = false, immutable = false): SegmentBytes {
+    const before = lstatSync(path, { bigint: true });
+    if (before.isSymbolicLink() || !before.isFile() || !Number.isSafeInteger(Number(before.size))) failure();
+    const stamp = statStamp(before), size = Number(before.size);
+    if (prior && size < prior.offset) failure();
+    if (!full && prior?.stamp === stamp) return { bytes: Buffer.alloc(0), start: prior.offset, offset: prior.offset, hash: prior.hash, tailBytes: size - prior.offset, stamp };
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const opened = fstatSync(fd, { bigint: true });
+      if (statStamp(opened) !== stamp) failure();
+      const read = (length: number): Buffer => {
+        const bytes = Buffer.alloc(length); let at = 0;
+        while (at < length) { const n = readSync(fd, bytes, at, length - at, at); if (!n) failure(); at += n; this.measured.bytesRead += n; }
+        return bytes;
+      };
+      const all = read(size), end = all.lastIndexOf(10) + 1, bytes = all.subarray(0, end);
+      if (prior && end < prior.offset) failure();
+      if (!read(end).equals(bytes) || fstatSync(fd, { bigint: true }).size < opened.size) failure();
+      const after = lstatSync(path, { bigint: true });
+      if (after.isSymbolicLink() || after.dev !== opened.dev || after.ino !== opened.ino) failure();
+      const cached = immutable ? undefined : this.prefixes.get(path);
+      let hasher: Hash;
+      if (!full && prior && cached && cached.offset === prior.offset && cached.hash === prior.hash) {
+        // Changed live input still reads/compares the old bytes, so rewrite-plus-growth cannot masquerade as append.
+        // ponytail: the generation counterpart of C02: O(segment) I/O per changed refresh (13 MB at 20K entries, p50 247 ms,
+        // docs/bench/p9-generation-read.md). Upgrade, measured first: a per-block hash chain or a tail window plus inode/size check.
+        if (!cached.bytes.equals(bytes.subarray(0, prior.offset))) failure();
+        hasher = cached.hasher.copy(); const suffix = bytes.subarray(prior.offset); hasher.update(suffix); this.measured.bytesHashed += suffix.length;
+      } else {
+        // ponytail: a cold changed segment verifies/seeds its whole prefix once (O(segment)); unchanged reopens are O(metadata).
+        // Serialize SHA state or retain per-block receipts only if measured cold-change cost warrants that additional format.
+        hasher = createHash("sha256");
+        if (prior) {
+          hasher.update(bytes.subarray(0, prior.offset)); this.measured.bytesHashed += prior.offset;
+          if (hasher.copy().digest("hex") !== prior.hash) failure();
+          if (!full) this.measured.coldChanged++;
+          hasher.update(bytes.subarray(prior.offset)); this.measured.bytesHashed += bytes.length - prior.offset;
+        } else { hasher.update(bytes); this.measured.bytesHashed += bytes.length; }
+      }
+      const hash = hasher.copy().digest("hex");
+      if (!immutable) this.prefixes.set(path, { offset: end, hash, hasher, bytes: Buffer.from(bytes) });
+      const start = !full && prior ? prior.offset : 0;
+      // A concurrent append is outside the captured length; retain the earlier stamp so the next read notices it.
+      return { bytes: Buffer.from(bytes.subarray(start)), ...(start ? { start } : {}), offset: end, hash, tailBytes: size - end, stamp };
+    } finally { closeSync(fd); }
+  }
+}
+
+function checkpointMap(rows: readonly LegacyCheckpoint[] = []): Map<string, LegacyCheckpoint> {
+  const map = new Map<string, LegacyCheckpoint>();
+  for (const row of rows) {
+    if (![diskSource, remoteSource].includes(row.source) || !segmentPath(row.path) || row.source === remoteSource && !row.path.startsWith("log/")
+      || !Number.isSafeInteger(row.offset) || row.offset < 0 || !/^[a-f0-9]{64}$/.test(row.hash)
+      || row.tailBytes !== undefined && (!Number.isSafeInteger(row.tailBytes) || row.tailBytes < 0)
+      || row.stamp !== undefined && (typeof row.stamp !== "string" || row.stamp.length > 1024)
+      || row.source === remoteSource && (!row.commit || !commitId(row.commit)) || row.source === diskSource && row.commit !== undefined || map.has(key(row))) failure();
+    map.set(key(row), row);
+  }
+  return map;
+}
+
+function checkedEntry(value: unknown): Entry {
+  if (!value || typeof value !== "object" || Array.isArray(value)) malformed();
+  const row = value as Record<string, unknown>;
+  const operation = row.op;
+  if (typeof operation !== "string") return malformed();
+  if (!Object.hasOwn(OP_CONTRACTS, operation)) return malformed();
+  const contract = OP_CONTRACTS[operation]!;
+  const schema = contract.payloadSchema;
+  if (!contract.implemented || contract.status !== "v1-equal" || !schema) malformed();
+  if (row.schema !== "agent-hub.memory/v1" || typeof row.id !== "string" || !/^[a-f0-9]{32}$/.test(row.id)) malformed();
+  const { id, ...body } = row;
+  if (entryId(body as unknown as Omit<Entry, "id">) !== id) malformed();
+  for (const name of schema.required) if (row[name] === undefined && !schema.legacyOptional.includes(name)) malformed();
+  for (const [name, field] of Object.entries(schema.fields)) {
+    const value = row[name];
+    if (value === undefined || value === null && (!schema.required.includes(name) || schema.legacyOptional.includes(name))) continue;
+    if (field.type === "string-array") { if (!Array.isArray(value) || !value.every(item => typeof item === "string")) malformed(); continue; }
+    if (typeof value !== "string" || field.maxLength !== undefined && value.length > field.maxLength || field.values && !field.values.includes(value)) malformed();
+    if (field.format === "id" && !/^[a-f0-9]{32}$/.test(value)) malformed();
+    if (field.format === "utc" && Number.isNaN(Date.parse(value))) malformed();
+  }
+  if (typeof row.at !== "string" || new Date(row.at).toISOString() !== row.at) malformed();
+  return row as unknown as Entry;
+}
+
+function* completeLines(bytes: Buffer): Generator<Buffer> {
+  let start = 0;
+  while (start < bytes.length) { const end = bytes.indexOf(10, start); if (end < 0) failure(); yield bytes.subarray(start, end); start = end + 1; }
+}
+
+/** Preserve original IDs; row order and JSON key order never produce duplicate evidence. */
+export function legacyEntries(segments: readonly LegacySegment[], options: { strict?: boolean; onMalformed?: () => void } = {}): Entry[] {
+  const rows = new Map<string, Entry>();
+  for (const segment of segments) {
+    if (segment.bytes.length !== segment.offset || digest(segment.bytes) !== segment.hash || segment.offset && segment.bytes.at(-1) !== 10) failure();
+    for (const bytes of completeLines(segment.bytes)) {
+      let row: Entry;
+      try {
+        let line: string;
+        try { line = new TextDecoder("utf-8", { fatal: true }).decode(bytes); } catch { malformed(); }
+        if (!line!.trim()) continue;
+        let value: unknown; try { value = JSON.parse(line!); } catch { malformed(); }
+        row = checkedEntry(value);
+      } catch (error) {
+        if (!(error instanceof LegacyInputError) || !error.malformed || options.strict) throw error;
+        options.onMalformed?.();
+        continue;
+      }
+      const prior = rows.get(row.id);
+      if (prior && !isDeepStrictEqual(JSON.parse(JSON.stringify(prior)), JSON.parse(JSON.stringify(row)))) failure();
+      rows.set(row.id, row);
+    }
+  }
+  return [...rows.values()];
+}
+
+/** Raw authoritative inputs only: never constructs a legacy store, opens its index or performs network I/O. */
+function snapshot(homeM: string, options: LegacySnapshotOptions): LegacySegment[] {
+  const root = realPath(homeM);
+  directory(root);
+  const checkpoints = checkpointMap(options.checkpoints), limits = options.limits === undefined ? undefined : checkpointMap(options.limits);
+  const result: LegacySegment[] = [];
+  const accept = (source: string, path: string, complete: Buffer, commit?: string, tailBytes = 0, stamp?: string) => {
+    if (!segmentPath(path)) failure();
+    const identity = `${source}:${path}`, prior = checkpoints.get(identity), limit = limits?.get(identity);
+    if (limits && !limit) return;
+    const verify = (receipt: LegacyCheckpoint) => {
+      if (receipt.offset > complete.length || receipt.offset > 0 && complete[receipt.offset - 1] !== 10 || digest(complete.subarray(0, receipt.offset)) !== receipt.hash) failure();
+    };
+    if (prior) verify(prior);
+    if (limit) { verify(limit); if (prior && limit.offset < prior.offset || limit.commit !== commit) failure(); }
+    const bytes = Buffer.from(limit ? complete.subarray(0, limit.offset) : complete);
+    result.push({ source, path, bytes, offset: bytes.length, hash: digest(bytes), local: path.startsWith("local/"), tailBytes: limit ? limit.tailBytes ?? 0 : tailBytes, ...((limit ? limit.stamp : stamp) ? { stamp: limit ? limit.stamp : stamp } : {}), ...(commit ? { commit } : {}) });
+  };
+  // Identity is read without invoking machineId(), which can initialize or repair local state.
+  let machine: unknown;
+  try { machine = JSON.parse(capturedIdentity(join(root, "machine.json"))); } catch { failure(); }
+  const machineId = (machine as { id?: unknown } | undefined)?.id;
+  if (typeof machineId !== "string" || !/^[a-f0-9]{16}$/.test(machineId)) failure();
+  for (const folder of ["log", "local"]) {
+    const dir = join(root, folder);
+    if (!directory(dir, true)) continue;
+    for (const name of readdirSync(dir).sort()) {
+      if (!name.endsWith(".jsonl")) continue;
+      const path = `${folder}/${name}`;
+      if (!segmentPath(path)) failure();
+      if (folder === "local" && name !== `${machineId}.jsonl`) continue;
+      const reader = options.reader ?? new SegmentReader();
+      const incremental = options.incremental && !limits;
+      const data = reader.read(join(dir, name), incremental ? checkpoints.get(`${diskSource}:${path}`) : undefined, !incremental);
+      if (incremental) result.push({ ...data, source: diskSource, path, local: folder === "local" });
+      else accept(diskSource, path, data.bytes, undefined, data.tailBytes, data.stamp);
+    }
+  }
+  if ((options.commit || options.previousCommit) && !options.generation || options.previousCommit && !commitId(options.previousCommit)) failure();
+  if (options.generation !== undefined) {
+    const commit = options.commit ?? legacyHead(root, options.generation);
+    if (commit) {
+      const manifest = archived(root, options.generation, commit);
+      directory(join(archiveDir(root, options.generation, commit), "log"));
+      for (const prior of new Set([...(options.previousCommit ? [options.previousCommit] : []), ...[...checkpoints.values()].filter(row => row.source === remoteSource).map(row => row.commit!)])) if (!archivedAncestor(root, options.generation, prior, commit)) failure();
+      for (const segment of manifest.segments) {
+        const reader = options.reader ?? new SegmentReader(), incremental = options.incremental && !limits;
+        const data = reader.read(join(archiveDir(root, options.generation, commit), segment.path), incremental ? checkpoints.get(`${remoteSource}:${segment.path}`) : undefined, !incremental, true);
+        if (data.offset !== segment.offset || data.hash !== segment.hash || data.tailBytes) failure();
+        if (incremental) result.push({ ...data, source: remoteSource, path: segment.path, local: false, tailBytes: segment.tailBytes, commit });
+        else accept(remoteSource, segment.path, data.bytes, commit, segment.tailBytes, data.stamp);
+      }
+    } else if (options.previousCommit) failure();
+  }
+  const returned = new Set(result.map(key));
+  for (const receipt of [...checkpoints.values(), ...(limits?.values() ?? [])]) if (!returned.has(key(receipt))) failure();
+  // Checkpointed complete prefixes were already validated; their full hashes prove unchanged bytes.
+  // Only newly completed suffixes need parsing on an incremental read.
+  const suffixes = result.map(segment => {
+    const start = checkpoints.get(key(segment))?.offset ?? 0;
+    const bytes = segment.bytes.subarray(Math.max(0, start - (segment.start ?? 0)));
+    return { ...segment, bytes, offset: bytes.length, hash: digest(bytes) };
+  });
+  legacyEntries(suffixes, { onMalformed: options.onMalformed });
+  return result;
+}
+
+function capturedIdentity(path: string): string {
+  const before = lstatSync(path);
+  if (before.isSymbolicLink() || !before.isFile()) failure();
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = fstatSync(fd);
+    if (stat.dev !== before.dev || stat.ino !== before.ino || stat.size > 4096) failure();
+    const bytes = Buffer.alloc(stat.size);
+    if (readSync(fd, bytes, 0, bytes.length, 0) !== bytes.length) failure();
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } finally { closeSync(fd); }
+}
+
+
+function cacheDirectory(root: string, generation: string): string | undefined {
+  if (!/^[a-f0-9]{32}$/.test(generation)) failure();
+  const cache = join(root, "generations", generation, "bridge.git");
+  for (const path of [join(root, "generations"), join(root, "generations", generation), cache]) if (!directory(path, true)) return undefined;
+  return cache;
+}
+function cachedGit(cache: string, args: string[], allowMissing = false): Buffer | undefined {
+  const argv = memoryGitArgv(["--git-dir", cache, ...args]);
+  const run = spawnSync(argv[0]!, argv.slice(1), { env: memoryGitEnv({ ...process.env, GIT_OPTIONAL_LOCKS: "0" }, { repositoryIsolation: true }), encoding: "buffer", timeout: 10_000, maxBuffer: 256 * 1024 * 1024 });
+  if (run.error || run.signal || run.status !== 0) { if (allowMissing && !run.error && !run.signal && run.status === 1) return undefined; failure(); }
+  return run.stdout;
+}
+/** Last explicitly fetched legacy main, not a claim about the current remote state. Never fetches or writes. */
+function head(homeM: string, generation: string): string | undefined {
+  const root = realPath(homeM); directory(root);
+  const dir = fixedGeneration(root, generation);
+  if (!directory(dir, true)) return undefined;
+  const active = readProfileJSON(join(dir, "bridge-snapshot.json"), 4096) as { schema?: unknown; generation?: unknown; commit?: unknown } | undefined;
+  if (!active) return undefined;
+  if (active.schema !== "agent-mem.legacy-head/v1" || active.generation !== generation || typeof active.commit !== "string" || !commitId(active.commit)) failure();
+  archived(root, generation, active.commit);
+  return active.commit;
+}
+
+
+export function readLegacySnapshot(homeM: string, options: LegacySnapshotOptions = {}): LegacySegment[] {
+  try { return snapshot(homeM, options); } catch { return failure(); }
+}
+export function legacyHead(homeM: string, generation: string): string | undefined {
+  try { return head(homeM, generation); } catch { return failure(); }
+}
+
+
+// ponytail: immutable historical snapshots remain while migration/resume and prior-commit receipts can reference them.
+// Disk use grows with sync history; add explicit journal-aware GC or content-addressed reuse if measurements justify it.
+interface ArchivedSegment { path: string; offset: number; hash: string; tailBytes: number }
+interface LegacyArchive { schema: "agent-mem.legacy-snapshot/v1"; generation: string; commit: string; previousCommit?: string; segments: ArchivedSegment[] }
+function fixedGeneration(root: string, generation: string): string {
+  if (!/^[a-f0-9]{32}$/.test(generation)) failure();
+  const parent = join(root, "generations");
+  if (directory(parent, true)) directory(join(parent, generation), true);
+  return join(parent, generation);
+}
+function archiveDir(root: string, generation: string, commit: string): string {
+  if (!commitId(commit)) failure();
+  const dir = join(fixedGeneration(root, generation), "bridge-snapshots");
+  directory(dir); const target = join(dir, commit); directory(target); return target;
+}
+function archived(root: string, generation: string, commit: string): LegacyArchive {
+  const value = readProfileJSON(join(archiveDir(root, generation, commit), "snapshot.json"), 32 * 1024 * 1024) as LegacyArchive | undefined;
+  if (!value || value.schema !== "agent-mem.legacy-snapshot/v1" || value.generation !== generation || value.commit !== commit || value.previousCommit !== undefined && !commitId(value.previousCommit) || !Array.isArray(value.segments)) failure();
+  const paths = new Set<string>();
+  for (const segment of value.segments) {
+    if (!segment || !segmentPath(segment.path) || !segment.path.startsWith("log/") || paths.has(segment.path) || !Number.isSafeInteger(segment.offset) || segment.offset < 0 || !/^[a-f0-9]{64}$/.test(segment.hash) || !Number.isSafeInteger(segment.tailBytes) || segment.tailBytes < 0) failure();
+    paths.add(segment.path);
+  }
+  return value;
+}
+function archivedAncestor(root: string, generation: string, previous: string, commit: string): boolean {
+  const visited = new Set<string>();
+  for (let cursor: string | undefined = commit; cursor && !visited.has(cursor); cursor = archived(root, generation, cursor).previousCommit) {
+    if (cursor === previous) return true;
+    visited.add(cursor);
+  }
+  return false;
+}
+
+/** Explicit sync-only Git capture. Ordinary readLegacySnapshot/legacyHead never call Git. */
+export function readLegacyGitSnapshot(homeM: string, generation: string, commit: string, previousCommit?: string): LegacySegment[] {
+  try {
+    const root = realPath(homeM), cache = cacheDirectory(root, generation);
+    if (!cache || !commitId(commit) || previousCommit !== undefined && !commitId(previousCommit)) failure();
+    if (cachedGit(cache, ["cat-file", "-t", commit])?.toString("utf8").trim() !== "commit") failure();
+    if (previousCommit && previousCommit !== commit) cachedGit(cache, ["merge-base", "--is-ancestor", previousCommit, commit]);
+    const result: LegacySegment[] = [];
+    for (const record of cachedGit(cache, ["ls-tree", "-rz", "--full-tree", commit, "--", "log"])!.toString("utf8").split("\0").filter(Boolean)) {
+      const match = /^([0-7]{6}) blob ([a-f0-9]{40})\t(.+)$/.exec(record);
+      if (!match || match[1] !== "100644" && match[1] !== "100755" || !segmentPath(match[3]!) || !match[3]!.startsWith("log/")) return failure();
+      const blob = cachedGit(cache, ["cat-file", "blob", match[2]!])!, end = blob.lastIndexOf(10) + 1, bytes = blob.subarray(0, end);
+      result.push({ source: remoteSource, path: match[3]!, offset: end, hash: digest(bytes), bytes, local: false, tailBytes: blob.length - end, commit });
+    }
+    if (previousCommit) for (const old of archived(root, generation, previousCommit).segments) {
+      const next = result.find(segment => segment.path === old.path);
+      if (!next || next.offset < old.offset || digest(next.bytes.subarray(0, old.offset)) !== old.hash) failure();
+    }
+    legacyEntries(result); return result;
+  } catch { return failure(); }
+}
+function immutable(path: string, bytes: Buffer): void {
+  const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${randomBytes(16).toString("hex")}.tmp`);
+  const fd = openSync(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+  try {
+    try { let at = 0; while (at < bytes.length) { const wrote = writeSync(fd, bytes, at, bytes.length - at); if (wrote <= 0) failure(); at += wrote; } fsyncSync(fd); } finally { closeSync(fd); }
+    try { linkSync(temporary, path); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      const before = lstatSync(path); if (!before.isFile() || before.isSymbolicLink()) failure();
+      const existing = openSync(path, constants.O_RDWR | constants.O_NOFOLLOW);
+      try {
+        const stat = fstatSync(existing);
+        if (stat.dev !== before.dev || stat.ino !== before.ino || !readFileSync(existing).equals(bytes)) failure();
+        // Matching bytes after an interrupted capture still need a durable-data fence before activation.
+        fsyncSync(existing);
+      } finally { closeSync(existing); }
+    }
+    fsyncDirectory(dirname(path));
+  } finally { try { unlinkSync(temporary); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; } }
+}
+/** Under the generation mutation fence, publish immutable cached blobs only after explicit sync's fixed-ref CAS. */
+export function captureLegacyMain(homeM: string, generation: string, commit: string, previousCommit?: string): void {
+  try {
+    const root = realPath(homeM), current = legacyHead(root, generation), cache = cacheDirectory(root, generation);
+    if (!cache || previousCommit !== current && current !== commit) failure();
+    if (cachedGit(cache, ["rev-parse", "--verify", "refs/remotes/legacy/main^{commit}"])?.toString("utf8").trim() !== commit) failure();
+    const segments = readLegacyGitSnapshot(root, generation, commit, current);
+    const dir = join(fixedGeneration(root, generation), "bridge-snapshots");
+    for (const target of [dir, join(dir, commit), join(dir, commit, "log")]) {
+      if (!directory(target, true)) mkdirSync(target, { mode: 0o700 });
+    }
+    for (const segment of segments) immutable(join(dir, commit, segment.path), segment.bytes);
+    const prior = current === commit ? archived(root, generation, commit).previousCommit : current;
+    const manifest: LegacyArchive = { schema: "agent-mem.legacy-snapshot/v1", generation, commit, ...(prior ? { previousCommit: prior } : {}), segments: segments.map(({ path, offset, hash, tailBytes }) => ({ path, offset, hash, tailBytes })) };
+    immutable(join(dir, commit, "snapshot.json"), Buffer.from(canonicalJSON(manifest) + "\n"));
+    for (const target of [join(dir, commit, "log"), join(dir, commit), dir]) fsyncDirectory(target);
+    writeProfileJSON(join(fixedGeneration(root, generation), "bridge-snapshot.json"), { schema: "agent-mem.legacy-head/v1", generation, commit });
+  } catch { return failure(); }
+}

package/src/memory/commands.ts

@@ -9,6 +9,8 @@ export interface MemoryCommandOptions {
   open: () => MemoryStore;
   readable: (notes: View[]) => View[];
   importPolicy: () => (text: string) => boolean;
+  /** Explicit person-status receipt; model-facing hosts omit this callback. */
+  onBridgeStatus?: (status: { skippedRows: number } | undefined) => void;
 }
 export interface GoalCommandOptions {
   store?: MemoryStore;
@@ -129,7 +131,10 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
       case "rebuild": { store.rebuild(); const c = store.counts(); return `rebuilt the index from ${c.segments} segment${c.segments === 1 ? "" : "s"}: ${c.long} long-term, ${c.short} short-term entries`; }
       default: return fail(MEMORY_USAGE);
     }
-  } finally { if (!opts.store) store.close(); }
+  } finally {
+    try { opts.onBridgeStatus?.(store.bridgeStatus()); }
+    finally { if (!opts.store) store.close(); }
+  }
 }
 
 const goalOne = (g: GoalView, me: string) => `${g.id.slice(0, 8)}  ${g.state.padEnd(7)} ${g.title}${g.scope === "shared" ? "  [shared]" : ""}  ${leaseText(g, me)}`;