pi-canon 0.1.2 → 0.2.0

package/extensions/lib/retrieval.ts

@@ -0,0 +1,355 @@
+/* Retrieval: the seam for knowledge the spine cannot address.
+
+   The spine answers every asset-scoped question deterministically and for free, and
+   nothing here changes that. Retrieval runs over the RESIDUE, the articles whose
+   address matches no asset, which is the category 1.0 named and left open ("knowledge
+   filed off the asset path never surfaces"). That scoping is what makes an expensive
+   ranker affordable: the corpus to rank is what has no home, not the whole store, and
+   it stays small precisely because everything with a home is answered without ranking.
+
+   Two built-ins ship. `none` is 1.0 exactly and is the experiment's control. `lexical`
+   is BM25 with nothing but the standard library. Anything that needs a model is
+   supplied by the caller as a function, so this package never grows a torch, ONNX or
+   network dependency and never decides which model you run.
+
+   Deliberately absent: any threshold. A retriever returns SCORES, and what to do with
+   them is measured rather than assumed. A constant deciding what an agent gets to see
+   is the mistake the session budget already made once. */
+
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { CanonStore } from "./store.ts";
+
+export interface Candidate {
+  path: string;
+  capsule: string;
+  body: string;
+  updated: string;
+  /* Whether this article SAID it is a cross-cutting rule, rather than being inferred
+     into the corpus by having no asset. See residue below. */
+  declared: boolean;
+}
+
+export interface Retriever {
+  name: string;
+  /* Called off the hot path whenever the residue changes. Free to be a no-op. */
+  index?(candidates: Candidate[]): void;
+  /* Higher is more relevant. A path missing from the result scored nothing. */
+  score(query: string, candidates: Candidate[]): Map<string, number>;
+}
+
+/* ---------------------------------------------------------------------------------
+   The query: intent, never evidence.
+
+   pi-fold measured this on memex and it is the single most expensive thing to get
+   wrong: a live window of 29,369 characters carried 29,244 characters of raw tool
+   output and 125 characters of the agent's own reasoning, so a lexical scorer was
+   matching against `read` and `shell` dumps and every retrieval number it produced was
+   that one defect. Tool RESULTS are therefore excluded outright.
+
+   The agent's own prose is excluded for a second, independent reason. Accordion's
+   relevance-signals exploration showed that a signal read off text the agent already
+   produced is retrospective: the text was generated while the article was absent, so
+   scoring against it measures agreement with the path already taken rather than need.
+   Where the agent went wrong for lack of an article, its own words argue against it.
+
+   What survives both objections is intent. A user message is exogenous and is a
+   statement of what is wanted. A tool call is agent-authored but is a forward
+   declaration of an action rather than reasoning about content, so the circularity
+   objection does not reach it; its name plus first meaningful argument is the whole
+   signal, and the rest is payload.
+---------------------------------------------------------------------------------- */
+
+const INTENT_ARGUMENT_KEYS = ["path", "file_path", "pattern", "query", "command", "description"];
+const INTENT_ARGUMENT_CHARS = 200;
+/* How much of the window's user speech counts as the current question. Newest first and
+   bounded rather than the whole window, because the position control is the strongest
+   number either package has on this: same window, oldest half MRR 0.0485 with 4 targets
+   in the top 5, newest half 0.1071 with 10. */
+const USER_INTENT_CHARS = 1500;
+/* What stands in for the middle of a message too long to carry whole. Visible on purpose:
+   a query built from two ends of a message should read as such. */
+const ELISION = "\n...\n";
+
+export interface IntentTurn {
+  role?: unknown;
+  content?: unknown;
+  toolName?: unknown;
+  input?: unknown;
+}
+
+/* Pi carries content as a string or as typed parts; only text parts are speech. */
+function messageText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const text: string[] = [];
+  for (const part of content) {
+    if (part && typeof part === "object" && (part as Record<string, unknown>).type === "text") {
+      text.push(String((part as Record<string, unknown>).text ?? ""));
+    }
+  }
+  return text.join("\n");
+}
+
+/* The user's own words out of the projection, newest first and bounded.
+
+   This is the best query either finding endorses without qualification: exogenous, so
+   the circularity objection cannot reach it, and a statement of what is wanted rather
+   than evidence of what was found.
+
+   pi-canon's own steered nudges arrive as messages too, and ranking articles against
+   the text of previous article nudges would be a feedback loop that scores an article
+   highly for having been surfaced already. They are excluded by both their customType
+   and their visible prefix, because only one of the two survives every delivery path. */
+export function userIntent(messages: unknown): IntentTurn[] {
+  if (!Array.isArray(messages)) return [];
+  const picked: IntentTurn[] = [];
+  let chars = 0;
+  for (let i = messages.length - 1; i >= 0 && chars < USER_INTENT_CHARS; i -= 1) {
+    const message = messages[i] as Record<string, unknown> | null;
+    if (!message || typeof message !== "object") continue;
+    if (message.role !== "user") continue;
+    if (message.customType === "pi-canon") continue;
+    const text = messageText(message.content).trim();
+    if (!text || text.startsWith("[pi-canon]")) continue;
+    /* Both ends of an over-long message, never one.
+
+       This kept the head, was changed to keep the tail on the argument that the position
+       effect should apply within a message as it does across the window, and neither is
+       right. The measured effect is about position in the WINDOW, and "fix X, here are the
+       logs" is at least as common as a trailing ask (Codex, 2026-08-13, whose example was
+       the review brief it was reading, where tail-only would have discarded every numbered
+       question and ranked on the closing section alone). Neither end is reliably the ask,
+       so when a message will not fit, keep the opening and the closing and drop the
+       middle, which is payload in both shapes. */
+    const room = USER_INTENT_CHARS - chars;
+    /* The elision marker is part of the budget, not on top of it, or the bound is not a
+       bound: half plus half plus the marker came out over USER_INTENT_CHARS. */
+    const half = Math.max(0, Math.floor((room - ELISION.length) / 2));
+    const bounded = text.length <= room ? text
+      : `${text.slice(0, half)}${ELISION}${text.slice(-half)}`;
+    chars += bounded.length;
+    picked.push({ role: "user", content: bounded });
+  }
+  /* Reversed back to oldest first, so the caller can append this turn's tool calls
+     after them and intentQuery's newest-first walk still reads in true order. */
+  return picked.reverse();
+}
+
+function firstArgument(input: unknown): string {
+  if (!input || typeof input !== "object") return "";
+  for (const key of INTENT_ARGUMENT_KEYS) {
+    const value = (input as Record<string, unknown>)[key];
+    if (typeof value === "string" && value.trim()) return value.trim().slice(0, INTENT_ARGUMENT_CHARS);
+  }
+  return "";
+}
+
+/* Newest first, because relevance to now sits at the tail: replaying 56 real retrieval
+   targets, pi-fold measured MRR 0.1071 with 10 targets in the top 5 for the newest half
+   of a window against 0.0485 and 4 for the oldest half of the SAME window, which makes
+   it a position effect rather than a length effect. */
+export function intentQuery(turns: readonly IntentTurn[]): string {
+  const pieces: string[] = [];
+  for (let i = turns.length - 1; i >= 0; i -= 1) {
+    const turn = turns[i];
+    if (turn?.toolName) {
+      const argument = firstArgument(turn.input);
+      pieces.push(argument ? `${String(turn.toolName)} ${argument}` : String(turn.toolName));
+      continue;
+    }
+    if (turn?.role === "user") {
+      const text = messageText(turn.content).trim();
+      if (text) pieces.push(text);
+    }
+  }
+  return pieces.join("\n");
+}
+
+/* ---------------------------------------------------------------------------------
+   BM25, standard library only.
+
+   Reimplemented rather than lifted from pi-fold. The two packages publish
+   independently, and a verbatim copy between them rebuilds exactly the drift problem
+   pi-fold deliberately retired. What crosses is the lessons, above and below, not the
+   code.
+---------------------------------------------------------------------------------- */
+
+const K1 = 1.5;
+const B = 0.75;
+const MIN_TOKEN = 4;
+const STOPWORDS = new Set([
+  "about", "after", "again", "against", "because", "been", "before", "being", "between",
+  "both", "cannot", "could", "does", "doing", "down", "during", "each", "from", "further",
+  "have", "having", "here", "into", "itself", "just", "more", "most", "once", "only",
+  "other", "over", "same", "should", "some", "such", "than", "that", "their", "them",
+  "then", "there", "these", "they", "this", "those", "through", "under", "until", "very",
+  "were", "what", "when", "where", "which", "while", "will", "with", "would", "your",
+]);
+
+/* Tokens WITH repetition: BM25 reads term frequency, and deduping here would silently
+   flatten every tf to 1. */
+export function tokens(value: string): string[] {
+  const out: string[] = [];
+  for (const raw of value.toLowerCase().split(/[^a-z0-9_]+/)) {
+    const token = raw.replace(/^_+|_+$/g, "");
+    if (token.length < MIN_TOKEN || STOPWORDS.has(token)) continue;
+    out.push(token);
+  }
+  return out;
+}
+
+interface Indexed {
+  length: number;
+  frequencies: Map<string, number>;
+}
+
+export class LexicalRetriever implements Retriever {
+  readonly name = "lexical";
+  private documents = new Map<string, Indexed>();
+  private documentFrequency = new Map<string, number>();
+  private averageLength = 0;
+
+  index(candidates: Candidate[]): void {
+    this.documents = new Map();
+    this.documentFrequency = new Map();
+    let total = 0;
+    for (const candidate of candidates) {
+      const frequencies = new Map<string, number>();
+      const terms = tokens(`${candidate.path} ${candidate.capsule} ${candidate.body}`);
+      for (const term of terms) frequencies.set(term, (frequencies.get(term) ?? 0) + 1);
+      this.documents.set(candidate.path, { length: terms.length, frequencies });
+      total += terms.length;
+      for (const term of frequencies.keys()) {
+        this.documentFrequency.set(term, (this.documentFrequency.get(term) ?? 0) + 1);
+      }
+    }
+    this.averageLength = candidates.length ? total / candidates.length : 0;
+  }
+
+  private idf(term: string): number {
+    const n = this.documentFrequency.get(term) ?? 0;
+    if (!n) return 0;
+    return Math.log(1 + (this.documents.size - n + 0.5) / (n + 0.5));
+  }
+
+  /* Divide by what a document scores when every query term is saturated in it. BM25's
+     raw score is unbounded and its scale moves with the query, so the same number means
+     different things run to run; against the ceiling it is an absolute 0..1 reading,
+     which is what makes a score comparable across turns and worth recording beside the
+     context it cost. */
+  private ceiling(terms: ReadonlySet<string>): number {
+    let ceiling = 0;
+    for (const term of terms) ceiling += this.idf(term) * (K1 + 1);
+    return ceiling;
+  }
+
+  score(query: string, candidates: Candidate[]): Map<string, number> {
+    const out = new Map<string, number>();
+    const terms = new Set(tokens(query));
+    if (!terms.size || !this.documents.size) return out;
+    const ceiling = this.ceiling(terms);
+    if (ceiling <= 0) return out;
+    for (const candidate of candidates) {
+      const document = this.documents.get(candidate.path);
+      if (!document?.length) continue;
+      let score = 0;
+      for (const term of terms) {
+        const frequency = document.frequencies.get(term);
+        if (!frequency) continue;
+        const denominator =
+          frequency + K1 * (1 - B + B * (document.length / (this.averageLength || 1)));
+        score += this.idf(term) * ((frequency * (K1 + 1)) / denominator);
+      }
+      if (score > 0) out.set(candidate.path, score / ceiling);
+    }
+    return out;
+  }
+}
+
+export const NONE: Retriever = {
+  name: "none",
+  score: () => new Map(),
+};
+
+export type RetrievalOption = "none" | "lexical" | Retriever;
+
+export function buildRetriever(option: RetrievalOption | undefined): Retriever {
+  if (option === undefined || option === "none") return NONE;
+  if (option === "lexical") return new LexicalRetriever();
+  if (typeof option === "object" && option && typeof option.score === "function") {
+    if (typeof option.name !== "string" || !option.name.trim()) {
+      throw new Error("pi-canon: a retrieval object needs a name, so runs can be told apart.");
+    }
+    return option;
+  }
+  throw new Error(
+    `pi-canon: retrieval must be "none", "lexical", or an object with a name and a score function; got ${
+      typeof option === "string" ? `"${option}"` : typeof option
+    }.`,
+  );
+}
+
+/* The residue: articles the spine can never surface, because surfacing is triggered by
+   touching an asset and there is nothing here to touch. Everything else is already
+   answered for free and must not be ranked, or retrieval would compete with the address
+   instead of completing it.
+
+   Membership is still decided by having no asset, and that is deliberate: an article
+   unreachable by address has exactly one mechanism left, and dropping it from that
+   mechanism would lose it outright. But the set has always held two populations, and
+   until now nothing could tell them apart (Codex, 2026-08-12). One is the deliberate
+   cross-cutting rule the doctrine asks for, filed at an address naming the rule. The
+   other is an accident: a typo in an address, or an article whose asset was deleted
+   under it. Defining the corpus only by what it is not made those the same thing.
+
+   So an article may DECLARE itself with `scope: rule`, and every candidate carries
+   whether it did. Nothing here filters on it, because a declaration the agent forgot
+   must not cost it the only mechanism that can reach it. What the flag buys is honesty:
+   a declared article is a rule on purpose, an undeclared one is a question, and the two
+   stop being counted as one number. */
+export function residue(store: CanonStore, dir: string): Candidate[] {
+  const out: Candidate[] = [];
+  for (const path of store.list()) {
+    const article = store.read(path);
+    if (!article) continue;
+    /* Declared first, so a rule stays reachable even if a file later appears at its
+       address. Membership was decided by the filesystem alone, which meant a
+       deliberate cross-cutting rule silently dropped out of the only mechanism that
+       reaches it the moment something coincided with its name (Sol Pro, 2026-08-13).
+       Undeclared and off the asset path still qualifies, so forgetting the flag stays
+       fail-open. */
+    if (article.scope !== RULE_SCOPE && governsAnAsset(dir, path)) continue;
+    out.push({
+      path,
+      capsule: article.capsule,
+      body: article.body,
+      updated: article.updated,
+      declared: article.scope === RULE_SCOPE,
+    });
+  }
+  return out;
+}
+
+/* The one declared value. A second would be a taxonomy, and nothing has asked for one. */
+export const RULE_SCOPE = "rule";
+
+/* An address governs an asset when something on disk normalizes back to it. Addresses
+   drop the extension, so `src/core/config` has to match `src/core/config.ts` as well as
+   a bare `src/core/config` directory or file, which is one readdir of the parent rather
+   than a walk of the tree. A path that cannot be read is treated as governing nothing,
+   which puts the article in the residue: over-including costs a ranking slot, while
+   under-including would silently drop knowledge from the only mechanism that can reach
+   it. */
+export function governsAnAsset(dir: string, path: string): boolean {
+  const full = join(dir, path);
+  if (existsSync(full)) return true;
+  const base = path.slice(path.lastIndexOf("/") + 1);
+  try {
+    return readdirSync(dirname(full)).some(
+      (entry) => entry === base || (entry.startsWith(`${base}.`) && !entry.slice(base.length + 1).includes(".")),
+    );
+  } catch {
+    return false;
+  }
+}

