naive-framework 0.1.0 → 0.3.0

package/interface/vitals.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Agent vitals (N-6): Naive's Core Web Vitals. Where Next.js measures time to first byte and time to
+// interactive, Naive measures what it costs an agent to get work done through the router:
+//
+//   calls_per_task      router calls an agent makes in one session (a task)
+//   tokens_per_call     tokens of context each call sends back
+//   time_to_useful_ms   time from a session's first call to its first useful answer
+//   decision_hours      time from a decision opening to a person deciding it (open ones count their age)
+//
+// Like Web Vitals, each is assessed at the 75th percentile and checked against a threshold (C-15),
+// so vitals are checked, not only measured. Calls and judgments come from the events log that
+// instrumentation writes (interface/instrumentation.mjs); decisions come from provenance.jsonl, so
+// decision latency is measured even with instrumentation off. Thresholds are the defaults below,
+// overridden by "vitals" in the venture's naive.config.json.
+//
+//   node interface/vitals.mjs <venture dir> [--json] [--check]     --check exits 1 when a vital fails
+//   node interface/vitals.mjs <venture dir> --trace [--session <id>] the events as a trace, for
+//                                                                   platform/integrations/langsmith.mjs
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { events } from "./instrumentation.mjs";
+import { entries } from "./provenance.mjs";
+import { ventureFile } from "../schema/venture-paths.mjs";
+
+export const THRESHOLDS = { calls_per_task: 25, tokens_per_call: 6000, time_to_useful_ms: 10000, decision_hours: 72 };
+const DECISION = /(^|\/)decisions\/[^/]+\.decision\.json$/;
+
+/** The 75th percentile, nearest rank. */
+export const p75 = (xs) => { if (!xs.length) return null; const s = [...xs].sort((a, b) => a - b); return s[Math.ceil(0.75 * s.length) - 1]; };
+const startOf = (e) => Date.parse(e.at) - (e.ms ?? 0);
+const config = (dir) => { const f = join(ventureFile(dir, "naive.config.json")); try { return existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : {}; } catch { return {}; } };
+
+/** Top-level calls grouped by session: one task per session. */
+export function tasks(dir) {
+  const calls = events(dir).filter((e) => e.kind === "call" && !e.parent);
+  const judgments = events(dir).filter((e) => e.kind === "judgment");
+  const by = new Map();
+  for (const e of calls) { const k = e.session ?? "(no session)"; if (!by.has(k)) by.set(k, []); by.get(k).push(e); }
+  return [...by.entries()].map(([session, es]) => {
+    const t0 = Math.min(...es.map(startOf));
+    const useful = es.filter((e) => e.useful).sort((a, b) => Date.parse(a.at) - Date.parse(b.at))[0];
+    return { session, calls: es.length, tokens_per_call: Math.round(es.reduce((n, e) => n + (e.tokens ?? 0), 0) / es.length), max_tokens: Math.max(...es.map((e) => e.tokens ?? 0)),
+      time_to_useful_ms: useful ? Date.parse(useful.at) - t0 : null, judgments: judgments.filter((j) => (j.session ?? "(no session)") === session).length };
+  });
+}
+
+/** Each decision the provenance log saw open: when it opened, when a person decided it, and the hours between. */
+export function decisionLatency(dir, now = Date.now()) {
+  const by = new Map();
+  for (const e of entries(dir).filter((x) => DECISION.test(x.entity ?? ""))) {
+    const d = by.get(e.entity) ?? { file: e.entity, opened: null, decided: null };
+    if (!d.opened) d.opened = e.at;
+    if (e.activity === "accept" && !d.decided) d.decided = e.at;
+    by.set(e.entity, d);
+  }
+  return [...by.values()].map((d) => {
+    let id = d.file.split("/").at(-1).replace(/\.decision\.json$/, "");
+    try { id = JSON.parse(readFileSync(ventureFile(dir, d.file), "utf8")).id ?? id; } catch {}
+    const end = d.decided ? Date.parse(d.decided) : now;
+    return { id, ...d, open: !d.decided, hours: Math.round(((end - Date.parse(d.opened)) / 36e5) * 100) / 100 };
+  });
+}
+
+/** The venture's vitals, each at p75 against its threshold. */
+export function vitals(dir, now = Date.now()) {
+  const limits = { ...THRESHOLDS, ...(config(dir).vitals ?? {}) };
+  const ts = tasks(dir), ds = decisionLatency(dir, now);
+  const measure = (name, xs, never = 0) => {
+    const v = p75(xs);
+    const n = xs.length + never;
+    const passed = n === 0 ? null : never > 0 && never / n > 0.25 ? false : v === null ? false : v <= limits[name];
+    return { p75: v, threshold: limits[name], n, passed, status: passed === null ? "no data" : passed ? "good" : "needs work", ...(never ? { never_useful: never } : {}) };
+  };
+  const out = {
+    calls_per_task: measure("calls_per_task", ts.map((t) => t.calls)),
+    tokens_per_call: measure("tokens_per_call", ts.map((t) => t.tokens_per_call)),
+    time_to_useful_ms: measure("time_to_useful_ms", ts.filter((t) => t.time_to_useful_ms !== null).map((t) => t.time_to_useful_ms), ts.filter((t) => t.time_to_useful_ms === null).length),
+    decision_hours: measure("decision_hours", ds.map((d) => d.hours)),
+  };
+  const failing = Object.entries(out).filter(([, v]) => v.passed === false).map(([k]) => k);
+  return { events: events(dir).length, tasks: ts, decisions: ds, vitals: out, passed: failing.length === 0, failing,
+    note: events(dir).length ? "p75 of each vital against its threshold (naive.config.json vitals overrides the defaults)" : "no events yet: turn instrumentation on in naive.config.json ({\"instrumentation\": {\"events\": true}}) to measure calls, tokens and time to a useful answer" };
+}
+
+/** The events as one trace (root run per session, a child per call, nested calls under their parent), with the vitals as feedback. */
+export function trace(dir, session) {
+  const es = events(dir).filter((e) => !session || (e.session ?? "(no session)") === session);
+  const calls = es.filter((e) => e.kind === "call");
+  const node = (e) => ({ name: `${e.action} ${e.route}`, run_type: e.action === "run" ? "tool" : "retriever", start: new Date(startOf(e)).toISOString(), end: e.at,
+    inputs: { venture: e.venture, route: e.route, action: e.action }, outputs: { ok: e.ok, useful: e.useful, tokens: e.tokens, ms: e.ms }, ...(e.ok ? {} : { error: "call failed" }),
+    metadata: { via: e.via, actor: e.actor }, children: calls.filter((c) => c.parent === e.id).map(node) });
+  const judged = es.filter((e) => e.kind === "judgment").map((e) => ({ name: `judgment ${e.question ?? e.route ?? ""}`.trim(), run_type: "llm", start: new Date(Date.parse(e.at) - (e.ms ?? 0)).toISOString(), end: e.at,
+    inputs: { question: e.question, route: e.route }, outputs: { score: e.score, threshold: e.threshold, outcome: e.outcome }, metadata: { model: e.model, owner: e.owner } }));
+  const v = vitals(dir);
+  const start = es.length ? new Date(Math.min(...es.map((e) => Date.parse(e.at) - (e.ms ?? 0)))).toISOString() : new Date().toISOString();
+  const end = es.length ? es.at(-1).at : start;
+  return { name: `naive ${JSON.parse(readFileSync(join(dir, "venture.json"), "utf8")).id}${session ? ` ${session}` : ""}`, run_type: "chain", start, end,
+    inputs: { session: session ?? null }, outputs: { calls: calls.filter((c) => !c.parent).length, judgments: judged.length },
+    children: [...calls.filter((c) => !c.parent).map(node), ...judged].sort((a, b) => a.start.localeCompare(b.start)),
+    feedback: Object.entries(v.vitals).filter(([, x]) => x.passed !== null).map(([key, x]) => ({ key, score: x.passed ? 1 : 0, comment: `p75 ${x.p75} against ${x.threshold}` })) };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const dir = process.argv[2];
+  if (!dir || !existsSync(join(dir, "venture.json"))) { console.error("usage: node interface/vitals.mjs <venture dir> [--json] [--check] [--trace [--session <id>]]"); process.exit(2); }
+  const arg = (n) => { const i = process.argv.indexOf(`--${n}`); return i >= 0 ? process.argv[i + 1] : undefined; };
+  if (process.argv.includes("--trace")) { console.log(JSON.stringify(trace(dir, arg("session")), null, 2)); process.exit(0); }
+  const r = vitals(dir);
+  if (process.argv.includes("--json")) console.log(JSON.stringify(r, null, 2));
+  else {
+    console.log(`${r.events} events, ${r.tasks.length} tasks, ${r.decisions.length} decisions. ${r.note}`);
+    for (const [k, x] of Object.entries(r.vitals)) console.log(`  ${k.padEnd(18)} ${x.status.padEnd(10)} p75 ${x.p75 ?? "-"} (threshold ${x.threshold}, n ${x.n})`);
+  }
+  if (process.argv.includes("--check") && !r.passed) { console.error(`vitals failing: ${r.failing.join(", ")}`); process.exit(1); }
+}

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/catalog.mjs

