canon-atlas 0.2.0 → 0.3.0

package/README.md

@@ -4,7 +4,15 @@ An atlas over a catalog of markdown documents that reference each other. Point i
 
 It is agnostic to what wrote the catalog. It was built as the human viewport onto [pi-canon](https://github.com/shaneconner/pi-canon) project memory, where mutable articles carry current ground truth and an immutable journal carries the journey to it, but any folder of markdown with `[[wikilinks]]` or relative links works: an Obsidian vault, a wiki, a notes directory, an agent memory store.
 
-![The constellation over a pi-canon memory store](docs/constellation.png)
+![The constellation over a knowledge store of two thousand documents](docs/constellation.png)
+
+Click a star and the camera flies to it, its neighborhood lights while the rest of the sky dims, and the reader opens. Follow a link and you hop the connection; back walks the trail home.
+
+![Navigating the atlas: gliding into a cluster, opening a document, hopping a connection](docs/atlas.gif)
+
+The same footage plays smoother as [a short video](docs/atlas.mp4).
+
+![A pinned document: the neighborhood lit, the sky dimmed](docs/selection.png)
 
 ## Quick start
 
@@ -62,7 +70,7 @@ References that resolve nowhere are not errors: they render as dashed, unwritten
 
 ### The article schema
 
-A store may carry a `schema.json` beside its collections ([pi-canon](https://github.com/shaneconner/pi-canon) writes one when it creates a store), declaring rules for an article's `capsule`, `title`, and `body`: `required`, `min_chars`, `max_chars`, and a `hint`. The atlas enforces the same contract at every one of its write doors. Enforcement is asymmetric on purpose: a `required` rule rejects a save that touches the field (and everything on create), with nothing written and the editor keeping your text while it tells you what to correct; every other rule warns, and a document already in violation shows heal notes in the reader instead of errors, so a body edit is never held hostage to a legacy omission. A malformed `schema.json` fails open and loud: nothing is enforced, and the map panel and every save say so, because a contract the owner believes is enforced while a typo disabled it is the worst state.
+A store may carry a `schema.json` beside its collections ([pi-canon](https://github.com/shaneconner/pi-canon) writes one when it creates a store), declaring rules for an article's `capsule`, `title`, and `body`: `required`, `min_chars`, `max_chars`, and a `hint`. The reference graph is part of the contract too, under `relations`: `refs` (`required`, `min_count`) judges a document's own citations at the write door, counting body links and refs frontmatter once each with code examples stripped, and touching means the reference set changed, so a body edit that keeps its citations is never re-litigated; `orphan.warn` notes a document nothing references; `children.listed` notes a document that fails to reference a direct child under its address. The graph rules are exactly what a whole-graph reader is positioned to enforce, so the atlas enforces them and pi-canon enforces `refs` at its own boundary, both from the same file. The atlas enforces the same contract at every one of its write doors. Enforcement is asymmetric on purpose: a `required` rule rejects a save that touches the field (and everything on create), with nothing written and the editor keeping your text while it tells you what to correct; every other rule warns, and a document already in violation shows heal notes in the reader instead of errors, so a body edit is never held hostage to a legacy omission. A malformed `schema.json` fails open and loud: nothing is enforced, and the map panel and every save say so, because a contract the owner believes is enforced while a typo disabled it is the worst state.
 
 ## Color
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canon-atlas",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "An atlas over a catalog of markdown documents that reference each other: a constellation graph, search, a reader, and local editing. Agnostic to what wrote the catalog.",
   "type": "module",
   "bin": {
@@ -8,6 +8,11 @@
   },
   "exports": {
     ".": "./src/build.mjs",
+    "./serve": "./src/serve.mjs",
+    "./page": "./src/page.mjs",
+    "./pipeline": "./src/ui/pipeline.cjs",
+    "./assets/*": "./src/ui/*",
+    "./vendor/*": "./vendor/*",
     "./package.json": "./package.json"
   },
   "files": [

package/src/serve.mjs

@@ -161,7 +161,7 @@ export function corpusApi(rootArg) {
     if (col.immutable) return [];
     /* A broken declaration enforces nothing, but every write says so. */
     if (!cfg.schema) return cfg.schemaProblems || [];
-    const r = P.checkDoc(String(content ?? ""), prevRaw, cfg.schema, col.fields.summary);
+    const r = P.checkDoc(String(content ?? ""), prevRaw, cfg.schema, col.fields);
     if (r.rejects.length) {
       throw httpError(422, "Write rejected by this store's schema.json:\n- " + r.rejects.join("\n- "));
     }

package/src/ui/pipeline.cjs

@@ -248,6 +248,15 @@ var AtlasPipeline = (function () {
   const SCHEMA_FILE = "schema.json";
   const SCHEMA_FIELDS = ["capsule", "title", "body"];
   const SCHEMA_RULE_KEYS = ["required", "min_chars", "max_chars", "hint"];
+  /* Relations rules are about the reference graph, not any one field. The
+     contract declares them once; each tool enforces what it can see. This
+     page sees the whole graph, so all three hold here: refs at the write
+     door and on read, orphan and children as read-side heal notes. */
+  const RELATION_KEYS = {
+    refs: ["required", "min_count", "hint"],
+    orphan: ["warn", "hint"],
+    children: ["listed", "hint"],
+  };
 
   /* The store lives either at the corpus root or nested under .canon/; the
      schema file sits beside the collections, wherever they are. */
@@ -271,8 +280,9 @@ var AtlasPipeline = (function () {
       return { schema: undefined, problems: [SCHEMA_FILE + " must hold a JSON object; its rules are not being enforced."] };
     }
     const problems = [];
-    const declared = raw.article;
-    if (declared === undefined) return { schema: {}, problems };
+    /* A missing article block is an empty one, not an early exit: a schema
+       may carry only relations rules. */
+    const declared = raw.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.'] };
     }
@@ -297,9 +307,51 @@ var AtlasPipeline = (function () {
       }
       schema[name] = rule;
     }
+    const rel = raw.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 = {};
+        for (const [name, value] of Object.entries(rel)) {
+          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 = {};
+          for (const [key, val] of Object.entries(value)) {
+            if (!keys.includes(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.hint = val;
+            else problems.push(SCHEMA_FILE + ': "relations.' + name + "." + key + '" has the wrong type and is ignored.');
+          }
+          relations[name] = rule;
+        }
+        schema.relations = relations;
+      }
+    }
     return { schema, problems };
   }
 
+  /* The outgoing references a document authors, as the write door can see them:
+     body links (code stripped by the extractor) plus the collection's refs
+     frontmatter, deduplicated case-insensitively. */
+  function outgoingOf(raw, refsKey) {
+    const { meta, body } = parseFrontmatter(raw);
+    const out = new Set();
+    for (const l of extractLinks(body)) out.add(l.target.trim().toLowerCase());
+    for (const r of asRefs(meta[refsKey])) out.add(String(r).trim().toLowerCase());
+    out.delete("");
+    return [...out].sort();
+  }
+
   /* The title the schema means: the body's leading # heading, nothing later. */
   function titleOf(body) {
     for (const line of body.split("\n")) {
@@ -311,15 +363,19 @@ var AtlasPipeline = (function () {
   }
 
   /* One save (or one read, when prevRaw === raw so nothing counts as touched)
-     against the schema. summaryKey is the frontmatter key this collection
-     carries its capsule under. A required violation rejects only when the save
-     touched that field or created the document; a legacy violation the save
-     left alone warns instead, so a body edit is never held hostage to an old
-     missing capsule. */
-  function checkDoc(raw, prevRaw, schema, summaryKey) {
+     against the schema. fields is the collection's frontmatter mapping (a bare
+     string is taken as the summary key, for callers predating relations). A
+     required violation rejects only when the save touched that field or
+     created the document; a legacy violation the save left alone warns
+     instead, so a body edit is never held hostage to an old missing capsule,
+     and a kept reference set is never re-litigated. */
+  function checkDoc(raw, prevRaw, schema, fields) {
     const rejects = [];
     const warns = [];
     if (!schema) return { rejects, warns };
+    const f = typeof fields === "string" ? { summary: fields } : fields || {};
+    const summaryKey = f.summary || "summary";
+    const refsKey = f.refs || "refs";
     const created = prevRaw == null;
     const extract = (text) => {
       const { meta, body } = parseFrontmatter(text);
@@ -348,6 +404,20 @@ var AtlasPipeline = (function () {
         warns.push("schema: " + name + " is over " + rule.max_chars + " characters (" + value.length + ")" + hint);
       }
     }
+    /* refs is judged from the save alone: touched means the reference SET
+       changed, so a body edit that keeps its citations passes untouched. */
+    const refsRule = schema.relations && schema.relations.refs;
+    if (refsRule) {
+      const cited = outgoingOf(raw, refsKey);
+      const touched = created || cited.join("\n") !== outgoingOf(prevRaw, refsKey).join("\n");
+      const hint = refsRule.hint ? " (" + refsRule.hint + ")" : "";
+      if (refsRule.required && cited.length === 0) {
+        if (touched) rejects.push("refs is required and this document references nothing" + hint);
+        else warns.push("schema: refs is required and this document references nothing; this document can be healed by editing" + hint);
+      } else if (refsRule.min_count != null && cited.length < refsRule.min_count) {
+        warns.push("schema: refs has " + cited.length + " outgoing (min " + refsRule.min_count + ")" + hint);
+      }
+    }
     return { rejects, warns };
   }
 
@@ -395,7 +465,7 @@ var AtlasPipeline = (function () {
     /* A read never rejects: a document in violation carries heal notes. */
     let schemaNotes;
     if (config.schema && !col.immutable) {
-      const w = checkDoc(text, text, config.schema, f.summary).warns;
+      const w = checkDoc(text, text, config.schema, f).warns;
       if (w.length) schemaNotes = w;
     }
     return {
@@ -911,6 +981,46 @@ var AtlasPipeline = (function () {
 
   function buildData(config, graph, mode) {
     const { nodes, edges } = graph;
+    /* The graph-wide relations rules, which only a whole-graph reader can
+       judge: orphan (nothing references this document) and children (a parent
+       must reference each direct child under its address). Read-side heal
+       notes, never a wall, and only over mutable documents. */
+    const rel = config.schema && config.schema.relations;
+    if (rel && ((rel.orphan && rel.orphan.warn) || (rel.children && rel.children.listed))) {
+      const inbound = new Set();
+      const outTargets = new Map();
+      for (const e of edges) {
+        inbound.add(e.target);
+        if (!outTargets.has(e.source)) outTargets.set(e.source, new Set());
+        outTargets.get(e.source).add(e.target);
+      }
+      const byAddress = new Map();
+      nodes.forEach((n, i) => {
+        if (n.exists && !n.immutable && n.address) byAddress.set(n.address, i);
+      });
+      nodes.forEach((n, i) => {
+        if (!n.exists || n.immutable) return;
+        const notes = [];
+        if (rel.orphan && rel.orphan.warn && !inbound.has(i)) {
+          notes.push("schema: nothing references this document" + (rel.orphan.hint ? " (" + rel.orphan.hint + ")" : ""));
+        }
+        if (rel.children && rel.children.listed && n.address) {
+          const prefix = n.address + "/";
+          const named = outTargets.get(i) || new Set();
+          const missing = [];
+          for (const [addr, ci] of byAddress) {
+            if (!addr.startsWith(prefix) || addr.slice(prefix.length).includes("/")) continue;
+            if (!named.has(ci)) missing.push(addr);
+          }
+          if (missing.length) {
+            missing.sort();
+            const shown = missing.slice(0, 3).join(", ") + (missing.length > 3 ? " and " + (missing.length - 3) + " more" : "");
+            notes.push("schema: children not referenced: " + shown + (rel.children.hint ? " (" + rel.children.hint + ")" : ""));
+          }
+        }
+        if (notes.length) n.schemaNotes = (n.schemaNotes || []).concat(notes);
+      });
+    }
     const { basis, clusters, assign } = assignClusters(nodes, edges, config.vectors || null);
     const counts = new Map();
     for (const n of nodes) {

package/src/ui/shell.js

@@ -286,8 +286,7 @@
     if (col.immutable) return [];
     /* A broken declaration enforces nothing, but every write says so. */
     if (!storeSchema.schema) return storeSchema.problems || [];
-    var summaryKey = (col.fields && col.fields.summary) || "summary";
-    var r = AtlasPipeline.checkDoc(String(content == null ? "" : content), prevRaw, storeSchema.schema, summaryKey);
+    var r = AtlasPipeline.checkDoc(String(content == null ? "" : content), prevRaw, storeSchema.schema, col.fields || {});
     if (r.rejects.length) {
       throw new Error("Write rejected by this store's schema.json:\n- " + r.rejects.join("\n- "));
     }