@staix/agent-mem 0.2.0 → 0.3.0

package/src/memory/generation.ts

@@ -0,0 +1,143 @@
+import { createHash, randomBytes } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, lstatSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { mutationDatabase } from "./mutation.ts";
+import { dirname, join } from "node:path";
+import { canonicalPath, processLiveness, processSignature, realPath } from "./platform.ts";
+
+export interface BoundProfile {
+  kind: "shared-v1" | "generation";
+  /** Canonical direct memory directory, not the historical parent-home option. */
+  home: string;
+  dir: string;
+  generation?: string;
+  selectorRevision: string;
+}
+export type ProfileInput = "shared-v1" | { generation: string };
+export interface ProfileSelector { schema: "agent-mem.profile/v1"; kind: "shared-v1" | "generation"; generation?: string }
+export interface GenerationDescriptor { schema: "agent-mem.generation/v1"; generation: string; legacySchema: "agent-hub.memory/v1" }
+export interface GenerationSeal { schema: "agent-mem.generation-seal/v1"; generation: string; descriptorHash: string; sourceDigest: string }
+export const PROFILE_LOCK_TIMEOUT_MS = 3000;
+export const LOCAL_METADATA_MAX_BYTES = 262_144;
+export const validGeneration = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{32}$/.test(value);
+export function canonicalJSON(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJSON).join(",")}]`;
+  if (value && typeof value === "object") return `{${Object.entries(value).filter(([, item]) => item !== undefined).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => `${JSON.stringify(key)}:${canonicalJSON(item)}`).join(",")}}`;
+  return JSON.stringify(value);
+}
+export const hashJSON = (value: unknown): string => createHash("sha256").update(canonicalJSON(value)).digest("hex");
+const unavailable = (): never => { throw new Error("memory profile metadata unavailable or invalid; inspect the local profile before continuing"); };
+
+/** Fixed metadata paths are regular files; absent means absent, never unreadable or a symlink. */
+export function readProfileJSON(path: string, limit = LOCAL_METADATA_MAX_BYTES): unknown | undefined {
+  try {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > limit) return unavailable();
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; return unavailable(); }
+}
+function keys(value: object, allowed: string[]): boolean { return Object.keys(value).every(key => allowed.includes(key)); }
+export function readSelector(memoryDir: string): { selector?: ProfileSelector; revision: string } {
+  const value = readProfileJSON(join(memoryDir, "profile.json"));
+  if (value === undefined) return { revision: "absent" };
+  if (!value || typeof value !== "object" || Array.isArray(value) || !keys(value, ["schema", "kind", "generation"])) return unavailable();
+  const selector = value as ProfileSelector;
+  if (selector.schema !== "agent-mem.profile/v1" || !["shared-v1", "generation"].includes(selector.kind)
+    || (selector.kind === "generation" ? !validGeneration(selector.generation) : selector.generation !== undefined)) return unavailable();
+  return { selector, revision: hashJSON(selector) };
+}
+export const selectorRevision = (memoryDir: string): string => readSelector(memoryDir).revision;
+export function generationDescriptor(generation: string): GenerationDescriptor {
+  if (!validGeneration(generation)) return unavailable();
+  return { schema: "agent-mem.generation/v1", generation, legacySchema: "agent-hub.memory/v1" };
+}
+export function generationDir(memoryDir: string, generation: string): string {
+  if (!validGeneration(generation)) return unavailable();
+  const generations = join(memoryDir, "generations"), dir = join(generations, generation);
+  for (const path of [generations, dir]) if (existsSync(path) && (lstatSync(path).isSymbolicLink() || !lstatSync(path).isDirectory())) return unavailable();
+  return dir;
+}
+export function validateGeneration(memoryDir: string, generation: string): string {
+  const dir = generationDir(memoryDir, generation), expected = generationDescriptor(generation);
+  for (const folder of ["log", "local"]) {
+    const path = join(dir, folder);
+    if (!existsSync(path) || !lstatSync(path).isDirectory() || lstatSync(path).isSymbolicLink()) return unavailable();
+  }
+  if (canonicalJSON(readProfileJSON(join(dir, "generation.json"), 4096)) !== canonicalJSON(expected)) return unavailable();
+  const seal = readProfileJSON(join(dir, "generation-seal.json"), 4096) as GenerationSeal | undefined;
+  if (!seal || !keys(seal, ["schema", "generation", "descriptorHash", "sourceDigest"]) || seal.schema !== "agent-mem.generation-seal/v1" || seal.generation !== generation
+    || seal.descriptorHash !== hashJSON(expected) || !/^[a-f0-9]{64}$/.test(seal.sourceDigest)) return unavailable();
+  const sources = readProfileJSON(join(dir, "migration-sources.json")) as { schema?: unknown; sources?: unknown; legacyCommit?: unknown } | undefined;
+  if (!sources || sources.schema !== "agent-mem.migration-sources/v1" || !Array.isArray(sources.sources) || seal.sourceDigest !== hashJSON({ sources: sources.sources, legacyCommit: sources.legacyCommit })) return unavailable();
+  const machine = readProfileJSON(join(dir, "machine.json"), 4096) as { id?: unknown; label?: unknown } | undefined;
+  if (!machine || typeof machine.id !== "string" || !/^[a-f0-9]{16}$/.test(machine.id) || typeof machine.label !== "string") return unavailable();
+  return dir;
+}
+export function resolveProfile(memoryDir: string, explicit?: ProfileInput): BoundProfile {
+  const home = existsSync(memoryDir) ? realPath(memoryDir) : canonicalPath(memoryDir), selected = readSelector(home);
+  if (explicit !== undefined && explicit !== "shared-v1" && (!explicit || typeof explicit !== "object" || !keys(explicit, ["generation"]) || !validGeneration(explicit.generation))) return unavailable();
+  const generation = explicit === "shared-v1" ? undefined : explicit?.generation ?? (selected.selector?.kind === "generation" ? selected.selector.generation : undefined);
+  return generation ? { kind: "generation", home, dir: validateGeneration(home, generation), generation, selectorRevision: selected.revision }
+    : { kind: "shared-v1", home, dir: home, selectorRevision: selected.revision };
+}
+
+export function fsyncDirectory(path: string): void { const fd = openSync(path, "r"); try { fsyncSync(fd); } finally { closeSync(fd); } }
+/** Caller owns the home-wide profile lock for selector updates and generation fences for generation metadata. */
+export function writeProfileJSON(path: string, value: unknown): void {
+  let serialized: string;
+  try {
+    serialized = canonicalJSON(value) + "\n";
+    JSON.parse(serialized);
+    if (Buffer.byteLength(serialized, "utf8") > LOCAL_METADATA_MAX_BYTES) return unavailable();
+  } catch { return unavailable(); }
+  // Match the reader's byte limit, including newline, before creating any temporary or replacing existing metadata.
+  const temporary = `${path}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+  const fd = openSync(temporary, "wx", 0o600);
+  try { writeFileSync(fd, serialized); fsyncSync(fd); } finally { closeSync(fd); }
+  renameSync(temporary, path); fsyncDirectory(dirname(path));
+}
+export async function withProfileLock<T>(memoryDir: string, work: () => T | Promise<T>): Promise<T> {
+  const signature = processSignature(process.pid);
+  if (!signature) throw new Error("cannot establish profile lock ownership");
+  const file = join(memoryDir, "profile.lock"), owner = canonicalJSON({ pid: process.pid, signature, token: randomBytes(16).toString("hex") });
+  const deadline = Date.now() + PROFILE_LOCK_TIMEOUT_MS;
+  for (;;) {
+    let acquired = false;
+    const fence = mutationDatabase(memoryDir);
+    let fenced = false;
+    try {
+      // Serialize the complete stale-owner probe/unlink/recreate sequence, then release before waiting on a live owner.
+      fence.run(`PRAGMA busy_timeout = ${Math.max(1, Math.min(25, deadline - Date.now()))}`);
+      try { fence.run("BEGIN IMMEDIATE"); fenced = true; } catch { /* bounded contention: retry after releasing connection */ }
+      if (fenced) for (let probe = 0; probe < 2; probe++) {
+        let fd: number;
+        try { fd = openSync(file, "wx", 0o600); }
+        catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw new Error("profile lock unavailable");
+          try {
+            if (!lstatSync(file).isFile() || lstatSync(file).isSymbolicLink()) break;
+            const previous = readFileSync(file, "utf8"), record = JSON.parse(previous) as { pid?: unknown; signature?: unknown };
+            if (typeof record.signature === "string" && record.signature && processLiveness(record.pid, record.signature) === "gone" && readFileSync(file, "utf8") === previous) {
+              unlinkSync(file); continue;
+            }
+          } catch { /* live, malformed or unknown owner cannot be stolen */ }
+          break;
+        }
+        try { writeFileSync(fd, owner); fsyncSync(fd); acquired = true; } finally { closeSync(fd); }
+        break;
+      }
+    } finally {
+      if (fenced) fence.run("ROLLBACK");
+      fence.close();
+    }
+    if (!acquired) {
+      if (Date.now() >= deadline) throw new Error("profile lock held by a live or unknown owner");
+      await new Promise(resolve => setTimeout(resolve, Math.min(25, Math.max(1, deadline - Date.now()))));
+      continue;
+    }
+    try { return await work(); }
+    finally {
+      // A live owner's token cannot be reclaimed; do not remove a file another actor replaced.
+      if (existsSync(file) && !lstatSync(file).isSymbolicLink() && readFileSync(file, "utf8") === owner) { unlinkSync(file); fsyncDirectory(memoryDir); }
+    }
+  }
+}