@@ -15,6 +15,7 @@ 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";
+import { ventureFile } from "../../schema/venture-paths.mjs";
 
 export const FILE = "_catalog/catalog.json";
 const MAX_BYTES = 1_000_000;
@@ -50,7 +51,7 @@ async function routeOf(path) {
   return { route: null, record: null };
 }
 
-export const load = (dir) => existsSync(join(dir, FILE)) ? JSON.parse(readFileSync(join(dir, FILE), "utf8")) : null;
+export const load = (dir) => existsSync(ventureFile(dir, FILE)) ? JSON.parse(readFileSync(ventureFile(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 } = {}) {
@@ -75,7 +76,7 @@ export async function build(dir, { write = true, sources } = {}) {
   }
   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"); }
+  if (write) { mkdirSync(join(dir, "_catalog"), { recursive: true }); writeFileSync(ventureFile(dir, FILE), JSON.stringify(catalog) + "\n"); }
   return { catalog, stats };
 }
 

package/knowledge/connectors/filesystem.mjs

@@ -13,6 +13,7 @@ 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";
+import { layoutOf, logicalFiles, ventureFile } from "../../schema/venture-paths.mjs";
 
 const SKIP = new Set(["node_modules"]);
 
@@ -29,7 +30,11 @@ export function connect({ id = "venture", root, writes = "direct", venture = fal
     }
     return e.isFile() ? [r] : [];
   });