package/extensions/lib/store.ts

@@ -4,19 +4,22 @@
    so the tree stays hand editable and Obsidian readable with no parser dependency;
    keys this package does not own are carried through writes untouched. */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 export interface Article {
   path: string;
   capsule: string;
   updated: string;
+  /* Declared scope. "rule" means this article names a cross-cutting rule and is not
+     expected to govern an asset; empty means the address is the claim, as usual. */
+  scope: string;
   extra: string[];
   body: string;
 }
 
 const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
-const OWNED_KEYS = new Set(["capsule", "updated"]);
+const OWNED_KEYS = new Set(["capsule", "updated", "scope"]);
 
 /* Keep an address inside the tree: .. resolves against its own segments, so
    a/b/../c means a/c, and clamps at the root, so nothing ever escapes. */
@@ -30,6 +33,16 @@ function contain(path: string): string {
   return parts.join("/");
 }
 
+/* The same address with nothing dropped. Needed to tell an asset path from an address
+   that is already canonical: normalize drops one extension, so putting the article
+   address src/core/config.test back through it yields src/core/config, a different
+   article. Callers that accept an address from an agent must not canonicalise twice. */
+export function contained(path: string, cwd = ""): string {
+  let out = path.trim().replace(/\\/g, "/");
+  if (cwd && (out === cwd || out.startsWith(`${cwd}/`))) out = out.slice(cwd.length);
+  return contain(out);
+}
+
 /* An asset address: relative to the project, contained, file extension dropped so
    src/core/config.ts shares its article's address. The drop happens once, here at
    the boundary; the store itself never drops again, or config.test would lose its
@@ -91,6 +104,34 @@ function unscalar(value: string): string {
   return value;
 }
 
+/* Which collision an entry was: name.md is the first, name-2.md the second. A burst of
+   entries lands inside one millisecond and shares a stamp, so this is what actually
+   separates them, and it is the same counter that wrote the file. */
+/* One journal entry as the index carries it: name, the instant it recorded, its subjects.
+   Short keys because this file grows one line per entry forever and is never read by a
+   human; the shape is documented here instead. */
+interface JournalRow {
+  n: string;
+  a: string;
+  s: string[];
+}
+
+function sequenceOf(name: string): number {
+  return Number(/-(\d+)\.md$/.exec(name)?.[1] ?? 1);
+}
+
+/* An inline array of scalars, each optionally quoted. Splitting on every comma broke
+   any value that legitimately contained one. */
+function subjectList(raw: string): string[] {
+  const inner = raw.trim().replace(/^\[|\]$/g, "");
+  const out: string[] = [];
+  for (const match of inner.matchAll(/"((?:[^"\\]|\\.)*)"|([^,]+)/g)) {
+    const value = match[1] !== undefined ? unscalar(`"${match[1]}"`) : (match[2] ?? "").trim();
+    if (value) out.push(value);
+  }
+  return out;
+}
+
 function today(): string {
   return new Date().toISOString().slice(0, 10);
 }
