naive-framework 0.0.0-stage → 0.1.0

package/knowledge/connectors/filesystem.mjs

@@ -0,0 +1,79 @@
+// The file system connector (EE-037): a folder, inside a git repository or not. It is the default
+// source: a venture without a source map keeps every record in its own folder, through this.
+//
+//   root     the folder (absolute)
+//   writes   direct (default) or none
+//   venture  true when the root is a venture folder: listing stops at a nested venture (it has
+//            its own records) and skips the venture's private _ folders, as the router always has
+//
+// version is the git blob SHA-1 of the content. When the file is committed and unchanged, read
+// also gives the last commit that touched it.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { blobSha, isText, matches, safePath } from "./contract.mjs";
+
+const SKIP = new Set(["node_modules"]);
+
+export function connect({ id = "venture", root, writes = "direct", venture = false } = {}) {
+  if (!root) throw new Error("the filesystem connector needs a root folder");
+  if (writes === "pull-request") throw new Error("the filesystem connector writes direct or none");
+
+  const walk = (d, rel = "") => !existsSync(d) ? [] : readdirSync(d, { withFileTypes: true }).flatMap((e) => {
+    if (e.name.startsWith(".") || SKIP.has(e.name)) return [];
+    const r = rel ? `${rel}/${e.name}` : e.name;
+    if (e.isDirectory()) {
+      if (venture && (existsSync(join(d, e.name, "venture.json")) || (!rel && e.name.startsWith("_")))) return [];
+      return walk(join(d, e.name), r);
+    }
+    return e.isFile() ? [r] : [];
+  });
+  const file = (p) => join(root, safePath(p));
+  const git = (...args) => spawnSync("git", ["-C", root, ...args], { encoding: "utf8" });
+  const lastCommit = (p, content) => {
+    const tracked = git("ls-files", "-s", "--", p);
+    if (tracked.status !== 0 || !tracked.stdout) return null;
+    if (tracked.stdout.split(/\s+/)[1] !== blobSha(content) || git("diff", "--quiet", "HEAD", "--", p).status !== 0) return null;
+    return git("log", "-1", "--format=%H", "--", p).stdout.trim() || null;
+  };
+
+  const c = {
+    id, kind: "filesystem", writes, root,
+    async list(prefix = "") {
+      const pre = prefix ? safePath(prefix) : "";
+      return walk(root).filter((p) => !pre || p === pre || p.startsWith(`${pre}/`)).sort()
+        .map((path) => ({ path, version: blobSha(readFileSync(join(root, path))) }));
+    },
+    async read(p) {
+      const f = file(p);
+      if (!existsSync(f) || !statSync(f).isFile()) return null;
+      const content = readFileSync(f, "utf8");
+      const commit = lastCommit(safePath(p), content);
+      return { path: safePath(p), content, version: blobSha(readFileSync(f)), ...(commit ? { commit } : {}) };
+    },
+    async version(p) {
+      const f = file(p);
+      return existsSync(f) && statSync(f).isFile() ? blobSha(readFileSync(f)) : null;
+    },
+    async search(query, { limit = 50 } = {}) {
+      const out = [];
+      for (const path of walk(root).sort()) {
+        if (out.length >= limit) break;
+        const content = readFileSync(join(root, path), "utf8");
+        if (isText(path, content) && matches(`${path}\n${content}`, query)) out.push({ path, version: blobSha(content) });
+      }
+      return out;
+    },
+    async write(p, content, _opts = {}) {
+      if (writes === "none") throw new Error(`${id} is read-only`);
+      const f = file(p);
+      mkdirSync(dirname(f), { recursive: true });
+      const tmp = `${f}.tmp-${process.pid}`;
+      writeFileSync(tmp, content);
+      renameSync(tmp, f);
+      return { path: safePath(p), version: blobSha(content) };
+    },
+  };
+  return c;
+}

package/knowledge/connectors/index.mjs