package/src/memory/migrate.ts

@@ -0,0 +1,216 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { legacyEntries, legacyHead, readLegacySnapshot, type LegacyCheckpoint } from "./bridge.ts";
+import { acquireMutation } from "./mutation.ts";
+import { canonicalPath, realPath } from "./platform.ts";
+import { canonicalJSON, fsyncDirectory, generationDescriptor, generationDir, hashJSON, readProfileJSON, readSelector, resolveProfile, validGeneration, withProfileLock, writeProfileJSON, type BoundProfile } from "./generation.ts";
+
+export interface SourcePrefix extends LegacyCheckpoint { tailBytes: number }
+interface MigrationJournal {
+  schema: "agent-mem.migration/v1";
+  generation: string;
+  selectorRevision: string;
+  phase: "captured" | "built" | "sealed" | "active";
+  sources: SourcePrefix[];
+  machine: { id: string; label: string };
+  legacyCommit?: string;
+}
+export interface MigrationCounts {
+  validRows: number;
+  skippedRows: number;
+  byOp: Record<string, number>;
+  byTier: Record<string, number>;
+  tailBytes: number;
+  expiredRows: number;
+  eligibleRows: number;
+}
+export interface MigrationResult {
+  mode: MigrateOptions["mode"];
+  profile: BoundProfile;
+  counts?: MigrationCounts;
+  alreadyActive?: boolean;
+  consequence: string;
+}
+export type MigrationCheckpoint = "after-seal" | "before-selector" | "after-selector";
+export interface MigrateOptions {
+  /** Direct M, with no historical parent-home conversion. */
+  memoryDir: string;
+  mode: "dry-run" | "apply" | "resume" | "deactivate";
+  generation?: string;
+  authorizedPerson: boolean;
+  tty: boolean;
+  /** Trusted builder must verify complete incremental/rebuild table equality. Injection is for crash fixtures. */
+  buildIndex?: (profile: BoundProfile, sources: readonly SourcePrefix[], legacyCommit?: string) => void | Promise<void>;
+  now?: () => number;
+  /** Trusted fault-injection callback for crash recovery fixtures; no protocol data or authority. */
+  checkpoint?: (stage: MigrationCheckpoint) => void | Promise<void>;
+}
+const changed = (): never => { throw new Error("migration source or selector changed; inspect local migration state before continuing"); };
+const consequence = "Generation writes never enter shared v1; legacy writers may continue. Deactivation omits generation-only notes and prune decisions.";
+/** Capture only complete authored prefixes. This performs no writes, lock creation, index opens or network. */
+export function readMigrationSources(memoryDir: string, generation?: string): SourcePrefix[] {
+  const commit = generation ? legacyHead(memoryDir, generation) : undefined;
+  return readLegacySnapshot(memoryDir, { generation, commit }).map(({ bytes: _bytes, local: _local, ...source }) => source);
+}
+export function readMigrationPrefix(memoryDir: string, source: SourcePrefix, generation?: string): Buffer {
+  return readLegacySnapshot(memoryDir, { generation, commit: source.commit, limits: [source] })[0]!.bytes;
+}
+function verifySources(memoryDir: string, generation: string, sources: readonly SourcePrefix[], legacyCommit?: string): void {
+  readLegacySnapshot(memoryDir, { generation, commit: legacyCommit, limits: sources });
+}
+
+function identity(memoryDir: string): { id: string; label: string } {
+  const value = readProfileJSON(join(memoryDir, "machine.json"), 4096) as { id?: unknown; label?: unknown } | undefined;
+  if (!value || typeof value.id !== "string" || !/^[a-f0-9]{16}$/.test(value.id) || typeof value.label !== "string") throw new Error("initialize a valid legacy machine identity before migration");
+  return { id: value.id, label: value.label };
+}
+function journalAt(memoryDir: string): string { return join(memoryDir, "migration.json"); }
+function readJournal(memoryDir: string): MigrationJournal {
+  const value = readProfileJSON(journalAt(memoryDir)) as MigrationJournal | undefined;
+  if (!value || value.schema !== "agent-mem.migration/v1" || !validGeneration(value.generation) || !["captured", "built", "sealed", "active"].includes(value.phase)
+    || !(value.selectorRevision === "absent" || /^[a-f0-9]{64}$/.test(value.selectorRevision)) || !Array.isArray(value.sources)
+    || !value.machine || !/^[a-f0-9]{16}$/.test(value.machine.id) || typeof value.machine.label !== "string") throw new Error("no valid resumable migration journal");
+  for (const source of value.sources) if (!["legacy-local", "legacy-main"].includes(source.source) || typeof source.path !== "string" || !Number.isSafeInteger(source.offset) || source.offset < 0 || !/^[a-f0-9]{64}$/.test(source.hash)
+    || !Number.isSafeInteger(source.tailBytes) || source.tailBytes < 0) throw new Error("invalid migration source receipt");
+  return value;
+}
+async function defaultBuild(profile: BoundProfile, sources: readonly SourcePrefix[], legacyCommit?: string): Promise<void> {
+  const core = await import("./store.ts");
+  await core.buildGenerationIndex(profile, sources, legacyCommit);
+}
+async function counts(memoryDir: string, generation: string | undefined, now: number, limits?: readonly SourcePrefix[], capturedCommit?: string): Promise<MigrationCounts> {
+  const core = await import("./store.ts");
+  let skippedRows = 0;
+  const commit = capturedCommit ?? (generation ? legacyHead(memoryDir, generation) : undefined);
+  const segments = readLegacySnapshot(memoryDir, { generation, commit, ...(limits ? { limits } : {}), onMalformed: () => skippedRows++ });
+  const rows = legacyEntries(segments, { onMalformed: () => {} });
+  const result = core.summarizeRawExpiry(rows.map(row => canonicalJSON(row)), now, segments.reduce((sum, source) => sum + source.tailBytes, 0));
+  return { ...result, skippedRows };
+}
+
+function rememberJournal(memoryDir: string, journal: MigrationJournal): void {
+  writeProfileJSON(journalAt(memoryDir), journal);
+}
+function writeSources(memoryDir: string, journal: MigrationJournal): void {
+  writeProfileJSON(join(generationDir(memoryDir, journal.generation), "migration-sources.json"),
+    { schema: "agent-mem.migration-sources/v1", sources: journal.sources, legacyCommit: journal.legacyCommit });
+}
+
+export async function migrate(options: MigrateOptions): Promise<MigrationResult> {
+  if (options.authorizedPerson !== true || options.tty !== true) throw new Error("migration requires an authorized person in a terminal");
+  if (!["dry-run", "apply", "resume", "deactivate"].includes(options.mode) || options.generation !== undefined && !validGeneration(options.generation)) throw new Error("invalid migration request");
+  const memoryDir = existsSync(options.memoryDir) ? realPath(options.memoryDir) : canonicalPath(options.memoryDir);
+  const selection = readSelector(memoryDir);
+  // Explicit undo reads only the selector: broken/missing G must not make the escape back to v1 impossible.
+  const selectedG = selection.selector?.kind === "generation" ? selection.selector.generation : undefined;
+  const initial: BoundProfile = options.mode === "deactivate"
+    ? { kind: selectedG ? "generation" : "shared-v1", home: memoryDir, dir: selectedG ? join(memoryDir, "generations", selectedG) : memoryDir, generation: selectedG, selectorRevision: selection.revision }
+    : resolveProfile(memoryDir);
+  if (options.mode === "dry-run") {
+    return { mode: options.mode, profile: initial, counts: await counts(memoryDir, options.generation ?? initial.generation, (options.now ?? Date.now)()), consequence };
+  }
+  return withProfileLock(memoryDir, async () => {
+    const selected = readSelector(memoryDir);
+    if (selected.revision !== initial.selectorRevision) return changed();
+    if (options.mode === "deactivate") {
+      let releaseGeneration: (() => void) | undefined;
+      try {
+        if (initial.kind === "generation") {
+          // Use an existing safe fence when available; never create, repair or validate corrupt generation state.
+          const parent = join(memoryDir, "generations"), file = join(initial.dir, "mutation-lock.db");
+          const safeDirectory = (path: string) => existsSync(path) && lstatSync(path).isDirectory() && !lstatSync(path).isSymbolicLink();
+          if (safeDirectory(parent) && safeDirectory(initial.dir) && existsSync(file) && lstatSync(file).isFile() && !lstatSync(file).isSymbolicLink()) {
+            let unavailable = false;
+            try { releaseGeneration = acquireMutation(initial.dir); } catch { unavailable = true; }
+            if (!unavailable && !releaseGeneration) throw new Error("generation mutation lock is busy");
+          }
+          if (readSelector(memoryDir).revision !== initial.selectorRevision) return changed();
+          writeProfileJSON(join(memoryDir, "profile.json"), { schema: "agent-mem.profile/v1", kind: "shared-v1" });
+        }
+        return { mode: options.mode, profile: resolveProfile(memoryDir), consequence };
+      } finally { releaseGeneration?.(); }
+    }
+    // Migration apply/resume never initialize an absent or invalid legacy identity.
+    const machine = identity(memoryDir);
+    let journal: MigrationJournal;
+    if (options.mode === "resume") {
+      journal = readJournal(memoryDir);
+      if (options.generation !== undefined && options.generation !== journal.generation) return changed();
+    } else {
+      if (initial.kind === "generation") {
+        if (options.generation !== undefined && options.generation !== initial.generation) throw new Error("deactivate the current generation before selecting another");
+        return { mode: options.mode, profile: initial, alreadyActive: true, counts: await counts(memoryDir, initial.generation, (options.now ?? Date.now)()), consequence };
+      }
+      if (existsSync(journalAt(memoryDir))) {
+        const previous = readJournal(memoryDir);
+        if (previous.phase !== "active") throw new Error("unfinished migration requires explicit resume");
+      }
+      const generation = options.generation ?? randomBytes(16).toString("hex");
+      const dir = generationDir(memoryDir, generation);
+      let generationMachine = machine;
+      if (existsSync(dir)) {
+        // Reopening a sealed, same-machine generation is explicit selection, not recovery of an unknown staging dir.
+        resolveProfile(memoryDir, { generation });
+        const existing = readProfileJSON(join(dir, "machine.json")) as { id?: unknown; label?: unknown } | undefined;
+        if (!existing || existing.id !== machine.id || typeof existing.label !== "string") return changed();
+        generationMachine = { id: machine.id, label: existing.label };
+      }
+      const releaseLegacy = acquireMutation(memoryDir);
+      if (!releaseLegacy) throw new Error("legacy mutation lock is busy");
+      let sources: SourcePrefix[], legacyCommit: string | undefined;
+      try {
+        legacyCommit = existsSync(dir) ? legacyHead(memoryDir, generation) : undefined;
+        const previous = existsSync(dir) ? readProfileJSON(join(dir, "migration-sources.json")) as { sources?: SourcePrefix[]; legacyCommit?: string } | undefined : undefined;
+        const segments = readLegacySnapshot(memoryDir, { generation, commit: legacyCommit, previousCommit: previous?.legacyCommit, checkpoints: previous?.sources });
+        sources = segments.map(({ bytes: _bytes, local: _local, ...source }) => source);
+      } finally { releaseLegacy(); }
+      journal = { schema: "agent-mem.migration/v1", generation, selectorRevision: initial.selectorRevision, phase: "captured", sources, machine: generationMachine, legacyCommit };
+      // Persist G before creating any staging state, so crash recovery cannot invent a second generation.
+      rememberJournal(memoryDir, journal);
+    }
+    const dir = generationDir(memoryDir, journal.generation);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    for (const folder of ["log", "local"]) mkdirSync(join(dir, folder), { recursive: true, mode: 0o700 });
+    for (const [name, value] of [["generation.json", generationDescriptor(journal.generation)], ["machine.json", journal.machine]] as const) {
+      const prior = readProfileJSON(join(dir, name));
+      if (prior === undefined) writeProfileJSON(join(dir, name), value);
+      else if (canonicalJSON(prior) !== canonicalJSON(value)) return changed();
+    }
+    rememberJournal(memoryDir, journal);
+    fsyncDirectory(join(memoryDir, "generations")); fsyncDirectory(memoryDir);
+    if (selected.selector?.kind === "generation" && selected.selector.generation === journal.generation) {
+      const profile = resolveProfile(memoryDir);
+      journal.phase = "active"; rememberJournal(memoryDir, journal);
+      return { mode: options.mode, profile, alreadyActive: true, counts: await counts(memoryDir, journal.generation, (options.now ?? Date.now)(), journal.sources, journal.legacyCommit), consequence };
+    }
+    if (selected.revision !== journal.selectorRevision) return changed();
+    if (canonicalJSON(readProfileJSON(join(dir, "generation.json"))) !== canonicalJSON(generationDescriptor(journal.generation))
+      || canonicalJSON(readProfileJSON(join(dir, "machine.json"))) !== canonicalJSON(journal.machine) || journal.machine.id !== machine.id) return changed();
+    verifySources(memoryDir, journal.generation, journal.sources, journal.legacyCommit);
+    const profile: BoundProfile = { kind: "generation", home: memoryDir, dir, generation: journal.generation, selectorRevision: journal.selectorRevision };
+    const releaseGeneration = acquireMutation(dir);
+    if (!releaseGeneration) throw new Error("generation mutation lock is busy");
+    try {
+      if (journal.phase !== "sealed" && journal.phase !== "active") writeSources(memoryDir, journal);
+      if (journal.phase !== "sealed" && journal.phase !== "active") {
+        await (options.buildIndex ?? defaultBuild)(profile, journal.sources, journal.legacyCommit);
+        journal.phase = "built"; rememberJournal(memoryDir, journal);
+        verifySources(memoryDir, journal.generation, journal.sources, journal.legacyCommit);
+        writeProfileJSON(join(dir, "generation-seal.json"), { schema: "agent-mem.generation-seal/v1", generation: journal.generation,
+          descriptorHash: hashJSON(generationDescriptor(journal.generation)), sourceDigest: hashJSON({ sources: journal.sources, legacyCommit: journal.legacyCommit }) });
+        journal.phase = "sealed"; rememberJournal(memoryDir, journal);
+        if (options.checkpoint) await options.checkpoint("after-seal");
+      }
+      verifySources(memoryDir, journal.generation, journal.sources, journal.legacyCommit);
+      resolveProfile(memoryDir, { generation: journal.generation });
+      if (options.checkpoint) await options.checkpoint("before-selector");
+      if (readSelector(memoryDir).revision !== journal.selectorRevision) return changed();
+      verifySources(memoryDir, journal.generation, journal.sources, journal.legacyCommit);
+      writeProfileJSON(join(memoryDir, "profile.json"), { schema: "agent-mem.profile/v1", kind: "generation", generation: journal.generation });
+      if (options.checkpoint) await options.checkpoint("after-selector");
+      journal.phase = "active"; rememberJournal(memoryDir, journal);
+      return { mode: options.mode, profile: resolveProfile(memoryDir), counts: await counts(memoryDir, journal.generation, (options.now ?? Date.now)(), journal.sources, journal.legacyCommit), consequence };
+    } finally { releaseGeneration(); }
+  });
+}