-  const file = (p) => join(root, safePath(p));
+  // A venture in the structured layout (EE-086) keeps its records in knowledge/ and meta/: read and write them
+  // by their logical paths, and list them that way, so routes never see the layout.
+  const structured = venture && layoutOf(root) === "structured";
+  const file = (p) => (structured ? ventureFile(root, safePath(p)) : join(root, safePath(p)));
+  const listed = () => structured ? logicalFiles(root).filter((r) => !r.split("/").some((s) => s.startsWith(".")) && !r.startsWith("_") && !r.startsWith("node_modules/")) : walk(root);
   const git = (...args) => spawnSync("git", ["-C", root, ...args], { encoding: "utf8" });
   const lastCommit = (p, content) => {
     const tracked = git("ls-files", "-s", "--", p);
@@ -42,8 +47,8 @@ export function connect({ id = "venture", root, writes = "direct", venture = fal
     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))) }));
+      return listed().filter((p) => !pre || p === pre || p.startsWith(`${pre}/`)).sort()
+        .map((path) => ({ path, version: blobSha(readFileSync(file(path))) }));
     },
     async read(p) {
       const f = file(p);
@@ -58,9 +63,9 @@ export function connect({ id = "venture", root, writes = "direct", venture = fal
     },
     async search(query, { limit = 50 } = {}) {
       const out = [];
-      for (const path of walk(root).sort()) {
+      for (const path of listed().sort()) {
         if (out.length >= limit) break;
-        const content = readFileSync(join(root, path), "utf8");
+        const content = readFileSync(file(path), "utf8");
         if (isText(path, content) && matches(`${path}\n${content}`, query)) out.push({ path, version: blobSha(content) });
       }
       return out;

package/knowledge/connectors/index.mjs

@@ -17,6 +17,7 @@ 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";
+import { ventureFile } from "../../schema/venture-paths.mjs";
 
 const repo = new URL("../..", import.meta.url).pathname;
 const load = (p) => JSON.parse(readFileSync(p, "utf8"));
@@ -34,8 +35,8 @@ export function registry() {
 
 /** 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)) };
+  const own = existsSync(ventureFile(dir, MAP)) ? load(ventureFile(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(ventureFile(dir, MAP)) };
 }
 
 /**

package/knowledge/freshness.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "../schema/freshness-profiles.schema.json",
+  "note": "Default freshness profiles (Revalidating, V-1 to V-3): how long a record stays fresh, by record type, after Next.js cacheLife profiles. A venture overrides any of them under freshness in its naive.config.json, as a Next.js app defines cacheLife profiles in next.config.js. stale: how long an agent may reuse what it read without reading it again. revalidate: after this the record is stale, still readable with a stale flag, and should be checked or redone. expire: after this it is expired and not frozen into a release. per_phase: the record is stale once the venture changes phase after it was last checked. live: a fast-changing record, never frozen into a release; it stays a live hole. Durations are seconds, or a number with s, m, h, d or w. Version 0.x: ours and unevaluated.",
+  "version": "0.1.0",
+  "default": "max",
+  "profiles": {
+    "live": {
+      "live": true,
+      "stale": "0s",
+      "revalidate": "7d",
+      "note": "Pipeline, money and streams: read from their system of record every time, synced at least weekly, never frozen"
+    },
+    "feedback": {
+      "stale": "1d",
+      "revalidate": "30d",
+      "expire": "90d",
+      "note": "What customers said: stale after 30 days, too old to rely on after 90"
+    },
+    "research": {
+      "stale": "1d",
+      "revalidate": "90d",
+      "expire": "365d",
+      "note": "Market research, product cards and site measurements: stale after 90 days"
+    },
+    "assumption": {
+      "per_phase": true,
+      "stale": "1d",
+      "revalidate": "90d",
+      "expire": "365d",
+      "note": "What the venture believes about its problem, solution, price and market: tested again each phase, and stale after 90 days"
+    },
+    "foundation": {
+      "per_phase": true,
+      "stale": "1d",
+      "revalidate": "365d",
+      "note": "The strategic foundation: tested again each phase; in Discovery even confirmed statements are"
+    },
+    "max": {
+      "stale": "1d",
+      "revalidate": "365d",
+      "note": "Governance and other slow records: looked at again once a year"
+    },
+    "none": {
+      "note": "Generated or configuration records: never stale by time, only when what they depend on changes"
+    }
+  },
+  "records": {
+    "customer": "live",
+    "investor": "live",
+    "money-account": "live",
+    "data-stream": "live",
+    "raw-source": "feedback",
+    "raw-text": "feedback",
+    "evidence": "feedback",
+    "product": "research",
+    "account": "research",
+    "site-presence": "research",
+    "anatomy-input": "research",
+    "anatomy-answers": "research",
+    "validation-problem": "assumption",
+    "validation-solution": "assumption",
+    "validation-product-market-fit": "assumption",
+    "validation-pricing": "assumption",
+    "validation-go-to-market": "assumption",
+    "validation-team": "assumption",
+    "validation-operations-readiness": "assumption",
+    "telos": "foundation",
+    "icp": "foundation",
+    "alignment": "foundation",
+    "idea-dump": "none",
+    "idea-map": "none",
+    "idea-graph": "none",
+    "venture-profile": "max",
+    "provenance": "none",
+    "freshness-log": "none",
+    "venture-package": "none",
+    "knowledge-sources": "none",
+    "where-used": "none",
+    "decision-record": "none",
+    "decision-rights": "none",
+    "team-plan": "max",
+    "marketing-sitemap": "none",
+    "marketing-content": "none"
+  }
+}

package/knowledge/layer.json

@@ -19,11 +19,18 @@
     "design-document",
     "nextjs-status",
     "knowledge-sources",
-    "where-used"
+    "where-used",
+    "freshness-profiles",
+    "freshness-log",
+    "judgment",
+    "systems-catalog",
+    "glossary"
   ],
   "reads": [
     "venture",
-    "product"
+    "product",
+    "provenance",
+    "decision-record"
   ],
   "writes": [
     "reference"
@@ -36,7 +43,8 @@
     "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"
+    "A merged pull request is not logged as an accept in provenance; the read after the merge is the only sign",
+    "Freshness (schema/freshness.mjs) checks children in the venture folder only; a child in another source is listed as needing the platform, and a webhook from a system of record that marks summaries stale (V-9) is the platform's"
   ],
   "name": "knowledge"
 }

package/knowledge/templates/glossary.md

@@ -0,0 +1,23 @@
+---
+type: template
+tags: [everything-ecosystem, knowledge, glossary, template]
+ai-model: claude-opus-5.5
+created: 2026-10-29T06:04:07Z
+source: hybrid
+---
+
+# Template: package glossary
+
+Fills `<venture>/glossary/<package>.json` (`schema/glossary.schema.json`). A package's terms stay local to it: an agent working in another package sees only the terms marked `export`. See what a package sees with `mentura glossary/terms run --value <package>`.
+
+```json
+{
+  "package": "finance",
+  "terms": [
+    { "term": "burn multiple", "meaning": "net burn divided by net new ARR" },
+    { "term": "runway", "meaning": "months of cash at the current burn", "export": true }
+  ]
+}
+```
+
+Two packages may not export one term with different meanings. A package's own term wins over another's exported one.

package/operations/layer.json

@@ -23,7 +23,11 @@
     "marketing-matrix",
     "site-presence",
     "marketing-sitemap",
-    "marketing-content"
+    "marketing-content",
+    "people",
+    "founder",
+    "marketing-brand",
+    "public-assets"
   ],
   "reads": [
     "agent-capability",
@@ -37,7 +41,8 @@
     "publication-policy",
     "role",
     "telos",
-    "venture"
+    "venture",
+    "raw-source"
   ],
   "writes": [
     "evidence"
@@ -50,7 +55,9 @@
     "schema/check-departments.mjs",
     "operations/marketing/site/presence.mjs",
     "operations/marketing/site/plan.mjs",
-    "operations/marketing/check-public.mjs"
+    "operations/marketing/check-public.mjs",
+    "schema/check-brand.mjs",
+    "schema/check-assets.mjs"
   ],
   "gaps": [
     "No run-handoff skill: the handoff contract is prose (operations/handoff-v2.md) beside three scripts in schema/ (check-ready, run-handoff, check-execution)",

package/operations/marketing/check-public.mjs

@@ -10,6 +10,7 @@
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
+import { ventureFile } from "../../schema/venture-paths.mjs";
 
 export const CONTENT = "operations/marketing/content";
 const RUN = 10;
@@ -27,24 +28,24 @@ export function frontmatter(text) {
 
 function files(dir) {
   if (!existsSync(dir)) return [];
-  return readdirSync(dir).flatMap((f) => statSync(join(dir, f)).isDirectory() ? files(join(dir, f)) : f.endsWith(".mdx") ? [join(dir, f)] : []);
+  return readdirSync(dir).flatMap((f) => statSync(ventureFile(dir, f)).isDirectory() ? files(ventureFile(dir, f)) : f.endsWith(".mdx") ? [ventureFile(dir, f)] : []);
 }
 
 export function check(dir) {
   const venture = existsSync(join(dir, "venture.json")) ? JSON.parse(readFileSync(join(dir, "venture.json"), "utf8")) : {};
   const publicText = [venture.name, venture.brand?.tagline].filter(Boolean);
-  const pdir = join(dir, "products");
+  const pdir = join(ventureFile(dir, "products"));
   if (existsSync(pdir)) for (const f of readdirSync(pdir).filter((f) => f.endsWith(".json"))) publicText.push(JSON.parse(readFileSync(join(pdir, f), "utf8")).name ?? "");
   const allowed = new Set(publicText.flatMap((t) => [...runs(t)]));
-  const results = files(join(dir, CONTENT)).map((f) => {
+  const results = files(ventureFile(dir, CONTENT)).map((f) => {
     const rel = relative(dir, f), { meta, body } = frontmatter(readFileSync(f, "utf8")), errors = [];
     if (!meta.variant_of) errors.push("names no internal record (variant_of): marketing content is a variant of an internal record");
-    else if (!existsSync(join(dir, meta.variant_of))) errors.push(`variant_of ${meta.variant_of} does not exist`);
+    else if (!existsSync(ventureFile(dir, meta.variant_of))) errors.push(`variant_of ${meta.variant_of} does not exist`);
     if (!meta.audience) errors.push("names no audience");
     if (meta.publish === undefined) errors.push("does not say whether it is published (publish: true or false)");
     if (meta.publish === true && !meta.approved_by) errors.push("is published without a person's approval (approved_by, EE-025)");
-    if (meta.variant_of && existsSync(join(dir, meta.variant_of))) {
-      const src = join(dir, meta.variant_of);
+    if (meta.variant_of && existsSync(ventureFile(dir, meta.variant_of))) {
+      const src = ventureFile(dir, meta.variant_of);
       const raw = readFileSync(src, "utf8");
       const internal = new Set(strings(src.endsWith(".json") ? JSON.parse(raw) : raw).flatMap((s) => [...runs(s)]));
       const leaks = [...runs(body)].filter((r) => internal.has(r) && !allowed.has(r));