@@ -99,6 +140,7 @@ function serialize(article: Article): string {
   const meta = [
     article.capsule ? `capsule: ${scalar(article.capsule)}` : "",
     `updated: ${article.updated}`,
+    article.scope ? `scope: ${scalar(article.scope)}` : "",
     ...article.extra,
   ].filter(Boolean).join("\n");
   return `---\n${meta}\n---\n${article.body.trimEnd()}\n`;
@@ -134,6 +176,7 @@ export class CanonStore {
       extra,
       capsule: typeof meta.capsule === "string" ? meta.capsule : "",
       updated: typeof meta.updated === "string" ? meta.updated : "",
+      scope: typeof meta.scope === "string" ? meta.scope : "",
     };
   }
 
@@ -163,7 +206,36 @@ export class CanonStore {
     return walk(this.articlesDir, "").sort();
   }
 
-  write(path: string, fields: { capsule?: string; body?: string }): Article {
+  /* What the store looks like right now, cheaply enough to ask every turn.
+
+     Retrieval re-reads and re-parses every article once a turn to rebuild the residue, and
+     the comment justifying that says the residue is small by construction. Measured, the
+     cost tracks the STORE and not the residue: 5,000 articles cost 242ms a turn when all of
+     them are residue and 214ms when only 50 are, because every path is read and stat-ed
+     before anything is filtered. At 20,000 articles it is 891ms, on every turn.
+
+     Statting instead of reading is 8x cheaper, 114ms against 891ms at 20,000. mtimeMs is the
+     reason this works where the obvious key does not: `updated` has day granularity, so an
+     article rewritten in the same session carries the same stamp and any cache built on it
+     serves a stale ranking for the rest of the run. Milliseconds do not have that problem,
+     and size catches a same-millisecond rewrite of a different length. */
+  signature(): string {
+    const parts: string[] = [];
+    const walk = (dir: string, prefix: string): void => {
+      if (!existsSync(dir)) return;
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) walk(join(dir, entry.name), `${prefix}${entry.name}/`);
+        else if (entry.name.endsWith(".md")) {
+          const stats = statSync(join(dir, entry.name));
+          parts.push(`${prefix}${entry.name}:${stats.mtimeMs}:${stats.size}`);
+        }
+      }
+    };
+    walk(this.articlesDir, "");
+    return parts.sort().join("|");
+  }
+
+  write(path: string, fields: { capsule?: string; body?: string; scope?: string }): Article {
     path = contain(path);
     const prior = this.read(path);
     /* Agents sometimes paste a whole file as the body, front matter included; stored
@@ -178,6 +250,7 @@ export class CanonStore {
       path,
       capsule: (fields.capsule ?? prior?.capsule ?? "").replace(/\s*\n\s*/g, " ").trim(),
       updated: today(),