package/src/memory/ops-contract.ts

@@ -0,0 +1,159 @@
+import type { Entry } from "./store.ts";
+
+export interface PayloadField {
+  type: "string" | "string-array";
+  values?: readonly string[];
+  format?: "utc" | "id";
+  maxLength?: number;
+}
+export interface PayloadSchema {
+  version: 1;
+  required: readonly string[];
+  fields: Readonly<Record<string, PayloadField>>;
+  /** Reader tolerance retained for pre-existing v1 logs, not permission to omit writer fields. */
+  legacyOptional: readonly string[];
+}
+export interface OpContract {
+  status: "v1-equal" | "truth-changing";
+  implemented: boolean;
+  payloadVersion: string;
+  required: readonly string[];
+  payloadSchema: PayloadSchema | null;
+  immutableTargets: string;
+  placement: string;
+  precedence: string;
+  identity: string;
+  crashBoundary: string;
+  fixtures: readonly string[];
+}
+
+const text: PayloadField = { type: "string" };
+const id: PayloadField = { type: "string", format: "id" };
+const utc: PayloadField = { type: "string", format: "utc" };
+const strings: PayloadField = { type: "string-array" };
+const base: Record<string, PayloadField> = {
+  schema: { type: "string", values: ["agent-hub.memory/v1"] }, op: text,
+  id, at: utc, machine: { type: "string", maxLength: 64 },
+};
+const identity = "sha256(canonical complete payload without id), first 32 hex; schema, at and machine participate; replay INSERT OR IGNORE";
+const crash = "complete newline is authoritative; append precedes derived-index refresh; incomplete tail waits; refresh/rebuild recovers a complete append";
+function current(op: Entry["op"], fields: Record<string, PayloadField>, required: string[], placement: string, targets: string, precedence: string, legacyOptional: string[] = []): OpContract {
+  const keys = [...Object.keys(base), ...required];
+  return Object.freeze<OpContract>({
+    status: "v1-equal", implemented: true, payloadVersion: "agent-hub.memory/v1",
+    required: keys, payloadSchema: { version: 1, required: keys, fields: { ...base, op: { type: "string", values: [op] }, ...fields }, legacyOptional },
+    immutableTargets: targets, placement, precedence, identity, crashBoundary: crash,
+    fixtures: [`v1-${op}`],
+  });
+}
+function ordinaryOp(op: Entry["op"], placement: string, targets: string, precedence: string, dated = false): OpContract {
+  const hasBy = !["forget", "confirm", "reject"].includes(op);
+  const by = dated ? utc : op === "supersede" ? id : op === "goal_state"
+    ? { type: "string" as const, values: ["open", "active", "blocked", "done", "dropped"] } : text;
+  return current(op, { target: op === "settle" ? { ...text, maxLength: 400 } : id, actor: text, ...(hasBy ? { by } : {}) },
+    ["target", "actor", ...(hasBy ? ["by"] : [])], placement, targets, precedence, ["actor"]);
+}
+
+/** Exhaustive over the current writer's Entry union: adding an op requires a contract in this registry. */
+const v1 = {
+  note: current("note", {
+    project: { type: "string", maxLength: 400 }, scope: { type: "string", values: ["project", "shared"] },
+    tier: { type: "string", values: ["short", "long"] }, kind: { type: "string", values: ["decision", "finding", "contract", "fail"] },
+    peer: { type: "string", maxLength: 64 }, title: text, text, task: text, about: strings,
+    supersedes: id, promotedFrom: id, source: { type: "string", values: ["hub", "person", "claude-mem"] }, expires: utc,
+  }, ["project", "scope", "tier", "kind", "peer", "text", "about", "source"], "short -> local; long -> synced",
+  "optional supersedes and promotedFrom are full immutable entry ids; about nodes and task keys retain v1 identity",
+  "newest at/id first; note supersedes joins supersede ops; promoted source hidden; expiry trusts wall clock (declared C05 rollback ceiling)", ["source"]),
+  forget: ordinaryOp("forget", "follows target authored segment: local when target.local, synced otherwise", "target entry id, promotion ancestry included", "forget wins independent of timestamp; never edits source rows"),
+  supersede: ordinaryOp("supersede", "follows old target authored segment: local when old.local, synced otherwise; replacement visibility never narrower", "target old id; by replacement id, never a mutable alias", "latest relation by at then replacement id; earliest cycle relation yields; gone replacement releases old entry"),
+  demote: ordinaryOp("demote", "synced for long targets; local for local short targets", "target entry id; by fixed expiry", "latest demotion at/id fixes short deadline; clock rollback retains C05 ceiling", true),
+  settle: ordinaryOp("settle", "local", "target immutable project#task@created key; by fixed expiry", "earliest settlement deadline wins; eligible held notes wait for promotion; clock rollback retains C05 ceiling", true),
+  goal: current("goal", {
+    project: { type: "string", maxLength: 400 }, scope: { type: "string", values: ["project", "shared"] },
+    title: { type: "string", maxLength: 400 }, milestones: strings, dependsOn: strings, actor: text,
+  }, ["project", "scope", "title", "milestones", "dependsOn", "actor"], "synced", "dependsOn goal ids; goal's full id is its immutable identity",
+  "goals newest at first; initial state open; subsequent state/link/lease ops reduce separately", ["scope", "actor"]),
+  goal_state: ordinaryOp("goal_state", "synced", "target full goal id; by open|active|blocked|done|dropped", "latest valid state by at/id wins"),
+  goal_link: ordinaryOp("goal_link", "synced", "target full goal id; by immutable project#task@created key", "unique authored intent; links retain at/machine; identical payload replays once"),
+  lease: ordinaryOp("lease", "synced", "target full goal id; by fixed UTC expiry; machine is holder identity", "claims after last forced claim; latest per machine; earliest uninterrupted active claim then machine id wins; expired holder is metadata", true),
+  lease_force: ordinaryOp("lease_force", "synced", "target full goal id; by fixed UTC expiry", "latest forced claim at/id discards earlier claims, then ordinary lease ordering applies", true),
+  suggest: ordinaryOp("suggest", "synced", "target source entry id; by relation:destination id", "suggestions stay dashed, never confirmed graph evidence; suggestion full id is verdict target"),
+  confirm: ordinaryOp("confirm", "synced", "target immutable suggestion id", "latest confirm/reject by at/id wins; confirmation adds evidence relation only for valid endpoints"),
+  reject: ordinaryOp("reject", "synced", "target immutable suggestion id", "latest confirm/reject by at/id wins; rejection excludes suggested relation from evidence"),
+} satisfies Record<Entry["op"], OpContract>;
+
+function blocked(op: string): OpContract {
+  return Object.freeze({ status: "truth-changing", implemented: false, payloadVersion: "unimplemented", required: [], payloadSchema: null,
+    immutableTargets: "not defined: no writer", placement: "future generation only; never local or synced shared-v1 segments",
+    precedence: "not defined: person-run generation migration and contracts required first", identity: "not defined: no payload is emitted",
+    crashBoundary: "refused before authoritative append", fixtures: [`deny-${op}`] });
+}
+
+export const V1_OPS: readonly Entry["op"][] = Object.freeze(Object.keys(v1) as Entry["op"][]);
+export const OP_CONTRACTS: Readonly<Record<string, OpContract>> = Object.freeze({ ...v1,
+  prune: blocked("prune"), correct: blocked("correct"), lift: blocked("lift"), consolidate: blocked("consolidate"), group: blocked("group"),
+});
+
+/** No reader inventory or announcement can authorize new truth in shared v1 logs. */
+export function assertSharedV1Op(op: unknown): void {
+  const contract = typeof op === "string" && Object.hasOwn(OP_CONTRACTS, op) ? OP_CONTRACTS[op] : undefined;
+  if (!contract?.implemented || contract.status !== "v1-equal") throw new Error("operation is not allowed in shared v1 segments; a person-run generation migration and contract are required");
+}
+
+/** Separate registry: importing this metadata never authorizes prune in OP_CONTRACTS/shared v1. */
+export interface GenerationPayloadField {
+  type: "string" | "object" | "array";
+  values?: readonly string[];
+  pattern?: string;
+  format?: "canonical-utc";
+  required?: readonly string[];
+  fields?: Readonly<Record<string, GenerationPayloadField>>;
+  additionalProperties?: false;
+  items?: GenerationPayloadField;
+  minItems?: number;
+  maxItems?: number;
+  sortedUniqueBy?: string;
+}
+export interface GenerationOpContract extends Omit<OpContract, "implemented" | "payloadSchema"> {
+  implemented: true;
+  generationOnly: true;
+  targetSemantics: "exact-entry-v1";
+  validator: "validatePruneRow";
+  validation: readonly string[];
+  payloadSchema: {
+    version: 1;
+    required: readonly string[];
+    fields: Readonly<Record<string, GenerationPayloadField>>;
+    additionalProperties: false;
+    maxUtf8Bytes: number;
+  };
+}
+const generationId: GenerationPayloadField = { type: "string", pattern: "^[a-f0-9]{32}$" };
+const authoredHash: GenerationPayloadField = { type: "string", pattern: "^[a-f0-9]{64}$" };
+const canonicalUtc: GenerationPayloadField = { type: "string", format: "canonical-utc" };
+const pruneRequired = ["schema", "op", "generation", "at", "machine", "actor", "placement", "cutoff", "targets", "id"] as const;
+export const PRUNE_GENERATION_CONTRACT: GenerationOpContract = Object.freeze<GenerationOpContract>({
+  status: "truth-changing", implemented: true, generationOnly: true, targetSemantics: "exact-entry-v1", validator: "validatePruneRow",
+  validation: ["exact required keys at each nested level; no additional fields", "canonical UTC; cutoff <= at; each expiredAt <= cutoff", "1..32 targets, strictly sorted unique full ids; canonical row <=16384 UTF-8 bytes", "id equals first 32 hex of canonical complete payload hash excluding id", "generation and authored segment placement match the bound generation/input", "target/basis full authored hashes and explicit expires/by relationship verified separately by reducer; missing witnesses remain pending"],
+  payloadVersion: "agent-mem.prune/v1", required: pruneRequired,
+  payloadSchema: { version: 1, required: pruneRequired, additionalProperties: false, maxUtf8Bytes: 16_384, fields: {
+    schema: { type: "string", values: ["agent-mem.prune/v1"] }, op: { type: "string", values: ["prune"] },
+    generation: generationId, at: canonicalUtc, machine: { type: "string", pattern: "^[a-f0-9]{16}$" },
+    actor: { type: "string", values: ["person"] }, placement: { type: "string", values: ["local", "synced"] }, cutoff: canonicalUtc, id: generationId,
+    targets: { type: "array", minItems: 1, maxItems: 32, sortedUniqueBy: "id", items: {
+      type: "object", required: ["id", "rowHash", "expiredAt", "basis"], additionalProperties: false, fields: {
+        id: generationId, rowHash: authoredHash, expiredAt: canonicalUtc,
+        basis: { type: "object", required: ["kind", "id", "rowHash"], additionalProperties: false, fields: {
+          kind: { type: "string", values: ["note", "demote", "settle"] }, id: generationId, rowHash: authoredHash,
+        } },
+      },
+    } },
+  } },
+  immutableTargets: "only explicit full note id plus SHA-256 of complete canonical authored row including id; exact note.expires or demote/settle.by basis id/hash; no implicit TTL/backstop proof or ancestry traversal",
+  placement: "generation local by default; synced only for positively attested public target and basis already in verified cached legacy-main or generation public segments; no policy-free bypass",
+  precedence: "validated exact target is permanently gone, union/idempotent across prune rows; later clock/deadline changes do not revoke it; missing witnesses pending; different IDs and independent replacements survive; raw promotion metadata remains for v1 source hiding",
+  identity: "sha256(canonical complete prune payload excluding id), first 32 hex; generation/at/machine/placement/cutoff/ordered targets participate; rowHash is full SHA-256 of authored witness including id",
+  crashBoundary: "fsync exact local sealed plan, mutation fence, revalidate proofs/policy, append+fsync complete row then refresh; per-row atomicity; retry skips durable IDs; incomplete own tail completes only from identical persisted-plan prefix; mismatched tail refuses",
+  fixtures: ["test/generation-prune.test.ts#only explicit note expires or demote settle by values can prove expiry", "test/generation-prune.test.ts#exact-entry reducer waits for witnesses and cannot be reversed by clock or later deadlines", "test/generation-prune.test.ts#prune partitions private target or basis locally and public attestations bind only public rows", "test/generation-prune.test.ts#prune row shape hashes canonical time ordering placement and byte bounds are strict"],
+});
+export const GENERATION_OP_CONTRACTS: Readonly<Record<"prune", GenerationOpContract>> = Object.freeze({ prune: PRUNE_GENERATION_CONTRACT });

