@staix/agent-mem 0.18.0 → 0.20.0

package/src/memory/capture.ts

@@ -1,3 +1,4 @@
+import { assertFormatFloor } from "./formats.ts";
 import { Database } from "bun:sqlite";
 import { createHash, randomBytes } from "node:crypto";
 import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, opendirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -49,6 +50,7 @@ export const CAPTURE_EVICT_MAX_BATCHES = 4;
 /** Wall-time bound for one invocation's eviction: with the batch bound, an append stays inside R2 after a cap shrink. */
 export const CAPTURE_EVICT_MAX_MS = 25;
 export const CAPTURE_DRAIN_MAX_LINES = 1000;
+const BRIEF_SUMMARY_CANDIDATES = 32;
 const SPOOL = "spool.jsonl";
 const DRAINING = "spool.jsonl.draining";
 const SPOOL_DIR = "spool";
@@ -210,6 +212,7 @@ export class CaptureStore {
     const maxReadRows = opts.maxReadRows ?? 128;
     if (this.readOnly && (!Number.isSafeInteger(maxReadRows) || maxReadRows < 1 || maxReadRows >= Number.MAX_SAFE_INTEGER)) throw new Error("invalid capture read row bound");
     this.base = opts.memoryDir ?? memoryBase(opts.home);
+    assertFormatFloor(this.base, "capture");
     const machine = opts.machine ?? (this.readOnly ? this.existingMachine() : machineId(this.base).id);
     if (this.readOnly && !/^[a-f0-9]{16}$/.test(machine)) throw new Error("capture machine identity unavailable");
     this.requestedKey = opts.project;
@@ -288,6 +291,7 @@ export class CaptureStore {
       db.run("CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)");
       // #173: additive nullable columns. Older readers use explicit or `SELECT *` column names and ignore extras.
       addAttributionColumns(db);
+      this.ensureBriefSummaryIndex(true);
       this.ensureFts();
     } catch (error) {
       if (!lockError(error)) { db.close(); throw error; }
@@ -383,6 +387,12 @@ export class CaptureStore {
   }
 
   private mcpReady = false;
+  private briefReady = false;
+  private prepareBriefSummaryIndex(): void {
+    if (this.readOnly || this.briefReady) return;
+    try { this.ensureBriefSummaryIndex(false); this.briefReady = true; }
+    catch { /* Optional summary coverage remains partial; query engines remain independent. */ }
+  }
   /** One-time MCP read cost only: hooks neither create this derived index nor scan history to fill it. */
   private ensureMcpFts(): boolean {
     if (this.readOnly) return !!this.db.query("SELECT 1 FROM sqlite_master WHERE name = 'mcp_fts' AND type = 'table'").get();
@@ -637,6 +647,41 @@ export class CaptureStore {
     return rows.map(toRow);
   }
 
+  /** Generic SQLite index maintenance also covers older writers sharing this file. */
+  private ensureBriefSummaryIndex(bounded: boolean): void {
+    if (this.db.query("SELECT 1 FROM sqlite_master WHERE name='rows_brief_summaries_v1' AND type='index'").get()) return;
+    const build = () => {
+      if (bounded) {
+        const count = (this.db.query("SELECT COUNT(*) AS n FROM (SELECT 1 FROM rows LIMIT 129)").get() as { n: number }).n;
+        if (count > 128) return;
+      }
+      this.db.run("CREATE INDEX IF NOT EXISTS rows_brief_summaries_v1 ON rows(project,at,id) WHERE event IN ('Recap','Compact') AND (subagent IS NULL OR subagent != 1)");
+    };
+    // Keep the small-store decision and build atomic against a concurrent older writer.
+    if (bounded) this.db.transaction(build).immediate(); else build();
+  }
+
+  /** Index reads return at most33 bodies. Legacy fallback reads at most128 recent rows. */
+  readBriefSummaries(limit = BRIEF_SUMMARY_CANDIDATES): { rows: CaptureRow[]; partial: boolean } {
+    this.checkReadBinding();
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > BRIEF_SUMMARY_CANDIDATES) throw new Error("invalid brief summary limit");
+    const indexed = !!this.db.query("SELECT 1 FROM sqlite_master WHERE name='rows_brief_summaries_v1' AND type='index'").get();
+    let rows: RawRow[], partial = false;
+    if (indexed) {
+      rows = this.db.query("SELECT * FROM rows INDEXED BY rows_brief_summaries_v1 WHERE project=? AND event IN ('Recap','Compact') AND (subagent IS NULL OR subagent != 1) ORDER BY at DESC,id DESC LIMIT ?")
+        .all(this.key, limit + 1) as RawRow[];
+    } else {
+      // ponytail: a large legacy store stays partial within128 rows until an off-hook
+      // query builds the partial index; never scan or build the history on a hook.
+      const hasSubagent = (this.db.query("PRAGMA table_info(rows)").all() as { name: string }[]).some(column => column.name === "subagent");
+      const subagent = hasSubagent ? " AND (subagent IS NULL OR subagent != 1)" : "";
+      rows = this.db.query(`SELECT * FROM (SELECT * FROM rows INDEXED BY rows_at ORDER BY at DESC,id DESC LIMIT 128) WHERE project=? AND event IN ('Recap','Compact')${subagent} ORDER BY at DESC,id DESC LIMIT ?`)
+        .all(this.key, limit + 1) as RawRow[];
+      partial = this.db.query("SELECT id FROM rows INDEXED BY rows_at ORDER BY at DESC,id DESC LIMIT 129").all().length > 128;
+    }
+    return { rows: rows.slice(0, limit).map(toRow), partial: partial || rows.length > limit };
+  }
+
   /** Exact-project, bounded body pages; MCP screens before filling its public candidate window. */
   readPage(window: ReadWindow & { query?: string; match?: "substring" }): { rows: CaptureRow[]; next?: ReadRef; engine?: "fts5" | "substring" } {
     this.checkReadBinding();
@@ -645,6 +690,7 @@ export class CaptureStore {
       if (window.query !== undefined) throw new Error("recent capture brief does not support query indexes");
       where.push("id IN (SELECT value FROM json_each(?))"); bind.push(JSON.stringify(this.recentReadIds));
     }
+    if (window.query !== undefined) this.prepareBriefSummaryIndex();
     const engine = window.query === undefined ? undefined : window.match !== "substring" && this.ensureMcpFts() ? "fts5" : "substring";
     const plan = captureReadPlan(window, engine, where, bind);
     if (!plan) return { rows: [], engine };

package/src/memory/catalog.ts

@@ -1,4 +1,5 @@
 import { Database } from "bun:sqlite";
+import { indexFileName } from "./index-file.ts";
 import { chmodSync, existsSync, lstatSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { memoryBase } from "./home.ts";
@@ -48,7 +49,7 @@ function curatedStats(base: string, hash: string, key: string, captured: boolean
   if (!existsSync(join(dir, "generation.json")) && !existsSync(join(dir, "generation-seal.json"))) return { entries: 0, lastAt: null };
   const store = openShardStore({ memoryDir: base, project: key, deferPromotions: true, lifecycle: "ignore" });
   try {
-    const db = new Database(join(dir, store.profile.foreignPruneFormat ? "index-v2.db" : "index.db"), { readonly: true });
+    const db = new Database(join(dir, indexFileName(!!store.profile.foreignPruneFormat)), { readonly: true });
     try {
       db.run("PRAGMA busy_timeout = 0");
       const row = db.query("SELECT COUNT(*) AS n, MAX(at) AS last FROM entries WHERE scope = 'project' AND project = ?" + (store.profile.foreignPruneFormat ? " AND id NOT IN (SELECT id FROM generation_targets)" : "")).get(key) as { n: number; last: string | null };

package/src/memory/doctor.ts

@@ -1,4 +1,6 @@
 import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { indexFileName } from "./index-file.ts";
+import { assertFormatFloor } from "./formats.ts";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import { Database } from "bun:sqlite";
@@ -12,10 +14,12 @@ import { readSelector } from "./generation.ts";
 import { processLiveness, withGitTimeout } from "./platform.ts";
 import { endLikeSignal, STOP_SIGNALS } from "./sync-cadence.ts";
 import { boundRepoRoot } from "./repo-scope.ts";
-import { facts, label, PLAIN, type Style } from "./style.ts";
+import { facts, label, PLAIN, singleLine, type Style } from "./style.ts";
 import { aliasedKeys, shardDir } from "./shard.ts";
 import type { MemoryStore, View } from "./store.ts";
 import { nextSyncAt, readSyncState, remoteConfigured, syncDue, usableState } from "./sync-cadence.ts";
+import { readSetupDrift } from "../setup-drift.ts";
+import { readHookSpoolStatus } from "../hook-spool.ts";
 
 /**
  * F15, `amem doctor`: one report over the memory home. It writes nothing into the home. Every check that needs a store (the notes, the brief, the index proof) runs on a
@@ -42,6 +46,8 @@ const MAX_IDS = 10;
 
 export interface DoctorOptions {
   home: string; homeSource: string; cwd: string; project: string; aliases: readonly string[]; now: number;
+  /** Test seam for setup path resolution; the CLI uses the process environment. */
+  env?: Readonly<Record<string, string | undefined>>;
   /** Opens this project's curated store on `base`, the way the other person reads do (a split home through its project shard). Doctor passes a private scratch base, never the live home. */
   openCurated: (base: string) => MemoryStore;
   /** The cadence command the person runs from their own shell; shown in the report, never installed. */
@@ -58,8 +64,12 @@ export interface DoctorReport {
     duplicates: Section; stale: Section; candidates: Section; capture: Section; brief: Section; index: Section; readers: Section; policy: Section; cadence: Section;
     /** Added after v1 shipped (#132); additive, so the schema stays amem.doctor/v1. */
     drops: Section;
+    /** #217, additive: bounded read-only home-wide hook backlog inventory. */
+    spool?: Section;
     /** #188, additive: present only when the project's curated logs hold forget or prune operations. Informational; status is always ok. */
     masked?: Section;
+    /** #202, additive: applied native setup registrations checked against the shared path resolver. */
+    setup?: Section;
   };
 }
 
@@ -202,7 +212,7 @@ export async function withBriefSnapshot<T>(home: string, project: string, read:
 
 /** A snapshot of the live shared-v1 index (a read-only connection, so no checkpoint, no lease), or false when there is none. */
 function snapshotIndex(live: string, to: string): boolean {
-  const file = join(live, "index.db");
+  const file = join(live, indexFileName(false));
   if (!regularFile(file)) return false;
   const forms: (() => Database)[] = [
     () => new Database(file, { readonly: true }),
@@ -356,6 +366,22 @@ function dropsSection(options: DoctorOptions): Section {
     ...(total ? { hint: "capture rows were dropped recently (see counts by reason); amem doctor --json keeps the numbers" } : {}) };
 }
 
+/** Bounded read-only inventory and classification; no replay, claim or retirement. */
+function spoolSection(options: DoctorOptions): Section {
+  try {
+    const inventory = readHookSpoolStatus(options.home);
+    const tiers = [inventory.active, inventory.reserve];
+    const full = tiers.some(tier => tier.files >= tier.maxFiles || tier.bytes >= tier.maxBytes);
+    const near = tiers.some(tier => tier.files >= tier.maxFiles * 0.9 || tier.bytes >= tier.maxBytes * 0.9);
+    return { ...inventory, status: !inventory.complete ? "unavailable" : full || near ? "attention" : "ok",
+      coverage: inventory.complete ? "complete" : "partial",
+      classificationCoverage: inventory.kinds.complete ? "complete" : "partial",
+      fill: full ? "full" : near ? "nearly_full" : !inventory.complete ? "unknown" : tiers.some(tier => tier.files > 0) ? "pending" : "empty",
+      ...(!inventory.complete ? { reason: "hook spool inventory is partial; reported file and byte counts are lower bounds" } : {}),
+      ...(full || near ? { hint: "pending hook spool needs attention: capture can be dropped when both tiers fill; supported orphan recovery is pending" } : {}) };
+  } catch { return unavailable("hook spool could not be read safely"); }
+}
+
 /** F16: which CLIs ingest at SessionEnd (setup receipts), and the person-owned sync cadence. amem registers no sync hook (a hook may not do network work). */
 function cadenceSection(options: DoctorOptions): Section {
   const ingest: Record<string, string> = {};
@@ -435,7 +461,11 @@ function guardScratch(): { adopt: (dir: string) => void; release: () => void } {
  * a lone signal waits at most one call for the signal handler, which then removes the scratch copy and ends doctor.
  */
 export const DOCTOR_GIT_TIMEOUT_MS = 5_000;
-export function doctorReport(options: DoctorOptions): Promise<DoctorReport> { return withGitTimeout(DOCTOR_GIT_TIMEOUT_MS, () => runDoctor(options)); }
+export function doctorReport(options: DoctorOptions): Promise<DoctorReport> {
+  // Doctor reads every surface below, live or through a scratch copy: a floor on any of them refuses the whole report before anything is read (#199 AC5).
+  for (const surface of ["curated", "capture", "candidates", "work-lists", "hook-spool"] as const) assertFormatFloor(options.home, surface);
+  return withGitTimeout(DOCTOR_GIT_TIMEOUT_MS, () => runDoctor(options));
+}
 async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
   let scratch: string | undefined, unguard: (() => void) | undefined;
   let duplicates: Section, stale: Section, index: Section;
@@ -459,7 +489,7 @@ async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
       } else {
         const home = join(scratch, "home"); mkdirSync(home, { mode: 0o700 });
         copyCurated(options, layout, home, budget);
-        const snapshotted = layout === "shared-v1" && snapshotIndex(options.home, join(home, "index.db"));
+        const snapshotted = layout === "shared-v1" && snapshotIndex(options.home, join(home, indexFileName(false)));
         curated = options.openCurated(home);
         const rows = curated.list({ project: options.project, limit: LIST_ALL });
         await tick();
@@ -480,10 +510,13 @@ async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
     candidates = summary === null ? unavailable("candidates.db exists but cannot be read")
       : { status: summary.dueWithin7Days ? "attention" : "ok", ...summary, ...(summary.dueWithin7Days ? { hint: "run amem review walk" } : {}) };
   } catch (error) { candidates = unavailable(message(error)); }
+  let setup: Section;
+  try { setup = { ...readSetupDrift({ home: options.home, ...(options.env ? { env: options.env } : {}), cwd: options.cwd }) }; }
+  catch { setup = unavailable("setup registrations could not be checked"); }
   let sections: DoctorReport["sections"];
   try {
     await tick();
-    sections = { duplicates, stale, candidates, capture: captureSection(options), brief: await briefSection(options, curated, workBase, copyFailed), index, readers: readersSection(options), policy: policySection(options), cadence: cadenceSection(options), drops: dropsSection(options), ...maskedSection(curated) };
+    sections = { duplicates, stale, candidates, capture: captureSection(options), brief: await briefSection(options, curated, workBase, copyFailed), index, readers: readersSection(options), policy: policySection(options), cadence: cadenceSection(options), drops: dropsSection(options), spool: spoolSection(options), setup, ...maskedSection(curated) };
     await tick();   // a signal that arrived during the last synchronous stage is handled while the guard is still installed
   } finally { try { curated?.close(); } finally { try { if (scratch) rmSync(scratch, { recursive: true, force: true }); } finally { unguard?.(); } } }
   return { schema: DOCTOR_SCHEMA, status: worst(Object.values(sections).map(section => section.status)), home: { path: options.home, source: options.homeSource }, project: options.project, sections };
@@ -493,6 +526,8 @@ async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
 const SECTION_TITLE: Record<keyof DoctorReport["sections"], string> = {
   duplicates: "duplicate notes", stale: "stale path references", candidates: "review candidates", capture: "capture per CLI", brief: "session brief",
   index: "index equals rebuild", readers: "reader leases", policy: "policy in effect", cadence: "ingest and sync cadence", drops: "recent capture drops",
+  spool: "pending hook spool",
+  setup: "native setup registrations",
   masked: "forgotten or pruned entries (informational)",
 };
 
@@ -513,6 +548,20 @@ function sectionDetail(name: string, detail: Record<string, unknown>, s: Style):
     const counts = Object.entries((detail.counts ?? {}) as Record<string, number>);
     return [counts.length ? `${counts.map(([reason, n]) => `${reason.replaceAll("_", " ")} ${n}`).join(", ")} (recent metrics tail)` : "none in the recent metrics tail"].map(line => detail.malformedLines ? `${line}; ${detail.malformedLines} malformed lines skipped` : line);
   }
+  if (name === "spool") {
+    if (!detail.active || !detail.reserve) return [];
+    const tiers = ["active", "reserve"].map(name => {
+      const tier = detail[name] as { files: number; bytes: number; maxFiles: number; maxBytes: number };
+      return `${name} ${tier.files}/${tier.maxFiles} files, ${tier.bytes}/${tier.maxBytes} bytes`;
+    });
+    const kinds = detail.kinds as { native: number; summaries: number; unclassified: number; complete: boolean };
+    return [`${detail.fill}; ${tiers.join("; ")}; claimed ${detail.claimed}; oldest ${detail.oldestAt ?? "none observed"}; coverage ${detail.coverage}${detail.complete ? "" : " (counts are lower bounds)"}`,
+      `native ${kinds.native}, summaries ${kinds.summaries}, unclassified ${kinds.unclassified}; classification ${detail.classificationCoverage}${kinds.complete ? "" : " (native and summary counts are lower bounds)"}`];
+  }
+  if (name === "setup" && Array.isArray(detail.entries)) {
+    return (detail.entries as { target?: unknown; file?: unknown; entry?: unknown; reason?: unknown; expectedFile?: unknown }[]).map(item =>
+      singleLine(`${item.target} ${item.file}${item.expectedFile ? ` -> ${item.expectedFile}` : ""} ${item.entry}: ${item.reason}`));
+  }
   if (name === "brief" && typeof detail.tokens === "number") return [`${detail.tokens} of ${detail.budget} tokens${detail.coverage ? `, coverage ${facts(detail.coverage as Record<string, unknown>) || "complete"}` : ""}`];
   const { examples, ...rest } = detail;
   const line = facts(rest);

package/src/memory/formats.ts

@@ -0,0 +1,65 @@
+import { closeSync, constants, fstatSync, openSync, readFileSync, readSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Format floors (#199 AC5). `formats.json` in the memory home is an append-only JSON array of `{ surface, minReader, since }` records: a
+ * person appends one to stop releases older than `minReader` from reading that surface (`home` covers every surface). This package never
+ * writes the file, so no writer raises a floor implicitly. Each surface checks its floor before it creates, opens or writes anything, and a
+ * reader below it refuses with `code: "format_floor"`; a file this version cannot read refuses with `code: "format_floor_unreadable"`.
+ * A record naming a surface this version does not know is not its concern. Releases before this one do not read the file.
+ */
+export const FORMATS_FILE = "formats.json";
+export const FORMAT_SURFACES = ["curated", "capture", "hook-spool", "candidates", "work-lists", "sync"] as const;
+export type FormatSurface = typeof FORMAT_SURFACES[number];
+export interface FormatFloor { surface: string; minReader: string; since: string }
+const MAX_BYTES = 64 * 1024, SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/;
+
+export class FormatFloorError extends Error {
+  constructor(readonly code: "format_floor" | "format_floor_unreadable", message: string, readonly floor?: FormatFloor & { reader: string }) { super(message); this.name = "FormatFloorError"; }
+}
+/**
+ * This release's version, read once when the module loads, so a long-running process whose install is replaced in place keeps comparing its own
+ * version. Undefined when it cannot be read: then every applicable floor refuses.
+ */
+const READER_VERSION: string | undefined = (() => {
+  try { const { version } = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")) as { version?: unknown }; return typeof version === "string" && SEMVER.test(version) ? version : undefined; }
+  catch { return undefined; }
+})();
+const parts = (version: string) => SEMVER.exec(version)!.slice(1, 4).map(Number);
+function below(reader: string, floor: string): boolean {
+  const a = parts(reader), b = parts(floor);
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i]! < b[i]!;
+  return false;
+}
+
+/** Bounded read of the floor records: undefined when there is no file; anything that is not a regular file of valid records refuses. */
+export function readFormatFloors(home: string): FormatFloor[] | undefined {
+  const file = join(home, FORMATS_FILE), unreadable = (why: string) => new FormatFloorError("format_floor_unreadable", `${file}: ${why}; nothing was read or written. Fix or restore the file (it is append-only and written by a person).`);
+  let fd: number;
+  try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT" || (error as NodeJS.ErrnoException).code === "ENOTDIR") return undefined; throw unreadable("not a readable regular file"); }
+  let text: string;
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > MAX_BYTES) throw unreadable("not a regular file of at most 64 KiB");
+    const data = Buffer.alloc(MAX_BYTES + 1); let size = 0, n: number;
+    while (size < data.length && (n = readSync(fd, data, size, data.length - size, null)) > 0) size += n;
+    if (size > MAX_BYTES) throw unreadable("not a regular file of at most 64 KiB");
+    text = data.subarray(0, size).toString("utf8");
+  } finally { closeSync(fd); }
+  let value: unknown;
+  try { value = JSON.parse(text); } catch { throw unreadable("not JSON"); }
+  if (!Array.isArray(value) || !value.every(record => record && typeof record === "object" && !Array.isArray(record)
+    && typeof record.surface === "string" && typeof record.minReader === "string" && SEMVER.test(record.minReader) && typeof record.since === "string")) throw unreadable("not an array of { surface, minReader, since } records");
+  return value.map(({ surface, minReader, since }) => ({ surface, minReader, since }));
+}
+
+/** Refuse before touching `surface` when the home records a floor above this release. */
+export function assertFormatFloor(home: string, surface: FormatSurface): void {
+  const floors = readFormatFloors(home);
+  if (!floors) return;
+  const reader = READER_VERSION ?? "unknown";
+  for (const floor of floors) if ((floor.surface === surface || floor.surface === "home") && (READER_VERSION === undefined || below(READER_VERSION, floor.minReader))) {
+    throw new FormatFloorError("format_floor", `amem ${reader} is below the ${surface} format floor ${floor.minReader} (since ${floor.since}) recorded in ${join(home, FORMATS_FILE)}; nothing was read or written. Upgrade amem to ${floor.minReader} or later.`, { ...floor, reader });
+  }
+}

package/src/memory/index-file.ts

@@ -0,0 +1,15 @@
+/** Bumped when the index's tables change: an index with another version is dropped and rebuilt from the logs. */
+export const INDEX_VERSION = 3; // 3: suggest, confirm and reject ops (an older index skipped them)
+/** The version that released 0.14.0 through 0.18.0 build into the unversioned names below; it keeps them so this release shares their warm index. */
+const SHARED_INDEX_VERSION = 3;
+
+/**
+ * The derived curated index file of a profile directory, one per `INDEX_VERSION` (#199 AC4): two releases with different index versions on
+ * one home each keep their own file instead of dropping and rebuilding the other's. Version 3 keeps the released names (`index.db`, and
+ * `index-v2.db` for the v2 public-prune view, whose `v2` is that view's format, not the index version); every later version names its own,
+ * `index-v<N>.db` or `index-v2-i<N>.db`. An older version's file is left as it is.
+ */
+export function indexFileName(foreignPruneFormat: boolean, version: number = INDEX_VERSION): string {
+  const base = foreignPruneFormat ? "index-v2" : "index";
+  return version === SHARED_INDEX_VERSION ? `${base}.db` : foreignPruneFormat ? `${base}-i${version}.db` : `${base}-v${version}.db`;
+}

package/src/memory/metrics.ts

@@ -1,8 +1,10 @@
 import { closeSync, constants, fstatSync, openSync, readSync, appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import type { HookRssSources } from "../hook-resources.ts";
+import type { HookTranscriptStopReason } from "../hook-contract.ts";
 import { join } from "node:path";
 
 /** Rolling resource samples; importing this leaf never loads a memory store or capacity probe. */
-export interface MetricSample { at: string; kind: "hook" | "search"; wallMs?: number; rssMB?: number; rawRssMB?: number; idleMB?: number; captureDrops?: number; captureDropReason?: CaptureDropReason }
+export interface MetricSample { at: string; kind: "hook" | "search"; wallMs?: number; rssMB?: number; rawRssMB?: number; rssSources?: HookRssSources; rssScope?: "owned-images"; transcriptOffset?: number; transcriptStopReason?: HookTranscriptStopReason; /** #226: owned children killed but still alive when the hook returned (bounded reap). */ abandonedChildren?: number; /** #226: a killed worker skipped this call's drain; staged records stay pending (not a capture drop). */ drainSkipped?: number; /** #226: when the worker drain started (ms after hook start) and how many records it committed. */ drainStartMs?: number; drained?: number; idleMB?: number; captureDrops?: number; captureDropReason?: CaptureDropReason }
 const METRICS_MAX_BYTES = 64 * 1024, METRICS_KEEP = 200;
 
 export function metricsPath(base: string): string {
@@ -36,8 +38,8 @@ export function readMetrics(base: string, limit = METRICS_KEEP): MetricSample[]
 }
 
 
-export type CaptureDropReason = "spool_full" | "cwd_removed" | "undrainable_expired" | "scope_unknown" | "project_archived" | "project_forgotten" | "unknown_schema_expired";
-const DROP_REASONS: readonly CaptureDropReason[] = ["spool_full", "cwd_removed", "undrainable_expired", "scope_unknown", "project_archived", "project_forgotten", "unknown_schema_expired"];
+export type CaptureDropReason = "summary_capacity" | "scope_capacity" | "spool_full" | "cwd_removed" | "undrainable_expired" | "scope_unknown" | "project_archived" | "project_forgotten" | "unknown_schema_expired" | "transcript_line_bound";
+const DROP_REASONS: readonly CaptureDropReason[] = ["summary_capacity", "scope_capacity", "spool_full", "cwd_removed", "undrainable_expired", "scope_unknown", "project_archived", "project_forgotten", "unknown_schema_expired", "transcript_line_bound"];
 /** Numeric notice only, bounded to the rolling metric tail; never an all-time counter. Fails open to no counts: hooks never deny over metrics. */
 export function captureDropSummary(base: string): Partial<Record<CaptureDropReason, number>> {
   const read = readCaptureDrops(base);

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

@@ -2,6 +2,7 @@
  * Checkpoints are fault seams after intent, shard marker, selector and intent removal.
  * A caller resumes an interrupted operation from its immutable direct-profile journal. */
 import { createHash } from "node:crypto";
+import { indexFileName } from "./index-file.ts";
 import { closeSync, constants, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { canonicalJSON, fsyncDirectory, hashJSON, readSelector, withProfileLock, writeProfileJSON, type BoundProfile } from "./generation.ts";
@@ -105,7 +106,7 @@ function immutable(file: string, text: string): void {
   linkSync(temp, file); fsyncDirectory(base); unlinkSync(temp); fsyncDirectory(base);
 }
 function syncIndex(profile: BoundProfile): void {
-  const file = join(profile.dir, "index-v2.db"); owned(file); const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  const file = join(profile.dir, indexFileName(true)); owned(file); const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
   try { fsyncSync(fd); } finally { closeSync(fd); } fsyncDirectory(profile.dir);
 }
 function nextProfile(realm: Realm, intent: Intent): BoundProfile {

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

@@ -49,14 +49,18 @@ export function waitForPublicPruneWriter(home: string, absoluteDeadline?: number
     const deadline = Math.min(absoluteDeadline ?? Infinity, Date.now() + PROFILE_LOCK_TIMEOUT_MS);
     const intentFile = join(home, PUBLIC_PRUNE_INTENT), lockFile = join(home, "profile.lock");
     if (!lstatSync(intentFile, { throwIfNoEntry: false }) && !lstatSync(lockFile, { throwIfNoEntry: false })) return;
+    // #225: a cooperating writer that finishes unlinks its intent, then its lock. If that lands between this reader's
+    // open and fstat, the fd's link count is 0. Only that is the normal disappearance (ENOENT): bytes read through the fd
+    // are discarded and the bounded loop re-resolves the path from scratch. Any other link count still refuses.
+    const unlinked = (stat: Stats): void => { if (stat.nlink === 0) throw Object.assign(new Error("publication unlinked while open"), { code: "ENOENT" }); };
     const small = (file: string, limit: number): Record<string, unknown> => {
       const before = lstatSync(file); privateStat(before); guard(before.size > 0 && before.size <= limit);
       const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
       try {
-        const opened = fstatSync(fd); privateStat(opened); guard(opened.size > 0 && opened.size <= limit);
+        const opened = fstatSync(fd); unlinked(opened); privateStat(opened); guard(opened.size > 0 && opened.size <= limit);
         const bytes = Buffer.alloc(opened.size + 1); let count = 0;
         while (count < bytes.length) { const read = readSync(fd, bytes, count, bytes.length - count, count); if (!read) break; count += read; }
-        const after = fstatSync(fd); privateStat(after); guard(count === opened.size && same(opened, after));
+        const after = fstatSync(fd); unlinked(after); privateStat(after); guard(count === opened.size && same(opened, after));
         const parsed: unknown = JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes.subarray(0, count))); guard(object(parsed)); return parsed;
       } finally { closeSync(fd); }
     };

package/src/memory/search-score.ts

@@ -17,12 +17,13 @@ const DEFAULT_TIER_WEIGHT = 0.9;
 // ponytail: fixed 1.25x ceiling for conversational capture, not a learned relevance model.
 // Raise it only with fresh S/M no-loss and private-capture evidence; curated tier factors stay unchanged.
 export const CAPTURE_CONVERSATION_WEIGHT = 1.25;
+const CONVERSATIONAL_CAPTURE_EVENTS = ["Stop", "UserPromptSubmit", "Title", "Recap", "Compact"] as const;
 export function captureEventWeight(event: string): number {
-  return event === "Stop" || event === "UserPromptSubmit" ? CAPTURE_CONVERSATION_WEIGHT : 1;
+  return (CONVERSATIONAL_CAPTURE_EVENTS as readonly string[]).includes(event) ? CAPTURE_CONVERSATION_WEIGHT : 1;
 }
 /** Only fixed internal SQL identifiers are supplied by callers; event values remain stored data. */
 export function captureEventWeightSql(eventColumn: string): string {
-  return `(CASE WHEN ${eventColumn} IN ('Stop', 'UserPromptSubmit') THEN ${CAPTURE_CONVERSATION_WEIGHT} ELSE 1.0 END)`;
+  return `(CASE WHEN ${eventColumn} IN (${CONVERSATIONAL_CAPTURE_EVENTS.map(event => `'${event}'`).join(", ")}) THEN ${CAPTURE_CONVERSATION_WEIGHT} ELSE 1.0 END)`;
 }
 const TIER_FACTOR: ScoreExpr = { op: "tier" };
 const DENOMINATOR: ScoreExpr = { op: "add", left: { op: "constant", value: 1 }, right: { op: "max", left: { op: "constant", value: 0 }, right: { op: "age" } } };

package/src/memory/shard.ts

@@ -1,4 +1,5 @@
 import { assertNoPublicPruneIntent, readPublicPruneView } from "./public-prune-view.ts";
+import { indexFileName } from "./index-file.ts";
 import { createHash, randomBytes } from "node:crypto";
 import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -145,7 +146,7 @@ export function assertCuratedShardPaths(memoryDir: string, opts: { project?: str
   check(dir, true);
   for (const folder of ["log", "local", "legacy", "legacy/log", "legacy/local", "legacy-main", "legacy-main/log", "legacy-main/local"]) check(join(dir, folder), true);
   for (const name of ["project.json", "generation.json", "generation-seal.json", "migration-sources.json", "machine.json", "legacy/machine.json", "legacy-main/machine.json", "prune-translations.jsonl"]) check(join(dir, name), false);
-  for (const database of ["index.db", "index-v2.db", "search.db", "mutation-lock.db"]) for (const suffix of ["", "-wal", "-shm", "-journal"]) check(join(dir, database + suffix), false);
+  for (const database of new Set(["index.db", "index-v2.db", indexFileName(false), indexFileName(true), "search.db", "mutation-lock.db"])) for (const suffix of ["", "-wal", "-shm", "-journal"]) check(join(dir, database + suffix), false);
 }
 
 /** Open one already-sealed shard without consulting the legacy home or the catalog. */

package/src/memory/store.ts

@@ -1,4 +1,6 @@
+import { assertFormatFloor } from "./formats.ts";
 import { readPublicPruneView } from "./public-prune-view.ts";
+import { INDEX_VERSION, indexFileName } from "./index-file.ts";
 import { readShardLegacySnapshot } from "./shard-bridge.ts";
 import { cliAttribution } from "./cli-attribution.ts";
 import { Database } from "bun:sqlite";
@@ -77,8 +79,6 @@ export type Entry = NoteEntry | OpEntry | GoalEntry;
 export const GOAL_STATES = ["open", "active", "blocked", "done", "dropped"] as const;
 export type GoalState = (typeof GOAL_STATES)[number];
 export const DEFAULT_LEASE_MS = 4 * 3600_000;
-/** Bumped when the index's tables change: an index with another version is dropped and rebuilt from the logs. */
-const INDEX_VERSION = 3; // 3: suggest, confirm and reject ops (an older index skipped them)
 export const SUGGESTED = ["contradicts", "same_topic"] as const;
 export type Suggested = (typeof SUGGESTED)[number];
 export interface Suggestion { id: string; at: string; from: string; to: string; rel: Suggested; status: "suggested" | "confirmed" | "rejected" }
@@ -233,6 +233,7 @@ export class MemoryStore {
     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"));
+    assertFormatFloor(home, "curated");
     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
@@ -253,7 +254,7 @@ export class MemoryStore {
     if (!bootstrap || bootstrap.authoring === true) this.releaseReaderLease = registerReaderLease(this.profile.home, this.profile.sharded ? {scope:"shard"} : {});
     let openedDb: Database | undefined, openedMutation: Database | undefined, openedSearch: SearchIndex | undefined;
     try {
-      const indexFile = join(this.dir, this.profile.foreignPruneFormat ? "index-v2.db" : "index.db");
+      const indexFile = join(this.dir, indexFileName(!!this.profile.foreignPruneFormat));
       if (this.profile.foreignPruneFormat) for (const suffix of ["", "-wal", "-shm", "-journal"]) {
         const stat = lstatSync(indexFile + suffix, {throwIfNoEntry:false});
         if (stat && (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1 || stat.uid !== process.getuid?.())) throw new Error("v2 index path unavailable");
@@ -280,7 +281,7 @@ export class MemoryStore {
       // 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, this.profile.foreignPruneFormat ? "index-v2.db" : "index.db"), 0o600); } catch { /* best effort */ }
+      try { chmodSync(indexFile, 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 } : {}) });
@@ -1633,6 +1634,7 @@ export function openShardStore(opts: StoreOptions & { project?: string; user?: b
   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"));
+  assertFormatFloor(home, "curated");
   assertCuratedShardPaths(home, opts);
   // Lifecycle refusal must remain before admission creates any lease/fence file.
   if (opts.user !== true && opts.lifecycle !== "ignore") assertProjectActive(home, opts.project!);

package/src/memory/sync.ts

@@ -1,3 +1,4 @@
+import { assertFormatFloor } from "./formats.ts";
 import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, rmSync, writeFileSync, writeSync, type BigIntStats } from "node:fs";
 import { createHash } from "node:crypto";
 import { dirname, join, relative, sep } from "node:path";
@@ -284,6 +285,7 @@ function captureShardSyncBinding(store: MemoryStore, selection: boolean): string
 }
 
 export async function syncMemory(store: MemoryStore, opts: SyncOptions = {}): Promise<SyncResult> {
+  assertFormatFloor(store.profile.home, "sync");
   if (store.profile.sharded) {
     try {
       // Refresh only through the existing proved monotone profile rebind before pinning this attempt.

package/src/memory/work-lists.ts

@@ -1,3 +1,4 @@
+import { assertFormatFloor } from "./formats.ts";
 import { Database } from "bun:sqlite";
 import { createHash, randomBytes } from "node:crypto";
 import { appendFileSync, chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readSync, readdirSync } from "node:fs";
@@ -131,6 +132,7 @@ export class WorkListStore {
       || !Number.isSafeInteger(this.busyTimeoutMs) || this.busyTimeoutMs < 0 || this.busyTimeoutMs > 3000) throw new Error("invalid work-list budget");
     this.checkBudget();
     const base = canonicalPath(options.base);
+    assertFormatFloor(base, "work-lists");
     this.project = options.exact === true ? options.project : resolveAlias(base, options.project);
     regular(join(base, "projects"), true); regular(shardDir(base, this.project), true);
     this.checkBudget();