naive-framework 0.0.0-stage → 0.2.0

package/interface/writes.mjs

@@ -0,0 +1,190 @@
+// What a write answers, what a layout offers, and the wrapper the router puts around every call
+// (Next.js translation M-3, M-9, M-17; it also wires in interface/reads.mjs, interface/boundaries.mjs
+// and interface/package-routes.mjs).
+//
+//   changed   M-3   one round trip: a write answers with the new state and what it changed: the
+//                   record's state before and after, each package whose progress or state moved,
+//                   the records that move now because of it, what it unlocked (a package that
+//                   completed and what that opens, a decision that no longer waits) and the
+//                   need-now rows it settled
+//   next      M-17  a write answers with the next route to act on: accept the draft it made, else
+//                   the next record in the same package that moves now, else what it unlocked,
+//                   else what need-now suggests, else the decision that matters most
+//   actions   M-9   a layout lists the actions available in its folder to the actor asking: each
+//                   route's actions, which of them this actor may take now, and whether a write
+//                   lands as the record, as a draft, or is locked or refused, with why
+//
+// around() runs before and after the router's own call: the framework and venture global errors
+// first (E-8), then package, group and venture routes (L-6, P-36, P-3), then the call, then what
+// reads and layouts add (L-9, L-10, O-1 to O-3, P-28) and what writes answer (M-3, M-17). It never
+// calls a model.
+
+import { allowed, draftOf, gateOf, resolve, routes, ventureDir } from "./router.mjs";
+import { frameworkHealth, globalError, ventureHealth } from "./boundaries.mjs";
+import { groupLayout, packageOfRecord, routeOfType, specialCall } from "./package-routes.mjs";
+import { filterRead, hierarchy, metadataFor, resolvedBy, withParams } from "./reads.mjs";
+
+/** The state a write can change, taken before and after it. */
+export async function snapshot(dir) {
+  const safe = async (f) => { try { return await f(); } catch { return null; } };
+  const { packages } = await import("../schema/packages.mjs");
+  const { needNow } = await import("../schema/need-now.mjs");
+  const { decisions } = await import("../schema/decisions.mjs");
+  return { packages: await safe(() => packages(dir)), need: await safe(() => needNow(dir)), decisions: await safe(() => decisions(dir)) };
+}
+
+const pkgMap = (s) => new Map([...(s?.packages?.core ?? []), ...(s?.packages?.handoff ?? [])].map((p) => [p.id, p]));
+const rowOf = (s, type) => (s?.packages?.core ?? []).flatMap((p) => p.records).find((x) => x.record === type && x.role !== "reads") ?? null;
+
+/** What a write changed (M-3), from the state before and after it. */
+export async function changed(before, after, { record }) {
+  const b = pkgMap(before), a = pkgMap(after);
+  const packages = [...a.values()].filter((p) => { const o = b.get(p.id); return !o || o.progress !== p.progress || o.state !== p.state; })
+    .map((p) => ({ package: p.id, title: p.title, progress: { from: b.get(p.id)?.progress ?? null, to: p.progress }, state: { from: b.get(p.id)?.state ?? null, to: p.state } }));
+  const was = new Map((before?.packages?.core ?? []).flatMap((p) => p.records.map((x) => [`${p.id}:${x.record}`, x])));
+  const moves = [];
+  for (const p of after?.packages?.core ?? []) for (const x of p.records) {
+    const o = was.get(`${p.id}:${x.record}`);
+    if (x.role !== "reads" && x.moves === "now" && o?.moves === "waits" && !moves.some((m) => m.record === x.record)) moves.push({ record: x.record, package: p.id, route: await routeOfType(x.record) });
+  }
+  const unlocked = [...a.values()].filter((p) => p.state === "complete" && b.get(p.id)?.state !== "complete").map((p) => ({ package: p.id, unlocks: p.unlocks ?? [] }));
+  const dBefore = new Map((before?.decisions?.decisions ?? []).map((d) => [d.id, d.render]));
+  const freed = (after?.decisions?.decisions ?? []).filter((d) => ["waiting", "later"].includes(dBefore.get(d.id)) && ["now", "overdue"].includes(d.render)).map((d) => ({ decision: d.id, question: d.question ?? null }));
+  const nBefore = new Map((before?.need?.rows ?? []).map((x) => [x.type, x.status]));
+  const need = (after?.need?.rows ?? []).filter((x) => nBefore.has(x.type) && nBefore.get(x.type) !== x.status).map((x) => ({ record: x.type, from: nBefore.get(x.type), to: x.status }));
+  return {
+    record: { type: record, from: rowOf(before, record)?.status ?? null, to: rowOf(after, record)?.status ?? null, package: packageOfRecord(record) },
+    packages, moves_now: moves, unlocked: [...unlocked, ...freed], need_now: need,
+  };
+}
+
+const commandFor = (route, venture) => route?.endsWith("[id]") ? `mentura ${route.replace("[id]", "<id>")} write --venture ${venture} --input <file>` : `mentura ${route} write --venture ${venture} --input <file>`;
+
+/** The next route to act on after a write (M-17). */
+export async function next(after, { record, route, draft, venture, change }) {
+  if (draft) return { route, action: "accept", who: "a person", command: `mentura accept ${route} --venture ${venture}`, why: "the write is held as a draft until a person accepts it" };
+  const home = packageOfRecord(record);
+  const p = (after?.packages?.core ?? []).find((x) => x.id === home);
+  const missing = (p?.records ?? []).filter((x) => x.role !== "reads" && x.record !== record && x.moves === "now" && x.status === "missing");
+  const required = missing.find((x) => x.role === "required");
+  if (required) { const rt = await routeOfType(required.record); return { route: rt, action: "write", command: commandFor(rt, venture), why: `the next required record in ${p.title} that moves now` }; }
+  // An agent's write waits for a person before what reads it can move.
+  const review = (p?.records ?? []).filter((x) => x.role !== "reads" && x.status === "agent");
+  if (review.length) { const rt = await routeOfType(review[0].record); return { route: rt, action: "review", who: "a person", command: `mentura ${rt} read --venture ${venture}`, why: `${review[0].title} was written by an agent: a person confirms it by writing it with --as person, and what reads it moves then` }; }
+  const freed = change?.moves_now?.[0];
+  if (freed) return { route: freed.route, action: "write", command: commandFor(freed.route, venture), why: `this write let ${freed.record} move` };
+  if (missing.length) { const rt = await routeOfType(missing[0].record); return { route: rt, action: "write", command: commandFor(rt, venture), why: `the next ${missing[0].role} record in ${p.title} that moves now` }; }
+  const suggest = (after?.need?.rows ?? []).filter((x) => x.status === "suggest now" && x.type !== record).sort((a, b) => b.now - a.now)[0];
+  if (suggest) { const rt = await routeOfType(suggest.type); if (rt) return { route: rt, action: "write", command: commandFor(rt, venture), why: `need-now suggests it now: ${suggest.why}` }; }
+  const { rank } = await import("../schema/decisions.mjs");
+  const ds = after?.decisions ? rank(after.decisions.decisions, after.decisions.phase).filter((d) => d.rank != null && d.source === "file") : [];
+  if (ds.length) return { route: "governance/decisions", action: "decide", who: "a person", command: `mentura decide ${ds[0].id} --venture ${venture} --by <your name>`, why: ds[0].question };
+  return { route: null, action: null, why: "nothing waits on this write" };
+}
+
+/** The actions available in a route's folder to one actor (M-9). */
+export async function actionsIn({ dir, r, route, actor = "agent", actor_id, venture }) {
+  const { holding, locked } = await import("../schema/decisions.mjs");
+  const { configOf, hold } = await import("../schema/gate.mjs");
+  const folder = r.collection === "item" ? r.route.slice(0, -"/[id]".length) : route.includes("/") ? route.slice(0, route.lastIndexOf("/")) : route;
+  const rs = routes().filter((x) => x.route === folder || x.route.startsWith(`${folder}/`));
+  const list = [];
+  for (const x of rs) {
+    const concrete = x.route === r.route ? route : x.route;
+    const entry = { route: concrete, kind: x.kind, actions: x.actions };
+    if (!dir) { list.push(entry); continue; }
+    const reads = allowed(dir, actor_id, "read", concrete);
+    const avail = x.actions.filter((a) => !["write", "run"].includes(a) && (reads || a === "template" || a === "layout"));
+    if (x.actions.includes("run")) {
+      const lock = actor !== "person" ? locked(dir, concrete, actor_id) : null;
+      if (reads && !lock) avail.push("run");
+      entry.run = lock ? { runs: false, why: `locked until decision ${lock.id} is made` } : reads ? { runs: true } : { runs: false, why: "the team plan does not let this role reach it" };
+    }
+    if (x.actions.includes("write")) {
+      let w;
+      if (!allowed(dir, actor_id, "write", concrete)) w = { lands: null, why: `${actor_id} may not write it (team plan routes)` };
+      else {
+        const lock = actor !== "person" ? locked(dir, concrete, actor_id) : null;
+        if (lock) w = { lands: null, why: `locked until decision ${lock.id} is made: ${lock.question}` };
+        else if (actor === "person") w = { lands: "record", why: "a person's write goes straight to the record" };
+        else {
+          const gate = gateOf(x, dir);
+          const d = !concrete.includes("[id]") ? draftOf(concrete, venture, undefined) : null;
+          const held = d ? holding(dir, d.file) : null;
+          const cfg = hold(configOf(dir), x.route, actor);
+          w = gate?.drafts ? { lands: "draft", why: `${x.record} is a ${gate.class} decision (${gate.level})` } : held ? { lands: "draft", why: `decision ${held.id} ${held.why}` } : cfg ? { lands: "draft", why: `${cfg.rule} fails closed in naive.config.json` } : { lands: "record", why: "no gate holds it" };
+        }
+      }
+      if (w.lands) avail.push("write");
+      entry.write = w;
+    }
+    entry.available = avail;
+    list.push(entry);
+  }
+  return { folder, actor: { kind: actor, ...(actor_id ? { id: actor_id } : {}) }, routes: list };
+}
+
+// The venture-relative file behind a read's source address (venture://path), for local sources only.
+const fileOfAddress = (a) => a?.startsWith("venture://") ? a.slice("venture://".length) : null;
+
+/**
+ * The wrapper around the router's call (see the top of this file). inner is the router's own call;
+ * args are what call takes. Returns what call returns, with the additions above.
+ */
+export async function around(inner, args) {
+  const { venture, route, action, input, actor = "agent", workspace } = args;
+  const actor_id = args.actor_id ?? process.env.MENTURA_ACTOR_ID;
+  // E-8: a broken framework file stops every route, with its recovery steps.
+  const fw = frameworkHealth();
+  if (fw) return globalError(fw);
+  let res;
+  try { res = resolve(route); } catch (e) { return globalError({ scope: "framework", file: "schema/data-model.json", problem: `the route table cannot be built: ${String(e.message ?? e).split("\n")[0]}`, recovery: ["Check the data model and the manifests: node schema/check-data-model.mjs", "Restore the file it names from git"] }); }
+  const dir = venture ? ventureDir(venture, workspace) : null;
+  // E-8: a broken venture.json answers with recovery steps, before anything reads it.
+  if (dir) { const h = ventureHealth(dir); if (h) return globalError(h, venture); }
+  // L-6, P-36, P-3: package, group and venture routes are answered here, outside the route table.
+  if (!res.r) return (await specialCall(args)) ?? inner(args);
+  const r = res.r, params = res.params;
+  const concrete = r.collection === "item" ? r.route.replace("[id]", params.id) : r.route;
+  const before = action === "write" && dir && r.kind === "record" ? await snapshot(dir) : null;
+  let out;
+  try { out = await inner(args); }
+  catch (e) {
+    // E-6: a record that cannot be read is that record's error, not a crash.
+    if (action !== "read") throw e;
+    return { ok: false, outcome: "error", error: `${concrete}: the record does not parse: ${String(e.message ?? e).split("\n")[0]}`, fix: { schema: r.schema ?? null, template: r.template ?? null }, resolved_by: "error" };
+  }
+
+  if (action === "read" && dir && r.kind === "record") {
+    if (out.ok) {
+      const items = r.collection === "list" ? Object.fromEntries(Object.entries(out.sources ?? {}).map(([id, s]) => [id, fileOfAddress(s.address)]).filter(([, f]) => f))
+        : out.source && fileOfAddress(out.source.address) ? { [params.id ?? r.record]: fileOfAddress(out.source.address) } : {};
+      out = { ...out, params, metadata: await metadataFor({ dir, r, route: concrete, params, result: out.result, items }) };
+      out = filterRead(out, input?.where, r);
+    }
+    out.resolved_by = resolvedBy(out);
+    if (input?.hierarchy) {
+      const { layout } = await import("./router.mjs");
+      const pkg = packageOfRecord(r.record);
+      const lay = withParams(layout(r, dir), { dir, params, file: draftOf(concrete, venture, workspace)?.file, group: pkg ? groupLayout(pkg, dir) : null });
+      out.hierarchy = hierarchy({ answer: out, layout: lay }).levels;
+    }
+    return out;
+  }
+
+  if (action === "layout" && out.ok) {
+    const pkg = r.kind === "record" ? packageOfRecord(r.record) : null;
+    const file = dir && r.kind === "record" && r.collection !== "list" && !concrete.includes("[id]") ? draftOf(concrete, venture, workspace)?.file : null;
+    const result = withParams(out.result, { dir, params, file, group: pkg ? groupLayout(pkg, dir) : null });
+    result.actions = await actionsIn({ dir, r, route: concrete, actor, actor_id, venture: venture ?? null });
+    return { ...out, result };
+  }
+
+  if (action === "write" && before && out.ok && out.result?.written) {
+    const after = await snapshot(dir);
+    const change = await changed(before, after, { record: r.record });
+    out.result.changed = change;
+    out.result.next = await next(after, { record: r.record, route: concrete, draft: out.result.draft, venture, change });
+  }
+  return out;
+}

