pi-canon 0.2.3 → 0.3.0

package/extensions/lib/tool.ts

@@ -3,7 +3,8 @@
 
 import { existsSync } from "node:fs";
 import { basename, join } from "node:path";
-import { advise, unretained } from "./lint.ts";
+import { advise, orphaned, unretained } from "./lint.ts";
+import { checkArticle, loadSchema, outgoingOf, READ_ONLY, SCHEMA_FILE } from "./schema.ts";
 import { contained, normalize, type CanonStore } from "./store.ts";
 import { type Candidate, LexicalRetriever, RULE_SCOPE } from "./retrieval.ts";
 import type { Mount, Surfacer } from "./surfacing.ts";
@@ -14,6 +15,64 @@ export interface CanonRuntime {
   cwd: string;
   mounts: Mount[];
   retrieval: string;
+  provenance?: { harness: string; sessionId?: string };
+}
+
+export const CANON_TOOL_PARAMETERS = {
+  type: "object",
+  properties: {
+    action: { type: "string", enum: ["read", "write", "journal", "map", "search"] },
+    path: {
+      type: "string",
+      description: "Article address, e.g. src/core/config. Required for read and write; optional filter for map.",
+    },
+    body: {
+      type: "string",
+      description:
+        "write: the full article body; specifics beat summaries (who consumes what, exact " +
+        "limits, what breaks). journal: the event text, source details intact.",
+    },
+    capsule: { type: "string", description: "write: one dense line injected when the asset is touched." },
+    query: { type: "string", description: "search: words to look for, across articles and the journal." },
+    journal: {
+      type: "boolean",
+      description:
+        "search: true to include journal entries in the results. Off by default because " +
+        "events are history, not current truth; the result names how many entries matched " +
+        "so you can opt in when the history is the point.",
+    },
+    scope: {
+      type: "string",
+      enum: ["rule", "asset"],
+      description:
+        "write: 'rule' when this article names a cross-cutting rule instead of governing an " +
+        "asset, so it is a rule on purpose rather than an article whose asset went missing; " +
+        "'asset' to take that back, when the article governs an asset after all.",
+    },
+    subject: {
+      type: "array",
+      items: { type: "string" },
+      description: "journal: article addresses this event concerns.",
+    },
+    slug: { type: "string", description: "journal: short name for the entry file." },
+  },
+  required: ["action"],
+} as const;
+
+export function canonToolDescription(retrieval = "none"): string {
+  return (
+    "Canonical project memory. Every asset has at most one governing article at its own address " +
+    "(src/core/config, lake/prices). read the governing article before working on an asset; " +
+    "write it after real changes. journal appends an immutable event entry: record the source " +
+    "as it happened, names and exact numbers included, because articles distill and only the " +
+    "journal keeps the original, so distil the prose but carry exact values through verbatim: " +
+    "ids, keys, names, counts, limits and durations, every member of a named set and not " +
+    "just the one you are working on. A rule without its values is worth nothing to the " +
+    "session that needs it. map lists articles with their capsules. " +
+    "Creation is rare: prefer updating the article that already governs. " +
+    "File a constraint at the asset it governs, or the shared parent when it spans assets, not " +
+    "the asset you happened to edit. " + filingTail(retrieval)
+  );
 }
 
 /* A path routes to the mount it names (lake:prices), the mount whose directory
@@ -50,51 +109,8 @@ export function buildCanonTool(ready: (ctx: unknown) => CanonRuntime, retrieval
   return {
     name: "pi_canon",
     label: "pi-canon",
-    description:
-      "Canonical project memory. Every asset has at most one governing article at its own address " +
-      "(src/core/config, lake/prices). read the governing article before working on an asset; " +
-      "write it after real changes. journal appends an immutable event entry: record the source " +
-      "as it happened, names and exact numbers included, because articles distill and only the " +
-      "journal keeps the original, so distil the prose but carry exact values through verbatim: " +
-      "ids, keys, names, counts, limits and durations, every member of a named set and not " +
-      "just the one you are working on. A rule without its values is worth nothing to the " +
-      "session that needs it. map lists articles with their capsules. " +
-      "Creation is rare: prefer updating the article that already governs. " +
-      "File a constraint at the asset it governs, or the shared parent when it spans assets, not " +
-      "the asset you happened to edit. " + filingTail(retrieval),
-    parameters: {
-      type: "object",
-      properties: {
-        action: { type: "string", enum: ["read", "write", "journal", "map", "search"] },
-        path: {
-          type: "string",
-          description: "Article address, e.g. src/core/config. Required for read and write; optional filter for map.",
-        },
-        body: {
-          type: "string",
-          description:
-            "write: the full article body; specifics beat summaries (who consumes what, exact " +
-            "limits, what breaks). journal: the event text, source details intact.",
-        },
-        capsule: { type: "string", description: "write: one dense line injected when the asset is touched." },
-        query: { type: "string", description: "search: words to look for, across articles and the journal." },
-        scope: {
-          type: "string",
-          enum: ["rule", "asset"],
-          description:
-            "write: 'rule' when this article names a cross-cutting rule instead of governing an " +
-            "asset, so it is a rule on purpose rather than an article whose asset went missing; " +
-            "'asset' to take that back, when the article governs an asset after all.",
-        },
-        subject: {
-          type: "array",
-          items: { type: "string" },
-          description: "journal: article addresses this event concerns.",
-        },
-        slug: { type: "string", description: "journal: short name for the entry file." },
-      },
-      required: ["action"],
-    },
+    description: canonToolDescription(retrieval),
+    parameters: CANON_TOOL_PARAMETERS,
     async execute(
       _toolCallId: string,
       params: Record<string, unknown>,
@@ -102,7 +118,7 @@ export function buildCanonTool(ready: (ctx: unknown) => CanonRuntime, retrieval
       _onUpdate: unknown,
       ctx: unknown,
     ) {
-      const text = run(ready(ctx), params);
+      const text = runCanon(ready(ctx), params);
       return { content: [{ type: "text", text }], details: {} };
     },
   };
@@ -148,10 +164,19 @@ function filingTail(retrieval: string): string {
    named. Neither is decoration.
 
    Ranking reuses LexicalRetriever rather than growing a second notion of relevance, so search
-   and recommendation cannot drift apart. */
+   and recommendation cannot drift apart.
+
+   The journal is opt-in (Shane, 2026-08-20): events are history, not current truth,
+   and R1 measured what including them by default cost, journal entries about an
+   event crowding out the article that carries its current truth for 8 to 20 points
+   of governing-article recall at realistic query lengths. Default search ranks
+   articles alone, never reads a journal body, and says the journal exists; with
+   journal true the window is split, articles up to half, journal the rest,
+   whichever side runs short ceding its slots. Current truth first, always. */
 const SEARCH_RESULTS = 10;
