@staix/agent-mem 0.3.1 → 0.4.0

package/src/memory/generation-index.ts

@@ -1,15 +1,17 @@
+import { SHARDED_SCHEMA } from "./shard.ts";
+import { readShardLegacySnapshot } from "./shard-bridge.ts";
 import type { Database } from "bun:sqlite";
 import { createHash } from "node:crypto";
 import { closeSync, constants, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeSync } from "node:fs";
 import { join } from "node:path";
-import { canonicalJSON, fsyncDirectory, readProfileJSON, selectorRevision, writeProfileJSON, type BoundProfile } from "./generation.ts";
+import { canonicalJSON, hashJSON, fsyncDirectory, readProfileJSON, selectorRevision, writeProfileJSON, type BoundProfile, validateVaultLinkRow, type VaultLink } from "./generation.ts";
 import { legacyEntries, legacyHead, readLegacySnapshot, SegmentReader, type LegacyCheckpoint, type LegacySegment } from "./bridge.ts";
 import { reducePruneRows, validatePruneRow, type PrunePlan, type PruneRow, type PruneSnapshot, type PruneSourceRow, type PruneStorePort } from "./prune.ts";
 import { PROMOTED_KINDS, type Entry } from "./store.ts";
 
 const digest = (bytes: Uint8Array) => createHash("sha256").update(bytes).digest("hex");
 const fail = (): never => { throw new Error("generation input unavailable or changed; person inspection required"); };
-export const GENERATION_TABLES = ["generation_rows", "generation_prunes", "generation_targets", "generation_segments", "generation_state"] as const;
+export const GENERATION_TABLES = ["generation_vault_links", "generation_rows", "generation_prunes", "generation_targets", "generation_segments", "generation_state"] as const;
 export interface GenerationIndexOptions {
   profile: BoundProfile; db: Database; now: () => number;
   apply: (line: string, source: string) => void;
@@ -43,6 +45,18 @@ export function explicitExpirySnapshot(rows: readonly PruneSourceRow[]): PruneSn
   });
 }
 
+/** Exact source-presence reducer shared by indexing and migration proof validation. */
+export function coalesceGenerationSource(prior: PruneSourceRow | undefined, row: Entry, source: { source: string; local: boolean }): PruneSourceRow {
+  if (prior && canonicalJSON(prior.row) !== canonicalJSON(row)) return fail();
+  const local = source.local || row.op === "settle" || row.op === "note" && row.tier === "short";
+  const publicWitness = !local && source.source !== "legacy-local";
+  const own = source.source === "generation";
+  return { row, placement: local && (!prior || prior.placement === "local") ? "local" : "synced",
+    publicWitness: !!prior?.publicWitness || publicWitness,
+    own: prior ? row.op === "note" ? prior.own === true && own : prior.own === true || own : own,
+    legacy: !!prior?.legacy || !own };
+}
+
 /** Generation-owned derived state. Legacy files are inputs, never opened as a MemoryStore. */
 export class GenerationIndex {
   readonly profile: BoundProfile;
@@ -55,6 +69,7 @@ export class GenerationIndex {
     const db = options.db;
     db.run("CREATE TABLE IF NOT EXISTS generation_rows (id TEXT PRIMARY KEY, line TEXT NOT NULL, local INTEGER NOT NULL, public INTEGER NOT NULL, own INTEGER NOT NULL, legacy INTEGER NOT NULL)");
     if (!(db.query("PRAGMA table_info(generation_rows)").all() as { name: string }[]).some(row => row.name === "legacy")) { db.run("ALTER TABLE generation_rows ADD COLUMN legacy INTEGER NOT NULL DEFAULT 0"); this.replayProvenance = true; }
+    db.run("CREATE TABLE IF NOT EXISTS generation_vault_links (id TEXT PRIMARY KEY, target TEXT NOT NULL, row_hash TEXT NOT NULL, project TEXT NOT NULL, path TEXT NOT NULL, at TEXT NOT NULL)");
     db.run("CREATE TABLE IF NOT EXISTS generation_prunes (id TEXT PRIMARY KEY, line TEXT NOT NULL, local INTEGER NOT NULL)");
     db.run("CREATE TABLE IF NOT EXISTS generation_targets (id TEXT PRIMARY KEY)");
     db.run("CREATE TABLE IF NOT EXISTS generation_segments (source TEXT NOT NULL, path TEXT NOT NULL, offset INTEGER NOT NULL, hash TEXT NOT NULL, commit_id TEXT, stamp TEXT, PRIMARY KEY(source,path))");
@@ -74,7 +89,15 @@ export class GenerationIndex {
       });
     });
   }