package/knowledge/connectors/README.md

@@ -0,0 +1,54 @@
+---
+type: reference
+source: hybrid
+created: 2026-10-28T01:10:00Z
+ai-model: claude-opus-5.5
+tags: [everything-ecosystem, knowledge, connectors, storage]
+description: "How the knowledge layer reaches the sources a venture keeps records in: the connector contract, the source map, the catalog and the evals (EE-037)."
+---
+
+# Knowledge connectors
+
+The knowledge layer is where every record is stored and found. It does not copy records into one place. Each venture keeps its records wherever it already works, and Mentura reaches each source through a connector (EE-037).
+
+## The parts
+
+| Part | File | What it does |
+|---|---|---|
+| Contract | `contract.mjs` | The five things every connector does: `list`, `read`, `version`, `search`, `write`. A version is the git blob SHA-1 of the content in every source. |
+| Registry | `../tooling/integrations.json` | An integration with a `connector` names the module that implements the contract for it. |
+| Source map | `<venture>/knowledge/sources.json` | Optional. The venture's sources, and which record type lives in which. Unnamed record types stay in the venture folder. Schema: `schema/knowledge-sources.schema.json`; checked by `schema/check-sources.mjs`. |
+| Connectors | `filesystem.mjs` | A folder or git repository (writes in place). The framework ships only this one: it works offline and names no vendor. Connectors that reach a vendor, such as GitHub, are platform and live in `platform/connectors/` (EE-041). |
+| Matrix | `resolve.mjs` | The source-of-truth matrix (EE-042): `rules` in the source map name a system of record and owner per record type, attribute and context (phase, product, account, actor). The most specific rule wins; a tie is an error. `records` is shorthand for rules that match anything. An attribute rule (a price in another source) is read from and written to that source, so the record's own file holds no second copy. |
+| Where-used | `<venture>/knowledge/where-used.json` | For each fact kept once (a price, a product name), every place that repeats it, live or frozen. `schema/check-where-used.mjs` reports drift offline; delivering the change into vendors is the platform's. |
+| Catalog | `catalog.mjs` | One index over every source: address, version, route, title and words. No content. Routes `knowledge/catalog` and `knowledge/search`. |
+| Evals | `suite.mjs`, `eval.mjs` | `suite.mjs` is the contract suite every connector passes, framework or platform. `eval.mjs` runs it on the filesystem connector, then the router over a mapped folder and the catalog. The GitHub connector's evals are `platform/connectors/eval.mjs`. |
+
+## A source map
+
+```json
+{
+  "sources": [
+    { "id": "team-repo", "connector": "github", "repo": "acme/tandem", "ref": "main", "root": "ventures/tandem" }
+  ],
+  "records": { "product": "team-repo" }
+}
+```
+
+The `github` connector is a platform connector (`platform/connectors/github.mjs`). With this map, `purpose/product/kettle` reads `ventures/tandem/products/kettle.json` from `acme/tandem` and says which version and commit it came from. A write opens a draft pull request, which a person accepts by merging. Every other record stays in the venture folder. The venture folder always keeps `venture.json`, the provenance log and drafts.
+
+## Adding a connector
+
+1. Decide which side it is on. If it works offline, needs no credentials and names no vendor, it is framework and goes in `knowledge/connectors/<id>.mjs`. Otherwise it is platform and goes in `platform/connectors/<id>.mjs` (EE-041). `node schema/check-boundary.mjs` enforces this.
+2. Export `connect(options)`, returning an object that meets the contract.
+3. Add a `connector` to its entry in `knowledge/tooling/integrations.json`: the module, its write modes and its options.
+4. Run it through `contract()` from `suite.mjs`: against a fake of its API offline, and against the real one when credentials are given.
+
+## Running the evals
+
+```sh
+node knowledge/connectors/eval.mjs                                                       # framework
+node platform/connectors/eval.mjs                                                        # platform (GitHub, against a fake)
+MENTURA_EVAL_GITHUB_REPO=owner/name GITHUB_TOKEN=... node platform/connectors/eval.mjs   # also live
+MENTURA_EVAL_GITHUB_WRITE=1 ...                                                          # and open one real draft PR
+```