@@ -0,0 +1,102 @@
+// Sources and connectors (EE-037). The knowledge layer federates: records stay in the sources a
+// venture already uses, and the router reaches each through a connector with one contract
+// (contract.mjs). Nothing is copied.
+//
+//   The registry   knowledge/tooling/integrations.json: an integration with a `connector` names
+//                  the module that implements the contract for it.
+//   A source map   <venture>/knowledge/sources.json (optional): the venture's sources, and which
+//                  record types live in which source. A record type it does not name, and every
+//                  record of a venture without a map, lives in the venture's own folder (the
+//                  `venture` source). The venture folder itself (venture.json, the provenance log,
+//                  drafts) always stays on the file system.
+//
+// A record keeps its route's file path inside whatever source holds it: products/kettle.json is
+// products/kettle.json under the source's root.
+
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { conformance } from "./contract.mjs";
+import { ANY, resolve as resolveRule } from "./resolve.mjs";
+
+const repo = new URL("../..", import.meta.url).pathname;
+const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+export const MAP = "knowledge/sources.json";
+export const LOCAL = "venture";
+
+let fetchImpl = null;
+/** Points every GitHub-style connector at another fetch (the evals' fake GitHub); null restores the real one. */
+export const useFetch = (f) => { fetchImpl = f; };
+
+/** The connector registry: integration id -> { module, writes, ... } from knowledge/tooling/integrations.json. */
+export function registry() {
+  return new Map(load(join(repo, "knowledge/tooling/integrations.json")).filter((t) => t.connector).map((t) => [t.id, { id: t.id, name: t.name, ...t.connector }]));
+}
+
+/** A venture's source map, with the implicit venture source first. */
+export function sourcesOf(dir) {
+  const own = existsSync(join(dir, MAP)) ? load(join(dir, MAP)) : { sources: [], records: {} };
+  return { sources: [{ id: LOCAL, connector: "filesystem", root: ".", writes: "direct", implicit: true }, ...(own.sources ?? [])], records: own.records ?? {}, rules: own.rules ?? [], mapped: existsSync(join(dir, MAP)) };
+}
+
+/**
+ * The source a record type lives in, for a context (EE-042): the system of record of the most
+ * specific rule that holds (resolve.mjs). The venture's phase comes from venture.json; product,
+ * account and actor come from the caller. With no rule, the venture's own folder.
+ */
+export function sourceFor(dir, recordType, context = {}) {
+  const m = sourcesOf(dir);
+  let phase;
+  try { phase = JSON.parse(readFileSync(join(dir, "venture.json"), "utf8")).phase; } catch {}
+  const hit = resolveRule(m, { record: recordType, ...(phase ? { phase } : {}), ...context });
+  if (hit?.ties.length) throw new Error(`${MAP}: ${hit.ties.length} rules for ${recordType} tie at the same specificity; make one more specific`);
+  const id = hit?.rule.system_of_record ?? LOCAL;
+  const s = m.sources.find((x) => x.id === id);
+  if (!s) throw new Error(`${MAP} puts ${recordType} in ${id}, which is not one of its sources`);
+  return s;
+}
+
+/**
+ * The attributes of a record type mastered somewhere other than the record itself, for a context
+ * (EE-042): [{ attribute, source }]. Such an attribute is kept in its source at the record's own
+ * path, as a JSON object holding only that attribute ({ "price": 12 }); a vendor's connector maps
+ * that onto its own system. The router reads each one from there and writes it there.
+ */
+export function attributeSources(dir, recordType, context = {}) {
+  const m = sourcesOf(dir);
+  const whole = sourceFor(dir, recordType, context);
+  let phase;
+  try { phase = JSON.parse(readFileSync(join(dir, "venture.json"), "utf8")).phase; } catch {}
+  const names = [...new Set((m.rules ?? []).filter((r) => r.record === recordType && r.attribute !== ANY).map((r) => r.attribute))];
+  return names.flatMap((attribute) => {
+    const hit = resolveRule(m, { record: recordType, attribute, ...(phase ? { phase } : {}), ...context });
+    if (!hit || hit.rule.attribute === ANY) return [];
+    if (hit.ties.length) throw new Error(`${MAP}: ${hit.ties.length} rules for ${recordType}.${attribute} tie at the same specificity; make one more specific`);
+    const source = m.sources.find((x) => x.id === hit.rule.system_of_record);
+    if (!source) throw new Error(`${MAP} masters ${recordType}.${attribute} in ${hit.rule.system_of_record}, which is not one of its sources`);
+    return source.id === whole.id ? [] : [{ attribute, source }];
+  });
+}
+
+const cache = new Map();
+/** A connected connector for one source of one venture. */
+export async function connect(source, dir) {
+  const reg = registry().get(source.connector);
+  if (!reg) throw new Error(`no connector ${source.connector}: knowledge/tooling/integrations.json has ${[...registry().keys()].join(", ")}`);
+  const mod = cache.get(reg.module) ?? await import(join(repo, reg.module));
+  cache.set(reg.module, mod);
+  const opts = { ...source };
+  delete opts.connector; delete opts.implicit;
+  if (source.connector === "filesystem") {
+    opts.root = isAbsolute(source.root ?? ".") ? source.root : resolve(dir, source.root ?? ".");
+    opts.venture = source.id === LOCAL;
+  } else if (fetchImpl) opts.fetch = fetchImpl;
+  const c = mod.connect(opts);
+  const problems = conformance(c);
+  if (problems.length) throw new Error(`${reg.module} does not meet the connector contract: ${problems.join("; ")}`);
+  return c;
+}
+
+/** Every source of a venture, connected. */
+export async function connectAll(dir) {
+  return Promise.all(sourcesOf(dir).sources.map(async (s) => ({ source: s, connector: await connect(s, dir) })));
+}

