@staix/agent-mem 0.12.0 → 0.14.0

package/src/memory/public-prune-activation.ts

@@ -0,0 +1,260 @@
+/** Explicit person-only, forward-only v2 activation. No read/capture path calls this API.
+ * Checkpoints are fault seams after intent, shard marker, selector and intent removal.
+ * A caller resumes an interrupted operation from its immutable direct-profile journal. */
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { canonicalJSON, fsyncDirectory, hashJSON, readSelector, withProfileLock, writeProfileJSON, type BoundProfile } from "./generation.ts";
+import { readShardDescriptor, resolveShardProfile, shardDir, shardKeyHash, userShardDir, SHARDED_V2_FIELDS } from "./shard.ts";
+import { acquireMutation } from "./mutation.ts";
+import { assertNoLiveReaders } from "./reader-lease.ts";
+import { aliasLogPath } from "./aliases.ts";
+import { realPath } from "./platform.ts";
+import { buildPublicPruneIndex } from "./store.ts";
+import { reducePublicPruneInputs } from "./public-prune-inputs.ts";
+import { PUBLIC_PRUNE_INTENT, publicPruneViewHash, readPublicPruneViewForActivation, validatePublicPruneView, type PublicPruneViewV1 } from "./public-prune-view.ts";
+
+export type PublicPruneActivationStage = "after-intent" | "after-shards" | "after-profile" | "after-remove";
+export interface PublicPruneActivationOptions {
+  memoryDir: string; mode: "dry-run" | "apply" | "resume"; authorizedPerson: boolean; tty: boolean;
+  view?: PublicPruneViewV1; checkpoint?: (stage: PublicPruneActivationStage) => void | Promise<void>;
+}
+export interface PublicPruneActivationResult { mode: PublicPruneActivationOptions["mode"]; generation: string; active: boolean; alreadyActive?: boolean; realms: number; viewHash: string; maskBuildCheck: "deferred" | "verified" }
+interface Realm { key: string; profile: BoundProfile; metadata: string; sourceHash: string; native: string[] }
+interface Intent {
+  schema: "agent-mem.public-prune-activation/v1"; home: string; generation: string; aliases: string;
+  previousProfile: string; previousShards: string; finalProfile: string; finalShards: string; finalProfileHash: string; finalShardsHash: string;
+  view: PublicPruneViewV1; realms: Realm[];
+}
+// ponytail: one complete 1 MiB journal; a larger installation needs a versioned segmented intent.
+const MAX = 1024 * 1024;
+const fail = (): never => { throw new Error("public prune activation unavailable; inspect or resume the pending activation"); };
+function guard(ok: unknown): asserts ok { if (!ok) fail(); }
+const hex = (v: unknown, n: number): v is string => typeof v === "string" && v.length === n && /^[a-f0-9]+$/.test(v);
+const object = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+const exact = (v: Record<string, unknown>, keys: string[]) => Reflect.ownKeys(v).length === keys.length && keys.every(key => Object.hasOwn(v, key));
+function owned(path: string, directory = false, links = 1) {
+  const stat = lstatSync(path); guard(!stat.isSymbolicLink() && (directory ? stat.isDirectory() : stat.isFile() && stat.nlink === links)
+    && stat.uid === process.getuid?.() && (stat.mode & 0o077) === 0); return stat;
+}
+function raw(path: string, optional = false, links = 1): string {
+  if (optional && !lstatSync(path, { throwIfNoEntry: false })) return "absent";
+  const stat = owned(path, false, links); guard((optional || stat.size > 0) && stat.size <= MAX);
+  const bytes = readFileSync(path); guard(bytes.length === stat.size); const next = owned(path, false, links);
+  guard(next.dev === stat.dev && next.ino === stat.ino && next.mtimeMs === stat.mtimeMs);
+  return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+}
+function readProfileBytes(home: string): string {
+  const file = join(home, "profile.json"); if (!lstatSync(file, { throwIfNoEntry: false })) return "absent";
+  const text = raw(file); guard(text !== "absent"); return text;
+}
+const optionalBytes = (file: string) => lstatSync(file, {throwIfNoEntry:false}) ? {exists:true,bytes:raw(file)} : {exists:false};
+const aliases = (home: string) => { const stat = owned(home, true); return hashJSON({ aliases: optionalBytes(aliasLogPath(home)), machine: raw(join(home, "machine.json")), dev: stat.dev, ino: stat.ino }); };
+function metadata(profile: BoundProfile): string {
+  const stat = owned(profile.dir, true);
+  return hashJSON({ dev: stat.dev, ino: stat.ino, files: ["project.json", "generation.json", "generation-seal.json", "migration-sources.json", "machine.json"].map(name => [name, name === "project.json" ? optionalBytes(join(profile.dir, name)) : {exists:true,bytes:raw(join(profile.dir, name))}]) });
+}
+function enumerate(home: string): { key: string; profile: BoundProfile }[] {
+  const result: { key: string; profile: BoundProfile }[] = [], projects = join(home, "projects");
+  if (lstatSync(projects, { throwIfNoEntry: false })) {
+    owned(projects, true); const names = readdirSync(projects).sort(); guard(names.length <= 1024);
+    for (const hash of names) {
+      guard(hex(hash, 16)); const dir = join(projects, hash); owned(dir, true);
+      if (!lstatSync(join(dir, "generation.json"), { throwIfNoEntry: false })) continue;
+      const descriptor = readShardDescriptor(home, hash); guard(descriptor && shardKeyHash(descriptor.key) === hash);
+      result.push({ key: `project:${descriptor.key}`, profile: resolveShardProfile(home, { project: descriptor.key }) });
+    }
+  }
+  if (lstatSync(join(userShardDir(home), "generation.json"), { throwIfNoEntry: false })) result.push({ key: "user", profile: resolveShardProfile(home, { user: true }) });
+  guard(result.length > 0); return result.sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+}
+function realmBinding(home: string, realms: Realm[]): void {
+  const expected = new Set(realms.map(realm => realm.profile.dir)), found = new Set<string>(), projects = join(home, "projects");
+  if (lstatSync(projects, { throwIfNoEntry: false })) for (const name of readdirSync(projects)) {
+    guard(hex(name, 16)); const dir = join(projects, name);
+    if (lstatSync(join(dir, "generation.json"), { throwIfNoEntry: false })) { owned(dir, true); found.add(dir); }
+  }
+  const user = userShardDir(home); if (lstatSync(join(user, "generation.json"), { throwIfNoEntry: false })) { owned(user, true); found.add(user); }
+  guard(found.size === expected.size && [...expected].every(dir => found.has(dir)));
+  for (const realm of realms) guard(metadata(realm.profile) === realm.metadata);
+}
+/** Atomic create-once publication, recovering only this exact complete staging pair. */
+function immutable(file: string, text: string): void {
+  const base = dirname(file); if (!lstatSync(base, { throwIfNoEntry: false })) { mkdirSync(base, { mode: 0o700 }); fsyncDirectory(dirname(base)); } owned(base, true);
+  const bytes = Buffer.from(text), temp = file + ".pending-" + createHash("sha256").update(bytes).digest("hex");
+  if (lstatSync(file, { throwIfNoEntry: false })) {
+    const stat = lstatSync(file);
+    if (stat.nlink === 2) {
+      const pending = owned(temp, false, 2); owned(file, false, 2); guard(stat.dev === pending.dev && stat.ino === pending.ino && stat.size === bytes.length);
+      const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+      try {
+        const opened = fstatSync(fd); guard(opened.dev === stat.dev && opened.ino === stat.ino && opened.nlink === 2 && readFileSync(fd).equals(bytes));
+        for (const name of [file, temp]) { const named = owned(name, false, 2); guard(named.dev === opened.dev && named.ino === opened.ino && named.size === opened.size && named.mtimeMs === opened.mtimeMs); }
+        unlinkSync(temp); fsyncDirectory(base);
+      } finally { closeSync(fd); }
+    }
+    guard(raw(file) === text); return;
+  }
+  if (lstatSync(temp, { throwIfNoEntry: false })) {
+    owned(temp); // Staging is not membership; discard an incomplete crash-left prefix under the profile fence.
+    if (!readFileSync(temp).equals(bytes)) { unlinkSync(temp); fsyncDirectory(base); }
+  }
+  if (!lstatSync(temp, { throwIfNoEntry: false })) {
+    const fd = openSync(temp, "wx", 0o600); try { writeFileSync(fd, bytes); fsyncSync(fd); } finally { closeSync(fd); }
+  } else { const fd = openSync(temp, constants.O_RDONLY | constants.O_NOFOLLOW); try { fsyncSync(fd); } finally { closeSync(fd); } }
+  linkSync(temp, file); fsyncDirectory(base); unlinkSync(temp); fsyncDirectory(base);
+}
+function syncIndex(profile: BoundProfile): void {
+  const file = join(profile.dir, "index-v2.db"); owned(file); const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try { fsyncSync(fd); } finally { closeSync(fd); } fsyncDirectory(profile.dir);
+}
+function nextProfile(realm: Realm, intent: Intent): BoundProfile {
+  return { ...realm.profile, selectorRevision: hashJSON(JSON.parse(intent.finalProfile)), foreignPruneFormat: "agent-mem.public-prune-witness/v1", pruneInputSetHash: publicPruneViewHash(intent.view) };
+}
+/** Existing membership must remain in the new checked cumulative chain, not merely its mask. */
+function validateAdvance(intent: Intent): void {
+  const previous = intent.previousProfile === "absent" ? undefined : JSON.parse(intent.previousProfile);
+  const old = previous?.schema === "agent-mem.profile/v2"
+    ? readPublicPruneViewForActivation(intent.home, previous.pruneInputSetHash, intent.generation)
+    : { realms: {} as Record<string, string> };
+  guard(Object.keys(old.realms).every(key => Object.hasOwn(intent.view.realms, key)));
+  for (const [key, set] of Object.entries(intent.view.realms)) {
+    const realm = intent.realms.find(item => item.key === key); guard(realm);
+    const proof = reducePublicPruneInputs({ dir: realm.profile.dir, realm: key === "user" ? { scope: "user" } : { scope: "project", key: key.slice(8) }, receivingGeneration: intent.generation, inputSetHash: set });
+    const ancestor = old.realms[key]; guard(ancestor === undefined || proof.commitments.includes(ancestor));
+  }
+}
+function verify(intent: Intent, profileBytes: string, shardBytes: string): void {
+  guard(aliases(intent.home) === intent.aliases && readProfileBytes(intent.home) === profileBytes && raw(join(intent.home, "shards.json")) === shardBytes);
+  realmBinding(intent.home, intent.realms);
+  validateAdvance(intent);
+  for (const realm of intent.realms) {
+    const old = buildPublicPruneIndex(realm.profile), next = buildPublicPruneIndex(nextProfile(realm, intent));
+    guard(old.sourceHash === realm.sourceHash && next.sourceHash === realm.sourceHash && realm.native.every(id => old.targets.includes(id) && next.targets.includes(id)));
+  }
+}
+function checkedIntent(value: unknown, home: string): Intent {
+  guard(object(value) && exact(value, ["schema", "home", "generation", "aliases", "previousProfile", "previousShards", "finalProfile", "finalShards", "finalProfileHash", "finalShardsHash", "view", "realms"]));
+  guard(value.schema === "agent-mem.public-prune-activation/v1" && value.home === home && hex(value.generation, 32) && hex(value.aliases, 64));
+  for (const key of ["previousProfile", "previousShards", "finalProfile", "finalShards"]) guard(typeof value[key] === "string" && Buffer.byteLength(value[key] as string) <= MAX);
+  const view = validatePublicPruneView(value.view); guard(view.receivingGeneration === value.generation && Array.isArray(value.realms) && value.realms.length > 0 && value.realms.length <= 1025);
+  const final = JSON.parse(value.finalProfile as string), shards = JSON.parse(value.finalShards as string);
+  const shardFields = new Set<string>(SHARDED_V2_FIELDS);
+  guard(object(shards) && Object.keys(shards).every(key => shardFields.has(key)));
+  guard(hex(value.finalProfileHash, 64) && hex(value.finalShardsHash, 64) && hashJSON(final) === value.finalProfileHash && hashJSON(shards) === value.finalShardsHash);
+  guard(canonicalJSON(final) + "\n" === value.finalProfile && canonicalJSON(shards) + "\n" === value.finalShards
+    && object(final) && exact(final, ["schema", "kind", "generation", "foreignPruneFormat", "pruneInputSetHash"])
+    && final.schema === "agent-mem.profile/v2" && final.generation === value.generation && final.kind === "generation" && final.foreignPruneFormat === "agent-mem.public-prune-witness/v1" && final.pruneInputSetHash === publicPruneViewHash(view)
+    && shards.schema === "agent-mem.shards/v2" && shards.phase === "active" && shards.generation === value.generation && shards.selectorRevision === hashJSON(final));
+  const previousProfile = value.previousProfile === "absent" ? undefined : JSON.parse(value.previousProfile as string), previousShards = JSON.parse(value.previousShards as string);
+  guard(previousProfile === undefined || object(previousProfile)
+    && (previousProfile.schema === "agent-mem.profile/v1" && ["shared-v1", "generation"].includes(String(previousProfile.kind))
+      && (previousProfile.kind === "generation" ? hex(previousProfile.generation, 32) : previousProfile.generation === undefined)
+      || previousProfile.schema === "agent-mem.profile/v2" && previousProfile.kind === "generation" && previousProfile.generation === value.generation));
+  const { schema: _schema, selectorRevision: _revision, ...before } = previousShards;
+  const { schema: _nextSchema, selectorRevision: _nextRevision, ...after } = shards; guard(canonicalJSON(before) === canonicalJSON(after));
+  let previous = "";
+  for (const item of value.realms) {
+    guard(object(item) && exact(item, ["key", "profile", "metadata", "sourceHash", "native"]) && typeof item.key === "string" && item.key > previous && hex(item.metadata, 64) && hex(item.sourceHash, 64)); previous = item.key;
+    guard(object(item.profile)); const profile = item.profile;
+    guard(Object.keys(profile).every(key => ["kind", "home", "dir", "generation", "selectorRevision", "legacyHome", "legacyMainHome", "sharded", "shardKey", "shardUser", "foreignPruneFormat", "pruneInputSetHash"].includes(key)));
+    const key = item.key === "user" ? undefined : item.key.startsWith("project:") ? item.key.slice(8) : fail();
+    const dir = key === undefined ? userShardDir(home) : shardDir(home, key);
+    guard(profile.kind === "generation" && profile.home === home && profile.dir === dir && profile.generation === value.generation && profile.sharded === true
+      && profile.selectorRevision === (previousProfile === undefined ? "absent" : hashJSON(previousProfile))
+      && profile.legacyHome === join(dir, "legacy") && (profile.legacyMainHome === undefined || profile.legacyMainHome === join(dir, "legacy-main"))
+      && (key === undefined ? profile.shardUser === true && profile.shardKey === undefined : profile.shardKey === key && profile.shardUser === undefined));
+    guard(Array.isArray(item.native) && item.native.every(id => hex(id, 32)) && new Set(item.native).size === item.native.length);
+  }
+  guard(Object.keys(view.realms).every(key => (value.realms as Realm[]).some(realm => realm.key === key)));
+  guard(Buffer.byteLength(canonicalJSON(value)) <= MAX); return { ...value, view } as unknown as Intent;
+}
+/** Dry-run reads proof only and defers native/v2 mask building. Apply/resume never roll markers backward. */
+export async function activatePublicPruneView(options: PublicPruneActivationOptions): Promise<PublicPruneActivationResult> {
+  const advanced = lstatSync(join(options.memoryDir,PUBLIC_PRUNE_INTENT),{throwIfNoEntry:false});
+  if (options.mode === "resume" && advanced?.isFile()) {
+    const value=JSON.parse(raw(join(options.memoryDir,PUBLIC_PRUNE_INTENT),false,advanced.nlink));
+    if (value?.schema === "agent-mem.public-prune-advance/v1") {
+      guard(options.authorizedPerson === true && options.tty === true);
+      const {resumePublicPruneAdvance}=await import("./public-prune-advance.ts");
+      const result=await resumePublicPruneAdvance(options.memoryDir,options.checkpoint);
+      return {mode:options.mode,generation:value.generation,active:true,realms:Object.keys(value.view.realms).length,viewHash:result.viewHash,maskBuildCheck:"verified"};
+    }
+  }
+
+  guard(options.authorizedPerson === true && options.tty === true && ["dry-run", "apply", "resume"].includes(options.mode));
+  const home = realPath(options.memoryDir); owned(home, true); const rootStat = lstatSync(home), intentFile = join(home, PUBLIC_PRUNE_INTENT);
+  const pending = lstatSync(intentFile, { throwIfNoEntry: false });
+  let intent: Intent;
+  if (pending) {
+    guard(options.mode === "resume"); const text = raw(intentFile, false, pending.nlink);
+    if (pending.nlink === 2) {
+      const temp = intentFile + ".pending-" + createHash("sha256").update(text).digest("hex"), pair = owned(temp, false, 2);
+      guard(pair.dev === pending.dev && pair.ino === pending.ino);
+    } else guard(pending.nlink === 1);
+    intent = checkedIntent(JSON.parse(text), home); guard(text === canonicalJSON(intent) + "\n");
+    guard(options.view === undefined || canonicalJSON(validatePublicPruneView(options.view)) === canonicalJSON(intent.view));
+  }
+  else {
+    const selection = readSelector(home), previousProfile = readProfileBytes(home), previousShards = raw(join(home, "shards.json")), old = JSON.parse(previousShards);
+    guard(old.phase === "active" && hex(old.generation, 32));
+    const generation = old.generation, view = validatePublicPruneView(options.view ?? (selection.selector?.schema === "agent-mem.profile/v2"
+      ? readPublicPruneViewForActivation(home, selection.selector.pruneInputSetHash, generation)
+      : { schema: "agent-mem.public-prune-view/v1", receivingGeneration: generation, realms: {} })); guard(view.receivingGeneration === generation);
+    const final = { schema: "agent-mem.profile/v2", kind: "generation", generation, foreignPruneFormat: "agent-mem.public-prune-witness/v1", pruneInputSetHash: publicPruneViewHash(view) };
+    const finalShards = { ...old, schema: "agent-mem.shards/v2", selectorRevision: hashJSON(final) };
+    const realms = enumerate(home).map(realm => ({ ...realm, metadata: metadata(realm.profile), sourceHash: "0".repeat(64), native: [] as string[] }));
+    intent = checkedIntent({ schema: "agent-mem.public-prune-activation/v1", home, generation, aliases: aliases(home), previousProfile, previousShards,
+      finalProfile: canonicalJSON(final) + "\n", finalShards: canonicalJSON(finalShards) + "\n", finalProfileHash: hashJSON(final), finalShardsHash: hashJSON(finalShards), view,
+      realms }, home);
+  }
+  validateAdvance(intent);
+  if (options.mode === "dry-run") {
+    guard(readProfileBytes(home) === intent.previousProfile && raw(join(home, "shards.json")) === intent.previousShards && aliases(home) === intent.aliases);
+    realmBinding(home, intent.realms);
+    return { mode: options.mode, generation: intent.generation, active: intent.previousProfile === intent.finalProfile && intent.previousShards === intent.finalShards, realms: intent.realms.length, viewHash: publicPruneViewHash(intent.view), maskBuildCheck: "deferred" };
+  }
+  if (!pending && intent.previousProfile !== "absent" && JSON.parse(intent.previousProfile).schema === "agent-mem.profile/v2") {
+    // Only the first reader-floor transition quiesces. Later views preserve native masks and grow foreign masks in place.
+    const alreadyActive = intent.previousProfile === intent.finalProfile && intent.previousShards === intent.finalShards;
+    if (!alreadyActive) {
+      const { advancePublicPruneView } = await import("./public-prune-advance.ts");
+      await advancePublicPruneView({ memoryDir: home, view: intent.view, expectedRevision: hashJSON(JSON.parse(intent.previousProfile)), checkpoint: options.checkpoint });
+    }
+    return { mode: options.mode, generation: intent.generation, active: true, ...(alreadyActive ? {alreadyActive:true} : {}), realms: intent.realms.length, viewHash: publicPruneViewHash(intent.view), maskBuildCheck: "verified" };
+  }
+  return withProfileLock(home, async () => {
+    const releases: (() => void)[] = [];
+    try {
+      guard(lstatSync(home).dev === rootStat.dev && lstatSync(home).ino === rootStat.ino);
+      const dirs = [...new Set([home, ...intent.realms.map(realm => realm.profile.dir)])].sort();
+      for (const dir of dirs) { assertNoLiveReaders(dir, {includeShards:true}); const release = acquireMutation(dir); guard(release); releases.push(release); }
+      validateAdvance(intent);
+      if (pending) immutable(intentFile, canonicalJSON(intent) + "\n");
+      if (!pending) {
+        guard(readProfileBytes(home) === intent.previousProfile && raw(join(home, "shards.json")) === intent.previousShards && aliases(home) === intent.aliases);
+        realmBinding(home, intent.realms);
+        intent = checkedIntent({ ...intent, realms: intent.realms.map(realm => {
+          const built = buildPublicPruneIndex(realm.profile); return { ...realm, sourceHash: built.sourceHash, native: [...built.targets].sort() };
+        }) }, home);
+      }
+      const viewHash = publicPruneViewHash(intent.view);
+      immutable(join(home, "public-prune-input-sets", viewHash + ".json"), canonicalJSON(intent.view) + "\n");
+      readPublicPruneViewForActivation(home, viewHash, intent.generation);
+      let profile = readProfileBytes(home), shards = raw(join(home, "shards.json"));
+      guard((profile === intent.previousProfile || profile === intent.finalProfile) && (shards === intent.previousShards || shards === intent.finalShards));
+      guard(profile !== intent.finalProfile || shards === intent.finalShards);
+      verify(intent, profile, shards); for (const realm of intent.realms) syncIndex(nextProfile(realm, intent));
+      if (!pending && profile === intent.finalProfile && shards === intent.finalShards) return { mode: options.mode, generation: intent.generation, active: true, alreadyActive: true, realms: intent.realms.length, viewHash, maskBuildCheck: "verified" };
+      immutable(intentFile, canonicalJSON(intent) + "\n");
+      await options.checkpoint?.("after-intent"); verify(intent, profile, shards);
+      if (shards !== intent.finalShards) { writeProfileJSON(join(home, "shards.json"), JSON.parse(intent.finalShards)); shards = intent.finalShards; }
+      await options.checkpoint?.("after-shards"); verify(intent, profile, shards);
+      if (profile !== intent.finalProfile) { writeProfileJSON(join(home, "profile.json"), JSON.parse(intent.finalProfile)); profile = intent.finalProfile; }
+      await options.checkpoint?.("after-profile"); verify(intent, profile, shards);
+      guard(raw(intentFile) === canonicalJSON(intent) + "\n"); unlinkSync(intentFile); fsyncDirectory(home);
+      await options.checkpoint?.("after-remove"); verify(intent, profile, shards);
+      return { mode: options.mode, generation: intent.generation, active: true, realms: intent.realms.length, viewHash, maskBuildCheck: "verified" };
+    } finally { for (const release of releases.reverse()) release(); }
+  });
+}