package/knowledge/connectors/catalog.mjs

@@ -0,0 +1,118 @@
+// The catalog (EE-037): one index over every item in every source of a venture, so a person or an
+// agent can find a record without knowing where it lives. For each item it keeps the address,
+// source, path, version, route and record type (when the item is a record), a title and the set
+// of words in it. It keeps no content: the words are a sorted set, not the text, and reading an
+// item always goes back to its source. A rebuild reads only items whose version changed.
+//
+//   node knowledge/connectors/catalog.mjs <venture dir> [--json]             build or refresh
+//   node knowledge/connectors/catalog.mjs <venture dir> --search <q> [--json] [--live]
+//          search the catalog (built first if there is none); --live asks each source instead
+//
+// The catalog is written to <venture>/_catalog/catalog.json. It is derived, so a venture may
+// ignore it in git; the router never routes _ folders.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { address, isText, words } from "./contract.mjs";
+import { connectAll } from "./index.mjs";
+
+export const FILE = "_catalog/catalog.json";
+const MAX_BYTES = 1_000_000;
+
+function title(path, content) {
+  if (path.endsWith(".json")) {
+    try { const j = JSON.parse(content); const t = j && typeof j === "object" && !Array.isArray(j) ? j.name ?? j.title ?? j.statement ?? j.id : null; if (typeof t === "string") return t.slice(0, 160); } catch {}
+  }
+  const fm = content.match(/^---\n[\s\S]*?\ntitle:\s*["']?(.+?)["']?\n[\s\S]*?\n---/);
+  if (fm) return fm[1];
+  const h = content.match(/^#\s+(.+)$/m);
+  return h ? h[1].trim() : path.split("/").at(-1);
+}
+
+// Which route a file in a source belongs to, from the route table (lazy, so the catalog works
+// without the router for a plain folder).
+let table = null;
+async function routeOf(path) {
+  if (!table) {
+    const { routes, glob } = await import("../../interface/router.mjs");
+    table = routes().filter((r) => r.kind === "record" && r.collection !== "list").map((r) => ({ r, res: r.files.map((g) => glob(g)) }));
+  }
+  for (const { r, res } of table) {
+    if (!res.some((re) => re.test(path))) continue;
+    if (r.collection !== "item") return { route: r.route, record: r.record };
+    for (const g of r.files) {
+      if (!g.includes("*")) continue;
+      const m = path.match(new RegExp("^" + g.split("*").map((s) => s.replace(/[.+^${}()|[\]\\]/g, "\\$&")).join("([^/]*)") + "$"));
+      if (m) return { route: r.route.replace("[id]", m[1]), record: r.record };
+    }
+    return { route: r.route, record: r.record };
+  }
+  return { route: null, record: null };
+}
+
+export const load = (dir) => existsSync(join(dir, FILE)) ? JSON.parse(readFileSync(join(dir, FILE), "utf8")) : null;
+
+/** Builds or refreshes the catalog. Returns it with stats: items, read (items fetched), reused. */
+export async function build(dir, { write = true, sources } = {}) {
+  const prior = new Map((load(dir)?.items ?? []).map((x) => [x.address, x]));
+  const conns = sources ?? await connectAll(dir);
+  const items = [];
+  const stats = { sources: conns.length, items: 0, read: 0, reused: 0, skipped: 0, errors: [] };
+  for (const { source, connector } of conns) {
+    let listed;
+    try { listed = await connector.list(); } catch (e) { stats.errors.push(`${source.id}: ${e.message}`); continue; }
+    for (const { path, version } of listed) {
+      const at = address(source.id, path);
+      const old = prior.get(at);
+      const where = await routeOf(path);
+      if (old && old.version === version) { items.push({ ...old, ...where }); stats.reused++; continue; }
+      if (!isText(path)) { items.push({ address: at, source: source.id, path, version, ...where, title: path.split("/").at(-1), terms: words(path) }); stats.skipped++; continue; }
+      const got = await connector.read(path);
+      stats.read++;
+      if (!got || got.content.length > MAX_BYTES || !isText(path, got.content)) { items.push({ address: at, source: source.id, path, version, ...where, title: path.split("/").at(-1), terms: words(path) }); continue; }
+      items.push({ address: at, source: source.id, path, version: got.version, ...where, title: title(path, got.content), terms: [...new Set(words(`${path}\n${got.content}`))].sort() });
+    }
+  }
+  stats.items = items.length;
+  const catalog = { built_at: new Date().toISOString(), sources: conns.map(({ source }) => ({ id: source.id, connector: source.connector })), items };
+  if (write) { mkdirSync(join(dir, "_catalog"), { recursive: true }); writeFileSync(join(dir, FILE), JSON.stringify(catalog) + "\n"); }
+  return { catalog, stats };
+}
+
+/** Items holding every word of the query, best first: words in the title count double. */
+export function search(catalog, query, { limit = 20 } = {}) {
+  const q = words(query);
+  if (!q.length) return [];
+  return catalog.items.map((x) => {
+    const terms = new Set(x.terms), t = words(x.title).join(" ");
+    if (!q.every((w) => terms.has(w) || x.terms.some((y) => y.startsWith(w)))) return null;
+    return { score: q.reduce((s, w) => s + (terms.has(w) ? 2 : 1) + (t.includes(w) ? 2 : 0), 0), ...x };
+  }).filter(Boolean).sort((a, b) => b.score - a.score || a.address.localeCompare(b.address)).slice(0, limit)
+    .map(({ terms, ...x }) => x);
+}
+
+/** Asks each source's own search instead of the catalog. */
+export async function searchLive(dir, query, { limit = 20 } = {}) {
+  const out = [];
+  for (const { source, connector } of await connectAll(dir)) {
+    try { for (const x of await connector.search(query, { limit })) out.push({ address: address(source.id, x.path), source: source.id, path: x.path, version: x.version, ...(await routeOf(x.path)) }); }
+    catch (e) { out.push({ source: source.id, error: e.message }); }
+  }
+  return out;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const [dir] = process.argv.slice(2).filter((a, i, all) => !a.startsWith("--") && all[i - 1] !== "--search");
+  const i = process.argv.indexOf("--search");
+  const json = process.argv.includes("--json");
+  if (!dir) { console.error("usage: node knowledge/connectors/catalog.mjs <venture dir> [--search <q>] [--live] [--json]"); process.exit(2); }
+  if (i >= 0) {
+    const q = process.argv[i + 1] ?? "";
+    const hits = process.argv.includes("--live") ? await searchLive(dir, q) : search(load(dir) ?? (await build(dir)).catalog, q);
+    console.log(json ? JSON.stringify({ query: q, hits }, null, 2) : hits.map((h) => `${h.address}  ${h.title ?? ""}${h.route ? `  (${h.route})` : ""}`).join("\n") || "no items match");
+  } else {
+    const { stats } = await build(dir);
+    console.log(json ? JSON.stringify(stats, null, 2) : `catalog: ${stats.items} items from ${stats.sources} sources (${stats.read} read, ${stats.reused} unchanged)${stats.errors.length ? `\n${stats.errors.join("\n")}` : ""}`);
+    if (stats.errors.length) process.exitCode = 1;
+  }
+}

package/knowledge/connectors/contract.mjs

@@ -0,0 +1,56 @@
+// The connector contract (EE-037). A connector reaches one source of records (a folder, a GitHub
+// repository, later a database, Notion or Salesforce) and does the same five things for every one:
+//
+//   list(prefix)            [{ path, version }] for every item under the prefix, sorted by path
+//   read(path)              { path, content, version, commit?, permalink? }, or null when it is missing
+//   version(path)           the item's version, or null when it is missing
+//   search(query, {limit})  [{ path, version }] for items whose text holds every word of the query
+//   write(path, content, {message, title})
+//                           { path, version, commit?, pull_request? }; how it writes is the
+//                           connector's `writes`: direct (in place), pull-request (a draft pull
+//                           request; merging it accepts the write) or none (read-only, write throws)
+//
+// Paths are relative to the source's root and use forward slashes; a path that leaves the root is
+// refused. Content is UTF-8 text. A version is the git blob SHA-1 of the content, whichever
+// connector holds it, so the same content has the same version in every source and a version
+// can be checked without asking the source. An item's address is <source id>://<path>; with its
+// version it is what provenance cites.
+
+import { createHash } from "node:crypto";
+
+export const METHODS = ["list", "read", "version", "search", "write"];
+export const WRITES = ["direct", "pull-request", "none"];
+
+/** The git blob SHA-1 of some content: what `git hash-object` prints. */
+export const blobSha = (content) => {
+  const buf = Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8");
+  return createHash("sha1").update(`blob ${buf.length}\0`).update(buf).digest("hex");
+};
+
+/** A path inside a source, normalised, or an error for one that is empty or leaves the root. */
+export function safePath(p) {
+  if (typeof p !== "string" || !p.length || p.includes("\0") || p.includes("\\") || p.startsWith("/")) throw new Error(`${JSON.stringify(p)} is not a path inside the source`);
+  const parts = p.split("/").filter((s) => s && s !== ".");
+  if (!parts.length || parts.includes("..")) throw new Error(`${p} is not a path inside the source`);
+  return parts.join("/");
+}
+
+export const address = (sourceId, path) => `${sourceId}://${path}`;
+
+/** Every word of the query, lowercased, appears in the text. */
+export const matches = (text, query) => {
+  const t = text.toLowerCase();
+  return words(query).every((w) => t.includes(w));
+};
+export const words = (s) => String(s).toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((w) => w.length > 1);
+
+/** Text a catalog may index: small files that are not binary. */
+export const isText = (path, content) => !/\.(png|jpe?g|gif|webp|ico|pdf|zip|gz|woff2?|ttf|mp4|mov)$/i.test(path) && (content === undefined || !content.includes("\0"));
+
+/** Checks an object has the contract's methods and a known `writes`. Returns the problems. */
+export function conformance(c) {
+  const problems = METHODS.filter((m) => typeof c?.[m] !== "function").map((m) => `no ${m}()`);
+  if (!WRITES.includes(c?.writes)) problems.push(`writes is ${c?.writes}, not one of ${WRITES.join(", ")}`);
+  if (typeof c?.id !== "string") problems.push("no id");
+  return problems;
+}

package/knowledge/connectors/eval.mjs

@@ -0,0 +1,176 @@
+// Evals for the framework's connectors (EE-037, EE-041). The framework ships one connector, the
+// file system, which works offline and names no vendor; connectors that reach a vendor are
+// platform and have their own evals (platform/connectors/eval.mjs), against the same suite.
+// Three parts:
+//
+//   contract   the shared suite (suite.mjs) on the filesystem connector, in a plain folder and in
+//              a git repository, plus the venture-folder rules
+//   router     a venture whose source map keeps one record type in another folder: reads come
+//              from there with their version, a write lands there and is logged by address,
+//              nothing invalid reaches the source, and every other record stays in the venture
+//   catalog    one index across both sources, and a rebuild reads only what changed
+//
+//   node knowledge/connectors/eval.mjs
+
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdtempSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { blobSha } from "./contract.mjs";
+import { contract, FIXTURE, harness, OUTSIDE } from "./suite.mjs";
+import { connect as fsConnect } from "./filesystem.mjs";
+import { build, FILE, load, search } from "./catalog.mjs";
+
+const repo = new URL("../..", import.meta.url).pathname;
+const h = harness("connectors");
+const { expect, write, scratch, finish } = h;
+
+// The filesystem connector, in a plain folder.
+const fsMake = (git) => async ({ writes = "direct" } = {}) => {
+  const d = mkdtempSync(join(scratch, "fs-"));
+  write(join(d, "kb"), FIXTURE);
+  write(d, OUTSIDE);
+  if (git) {
+    const g = (...a) => spawnSync("git", ["-C", d, ...a], { encoding: "utf8" });
+    g("init", "-q"); g("add", "."); g("-c", "user.name=eval", "-c", "user.email=eval@example.com", "commit", "-qm", "fixture");
+  }
+  return { c: fsConnect({ id: "folder", root: join(d, "kb"), writes }), dir: d };
+};
+await contract(h, "filesystem (plain folder)", fsMake(false));
+const gitT = await contract(h, "filesystem (git repository)", fsMake(true));
+{
+  const fresh = await fsMake(true)();
+  const r = await fresh.c.read("notes/beta.md");
+  const head = spawnSync("git", ["-C", fresh.dir, "rev-parse", "HEAD"], { encoding: "utf8" }).stdout.trim();
+  expect("filesystem (git repository): a committed, unchanged item gives the commit that last touched it", r.commit === head);
+  await fresh.c.write("notes/beta.md", "changed\n");
+  expect("filesystem (git repository): a changed item gives no commit, since no commit holds that version", !(await fresh.c.read("notes/beta.md")).commit);
+  void gitT;
+}
+{
+  const d = mkdtempSync(join(scratch, "venture-"));
+  write(d, { "venture.json": "{}", "purpose/telos.json": "{}", "_drafts/x.draft": "{}", "studio/venture.json": "{}", "studio/purpose/telos.json": "{}" });
+  const v = fsConnect({ root: d, venture: true });
+  expect("filesystem (venture folder): listing stops at a nested venture and skips private _ folders", JSON.stringify((await v.list()).map((x) => x.path)) === JSON.stringify(["purpose/telos.json", "venture.json"]));
+}
+
+// ---- Router --------------------------------------------------------------------------------------
+console.log("\n# router over a mapped source");
+const ws = join(scratch, "workspace");
+cpSync(join(repo, "schema/examples/workspace"), ws, { recursive: true });
+process.env.MENTURA_WORKSPACE = ws;
+const tandem = join(ws, "ventures/tandem");
+const shared = join(ws, "shared");
+const { call } = await import("../../interface/router.mjs");
+const { entries } = await import("../../interface/provenance.mjs");
+const kettle = { ...Object.values((await call({ venture: "tandem", route: "purpose/product", action: "read" })).result)[0], id: "kettle", name: "Kettle (in the shared folder)" };
+write(shared, { "products/kettle.json": JSON.stringify(kettle, null, 2) + "\n", "notes/launch.md": "# Launch plan\n\nShip the kettle subscription in spring.\n" });
+const map = { sources: [{ id: "shared", connector: "filesystem", root: "../../shared" }], records: { product: "shared" } };
+write(tandem, { "knowledge/sources.json": JSON.stringify(map, null, 2) + "\n" });
+const localProducts = existsSync(join(tandem, "products")) ? spawnSync("ls", [join(tandem, "products")], { encoding: "utf8" }).stdout.trim().split("\n") : [];
+
+const list = await call({ venture: "tandem", route: "purpose/product", action: "read" });
+expect("router: a mapped record type is read from its source, not the venture folder", list.ok && JSON.stringify(Object.keys(list.result)) === JSON.stringify(["kettle"]) && localProducts.length > 0, JSON.stringify(list).slice(0, 300));
+const one = await call({ venture: "tandem", route: "purpose/product/kettle", action: "read" });
+expect("router: a read says which source and version it came from", one.result?.name === "Kettle (in the shared folder)" && one.source?.address === "shared://products/kettle.json"
+  && one.source.version === blobSha(JSON.stringify(kettle, null, 2) + "\n"), JSON.stringify(one.source));
+const local = await call({ venture: "tandem", route: "purpose/validation/problem", action: "read" });
+expect("router: every record type the map does not name stays in the venture folder", local.ok && local.source?.source === "venture" && local.source.version === blobSha(readFileSync(join(tandem, "purpose/validation/problem.json"))));
+const teapot = { ...kettle, id: "teapot", name: "Teapot" };
+const bad = await call({ venture: "tandem", route: "purpose/product/teapot", action: "write", input: { id: "teapot" } });
+expect("router: a write that does not match the schema never reaches the source", !bad.ok && /does not match/.test(bad.error) && !existsSync(join(shared, "products/teapot.json")));
+const w = await call({ venture: "tandem", route: "purpose/product/teapot", action: "write", input: teapot, actor: "person", via: "cli", provenance: { note: "add the teapot" } });
+expect("router: a write lands in the mapped source, not the venture folder", w.ok && JSON.parse(readFileSync(join(shared, "products/teapot.json"), "utf8")).name === "Teapot" && !existsSync(join(tandem, "products/teapot.json")), JSON.stringify(w));
+const e = entries(tandem).at(-1);
+expect("router: the write is logged by address, with the source's version", e.entity === "shared://products/teapot.json" && e.source?.connector === "filesystem" && e.source.version === blobSha(readFileSync(join(shared, "products/teapot.json"))), JSON.stringify(e));
+const prov = spawnSync("node", [join(repo, "schema/check-provenance.mjs"), ws], { encoding: "utf8" });
+const srcCheck = (d) => spawnSync("node", [join(repo, "schema/check-sources.mjs"), d], { encoding: "utf8" });
+expect("router: check-provenance accepts entries for records in another source", prov.status === 0, prov.stderr);
+expect("router: check-sources accepts the map", srcCheck(ws).status === 0, srcCheck(ws).stderr);
+const valid = spawnSync("python3", ["-I", join(repo, "schema/validate.py"), "--schema", "knowledge-sources.schema.json", "--file", join(tandem, "knowledge/sources.json")], { encoding: "utf8" });
+expect("router: the map matches its schema", valid.status === 0, valid.stdout + valid.stderr);
+write(tandem, { "knowledge/sources.json": JSON.stringify({ sources: [{ id: "team-repo", connector: "notion" }], records: { product: "team-repo", venture: "team-repo" } }) });
+const broken = srcCheck(ws);
+expect("router: check-sources refuses an unknown connector and a record type that must stay in the folder", broken.status === 1 && /no connector notion/.test(broken.stderr) && /venture stays in the venture folder/.test(broken.stderr), broken.stderr);
+const refused = await call({ venture: "tandem", route: "purpose/product", action: "read" });
+expect("router: a read through an unknown connector fails and says which connectors exist", !refused.ok && /no connector notion: .*filesystem/.test(refused.error), refused.error);
+write(tandem, { "knowledge/sources.json": JSON.stringify({ ...map, sources: [{ ...map.sources[0], writes: "none" }] }) });
+const ro = await call({ venture: "tandem", route: "purpose/product/teapot", action: "write", input: teapot, actor: "person" });
+expect("router: a write to a read-only source is refused", !ro.ok && /read-only/.test(ro.error));
+write(tandem, { "knowledge/sources.json": JSON.stringify(map, null, 2) + "\n" });
+
+// ---- Catalog -------------------------------------------------------------------------------------
+console.log("\n# catalog");
+const { stats } = await build(tandem);
+const cat = load(tandem);
+expect("catalog: indexes every item in both sources", cat.items.some((x) => x.source === "shared" && x.path === "notes/launch.md") && cat.items.some((x) => x.source === "venture" && x.path === "purpose/validation/problem.json") && stats.errors.length === 0, JSON.stringify(stats));
+expect("catalog: every item has an address and its version", cat.items.every((x) => x.address === `${x.source}://${x.path}` && /^[0-9a-f]{40}$/.test(x.version)));
+expect("catalog: records are tied to their routes, wherever they live", cat.items.find((x) => x.address === "shared://products/kettle.json")?.route === "product/kettle" && cat.items.find((x) => x.path === "purpose/validation/problem.json")?.route === "foundation/problem");
+const s1 = search(cat, "kettle subscription spring");
+expect("catalog: search finds an item in the mapped source", s1[0]?.address === "shared://notes/launch.md" && s1[0].title === "Launch plan", JSON.stringify(s1.slice(0, 2)));
+const research = readFileSync(join(tandem, "knowledge/research/pilot-2026-10.md"), "utf8");
+expect("catalog: search finds an item in the venture folder", search(cat, "pilot").some((x) => x.address === "venture://knowledge/research/pilot-2026-10.md"));
+const raw = readFileSync(join(tandem, FILE), "utf8");
+const phrase = research.split("\n").find((l) => l.split(" ").length > 6)?.slice(0, 40);
+expect("catalog: keeps no content (no sentence of an item appears in it)", phrase && !raw.includes(phrase) && !raw.includes("Ship the kettle subscription"), phrase);
+const again = (await build(tandem)).stats;
+expect("catalog: a rebuild with nothing changed reads nothing", again.read === 0 && again.reused === stats.items, JSON.stringify(again));
+write(shared, { "notes/later.md": "# Later\n\nAdded after the first build.\n" });
+const changed = (await build(tandem)).stats;
+expect("catalog: after a change, a rebuild reads only the new item", changed.read === 1 && load(tandem).items.some((x) => x.address === "shared://notes/later.md"), JSON.stringify(changed));
+
+// ---- Matrix (EE-042) ------------------------------------------------------------------------------
+console.log("\n# source-of-truth matrix");
+const { resolve: resolveRule } = await import("./resolve.mjs");
+const { sourceFor } = await import("./index.mjs");
+const rule = (o) => ({ record: "product", attribute: "*", phase: "*", product: "*", account: "*", actor: "*", owner: "founder", ...o });
+const matrix = { sources: map.sources, records: {}, rules: [
+  rule({ system_of_record: "venture" }),
+  rule({ phase: "validation", system_of_record: "shared" }),
+  rule({ product: "kettle", phase: "validation", system_of_record: "venture", note: "the kettle stays in the folder" }),
+  rule({ attribute: "price", system_of_record: "shared" }),
+] };
+expect("matrix: the most specific rule wins", resolveRule(matrix, { record: "product", phase: "validation", product: "kettle" }).rule.note === "the kettle stays in the folder");
+expect("matrix: a rule narrowed to a phase holds only in that phase", resolveRule(matrix, { record: "product", phase: "validation" }).rule.system_of_record === "shared" && resolveRule(matrix, { record: "product", phase: "scale" }).rule.system_of_record === "venture");
+expect("matrix: a field the query leaves out matches only \"*\"", resolveRule(matrix, { record: "product" }).rule.system_of_record === "venture");
+expect("matrix: an attribute rule answers for that attribute, not for whole-record reads", resolveRule(matrix, { record: "product", attribute: "price" }).rule.attribute === "price" && resolveRule(matrix, { record: "product" }).rule.attribute === "*");
+expect("matrix: a record type no rule names falls back to the records shorthand, then to nothing", resolveRule({ records: { account: "shared" } }, { record: "account" }).rule.system_of_record === "shared" && resolveRule(matrix, { record: "telos" }) === null);
+expect("matrix: two rules that hold at once at the same specificity tie", resolveRule({ rules: [rule({ phase: "validation", system_of_record: "a" }), rule({ actor: "agent", system_of_record: "b" })] }, { record: "product", phase: "validation", actor: "agent" }).ties.length === 2);
+write(tandem, { "knowledge/sources.json": JSON.stringify(matrix, null, 2) + "\n" });
+expect("matrix: sourceFor reads the venture's phase from venture.json (tandem is in validation)", sourceFor(tandem, "product").id === "shared" && sourceFor(tandem, "product", { product: "kettle" }).id === "venture");
+const viaRouter = await call({ venture: "tandem", route: "purpose/product/teapot", action: "read" });
+const kettleWrite = await call({ venture: "tandem", route: "purpose/product/kettle", action: "write", input: { ...kettle, name: "Kettle (kept in the folder)" }, actor: "person" });
+expect("matrix: the router routes each read and write by its context", viaRouter.source?.source === "shared" && kettleWrite.ok && existsSync(join(tandem, "products/kettle.json")) && JSON.parse(readFileSync(join(shared, "products/kettle.json"), "utf8")).name === "Kettle (in the shared folder)", JSON.stringify([viaRouter.source, kettleWrite]));
+expect("matrix: check-sources accepts the matrix", srcCheck(ws).status === 0, srcCheck(ws).stderr);
+write(tandem, { "knowledge/sources.json": JSON.stringify({ ...matrix, rules: [...matrix.rules, rule({ actor: "agent", system_of_record: "venture" })] }, null, 2) + "\n" });
+const tie = srcCheck(ws);
+expect("matrix: check-sources refuses two rules that can tie", tie.status === 1 && /tie at the same specificity/.test(tie.stderr), tie.stderr);
+const tieRead = await call({ venture: "tandem", route: "purpose/product", action: "read", actor: "agent" });
+expect("matrix: a read that two rules tie on fails and says so", !tieRead.ok && /tie at the same specificity/.test(tieRead.error), tieRead.error);
+
+// Attributes mastered elsewhere: the product's description lives in the shared folder, the rest
+// of the product in the venture folder.
+const byAttr = { sources: map.sources, records: {}, rules: [rule({ system_of_record: "venture" }), rule({ attribute: "description", system_of_record: "shared" })] };
+write(tandem, { "knowledge/sources.json": JSON.stringify(byAttr, null, 2) + "\n" });
+write(shared, { "products/shop-app.json": JSON.stringify({ description: "Mastered in the shared folder" }, null, 2) + "\n" });
+const shop = await call({ venture: "tandem", route: "purpose/product/shop-app", action: "read" });
+expect("attributes: a read fills each attribute from its own system of record and cites it", shop.result?.description === "Mastered in the shared folder" && shop.source?.source === "venture" && shop.source.attributes?.description?.address === "shared://products/shop-app.json", JSON.stringify(shop.source));
+const shopList = await call({ venture: "tandem", route: "purpose/product", action: "read" });
+expect("attributes: list reads overlay too", shopList.result?.["shop-app"]?.description === "Mastered in the shared folder");
+write(shared, { "products/kettle.json": "{}\n" });
+const noFrag = await call({ venture: "tandem", route: "purpose/product/kettle", action: "read" });
+expect("attributes: a source holding nothing for the attribute leaves the record's own value and says so", noFrag.result?.name === "Kettle (kept in the folder)" && noFrag.result?.description === kettle.description && noFrag.source.attributes?.description?.missing === true, JSON.stringify(noFrag.source));
+const shopWrite = await call({ venture: "tandem", route: "purpose/product/shop-app", action: "write", input: { ...shop.result, description: "Changed once, in one place" }, actor: "person", provenance: { note: "new description" } });
+const own = JSON.parse(readFileSync(join(tandem, "products/shop-app.json"), "utf8"));
+const frag = JSON.parse(readFileSync(join(shared, "products/shop-app.json"), "utf8"));
+expect("attributes: a write sends the attribute to its system of record and leaves it out of the record's own file", shopWrite.ok && frag.description === "Changed once, in one place" && !("description" in own) && shopWrite.result.attributes?.[0]?.written === "shared://products/shop-app.json", JSON.stringify(shopWrite));
+expect("attributes: the attribute write is logged by address and attribute", entries(tandem).some((x) => x.entity === "shared://products/shop-app.json#description"));
+const after = await call({ venture: "tandem", route: "purpose/product/shop-app", action: "read" });
+expect("attributes: the next read shows the one value", after.result?.description === "Changed once, in one place");
+const badAttr = await call({ venture: "tandem", route: "purpose/product/shop-app", action: "write", input: { id: "shop-app" }, actor: "person" });
+expect("attributes: a record that fails its schema writes nothing anywhere", !badAttr.ok && JSON.parse(readFileSync(join(shared, "products/shop-app.json"), "utf8")).description === "Changed once, in one place");
+write(tandem, { "knowledge/sources.json": JSON.stringify({ ...byAttr, sources: [{ ...map.sources[0], writes: "none" }] }, null, 2) + "\n" });
+const roAttr = await call({ venture: "tandem", route: "purpose/product/shop-app", action: "write", input: after.result, actor: "person" });
+expect("attributes: a write whose attribute is mastered in a read-only source is refused before anything lands", !roAttr.ok && /read-only/.test(roAttr.error));
+write(tandem, { "knowledge/sources.json": JSON.stringify(map, null, 2) + "\n" });
+
+finish();