@staix/agent-mem 0.4.0 → 0.6.0

package/src/memory/platform.ts

@@ -1,7 +1,12 @@
 // Single-source platform helpers. Hub, local and Pi modules re-export these functions unchanged.
 import { realpathSync } from "node:fs";
 import { basename, dirname, join, resolve, sep } from "node:path";
-import { spawnSync, execFileSync, type SpawnSyncOptionsWithStringEncoding, type SpawnSyncReturns } from "node:child_process";
+import type { SpawnSyncOptionsWithStringEncoding, SpawnSyncReturns } from "node:child_process";
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+let processes: typeof import("node:child_process") | undefined;
+// Path/policy-only hook parents never need a process module. Node-safe synchronous users load it on demand.
+const childProcess = () => processes ??= require("node:child_process") as typeof import("node:child_process");
 import { createHash } from "node:crypto";
 
 const canonical = (path: string): string => {
@@ -33,7 +38,7 @@ export function realPath(path: string): string {
     // The path as given: resolve() would fold a `..` after a symlink by text. GNU realpath accepts a dangling last
     // component unless told -e; the BSD one on macOS refuses it by default.
     const argv = process.platform === "darwin" ? ["/bin/realpath", "--", path] : ["realpath", "-e", "--", path];
-    const r = spawnSync(argv[0]!, argv.slice(1), { encoding: "utf8" });
+    const r = childProcess().spawnSync(argv[0]!, argv.slice(1), { encoding: "utf8" });
     if (r.status !== 0 || !r.stdout.endsWith("\n")) throw error;
     return r.stdout.slice(0, -1);
   }
@@ -94,7 +99,7 @@ export function memoryGitEnv(env: NodeJS.ProcessEnv = process.env, options: { re
 /** spawnSync form of the same call: the env option is merged with memoryGitEnv, everything else passes through. */
 export function memoryGitSync(args: string[], options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns<string> {
   const argv = memoryGitArgv(args);
-  return spawnSync(argv[0]!, argv.slice(1), { ...options, env: memoryGitEnv(options.env ?? process.env) });
+  return childProcess().spawnSync(argv[0]!, argv.slice(1), { ...options, env: memoryGitEnv(options.env ?? process.env) });
 }
 
 /**
@@ -109,7 +114,7 @@ export function memoryGitSync(args: string[], options: SpawnSyncOptionsWithStrin
  */
 export function processSignature(pid: number): string | undefined {
   try {
-    const text = execFileSync("ps", ["-p", String(pid), "-o", "lstart=,comm="], { encoding: "utf8", env: { ...process.env, LC_ALL: "C", TZ: "UTC" } }).trim();
+    const text = childProcess().execFileSync("ps", ["-p", String(pid), "-o", "lstart=,comm="], { encoding: "utf8", env: { ...process.env, LC_ALL: "C", TZ: "UTC" } }).trim();
     return text ? createHash("sha256").update(text).digest("hex") : undefined;
   } catch { return undefined; }
 }

package/src/memory/project.ts

@@ -1,14 +1,66 @@
 import { createHash } from "node:crypto";
-import { basename, dirname, resolve } from "node:path";
-import { readFileSync } from "node:fs";
-import { memoryGitSync, realPath } from "./platform.ts";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
+import { lstatSync, readFileSync } from "node:fs";
+import { memoryGitEnv, memoryGitSync, realPath } from "./platform.ts";
 
-/** Project names from the outermost superproject down to this repo. */
-export function projectChain(cwd: string): string[] {
-  const git = (dir: string, arg: string) => memoryGitSync(["-C", dir, "rev-parse", arg], { encoding: "utf8" }).stdout?.trim() ?? "";
+/** Host-owned read-only Git transport. Arguments are the existing Git operation, before platform argv hardening. */
+export type ProjectGitRead = (args: string[], env: NodeJS.ProcessEnv) => {
+  stdout: string; status: number | null; error?: unknown; signal?: string | null;
+};
+
+interface ProjectIdentityOptions {
+  repositoryIsolation?: boolean;
+  /** Host-only: native intake must not rebind a failed Git identity to a local fallback. */
+  strictGitErrors?: boolean;
+  /** Host-only transport seam; callers retain the same strict status and shape checks. */
+  gitRead?: ProjectGitRead;
+}
+class GitIdentityUnavailable extends Error { constructor() { super("Git project identity unavailable"); } }
+const unavailable = (): never => { throw new GitIdentityUnavailable(); };
+function canonicalCwd(cwd: string, strict: boolean | undefined): string {
+  if (!strict) return cwd;
+  try { const canonical = realPath(cwd); if (!lstatSync(canonical).isDirectory()) unavailable(); return canonical; }
+  catch { return unavailable(); }
+}
+/** Filesystem evidence only; unknown ancestry never certifies an ordinary non-Git directory. */
+function physicalGit(cwd: string): boolean {
+  const present = (file: string) => {
+    try { return !!lstatSync(file, { throwIfNoEntry: false }); }
+    catch { return unavailable(); }
+  };
+  for (let dir = cwd, depth = 0; depth < 32; dir = dirname(dir), depth++) {
+    if (present(resolve(dir, ".git")) || present(resolve(dir, "HEAD")) && present(resolve(dir, "objects"))) return true;
+    if (dir === dirname(dir)) return false;
+  }
+  return unavailable();
+}
+function checkedGit(args: string[], env: NodeJS.ProcessEnv, strict: boolean, gitRead?: ProjectGitRead, statuses = [0]) {
+  const result = gitRead ? gitRead(args, env) : memoryGitSync(args, { encoding: "utf8", env });
+  if (strict && (result.error || result.signal || !statuses.includes(result.status ?? -1) || typeof result.stdout !== "string"
+    || result.stdout.length > 64 * 1024 || result.stdout.includes("\0"))) unavailable();
+  return result;
+}
+function pathText(text: string, strict: boolean, empty = false): string {
+  if (strict && (text ? !isAbsolute(text) || /[\r\n]/.test(text) : !empty)) unavailable();
+  return text;
+}
+
+/** Project names from the outermost superproject down to this repo; isolation binds native hook cwd over inherited Git routing. */
+export function projectChain(cwd: string, options: ProjectIdentityOptions = {}): string[] {
+  cwd = canonicalCwd(cwd, options.strictGitErrors);
+  const strict = options.strictGitErrors === true && physicalGit(cwd);
+  const env = memoryGitEnv(process.env, options);
+  const git = (dir: string, arg: string) => pathText(checkedGit(["-C", dir, "rev-parse", arg], env, strict, options.gitRead).stdout?.trim() ?? "", strict, arg === "--show-superproject-working-tree");
   const top = git(cwd, "--show-toplevel");
   if (!top) return [basename(cwd)];
+  return projectChainAtRoot(top, options);
+}
 
+/** Internal callers that have already resolved the working root do not repeat its git lookup. */
+function projectChainAtRoot(top: string, options: ProjectIdentityOptions): string[] {
+  const strict = options.strictGitErrors === true;
+  const env = memoryGitEnv(process.env, options);
+  const git = (dir: string, arg: string) => pathText(checkedGit(["-C", dir, "rev-parse", arg], env, strict, options.gitRead).stdout?.trim() ?? "", strict, true);
   // claude-mem's native identity for a worktree is [parent, parent/worktree].
   // The worktree's .git file points into <parent>/.git/worktrees/<name>; the
   // ordinary superproject walk below remains unchanged for repos and submodules.
@@ -19,12 +71,13 @@ export function projectChain(cwd: string): string[] {
       const gitDir = resolve(top, match[1]!);
       if (/[/\\]\.git[/\\]worktrees[/\\][^/\\]+$/.test(gitDir)) {
         const parentRoot = dirname(dirname(dirname(gitDir)));
-        const parent = projectChain(parentRoot);
+        const parent = projectChain(parentRoot, options);
         const parentName = basename(parentRoot);
         return [...parent, `${parentName}/${basename(top)}`];
       }
     }
-  } catch {
+  } catch (error) {
+    if (error instanceof GitIdentityUnavailable) throw error;
     // A missing or unreadable .git file falls through to git's normal chain.
   }
 
@@ -32,7 +85,7 @@ export function projectChain(cwd: string): string[] {
   for (let dir = top; dir && chain.length < 8; dir = git(dir, "--show-superproject-working-tree")) {
     chain.unshift(basename(dir));
   }
-  return chain.length ? chain : [basename(cwd)];
+  return chain.length ? chain : [basename(top)];
 }
 
 /**
@@ -41,8 +94,13 @@ export function projectChain(cwd: string): string[] {
  * the main working root keeps two unrelated repositories that share a name apart while the main checkout, a
  * subdirectory and a worktree resolve to one key (that key is this machine's only, and root-invoked keys stay stable).
  */
-export function memoryProjectKey(cwd: string): string {
-  const url = memoryGitSync(["-C", cwd, "remote", "get-url", "origin"], { encoding: "utf8" }).stdout?.trim() ?? "";
+export function memoryProjectKey(cwd: string, options: ProjectIdentityOptions = {}): string {
+  cwd = canonicalCwd(cwd, options.strictGitErrors);
+  const strict = options.strictGitErrors === true && physicalGit(cwd);
+  const env = memoryGitEnv(process.env, options);
+  const origin = checkedGit(["-C", cwd, "remote", "get-url", "origin"], env, strict, options.gitRead, [0, 2]);
+  const url = origin.stdout?.trim() ?? "";
+  if (strict && (origin.status === 0 ? !url || /[\r\n]/.test(url) : !!url)) unavailable();
   // A URL's default port is not part of the repository (`ssh://git@github.com:22/o/r` is `github.com/o/r`); any other
   // port is, since another service may run there. An scp-style `host:path` has no port.
   const u = /^([a-z+]+):\/\/(?:[^@/]+@)?(\[[^\]/]+\]|[^/:]+)(?::(\d*))?\/(.+?)(?:\.git)?\/?$/i.exec(url); // an IPv6 host is bracketed
@@ -60,26 +118,77 @@ export function memoryProjectKey(cwd: string): string {
   // No usable remote: hash the main working root, not the cwd or git dir. Root-invoked keys therefore keep their
   // pre-#15 value while the main checkout, a subdirectory and a worktree resolve to ONE key (#15 D2/AC2). A bare
   // repository has no working root: its own directory is the stable identity for it and its worktrees.
-  const common = memoryGitSync(["-C", cwd, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8" }).stdout?.trim() ?? "";
+  // The bounded native hook port reads all ordinary-repository metadata in its second Git call. Git itself
+  // resolves core.worktree for --show-toplevel; no config interpretation or root guess replaces that result.
+  let location: string[];
+  if (strict && options.gitRead) {
+    const metadata = checkedGit(["-C", cwd, "rev-parse", "--path-format=absolute", "--git-common-dir", "--git-dir", "--is-bare-repository", "--show-toplevel", "--show-superproject-working-tree"], env, true, options.gitRead, [0, 128]);
+    const fields = metadata.stdout.trim().split("\n");
+    if (fields.length < 3 || !isAbsolute(fields[0]!) || !isAbsolute(fields[1]!) || !/^(true|false)$/.test(fields[2]!)) unavailable();
+    location = fields.slice(0, 3);
+    if (metadata.status === 128) {
+      // A bare repository emits exactly the three proven metadata rows before show-toplevel refuses.
+      // Any other failed/partial shape stays unknown; stderr never participates in an identity decision.
+      if (fields.length !== 3 || fields[2] !== "true") unavailable();
+      if (fields[0] === fields[1]) {
+        const root = canonicalCwd(fields[0]!, true);
+        return `${basename(root)}@${createHash("sha256").update(root).digest("hex").slice(0, 8)}`;
+      }
+    } else {
+      if ((fields.length !== 4 && fields.length !== 5) || fields[2] !== "false") unavailable();
+      pathText(fields[3]!, true);
+      if (fields.length === 5) pathText(fields[4]!, true);
+      if (fields[0] === fields[1]) {
+        const root = canonicalCwd(fields[3]!, true), realCommon = canonicalCwd(fields[0]!, true);
+        // A separate/symlinked directory literally named .git can carry a historical parent-root key.
+        // Only the established config/root path below can distinguish an explicit core.worktree there.
+        if (basename(realCommon) !== ".git" || dirname(realCommon) === root) {
+          const chain = [basename(root)];
+          // Match the existing outermost-superproject walk, without reinterpreting a parent's worktree label.
+          for (let parent = fields[4] ?? ""; parent && chain.length < 8;) {
+            chain.unshift(basename(parent));
+            parent = pathText(checkedGit(["-C", parent, "rev-parse", "--show-superproject-working-tree"], env, true, options.gitRead).stdout.trim(), true, true);
+          }
+          return `${chain.join("/")}@${createHash("sha256").update(root).digest("hex").slice(0, 8)}`;
+        }
+      }
+    }
+    // Linked worktrees and ambiguous .git directory roots retain the established resolution below.
+  } else {
+    location = checkedGit(["-C", cwd, "rev-parse", "--path-format=absolute", "--git-common-dir", "--git-dir", "--is-bare-repository"], env, strict, options.gitRead).stdout?.trim().split("\n") ?? [];
+  }
+  if (strict && (location.length !== 3 || !isAbsolute(location[0]!) || !isAbsolute(location[1]!) || !/^(true|false)$/.test(location[2]!))) unavailable();
+  const ordinary = location.length === 3 && location[0] === location[1] && /^(true|false)$/.test(location[2]!);
+  const common = location.length === 3 ? location[0]! : checkedGit(["-C", cwd, "rev-parse", "--path-format=absolute", "--git-common-dir"], env, strict, options.gitRead).stdout?.trim() ?? "";
   if (common) {
     let realCommon = common;
-    try { realCommon = realPath(common); } catch { /* as given */ }
-    const bare = (memoryGitSync(["--git-dir", realCommon, "rev-parse", "--is-bare-repository"], { encoding: "utf8" }).stdout?.trim() ?? "") === "true";
-    let root = realCommon;
+    try { realCommon = realPath(common); } catch { if (strict) unavailable(); /* as given */ }
+    const bareText = ordinary ? location[2]! : checkedGit(["--git-dir", realCommon, "rev-parse", "--is-bare-repository"], env, strict, options.gitRead).stdout?.trim() ?? "";
+    if (strict && !/^(true|false)$/.test(bareText)) unavailable();
+    const bare = bareText === "true";
+    let root = realCommon, knownWorkingRoot = false;
     if (!bare) {
-      const configured = memoryGitSync(["--git-dir", realCommon, "config", "--path", "core.worktree"], { encoding: "utf8" }).stdout?.trim() ?? "";
-      const top = memoryGitSync(["-C", cwd, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).stdout?.trim() ?? "";
+      const config = checkedGit(["--git-dir", realCommon, "config", "--path", "core.worktree"], env, strict, options.gitRead, [0, 1]);
+      const configured = config.stdout?.trim() ?? "";
+      if (strict && (config.status === 0 ? !configured || /[\r\n]/.test(configured) : !!configured)) unavailable();
+      // Only a separate git directory without core.worktree needs another root lookup.
+      // Ordinary repositories already bind their root through the canonical .git directory.
+      const top = !configured && basename(realCommon) !== ".git"
+        ? checkedGit(["-C", cwd, "rev-parse", "--show-toplevel"], env, strict, options.gitRead).stdout?.trim() ?? "" : "";
       // Only an actual `.git` directory makes its parent the working root. A separate git dir shares its parent
       // with unrelated repositories, so the real worktree root (or, as a last resort, the unique git dir) is safer.
+      if (strict && !configured && basename(realCommon) !== ".git") pathText(top, true);
       root = configured ? resolve(realCommon, configured) : basename(realCommon) === ".git" ? dirname(realCommon) : top || realCommon;
+      knownWorkingRoot = !configured && basename(realCommon) === ".git";
     }
     let realRoot = root;
-    try { realRoot = realPath(root); } catch { /* as given */ }
-    return `${projectChain(realRoot).join("/")}@${createHash("sha256").update(realRoot).digest("hex").slice(0, 8)}`;
+    try { realRoot = realPath(root); } catch { if (strict) unavailable(); /* as given */ }
+    const chain = strict && bare ? [basename(realRoot)] : knownWorkingRoot ? projectChainAtRoot(realRoot, options) : projectChain(realRoot, options);
+    return `${chain.join("/")}@${createHash("sha256").update(realRoot).digest("hex").slice(0, 8)}`;
   }
   let real = cwd;
   try { real = realPath(cwd); } catch { /* as given */ }
-  return `${projectChain(cwd).join("/")}@${createHash("sha256").update(real).digest("hex").slice(0, 8)}`;
+  return `${projectChain(cwd, options).join("/")}@${createHash("sha256").update(real).digest("hex").slice(0, 8)}`;
 }
 
 /**

package/src/memory/reader-lease.ts

@@ -8,14 +8,15 @@ const READER_LEASE_SCHEMA = "agent-mem.reader-lease/v1";
 const RENEW_MS = 25_000;
 interface Lease { schema: typeof READER_LEASE_SCHEMA; pid: number; signature: string; renewedAt: string }
 export interface ReaderLease { (): void; verify(): void }
-interface OpenLease { refs: number; timer: ReturnType<typeof setInterval> }
+interface OpenLease { refs: number; timer: ReturnType<typeof setInterval>; busyTimeoutMs: number }
 const open = new Map<string, OpenLease>();
+let activeIdentity: { pid: number; signature: string } | undefined;
 
 const fileFor = (memoryDir: string, pid: number, signature: string) => join(memoryDir, "readers", `${pid}-${signature}.json`);
 const record = (pid: number, signature: string): Lease => ({ schema: READER_LEASE_SCHEMA, pid, signature, renewedAt: new Date().toISOString() });
 
-function withFence<T>(memoryDir: string, work: () => T): T {
-  const db = readerAdmissionDatabase(memoryDir);
+function withFence<T>(memoryDir: string, work: () => T, busyTimeoutMs = 3000): T {
+  const db = readerAdmissionDatabase(memoryDir, busyTimeoutMs);
   try { return db.transaction(work).immediate(); } finally { db.close(); }
 }
 
@@ -52,10 +53,20 @@ function admitReader(memoryDir: string): void {
 }
 
 /** One lease per process, reference-counted across handles; an unref'd timer does not keep the process resident. */
-export function registerReaderLease(memoryDir: string): ReaderLease {
-  const pid = process.pid, signature = processSignature(pid);
+export function registerReaderLease(memoryDir: string, options: { busyTimeoutMs?: number; signature?: string } = {}): ReaderLease {
+  const requestedTimeout = options.busyTimeoutMs ?? 3000;
+  if (!Number.isSafeInteger(requestedTimeout) || requestedTimeout < 0 || requestedTimeout > 3000) throw new Error("invalid reader admission busy timeout");
+  if (options.signature !== undefined && (typeof options.signature !== "string" || !/^[a-f0-9]{64}$/.test(options.signature))) throw new Error("invalid reader lease identity");
+  const pid = process.pid;
+  // A live reference already established this process lifetime; nested readers keep the same identity.
+  // Ownership and admission are still checked under the fence for every registration.
+  const inherited = open.size > 0 && activeIdentity?.pid === pid ? activeIdentity.signature : undefined;
+  if (inherited && options.signature !== undefined && options.signature !== inherited) throw new Error("reader lease identity changed");
+  // Host-only: the supplied hash must already describe this process's pinned native ps identity.
+  const signature = inherited ?? options.signature ?? processSignature(pid);
   if (!signature) throw new Error("cannot establish reader lease identity");
   const file = fileFor(memoryDir, process.pid, signature);
+  const busyTimeoutMs = open.get(file)?.busyTimeoutMs ?? requestedTimeout;
   mkdirSync(memoryDir, { recursive: true, mode: 0o700 });
   withFence(memoryDir, () => {
     admitReader(memoryDir);
@@ -77,12 +88,13 @@ export function registerReaderLease(memoryDir: string): ReaderLease {
         withFence(memoryDir, () => {
           ownedLease(memoryDir, file, signature);
           writeProfileJSON(file, record(process.pid, signature));
-        });
+        }, busyTimeoutMs);
       } catch { /* keep unknown evidence; migration admission remains fail-closed */ }
     }, RENEW_MS);
     timer.unref();
-    open.set(file, { refs: 1, timer });
-  });
+    open.set(file, { refs: 1, timer, busyTimeoutMs });
+    activeIdentity = { pid, signature };
+  }, busyTimeoutMs);
   let released = false;
   const release = () => {
     if (released) return;
@@ -97,8 +109,8 @@ export function registerReaderLease(memoryDir: string): ReaderLease {
       withFence(memoryDir, () => {
         ownedLease(memoryDir, file, signature);
         rmSync(file);
-      });
-    } catch { /* another actor replaced it: never remove its lease */ }
+      }, held.busyTimeoutMs);
+    } catch { /* Contention or replacement keeps evidence; never remove another actor's lease. */ }
   };
   return Object.assign(release, {
     verify(): void {

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

@@ -1,7 +1,8 @@
 import { createHash, randomBytes } from "node:crypto";
-import { appendFileSync, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { canonicalJSON, generationDescriptor, hashJSON, readProfileJSON, readSelector, validGeneration, type BoundProfile, type GenerationSeal } from "./generation.ts";
+import { SHARD_SCHEMA, resolveAlias } from "./aliases.ts";
 
 /**
  * #15 T1: the per-project shard layout under the user home. One shard per project key at `projects/<key-hash>/`;
@@ -17,7 +18,7 @@ import { canonicalJSON, generationDescriptor, hashJSON, readProfileJSON, readSel
  * append-only ops in `aliases.jsonl`, resolved one hop, and never merged automatically on a name match.
  */
 
-export const SHARD_SCHEMA = "agent-hub.memory.shard/v1";
+export { SHARD_SCHEMA, aliasLogPath, appendAlias, appendUnalias, listAliases, effectiveAliases, resolveAlias, aliasedKeys, type AliasOp, type UnaliasOp, type AliasLogOp } from "./aliases.ts";
 
 /** The directory name of one project's shard: a hash, since keys are URLs and path-hash forms. */
 export function shardKeyHash(key: string): string {
@@ -73,50 +74,6 @@ export function readShardDescriptor(base: string, hash: string): ShardDescriptor
   return undefined;
 }
 
-export interface AliasOp { schema: typeof SHARD_SCHEMA; op: "alias"; at: string; machine: string; alias: string; key: string; actor: string }
-
-export function aliasLogPath(base: string): string {
-  return join(base, "aliases.jsonl");
-}
-
-/**
- * One person-reviewed alias op, appended to `aliases.jsonl`. An alias never chains (its target must not itself be
- * an alias), and a machine that races the append keeps both ops: the latest one wins at read time.
- */
-export function appendAlias(base: string, input: { alias: string; key: string; actor: string; machine: string; at?: string }): AliasOp {
-  const alias = input.alias.trim(), key = input.key.trim();
-  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()]);
-  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 });
-  appendFileSync(aliasLogPath(base), JSON.stringify(op) + "\n", { mode: 0o600 });
-  return op;
-}
-
-/** Every alias op in order; a malformed line is skipped, never fatal. */
-export function listAliases(base: string): AliasOp[] {
-  let text = "";
-  try { text = readFileSync(aliasLogPath(base), "utf8"); } catch { return []; }
-  const ops: AliasOp[] = [];
-  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);
-    } 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). */
-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;
-}
-
 /** `memoryBase(home)` plus the shard of `key` after alias resolution. */
 export function captureShardDir(base: string, key: string, machine: string): string {
   return shardMachineDir(base, resolveAlias(base, key), machine);