package/knowledge/connectors/resolve.mjs

@@ -0,0 +1,44 @@
+// The source-of-truth matrix (EE-042). A venture's source map may hold rules: each names, for one
+// record type in one context, its system of record (the source reads come from and writes go to)
+// and its owner. Rules are written for a fast model to read: flat, one context per rule, every
+// context field present, "*" meaning any. Resolution itself is deterministic and needs no model:
+// the matching rule with the most fields that are not "*" wins; a tie is an error the check
+// reports. A record type no rule names falls back to `records` (the EE-037 shorthand) and then to
+// the venture's own folder.
+//
+//   context   phase      the venture's phase (venture.json), or "*"
+//             product    the product id the record is about, or "*"
+//             account    the account id the record is about, or "*"
+//             actor      person or agent, or "*"
+//   attribute            "*" for the whole record, or one top-level field; an attribute rule
+//                        names where that field is mastered (a price in Stripe, say). The router
+//                        reads that field from there and writes it there (index.mjs,
+//                        attributeSources), so the record's own file never holds a second copy.
+
+export const ANY = "*";
+export const CONTEXT = ["phase", "product", "account", "actor"];
+export const FIELDS = ["record", "attribute", ...CONTEXT];
+
+/** How many fields of a rule narrow it (the record type itself always matches). */
+export const specificity = (rule) => ["attribute", ...CONTEXT].filter((k) => rule[k] !== ANY).length;
+
+/** The rules a map states, the `records` shorthand included as rules that match anything. */
+export function rulesOf(map) {
+  const short = Object.entries(map.records ?? {}).map(([record, system_of_record]) => ({ record, attribute: ANY, phase: ANY, product: ANY, account: ANY, actor: ANY, system_of_record, shorthand: true }));
+  return [...(map.rules ?? []), ...short];
+}
+
+/**
+ * The rule that holds for a query: { record, attribute?, phase?, product?, account?, actor? }.
+ * A field left out of the query matches only "*" in a rule, so a rule narrowed to a product never
+ * applies to a read that names no product. Returns { rule, specificity, ties } or null.
+ */
+export function resolve(map, query) {
+  const q = { attribute: ANY, ...query };
+  const fits = (rule) => rule.record === q.record && ["attribute", ...CONTEXT].every((k) => rule[k] === ANY || rule[k] === q[k]);
+  const hits = rulesOf(map).filter(fits).map((rule) => ({ rule, specificity: specificity(rule) - (rule.shorthand ? 0.5 : 0) }));
+  if (!hits.length) return null;
+  hits.sort((a, b) => b.specificity - a.specificity);
+  const ties = hits.filter((h) => h.specificity === hits[0].specificity).map((h) => h.rule);
+  return { rule: hits[0].rule, specificity: Math.ceil(hits[0].specificity), ties: ties.length > 1 ? ties : [] };
+}