+      scope: (fields.scope ?? prior?.scope ?? "").trim(),
       extra: prior?.extra ?? [],
       body,
     };
@@ -194,12 +267,24 @@ export class CanonStore {
     const slug =
       (entry.slug ?? "entry").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "") || "entry";
     mkdirSync(this.journalDir, { recursive: true });
-    const front = entry.subject?.length ? `---\nsubject: [${entry.subject.join(", ")}]\n---\n` : "";
-    const text = `${front}${entry.body.trimEnd()}\n`;
+    /* An explicit instant, because the filename cannot carry one. Entries are named by
+       date plus slug with -2, -3 for collisions, and sorting those lexicographically puts
+       -10 before -2 and the unsuffixed name after every suffixed one, so "the newest
+       three" was not the newest three (Codex, 2026-08-13). Subjects are quoted through
+       the same scalar() as everything else, so an address containing a comma survives
+       the round trip instead of splitting into two. */
+    const stamp = new Date().toISOString();
+    const front = [
+      entry.subject?.length ? `subject: [${entry.subject.map(scalar).join(", ")}]` : "",
+      `logged: ${stamp}`,
+    ].filter(Boolean).join("\n");
+    const text = `---\n${front}\n---\n${entry.body.trimEnd()}\n`;
     for (let n = 1; ; n += 1) {
-      const file = join(this.journalDir, `${today()}-${slug}${n > 1 ? `-${n}` : ""}.md`);
+      const name = `${today()}-${slug}${n > 1 ? `-${n}` : ""}.md`;
+      const file = join(this.journalDir, name);
       try {
         writeFileSync(file, text, { flag: "wx" });
+        this.note({ n: name, a: stamp, s: entry.subject ?? [] });
         return file;
       } catch (error) {
         if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
@@ -207,6 +292,59 @@ export class CanonStore {
     }
   }
 
+  /* Append the new entry to both the loaded index and the file on disk, so the count stays
+     matched and the next session loads instead of rebuilding. Appending only when the index
+     is already loaded would leave the file one row short of the directory and force a
+     rebuild every session that journals without reading. */
+  private note(row: JournalRow): void {
+    try {
+      if (existsSync(this.indexFile)) {
+        if (this.index) this.index.push(row);
+        appendFileSync(this.indexFile, JSON.stringify(row) + "\n");
+        return;
+      }
+      /* No index yet. Drop what is cached and rebuild from the directory, which already
+         holds this entry, so the file is created complete rather than one row short. */
+      this.index = undefined;
+      this.rows();
+    } catch {
+      /* Losing the append costs a rebuild next session, never a failed write. */
+    }
+  }
+
+  /* Every journal entry, with its body. Distinct from the index, which deliberately holds
+     no bodies so an article read never opens a journal file: this reads them all, and is
+     therefore only for the agent-solicited path, never the hot one. A journal entry has no
+     address, so what scopes it is its instant and the subjects it names. */
+  journalEntries(): { name: string; logged: string; subjects: string[]; body: string }[] {
+    let names: string[];
+    try {
+      names = readdirSync(this.journalDir).filter((name) => name.endsWith(".md"));
+    } catch {
+      return [];
+    }
+    const out = [];
+    for (const name of names.sort()) {
+      try {
+        const text = readFileSync(join(this.journalDir, name), "utf8");
+        /* The same two regexes CanonStore.row uses, deliberately. Journal front matter is
+           written as `subject: [a, b]`, which the generic parser does not return under
+           `meta`, so reading it a second way here would let search and the journal index
+           disagree about what an entry names. */
+        out.push({
+          name,
+          logged: /^logged:\s*(.*)$/m.exec(text)?.[1]?.trim() || name.slice(0, 10),
+          subjects: subjectList(/^subject:\s*(.*)$/m.exec(text)?.[1] ?? ""),
+          body: text.replace(/^---\n[\s\S]*?\n---\n/, ""),
+        });
+      } catch {
+        /* An unreadable entry is skipped, never fatal: search is a convenience and one
+           bad file must not make the whole journal unsearchable. */
+      }
+    }
+    return out;
+  }
+
   journalCount(): number {
     try {
       return readdirSync(this.journalDir).filter((name) => name.endsWith(".md")).length;
@@ -215,20 +353,74 @@ export class CanonStore {
     }
   }
 
-  /* Journal entries whose subject names this address: the index a read surfaces
-     so the agent can dig into event history when it wants more than current truth. */
-  journalMentions(path: string): string[] {
+  /* One row per entry: filename, the instant it recorded, the addresses it names.
+     Everything journalMentions needs, so a read never opens a journal file. */
+  private index: JournalRow[] | undefined;
+
+  private get indexFile(): string {
+    return join(this.root, ".journal-index.jsonl");
+  }
+
+  private static row(dir: string, name: string): JournalRow {
+    const text = readFileSync(join(dir, name), "utf8");
+    /* Hand written and pre-2.0 entries have no stamp; the date in the name is the
+       best available and still orders them against each other. */
+    return {
+      n: name,
+      a: /^logged:\s*(.*)$/m.exec(text)?.[1]?.trim() || name.slice(0, 10),
+      s: subjectList(/^subject:\s*(.*)$/m.exec(text)?.[1] ?? ""),
+    };
+  }
+
+  /* The index, checked against one directory listing and no file reads.
+
+     Holding the cache without checking was wrong: a second CanonStore on the same root, or
+     this one after an entry arrives from outside, answers from a snapshot that has since
+     moved. One readdir per call is the cheap validation, and it is still the whole point,
+     because what this replaced read every entry on every article read.
+
+     What a count cannot see is an entry whose subject line is edited in place: the count
+     matches and the stale row stands. That is the deliberate trade. Catching it means
+     opening every entry, which is the scan this exists to remove, and the cost of being
+     wrong is one filename missing from a hint list that only invites digging. */
+  private rows(): JournalRow[] {
+    const count = this.journalCount();
+    if (this.index && this.index.length === count) return this.index;
+    let loaded: JournalRow[] | undefined;
     try {
-      return readdirSync(this.journalDir)
-        .filter((name) => {
-          if (!name.endsWith(".md")) return false;
-          const subject = /^subject:\s*(.*)$/m.exec(readFileSync(join(this.journalDir, name), "utf8"))?.[1] ?? "";
-          return subject.replace(/^\[|\]$/g, "").split(",").some((s) => s.trim() === path);
-        })
-        .sort();
+      loaded = readFileSync(this.indexFile, "utf8")
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => JSON.parse(line) as JournalRow);
     } catch {
-      return [];
+      loaded = undefined;
     }
+    if (loaded && loaded.length === count) return (this.index = loaded);
+    let rebuilt: JournalRow[] = [];
+    try {
+      rebuilt = readdirSync(this.journalDir)
+        .filter((name) => name.endsWith(".md"))
+        .map((name) => CanonStore.row(this.journalDir, name));
+    } catch {
+      return (this.index = []);
+    }
+    try {
+      mkdirSync(this.root, { recursive: true });
+      writeFileSync(this.indexFile, rebuilt.map((r) => JSON.stringify(r)).join("\n") + "\n");
+    } catch {
+      /* An unwritable index costs a rebuild next session, never a failed read. */
+    }
+    return (this.index = rebuilt);
+  }
+
+  /* Journal entries whose subject names this address: the index a read surfaces
+     so the agent can dig into event history when it wants more than current truth. */
+  /* Oldest first, by the instant the entry recorded rather than by its filename. */
+  journalMentions(path: string): string[] {
+    return this.rows()
+      .filter((row) => row.s.includes(path))
+      .sort((a, b) => (a.a === b.a ? sequenceOf(a.n) - sequenceOf(b.n) : a.a.localeCompare(b.a)))
+      .map((row) => row.n);
   }
 
   map(under = ""): string {