naive-framework 0.1.0 → 0.2.0

package/schema/frame.schema.json

@@ -0,0 +1,240 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "frame.schema.json",
+  "title": "Frame (decision library)",
+  "description": "One recurring venture problem, as a shape, at packages/<function>/frames/<id>.frame.json. A frame is to Naive what a component is to a React component library. It holds the goal, the decisions hidden in the founder's sentence, the premises that sentence assumes and the moves to attack them, and what current information a lookup must supply. It never holds an answer: no instrument, vendor, term or market norm, because those go stale and can be wrong. schema/frames.mjs matches a frame to the founder's words, reads the props from the venture's records, has a model judge each premise yes, no or unknown, and proposes the frame's decisions with open options for the founder to decide.",
+  "type": "object",
+  "required": [
+    "id",
+    "title",
+    "functions",
+    "triggers",
+    "goal",
+    "premises",
+    "attacks",
+    "reframe",
+    "props",
+    "freshness",
+    "reasoning",
+    "emits"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$"
+    },
+    "title": {
+      "type": "string"
+    },
+    "functions": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9-]+$"
+      },
+      "description": "The venture functions the problem belongs to; the first is the package the frame lives in"
+    },
+    "triggers": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string"
+      },
+      "description": "Sentences a founder says when they have this problem, in a founder's words"
+    },
+    "goal": {
+      "type": "string",
+      "description": "The end the decisions serve; {prop} placeholders are filled from the venture"
+    },
+    "premises": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "claim",
+          "attack"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "claim": {
+            "type": "string",
+            "description": "What the founder's sentence assumes, as a yes/no proposition about this venture"
+          },
+          "attack": {
+            "type": "string",
+            "description": "The premise attack applied to it, one of schema/frames.mjs ATTACKS"
+          },
+          "reads": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The props the judgment of this premise needs"
+          }
+        }
+      },
+      "description": "The chain the founder's sentence assumes, in order"
+    },
+    "attacks": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string"
+      },
+      "description": "The premise attacks the frame uses (the hooks of the library)"
+    },
+    "dichotomy": {
+      "type": "string",
+      "description": "The trade the founder's sentence forces, asked as: is it false, a real trade-off, or a sequence?"
+    },
+    "reframe": {
+      "type": "string",
+      "description": "The better question the frame leaves the founder with; {prop} placeholders are filled from the venture"
+    },
+    "composes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Smaller frames this one is built from"
+    },
+    "props": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "The venture facts the frame reads, never stores: phase, goal, runway, revenue, cap_table, jurisdiction, control_rights"
+    },
+    "freshness": {
+      "type": "object",
+      "required": [
+        "look_for",
+        "max_age_days",
+        "cite"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "look_for": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          },
+          "description": "What a lookup must find, described as a problem, never as a named answer"
+        },
+        "filter_by": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "max_age_days": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "cite": {
+          "type": "boolean",
+          "const": true
+        }
+      },
+      "description": "What current information the frame needs and how fresh it must be. The lookup itself is a kit's skill; the frame says only what to look for."
+    },
+    "reasoning": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string"
+      },
+      "description": "What a model that fetches the frame must do, in order"
+    },
+    "emits": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "question"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "question": {
+            "type": "string"
+          },
+          "options": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Options that describe the problem's own parts, never a named answer; options from a lookup are added at run time with their date and source"
+          },
+          "options_from": {
+            "enum": [
+              "frame",
+              "lookup"
+            ],
+            "default": "frame"
+          },
+          "layer": {
+            "enum": [
+              "purpose",
+              "knowledge",
+              "operations",
+              "evidence",
+              "governance",
+              "interface"
+            ]
+          },
+          "needed_in": {
+            "enum": [
+              "discovery",
+              "validation",
+              "beachhead",
+              "scale",
+              "platform"
+            ]
+          }
+        }
+      },
+      "description": "The decisions the frame proposes, each open for the founder to decide"
+    },
+    "cases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "facts",
+          "expect"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "facts": {
+            "type": "object",
+            "description": "The props of a worked venture"
+          },
+          "expect": {
+            "type": "object",
+            "description": "The premise verdicts and dichotomy a good judgment reaches for these facts"
+          }
+        }
+      },
+      "description": "Worked cases, to evaluate a model's judgments against"
+    }
+  }
+}