package/knowledge/connectors/suite.mjs

@@ -0,0 +1,80 @@
+// The connector contract suite (EE-037), shared by every connector's evals: the framework's
+// (knowledge/connectors/eval.mjs) and the platform's (platform/connectors/eval.mjs). A connector
+// written anywhere proves itself against this one suite (EE-041).
+//
+//   const h = harness("name");          expect, throws, gitHash, write, scratch, finish
+//   await contract(h, "label", make);   make(opts) -> { c, base(path), later(path, branch), pulls() }
+
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { blobSha, conformance } from "./contract.mjs";
+
+export function harness(name) {
+  let failed = 0, passed = 0, skipped = 0;
+  const scratch = mkdtempSync(join(tmpdir(), `mentura-${name}-`));
+  return {
+    scratch,
+    expect: (n, ok, detail = "") => { console.log(`${ok ? "ok  " : "FAIL"} ${n}${!ok && detail ? `\n       ${detail}` : ""}`); ok ? passed++ : failed++; },
+    throws: async (f, re) => { try { await f(); return false; } catch (e) { return re ? re.test(e.message) : true; } },
+    skip: (why) => { console.log(`skip ${why}`); skipped++; },
+    gitHash: (content) => spawnSync("git", ["hash-object", "--stdin"], { input: content, encoding: "utf8" }).stdout.trim(),
+    write: (root, files) => { for (const [p, c] of Object.entries(files)) { mkdirSync(dirname(join(root, p)), { recursive: true }); writeFileSync(join(root, p), c); } },
+    finish: () => {
+      rmSync(scratch, { recursive: true, force: true });
+      console.log(`\n${passed} passed, ${failed} failing${skipped ? `, ${skipped} skipped` : ""}`);
+      process.exit(failed ? 1 : 0);
+    },
+  };
+}
+
+// The fixture: three items under the source's root, one outside it that must never show.
+export const FIXTURE = {
+  "notes/alpha.md": "# Alpha\n\nThe kettle pilot ran in October with nine households.\n",
+  "notes/beta.md": "# Beta\n\nPricing interviews: most would pay monthly.\n",
+  "records/item.json": JSON.stringify({ id: "item", name: "Item one", tags: ["fixture"] }, null, 2) + "\n",
+};
+export const OUTSIDE = { "other/secret.md": "# Outside\n\nkettle text outside the root\n" };
+export const UNICODE = "# Café ☕\n\nLine one\nLine two with ünïcode, emoji 🫖 and a tab\tend\n";
+
+// ---- Contract ----------------------------------------------------------------------------------
+// make() gives { c, base(path) -> content on the branch or folder reads come from, later(path) ->
+// content where a write lands (the folder, or the pull request's branch), pulls() }.
+export async function contract({ expect, throws, gitHash }, name, make) {
+  console.log(`\n# contract: ${name}`);
+  const t = await make();
+  const { c } = t;
+  expect(`${name}: meets the contract (list, read, version, search, write; writes ${c.writes})`, conformance(c).length === 0, conformance(c).join("; "));
+  const listed = await c.list();
+  expect(`${name}: list gives every item under the root and nothing outside it, sorted`, JSON.stringify(listed.map((x) => x.path)) === JSON.stringify(Object.keys(FIXTURE).sort()), JSON.stringify(listed.map((x) => x.path)));
+  expect(`${name}: list gives each item's version as its git blob SHA-1`, listed.every((x) => x.version === blobSha(FIXTURE[x.path])));
+  expect(`${name}: list(prefix) keeps to the prefix`, JSON.stringify((await c.list("notes")).map((x) => x.path)) === JSON.stringify(["notes/alpha.md", "notes/beta.md"]));
+  const a = await c.read("notes/alpha.md");
+  expect(`${name}: read gives the exact content`, a?.content === FIXTURE["notes/alpha.md"]);
+  expect(`${name}: read's version is what git hash-object prints for the content`, a?.version === gitHash(FIXTURE["notes/alpha.md"]), `${a?.version} vs ${gitHash(FIXTURE["notes/alpha.md"])}`);
+  expect(`${name}: version(path) matches read`, (await c.version("notes/alpha.md")) === a?.version);
+  expect(`${name}: JSON reads back as the same JSON`, JSON.parse((await c.read("records/item.json"))?.content ?? "null")?.name === "Item one");
+  expect(`${name}: a missing item reads as null, and has no version`, (await c.read("notes/nope.md")) === null && (await c.version("notes/nope.md")) === null);
+  expect(`${name}: a path that leaves the root is refused`, await throws(() => c.read("../other/secret.md"), /not a path inside/) && await throws(() => c.read("/etc/passwd"), /not a path inside/) && await throws(() => c.write("a/../../x.md", "x"), /not a path inside/));
+  const hits = await c.search("kettle pilot");
+  expect(`${name}: search finds the item holding every word, and only inside the root`, JSON.stringify(hits.map((x) => x.path)) === JSON.stringify(["notes/alpha.md"]) && hits[0].version === a?.version, JSON.stringify(hits));
+  expect(`${name}: search for words in no item finds nothing`, (await c.search("zebra quantum")).length === 0);
+  if (c.writes === "direct") {
+    const w = await c.write("notes/gamma.md", UNICODE);
+    expect(`${name}: a direct write lands in place and returns the new version`, w.version === blobSha(UNICODE) && (await c.read("notes/gamma.md"))?.content === UNICODE);
+    const w2 = await c.write("notes/alpha.md", FIXTURE["notes/alpha.md"] + "Added.\n");
+    expect(`${name}: overwriting changes the version`, w2.version !== a.version && (await c.version("notes/alpha.md")) === w2.version);
+    expect(`${name}: a written item is listed`, (await c.list()).some((x) => x.path === "notes/gamma.md"));
+  } else if (c.writes === "pull-request") {
+    const w = await c.write("notes/gamma.md", UNICODE, { message: "Add gamma" });
+    expect(`${name}: a write opens a draft pull request and returns its link and the new version`, /\/pull\/\d+$/.test(w.pull_request?.url ?? "") && w.version === blobSha(UNICODE) && t.pulls().at(-1)?.draft === true, JSON.stringify(w));
+    expect(`${name}: the branch reads come from is unchanged until the pull request is merged`, (await c.read("notes/gamma.md")) === null && t.base("notes/gamma.md") === null);
+    expect(`${name}: the pull request's branch holds the exact content`, t.later("notes/gamma.md", w.pull_request.branch) === UNICODE);
+    const w2 = await c.write("notes/alpha.md", FIXTURE["notes/alpha.md"] + "Added.\n");
+    expect(`${name}: overwriting an existing item opens its own pull request`, w2.pull_request.branch !== w.pull_request.branch && t.later("notes/alpha.md", w2.pull_request.branch).endsWith("Added.\n") && t.base("notes/alpha.md") === FIXTURE["notes/alpha.md"]);
+  }
+  const ro = await make({ writes: "none" });
+  expect(`${name}: a read-only source refuses writes`, await throws(() => ro.c.write("notes/x.md", "x"), /read-only/));
+  return t;
+}

