@staix/agent-mem 0.4.0 → 0.5.0

package/src/memory/catalog.ts

@@ -2,7 +2,7 @@ import { Database } from "bun:sqlite";
 import { chmodSync, existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { memoryBase } from "./home.ts";
-import { listAliases, readShardDescriptor, SHARDED_SCHEMA } from "./shard.ts";
+import { effectiveAliases, readShardDescriptor, SHARDED_SCHEMA } from "./shard.ts";
 import { readProfileJSON, validGeneration } from "./generation.ts";
 import { captureShardStats, readCaptureConfig } from "./capture.ts";
 import { openShardStore } from "./store.ts";
@@ -73,9 +73,8 @@ export function walkShards(base: string): { hash: string; key: string; local: bo
 /** What the shards and the alias log say, before anything is persisted. */
 export function scanCatalog(base: string): CatalogProject[] {
   const captured = capturedSelection(base);
-  // The latest op per alias: an alias lists only under the key it currently points at, never under a past target.
-  const latest = new Map<string, string>();
-  for (const op of listAliases(base)) latest.set(op.alias, op.key);
+  // The latest op per alias (a removal included): an alias lists only under the key it currently points at, never under a past target or after `alias remove`.
+  const latest = effectiveAliases(base);
   const out: CatalogProject[] = [];
   for (const shard of walkShards(base)) {
     let rows = 0, bytes = 0, lastAt: string | null = null;

package/src/memory/import.ts

@@ -5,7 +5,7 @@ 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 { aliasedKeys, 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. */
@@ -27,8 +27,7 @@ export async function importClaudeMemWorkState(opts: { base: string; project: st
   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 aliases = aliasedKeys(opts.base, project);
   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 });

package/src/memory/search-fts.ts

@@ -165,15 +165,25 @@ export class SearchIndex {
    * Best BM25 first (rank is negative: smaller wins). `project` filters inside the MATCH (its own rows plus shared
    * ones), so a busy sibling project can never starve a project's LIMIT. Visibility stays with the caller.
    */
-  query(q: string, limit: number, project?: string, offset = 0): RankedRef[] {
+  query(q: string, limit: number, project?: string | readonly string[], offset = 0): RankedRef[] {
     if (!this.db) return [];
     const match = ftsTerms(q);
     if (!match) return [];
-    const where = project ? "docs MATCH ? AND (project = ? OR scope = 'shared')" : "docs MATCH ?";
-    const bind = project ? [match, project] : [match];
+    const where = project ? "docs MATCH ? AND (project IN (SELECT value FROM json_each(?)) OR scope = 'shared')" : "docs MATCH ?";
+    const bind = project ? [match, JSON.stringify(typeof project === "string" ? [project] : project)] : [match];
     return this.db.query(`SELECT ref, project, tier, at, bm25(docs) AS rank FROM docs WHERE ${where} ORDER BY rank, ref LIMIT ? OFFSET ?`).all(...bind, limit, offset) as RankedRef[];
   }
 
+  /** Matching identities in chronological keyset pages; raw-corpus BM25 never selects a private-policy window. */
+  candidates(q: string, window: ReadWindow): ReadRef[] {
+    if (!this.db) return [];
+    const match = ftsTerms(q); if (!match) return [];
+    const { columns, where, bind } = readWindowSql(window, "ref");
+    where.push("docs MATCH ?"); bind.push(match);
+    return (this.db.query(`SELECT ${columns} FROM docs 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);
+  }
+
   close(): void { this.db?.close(); }
 }
 
@@ -201,3 +211,34 @@ export function captureSearch(dir: string, q: string, limit: number, notBefore?:
   } catch { return []; }
   finally { db?.close(); }
 }
+
+/** Internal keyset pages: bounds apply to row bodies, never to the total corpus. */
+export interface ReadWindow {
+  project: string;
+  /** #27: every key the page covers; `project` alone when absent. */
+  projects?: readonly string[];
+  limit: number;
+  since?: string;
+  anchor?: string;
+  prefix?: string;
+  id?: string;
+  after?: { position: number; id: string };
+}
+export interface ReadRef { id: string; at: string; position: number }
+/** Fixed column names supplied by the three derived stores; all caller values remain SQL parameters. */
+export function readWindowSql(window: ReadWindow, id: "id" | "ref") {
+  if (!Number.isSafeInteger(window.limit) || window.limit < 1 || window.limit > 256) throw new Error("invalid read page limit");
+  const bind: (string | number)[] = [];
+  const position = window.anchor ? (bind.push(window.anchor), "abs(julianday(at) - julianday(?))") : "-julianday(at)";
+  const columns = `CAST(${id} AS TEXT) AS candidate_id, at, ${position} AS candidate_position`;
+  const where = ["project IN (SELECT value FROM json_each(?))"]; bind.push(JSON.stringify(window.projects ?? [window.project]));
+  if (window.since) { where.push("julianday(at) >= julianday(?)"); bind.push(window.since); }
+  if (window.id !== undefined) { where.push(`${id} = ?`); bind.push(window.id); }
+  if (window.prefix !== undefined) { where.push(`substr(${id}, 1, length(?)) = ?`); bind.push(window.prefix, window.prefix); }
+  if (window.after) {
+    where.push("(candidate_position > ? OR (candidate_position = ? AND candidate_id > ?))");
+    bind.push(window.after.position, window.after.position, window.after.id);
+  }
+  return { columns, where, bind };
+}
+export const readRef = (row: { candidate_id: string; at: string; candidate_position: number }): ReadRef => ({ id: row.candidate_id, at: row.at, position: row.candidate_position });

package/src/memory/shard.ts

@@ -74,6 +74,13 @@ export function readShardDescriptor(base: string, hash: string): ShardDescriptor
 }
 
 export interface AliasOp { schema: typeof SHARD_SCHEMA; op: "alias"; at: string; machine: string; alias: string; key: string; actor: string }
+/**
+ * #27 option 2: the person's removal of one alias. An append-only op in the same local `aliases.jsonl` (never a shared-v1 segment, so no shared-v1 reader sees a new op
+ * kind there: an older reader skips the line and keeps resolving the alias, which is the C1 "local only" placement). The latest op for an alias wins, so after an
+ * `unalias` the key resolves to itself again, and a later `alias` op maps it again.
+ */
+export interface UnaliasOp { schema: typeof SHARD_SCHEMA; op: "unalias"; at: string; machine: string; alias: string; actor: string }
+export type AliasLogOp = AliasOp | UnaliasOp;
 
 export function aliasLogPath(base: string): string {
   return join(base, "aliases.jsonl");
@@ -88,8 +95,8 @@ export function appendAlias(base: string, input: { alias: string; key: string; a
   if (!alias || !key) throw new Error("an alias needs both keys");
   if (alias === key) throw new Error("an alias cannot target itself");
   if (resolveAlias(base, key) !== key) throw new Error("an alias cannot target another alias");
-  // The other direction too, using only the latest op per alias: a target abandoned by a later retarget is free again.
-  const currentTargets = new Set([...new Map(listAliases(base).map((op) => [op.alias, op.key])).values()]);
+  // The other direction too, using only the latest op per alias: a target abandoned by a later retarget or a removal is free again.
+  const currentTargets = new Set(effectiveAliases(base).values());
   if (currentTargets.has(alias)) throw new Error("an alias target cannot become an alias");
   const op: AliasOp = { schema: SHARD_SCHEMA, op: "alias", at: input.at ?? new Date().toISOString(), machine: input.machine, alias, key, actor: input.actor };
   mkdirSync(base, { recursive: true, mode: 0o700 });
@@ -97,24 +104,51 @@ export function appendAlias(base: string, input: { alias: string; key: string; a
   return op;
 }
 
-/** Every alias op in order; a malformed line is skipped, never fatal. */
-export function listAliases(base: string): AliasOp[] {
+/** Every alias and unalias op in order (the full history); a malformed or unknown line is skipped, never fatal. */
+export function listAliases(base: string): AliasLogOp[] {
   let text = "";
   try { text = readFileSync(aliasLogPath(base), "utf8"); } catch { return []; }
-  const ops: AliasOp[] = [];
+  const ops: AliasLogOp[] = [];
   for (const line of text.split("\n").filter(Boolean)) {
     try {
-      const op = JSON.parse(line) as AliasOp;
-      if (op?.schema === SHARD_SCHEMA && op.op === "alias" && typeof op.alias === "string" && typeof op.key === "string") ops.push(op);
+      const op = JSON.parse(line) as AliasLogOp;
+      if (op?.schema !== SHARD_SCHEMA || typeof op.alias !== "string") continue;
+      if (op.op === "alias" && typeof op.key === "string") ops.push(op);
+      else if (op.op === "unalias") ops.push(op);
     } catch { /* a malformed line is skipped */ }
   }
   return ops;
 }
 
-/** The canonical key for a possibly aliased one: the latest op for it, one hop (aliases never chain). */
+/** The aliases in force: for each alias key the latest op decides, and an `unalias` removes it. Map of alias key to canonical key. */
+export function effectiveAliases(base: string): Map<string, string> {
+  const latest = new Map<string, string>();
+  for (const op of listAliases(base)) { if (op.op === "alias") latest.set(op.alias, op.key); else latest.delete(op.alias); }
+  return latest;
+}
+
+/** The canonical key for a possibly aliased one: the latest op for it, one hop (aliases never chain). An unaliased key is its own canonical key. */
 export function resolveAlias(base: string, key: string): string {
-  const ops = listAliases(base).filter((op) => op.alias === key);
-  return ops.length ? ops[ops.length - 1]!.key : key;
+  return effectiveAliases(base).get(key) ?? key;
+}
+
+/** Every key currently aliased to `canonical`, sorted (the keys whose curated rows the CLI and MCP project filter now covers, #27 option 1). */
+export function aliasedKeys(base: string, canonical: string): string[] {
+  return [...effectiveAliases(base)].filter(([, key]) => key === canonical).map(([alias]) => alias).sort();
+}
+
+/**
+ * One person-reviewed removal, appended to `aliases.jsonl`. Nothing is rewritten: the alias line stays in the history and the later op wins. Refused when the key is
+ * not aliased now, so a typo never records a removal that means nothing.
+ */
+export function appendUnalias(base: string, input: { alias: string; actor: string; machine: string; at?: string }): UnaliasOp {
+  const alias = input.alias.trim();
+  if (!alias) throw new Error("an alias removal needs the alias key");
+  if (!effectiveAliases(base).has(alias)) throw new Error(`no alias to remove: ${alias} is not aliased now`);
+  const op: UnaliasOp = { schema: SHARD_SCHEMA, op: "unalias", at: input.at ?? new Date().toISOString(), machine: input.machine, alias, actor: input.actor };
+  mkdirSync(base, { recursive: true, mode: 0o700 });
+  appendFileSync(aliasLogPath(base), JSON.stringify(op) + "\n", { mode: 0o600 });
+  return op;
 }
 
 /** `memoryBase(home)` plus the shard of `key` after alias resolution. */

package/src/memory/store.ts

@@ -6,7 +6,7 @@ import { isDenied } from "./platform.ts";
 import { looksSecret } from "./screen.ts";
 import { mutationDatabase } from "./mutation.ts";
 import { memoryHome } from "./home.ts";
-import { SearchIndex, captureSearch } from "./search-fts.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";
@@ -194,10 +194,12 @@ export type PromotionScreen = (v: View) => "promote" | "keep" | "skip";
  * went) wait for a process that has one; a person's explicit promote goes through.
  */
 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; authoring?: boolean; userOverlay?: MemoryStore }
+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;
@@ -215,6 +217,9 @@ export class MemoryStore {
   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;
 
@@ -222,6 +227,8 @@ export class MemoryStore {
     if (bootstrap && bootstrap.token !== MIGRATION_BOOTSTRAP) throw new Error("invalid migration bootstrap");
     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");
@@ -290,9 +297,9 @@ export class MemoryStore {
     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=? LIMIT ?").all(project, scanLimit + 1) as { id: string }[];
+    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).map(entry => [entry.view.id, entry.rowHash]));
+    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 => {
@@ -305,20 +312,24 @@ export class MemoryStore {
   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.generationIndex?.vaultLinks(project) ?? []), ...(this.userOverlay?.vaultLinks(project) ?? [])];
+    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, path } as const;
+        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);
@@ -345,7 +356,7 @@ export class MemoryStore {
     const release = this.releaseReaderLease;
     this.releaseReaderLease = undefined;
     try { this.db.close(); this.mutationDb.close(); this.searchIndex.close(); }
-    finally { try { this.userOverlay?.close(); } finally { release?.(); } }
+    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. */
@@ -400,10 +411,8 @@ 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) {
-      if ((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" && this.userOverlay.ownsTarget(body.target as string)) return this.userOverlay.appendBody(body, local);
-    }
+    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");
     }
@@ -522,7 +531,8 @@ export class MemoryStore {
    */
   promote(id: string, actor: string, project?: string, auto = false): string | undefined {
     const v = this.get(id, project);
-    if (v && this.userOverlay?.ownsTarget(v.id)) return this.userOverlay.promote(v.id, actor, project, auto);
+    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;
@@ -533,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.
@@ -548,9 +558,11 @@ export class MemoryStore {
     try {
       const entry = { op: "settle", target: task, actor, by: this.until() } as const;
       const at = new Date(this.now()).toISOString();
-      this.append(entry, true, at);
+      // #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);
+      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 {
@@ -705,7 +717,23 @@ export class MemoryStore {
   }
 
   /** Only the bound project and user overlay participate; never scan another project's private shard. */
-  private readStores(): MemoryStore[] { return this.userOverlay ? [this, this.userOverlay] : [this]; }
+  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>[]);
@@ -724,13 +752,14 @@ export class MemoryStore {
    * 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.
     const read = () => this.viewRows(expired, selection, expiredOnly);
-    return this.db.transaction(() => this.userOverlay ? this.userOverlay.db.transaction(read).deferred() : read()).deferred();
+    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.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));
@@ -825,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); }
@@ -845,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;
@@ -873,6 +908,7 @@ export class MemoryStore {
   /** 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 */ }
@@ -884,7 +920,7 @@ export class MemoryStore {
    */
   private live(selection?: Filter): View[] {
     this.ensureFresh();
-    this.prune(); this.userOverlay?.promoteHeld(); 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;
@@ -892,12 +928,32 @@ 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
@@ -908,7 +964,7 @@ export class MemoryStore {
   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 || v.project === f.project || v.scope === "shared")
+    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();
@@ -926,7 +982,7 @@ export class MemoryStore {
       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, offset);
+        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;
@@ -964,14 +1020,18 @@ export class MemoryStore {
     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;
-    this.searchIndex.resync(() => (this.db.query("SELECT id, at, project, tier, scope, title, text, about FROM entries").all() as { id: string; at: string; project: string; tier: string; scope: string; title: string | null; text: string; about: string }[])
-      .map((r) => ({ 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(" ")}` })));
+    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);
@@ -1099,7 +1159,7 @@ export class MemoryStore {
     const now = this.now();
     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 || r.project === project || r.scope === "shared").map((r): GoalView => {
+    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 }));
@@ -1117,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 } };
@@ -1213,9 +1273,20 @@ export function openShardStore(opts: StoreOptions & { project?: string; user?: b
   const missing = !existsSync(join(dir, "generation.json"));
   if (missing) initializeShard(home, opts);
   const profile = resolveShardProfile(home, opts);
-  const userOverlay = opts.user === true ? undefined : openShardStore({ ...opts, project: undefined, user: true });
-  try { return new MemoryStore(opts, { token: MIGRATION_BOOTSTRAP, profile, authoring: true, userOverlay }); }
-  catch (error) { userOverlay?.close(); throw error; }
+  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. */