package/src/memory/public-prune-advance.ts

@@ -0,0 +1,149 @@
+/** Already-v2 monotone commit. Native rows stay unchanged; readers apply the proved growing mask on rebind. */
+import { createHash } from "node:crypto";
+import { constants, closeSync, fsyncSync, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { canonicalJSON, fsyncDirectory, hashJSON, readSelector, withProfileLock } from "./generation.ts";
+import { aliasLogPath, shardDir, userShardDir, resolveShardProfile, SHARDED_V2_FIELDS } from "./shard.ts";
+import { acquireMutation, assertMutationHandle, type MutationHandle } from "./mutation.ts";
+import { createPublicPruneReplayCache, type PublicPruneProjection } from "./public-prune-inputs.ts";
+import { PUBLIC_PRUNE_INTENT, publicPruneViewHash, readPublicPruneViewForActivation, validatePublicPruneView, type PublicPruneViewV1 } from "./public-prune-view.ts";
+import { realPath } from "./platform.ts";
+
+export type PublicPruneAdvanceStage = "after-intent" | "after-shards" | "after-profile" | "after-remove";
+export interface PublicPruneAdvanceOptions {
+  memoryDir: string; view: PublicPruneViewV1; expectedRevision: string; mutations?: readonly MutationHandle[];
+  checkpoint?: (stage: PublicPruneAdvanceStage) => void | Promise<void>;
+}
+export interface PublicPruneAdvanceResult { revision: string; viewHash: string }
+interface Binding { key: string; dir: string; dev: number; ino: number; metadata: string }
+interface AdvanceIntent {
+  schema: "agent-mem.public-prune-advance/v1"; home: string; generation: string; expectedRevision: string;
+  previousProfile: string; previousShards: string; finalProfile: string; finalShards: string; finalProfileHash: string; finalShardsHash: string;
+  view: PublicPruneViewV1; bindings: Binding[]; root: { dev: number; ino: number; aliasesHash: string; machineHash: string };
+}
+const MAX = 1024 * 1024;
+const fail = (): never => { throw new Error("public prune advance unavailable; resume the pending view operation"); };
+function guard(ok: unknown): asserts ok { if (!ok) fail(); }
+const object = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+const exact = (v: Record<string, unknown>, keys: string[]) => Object.keys(v).length === keys.length && keys.every(key => Object.hasOwn(v,key));
+const hex = (v: unknown, size: number): v is string => typeof v === "string" && v.length === size && /^[a-f0-9]+$/.test(v);
+function owned(file: string, directory = false, links = 1) {
+  const stat = lstatSync(file); guard(!stat.isSymbolicLink() && (directory ? stat.isDirectory() : stat.isFile() && stat.nlink === links)
+    && stat.uid === process.getuid?.() && (stat.mode & 0o077) === 0); return stat;
+}
+function raw(file: string, links = 1): string {
+  const before = owned(file,false,links); guard(before.size > 0 && before.size <= MAX);
+  const fd = openSync(file,constants.O_RDONLY|constants.O_NOFOLLOW);
+  try {
+    const opened = fstatSync(fd), bytes = readFileSync(fd), afterFd = fstatSync(fd), after = owned(file,false,links);
+    guard(opened.isFile() && opened.nlink === links && opened.uid === before.uid && (opened.mode & 0o077) === 0
+      && afterFd.ino === opened.ino && afterFd.dev === opened.dev && afterFd.size === opened.size && afterFd.mtimeMs === opened.mtimeMs && afterFd.ctimeMs === opened.ctimeMs
+      && opened.ino === before.ino && opened.dev === before.dev && after.ino === before.ino && after.dev === before.dev
+      && bytes.length === before.size && after.mtimeMs === before.mtimeMs && after.ctimeMs === before.ctimeMs);
+    return new TextDecoder("utf-8",{fatal:true}).decode(bytes);
+  } finally { closeSync(fd); }
+}
+const optional = (file: string) => lstatSync(file,{throwIfNoEntry:false}) ? {exists:true,bytes:raw(file)} : {exists:false};
+function metadata(dir: string): string {
+  return hashJSON(["project.json","generation.json","generation-seal.json","migration-sources.json","machine.json"].map(name=>[name,optional(join(dir,name))]));
+}
+function realmDir(home: string, key: string): string { return key === "user" ? userShardDir(home) : key.startsWith("project:") ? shardDir(home,key.slice(8)) : fail(); }
+function immutable(file: string, bytes: string): void {
+  const base = dirname(file); if (!lstatSync(base,{throwIfNoEntry:false})) {mkdirSync(base,{mode:0o700});fsyncDirectory(dirname(base));} owned(base,true);
+  const temp = file+".pending-"+createHash("sha256").update(bytes).digest("hex");
+  if (lstatSync(file,{throwIfNoEntry:false})) {
+    const stat = lstatSync(file);
+    if (stat.nlink === 2) { const pending = owned(temp,false,2); owned(file,false,2); guard(pending.ino === stat.ino && pending.dev === stat.dev && raw(file,2) === bytes); unlinkSync(temp);fsyncDirectory(base); }
+    guard(raw(file) === bytes);return;
+  }
+  if (lstatSync(temp,{throwIfNoEntry:false})) { const staged=owned(temp); guard(staged.size<=MAX); if (!readFileSync(temp).equals(Buffer.from(bytes))) {unlinkSync(temp);fsyncDirectory(base);} }
+  if (!lstatSync(temp,{throwIfNoEntry:false})) {const fd=openSync(temp,"wx",0o600);try{writeFileSync(fd,bytes);fsyncSync(fd);}finally{closeSync(fd);}}
+  const stagedFd=openSync(temp,constants.O_RDONLY|constants.O_NOFOLLOW);try{fsyncSync(stagedFd);}finally{closeSync(stagedFd);}
+  linkSync(temp,file);fsyncDirectory(base);unlinkSync(temp);fsyncDirectory(base);
+}
+function replace(file: string, text: string): void {
+  const temp=file+".advance.tmp";
+  if (lstatSync(temp,{throwIfNoEntry:false})) {owned(temp);unlinkSync(temp);}
+  const fd=openSync(temp,"wx",0o600);try{writeFileSync(fd,text);fsyncSync(fd);}finally{closeSync(fd);}
+  // Same exact bytes recorded in the durable intent, not a reparsed/re-authored payload.
+  renameSync(temp,file);fsyncDirectory(dirname(file));
+}
+function checked(value: unknown, home: string): AdvanceIntent {
+  guard(object(value) && exact(value,["schema","home","generation","expectedRevision","previousProfile","previousShards","finalProfile","finalShards","finalProfileHash","finalShardsHash","view","bindings","root"]));
+  guard(value.schema === "agent-mem.public-prune-advance/v1" && value.home === home && hex(value.generation,32) && hex(value.expectedRevision,64));
+  for(const key of ["previousProfile","previousShards","finalProfile","finalShards"])guard(typeof value[key] === "string");
+  const previous=JSON.parse(value.previousProfile as string), oldShards=JSON.parse(value.previousShards as string), final=JSON.parse(value.finalProfile as string), shards=JSON.parse(value.finalShards as string), view=validatePublicPruneView(value.view);
+  guard(object(previous) && exact(previous,["schema","kind","generation","foreignPruneFormat","pruneInputSetHash"]) && previous.kind === "generation" && hex(previous.pruneInputSetHash,64) && previous.schema === "agent-mem.profile/v2" && previous.generation === value.generation && previous.foreignPruneFormat === "agent-mem.public-prune-witness/v1" && hashJSON(previous) === value.expectedRevision);
+  guard(object(final) && exact(final,["schema","kind","generation","foreignPruneFormat","pruneInputSetHash"]) && final.schema === previous.schema && final.kind === "generation" && final.generation === value.generation && final.foreignPruneFormat === previous.foreignPruneFormat && final.pruneInputSetHash === publicPruneViewHash(view));
+  guard(view.receivingGeneration === value.generation && canonicalJSON(final)+"\n" === value.finalProfile && hashJSON(final) === value.finalProfileHash && hashJSON(shards) === value.finalShardsHash && canonicalJSON(shards)+"\n" === value.finalShards);
+  guard(object(oldShards) && object(shards) && Object.keys(oldShards).every(key=>(SHARDED_V2_FIELDS as readonly string[]).includes(key)) && Object.keys(shards).every(key=>(SHARDED_V2_FIELDS as readonly string[]).includes(key)) && oldShards.phase === "active" && oldShards.generation === value.generation && oldShards.schema === "agent-mem.shards/v2" && oldShards.selectorRevision === value.expectedRevision && shards.selectorRevision === value.finalProfileHash);
+  const {selectorRevision:_old,...a}=oldShards,{selectorRevision:_new,...b}=shards;guard(canonicalJSON(a)===canonicalJSON(b));
+  guard(Array.isArray(value.bindings) && value.bindings.length <= 1024 && object(value.root) && exact(value.root,["dev","ino","aliasesHash","machineHash"]) && hex(value.root.aliasesHash,64) && hex(value.root.machineHash,64));
+  let prior="";for(const item of value.bindings){guard(object(item)&&exact(item,["key","dir","dev","ino","metadata"])&&typeof item.key==="string"&&item.key>prior&&item.dir===realmDir(home,item.key)&&hex(item.metadata,64));prior=item.key;}
+  guard(Buffer.byteLength(canonicalJSON(value))<=MAX);return {...value,view} as unknown as AdvanceIntent;
+}
+function proofs(intent: AdvanceIntent): (()=>void)[] {
+  const previous=JSON.parse(intent.previousProfile),old=readPublicPruneViewForActivation(intent.home,previous.pruneInputSetHash,intent.generation);
+  guard(Object.keys(old.realms).every(key=>Object.hasOwn(intent.view.realms,key)));
+  const changed=Object.keys(intent.view.realms).filter(key=>old.realms[key]!==intent.view.realms[key]);
+  guard(intent.bindings.length===changed.length&&intent.bindings.every(item=>changed.includes(item.key)));
+  const checks:(()=>void)[]=[];
+  for(const [key,set] of Object.entries(intent.view.realms)){
+    if(old.realms[key]===set)continue;
+    const binding=intent.bindings.find(item=>item.key===key);guard(binding);
+    const load=createPublicPruneReplayCache({dir:binding.dir,realm:key==="user"?{scope:"user"}:{scope:"project",key:key.slice(8)},receivingGeneration:intent.generation,inputSetHash:set});
+    const check=()=>{const proof:PublicPruneProjection=load();guard(old.realms[key]===undefined||proof.commitments.includes(old.realms[key]!));};check();checks.push(check);
+  }
+  return checks;
+}
+function run(intent: AdvanceIntent, provided: readonly MutationHandle[]|undefined, checkpoint?: PublicPruneAdvanceOptions["checkpoint"]): Promise<PublicPruneAdvanceResult> {
+  const checks=proofs(intent), releases:MutationHandle[]=[];
+  const work=()=>{
+    const dirs=[intent.home,...intent.bindings.map(item=>item.dir)].sort();
+    const handles=provided??dirs.map(dir=>{const lease=acquireMutation(dir);guard(lease);releases.push(lease);return lease;});
+    const verify=()=>{
+      const root=owned(intent.home,true);guard(root.dev===intent.root.dev&&root.ino===intent.root.ino&&hashJSON(optional(aliasLogPath(intent.home)))===intent.root.aliasesHash&&hashJSON(raw(join(intent.home,"machine.json")))===intent.root.machineHash);
+      for(const dir of dirs){let found=false;for(const handle of handles){try{assertMutationHandle(handle,dir);found=true;break;}catch{}}guard(found);}
+      for(const item of intent.bindings){const stat=owned(item.dir,true);guard(stat.dev===item.dev&&stat.ino===item.ino&&metadata(item.dir)===item.metadata);}
+      for(const check of checks)check();
+    };
+    const stages=function*():Generator<PublicPruneAdvanceStage,PublicPruneAdvanceResult>{
+      verify();let profile=raw(join(intent.home,"profile.json")),shards=raw(join(intent.home,"shards.json"));
+      guard((profile===intent.previousProfile||profile===intent.finalProfile)&&(shards===intent.previousShards||shards===intent.finalShards)&&!(profile===intent.finalProfile&&shards!==intent.finalShards));
+      const viewHash=publicPruneViewHash(intent.view),file=join(intent.home,PUBLIC_PRUNE_INTENT),text=canonicalJSON(intent)+"\n";
+      if(profile===intent.finalProfile&&shards===intent.finalShards&&!lstatSync(file,{throwIfNoEntry:false}))return{revision:intent.finalProfileHash,viewHash};
+      immutable(join(intent.home,"public-prune-input-sets",viewHash+".json"),canonicalJSON(intent.view)+"\n");
+      immutable(file,text);yield "after-intent";verify();guard(raw(file)===text&&raw(join(intent.home,"profile.json"))===profile&&raw(join(intent.home,"shards.json"))===shards);
+      if(shards!==intent.finalShards)replace(join(intent.home,"shards.json"),intent.finalShards);shards=intent.finalShards;
+      yield "after-shards";verify();guard(raw(file)===text&&raw(join(intent.home,"profile.json"))===profile&&raw(join(intent.home,"shards.json"))===shards);
+      if(profile!==intent.finalProfile)replace(join(intent.home,"profile.json"),intent.finalProfile);profile=intent.finalProfile;
+      yield "after-profile";verify();guard(raw(file)===text&&raw(join(intent.home,"profile.json"))===profile&&raw(join(intent.home,"shards.json"))===shards);
+      unlinkSync(file);fsyncDirectory(intent.home);yield "after-remove";verify();
+      return{revision:intent.finalProfileHash,viewHash};
+    };
+    if(checkpoint)return(async()=>{const iterator=stages();for(;;){const next=iterator.next();if(next.done)return next.value;await checkpoint(next.value);}})();
+    const iterator=stages();for(;;){const next=iterator.next();if(next.done)return next.value;}
+  };
+  return withProfileLock(intent.home,work).finally(()=>{for(const release of releases.reverse())release();});
+}
+export async function advancePublicPruneView(options: PublicPruneAdvanceOptions):Promise<PublicPruneAdvanceResult>{
+  const home=realPath(options.memoryDir),root=owned(home,true),selection=readSelector(home),profile=selection.selector;
+  guard(profile?.schema==="agent-mem.profile/v2"&&selection.revision===options.expectedRevision);
+  const view=validatePublicPruneView(options.view);guard(view.receivingGeneration===profile.generation);
+  const previousProfile=raw(join(home,"profile.json")),previousShards=raw(join(home,"shards.json")),old=readPublicPruneViewForActivation(home,profile.pruneInputSetHash,profile.generation);
+  const bindings:Binding[]=[];
+  for(const key of Object.keys(view.realms).sort())if(old.realms[key]!==view.realms[key]){
+    const bound=resolveShardProfile(home,key==="user"?{user:true}:{project:key.slice(8)}),stat=owned(bound.dir,true);
+    bindings.push({key,dir:bound.dir,dev:stat.dev,ino:stat.ino,metadata:metadata(bound.dir)});
+  }
+  const final={...profile,pruneInputSetHash:publicPruneViewHash(view)},shards={...JSON.parse(previousShards),selectorRevision:hashJSON(final)};
+  const intent=checked({schema:"agent-mem.public-prune-advance/v1",home,generation:profile.generation,expectedRevision:options.expectedRevision,previousProfile,previousShards,
+    finalProfile:canonicalJSON(final)+"\n",finalShards:canonicalJSON(shards)+"\n",finalProfileHash:hashJSON(final),finalShardsHash:hashJSON(shards),view,bindings,
+    root:{dev:root.dev,ino:root.ino,aliasesHash:hashJSON(optional(aliasLogPath(home))),machineHash:hashJSON(raw(join(home,"machine.json")))}},home);
+  return run(intent,options.mutations,options.checkpoint);
+}
+/** Explicit forward recovery only; ordinary reads never call this operation. */
+export async function resumePublicPruneAdvance(memoryDir:string,checkpoint?:PublicPruneAdvanceOptions["checkpoint"]):Promise<PublicPruneAdvanceResult>{
+  const home=realPath(memoryDir),file=join(home,PUBLIC_PRUNE_INTENT),stat=lstatSync(file),text=raw(file,stat.nlink);
+  const intent=checked(JSON.parse(text),home);guard(text===canonicalJSON(intent)+"\n");return run(intent,undefined,checkpoint);
+}

package/src/memory/public-prune-input-chain.ts

@@ -0,0 +1,73 @@
+/** Metadata-only input-set ancestry for the generation reader's cold path. Never loads proof bodies. */
+import { constants, closeSync, fstatSync, lstatSync, openSync, readSync, type BigIntStats } from "node:fs";
+import { join } from "node:path";
+import { canonicalJSON, hashJSON } from "./generation.ts";
+import { realPath } from "./platform.ts";
+
+export const PUBLIC_PRUNE_INPUT_MAX_BYTES = 65_536;
+export const PUBLIC_PRUNE_REPLAY_MAX_BYTES = 256 * 1024 * 1024;
+export const PUBLIC_PRUNE_MAX_SETS = 4096;
+export interface PublicPruneInputSetV1 {
+  schema: "agent-mem.public-prune-input-set/v1"; receivingGeneration: string; previous: string | null; inputs: string[];
+}
+export class PublicPruneInputError extends Error {
+  constructor(readonly code: "unavailable" | "resource" | "binding" = "unavailable") {
+    super(`public prune input ${code}`); this.name = "PublicPruneInputError";
+  }
+}
+function guard(ok: unknown, resource = false): asserts ok { if (!ok) throw new PublicPruneInputError(resource ? "resource" : "unavailable"); }
+function protectedCall<T>(work: () => T): T {
+  try { return work(); } catch (error) { if (error instanceof PublicPruneInputError) throw error; throw new PublicPruneInputError(); }
+}
+const object = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+const hex = (v: unknown, n: number): v is string => typeof v === "string" && v.length === n && /^[a-f0-9]+$/.test(v);
+export function validatePublicPruneInputSet(v: unknown): PublicPruneInputSetV1 {
+  return protectedCall(() => {
+    guard(object(v) && Object.keys(v).length === 4 && ["schema", "receivingGeneration", "previous", "inputs"].every(key => Object.hasOwn(v, key)));
+    guard(Buffer.byteLength(canonicalJSON(v)) <= PUBLIC_PRUNE_INPUT_MAX_BYTES, true);
+    guard(v.schema === "agent-mem.public-prune-input-set/v1" && hex(v.receivingGeneration, 32) && (v.previous === null || hex(v.previous, 64)) && Array.isArray(v.inputs));
+    let previous = "";
+    for (const id of v.inputs) { guard(hex(id, 64) && id > previous); previous = id; }
+    return { schema: v.schema, receivingGeneration: v.receivingGeneration, previous: v.previous, inputs: [...v.inputs] as string[] };
+  });
+}
+function owned(stat: BigIntStats, directory = false): void {
+  guard(!stat.isSymbolicLink() && (directory ? stat.isDirectory() : stat.isFile() && stat.nlink === 1n)
+    && stat.uid === BigInt(process.getuid?.() ?? -1) && (stat.mode & 0o077n) === 0n);
+}
+const same = (a: BigIntStats, b: BigIntStats) => a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs;
+/** Complete bounded chain, closed canonical metadata, exact hashes and monotone membership. */
+export function readPublicPruneInputSetChain(input: { dir: string; receivingGeneration: string; inputSetHash: string }): { commitments: string[]; inputs: string[] } {
+  return protectedCall(() => {
+    guard(hex(input.receivingGeneration, 32) && hex(input.inputSetHash, 64));
+    const original = lstatSync(input.dir, { bigint: true }); owned(original, true);
+    const dir = realPath(input.dir), root = lstatSync(dir, { bigint: true }); owned(root, true); guard(root.dev === original.dev && root.ino === original.ino);
+    const folder = join(dir, "public-prune-input-sets"), parent = lstatSync(folder, { bigint: true }); owned(parent, true);
+    const frontier = new Map<string, BigIntStats>(), commitments: string[] = [], seen = new Set<string>();
+    let id: string | null = input.inputSetHash, later: Set<string> | undefined, inputs: string[] = [], total = 0;
+    while (id !== null) {
+      guard(!seen.has(id)); guard(seen.size < PUBLIC_PRUNE_MAX_SETS, true); seen.add(id); commitments.push(id);
+      const file = join(folder, id + ".json"), before = lstatSync(file, { bigint: true }); owned(before);
+      guard(before.size > 0n && before.size <= BigInt(PUBLIC_PRUNE_INPUT_MAX_BYTES), true);
+      total += Number(before.size); guard(total <= PUBLIC_PRUNE_REPLAY_MAX_BYTES, true);
+      const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); let bytes: Buffer;
+      try {
+        const opened = fstatSync(fd, { bigint: true }); owned(opened); guard(same(before, opened));
+        const data = Buffer.alloc(Number(opened.size) + 1); let count = 0;
+        while (count < data.length) { const n = readSync(fd, data, count, data.length - count, count); if (!n) break; count += n; }
+        const after = fstatSync(fd, { bigint: true }), named = lstatSync(file, { bigint: true }); owned(after); owned(named);
+        guard(count === Number(before.size) && same(before, after) && same(before, named)); bytes = data.subarray(0, count); frontier.set(file, before);
+      } finally { closeSync(fd); }
+      const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes), raw: unknown = JSON.parse(text), canonical = canonicalJSON(raw);
+      guard(text === canonical || text === canonical + "\n");
+      const set = validatePublicPruneInputSet(raw); guard(hashJSON(set) === id && set.receivingGeneration === input.receivingGeneration);
+      if (later) guard(set.inputs.every(member => later!.has(member))); else inputs = set.inputs;
+      later = new Set(set.inputs); id = set.previous;
+    }
+    for (const [file, before] of frontier) { const now = lstatSync(file, { bigint: true }); owned(now); guard(same(before, now)); }
+    for (const [file, before] of [[input.dir, original], [dir, root], [folder, parent]] as const) {
+      const now = lstatSync(file, { bigint: true }); owned(now, true); guard(now.dev === before.dev && now.ino === before.ino);
+    }
+    return { commitments, inputs: [...inputs] };
+  });
+}