package/src/memory/platform.ts

@@ -82,7 +82,14 @@ export const memoryGitArgv = (args: string[], opts: { credentials?: boolean } =
   ["git", "--no-pager", ...SAFE_CONFIG.filter((c) => !opts.credentials || !CREDENTIAL_KEYS.has(c)).flatMap((c) => ["-c", c]), ...args];
 
 /** The caller's env plus the no-prompt switch; existing keys (childEnv, GIT_OPTIONAL_LOCKS=0) pass through. */
-export const memoryGitEnv = (env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv => ({ ...env, GIT_TERMINAL_PROMPT: "0" });
+export function memoryGitEnv(env: NodeJS.ProcessEnv = process.env, options: { repositoryIsolation?: boolean } = {}): NodeJS.ProcessEnv {
+  const result: NodeJS.ProcessEnv = { ...env, GIT_TERMINAL_PROMPT: "0" };
+  if (options.repositoryIsolation) {
+    for (const key of Object.keys(result)) if (["GIT_DIR", "GIT_COMMON_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY", "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_NAMESPACE", "GIT_PREFIX", "GIT_SHALLOW_FILE", "GIT_GRAFT_FILE", "GIT_REPLACE_REF_BASE", "GIT_CONFIG_COUNT", "GIT_CONFIG_PARAMETERS"].includes(key) || /^GIT_CONFIG_(KEY|VALUE)_/.test(key)) delete result[key];
+    result.GIT_NO_REPLACE_OBJECTS = "1";
+  }
+  return result;
+}
 
 /** spawnSync form of the same call: the env option is merged with memoryGitEnv, everything else passes through. */
 export function memoryGitSync(args: string[], options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns<string> {