@staix/agent-mem 0.3.1 → 0.5.0

package/src/memory/store.ts

@@ -1,16 +1,22 @@
 import { Database } from "bun:sqlite";
 import { createHash, randomBytes } from "node:crypto";
-import { appendFileSync, chmodSync, closeSync, existsSync, fstatSync, linkSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, chmodSync, closeSync, constants, existsSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, normalize } from "node:path";
 import { isDenied } from "./platform.ts";
+import { looksSecret } from "./screen.ts";
 import { mutationDatabase } from "./mutation.ts";
 import { memoryHome } from "./home.ts";
+import { readWindowSql, readRef, type ReadWindow, type ReadRef, SearchIndex, captureSearch } from "./search-fts.ts";
+import { assertCuratedShardPaths, ensureShardDescriptor, readShardDescriptor, readShardedSelection, resolveAlias, resolveShardProfile, shardDir, shardKeyHash, shardMachineDir, userShardDir } from "./shard.ts";
+import { readCaptureConfig, type CaptureRow } from "./capture.ts";
 import { assertSharedV1Op } from "./ops-contract.ts";
-import { generationDescriptor, generationDir, canonicalJSON, readProfileJSON, resolveProfile, type BoundProfile, type ProfileInput } from "./generation.ts";
+import { generationDescriptor, generationDir, fsyncDirectory, canonicalJSON, hashJSON, readProfileJSON, resolveProfile, writeProfileJSON, type BoundProfile, type ProfileInput, validateVaultLinkRow, vaultLinkId, type VaultLink, type VaultLinkRow } from "./generation.ts";
 import { GenerationIndex, explicitExpirySnapshot, GENERATION_TABLES } from "./generation-index.ts";
 import { legacyEntries, type LegacyCheckpoint } from "./bridge.ts";
+import { readMigrationSources } from "./migrate.ts";
 import type { PruneStorePort } from "./prune.ts";
 import { isDeepStrictEqual } from "node:util";
+import { registerReaderLease } from "./reader-lease.ts";
 
 /**
  * #258: the hub's own memory. Append-only JSONL logs are the truth: `log/<machine>.jsonl` holds long-term entries and
@@ -79,10 +85,8 @@ function canonical(value: unknown): string {
 }
 export const entryId = (e: Omit<Entry, "id">): string => createHash("sha256").update(canonical(e)).digest("hex").slice(0, 32);
 
-const SECRETS = [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, /\bAKIA[0-9A-Z]{16}\b/, /\bgh[pousr]_[A-Za-z0-9]{30,}/, /\bgithub_pat_[A-Za-z0-9_]{40,}/, /\bsk-[A-Za-z0-9_-]{20,}/,
-  /\bxox[abprs]-[A-Za-z0-9-]{10,}/, /\bAIza[0-9A-Za-z_-]{35}\b/, /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/, /\b(?:password|passwd|secret|api[_-]?key|token)\s*[:=]\s*\S{8,}/i];
-/** A secret-looking string: refused before anything is written, since long-term entries leave the machine. */
-export const looksSecret = (text: string): boolean => SECRETS.some((re) => re.test(text));
+// Single-sourced in screen.ts so the capture tier (#13) screens excerpts without importing this store; the export stays.
+export { looksSecret };
 
 /** `task`: the board task's id and proposal time; its node carries both, so a task id reused after `ahub reset --all` is another node. */
 export interface Extract { cwd: string; project: string; repo: string; deny?: string[]; paths?: string[]; symbols?: string[]; task?: { id: number; created: number }; checkExists?: boolean }
@@ -162,6 +166,7 @@ export interface View {
   /** Written as short-term, so it lives in this machine's local segment and never syncs. */
   local: boolean;
 }
