pi-canon 0.2.4 → 0.3.0

package/extensions/lib/schema.ts

@@ -0,0 +1,251 @@
+/* Per-store article schema: schema.json at the store root, a data contract rather
+   than buried code. The file is created with these defaults made explicit the first
+   time the store persists anything, so its owner can see it, edit it per project,
+   and point other tools at the same contract this package enforces.
+
+   Enforcement is asymmetric on purpose. A rule marked required rejects the write
+   that violates it, because a missing required field is exactly the class of miss
+   that soft advice has demonstrably failed to prevent; every other rule warns, on
+   write and on read, so an agent reading a noncompliant article learns it can heal
+   what it is holding. A required violation the current write did not touch also
+   only warns: a capsule-only update must not be held hostage to a legacy body. */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Article } from "./store.ts";
+
+export const SCHEMA_FILE = "schema.json";
+export const SCHEMA_VERSION = 1;
+
+export interface SchemaRule {
+  required?: boolean;
+  min_chars?: number;
+  max_chars?: number;
+  hint?: string;
+}
+
+/* Relations rules are about the reference graph, not any one field. The store
+   declares them once here; each tool enforces the ones it can see. This package
+   sees an article's own outgoing [[references]] at the write boundary, so it
+   enforces refs; orphan and children need the whole graph and are enforced by
+   graph-reading tools (canon-atlas) from this same file. */
+export interface RefsRule {
+  required?: boolean;
+  min_count?: number;
+  hint?: string;
+}
+export interface OrphanRule {
+  warn?: boolean;
+  hint?: string;
+}
+export interface ChildrenRule {
+  listed?: boolean;
+  hint?: string;
+}
+export interface CanonRelations {
+  refs?: RefsRule;
+  orphan?: OrphanRule;
+  children?: ChildrenRule;
+}
+
+export interface CanonSchema {
+  capsule?: SchemaRule;
+  title?: SchemaRule;
+  body?: SchemaRule;
+  relations?: CanonRelations;
+}
+
+const FIELD_NAMES = ["capsule", "title", "body"] as const;
+const RULE_KEYS = new Set(["required", "min_chars", "max_chars", "hint"]);
+const RELATION_KEYS: Record<string, Set<string>> = {
+  refs: new Set(["required", "min_count", "hint"]),
+  orphan: new Set(["warn", "hint"]),
+  children: new Set(["listed", "hint"]),
+};
+
+/* The shipped defaults, written into the file verbatim. Nothing is required and the
+   caps mirror what the advisory lint has always said, so a store that never edits
+   this file behaves as it always did, just with the contract visible on disk. */
+const DEFAULT_FILE = `{
+  "schema_version": 1,
+  "about": "Article schema for this canon store. pi-canon enforces it at the tool boundary: a rule marked required rejects a write that violates it (judged on what the write touches, and on everything when the article is first created); every other rule warns on write and is reported on read, so agents can heal what they are holding. Other tools reading this store can enforce the same contract from this file. Fields: capsule (the front matter line surfaced on touch), title (the body's leading # heading), body. Rule keys: required, min_chars, max_chars, hint. Relations rules live under relations: refs (required, min_count) over an article's own outgoing references, orphan (warn) and children (listed) over the whole graph; each tool enforces the rules it can see, so refs holds here and the graph rules hold in graph-reading tools like canon-atlas. Delete a rule to drop it; delete this file to disable schema checks.",
+  "article": {
+    "capsule": { "required": false, "max_chars": 1000, "hint": "One dense line of current truth; surfacing injects it when the asset is touched." },
+    "title": { "required": false, "hint": "Start the body with a # heading naming the asset." },
+    "body": { "max_chars": 20000, "hint": "Past this, go hierarchical: keep this article as the summary and router, and move detail into children at addresses under it." }
+  },
+  "relations": {
+    "refs": { "required": false, "hint": "Outgoing [[references]] authored by this article. required rejects a write whose body cites nothing; min_count warns under a floor." },
+    "orphan": { "warn": false, "hint": "Warn when no other article references this one. Needs the whole graph, so graph-reading tools enforce it." },
+    "children": { "listed": false, "hint": "Warn when an article does not reference each direct child under its address. Enforced by graph-reading tools." }
+  }
+}
+`;
+
+/* Created only when absent, so an edited or deleted file is never fought over. */
+export function ensureSchemaFile(root: string): void {
+  try {
+    writeFileSync(join(root, SCHEMA_FILE), DEFAULT_FILE, { flag: "wx" });
+  } catch {
+    /* Exists already, or the root is unwritable; either way not this call's problem. */
+  }
+}
+
+/* The schema as declared, plus every problem with the declaration itself. A malformed
+   file fails open and loud: rules stop being enforced, and the caller says so, because
+   a schema the owner believes is enforced while a typo disabled it is the worst state. */
+export function loadSchema(root: string): { schema: CanonSchema | undefined; problems: string[] } {
+  const file = join(root, SCHEMA_FILE);
+  if (!existsSync(file)) return { schema: undefined, problems: [] };
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(file, "utf8"));
+  } catch (error) {
+    return {
+      schema: undefined,
+      problems: [`${SCHEMA_FILE} is not valid JSON (${(error as Error).message}); its rules are not being enforced.`],
+    };
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { schema: undefined, problems: [`${SCHEMA_FILE} must hold a JSON object; its rules are not being enforced.`] };
+  }
+  const problems: string[] = [];
+  /* A missing article block is an empty one, not an early exit: a schema may
+     carry only relations rules. */
+  const declared = (raw as Record<string, unknown>).article ?? {};
+  if (typeof declared !== "object" || declared === null || Array.isArray(declared)) {
+    return { schema: undefined, problems: [`${SCHEMA_FILE}: "article" must be an object; its rules are not being enforced.`] };
+  }
+  const schema: CanonSchema = {};
+  for (const [name, value] of Object.entries(declared as Record<string, unknown>)) {
+    if (!(FIELD_NAMES as readonly string[]).includes(name)) {
+      problems.push(`${SCHEMA_FILE}: unknown article field "${name}" is ignored (fields: ${FIELD_NAMES.join(", ")}).`);
+      continue;
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      problems.push(`${SCHEMA_FILE}: rule for "${name}" must be an object and is ignored.`);
+      continue;
+    }
+    const rule: SchemaRule = {};
+    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+      if (!RULE_KEYS.has(key)) {
+        problems.push(`${SCHEMA_FILE}: unknown rule key "${name}.${key}" is ignored (keys: required, min_chars, max_chars, hint).`);
+      } else if (key === "required" && typeof val === "boolean") rule.required = val;
+      else if ((key === "min_chars" || key === "max_chars") && typeof val === "number" && Number.isInteger(val) && val >= 0) rule[key] = val;
+      else if (key === "hint" && typeof val === "string") rule.hint = val;
+      else problems.push(`${SCHEMA_FILE}: "${name}.${key}" has the wrong type and is ignored.`);
+    }
+    schema[name as "capsule" | "title" | "body"] = rule;
+  }
+  const rel = (raw as Record<string, unknown>).relations;
+  if (rel !== undefined) {
+    if (typeof rel !== "object" || rel === null || Array.isArray(rel)) {
+      problems.push(`${SCHEMA_FILE}: "relations" must be an object and is ignored.`);
+    } else {
+      const relations: CanonRelations = {};
+      for (const [name, value] of Object.entries(rel as Record<string, unknown>)) {
+        const keys = RELATION_KEYS[name];
+        if (!keys) {
+          problems.push(`${SCHEMA_FILE}: unknown relations field "${name}" is ignored (fields: refs, orphan, children).`);
+          continue;
+        }
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+          problems.push(`${SCHEMA_FILE}: rule for "relations.${name}" must be an object and is ignored.`);
+          continue;
+        }
+        const rule: Record<string, boolean | number | string> = {};
+        for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+          if (!keys.has(key)) {
+            problems.push(`${SCHEMA_FILE}: unknown rule key "relations.${name}.${key}" is ignored (keys: ${[...keys].join(", ")}).`);
+          } else if ((key === "required" || key === "warn" || key === "listed") && typeof val === "boolean") rule[key] = val;
+          else if (key === "min_count" && typeof val === "number" && Number.isInteger(val) && val >= 0) rule[key] = val;
+          else if (key === "hint" && typeof val === "string") rule[key] = val;
+          else problems.push(`${SCHEMA_FILE}: "relations.${name}.${key}" has the wrong type and is ignored.`);
+        }
+        relations[name as keyof CanonRelations] = rule;
+      }
+      schema.relations = relations;
+    }
+  }
+  return { schema, problems };
+}
+
+/* The outgoing references an article authors: [[wikilink]] targets in the body,
+   fenced and inline code stripped (examples are not citations), deduplicated
+   case-insensitively. The write boundary can always see these, whatever else it
+   cannot see of the graph. */
+export function outgoingOf(body: string): string[] {
+  const stripped = body.replace(/```[\s\S]*?```/g, "").replace(/`[^`\n]*`/g, "");
+  const out = new Set<string>();
+  for (const m of stripped.matchAll(/\[\[([^\]|#\n]+)(?:[|#][^\]\n]*)?\]\]/g)) {
+    const target = m[1].trim().toLowerCase();
+    if (target) out.add(target);
+  }
+  return [...out].sort();
+}
+
+/* The title is the body's leading # heading; the write interface has no separate
+   title field on purpose, so the rule checks the one place a title can live. */
+export function titleOf(body: string): string | undefined {
+  const first = body.split(/\r?\n/).find((line) => line.trim() !== "");
+  const heading = first === undefined ? undefined : /^#\s+(.+)$/.exec(first.trim());
+  return heading ? heading[1].trim() : undefined;
+}
+
+export interface Touched {
+  capsule: boolean;
+  body: boolean;
+  refs: boolean;
+  created: boolean;
+}
+
+/* No write in flight: every violation is reportable but none can reject. */
+export const READ_ONLY: Touched = { capsule: false, body: false, refs: false, created: false };
+
+export interface Verdict {
+  rejections: string[];
+  warnings: string[];
+}
+
+export function checkArticle(article: Article, schema: CanonSchema, touched: Touched): Verdict {
+  const verdict: Verdict = { rejections: [], warnings: [] };
+  const fields: { name: keyof CanonSchema; value: string | undefined; missing: string; carrier: "capsule" | "body" }[] = [
+    { name: "capsule", value: article.capsule || undefined, missing: "required and empty", carrier: "capsule" },
+    { name: "title", value: titleOf(article.body), missing: "required and the body has no leading # heading", carrier: "body" },
+    { name: "body", value: article.body || undefined, missing: "required and empty", carrier: "body" },
+  ];
+  for (const field of fields) {
+    const rule = schema[field.name];
+    if (!rule) continue;
+    const hint = rule.hint ? ` ${rule.hint}` : "";
+    if (rule.required && field.value === undefined) {
+      const message = `${field.name}: ${field.missing}.${hint}`;
+      if (touched.created || touched[field.carrier]) verdict.rejections.push(message);
+      else verdict.warnings.push(message);
+      continue;
+    }
+    if (field.value === undefined) continue;
+    if (rule.min_chars !== undefined && field.value.length < rule.min_chars) {
+      verdict.warnings.push(`${field.name}: ${field.value.length} chars (min ${rule.min_chars}).${hint}`);
+    }
+    if (rule.max_chars !== undefined && field.value.length > rule.max_chars) {
+      verdict.warnings.push(`${field.name}: ${field.value.length} chars (max ${rule.max_chars}).${hint}`);
+    }
+  }
+  /* The one relations rule this boundary can see whole: the article's own
+     citations. required follows the same asymmetry as the fields, rejecting only
+     the write that changed the reference set or created the article. */
+  const refsRule = schema.relations && schema.relations.refs;
+  if (refsRule) {
+    const cited = outgoingOf(article.body).length;
+    const hint = refsRule.hint ? ` ${refsRule.hint}` : "";
+    if (refsRule.required && cited === 0) {
+      const message = `refs: required and the body references nothing.${hint}`;
+      if (touched.created || touched.refs) verdict.rejections.push(message);
+      else verdict.warnings.push(message);
+    } else if (refsRule.min_count !== undefined && cited < refsRule.min_count) {
+      verdict.warnings.push(`refs: ${cited} outgoing (min ${refsRule.min_count}).${hint}`);
+    }
+  }
+  return verdict;
+}

package/extensions/lib/store.ts

@@ -6,6 +6,7 @@
 
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { ensureSchemaFile } from "./schema.ts";
 
 export interface Article {
   path: string;
@@ -235,7 +236,10 @@ export class CanonStore {
     return parts.sort().join("|");
   }
 
-  write(path: string, fields: { capsule?: string; body?: string; scope?: string }): Article {
+  /* The article this write would store, without storing it. Public so the tool can
+     hold a would-be article against the store's schema and reject before anything
+     touches disk; write() persists exactly what compose() returns. */
+  compose(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
@@ -246,7 +250,7 @@ export class CanonStore {
     if (block && block[1].split(/\r?\n/).every((line) => /^[\w-]+:\s|^\s*$/.test(line))) {
       body = body.slice(block[0].length).trimStart();
     }
-    const article: Article = {
+    return {
       path,
       capsule: (fields.capsule ?? prior?.capsule ?? "").replace(/\s*\n\s*/g, " ").trim(),
       updated: today(),
@@ -254,8 +258,13 @@ export class CanonStore {
       extra: prior?.extra ?? [],
       body,
     };
-    const file = this.fileFor(path);
+  }
+
+  write(path: string, fields: { capsule?: string; body?: string; scope?: string }): Article {
+    const article = this.compose(path, fields);
+    const file = this.fileFor(article.path);
     mkdirSync(dirname(file), { recursive: true });
+    ensureSchemaFile(this.root);
     writeFileSync(file, serialize(article));
     return article;
   }
@@ -272,6 +281,7 @@ export class CanonStore {
     const slug =
       (entry.slug ?? "entry").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "") || "entry";
     mkdirSync(this.journalDir, { recursive: true });
+    ensureSchemaFile(this.root);
     /* 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

package/extensions/lib/surfacing.ts

@@ -30,6 +30,52 @@ function trace(kind: string, data: Record<string, unknown>): void {
 
 const PATHLIKE = /(?:^|[\s"'`=:,([{])(\/?[\w.@-]+(?:\/[\w.@-]+)+)/g;
 
+/* A touch says what knowledge should surface. It does not by itself say that current
+   truth changed. The write-after reminder needs positive evidence of a modifying tool,
+   otherwise Read, Grep, and inspection-only shell calls turn an optional maintenance
+   prompt into a false stop. This list stays deliberately small: an unknown tool may
+   surface an article, but it cannot create an update obligation merely by naming a path. */
+const MUTATING_TOOL_SUFFIXES = [
+  "applypatch",
+  "write",
+  "writefile",
+  "edit",
+  "editfile",
+  "multiedit",
+  "notebookedit",
+  "createfile",
+  "deletefile",
+  "movefile",
+  "renamefile",
+  "replaceinfile",
+  "strreplaceeditor",
+];
+
+const SHELL_TOOL_SUFFIXES = ["bash", "shell", "exec", "execcommand", "runcommand", "terminal"];
+
+function stringsIn(value: unknown): string[] {
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value)) return value.flatMap(stringsIn);
+  if (!value || typeof value !== "object") return [];
+  return Object.values(value).flatMap(stringsIn);
+}
+
+export function changesAssets(toolName: unknown, input: unknown): boolean {
+  if (typeof toolName !== "string" || !toolName) return false;
+  const compact = toolName.toLowerCase().replace(/[^a-z0-9]+/g, "");
+  if (MUTATING_TOOL_SUFFIXES.some((suffix) => compact.endsWith(suffix))) return true;
+  if (!SHELL_TOOL_SUFFIXES.some((suffix) => compact.endsWith(suffix))) return false;
+
+  const command = stringsIn(input).join("\n");
+  if (/\btools\.apply_patch\s*\(/.test(command)) return true;
+  if (/(?:^|[\n;&|]\s*)(?:sudo\s+)?(?:[\w.-]+\/)*(?:apply_patch|cp|mv|rm|mkdir|rmdir|touch|chmod|chown|ln|install|truncate|dd|patch)\b/m.test(command)) {
+    return true;
+  }
+  if (/\bsed\s+(?:-[a-z]*i[a-z]*\b|--in-place(?:=|\b))/i.test(command)) return true;
+  if (/\bperl\s+-[a-z]*pi[a-z]*\b/i.test(command)) return true;
+  return /\bgit\s+(?:apply|checkout|restore|reset|clean|mv|rm)\b/.test(command);
+}
+
 /* Presence marks -----------------------------------------------------------------
 
    "Seen" used to mean "we sent it once", which is only the same thing as "the agent
@@ -510,6 +556,18 @@ export class Surfacer {
     }
   }
 
+  /* Record a successful modifying call separately from a touch. A read still stages the
+     governing article, but it creates no update obligation. */
+  markChanged(assets: string[]): void {
+    for (const asset of assets) {
+      const { mount, absolute } = this.locate(asset);
+      const article = mount.store.resolve(absolute, mount.dir);
+      if (!article) continue;
+      const key = mount.name ? `${mount.name}:${article.path}` : article.path;
+      this.pendingUpdates.add(key);
+    }
+  }
+
   /* Stage each newly touched governing article. Nothing is sent or spent here. */
   collect(assets: string[]): void {
     for (const asset of assets) {
@@ -517,7 +575,6 @@ export class Surfacer {
       const article = mount.store.resolve(absolute, mount.dir);
       if (!article) continue;
       const key = mount.name ? `${mount.name}:${article.path}` : article.path;
-      this.pendingUpdates.add(key);
       if (this.seen.has(key) || this.staged.has(key)) continue;
       const stamp = article.updated ? ` (updated ${article.updated})` : "";
       this.staged.set(key, { capsule: article.capsule, stamp, asset });
@@ -607,8 +664,8 @@ export class Surfacer {
     trace("delivery-undone", {});
   }
 
-  /* The write-after half of the doctrine: every governing article touched since its
-     last update draws one reminder, then the slate clears for the next batch. */
+  /* The write-after half of the doctrine: every governing article named by a successful
+     modifying call since its last update draws one reminder, then the slate clears. */
   settleNudge(): string | undefined {
     const stale = [...this.pendingUpdates];
     this.lastNudge = stale;

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";
@@ -33,6 +34,13 @@ export const CANON_TOOL_PARAMETERS = {
     },
     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"],
@@ -156,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()) {
@@ -175,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.";
@@ -196,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(", ")})` : "";
@@ -208,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");
 }
 
@@ -253,7 +286,18 @@ export function runCanon(runtime: CanonRuntime, params: Record<string, unknown>)
       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.";
@@ -266,7 +310,7 @@ export function runCanon(runtime: CanonRuntime, params: Record<string, unknown>)
          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
@@ -274,16 +318,93 @@ export function runCanon(runtime: CanonRuntime, params: Record<string, unknown>)
            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": {
@@ -330,7 +451,7 @@ export function runCanon(runtime: CanonRuntime, params: Record<string, unknown>)
     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.`;
   }