package/knowledge/layer.json

@@ -0,0 +1,42 @@
+{
+  "layer": "knowledge",
+  "purpose": "The memory layer: where every record is stored. The other layers each define the records they write here and the conventions for them; this layer defines only how a record is stored and found (route, schema, provenance), the decision log, the venture profile, design documents and the sources behind them. Storage is federated: records stay in the sources a venture already uses (its own folder by default, or a GitHub repository), reached through connectors with one contract, found through a catalog that copies no content (EE-036, EE-037).",
+  "product": "everything-ecosystem/knowledge-kit",
+  "skills": [
+    {
+      "id": "find-reference",
+      "path": "knowledge/skills/find-reference/SKILL.md",
+      "standalone": true
+    },
+    {
+      "id": "industry-awareness",
+      "path": "knowledge/skills/industry-awareness/SKILL.md"
+    }
+  ],
+  "records": [
+    "venture-profile",
+    "decision",
+    "design-document",
+    "nextjs-status",
+    "knowledge-sources",
+    "where-used"
+  ],
+  "reads": [
+    "venture",
+    "product"
+  ],
+  "writes": [
+    "reference"
+  ],
+  "checks": [
+    "schema/check-sources.mjs",
+    "schema/check-where-used.mjs"
+  ],
+  "gaps": [
+    "No check on the venture profile or design documents of its own; design-coverage (evidence) is the only one",
+    "Two connectors so far (filesystem and GitHub); a database, Notion, Slack or Salesforce each need their own module meeting the same contract",
+    "Checks and command routes (need-now, time-to-ready, validation score) still read the venture folder, so they do not yet see a record kept in another source",
+    "A merged pull request is not logged as an accept in provenance; the read after the merge is the only sign"
+  ],
+  "name": "knowledge"
+}