package/schema/frames.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+// The decision library: frames (schema/frame.schema.json). A frame is a recurring venture problem as a
+// shape, the way a component is a reusable piece of UI. It holds no answer. This module:
+//
+//   match    finds the frames whose triggers the founder's words fit (code, by word overlap)
+//   props    reads the facts a frame needs from the venture's records, never from the frame
+//   request  asks a model to judge each premise yes, no or unknown, and whether the trade is false, a
+//            real trade-off or a sequence (one typed question each, the Jev protocol)
+//   run      settles the verdicts in code and proposes the frame's decisions, open, beside the venture's
+//            other decisions; options come from the frame's own parts or from a dated, cited lookup
+//   check    a frame matches its schema's rules and names no instrument as an answer
+//   eval     judges the frame's worked cases and compares the verdicts with what they expect
+//
+// Judgments go through the judgment cache (schema/caching.mjs) with the command in NAIVE_JUDGE_CMD,
+// else Jev when TYPESAFE_API_KEY is set. Lookups are a kit's job: run reads one from --lookup.
+//
+//   node schema/frames.mjs list
+//   node schema/frames.mjs match "<the founder's words>"
+//   node schema/frames.mjs check
+//   node schema/frames.mjs run <venture dir> [<frame id>] [--text "<the founder's words>"] [--lookup <file>]
+//   node schema/frames.mjs eval <frame id>
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+const repo = new URL("..", import.meta.url).pathname;
+const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+export const YES = 0.7, NO = 0.3, MATCH = 0.34;
+
+/** The premise attacks: the reusable reasoning moves frames call, as hooks are called by components. */
+export const ATTACKS = {
+  "test-the-goal": "Make the goal concrete (a number and a date) and check whether the problem serves it at all.",
+  "split-the-dimension": "Break a bundled thing (control, ownership, price) into the parts that can move separately.",
+  "name-the-control": "Name the specific right that matters: direction, votes, board seats, vetoes, day-to-day authority or the mission.",
+  "false-dichotomy": "Ask whether the founder can have both. Answer false, a real trade-off, or a sequence.",
+  "sequence-not-choose": "Ask whether both can happen in order, and which comes first.",
+  "invert": "Ask what would guarantee the bad outcome, and avoid that first.",
+  "who-solved-this": "Find ventures that faced the same shape, through a dated lookup, without copying their answer.",
+};
+
+// Words that would make a frame an answer: named instruments, which go stale and can be wrong. A frame
+// that says "use a SAFE" carries the error that a SAFE gives up no equity; it converts at a later round.
+export const NEVER = ["safe", "convertible note", "revenue-based financing", "venture debt", "dual-class", "preferred stock", "crowdfunding", "bootstrap", "term sheet", "series a"];
+
+const framesDir = (pkg) => join(repo, "packages", pkg, "frames");
+export function frames() {
+  if (!existsSync(join(repo, "packages"))) return [];
+  return readdirSync(join(repo, "packages")).filter((p) => existsSync(framesDir(p))).flatMap((p) =>
+    readdirSync(framesDir(p)).filter((f) => f.endsWith(".frame.json")).map((f) => ({ ...load(join(framesDir(p), f)), package: p, file: `packages/${p}/frames/${f}` })));
+}
+export const frameOf = (id) => frames().find((f) => f.id === id) ?? null;
+
+// ---- check ----
+
+const placeholders = (s) => [...String(s).matchAll(/\{([a-z_]+)\}/g)].map((m) => m[1]);
+export function check(f) {
+  const errors = [];
+  const text = JSON.stringify({ ...f, cases: undefined }).toLowerCase();
+  for (const w of NEVER) if (new RegExp(`\\b${w.replace(/[-]/g, "[- ]")}\\b`).test(text)) errors.push(`${f.id}: names "${w}", an answer; a frame describes the problem and a lookup supplies current options`);
+  for (const a of f.attacks) if (!ATTACKS[a]) errors.push(`${f.id}: unknown attack ${a}`);
+  for (const p of f.premises) {
+    if (!f.attacks.includes(p.attack)) errors.push(`${f.id}: premise ${p.id} uses ${p.attack}, which the frame does not list in attacks`);
+    for (const r of p.reads ?? []) if (!f.props.includes(r)) errors.push(`${f.id}: premise ${p.id} reads ${r}, which is not one of its props`);
+  }
+  for (const s of [f.goal, f.reframe]) for (const ph of placeholders(s)) if (!f.props.includes(ph)) errors.push(`${f.id}: {${ph}} is not one of its props`);
+  if (f.package && f.package !== f.functions[0]) errors.push(`${f.id}: lives in packages/${f.package} but its first function is ${f.functions[0]}`);
+  for (const e of f.emits) if ((e.options_from ?? "frame") === "frame" && !e.options?.length) errors.push(`${f.id}: ${e.id} takes its options from the frame but lists none`);
+  for (const c of f.cases ?? []) for (const k of Object.keys(c.expect)) if (k !== "dichotomy" && !f.premises.some((p) => p.id === k)) errors.push(`${f.id}: case ${c.id} expects a verdict for ${k}, which is not a premise`);
+  return errors;
+}
+
+// ---- match ----
+
+const words = (s) => new Set(String(s).toLowerCase().replace(/[^a-z0-9' ]+/g, " ").split(/\s+/).filter((w) => w.length > 2 && !STOP.has(w)));
+const STOP = new Set(["the", "and", "but", "want", "need", "don't", "dont", "not", "can", "how", "what", "with", "for", "that", "this", "too", "much", "have", "get", "give", "away", "without", "keep", "lose", "losing", "my", "our", "you"]);
+/** Frames whose triggers the founder's words fit, best first: the share of a trigger's words they use. */
+export function match(text) {
+  const said = words(text);
+  return frames().map((f) => {
+    const best = Math.max(...f.triggers.map((t) => { const w = words(t); return w.size ? [...w].filter((x) => said.has(x)).length / w.size : 0; }));
+    return { id: f.id, title: f.title, score: Math.round(best * 100) / 100 };
+  }).filter((m) => m.score >= MATCH).sort((a, b) => b.score - a.score);
+}
+
+// ---- props ----
+
+const NONE = "not on record";
+const money = (m) => (m ? `${(m.amount / 100).toLocaleString("en-US", { maximumFractionDigits: 0 })} ${m.currency}` : null);
+/** The facts a frame reads, from the venture's records; a fact the records do not hold is "not on record". */
+export async function props(dir) {
+  const { decisions } = await import("./decisions.mjs");
+  const v = load(join(dir, "venture.json"));
+  const ds = decisions(dir).decisions;
+  const answer = (id) => { const d = ds.find((x) => x.id === id); return d?.status === "decided" ? d.answer : null; };
+  const sum = existsSync(join(dir, "money/_summary.json")) ? load(join(dir, "money/_summary.json")) : null;
+  const own = existsSync(join(dir, "governance/ownership.json")) ? load(join(dir, "governance/ownership.json")) : null;
+  const people = existsSync(join(dir, "people/people.json")) ? load(join(dir, "people/people.json")) : null;
+  const out = {
+    phase: v.phase,
+    goal: answer("discovery-goal") ?? NONE,
+    revenue: sum ? `${money(sum.monthly_inflow)} a month in, as of ${sum.as_of.slice(0, 10)} (${sum.source})` : NONE,
+    runway: sum ? (sum.runway_months == null ? `cash ${money(sum.cash)}, net cash flow ${money(sum.monthly_net)} a month, so no runway limit (${sum.source}, as of ${sum.as_of.slice(0, 10)})` : `${sum.runway_months} months (${sum.source}, as of ${sum.as_of.slice(0, 10)})`) : NONE,
+    cap_table: own ? own.holders.map((h) => h.name ?? h.id).join(", ") : people ? `${people.people.map((p) => p.name).join(", ")}; no ownership record yet` : NONE,
+    control_rights: answer("which-control-matters") ?? NONE,
+    jurisdiction: v.profile?.jurisdiction ?? v.form?.jurisdiction ?? NONE,
+  };
+  return { facts: out, sources: { revenue: sum ? "money/_summary.json" : null, runway: sum ? "money/_summary.json" : null, goal: answer("discovery-goal") ? "decisions: discovery-goal" : null } };
+}
+const fill = (s, facts) => String(s).replace(/\{([a-z_]+)\}/g, (_, k) => (facts[k] && facts[k] !== NONE ? facts[k] : `the venture's ${k.replace(/_/g, " ")}`));
+
+// ---- request and verdicts ----
+
+const DICHOTOMY = { false: "a false choice: the founder can have both", "trade-off": "a real trade-off: gaining one costs the other", sequence: "a sequence: both, one after the other" };
+/** The typed request: one noul question per premise, and one per reading of the trade. */
+export function request(f, facts) {
+  const questions = {};
+  for (const p of f.premises) questions[`premise:${p.id}`] = { type: "noul", instructions: `Given only the facts in \`venture\` (a fact that says "${NONE}" is unknown), is this true: ${p.claim}`, criteria: { true: "Yes: the facts show it is true for this venture", false: "No: the facts show it is false for this venture" } };
+  if (f.dichotomy) for (const [k, d] of Object.entries(DICHOTOMY)) questions[`dichotomy:${k}`] = { type: "noul", instructions: `The founder's sentence forces this trade: "${f.dichotomy}" Given only the facts in \`venture\`, is that trade ${d}?`, criteria: { true: "Yes", false: "No" } };
+  return { state: { guidelines: "Judge each question against the venture's facts alone, as an experienced founder and investor would. Do not assume facts that are not given.", venture: facts, frame: { problem: f.title, goal: fill(f.goal, facts) } }, model: "jev-latest", questions };
+}
+const p = (a) => (typeof a?.noul === "number" ? a.noul : a?.noul === true ? 1 : a?.noul === false ? 0 : null);
+/** Code settles the verdicts: yes at 0.7 or above, no at 0.3 or below, unknown between or unanswered. */
+// When every fact a premise reads is missing from the records, the verdict is unknown whatever the model
+// said: code wins over a judgment the facts cannot support.
+export function verdicts(f, answers, facts = null) {
+  const out = {};
+  for (const x of f.premises) {
+    const v = p(answers[`premise:${x.id}`]);
+    const blind = facts && x.reads?.length && x.reads.every((r) => !facts[r] || facts[r] === NONE);
+    out[x.id] = { claim: x.claim, attack: x.attack, move: ATTACKS[x.attack], p: v, verdict: blind || v == null ? "unknown" : v >= YES ? "yes" : v <= NO ? "no" : "unknown", ...(blind ? { overruled: `the records hold none of: ${x.reads.join(", ")}` } : {}) };
+  }
+  let dichotomy = null;
+  if (f.dichotomy) {
+    const ranked = Object.keys(DICHOTOMY).map((k) => ({ k, p: p(answers[`dichotomy:${k}`]) ?? 0 })).sort((a, b) => b.p - a.p);
+    dichotomy = { trade: f.dichotomy, reading: ranked[0].p >= YES ? ranked[0].k : "unknown", p: ranked[0].p };
+  }
+  return { premises: out, dichotomy };
+}
+
+function judgeCmd() {
+  if (process.env.NAIVE_JUDGE_CMD) return process.env.NAIVE_JUDGE_CMD;
+  if (process.env.TYPESAFE_API_KEY || process.env.TYPESAFEAI_API_KEY) return `node ${join(repo, "platform/integrations/jev.mjs")}`;
+  return null;
+}
+async function ask(dir, req) {
+  const cmd = judgeCmd();
+  if (!cmd) throw new Error("no judge: set NAIVE_JUDGE_CMD (a command that answers the Jev protocol) or TYPESAFE_API_KEY");
+  const { judge } = await import("./caching.mjs");
+  return judge(dir, req, { cmd, packages: [req.package].filter(Boolean) });
+}
+
+// ---- run ----
+
+/** Options a lookup found, kept only when dated within the frame's freshness and cited. */
+export function fresh(f, lookup, now = Date.now()) {
+  const max = f.freshness.max_age_days * 864e5;
+  const list = (lookup?.options ?? lookup ?? []);
+  const kept = list.filter((o) => o.option && o.source && o.as_of && now - Date.parse(o.as_of) <= max);
+  return { kept, dropped: list.length - kept.length };
+}
+
+/** Match (or take) a frame, judge its premises against the venture, and propose its decisions, open. */
+export async function run(dir, { id, text, lookup, now = Date.now(), agentId = "frames", harness, model } = {}) {
+  const f = id ? frameOf(id) : (text ? frameOf(match(text)[0]?.id) : null);
+  if (!f) return { ok: false, error: id ? `no frame ${id}` : `no frame fits "${text ?? ""}"; node schema/frames.mjs list shows them` };
+  const bad = check(f);
+  if (bad.length) return { ok: false, error: bad.join("\n") };
+  const { facts, sources } = await props(dir);
+  const req = request(f, facts);
+  let judged;
+  try { judged = await ask(dir, req); } catch (e) { return { ok: false, error: e.message, request: req }; }
+  const v = verdicts(f, judged.answers, facts);
+  const reframe = fill(f.reframe, facts);
+  const { propose, decisions } = await import("./decisions.mjs");
+  const said = text ? `The founder said: "${text}". ` : "";
+  const summary = Object.entries(v.premises).map(([k, x]) => `${k} ${x.verdict}`).join("; ");
+  const proposed = [], skipped = [];
+  for (const e of f.emits) {
+    const existing = decisions(dir).decisions.find((d) => d.id === e.id);
+    if (existing?.status === "decided") { skipped.push({ id: e.id, why: "decided already" }); continue; }
+    const looked = (e.options_from ?? "frame") === "lookup" ? fresh(f, lookup, now) : null;
+    const options = looked ? looked.kept.map((o) => `${o.option} (${o.source}, ${o.as_of.slice(0, 10)})`) : e.options;
+    const note = `${said}From the frame ${f.id}: ${reframe} Premises: ${summary}${v.dichotomy ? `; the trade reads as ${v.dichotomy.reading}` : ""}.${looked && !looked.kept.length ? ` Options come from a dated, cited lookup for: ${f.freshness.look_for.join("; ")} (no more than ${f.freshness.max_age_days} days old); none is on file yet.` : ""}`;
+    const r = propose(dir, { id: e.id, question: e.question, ...(options?.length ? { options } : {}), ...(e.layer ? { layer: e.layer } : {}), ...(e.needed_in ? { needed_in: e.needed_in } : {}), note }, { agentId, via: "mcp", harness, model: judged.model ?? model });
+    if (!r.ok) return { ok: false, error: r.error };
+    proposed.push({ id: e.id, question: e.question, options: options ?? [], awaiting: "the founder" });
+  }
+  return { ok: true, result: { frame: f.id, title: f.title, goal: fill(f.goal, facts), facts, sources, verdicts: v.premises, dichotomy: v.dichotomy, reframe, proposed, skipped, judge: { model: judged.model, cache: judged.cache.status } } };
+}
+
+// ---- eval ----
+
+/** Judge each worked case and compare the verdicts with what the case expects. */
+// Its judgments are cached outside the repository, so an eval never writes into it.
+export async function evaluate(id, { dir = join(tmpdir(), "naive-frame-evals") } = {}) {
+  const f = frameOf(id);
+  if (!f) return { ok: false, error: `no frame ${id}` };
+  const rows = [];
+  for (const c of f.cases ?? []) {
+    const { answers, model } = await ask(dir, request(f, c.facts));
+    const v = verdicts(f, answers, c.facts);
+    const got = { ...Object.fromEntries(Object.entries(v.premises).map(([k, x]) => [k, x.verdict])), ...(v.dichotomy ? { dichotomy: v.dichotomy.reading } : {}) };
+    const right = Object.entries(c.expect).filter(([k, x]) => got[k] === x).length;
+    rows.push({ case: c.id, model, right, of: Object.keys(c.expect).length, got, expect: c.expect });
+  }
+  const right = rows.reduce((s, r) => s + r.right, 0), of = rows.reduce((s, r) => s + r.of, 0);
+  return { ok: true, result: { frame: id, cases: rows, accuracy: of ? Math.round((right / of) * 100) / 100 : null } };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === new URL(import.meta.url).pathname) {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const flag = (n) => { const i = rest.indexOf(`--${n}`); if (i < 0) return undefined; const v = rest[i + 1]; rest.splice(i, 2); return v; };
+  const show = (r) => { console.log(JSON.stringify(r.ok === undefined ? r : r.ok ? r.result : { error: r.error }, null, 2)); process.exit(r.ok === false ? 1 : 0); };
+  if (cmd === "list") show(frames().map((f) => ({ id: f.id, title: f.title, package: f.package, triggers: f.triggers })));
+  else if (cmd === "match") show(match(rest.join(" ")));
+  else if (cmd === "check") {
+    const errs = frames().flatMap(check);
+    if (errs.length) { console.error(errs.join("\n")); process.exit(1); }
+    console.log(`${frames().length} frame(s): each describes a problem and names no answer.`);
+  } else if (cmd === "run") {
+    const text = flag("text"), lk = flag("lookup");
+    const [dirArg, id] = rest;
+    if (!dirArg || !existsSync(join(dirArg, "venture.json"))) { console.error("usage: node schema/frames.mjs run <venture dir> [<frame id>] [--text ...] [--lookup <file>]"); process.exit(2); }
+    show(await run(resolve(dirArg), { id, text, lookup: lk ? load(lk) : null }));
+  } else if (cmd === "eval") show(await evaluate(rest[0]));
+  else { console.error("usage: node schema/frames.mjs list|match|check|run|eval"); process.exit(2); }
+}

package/schema/freshness-log.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "freshness-log.schema.json",
+  "title": "Freshness log entry",
+  "description": "One line of a venture's freshness log (<venture>/knowledge/freshness.jsonl, Revalidating V-1, V-2, V-5, V-7): an on-demand revalidation (a tag, a folder path or a package marked stale, like revalidateTag and revalidatePath), a check that a record is still right without changing it (verify), or a phase change. Append-only; each append is also a line in the provenance log. schema/freshness.mjs writes and reads it.",
+  "type": "object",
+  "required": ["at", "event", "by"],
+  "additionalProperties": false,
+  "properties": {
+    "at": { "type": "string", "format": "date-time" },
+    "event": { "enum": ["revalidate", "verify", "phase"], "description": "revalidate: mark stale on demand. verify: a record was checked and is still right; its age starts again. phase: the venture changed phase" },
+    "target": {
+      "type": "object",
+      "required": ["kind", "value"],
+      "additionalProperties": false,
+      "description": "revalidate and verify: what is marked. tag: one record file and everything that depends on it. path: every record under a folder. package: every record of a package's record types",
+      "properties": {
+        "kind": { "enum": ["tag", "path", "package"] },
+        "value": { "type": "string", "pattern": "^(?!/)(?!.*\\.\\./).+$" }
+      }
+    },
+    "from": { "type": "string", "description": "phase: the phase before" },
+    "to": { "type": "string", "description": "phase: the phase after" },
+    "reason": { "type": "string" },
+    "pivot": { "type": "boolean", "description": "A revalidate of the validation package because the venture pivoted" },
+    "by": {
+      "type": "object",
+      "required": ["kind", "via"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": { "enum": ["person", "agent"] },
+        "id": { "type": "string" },
+        "model": { "type": "string" },
+        "session": { "type": "string" },
+        "harness": { "type": "string" },
+        "via": { "enum": ["cli", "mcp", "api", "router"] }
+      }
+    }
+  }
+}

package/schema/freshness-profiles.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "freshness-profiles.schema.json",
+  "title": "Freshness profiles",
+  "description": "How long records stay fresh (Revalidating, V-1 to V-3), after Next.js cacheLife profiles (stale, revalidate, expire) plus two Naive adds: per_phase (stale once the venture changes phase) and live (never frozen into a release; a live hole). The framework's defaults are knowledge/freshness.json; a venture overrides profiles and record assignments under freshness in its naive.config.json. schema/freshness.mjs reads both.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "note": { "type": "string" },
+    "version": { "type": "string" },
+    "default": { "type": "string", "description": "The profile a record type gets when records names none" },
+    "profiles": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/profile" }
+    },
+    "records": {
+      "type": "object",
+      "description": "Profile name by record type id, or by route prefix (validation, foundation/problem); a route prefix wins over the record type, and the longest prefix wins",
+      "additionalProperties": { "type": "string" }
+    }
+  },
+  "$defs": {
+    "duration": {
+      "description": "Seconds, or a number followed by s, m, h, d or w",
+      "oneOf": [
+        { "type": "integer", "minimum": 0 },
+        { "type": "string", "pattern": "^[0-9]+(s|m|h|d|w)$" }
+      ]
+    },
+    "profile": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "stale": { "$ref": "#/$defs/duration", "description": "How long an agent may reuse what it read without reading it again" },
+        "revalidate": { "$ref": "#/$defs/duration", "description": "After this long since it was last checked, the record is stale: readable with a stale flag, to be checked or redone" },
+        "expire": { "$ref": "#/$defs/duration", "description": "After this long it is expired: not relied on, and not frozen into a release" },
+        "per_phase": { "type": "boolean", "description": "Stale once the venture changes phase after the record was last checked" },
+        "live": { "type": "boolean", "description": "A fast-changing record (pipeline, money, streams): never frozen into a release, it stays a live hole" },
+        "note": { "type": "string" }
+      }
+    }
+  }
+}