+export interface VaultEntry { view: View; /** Full authored hash in generation profiles; empty for read-only shared-v1. */ rowHash: string }
 export interface GoalView {
   id: string; at: string; machine: string; project: string; scope: Scope; title: string; milestones: string[]; dependsOn: string[];
   state: GoalState; links: { task: string; at: string; machine: string }[];
@@ -169,6 +174,14 @@ export interface GoalView {
   lease: { holder: string | null; until: string | null; conflict: string[]; expired: boolean; lastHolder?: string | null };
 }
 export interface Filter { project?: string; tier?: Tier; kind?: Kind; peer?: string; machine?: string; since?: string; q?: string; limit?: number; includeSuperseded?: boolean }
+/** #13 search: `Filter` plus the capture-tier switch (on by default; capture is recall, never curated evidence). */
+export interface SearchFilter extends Filter {
+  includeCapture?: boolean;
+  /** A host that writes capture with a `retentionDays` override passes the same value here; files decide otherwise. */
+  captureRetentionDays?: number;
+}
+export interface SearchHit { source: "curated" | "capture"; score: number; view?: View; capture?: CaptureRow }
+export interface SearchResult { engine: "fts5" | "substring"; hits: SearchHit[] }
 export interface Graph { nodes: { id: Node; type: string; label: string; kind?: string; tier?: Tier }[]; edges: { from: Node; to: Node; rel: string }[] }
 
 /**
@@ -180,11 +193,13 @@ export type PromotionScreen = (v: View) => "promote" | "keep" | "skip";
  * `screen`: applied to every promotion. Without one, automatic promotions (a settlement, a held note whose replacement
  * went) wait for a process that has one; a person's explicit promote goes through.
  */
-export interface StoreOptions { home?: string; ttlMs?: number; now?: () => number; log?: (line: string) => void; screen?: PromotionScreen; deferPromotions?: boolean; profile?: ProfileInput;
+export interface StoreOptions { home?: string; memoryDir?: string; ttlMs?: number; now?: () => number; log?: (line: string) => void; screen?: PromotionScreen; deferPromotions?: boolean; profile?: ProfileInput;
+  /** #27: read the `aliases` keys' curated rows as part of the `canonical` project (CLI and MCP only); the library default reads the raw key. Rows are presented under `canonical`. */
+  reconcile?: { canonical: string; aliases: readonly string[] };
 }
 
 const MIGRATION_BOOTSTRAP = Symbol("migration index bootstrap");
-interface BootstrapBinding { token: typeof MIGRATION_BOOTSTRAP; profile: BoundProfile; limits: readonly LegacyCheckpoint[]; commit?: string }
+interface BootstrapBinding { token: typeof MIGRATION_BOOTSTRAP; profile: BoundProfile; limits?: readonly LegacyCheckpoint[]; commit?: string; authoring?: boolean; userOverlay?: MemoryStore; aliasStores?: MemoryStore[] }
 export class MemoryStore {
   readonly dir: string;
   readonly profile: BoundProfile;
@@ -197,49 +212,78 @@ export class MemoryStore {
   private readonly now: () => number;
   private readonly log: (line: string) => void;
   private readonly deferPromotions: boolean;
+  /** #13: the derived FTS5 copy of the curated rows, and the memory home base for capture shard resolution (#15 T1). */
+  private readonly searchIndex: SearchIndex;
+  private readonly memoryBaseDir: string;
+  private releaseReaderLease?: () => void;
+  private readonly userOverlay?: MemoryStore;
+  /** #27: the other keys' shards of a reconciled read (curated shards); shared-v1 reads them from its own index. */
+  private readonly aliasStores: MemoryStore[];
+  private readonly reconcile?: { canonical: string; aliases: readonly string[] };
+  /** A full rebuild refills FTS in one resync instead of one derived transaction per entry. */
+  private rebuildingSearch = false;
 
   constructor(opts: StoreOptions = {}, bootstrap?: BootstrapBinding) {
     if (bootstrap && bootstrap.token !== MIGRATION_BOOTSTRAP) throw new Error("invalid migration bootstrap");
-    this.bootstrapOnly = bootstrap !== undefined;
-    const home = opts.home === undefined ? memoryHome() : join(opts.home, "memory");
+    this.bootstrapOnly = bootstrap ? bootstrap.authoring !== true : false;
+    this.userOverlay = bootstrap?.userOverlay;
+    this.aliasStores = bootstrap?.aliasStores ?? [];
+    this.reconcile = opts.reconcile && opts.reconcile.aliases.length ? { canonical: opts.reconcile.canonical, aliases: [...opts.reconcile.aliases] } : undefined;
+    if (opts.memoryDir !== undefined && (opts.home !== undefined || typeof opts.memoryDir !== "string" || !opts.memoryDir.trim())) throw new Error("choose a memory home or one explicit memory directory");
+    const home = bootstrap?.profile.home ?? opts.memoryDir ?? (opts.home === undefined ? memoryHome() : join(opts.home, "memory"));
+    if (!bootstrap && lstatSync(join(home, "shards.json"), { throwIfNoEntry: false })) throw new Error("memory home has a curated split; hosts must use openShardStore({ project }) or openShardStore({ user: true }); finish an incomplete split with amem migrate --shards --resume");
     this.profile = bootstrap?.profile ?? resolveProfile(home, opts.profile);
     if (bootstrap && (this.profile.kind !== "generation" || !this.profile.generation
-      || this.profile.dir !== generationDir(this.profile.home, this.profile.generation)
+      || (!this.profile.sharded && this.profile.dir !== generationDir(this.profile.home, this.profile.generation))
       || canonicalJSON(readProfileJSON(join(this.profile.dir, "generation.json"))) !== canonicalJSON(generationDescriptor(this.profile.generation)))) throw new Error("invalid migration profile binding");
     // Shared-v1 preserves its historical lexical dir API; profile.home is still canonical for selector identity.
     this.dir = this.profile.kind === "shared-v1" ? home : this.profile.dir;
     mkdirSync(join(this.dir, "log"), { recursive: true, mode: 0o700 });
     mkdirSync(join(this.dir, "local"), { recursive: true, mode: 0o700 });
     chmodSync(this.dir, 0o700); // mkdir's mode applies only when it creates the directory
-    this.machine = machineId(this.dir);
+    this.machine = machineId(this.profile.sharded ? this.profile.home : this.dir);
     this.ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
     this.now = opts.now ?? Date.now;
     this.log = opts.log ?? (() => {});
     this.screen = opts.screen;
     this.deferPromotions = opts.deferPromotions ?? false;
-    const db = new Database(join(this.dir, "index.db"), { create: true });
-    db.run(`PRAGMA busy_timeout = ${MEMORY_DB_BUSY_TIMEOUT_MS}`);
-    db.run("PRAGMA journal_mode = WAL");
-    if ((db.query("PRAGMA user_version").get() as { user_version: number }).user_version !== INDEX_VERSION) {
-      for (const t of ["segments", "heads", "entries", "ops", "edges", "goals"]) db.run(`DROP TABLE IF EXISTS ${t}`);
-      db.run(`PRAGMA user_version = ${INDEX_VERSION}`);
+    // Announce before opening derived handles or reading rows; failed admission leaks no database handles.
+    if (!bootstrap) this.releaseReaderLease = registerReaderLease(this.profile.home);
+    let openedDb: Database | undefined, openedMutation: Database | undefined, openedSearch: SearchIndex | undefined;
+    try {
+      const db = openedDb = new Database(join(this.dir, "index.db"), { create: true });
+      db.run(`PRAGMA busy_timeout = ${MEMORY_DB_BUSY_TIMEOUT_MS}`);
+      db.run("PRAGMA journal_mode = WAL");
+      if ((db.query("PRAGMA user_version").get() as { user_version: number }).user_version !== INDEX_VERSION) {
+        for (const t of ["segments", "heads", "entries", "ops", "edges", "goals"]) db.run(`DROP TABLE IF EXISTS ${t}`);
+        db.run(`PRAGMA user_version = ${INDEX_VERSION}`);
+      }
+      db.run("CREATE TABLE IF NOT EXISTS segments (file TEXT PRIMARY KEY, offset INTEGER NOT NULL)");
+      // The hash of each segment's whole indexed prefix: a segment rewritten in place (same size or larger) is caught.
+      db.run("CREATE TABLE IF NOT EXISTS heads (file TEXT PRIMARY KEY, hash TEXT NOT NULL)");
+      db.run("CREATE TABLE IF NOT EXISTS goals (id TEXT PRIMARY KEY, at TEXT NOT NULL, machine TEXT NOT NULL, project TEXT NOT NULL, scope TEXT NOT NULL, title TEXT NOT NULL, milestones TEXT NOT NULL, depends TEXT NOT NULL, actor TEXT NOT NULL)");
+      db.run(`CREATE TABLE IF NOT EXISTS entries (id TEXT PRIMARY KEY, at TEXT NOT NULL, machine TEXT NOT NULL, project TEXT NOT NULL, scope TEXT NOT NULL, tier TEXT NOT NULL,
+        kind TEXT NOT NULL, peer TEXT NOT NULL, title TEXT, text TEXT NOT NULL, task TEXT, about TEXT NOT NULL, supersedes TEXT, promoted_from TEXT, source TEXT NOT NULL, expires TEXT)`);
+      db.run("CREATE TABLE IF NOT EXISTS ops (id TEXT PRIMARY KEY, op TEXT NOT NULL, at TEXT NOT NULL, machine TEXT NOT NULL, target TEXT NOT NULL, by TEXT, actor TEXT NOT NULL)");
+      db.run("CREATE TABLE IF NOT EXISTS edges (src TEXT NOT NULL, dst TEXT NOT NULL, PRIMARY KEY (src, dst))");
+      db.run("CREATE INDEX IF NOT EXISTS edges_dst ON edges (dst)");
+      this.db = db;
+      this.mutationDb = openedMutation = mutationDatabase(this.dir);
+      // One derived FTS copy per profile: a generation handle and a shared-v1 handle on one home never resync-fight.
+      this.searchIndex = openedSearch = new SearchIndex(this.profile.sharded ? join(this.dir, "search.db") : join(home, this.profile.kind === "generation" ? `search-${this.profile.generation}.db` : "search.db"));
+      this.memoryBaseDir = home;
+      try { chmodSync(join(this.dir, "index.db"), 0o600); } catch { /* best effort */ }
+      if (this.profile.kind === "generation") this.generationIndex = new GenerationIndex({ profile: this.profile, db, now: this.now,
+        apply: (line, source) => this.apply(line, source), withMutation: work => this.withMutation(work),
+        ...(bootstrap ? { limits: bootstrap.limits } : {}), ...(bootstrap?.commit ? { commit: bootstrap.commit } : {}) });
+      this.refresh();
+    } catch (error) {
+      for (const handle of [openedSearch, openedMutation, openedDb]) { try { handle?.close(); } catch { /* preserve the opening failure */ } }
+      const release = this.releaseReaderLease;
+      this.releaseReaderLease = undefined;
+      release?.();
+      throw error;
     }
-    db.run("CREATE TABLE IF NOT EXISTS segments (file TEXT PRIMARY KEY, offset INTEGER NOT NULL)");
-    // The hash of each segment's whole indexed prefix: a segment rewritten in place (same size or larger) is caught.
-    db.run("CREATE TABLE IF NOT EXISTS heads (file TEXT PRIMARY KEY, hash TEXT NOT NULL)");
-    db.run("CREATE TABLE IF NOT EXISTS goals (id TEXT PRIMARY KEY, at TEXT NOT NULL, machine TEXT NOT NULL, project TEXT NOT NULL, scope TEXT NOT NULL, title TEXT NOT NULL, milestones TEXT NOT NULL, depends TEXT NOT NULL, actor TEXT NOT NULL)");
-    db.run(`CREATE TABLE IF NOT EXISTS entries (id TEXT PRIMARY KEY, at TEXT NOT NULL, machine TEXT NOT NULL, project TEXT NOT NULL, scope TEXT NOT NULL, tier TEXT NOT NULL,
-      kind TEXT NOT NULL, peer TEXT NOT NULL, title TEXT, text TEXT NOT NULL, task TEXT, about TEXT NOT NULL, supersedes TEXT, promoted_from TEXT, source TEXT NOT NULL, expires TEXT)`);
-    db.run("CREATE TABLE IF NOT EXISTS ops (id TEXT PRIMARY KEY, op TEXT NOT NULL, at TEXT NOT NULL, machine TEXT NOT NULL, target TEXT NOT NULL, by TEXT, actor TEXT NOT NULL)");
-    db.run("CREATE TABLE IF NOT EXISTS edges (src TEXT NOT NULL, dst TEXT NOT NULL, PRIMARY KEY (src, dst))");
-    db.run("CREATE INDEX IF NOT EXISTS edges_dst ON edges (dst)");
-    this.db = db;
-    this.mutationDb = mutationDatabase(this.dir);
-    try { chmodSync(join(this.dir, "index.db"), 0o600); } catch { /* best effort */ }
-    if (this.profile.kind === "generation") this.generationIndex = new GenerationIndex({ profile: this.profile, db, now: this.now,
-      apply: (line, source) => this.apply(line, source), withMutation: work => this.withMutation(work),
-      ...(bootstrap ? { limits: bootstrap.limits } : {}), ...(bootstrap?.commit ? { commit: bootstrap.commit } : {}) });
-    this.refresh();
   }
 
   /** The host must authenticate person intent before authorizing plan/apply through this port. */
@@ -248,13 +292,72 @@ export class MemoryStore {
     return this.generationIndex.port(this.machine.id);
   }
 
+  /** Read-only project views, bounded before bodies or hashes; never promotes or authors a prune. */
+  vaultEntries(project: string): VaultEntry[] {
+    if (!project.trim() || this.profile.sharded && !this.profile.shardUser && this.profile.shardKey !== project) throw new Error("vault project does not match the bound store");
+    this.withDeferredPromotions(() => this.ensureFresh());
+    const scanLimit = 5000;
+    const own = this.db.query("SELECT id FROM entries WHERE project IN (SELECT value FROM json_each(?)) LIMIT ?").all(JSON.stringify(this.scopeKeys(project)), scanLimit + 1) as { id: string }[];
+    if (own.length > scanLimit) throw new Error("vault scan budget exceeded; refine the store before retrying");
+    const overlay = new Map([...(this.userOverlay?.vaultEntries(project) ?? []), ...this.aliasStores.flatMap(store => store.vaultEntries(store.profile.shardKey!))].map(entry => [entry.view.id, entry.rowHash]));
+    if (new Set([...own.map(row => row.id), ...overlay.keys()]).size > scanLimit) throw new Error("vault scan budget exceeded; refine the store before retrying");
+    const authored = this.generationIndex?.vaultWitnesses(own.map(row => row.id));
+    return this.views(false, { project }).filter(view => view.project === project).map(view => {
+      // A shared-v1 read cannot record links and needs no authored witness or new index field.
+      const rowHash = this.generationIndex ? authored?.get(view.id) ?? overlay.get(view.id) : "";
+      if (rowHash === undefined) throw new Error("authored vault entry witness unavailable");
+      return { view, rowHash };
+    });
+  }
+  vaultLinks(project: string): VaultLink[] {
+    this.ensureFresh();
+    if (!project.trim() || this.profile.sharded && !this.profile.shardUser && this.profile.shardKey !== project) throw new Error("vault project does not match the bound store");
+    return [...this.scopeKeys(project).flatMap(key => this.generationIndex?.vaultLinks(key) ?? []), ...(this.userOverlay?.vaultLinks(project) ?? []), ...this.aliasStores.flatMap(store => store.vaultLinks(store.profile.shardKey!))];
+  }
+  /** Exact id/hash recheck under the existing mutation fence; never follows promoted/superseded aliases. */
+  recordVaultLink(id: string, path: string, project: string, rowHash: string): string {
+    if (this.bootstrapOnly || !this.generationIndex) throw new Error("vault links require an active generation handle");
+    if (this.userOverlay?.vaultEntries(project).some(entry => entry.view.id === id)) return this.userOverlay.recordVaultLink(id, path, project, rowHash);
+    const aliased = this.aliasStores.find(store => store.vaultEntries(store.profile.shardKey!).some(entry => entry.view.id === id));
+    if (aliased) return aliased.recordVaultLink(id, path, aliased.profile.shardKey!, rowHash);
+    return this.withMutation(() => {
+      this.refresh();
+      const entry = this.vaultEntries(project).find(row => row.view.id === id && row.rowHash === rowHash);
+      if (!entry || entry.view.tier !== "long" || entry.view.local || entry.view.supersededBy) throw new Error("exact vault entry changed or unavailable");
+      // A link names the key the row was written under (never the canonical label a reconciled read shows), so a raw-key reader still finds it.
+      const written = this.rawProject(entry.view);
+      const prior = this.vaultLinks(project).find(row => row.target === id && row.rowHash === rowHash && row.path === path);
+      if (prior) return prior.id;
+      const body = { schema: "agent-mem.vault-link/v1", op: "vault_link", generation: this.profile.generation!,
+        at: new Date(this.now()).toISOString(), machine: this.machine.id, actor: "person", placement: "local", target: id, rowHash, project: written, path } as const;
+      const row: VaultLinkRow = { ...body, id: vaultLinkId(body) };
+      validateVaultLinkRow(row, this.profile.generation, "local");
+      this.generationIndex!.assertAppendable(true, this.machine.id);
+      const file = join(this.dir, "local", `${this.machine.id}.jsonl`), existed = existsSync(file);
+      const fd = openSync(file, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+      try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.nlink !== 1) throw new Error("vault link segment is not an owned regular file");
+        appendFileSync(fd, canonicalJSON(row) + "\n"); fsyncSync(fd);
+      } finally { closeSync(fd); }
+      if (!existed) fsyncDirectory(join(this.dir, "local"));
+      try { this.refresh(); } catch (error) { this.stale = true; throw error; }
+      return row.id;
+    });
+  }
+
   /** Full derived receipt for golden replay; raw debug data, never model evidence. */
   derivedTables(): Record<string, unknown[]> {
     const tables = this.db.query("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name").all() as { name: string }[];
     return Object.fromEntries(tables.map(({ name }) => [name, (this.db.query(`SELECT * FROM "${name.replaceAll('"', '""')}"`).all() as unknown[]).sort((a, b) => canonicalJSON(a).localeCompare(canonicalJSON(b)))]));
   }
 
-  close(): void { this.db.close(); this.mutationDb.close(); }
+  close(): void {
+    const release = this.releaseReaderLease;
+    this.releaseReaderLease = undefined;
+    try { this.db.close(); this.mutationDb.close(); this.searchIndex.close(); }
+    finally { try { this.userOverlay?.close(); } finally { try { for (const store of this.aliasStores) store.close(); } finally { release?.(); } } }
+  }
 
   /** A synchronous host-authorized mutation whose reads must not implicitly promote unrelated notes. */
   withDeferredPromotions<T>(work: () => T): T {
@@ -269,6 +372,7 @@ export class MemoryStore {
 
   /** Serialize current-store writers, screen one normalized body, and expose a one-shot append of that body. */
   withAcceptedNote<T>(note: NoteInput, work: (append: () => string) => T): T {
+    if (this.userOverlay && note.scope === "shared") return this.userOverlay.withAcceptedNote(note, work);
     try { return this.withMutation(() => {
       // Ordinary writes may defer indexing, but accepting an exact target revision must have a current index.
       this.db.transaction(() => this.refresh()).immediate();
@@ -307,6 +411,12 @@ export class MemoryStore {
 
   private appendBody(body: Omit<Entry, "id">, local: boolean): string {
     if (this.bootstrapOnly) throw new Error("migration bootstrap cannot author memory");
+    if (this.userOverlay && (body.op === "note" || body.op === "goal") && "scope" in body && body.scope === "shared") return this.userOverlay.appendBody(body, local);
+    if ("target" in body && body.op !== "settle") { const owner = this.ownerOf(body.target as string); if (owner) return owner.appendBody(body, local); }
+    if (this.profile.sharded && (body.op === "note" || body.op === "goal") && "scope" in body && "project" in body) {
+      if (this.profile.shardUser ? body.scope !== "shared" : body.scope !== "project" || body.project !== this.profile.shardKey) throw new Error("entry does not belong to this curated shard");
+    }
+    if (this.profile.sharded && body.op === "settle" && "target" in body && (typeof body.target !== "string" || (!this.profile.shardUser && !body.target.startsWith(`${this.profile.shardKey}#`)))) throw new Error("settlement does not belong to this curated shard");
     assertSharedV1Op(body.op);
     // Lock the authoritative log independently: a busy derived index must never prevent an ordinary append.
     return this.withMutation(() => {
@@ -330,6 +440,8 @@ export class MemoryStore {
    */
   importNote(n: NoteInput, at: string): { id: string; added: boolean } {
     if (this.bootstrapOnly) throw new Error("migration bootstrap cannot import memory");
+    if (this.userOverlay && n.scope === "shared") return this.userOverlay.importNote(n, at);
+    if (this.profile.sharded && (this.profile.shardUser ? n.scope !== "shared" : n.scope !== "project" || n.project !== this.profile.shardKey)) throw new Error("entry does not belong to this curated shard");
     assertSharedV1Op(n.op);
     // A fixed machine: the same observation imported on two machines is one entry once they sync.
     const body = { schema: MEMORY_SCHEMA, at, machine: "claude-mem", ...n, text: n.text.slice(0, MAX_TEXT), ...(n.title ? { title: n.title.slice(0, MAX_TITLE) } : {}) } as Omit<Entry, "id">;
@@ -419,6 +531,8 @@ export class MemoryStore {
    */
   promote(id: string, actor: string, project?: string, auto = false): string | undefined {
     const v = this.get(id, project);
+    const owner = v ? this.ownerOf(v.id) : undefined;
+    if (v && owner) return owner.promote(v.id, actor, owner.profile.shardKey ?? project, auto);
     if (v && this.generationIndex && !this.generationIndex.own(v.id)) return undefined;
     if (!v || v.tier !== "short") return v?.id;
     if (v.supersededBy) return undefined;
@@ -429,7 +543,7 @@ export class MemoryStore {
     // ponytail: the check and the append are not one step across processes: a person forgetting or replacing this entry
     // at the very moment another process promotes it can leave the copy current on other machines. A per-machine lock
     // around local mutations (like sync's) would close it.
-    return this.append({ op: "note", project: v.project, scope: v.scope, tier: "long", kind: v.kind, peer: v.peer, ...(v.title ? { title: v.title } : {}), text: v.text,
+    return this.append({ op: "note", project: this.rawProject(v), scope: v.scope, tier: "long", kind: v.kind, peer: v.peer, ...(v.title ? { title: v.title } : {}), text: v.text,
       ...(v.task ? { task: v.task } : {}), about: v.about, promotedFrom: v.id, source: v.source as NoteEntry["source"] }, false,
       // Dated as its source, from its source's machine and with its fields, whoever promotes and wherever: two processes or
       // two machines promoting the same entry write one id, which the index keeps once.
@@ -442,8 +556,13 @@ export class MemoryStore {
   settle(task: string, actor: string): number {
     this.promoting = true; // promoted here, in the settling actor's name, not after each read
     try {
-      this.append({ op: "settle", target: task, actor, by: this.until() }, true);
-      return this.promoteSettled(task, actor);
+      const entry = { op: "settle", target: task, actor, by: this.until() } as const;
+      const at = new Date(this.now()).toISOString();
+      // #27: a task key `<key>#...` belongs to the shard of `<key>`. In a reconciled sharded store that can be an aliased key's shard, which refuses a settlement of any other key.
+      const owner = this.aliasStores.find(store => store.profile.shardKey !== undefined && task.startsWith(`${store.profile.shardKey}#`));
+      (owner ?? this).append(entry, true, at, owner ? this.machine.id : undefined);
+      if (this.userOverlay) this.userOverlay.append(entry, true, at, this.machine.id);
+      return this.promoteSettled(task, actor) + (this.userOverlay?.promoteSettled(task, actor) ?? 0) + this.aliasStores.reduce((n, store) => n + store.promoteSettled(task, actor), 0);
     } finally { this.promoting = false; }
   }
   private promoteSettled(task: string, actor: string): number {
@@ -453,12 +572,12 @@ export class MemoryStore {
   }
   /** Whether a task was settled in this profile. Reconciliation may opt into bridged legacy settlements. */
   settled(task: string, options: { includeLegacy?: boolean } = {}): boolean {
-    return !!this.db.query(this.generationIndex && !options.includeLegacy
+    return this.readRows(this.generationIndex && !options.includeLegacy
       ? "SELECT 1 FROM ops JOIN generation_rows ON generation_rows.id=ops.id WHERE op='settle' AND target=? AND own=1"
-      : "SELECT 1 FROM ops WHERE op = 'settle' AND target = ?").get(task);
+      : "SELECT 1 FROM ops WHERE op = 'settle' AND target = ?", task).length > 0;
   }
   /** Whether any entry was saved against the task. */
-  hasTask(task: string): boolean { return !!this.db.query("SELECT 1 FROM entries WHERE task = ?").get(task); }
+  hasTask(task: string): boolean { this.ensureFresh(); return this.readRows("SELECT 1 FROM entries WHERE task = ?", task).length > 0; }
   private promoting = false;
   private readonly screen?: PromotionScreen;
   /**
@@ -546,9 +665,14 @@ export class MemoryStore {
 
   /** Drop the index and read every segment again: the same rows as the incremental index. */
   rebuild(): void {
+    this.searchIndex.reset();
     if (this.generationIndex) { this.generationIndex.rebuild(); return; }
     // One transaction: no reader sees the index empty, and no other process commits an offset in between.
-    this.db.transaction(() => { for (const t of ["segments", "heads", "entries", "ops", "edges", "goals"]) this.db.run(`DELETE FROM ${t}`); this.refresh(); }).immediate();
+    this.rebuildingSearch = true;
+    try {
+      this.db.transaction(() => { for (const t of ["segments", "heads", "entries", "ops", "edges", "goals"]) this.db.run(`DELETE FROM ${t}`); this.refresh(); }).immediate();
+    } finally { this.rebuildingSearch = false; }
+    this.syncSearchIndex(); // one batched derived write, not one search.db transaction per rebuilt entry
   }
 
   private segments(sub: "log" | "local"): string[] {
@@ -572,9 +696,13 @@ export class MemoryStore {
     if (e.op === "note") {
       if (!KINDS.includes(e.kind) || typeof e.text !== "string" || !Array.isArray(e.about) || !str(e.project, 400) || !str(e.peer, 64)
         || !opt(e.title) || !opt(e.task) || !opt(e.supersedes) || !opt(e.promotedFrom) || !opt(e.expires) || (typeof e.expires === "string" && Number.isNaN(Date.parse(e.expires))) || !opt(e.source) || !["project", "shared"].includes(e.scope as string) || !["short", "long"].includes(e.tier as string)) { this.log(`memory segment ${segment}: a malformed entry was skipped`); return; }
-      this.db.query(`INSERT OR IGNORE INTO entries (id, at, machine, project, scope, tier, kind, peer, title, text, task, about, supersedes, promoted_from, source, expires)
+      const inserted = this.db.query(`INSERT OR IGNORE INTO entries (id, at, machine, project, scope, tier, kind, peer, title, text, task, about, supersedes, promoted_from, source, expires)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, e.at, e.machine, e.project, e.scope === "shared" ? "shared" : "project", e.tier === "long" ? "long" : "short",
-        e.kind, e.peer, e.title ?? null, e.text, e.task ?? null, JSON.stringify(e.about.map(String)), e.supersedes ?? null, e.promotedFrom ?? null, e.source ?? "hub", typeof e.expires === "string" ? e.expires : null);
+        e.kind, e.peer, e.title ?? null, e.text, e.task ?? null, JSON.stringify(e.about.map(String)), e.supersedes ?? null, e.promotedFrom ?? null, e.source ?? "hub", typeof e.expires === "string" ? e.expires : null).changes;
+      // The FTS copy follows the committed row. `changes` is only a hint here (bun:sqlite misreports it for ignored
+      // inserts inside a transaction): addCurated is idempotent by entry id, and a missed hint becomes a count drift
+      // the next search resyncs.
+      if (inserted && !this.rebuildingSearch) this.searchIndex.addCurated({ id, at: e.at, project: e.project, tier: e.tier === "long" ? "long" : "short", scope: e.scope === "shared" ? "shared" : "project", body: `${e.title ?? ""}\n${e.text}\n${e.about.map(String).join(" ")}` });
       for (const node of e.about) this.db.query("INSERT OR IGNORE INTO edges (src, dst) VALUES (?, ?)").run(id, String(node));
     } else if (e.op === "goal") {
       if (!str(e.title, 400) || !Array.isArray(e.milestones) || !Array.isArray(e.dependsOn) || !str(e.project, 400) || !opt(e.actor) || !opt(e.scope)) { this.log(`memory segment ${segment}: a malformed entry was skipped`); return; }
@@ -588,26 +716,59 @@ export class MemoryStore {
     }
   }
 
+  /** Only the bound project and user overlay participate; never scan another project's private shard. */
+  private readStores(): MemoryStore[] { return [this, ...(this.userOverlay ? [this.userOverlay] : []), ...this.aliasStores]; }
+  /** #27: the keys a project filter covers: the project, and with a reconciled read every key aliased to it. */
+  private scopeKeys(project: string): string[] { return this.reconcile && project === this.reconcile.canonical ? [project, ...this.reconcile.aliases] : [project]; }
+  private inScope(rowProject: string, project: string): boolean { return this.scopeKeys(project).includes(rowProject); }
+  /** The key a row was written under. A reconciled read labels aliased rows with the canonical key, but every write that copies a row keeps its own key (#27). */
+  private rawProject(view: View): string {
+    if (!this.reconcile || !this.reconcile.aliases.length) return view.project;
+    for (const store of this.readStores()) {
+      const row = store.db.query("SELECT project FROM entries WHERE id = ?").get(view.id) as { project: string } | null;
+      if (row) return row.project;
+    }
+    return view.project;
+  }
+  /** A row of an aliased key reads under the canonical key. */
+  private label(project: string): string { return this.reconcile?.aliases.includes(project) ? this.reconcile.canonical : project; }
+  /** The store that holds the log line of `id`, when it is not this one: the user overlay or an aliased key's shard. */
+  private ownerOf(id: string): MemoryStore | undefined { return [...(this.userOverlay ? [this.userOverlay] : []), ...this.aliasStores].find(store => store.ownsTarget(id)); }
+
+  private readRows(sql: string, ...bind: string[]): Record<string, unknown>[] {
+    const rows = this.readStores().flatMap(store => store.db.query(sql).all(...bind) as Record<string, unknown>[]);
+    const unique = new Map<string, Record<string, unknown>>();
+    for (const row of rows) unique.set(typeof row.id === "string" ? row.id : canonicalJSON(row), row);
+    return [...unique.values()].sort((a, b) => String(a.at ?? "").localeCompare(String(b.at ?? "")) || String(a.id ?? "").localeCompare(String(b.id ?? "")));
+  }
+
+  private ownsTarget(id: string): boolean {
+    this.ensureFresh();
+    return !!this.db.query("SELECT id FROM entries WHERE id=? UNION SELECT id FROM goals WHERE id=? UNION SELECT id FROM ops WHERE id=?").get(id, id, id);
+  }
+
   /**
    * Every live note with its derived state; an expired one is left out as soon as its deadline passes, before any
    * prune. Lifecycle relations still fold globally; SQL selects full rows before View/JSON materialization.
    * ponytail: lifecycle metadata is still scanned on every read; measure before adding a revision cache.
    */
-  private views(expired = false, selection?: Filter, expiredOnly = false): View[] {
+  private views(expired = false, selection?: Filter & { ids?: string[] }, expiredOnly = false): View[] {
     // Metadata, ops and candidate bodies must describe one WAL snapshot, even if another process indexes a copy.
-    return this.db.transaction(() => this.viewRows(expired, selection, expiredOnly)).deferred();
+    const read = () => this.viewRows(expired, selection, expiredOnly);
+    const nest = (stores: MemoryStore[]): View[] => stores.length ? stores[0]!.db.transaction(() => nest(stores.slice(1))).deferred() : read();
+    return nest(this.readStores());
   }
 
-  private viewRows(expired: boolean, selection: Filter | undefined, expiredOnly: boolean): View[] {
+  private viewRows(expired: boolean, selection: (Filter & { ids?: string[] }) | undefined, expiredOnly: boolean): View[] {
     const now = this.now(), selecting = selection !== undefined || expiredOnly;
-    const pruned = this.generationIndex ? new Set((this.db.query("SELECT id FROM generation_targets").all() as { id: string }[]).map(row => row.id)) : undefined;
-    if (this.generationIndex && pruned) this.generationIndex.pruned = pruned;
+    const pruned = this.generationIndex ? new Set((this.readRows("SELECT id FROM generation_targets") as { id: string }[]).map(row => row.id)) : undefined;
+    if (this.generationIndex) this.generationIndex.pruned = new Set((this.db.query("SELECT id FROM generation_targets").all() as { id: string }[]).map(row => row.id));
     // Relations may cross projects and promoted copies: fold their small metadata globally, never filtered bodies.
-    const rows = this.db.query(selecting
+    const rows = this.readRows(selecting
       ? "SELECT id, at, tier, kind, task, expires, supersedes, promoted_from FROM entries"
-      : "SELECT * FROM entries").all() as Record<string, string | null>[];
-    const ops = this.db.query("SELECT id, op, at, target, by FROM ops ORDER BY at, id").all() as { id: string; op: string; at: string; target: string; by: string | null }[];
-    const realms = this.generationIndex ? new Map((this.db.query("SELECT id,own,legacy FROM generation_rows").all() as { id: string; own: number; legacy: number }[]).map(row => [row.id, row])) : undefined;
+      : "SELECT * FROM entries") as Record<string, string | null>[];
+    const ops = this.readRows("SELECT id, op, at, target, by FROM ops ORDER BY at, id") as { id: string; op: string; at: string; target: string; by: string | null }[];
+    const realms = this.generationIndex ? new Map((this.readRows("SELECT id,own,legacy FROM generation_rows") as { id: string; own: number; legacy: number }[]).map(row => [row.id, row])) : undefined;
     const born = realms ? new Set([...realms.values()].filter(row => row.own).map(row => row.id)) : undefined;
     const forgotten = new Set(ops.filter((o) => o.op === "forget").map((o) => o.target));
     // Deadlines were fixed when the entries were written, so every process (whatever its own TTL) prunes the same rows.
@@ -693,7 +854,13 @@ export class MemoryStore {
       ids(hidden, true);
       if (expiredOnly) ids(expiredIds, false); else if (!expired) ids(expiredIds, true);
       if (selection) {
-        if (selection.project) { where.push("(project = ? OR scope = 'shared')"); bind.push(selection.project); }
+        if (selection.project) {
+          // The exact-key form is unchanged unless a reconciled read widens it (#27).
+          const keys = this.scopeKeys(selection.project);
+          if (keys.length === 1) { where.push("(project = ? OR scope = 'shared')"); bind.push(selection.project); }
+          else { where.push("(project IN (SELECT value FROM json_each(?)) OR scope = 'shared')"); bind.push(JSON.stringify(keys)); }
+        }
+        if (selection.ids) ids(selection.ids, false);
         if (selection.tier) {
           if (demoted.size) { where.push("CASE WHEN id IN (SELECT value FROM json_each(?)) THEN 'short' ELSE tier END = ?"); bind.push(JSON.stringify([...demoted.keys()]), selection.tier); }
           else { where.push("tier = ?"); bind.push(selection.tier); }
@@ -703,7 +870,7 @@ export class MemoryStore {
       }
       // No SQL LIMIT: a host may screen the complete matching set before its own caps or visible counts.
       // Date parsing, Unicode query matching, locale order and slice semantics stay in JavaScript.
-      candidates = this.db.query(`SELECT * FROM entries${where.length ? ` WHERE ${where.join(" AND ")}` : ""}`).all(...bind) as Record<string, string | null>[];
+      candidates = this.readRows(`SELECT * FROM entries${where.length ? ` WHERE ${where.join(" AND ")}` : ""}`, ...bind) as Record<string, string | null>[];
     }
     const out: View[] = [];
     for (const r of candidates) {
@@ -713,7 +880,7 @@ export class MemoryStore {
       const tier: Tier = demoted.has(id) ? "short" : r.tier as Tier;
       const expiresAt = expiry(r);
       if (!expired && expiresAt !== null && Date.parse(expiresAt) <= now) continue;
-      out.push({ id, at: r.at!, machine: r.machine!, project: r.project!, scope: r.scope as Scope, tier, kind: r.kind as Kind, peer: r.peer!, title: r.title ?? null, text: r.text!,
+      out.push({ id, at: r.at!, machine: r.machine!, project: this.label(r.project!), scope: r.scope as Scope, tier, kind: r.kind as Kind, peer: r.peer!, title: r.title ?? null, text: r.text!,
         task: r.task ?? null, about: JSON.parse(r.about!), source: r.source!, supersededBy: superseded.get(id) ?? null, supersedes: supersedes.get(id) ?? [], promotedFrom: r.promoted_from ?? null, expiresAt, local: r.tier === "short" });
     }
     return out;
@@ -734,11 +901,14 @@ export class MemoryStore {
     for (const v of expired) for (let id: string | undefined = v.id; id && !gone.has(id); id = parent.get(id)) gone.add(id);
     if (!gone.size) return 0;
     this.db.transaction(() => { for (const id of gone) { this.db.query("DELETE FROM entries WHERE id = ?").run(id); this.db.query("DELETE FROM edges WHERE src = ?").run(id); } }).immediate();
+    this.searchIndex.markDirty(); // FTS cannot subtract rows incrementally: the next search resyncs it
     return gone.size;
   }
 
   /** Index deferred writes before any note, goal or suggestion read. */
   private ensureFresh(): void {
+    this.userOverlay?.ensureFresh();
+    for (const store of this.aliasStores) store.ensureFresh();
     if (this.generationIndex) { this.generationIndex.refresh(); return; }
     // Another process (a CLI, another project's hub, a sync) may have written since this one last read the segments.
     if (this.stale || this.shape() !== this.seen) try { this.stale = false; this.refresh(); } catch { this.stale = true; /* still busy: the next read tries again */ }
@@ -750,7 +920,7 @@ export class MemoryStore {
    */
   private live(selection?: Filter): View[] {
     this.ensureFresh();
-    this.prune(); this.promoteHeld(); return this.views(false, selection);
+    this.prune(); this.userOverlay?.promoteHeld(); for (const store of this.aliasStores) store.promoteHeld(); this.promoteHeld(); return this.views(false, selection);
   }
   /** A write whose index update failed: the next read refreshes first. */
   private stale = false;
@@ -758,24 +928,118 @@ export class MemoryStore {
   /** Entries visible from `project` (its own, and `shared` ones of any project), newest first, filtered. */
   list(f: Filter = {}): View[] {
     const q = f.q?.toLowerCase().split(/\s+/).filter(Boolean) ?? [];
-    return this.live(f).filter((v) => (!f.project || v.project === f.project || v.scope === "shared") && (!f.tier || v.tier === f.tier) && (!f.kind || v.kind === f.kind)
+    return this.live(f).filter((v) => (!f.project || this.inScope(v.project, f.project) || v.scope === "shared") && (!f.tier || v.tier === f.tier) && (!f.kind || v.kind === f.kind)
       && (!f.peer || v.peer === f.peer) && (!f.machine || v.machine === f.machine) && (!f.since || Date.parse(v.at) >= Date.parse(f.since)) && (f.includeSuperseded || !v.supersededBy)
       && q.every((w) => `${v.title ?? ""}\n${v.text}\n${v.about.join(" ")}`.toLowerCase().includes(w)))
       .sort((a, b) => b.at.localeCompare(a.at) || a.id.localeCompare(b.id)).slice(0, f.limit ?? 200);
   }
 
+  /** Exact-project body pages for policy-aware callers. Relations still fold over complete metadata. */
+  readPage(window: ReadWindow & { query?: string; includeSuperseded?: boolean }): { rows: View[]; next?: ReadRef } {
+    this.ensureFresh(); this.prune();
+    const refs: ReadRef[] = [];
+    for (const store of this.readStores()) {
+      if (window.query !== undefined && store.searchIndex.available) {
+        store.syncSearchIndex(); refs.push(...store.searchIndex.candidates(window.query, this.reconcile ? { ...window, projects: this.scopeKeys(window.project) } : window));
+      } else {
+        const { columns, where, bind } = readWindowSql(this.reconcile ? { ...window, projects: this.scopeKeys(window.project) } : window, "id");
+        refs.push(...(store.db.query(`SELECT ${columns} FROM entries WHERE ${where.join(" AND ")} ORDER BY candidate_position, candidate_id LIMIT ?`)
+          .all(...bind, window.limit) as { candidate_id: string; at: string; candidate_position: number }[]).map(readRef));
+      }
+    }
+    const page = [...new Map(refs.map(ref => [ref.id, ref])).values()].sort((a, b) => a.position - b.position || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)).slice(0, window.limit);
+    if (!page.length) return { rows: [] };
+    const views = new Map(this.views(false, { project: window.project, ids: page.map(ref => ref.id), includeSuperseded: window.includeSuperseded })
+      .filter(view => view.project === window.project && (window.includeSuperseded || !view.supersededBy)).map(view => [view.id, view]));
+    return { rows: page.flatMap(ref => views.get(ref.id) ?? []), next: page[page.length - 1] };
+  }
+
+  /**
+   * #13 R5: natural-language search over the curated tier and this machine's capture tier, ranked by BM25 with
+   * tier and recency weights (curated outranks capture; a newer row beats an older one at equal text). Visibility
+   * (forgotten, superseded, expired, pruned) is decided by the same live views `list` uses. Without FTS5 the engine
+   * falls back to the substring filter and says so; capture recall needs FTS5 and is skipped in the fallback (the
+   * R3 cost of the fallback is the pre-#13 behavior: same scan, same memory).
+   */
+  search(q: string, f: SearchFilter = {}): SearchResult {
+    const limit = f.limit ?? 200;
+    if (!this.searchIndex.available) return { engine: "substring", hits: this.list({ ...f, q }).map((view) => ({ source: "curated" as const, score: 0, view })) };
+    const visible = new Map(this.live(f).filter((v) => (!f.project || this.inScope(v.project, f.project) || v.scope === "shared")
+      && (!f.since || Date.parse(v.at) >= Date.parse(f.since)) && (f.includeSuperseded || !v.supersededBy)).map((v) => [v.id, v]));
+    for (const store of this.readStores()) store.syncSearchIndex();
+    const now = this.now();
+    const recency = (at: string): number => 1 / (1 + Math.max(0, now - Date.parse(at)) / (30 * 24 * 3600_000));
+    const hits: SearchHit[] = [];
+    // The project filter runs inside the FTS query (its rows plus shared ones), so a busy sibling project can never
+    // starve this project's LIMIT.
+    // Superseded, forgotten, expired and `since` rows are filtered after FTS, so a fixed candidate cap could be filled
+    // by invisible rows and hide a visible match: widen the cap until `limit` visible hits or the index is exhausted.
+    // Pages of fixed size, so memory stays one page plus the hits (#13 R3) however many invisible rows rank first.
+    // ponytail: with almost nothing visible (a selective `since`, many superseded or forgotten rows) the pages walk the
+    // store's whole match set; push `since` into SearchIndex.query (docs carries `at`) if that time shows up.
+    const page = Math.max(limit * 4, 32);
+    for (const store of visible.size ? this.readStores() : []) {
+      let found = 0;
+      const seen = new Set<string>(); // another process's sync between pages can shift offsets and repeat a ref
+      for (let offset = 0; found < limit; offset += page) {
+        const ranked = store.searchIndex.query(q, page, f.project === undefined ? undefined : this.scopeKeys(f.project), offset);
+        for (const hit of ranked) {
+          const view = visible.get(hit.ref);
+          if (!view || seen.has(hit.ref)) continue;
+          seen.add(hit.ref);
+          found++;
+          hits.push({ source: "curated", score: -hit.rank * (view.tier === "long" ? 1 : 0.9) * recency(hit.at), view });
+        }
+        if (ranked.length < page) break;
+      }
+    }
+    // #15 D4/T1: the capture tier is project-scoped; without a project key there is no shard to recall from.
+    if (f.includeCapture !== false && f.project) {
+      const shard = shardMachineDir(this.memoryBaseDir, resolveAlias(this.memoryBaseDir, f.project), this.machine.id);
+      // The retention cutoff and `since` run in the capture query, so neither expired nor old rows take a candidate slot.
+      // An out-of-range retention_days gives no cutoff rather than failing the whole search (eviction keeps its own check).
+      const override = f.captureRetentionDays, days = typeof override === "number" && Number.isFinite(override) && override > 0 ? override : readCaptureConfig(shard, this.memoryBaseDir).retentionDays;
+      const cutoff = new Date(now - days * 24 * 3600_000);
+      const retained = Number.isFinite(cutoff.getTime()) ? cutoff.toISOString() : undefined;
+      const since = f.since && Number.isFinite(Date.parse(f.since)) ? new Date(Date.parse(f.since)).toISOString() : undefined;
+      for (const { row, rank } of captureSearch(shard, q, Math.max(limit * 4, 32), since && (!retained || since > retained) ? since : retained)) {
+        hits.push({ source: "capture", score: -rank * 0.5 * recency(row.at), capture: row });
+      }
+    }
+    // Where FTS misses entirely (a stopword-only query, a tokenization edge), the substring filter is the safety net.
+    if (!hits.length && q.trim()) {
+      for (const view of this.list({ ...f, q })) hits.push({ source: "curated", score: 0, view });
+    }
+    const ref = (h: SearchHit): string => h.view?.id ?? String(h.capture?.id ?? 0).padStart(12, "0");
+    hits.sort((a, b) => b.score - a.score || ref(a).localeCompare(ref(b)));
+    return { engine: "fts5", hits: hits.slice(0, limit) };
+  }
+
+  /** Bring the derived FTS copy level with the curated rows when a prune, a crash, a lock or a rebuild drifted them apart. */
+  private syncSearchIndex(): void {
+    if (!this.searchIndex.available) return;
+    const curated = (this.db.query("SELECT COUNT(*) AS n FROM entries").get() as { n: number }).n;
+    if (!this.searchIndex.needsResync(curated)) return;
+    const db = this.db;
+    this.searchIndex.resync(function* () {
+      for (const r of db.query("SELECT id, at, project, tier, scope, title, text, about FROM entries").iterate() as Iterable<{ id: string; at: string; project: string; tier: string; scope: string; title: string | null; text: string; about: string }>) {
+        yield { id: r.id, at: r.at, project: r.project, tier: r.tier, scope: r.scope, body: `${r.title ?? ""}\n${r.text}\n${(JSON.parse(r.about) as string[]).join(" ")}` };
+      }
+    });
+  }
+
   /** One entry by id or unique id prefix; with `project`, only one that project may read (its own or shared). */
   get(id: string, project?: string): View | undefined {
     id = id.replace(/^mem:/, ""); // briefs and recall print `mem:<id>`
-    const all = this.live().filter((v) => !project || v.project === project || v.scope === "shared");
+    const all = this.live().filter((v) => !project || this.inScope(v.project, project) || v.scope === "shared");
     const pick = <T extends { id: string }>(rows: T[]) => rows.find((v) => v.id === id) ?? (id.length >= 6 ? (() => { const m = rows.filter((v) => v.id.startsWith(id)); return m.length === 1 ? m[0] : undefined; })() : undefined);
     if (this.generationIndex?.pruned.has(id)) return undefined;
     const found = pick(all);
     if (found) return found;
     // A short-term id an agent kept after its task was approved names the promoted copy now, here or on another machine
     // that has only the synced copy (which names its source).
-    let at = pick(this.db.query("SELECT id FROM entries UNION SELECT promoted_from FROM entries WHERE promoted_from IS NOT NULL").all() as { id: string }[])?.id;
-    for (let copy = at; copy; copy = (this.db.query("SELECT id FROM entries WHERE promoted_from = ?").get(copy) as { id: string } | null)?.id) { if (this.generationIndex?.pruned.has(copy)) return undefined; at = copy; }
+    let at = pick(this.readRows("SELECT id FROM entries UNION SELECT promoted_from AS id FROM entries WHERE promoted_from IS NOT NULL") as { id: string }[])?.id;
+    for (let copy = at; copy; copy = (this.readRows("SELECT id FROM entries WHERE promoted_from = ?", copy)[0] as { id: string } | undefined)?.id) { if (this.generationIndex?.pruned.has(copy)) return undefined; at = copy; }
     return at ? all.find((v) => v.id === at) : undefined;
   }
 
@@ -793,7 +1057,7 @@ export class MemoryStore {
     const near = new Map<string, 1 | 2>();
     const about = (ns: Iterable<Node>) => {
       const ids = new Set<string>();
-      for (const n of ns) for (const r of this.db.query("SELECT src FROM edges WHERE dst = ?").all(n) as { src: string }[]) if (live.has(r.src)) ids.add(r.src);
+      for (const n of ns) for (const r of this.readRows("SELECT src FROM edges WHERE dst = ?", n) as { src: string }[]) if (live.has(r.src)) ids.add(r.src);
       return ids;
     };
     const first = about(nodes);
@@ -893,9 +1157,9 @@ export class MemoryStore {
   goals(project?: string): GoalView[] {
     this.ensureFresh();
     const now = this.now();
-    const rows = this.db.query("SELECT * FROM goals").all() as { id: string; at: string; machine: string; project: string; scope: string; title: string; milestones: string; depends: string }[];
-    const ops = this.db.query("SELECT op, at, machine, target, by FROM ops WHERE op IN ('goal_state', 'goal_link', 'lease', 'lease_force') ORDER BY at, id").all() as { op: string; at: string; machine: string; target: string; by: string | null }[];
-    return rows.filter((r) => !project || r.project === project || r.scope === "shared").map((r): GoalView => {
+    const rows = this.readRows("SELECT * FROM goals") as { id: string; at: string; machine: string; project: string; scope: string; title: string; milestones: string; depends: string }[];
+    const ops = this.readRows("SELECT id, op, at, machine, target, by FROM ops WHERE op IN ('goal_state', 'goal_link', 'lease', 'lease_force') ORDER BY at, id") as { op: string; at: string; machine: string; target: string; by: string | null }[];
+    return rows.filter((r) => !project || this.inScope(r.project, project) || r.scope === "shared").map((r): GoalView => {
       const mine = ops.filter((o) => o.target === r.id);
       const states = mine.filter((o) => o.op === "goal_state" && (GOAL_STATES as readonly string[]).includes(o.by ?? ""));
       const links = mine.filter((o) => o.op === "goal_link" && o.by).map((o) => ({ task: o.by!, at: o.at, machine: o.machine }));
@@ -913,7 +1177,7 @@ export class MemoryStore {
       const active = [...latest].filter(([, until]) => Date.parse(until) > now).sort((a, b) => first.get(a[0])!.localeCompare(first.get(b[0])!) || a[0].localeCompare(b[0]));
       const last = fresh.at(-1);
       // One line whatever another machine wrote: titles are rendered into agents' context.
-      return { id: r.id, at: r.at, machine: r.machine, project: r.project, scope: r.scope as Scope, title: oneLine(r.title), milestones: (JSON.parse(r.milestones) as string[]).map(oneLine), dependsOn: JSON.parse(r.depends),
+      return { id: r.id, at: r.at, machine: r.machine, project: this.label(r.project), scope: r.scope as Scope, title: oneLine(r.title), milestones: (JSON.parse(r.milestones) as string[]).map(oneLine), dependsOn: JSON.parse(r.depends),
         state: (states.at(-1)?.by as GoalState | undefined) ?? "open", links,
         lease: active.length ? { holder: active[0]![0], until: active[0]![1], conflict: active.slice(1).map(([m]) => m), expired: false }
           : { holder: null, until: last?.by ?? null, conflict: [], expired: !!last, lastHolder: last?.machine ?? null } };
@@ -943,7 +1207,7 @@ export class MemoryStore {
   suggestions(project?: string): Suggestion[] {
     this.ensureFresh();
     const visible = project ? new Set(this.list({ project, limit: Number.MAX_SAFE_INTEGER, includeSuperseded: true }).map((v) => v.id)) : undefined;
-    const ops = this.db.query("SELECT id, op, at, target, by FROM ops WHERE op IN ('suggest', 'confirm', 'reject') ORDER BY at, id").all() as { id: string; op: string; at: string; target: string; by: string | null }[];
+    const ops = this.readRows("SELECT id, op, at, target, by FROM ops WHERE op IN ('suggest', 'confirm', 'reject') ORDER BY at, id") as { id: string; op: string; at: string; target: string; by: string | null }[];
     const verdict = new Map<string, "confirmed" | "rejected">();
     for (const o of ops) if (o.op !== "suggest") verdict.set(o.target, o.op === "confirm" ? "confirmed" : "rejected");
     return ops.filter((o) => o.op === "suggest" && o.by).flatMap((o) => {
@@ -980,6 +1244,51 @@ export function buildGenerationIndex(profile: BoundProfile, sources: readonly Le
   finally { store.close(); }
 }
 
+function initializeShard(home: string, opts: { project?: string; user?: boolean }): void {
+  const selection = readShardedSelection(home), generation = selection.generation;
+  const dir = opts.user === true ? userShardDir(home) : shardDir(home, opts.project!), machine = machineId(home);
+  if (opts.project !== undefined) ensureShardDescriptor(home, opts.project);
+  for (const folder of ["log", "local", "legacy/log", "legacy/local", "legacy-main/log", "legacy-main/local"]) mkdirSync(join(dir, folder), { recursive: true, mode: 0o700 });
+  for (const [path, value] of [["generation.json", generationDescriptor(generation)], ["machine.json", machine], ["legacy/machine.json", machine], ["legacy-main/machine.json", machine]] as const) {
+    const file = join(dir, path), prior = readProfileJSON(file);
+    if (prior === undefined) writeProfileJSON(file, value);
+    else if (canonicalJSON(prior) !== canonicalJSON(value)) throw new Error("curated shard metadata changed during initialization");
+  }
+  const legacyHome = join(dir, "legacy"), sources = readMigrationSources(legacyHome);
+  writeProfileJSON(join(dir, "migration-sources.json"), { schema: "agent-mem.migration-sources/v1", sources });
+  const profile: BoundProfile = { kind: "generation", home, dir, generation, selectorRevision: selection.selectorRevision,
+    legacyHome, legacyMainHome: join(dir, "legacy-main"), sharded: true, ...(opts.user === true ? { shardUser: true } : { shardKey: opts.project! }) };
+  buildGenerationIndex(profile, sources);
+  writeProfileJSON(join(dir, "generation-seal.json"), { schema: "agent-mem.generation-seal/v1", generation,
+    descriptorHash: hashJSON(generationDescriptor(generation)), sourceDigest: hashJSON({ sources, legacyCommit: undefined }) });
+}
+
+/** Open one sealed project or user shard directly; no legacy-home scan, catalog walk or old-layout reader lease. */
+export function openShardStore(opts: StoreOptions & { project?: string; user?: boolean; memoryDir?: string }): MemoryStore {
+  if (opts.user === true && opts.project !== undefined || opts.user !== true && !opts.project) throw new Error("choose exactly one project or the user shard");
+  if (opts.memoryDir !== undefined && (opts.home !== undefined || typeof opts.memoryDir !== "string" || !opts.memoryDir.trim())) throw new Error("choose a memory home or one explicit memory directory");
+  const home = opts.memoryDir ?? (opts.home === undefined ? memoryHome() : join(opts.home, "memory"));
+  assertCuratedShardPaths(home, opts);
+  const dir = opts.user === true ? userShardDir(home) : shardDir(home, opts.project!);
+  const missing = !existsSync(join(dir, "generation.json"));
+  if (missing) initializeShard(home, opts);
+  const profile = resolveShardProfile(home, opts);
+  const { reconcile, ...plain } = opts;
+  const userOverlay = opts.user === true ? undefined : openShardStore({ ...plain, project: undefined, user: true });
+  const aliasStores: MemoryStore[] = [];
+  try {
+    // #27: an aliased key that has a shard of its own is read beside this one; one that never had a shard has nothing to read and is not created.
+    if (opts.user !== true && reconcile && reconcile.canonical === opts.project) {
+      for (const alias of reconcile.aliases) {
+        if (alias === opts.project || !existsSync(join(shardDir(home, alias), "generation.json"))) continue;
+        assertCuratedShardPaths(home, { project: alias });
+        aliasStores.push(new MemoryStore(plain, { token: MIGRATION_BOOTSTRAP, profile: resolveShardProfile(home, { project: alias }), authoring: true }));
+      }
+    }
+    return new MemoryStore(opts, { token: MIGRATION_BOOTSTRAP, profile, authoring: true, userOverlay, aliasStores });
+  } catch (error) { for (const store of aliasStores) store.close(); userOverlay?.close(); throw error; }
+}
+
 /** Person-only migration receipt; this inspector reads raw rows without opening a store or writing any index. */
 export function summarizeRawExpiry(rawLines: string[], now: number, tailBytes: number): import("./migrate.ts").MigrationCounts {
   const bytes = Buffer.from(rawLines.filter(Boolean).join("\n") + (rawLines.length ? "\n" : ""));