+  /** Authoring handles cannot read or append a partially resumed split; migration index bootstraps use captured limits. */
+  private shardFrontier(): string | undefined {
+    if (!this.profile.sharded || this.options.limits !== undefined) return undefined;
+    const value = readProfileJSON(join(this.profile.home, "shards.json")) as { schema?: unknown; phase?: unknown; generation?: unknown; selectorRevision?: unknown } | undefined;
+    if (!value || value.schema !== SHARDED_SCHEMA || value.phase !== "active" || value.generation !== this.profile.generation || value.selectorRevision !== this.profile.selectorRevision) return fail();
+    return hashJSON(value);
+  }
   private capture(): { segments: LegacySegment[]; commit?: string } {
+    const shardBefore = this.shardFrontier();
     const db = this.options.db;
     const previous = db.query("SELECT source,path,offset,hash,commit_id,stamp FROM generation_segments WHERE source != 'generation'").all() as (LegacyCheckpoint & { commit_id: string | null; stamp: string | null })[];
     const initial = readProfileJSON(join(this.profile.dir, "migration-sources.json")) as { sources?: LegacyCheckpoint[]; legacyCommit?: string } | undefined;
@@ -84,13 +107,18 @@ export class GenerationIndex {
     const persisted = new Set(previous.map(row => `${row.source}:${row.path}`));
     const completeFrontier = checkpoints.every(row => persisted.has(`${row.source}:${row.path}`));
     const prior = (db.query("SELECT value FROM generation_state WHERE key='legacyCommit'").get() as { value: string } | null)?.value ?? initial?.legacyCommit;
-    const commit = this.options.commit ?? legacyHead(this.profile.home, this.profile.generation!);
-    const legacy = readLegacySnapshot(this.profile.home, { generation: this.profile.generation, ...(commit ? { commit } : {}), checkpoints, ...(prior ? { previousCommit: prior } : {}), ...(this.options.limits ? { limits: this.options.limits } : {}), reader: this.reader, incremental: !this.fullCapture && !this.options.limits && completeFrontier });
+    const legacyHome = this.profile.legacyHome ?? this.profile.home;
+    const generation = this.profile.sharded ? undefined : this.profile.generation;
+    const commit = this.options.commit ?? (generation ? legacyHead(legacyHome, generation) : undefined);
+    const legacy = this.profile.sharded
+      ? readShardLegacySnapshot(this.profile, { checkpoints, ...(this.options.limits ? { limits: this.options.limits } : {}), reader: this.reader, incremental: !this.fullCapture && !this.options.limits && completeFrontier })
+      : readLegacySnapshot(legacyHome, { ...(generation ? { generation } : {}), ...(commit ? { commit } : {}), checkpoints, ...(generation && prior ? { previousCommit: prior } : {}), ...(this.options.limits ? { limits: this.options.limits } : {}), reader: this.reader, incremental: !this.fullCapture && !this.options.limits && completeFrontier });
     const own = this.ownSegments();
     for (const old of db.query("SELECT path,offset,hash FROM generation_segments WHERE source='generation'").all() as { path: string; offset: number; hash: string }[]) {
       const segment = own.find(s => s.path === old.path);
       if (!segment || segment.offset < old.offset) fail();
     }
+    if (this.shardFrontier() !== shardBefore) return fail();
     return { segments: [...legacy, ...own], ...(commit ? { commit } : {}) };
   }
   private index(captured: { segments: LegacySegment[]; commit?: string }): void {
@@ -107,19 +135,21 @@ export class GenerationIndex {
           db.query("INSERT OR IGNORE INTO generation_prunes VALUES (?,?,?)").run(row.id, canonicalJSON(row), Number(segment.local));
           continue;
         }
+        if (segment.source === "generation" && parsed && typeof parsed === "object" && (parsed as { op?: string }).op === "vault_link") {
+          const row = validateVaultLinkRow(parsed, this.profile.generation, segment.local ? "local" : "synced");
+          if (segment.path !== `local/${row.machine}.jsonl`) fail();
+          db.query("INSERT OR IGNORE INTO generation_vault_links VALUES (?,?,?,?,?,?)").run(row.id, row.target, row.rowHash, row.project, row.path, row.at);
+          continue;
+        }
         const bytes = Buffer.from(line + "\n");
         const row = legacyEntries([{ ...segment, bytes, offset: bytes.length, hash: digest(bytes) }], { strict: segment.source === "generation", onMalformed: () => this.recordSkipped(segment) })[0];
         if (!row) continue;
-        const canonical = canonicalJSON(row), old = db.query("SELECT line,own,legacy FROM generation_rows WHERE id=?").get(row.id) as { line: string; own: number; legacy: number } | null;
+        const canonical = canonicalJSON(row), old = db.query("SELECT line,local,public,own,legacy FROM generation_rows WHERE id=?").get(row.id) as { line: string; local: number; public: number; own: number; legacy: number } | null;
         if (old && old.line !== canonical) fail();
         this.options.apply(line, segment.path);
-        const local = segment.local || row.op === "settle" || row.op === "note" && row.tier === "short";
-        const publicWitness = !local && segment.source !== "legacy-local";
-        const own = segment.source === "generation", legacy = !own;
-        // Notes retain legacy birth when duplicated; ops can independently occur in both birth realms.
-        const ownPresence = old ? row.op === "note" ? !!old.own && own : !!old.own || own : own;
+        const presence = coalesceGenerationSource(old ? { row, placement: old.local ? "local" : "synced", publicWitness: !!old.public, own: !!old.own, legacy: !!old.legacy } : undefined, row, segment);
         db.query("INSERT INTO generation_rows VALUES (?,?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET local=MIN(local,excluded.local), public=MAX(public,excluded.public), own=excluded.own, legacy=excluded.legacy")
-          .run(row.id, canonical, Number(local), Number(publicWitness), Number(ownPresence), Number(!!old?.legacy || legacy));
+          .run(row.id, canonical, Number(presence.placement === "local"), Number(presence.publicWitness), Number(presence.own), Number(presence.legacy));
       }
       db.query("INSERT INTO generation_segments VALUES (?,?,?,?,?,?) ON CONFLICT(source,path) DO UPDATE SET offset=excluded.offset,hash=excluded.hash,commit_id=excluded.commit_id,stamp=excluded.stamp")
         .run(segment.source, segment.path, segment.offset, segment.hash, segment.commit ?? null, segment.stamp ?? null);
@@ -173,6 +203,18 @@ export class GenerationIndex {
     if (!committed) { if (attempt < 5) return this.rebuild(attempt + 1); return fail(); }
     this.replayProvenance = false;
   }
+  vaultWitnesses(ids: readonly string[]): Map<string, string> {
+    if (ids.length > 5000) throw new Error("vault scan budget exceeded");
+    return new Map((this.options.db.query("SELECT id,line FROM generation_rows WHERE id IN (SELECT value FROM json_each(?))").all(JSON.stringify(ids)) as { id: string; line: string }[])
+      .map(row => [row.id, hashJSON(JSON.parse(row.line))]));
+  }
+  vaultLinks(project: string): VaultLink[] {
+    const rows = this.options.db.query("SELECT l.id,l.target,l.row_hash AS rowHash,l.project,l.path,l.at,r.line FROM generation_vault_links l JOIN generation_rows r ON r.id=l.target WHERE l.project=? ORDER BY l.at,l.id LIMIT 5001").all(project) as (VaultLink & { line: string })[];
+    if (rows.length > 5000) throw new Error("vault scan budget exceeded");
+    return rows
+      .filter(row => { const note = JSON.parse(row.line) as Entry; return note.op === "note" && note.project === row.project && hashJSON(note) === row.rowHash; })
+      .map(({ line: _line, ...row }) => row);
+  }
   own(id: string): boolean { return !!(this.options.db.query("SELECT own FROM generation_rows WHERE id=?").get(id) as { own: number } | null)?.own; }
   snapshot(refresh = true): PruneSnapshot {
     if (refresh) this.refresh();
@@ -191,6 +233,7 @@ export class GenerationIndex {
   private pendingPath(local: boolean, machine: string): string { return join(this.profile.dir, "prune-plans", `pending-${local ? "local" : "log"}-${machine}.json`); }
   /** Every ordinary writer must refuse to append unrelated JSON after a prune crash tail. */
   assertAppendable(local: boolean, machine: string): void {
+    this.shardFrontier();
     if (readProfileJSON(this.pendingPath(local, machine)) !== undefined) fail();
     const file = join(this.profile.dir, local ? "local" : "log", `${machine}.jsonl`);
     if (!existsSync(file)) return;

package/src/memory/generation.ts

@@ -1,6 +1,7 @@
 import { createHash, randomBytes } from "node:crypto";
+import { types } from "node:util";
 import { closeSync, existsSync, fsyncSync, lstatSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { mutationDatabase } from "./mutation.ts";
+import { readerAdmissionDatabase } from "./mutation.ts";
 import { dirname, join } from "node:path";
 import { canonicalPath, processLiveness, processSignature, realPath } from "./platform.ts";
 
@@ -11,6 +12,13 @@ export interface BoundProfile {
   dir: string;
   generation?: string;
   selectorRevision: string;
+  /** Sharded profiles read only their own legacy input; the root home remains the machine/selector identity. */
+  legacyHome?: string;
+  /** Public legacy witnesses stay distinct from same-machine private bridge input. */
+  legacyMainHome?: string;
+  sharded?: boolean;
+  shardKey?: string;
+  shardUser?: boolean;
 }
 export type ProfileInput = "shared-v1" | { generation: string };
 export interface ProfileSelector { schema: "agent-mem.profile/v1"; kind: "shared-v1" | "generation"; generation?: string }
@@ -102,7 +110,7 @@ export async function withProfileLock<T>(memoryDir: string, work: () => T | Prom
   const deadline = Date.now() + PROFILE_LOCK_TIMEOUT_MS;
   for (;;) {
     let acquired = false;
-    const fence = mutationDatabase(memoryDir);
+    const fence = readerAdmissionDatabase(memoryDir);
     let fenced = false;
     try {
       // Serialize the complete stale-owner probe/unlink/recreate sequence, then release before waiting on a live owner.
@@ -141,3 +149,34 @@ export async function withProfileLock<T>(memoryDir: string, work: () => T | Prom
     }
   }
 }
+
+
+export interface VaultLinkRow {
+  schema: "agent-mem.vault-link/v1"; op: "vault_link"; generation: string;
+  id: string; at: string; machine: string; actor: "person"; placement: "local";
+  target: string; rowHash: string; project: string; path: string;
+}
+export interface VaultLink { id: string; target: string; rowHash: string; project: string; path: string; at: string }
+const invalidVaultLink = (): never => { throw new Error("invalid vault link or unavailable exact entry"); };
+export const vaultLinkId = (body: unknown): string => createHash("sha256").update(canonicalJSON(body)).digest("hex").slice(0, 32);
+
+/** Metadata only: this path is never resolved, opened, copied or written by amem. */
+export function validVaultPath(path: unknown): path is string {
+  return typeof path === "string" && path.length > 0 && Buffer.byteLength(path) <= 512 && path.endsWith(".md")
+    && !/[\\:\p{Cc}]/u.test(path) && !path.startsWith("/") && path.split("/").every(part => part !== "" && part !== "." && part !== "..");
+}
+export function validateVaultLinkRow(value: unknown, generation: string | undefined, placement: "local" | "synced"): VaultLinkRow {
+  if (!value || typeof value !== "object" || types.isProxy(value) || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype || Object.getOwnPropertySymbols(value).length) return invalidVaultLink();
+  const expected = ["schema", "op", "generation", "id", "at", "machine", "actor", "placement", "target", "rowHash", "project", "path"].sort();
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (canonicalJSON(Object.keys(descriptors).sort()) !== canonicalJSON(expected) || Object.values(descriptors).some(field => !("value" in field) || !field.enumerable || typeof field.value !== "string")) return invalidVaultLink();
+  const row = value as VaultLinkRow;
+  if (row.schema !== "agent-mem.vault-link/v1" || row.op !== "vault_link" || row.generation !== generation || !/^[a-f0-9]{32}$/.test(row.generation)
+    || row.placement !== "local" || placement !== "local" || row.actor !== "person" || !/^[a-f0-9]{16}$/.test(row.machine)
+    || !/^[a-f0-9]{32}$/.test(row.id) || !/^[a-f0-9]{32}$/.test(row.target) || !/^[a-f0-9]{64}$/.test(row.rowHash)
+    || !row.project.trim() || row.project.length > 400 || /\p{Cc}/u.test(row.project) || !validVaultPath(row.path)
+    || !Number.isFinite(Date.parse(row.at)) || new Date(row.at).toISOString() !== row.at || Buffer.byteLength(canonicalJSON(row)) > 4096) return invalidVaultLink();
+  const { id, ...body } = row;
+  if (id !== vaultLinkId(body)) return invalidVaultLink();
+  return row;
+}

package/src/memory/home.ts

@@ -8,3 +8,8 @@ export function memoryHome(env: NodeJS.ProcessEnv = process.env): string {
   if (own) return canonicalPath(own);
   return join(canonicalPath(env.AGENTHUB_HOME?.trim() || join(homedir(), ".agenthub")), "memory");
 }
+
+/** The store's own base convention: `StoreOptions.home` names the parent and gets `/memory` appended. */
+export function memoryBase(home?: string): string {
+  return home === undefined ? memoryHome() : join(home, "memory");
+}

package/src/memory/import.ts

@@ -5,6 +5,8 @@ import { realPath } from "./platform.ts";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { KINDS, looksSecret, type Kind, type MemoryStore } from "./store.ts";
+import { listAliases, resolveAlias } from "./shard.ts";
+import { WorkListStore, type WorkListFields, type WorkListPolicy } from "./work-lists.ts";
 
 /** The claude-mem store is another program's: opened read-only, never written, its locks waited on briefly. */
 export const CLAUDE_MEM_BUSY_TIMEOUT_MS = 3000;
@@ -12,6 +14,64 @@ export const CLAUDE_MEM_BUSY_TIMEOUT_MS = 3000;
 const MODEL_ANSWER = "ahub ask (model answer)";
 
 export interface ImportResult { read: number; added: number; skipped: { model: number; pii: number; secret: number }; more: boolean; cursor: number }
+export interface WorkStateImportResult { read: number; added: number; skipped: { invalid: number; policy: number }; more: boolean; cursor: number }
+
+/**
+ * Import only the source project names explicitly mapped by the person's D2 alias table. A basename or even
+ * an exact canonical-key match is not permission to adopt another program's project. Source receipts preserve
+ * synced device/id identity across database copies; unsynced rows are scoped to the source's real path.
+ */
+export async function importClaudeMemWorkState(opts: { base: string; project: string; policy: WorkListPolicy; db?: string; limit?: number; restart?: boolean; log?: (line: string) => void }): Promise<WorkStateImportResult> {
+  const file = opts.db ?? join(homedir(), ".claude-mem", "claude-mem.db");
+  if (!existsSync(file)) throw new Error(`no claude-mem store at ${file}`);
+  const limit = opts.limit ?? 10_000;
+  if (!Number.isSafeInteger(limit) || limit <= 0) throw new Error("--limit takes a positive integer");
+  const project = resolveAlias(opts.base, opts.project);
+  const aliases = [...new Map(listAliases(opts.base).map(op => [op.alias, op.key]))]
+    .filter(([, key]) => key === project).map(([alias]) => alias).sort();
+  const result: WorkStateImportResult = { read: 0, added: 0, skipped: { invalid: 0, policy: 0 }, more: false, cursor: 0 };
+  if (!aliases.length) return result;
+  const db = new Database(file, { readonly: true });
+  let store: WorkListStore | undefined;
+  let state: string | undefined, key = "", cursor = 0;
+  try {
+    db.run(`PRAGMA busy_timeout = ${CLAUDE_MEM_BUSY_TIMEOUT_MS}`);
+    if (!db.query("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'work_state_entries'").get()) return result;
+    const columns = new Set((db.query("PRAGMA table_info(work_state_entries)").all() as { name: string }[]).map(row => row.name));
+    const origin = columns.has("origin_device_id") && columns.has("origin_local_id");
+    const sourceMachine = createHash("sha256").update(realPath(file)).digest("hex");
+    store = new WorkListStore({ base: opts.base, project, policy: opts.policy });
+    state = join(store.dir, "import-state.json");
+    key = createHash("sha256").update(JSON.stringify([sourceMachine, aliases, project])).digest("hex");
+    cursor = opts.restart ? 0 : readCursors(state)[key] ?? 0;
+    const where = `project IN (${aliases.map(() => "?").join(",")})`;
+    const max = db.query(`SELECT MAX(id) AS id FROM work_state_entries WHERE ${where}`).get(...aliases) as { id: number | null };
+    if ((max.id ?? 0) < cursor) cursor = 0;
+    const rows = db.query(`SELECT id, list_name, fields, created_at_epoch${origin ? ", origin_device_id, origin_local_id" : ", NULL AS origin_device_id, NULL AS origin_local_id"} FROM work_state_entries WHERE ${where} AND id > ? ORDER BY id LIMIT ?`)
+      .all(...aliases, cursor, limit) as { id: number; list_name: string; fields: string; created_at_epoch: number; origin_device_id: string | null; origin_local_id: string | null }[];
+    result.read = rows.length; result.more = rows.length === limit;
+    for (const row of rows) {
+      try {
+        let fields: WorkListFields;
+        try { fields = JSON.parse(row.fields) as WorkListFields; } catch { result.skipped.invalid++; cursor = row.id; continue; }
+        const synced = typeof row.origin_device_id === "string" && !!row.origin_device_id && typeof row.origin_local_id === "string" && !!row.origin_local_id;
+        const written = await store.write(row.list_name, fields, { source: "claude-mem/work_state", id: synced ? row.origin_local_id! : String(row.id), machine: synced ? row.origin_device_id! : sourceMachine, at: row.created_at_epoch });
+        if (!written.already) result.added++;
+      } catch (error) {
+        if (error instanceof Error && error.message === "invalid work-list input") result.skipped.invalid++;
+        else if (error instanceof Error && error.message === "work-list privacy policy refused the write") result.skipped.policy++;
+        else throw error; // Do not advance a receipt conflict or a failed append.
+      }
+      cursor = row.id;
+    }
+  } finally {
+    db.close();
+    result.cursor = cursor;
+    if (state) writeCursor(state, key, cursor, opts.log ?? console.error);
+    store?.close();
+  }
+  return result;
+}
 
 /** Machine-local progress is disposable; malformed/unreadable state simply replays the idempotent import. */
 function readCursors(file: string): Record<string, number> {

package/src/memory/migrate.ts

@@ -97,10 +97,17 @@ function writeSources(memoryDir: string, journal: MigrationJournal): void {
     { schema: "agent-mem.migration-sources/v1", sources: journal.sources, legacyCommit: journal.legacyCommit });
 }
 
+function refuseShardSelection(memoryDir: string): void {
+  try { lstatSync(join(memoryDir, "shards.json")); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return; throw error; }
+  throw new Error("ordinary generation migration is unavailable after shard migration starts; inspect amem status and use amem migrate --shards --resume; the existing selector was retained");
+}
+
 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);
+  refuseShardSelection(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;
@@ -111,6 +118,7 @@ export async function migrate(options: MigrateOptions): Promise<MigrationResult>
     return { mode: options.mode, profile: initial, counts: await counts(memoryDir, options.generation ?? initial.generation, (options.now ?? Date.now)()), consequence };
   }
   return withProfileLock(memoryDir, async () => {
+    refuseShardSelection(memoryDir);
     const selected = readSelector(memoryDir);
     if (selected.revision !== initial.selectorRevision) return changed();
     if (options.mode === "deactivate") {

package/src/memory/mutation.ts

@@ -1,5 +1,5 @@
 import { Database } from "bun:sqlite";
-import { chmodSync } from "node:fs";
+import { chmodSync, lstatSync } from "node:fs";
 import { join } from "node:path";
 
 export const MUTATION_BUSY_TIMEOUT_MS = 3000;
@@ -20,3 +20,15 @@ export function acquireMutation(dir: string): (() => void) | undefined {
   catch { db.close(); return undefined; }
   return () => { try { db.run("ROLLBACK"); } finally { db.close(); } };
 }
+
+/** Short local admission fence, never held across sync/network or data mutations. */
+export function readerAdmissionDatabase(dir: string): Database {
+  const file = join(dir, "reader-admission.db");
+  for (const suffix of ["", "-wal", "-shm", "-journal"]) {
+    const stat = lstatSync(file + suffix, { throwIfNoEntry: false });
+    if (stat && (stat.isSymbolicLink() || !stat.isFile())) throw new Error("reader admission fence is not a regular file");
+  }
+  const db = new Database(file, { create: true });
+  try { chmodSync(file, 0o600); db.run(`PRAGMA busy_timeout = ${MUTATION_BUSY_TIMEOUT_MS}`); return db; }
+  catch (error) { db.close(); throw error; }
+}

package/src/memory/ops-contract.ts

@@ -118,7 +118,7 @@ export interface GenerationOpContract extends Omit<OpContract, "implemented" | "
   implemented: true;
   generationOnly: true;
   targetSemantics: "exact-entry-v1";
-  validator: "validatePruneRow";
+  validator: "validatePruneRow" | "validateVaultLinkRow";
   validation: readonly string[];
   payloadSchema: {
     version: 1;
@@ -156,4 +156,21 @@ export const PRUNE_GENERATION_CONTRACT: GenerationOpContract = Object.freeze<Gen
   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 });
+export const VAULT_LINK_GENERATION_CONTRACT: GenerationOpContract = Object.freeze<GenerationOpContract>({
+  status: "truth-changing", implemented: true, generationOnly: true, targetSemantics: "exact-entry-v1", validator: "validateVaultLinkRow",
+  validation: ["exact string-valued keys; no additional fields; canonical UTC and bounded metadata", "id is canonical complete payload hash excluding id", "bound generation and local authored machine segment must match", "projection requires exact full target id and authored row hash in the same project"],
+  payloadVersion: "agent-mem.vault-link/v1", required: ["schema", "op", "generation", "id", "at", "machine", "actor", "placement", "target", "rowHash", "project", "path"],
+  payloadSchema: { version: 1, required: ["schema", "op", "generation", "id", "at", "machine", "actor", "placement", "target", "rowHash", "project", "path"], additionalProperties: false, maxUtf8Bytes: 4096, fields: {
+    schema: { type: "string", values: ["agent-mem.vault-link/v1"] }, op: { type: "string", values: ["vault_link"] },
+    generation: generationId, id: generationId, at: canonicalUtc, machine: { type: "string", pattern: "^[a-f0-9]{16}$" },
+    actor: { type: "string", values: ["person"] }, placement: { type: "string", values: ["local"] }, target: generationId, rowHash: authoredHash,
+    project: { type: "string" }, path: { type: "string" },
+  } },
+  immutableTargets: "full exact note id and SHA-256 of the complete canonical authored row; project must match; no aliases, promotion ancestry or replacements",
+  placement: "generation local segment only; vault paths are machine-local metadata and never sync; shard migration carries the row to its exact target owner",
+  precedence: "append-only links suppress only their witnessed exact entry from future candidates; independent replacement ids survive; malformed or missing witnesses cannot suppress",
+  identity: "sha256(canonical complete vault-link payload excluding id), first 32 hex; generation, target id, full witness hash and path participate",
+  crashBoundary: "mutation fence and exact id/hash recheck; refuse an incomplete prior tail; append+fsync then derived refresh; complete rows replay, incomplete tails require person inspection",
+  fixtures: ["test/vault.test.ts#vault links refuse shared-v1 and bind exact generation entries, survive rebuild, and never touch v1 logs", "test/vault.test.ts#vault link validation rejects changed payload hashes, foreign generation and public placement", "test/vault.test.ts#vault links retain their exact target through curated shard migration"],
+});
+export const GENERATION_OP_CONTRACTS: Readonly<Record<"prune" | "vault_link", GenerationOpContract>> = Object.freeze({ prune: PRUNE_GENERATION_CONTRACT, vault_link: VAULT_LINK_GENERATION_CONTRACT });

package/src/memory/policy.ts

@@ -0,0 +1,120 @@
+import { posix } from "node:path";
+import { types } from "node:util";
+import { looksSecret } from "./screen.ts";
+import { isDenied } from "./platform.ts";
+import { nodePath, pathCandidates } from "./project.ts";
+
+/** True means the complete value is public. Hosts may narrow, never replace, standalone policy. */
+export interface MemoryPolicy { screen(value: unknown): Promise<boolean> }
+export interface StandalonePolicyOptions {
+  denyPaths?: readonly string[];
+  /** Case-insensitive literal substrings, not executable regular expressions. */
+  piiPatterns?: readonly string[];
+  host?: MemoryPolicy;
+}
+
+const MAX_DEPTH = 16, MAX_NODES = 4096, MAX_BYTES = 256 * 1024, MAX_STRING_BYTES = 16 * 1024;
+const fold = (text: string) => text.normalize("NFKC").replace(/\p{Default_Ignorable_Code_Point}/gu, "").toLowerCase().replace(/\\/g, "/");
+const flags = new Set(["private", "pii", "privateturn", "isprivate", "ispii"]);
+
+/** Inspect descriptors, not getters/toJSON, and build the only value a host is allowed to see. */
+function snapshot(value: unknown): { value: unknown; texts: string[] } | undefined {
+  let nodes = 0, bytes = 0;
+  const seen = new Set<object>(), texts: string[] = [];
+  const add = (text: string) => {
+    const length = Buffer.byteLength(text);
+    if (length > MAX_STRING_BYTES || (bytes += length) > MAX_BYTES) throw new Error("policy bound");
+    texts.push(text);
+  };
+  const visit = (input: unknown, depth: number): unknown => {
+    if (depth > MAX_DEPTH || ++nodes > MAX_NODES) throw new Error("policy bound");
+    if (input === null || typeof input === "boolean") { bytes += 5; return input; }
+    if (typeof input === "number") { if (!Number.isFinite(input)) throw new Error("policy shape"); bytes += 24; return input; }
+    if (typeof input === "string") { add(input); return input; }
+    if (!input || typeof input !== "object" || types.isProxy(input) || seen.has(input)) throw new Error("policy shape");
+    const array = Array.isArray(input), prototype = Object.getPrototypeOf(input);
+    if (array ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null) throw new Error("policy shape");
+    if (Object.getOwnPropertySymbols(input).length) throw new Error("policy shape");
+    seen.add(input);
+    try {
+      const descriptors = Object.getOwnPropertyDescriptors(input);
+      if (array) {
+        const length = descriptors.length?.value;
+        if (!Number.isSafeInteger(length) || length > MAX_NODES || Object.keys(descriptors).length !== length + 1) throw new Error("policy shape");
+        const output: unknown[] = [];
+        for (let index = 0; index < length; index++) {
+          const descriptor = descriptors[String(index)];
+          if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) throw new Error("policy shape");
+          output.push(visit(descriptor.value, depth + 1));
+        }
+        return output;
+      }
+      const output: Record<string, unknown> = Object.create(null);
+      for (const [key, descriptor] of Object.entries(descriptors)) {
+        if (!("value" in descriptor) || !descriptor.enumerable) throw new Error("policy shape");
+        add(key);
+        const flag = fold(key).replace(/[_-]/g, "");
+        if (flags.has(flag) && descriptor.value !== false) throw new Error("private value");
+        const item = visit(descriptor.value, depth + 1);
+        // A secret may be split between a metadata key and its scalar value.
+        if (typeof item === "string") add(`${key}: ${item}`);
+        output[key] = item;
+      }
+      return output;
+    } finally { seen.delete(input); }
+  };
+  try { const copy = visit(value, 0); return bytes <= MAX_BYTES ? { value: copy, texts } : undefined; }
+  catch { return undefined; }
+}
+
+function literals(value: unknown, label: string): string[] {
+  if (value === undefined) return [];
+  if (types.isProxy(value) || !Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype || value.length > 64 || Object.getOwnPropertySymbols(value).length) throw new Error(`invalid ${label}`);
+  const descriptors = Object.getOwnPropertyDescriptors(value), result: string[] = [];
+  if (Object.keys(descriptors).length !== value.length + 1) throw new Error(`invalid ${label}`);
+  for (let i = 0; i < value.length; i++) {
+    const item = descriptors[String(i)];
+    if (!item || !("value" in item) || typeof item.value !== "string" || !item.value.trim() || Buffer.byteLength(item.value) > 256 || /[\x00-\x1f\x7f]/.test(item.value)) throw new Error(`invalid ${label}`);
+    const normalized = fold(item.value);
+    if (!normalized.trim()) throw new Error(`invalid ${label}`);
+    result.push(normalized);
+  }
+  return [...new Set(result)];
+}
+
+function defaultPii(text: string): boolean {
+  if (/\b(?:\d{6}-\d{7}|\d{3}-\d{2}-\d{4})\b/.test(text)) return true;
+  // Bound each email candidate before matching; arbitrary user regexes are never run.
+  for (const token of text.split(/[\s<>()\[\]{}",;:]+/)) if (token.includes("@")) {
+    if (token.length > 320 || /[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}/i.test(token)) return true;
+  }
+  return false;
+}
+
+/** No filesystem, model, network or storage work occurs while constructing or screening this policy. */
+export function createStandalonePolicy(options: StandalonePolicyOptions = {}): MemoryPolicy {
+  if (!options || typeof options !== "object" || types.isProxy(options) || Object.getPrototypeOf(options) !== Object.prototype || Object.getOwnPropertySymbols(options).length) throw new Error("invalid standalone policy options");
+  const descriptors = Object.getOwnPropertyDescriptors(options);
+  for (const [key, descriptor] of Object.entries(descriptors)) if (!["denyPaths", "piiPatterns", "host"].includes(key) || !("value" in descriptor)) throw new Error("invalid standalone policy options");
+  const deny = literals(descriptors.denyPaths?.value, "deny paths").map(path => posix.normalize(path));
+  const pii = literals(descriptors.piiPatterns?.value, "PII patterns");
+  const host = descriptors.host?.value as MemoryPolicy | undefined;
+  if (host !== undefined && (!host || typeof host.screen !== "function")) throw new Error("invalid host policy");
+  return {
+    async screen(value: unknown): Promise<boolean> {
+      try {
+        const complete = snapshot(value);
+        if (!complete) return false;
+        for (const text of complete.texts) {
+          if (looksSecret(text) || looksSecret(text.replace(/["']/g, ""))) return false;
+          const normalized = fold(text);
+          if (defaultPii(normalized) || pii.some(pattern => normalized.includes(pattern))) return false;
+          const candidates = normalized.includes("/") || /\.[a-z]/.test(normalized) ? pathCandidates(normalized) : [];
+          const paths = [normalized, nodePath(normalized), ...candidates, ...normalized.split(/[\s"'`(){}\[\],;:=<>]+/)];
+          for (const path of paths) if (path && isDenied(posix.normalize(path), deny)) return false;
+        }
+        return host === undefined || await host.screen(complete.value) === true;
+      } catch { return false; }
+    },
+  };
+}

package/src/memory/project.ts

@@ -38,7 +38,8 @@ export function projectChain(cwd: string): string[] {
 /**
  * #258: the name hub memory files a project's entries under. The project's `origin` remote, normalized to host and
  * path (`github.com/owner/repo`), is the same on every machine and unique; without one, the git chain plus a hash of
- * the directory keeps two unrelated repositories that share a name apart (that key is this machine's only).
+ * the main working root keeps two unrelated repositories that share a name apart while the main checkout, a
+ * subdirectory and a worktree resolve to one key (that key is this machine's only, and root-invoked keys stay stable).
  */
 export function memoryProjectKey(cwd: string): string {
   const url = memoryGitSync(["-C", cwd, "remote", "get-url", "origin"], { encoding: "utf8" }).stdout?.trim() ?? "";
@@ -56,6 +57,26 @@ export function memoryProjectKey(cwd: string): string {
     // GitHub serves one repository under every form, and its owner and repository names ignore case.
     return host === "github.com" ? `${host}/${m[1].replace(/^~\/?/, "").toLowerCase()}` : `${host}/${m[1]}`;
   }
+  // No usable remote: hash the main working root, not the cwd or git dir. Root-invoked keys therefore keep their
+  // pre-#15 value while the main checkout, a subdirectory and a worktree resolve to ONE key (#15 D2/AC2). A bare
+  // repository has no working root: its own directory is the stable identity for it and its worktrees.
+  const common = memoryGitSync(["-C", cwd, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8" }).stdout?.trim() ?? "";
+  if (common) {
+    let realCommon = common;
+    try { realCommon = realPath(common); } catch { /* as given */ }
+    const bare = (memoryGitSync(["--git-dir", realCommon, "rev-parse", "--is-bare-repository"], { encoding: "utf8" }).stdout?.trim() ?? "") === "true";
+    let root = realCommon;
+    if (!bare) {
+      const configured = memoryGitSync(["--git-dir", realCommon, "config", "--path", "core.worktree"], { encoding: "utf8" }).stdout?.trim() ?? "";
+      const top = memoryGitSync(["-C", cwd, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).stdout?.trim() ?? "";
+      // Only an actual `.git` directory makes its parent the working root. A separate git dir shares its parent
+      // with unrelated repositories, so the real worktree root (or, as a last resort, the unique git dir) is safer.
+      root = configured ? resolve(realCommon, configured) : basename(realCommon) === ".git" ? dirname(realCommon) : top || realCommon;
+    }
+    let realRoot = root;
+    try { realRoot = realPath(root); } catch { /* as given */ }
+    return `${projectChain(realRoot).join("/")}@${createHash("sha256").update(realRoot).digest("hex").slice(0, 8)}`;
+  }
   let real = cwd;
   try { real = realPath(cwd); } catch { /* as given */ }
   return `${projectChain(cwd).join("/")}@${createHash("sha256").update(real).digest("hex").slice(0, 8)}`;