+const ARTICLE_SLOTS = 5;
 
-function search(store: CanonStore, query: string): string {
+function search(store: CanonStore, query: string, includeJournal: boolean): string {
   if (!query.trim()) return "search needs a query.";
   const articles: Candidate[] = [];
   for (const path of store.list()) {
@@ -167,20 +192,26 @@ function search(store: CanonStore, query: string): string {
     }
   }
   /* Journal entries enter the same index under a `journal/` key so one ranking covers both.
-     The key is an index handle, never an address: it is not something `read` accepts. */
-  const entries = store.journalEntries();
+     The key is an index handle, never an address: it is not something `read` accepts.
+     Built only on opt-in, so a default search never pays for reading every entry body. */
   const byKey = new Map<string, { logged: string; subjects: string[]; body: string }>();
-  const journal: Candidate[] = entries.map((entry) => {
-    const key = `journal/${entry.name.replace(/\.md$/, "")}`;
-    byKey.set(key, entry);
-    return {
-      path: key,
-      capsule: entry.subjects.join(", "),
-      body: entry.body,
-      updated: entry.logged,
-      declared: false,
-    };
-  });
+  const journal: Candidate[] = !includeJournal
+    ? []
+    : store.journalEntries().map((entry) => {
+        const key = `journal/${entry.name.replace(/\.md$/, "")}`;
+        byKey.set(key, entry);
+        return {
+          path: key,
+          capsule: entry.subjects.join(", "),
+          body: entry.body,
+          updated: entry.logged,
+          declared: false,
+        };
+      });
+  const invitation =
+    !includeJournal && store.journalCount() > 0
+      ? "The journal was not searched; pass journal true to search events too."
+      : "";
 
   const all = [...articles, ...journal];
   if (!all.length) return "Nothing in the canon yet.";
@@ -188,9 +219,18 @@ function search(store: CanonStore, query: string): string {
   retriever.index(all);
   const scored = retriever.score(query, all);
   const ranked = [...scored.entries()].sort((a, b) => b[1] - a[1]);
-  if (!ranked.length) return `Nothing matches "${query}".`;
+  if (!ranked.length) return [`Nothing matches "${query}".`, invitation].filter(Boolean).join(" ");
+
+  const articleRanked = ranked.filter(([key]) => !byKey.has(key));
+  const journalRanked = ranked.filter(([key]) => byKey.has(key));
+  const articleQuota = Math.min(
+    articleRanked.length,
+    Math.max(ARTICLE_SLOTS, SEARCH_RESULTS - journalRanked.length),
+  );
+  const journalQuota = Math.min(journalRanked.length, SEARCH_RESULTS - articleQuota);
+  const chosen = [...articleRanked.slice(0, articleQuota), ...journalRanked.slice(0, journalQuota)];
 
-  const lines = ranked.slice(0, SEARCH_RESULTS).map(([key]) => {
+  const lines = chosen.map(([key]) => {
     const entry = byKey.get(key);
     if (entry) {
       const subjects = entry.subjects.length ? ` (${entry.subjects.join(", ")})` : "";
@@ -200,9 +240,10 @@ function search(store: CanonStore, query: string): string {
     return `${key}: ${article?.capsule || excerpt(article?.body ?? "")}`;
   });
   /* Say what was dropped. A silent cap reads as "that is everything". */
-  if (ranked.length > SEARCH_RESULTS) {
-    lines.push(`... ${ranked.length - SEARCH_RESULTS} more matched; narrow the query to see them.`);
+  if (ranked.length > chosen.length) {
+    lines.push(`... ${ranked.length - chosen.length} more matched; narrow the query to see them.`);
   }
+  if (invitation) lines.push(invitation);
   return lines.join("\n");
 }
 
@@ -211,7 +252,7 @@ function excerpt(body: string): string {
   return flat.length > 160 ? `${flat.slice(0, 157)}...` : flat;
 }
 
-function run(runtime: CanonRuntime, params: Record<string, unknown>): string {
+export function runCanon(runtime: CanonRuntime, params: Record<string, unknown>): string {
   const { surfacer } = runtime;
   const action = String(params.action ?? "");
   const { mount, path } = typeof params.path === "string" ? route(runtime, params.path) : { mount: runtime.mounts[0], path: "" };
@@ -245,7 +286,18 @@ function run(runtime: CanonRuntime, params: Record<string, unknown>): string {
       const index = recent.length
         ? `\n\njournal: ${recent.join(", ")}${earlier ? ` and ${earlier} earlier` : ""}`
         : "";
-      return `${title}\n${head}\n\n${article.body}`.trim() + index;
+      /* Reads never reject, but they do report: an agent holding a noncompliant
+         article is the one agent positioned to heal it, and silence here is how a
+         store drifts out of its own contract one read at a time. */
+      const { schema, problems } = loadSchema(store.root);
+      const standing = schema ? checkArticle(article, schema, READ_ONLY) : { rejections: [], warnings: [] };
+      const issues = [...standing.warnings, ...problems];
+      const report = issues.length
+        ? `\n\nschema (${SCHEMA_FILE}): ${issues.join(" ")} This article can be healed with a write.`
+        : "";
+      const missing = orphaned(mount.dir, article);
+      const orphan = missing ? `\n\n${missing}` : "";
+      return `${title}\n${head}\n\n${article.body}`.trim() + index + report + orphan;
     }
     case "write": {
       if (!path) return "write needs a path.";
@@ -258,7 +310,7 @@ function run(runtime: CanonRuntime, params: Record<string, unknown>): string {
          prior state; which fields this call happened to set is a separate question and is
          answered separately below. */
       const prior = store.read(path);
-      const article = store.write(path, {
+      const fields = {
         capsule: params.capsule ? String(params.capsule) : undefined,
         body: params.body ? String(params.body) : undefined,
         /* "asset" is the way back. The enum is the only vocabulary the model has, so
@@ -266,16 +318,93 @@ function run(runtime: CanonRuntime, params: Record<string, unknown>): string {
            one: every other input falls through to undefined, which means untouched. It
            stores empty, which is the default state, the address being the claim. */
         scope: params.scope === "asset" ? "" : params.scope ? String(params.scope) : undefined,
-      });
+      };
+      /* The store's declared contract, held against the article this write WOULD
+         store, before anything touches disk. Only a required rule the write itself
+         touched (or a brand new article) rejects; everything else warns, so the write
+         still lands and the agent still learns. */
+      const { schema, problems } = loadSchema(store.root);
+      const composed = store.compose(path, fields);
+      const verdict = schema
+        ? checkArticle(composed, schema, {
+            capsule: fields.capsule !== undefined,
+            body: fields.body !== undefined,
+            /* Touched means the reference SET changed, not that a body was sent: a
+               body edit that keeps its citations must not re-litigate them. */
+            refs: outgoingOf(prior ? prior.body : "").join("\n") !== outgoingOf(composed.body).join("\n"),
+            created: !prior,
+          })
+        : { rejections: [], warnings: [] };
+      if (verdict.rejections.length) {
+        return [
+          `Write rejected by this store's ${SCHEMA_FILE}:`,
+          ...verdict.rejections.map((line) => `- ${line}`),
+          "Nothing was written. Fix the listed fields and write again.",
+        ].join("\n");
+      }
+      /* A write that changes nothing is a restatement, not a change. Measured (W1j):
+         restating the current state through the write path was the one store
+         corruption no content rule could catch, because no field differs; the only
+         thing it changed was the freshness stamp, which then lied. So equality is
+         checked here, mechanically, and `updated` keeps meaning what it says. */
+      if (
+        prior &&
+        composed.capsule === prior.capsule &&
+        composed.scope === prior.scope &&
+        composed.body.trimEnd() === prior.body.trimEnd()
+      ) {
+        surfacer.markUpdated(
+          qualify(composed.path),
+          [params.capsule, params.body].filter(Boolean).map(String).join("\n"),
+        );
+        return [
+          `${qualify(composed.path)} is already current: this write matches the stored article, ` +
+            `so nothing was rewritten and updated stays ${prior.updated}.`,
+          ...verdict.warnings.map((line) => `schema: ${line}`),
+          ...problems,
+        ].join("\n");
+      }
+      const article = store.write(path, fields);
+      /* When a rewrite grows the body, the result says so and restates the split.
+         Measured over three captures, two arms each, on byte-identical
+         eight-session lineages: writers narrate history into articles until the
+         store outgrows the raw transcripts it distills, and prompt-side guidance
+         does not change the habit. The arm that got this line ended with fewer
+         standing superseded values in all three, 51 and 45 and 71 of 96 against
+         88 and 87 and 85. Take the DIRECTION and not the size. The third capture
+         counterbalanced the arm order and kept the direction while losing most of
+         the magnitude, and re-running a matched untreated cell moved its median
+         store 39 percent, so this instrument does not measure its own magnitudes
+         reliably. Two readers in 96 sessions were harmed by a stale value, one
+         from each arm, so this line is not known to protect readers. It is also
+         not one exposure: it fired after 117, 99, and 126 of that arm's 198, 184,
+         and 207 writes. Any growth fires; that exact behavior is what was
+         measured. Creation is not growth, and a capsule-only write never grows
+         the stored body. */
+      const priorBytes = prior ? Buffer.byteLength(prior.body.trimEnd()) : null;
+      const nextBytes = Buffer.byteLength(composed.body.trimEnd());
+      const growth =
+        priorBytes !== null && nextBytes > priorBytes
+          ? [
+              `Body grew ${priorBytes} -> ${nextBytes} bytes. An article carries current ` +
+                `state; if this growth is narrated history (old values, transitions), move ` +
+                `it to the journal and keep the article at what is true now.`,
+            ]
+          : [];
       /* What this write put in the window, which is what the agent supplied, not the
          merged article: a capsule-only write does not deliver the stored body. */
       surfacer.markUpdated(
         qualify(article.path),
         [params.capsule, params.body].filter(Boolean).map(String).join("\n"),
       );
+      const missingAsset = orphaned(mount.dir, article);
       return [
         `Wrote ${qualify(article.path)}.`,
-        ...advise(article, store, prior?.body, { dir: mount.dir, retrieval: runtime.retrieval }),
+        ...growth,
+        ...verdict.warnings.map((line) => `schema: ${line}`),
+        ...problems,
+        ...advise(article, store, prior?.body, { dir: mount.dir, retrieval: runtime.retrieval }, schema),
+        ...(missingAsset ? [missingAsset] : []),
       ].join("\n");
     }
     case "journal": {
@@ -293,6 +422,7 @@ function run(runtime: CanonRuntime, params: Record<string, unknown>): string {
         body,
         subject,
         slug: typeof params.slug === "string" ? params.slug : undefined,
+        provenance: runtime.provenance,
       });
       /* The article was written before this entry (agents write then journal), so this
          is the first moment both exist. Report what the source kept and the article did
@@ -321,7 +451,7 @@ function run(runtime: CanonRuntime, params: Record<string, unknown>): string {
     case "map":
       return store.map(path);
     case "search":
-      return search(store, String(params.query ?? ""));
+      return search(store, String(params.query ?? ""), params.journal === true);
     default:
       return `Unknown action "${action}". Actions: read, write, journal, map, search.`;
   }