package/knowledge/skills/find-reference/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: find-reference
+description: "Find, confirm and record the source behind a reference in a layer's references/references.json: fill a missing URL from title, authors and year, re-check URLs that may have rotted, and add new references with a stance. Triggers: add a reference, cite this, where does this term come from, find the source for, check the references, a reference has no url. Do not trigger for general web research that will not be recorded as a reference."
+type: skill
+source: hybrid
+created: 2026-10-27T04:16:38Z
+ai-model: claude-opus-5.5
+tags: [skill, everything-ecosystem, knowledge, references]
+---
+
+# find-reference
+
+The system is opinionated: each layer names one default for each choice, and its references say where the default came from and what the alternatives were (EE-014). This skill keeps those references findable.
+
+## Where references live
+
+One file per layer: `<layer>/references/references.json`, checked by `schema/reference.schema.json`. Each record has an id, title, authors, year, kind, summary, what it informs (`phase:validation`, `noun:wedge`, `field:venture.industry`), and a stance (adopted, adapted, alternative or rejected, with why). A url and the date it was last checked are recorded when a page exists.
+
+## Fill a missing URL
+
+1. Search with the exact title, the first author's surname and the year.
+2. Prefer, in order: the author's or publisher's own page, a standards body, a library or DOI record, an archive copy (for example web.archive.org or a maintained mirror), then a reputable summary. Never a page that only quotes a snippet.
+3. Open the page and confirm the title, author and year match. If they differ, fix the record or say which part could not be confirmed.
+4. Write `url` and `checked` (today, from `date -u +%F`). If nothing confirms it, leave the url out and add one line to the summary saying what was searched.
+
+## Re-check URLs
+
+Re-check any url whose `checked` date is older than 180 days, or when a reader reports it broken. If it no longer resolves, look for the same work on an archive or the publisher's new site, and update the url. Never delete the record: the title, authors and year still identify the work.
+
+## Add a reference
+
+Add one when a default, a noun or a gate is chosen because of a source, or when an alternative was weighed and set aside. Write the summary in your own words (one or two sentences), set `informs` to the nouns, phases, gates or fields it backs, and give the stance with a one-line why. A source that is a conversation (for example an AI chat a founder shared) gets kind `conversation` and no url.
+
+## Rules
+
+- Standards first: when a published standard exists, cite it and use its term with its meaning (EE-014).
+- A reference informs a decision; it never makes one. The decision log records the choice.
+- Keep each layer's file to the sources that layer's defaults rest on.