naive-framework 0.0.0-stage → 0.2.0

package/schema/telos.schema.json

@@ -0,0 +1,197 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "telos.schema.json",
+  "title": "Telos",
+  "description": "The end a venture exists to reach, at <venture>/purpose/telos.json (EE-023): start with the end. It states the end state, how anyone would know it was reached (measures), what the owners intend to happen when it is reached (owner outcome), and, for each phase of the Succession Matrix, the exit criteria that must be true to leave it, each serving at least one measure. Other layers read it instead of asking again: the governance layer's exit.json prefers the owner outcome's path, and MAD's governance tier takes its success measure from the primary measure. schema/check-telos.mjs checks it. Written by the owner; an agent may draft it but not settle it.",
+  "type": "object",
+  "required": [
+    "statement",
+    "end_state",
+    "measures",
+    "owner_outcome"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "statement": {
+      "type": "string",
+      "description": "The end, in one sentence: what the venture is for when it has done its job"
+    },
+    "end_state": {
+      "type": "string",
+      "description": "What is true in the world when the end is reached"
+    },
+    "horizon": {
+      "type": [
+        "integer",
+        "string"
+      ],
+      "description": "The year the end should be reached by, or 'open'"
+    },
+    "measures": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "statement",
+          "kind"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "statement": {
+            "type": "string"
+          },
+          "target": {
+            "type": "string"
+          },
+          "kind": {
+            "enum": [
+              "revenue",
+              "usage_or_adoption",
+              "cost_or_time_saved",
+              "compliance_met",
+              "learning",
+              "flow_and_lead_time",
+              "impact"
+            ],
+            "description": "The kind of measure; the first six match MAD's success_measure answers, impact is a change in the world beyond the venture"
+          },
+          "primary": {
+            "type": "boolean",
+            "description": "Exactly one measure is primary"
+          }
+        }
+      }
+    },
+    "owner_outcome": {
+      "type": "object",
+      "required": [
+        "path"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "enum": [
+            "acquisition",
+            "ipo",
+            "secondary-sale",
+            "merger",
+            "management-buyout",
+            "wind-down",
+            "hold"
+          ],
+          "description": "What the owners intend to happen once the end is reached; hold means they keep it"
+        },
+        "why": {
+          "type": "string"
+        }
+      }
+    },
+    "phases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "phase",
+          "exit_criteria"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "phase": {
+            "enum": [
+              "discovery",
+              "validation",
+              "beachhead",
+              "scale",
+              "platform"
+            ]
+          },
+          "exit_criteria": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "required": [
+                "id",
+                "statement",
+                "serves"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "pattern": "^[a-z0-9-]+$"
+                },
+                "statement": {
+                  "type": "string"
+                },
+                "serves": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Measure ids this criterion moves the venture toward"
+                },
+                "evidence": {
+                  "type": "string",
+                  "description": "How it is shown: a check command, an evidence record, or a metric"
+                }
+              }
+            }
+          }
+        }
+      },
+      "description": "Per phase, what must be true to leave it; refines that phase's generic gate in purpose/frameworks/product-anatomy/phases.json for this venture"
+    },
+    "steering": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "How the venture decides to start, keep going or stop, when it reviews that, and what happens when evidence says the direction is wrong (EE-040; MAD's governance tier reads these as go_decision, review_cadence and change_of_direction). Who may make each call is in the decision rights: continue-or-stop and change-direction.",
+      "properties": {
+        "go_decision": {
+          "enum": [
+            "test-hypotheses-first",
+            "business-case-upfront",
+            "owner-judgment",
+            "last-responsible-moment",
+            "other"
+          ],
+          "description": "test-hypotheses-first: assumptions are written down and tested with real people before committing. business-case-upfront: a case is approved before work starts. owner-judgment: the owner decides as they go. last-responsible-moment: commitments wait until delay costs more than deciding."
+        },
+        "review": {
+          "enum": [
+            "per-experiment",
+            "per-release",
+            "fixed-period",
+            "continuous",
+            "none"
+          ],
+          "description": "When the decision to continue is reviewed: after each experiment or customer test, at each release or milestone, on a calendar, continuously from watched measures, or never formally"
+        },
+        "review_period": {
+          "type": "string",
+          "description": "For fixed-period: the period, such as quarterly"
+        },
+        "change_of_direction": {
+          "enum": [
+            "pivot-on-evidence",
+            "formal-change-control",
+            "owner-decides",
+            "public-proposal",
+            "other"
+          ],
+          "description": "pivot-on-evidence: changing the product, customer or model is expected and planned for. formal-change-control: a change request the deciders approve or reject. owner-decides: the owner adjusts as they see fit. public-proposal: anyone proposes in public and maintainers decide by a published rule."
+        },
+        "note": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/schema/time-to-ready.mjs

@@ -0,0 +1,93 @@
+// Time to running, and time to ready per layer and per MAD tier (the telos's Option B measure).
+//
+//   running: the venture is operating when its core promise is written, a product is live with at
+//     least one account, and the next phase's exit criteria exist in the telos.
+//     The date is the latest of the dates those records first appeared.
+//   layer ready: every record the need-now score suggests for the current phase exists in that
+//     layer; the date is when the last of them first appeared. A layer still missing one is not
+//     ready, and the missing records are listed.
+//   tier ready: the operations-readiness record's ready_on per MAD tier.
+// A record's date is when git first saw the file, else the file's own updated or opened date.
+//
+//   node schema/time-to-ready.mjs <venture dir> [--json]
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { needNow } from "./need-now.mjs";
+
+const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+const day = (d) => d ? d.slice(0, 10) : null;
+const days = (a, b) => a && b ? Math.round((new Date(b) - new Date(a)) / 864e5) : null;
+
+function firstSeen(file) {
+  try {
+    const out = execFileSync("git", ["log", "--diff-filter=A", "--follow", "--format=%as", "--", file], { cwd: dirname(file), encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim().split("\n").filter(Boolean);
+    if (out.length) return out[out.length - 1];
+  } catch {}
+  try { const j = load(file); if (j.updated || j.opened) return day(j.updated ?? j.opened); } catch {}
+  return day(statSync(file).mtime.toISOString());
+}
+
+const files = (d, base = d) => existsSync(d) ? readdirSync(d, { withFileTypes: true }).flatMap((e) =>
+  e.isDirectory() ? files(join(d, e.name), base) : [join(d, e.name).slice(base.length + 1)]) : [];
+const glob = (g) => new RegExp("^" + g.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*\//g, "\0").replace(/\*/g, "[^/]*").replace(/\0/g, "(?:[^/]+/)*") + "$");
+
+export function timeToReady(dir) {
+  const repo = new URL("..", import.meta.url).pathname;
+  const model = load(join(repo, "schema/data-model.json"));
+  const v = load(join(dir, "venture.json"));
+  const start = day(v.opened) ?? firstSeen(join(dir, "venture.json"));
+  const here = files(dir);
+  const where = (type) => {
+    const rels = (model.records.find((r) => r.id === type)?.paths ?? []).filter((p) => p.startsWith("instance/**/")).map((p) => p.slice("instance/**/".length));
+    return here.filter((x) => rels.some((g) => glob(g).test(x)));
+  };
+  const seen = (type) => { const fs = where(type); return fs.length ? fs.map((f) => firstSeen(join(dir, f))).sort()[0] : null; };
+
+  // Running.
+  const nn = needNow(dir);
+  const products = where("product").map((f) => ({ f, p: load(join(dir, f)) }));
+  const offered = products.filter(({ p }) => p.status === "live");
+  const telosFile = where("telos")[0];
+  const telos = telosFile ? load(join(dir, telosFile)) : null;
+  const conditions = {
+    promise: v.core?.promise ? firstSeen(join(dir, "venture.json")) : null,
+    product_offered: offered.length ? offered.map(({ f }) => firstSeen(join(dir, f))).sort()[0] : null,
+    first_account: seen("account"),
+    next_exit_criteria: nn.next && telos?.phases?.some((p) => p.phase === nn.next) ? firstSeen(join(dir, telosFile)) : null,
+  };
+  const missing = Object.entries(conditions).filter(([, d]) => !d).map(([k]) => k);
+  const runningOn = missing.length ? null : Object.values(conditions).sort().at(-1);
+
+  // Layers.
+  const layers = {};
+  for (const row of nn.rows.filter((r) => r.status === "held" || r.status === "suggest now")) {
+    const l = row.layer ?? "system";
+    layers[l] ??= { dates: [], missing: [] };
+    const d = seen(row.type);
+    if (d) layers[l].dates.push(d); else layers[l].missing.push(row.type);
+  }
+  const layerRows = Object.entries(layers).map(([layer, x]) => {
+    const on = x.missing.length ? null : x.dates.sort().at(-1) ?? null;
+    return { layer, ready_on: on, days: days(start, on), missing: x.missing };
+  });
+
+  // MAD tiers.
+  const opsFile = where("validation-operations-readiness")[0];
+  const tiers = opsFile ? load(join(dir, opsFile)).tiers.map((t) => ({ tier: t.tier, ready_on: t.ready_on ?? null, days: days(start, t.ready_on) })) : [];
+
+  return { venture: v.id, phase: nn.phase, started: start, running: { on: runningOn, days: days(start, runningOn), missing, conditions }, layers: layerRows, tiers };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const dir = process.argv[2];
+  if (!dir || !existsSync(join(dir, "venture.json"))) { console.error("usage: node schema/time-to-ready.mjs <venture dir> [--json]"); process.exit(2); }
+  const r = timeToReady(dir);
+  if (process.argv.includes("--json")) { console.log(JSON.stringify(r, null, 2)); process.exit(0); }
+  console.log(`${r.venture}: started ${r.started}, phase ${r.phase}`);
+  console.log(r.running.on ? `running since ${r.running.on} (${r.running.days} days to running)` : `not running yet: missing ${r.running.missing.join(", ")}`);
+  console.log("\nlayer ready (for what the current phase needs)");
+  for (const l of r.layers) console.log(`  ${l.layer.padEnd(12)} ${l.ready_on ? `${l.ready_on} (${l.days} days)` : `not ready: ${l.missing.join(", ")}`}`);
+  if (r.tiers.length) { console.log("\nMAD tier ready"); for (const t of r.tiers) console.log(`  ${t.tier.padEnd(22)} ${t.ready_on ? `${t.ready_on} (${t.days} days)` : "not ready"}`); }
+}

package/schema/trigger.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "trigger.schema.json",
+  "title": "Trigger",
+  "description": "What starts the next step when something happens in a venture (M-12), as React's event handlers and effects trigger actions. An event is a line of the venture's provenance log: a record written, drafted, accepted, confirmed or moved. A trigger lives in naive.config.json triggers, or in a Mentura kit's automations; a kit's automation also names the package it needs, and runs only once that package is complete. A run that fails is recorded and raised as a decision for the founder, never lost (E-7). schema/triggers.mjs runs them.",
+  "type": "object",
+  "required": ["id", "on", "run"],
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "on": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Which provenance entries start it; every field given must match",
+      "properties": {
+        "activity": {
+          "oneOf": [
+            { "enum": ["write", "draft", "accept", "baseline", "confirm", "move", "release"] },
+            { "type": "array", "minItems": 1, "items": { "enum": ["write", "draft", "accept", "baseline", "confirm", "move", "release"] } }
+          ]
+        },
+        "route": { "type": "string", "description": "A glob over the entry's route, such as foundation/**" },
+        "entity": { "type": "string", "description": "A glob over the file the entry names" },
+        "by": { "enum": ["person", "agent"], "description": "Only entries by a person, or only by an agent" }
+      }
+    },
+    "run": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The next step: one router call, or a decision proposed for a person",
+      "properties": {
+        "route": { "type": "string" },
+        "action": { "enum": ["read", "check", "run", "write", "layout", "view"] },
+        "input": {},
+        "propose": { "type": "object", "description": "A decision record (decision-record.schema.json) proposed for a person to decide" }
+      },
+      "oneOf": [ { "required": ["route", "action"] }, { "required": ["propose"] } ]
+    },
+    "needs": { "type": "string", "description": "The package that must be complete first (required for a kit's automation)" },
+    "once": { "type": "boolean", "description": "Run it once only; later events do not start it again" },
+    "enabled": { "type": "boolean", "default": true },
+    "note": { "type": "string" }
+  }
+}

package/schema/triggers.mjs

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+// Triggers (M-12) and what happens when one fails (E-7). In React an event handler or an effect starts
+// an action when something happens; in Naive an event is a line of the venture's provenance log (a
+// record written, drafted, accepted, confirmed or moved), and a trigger starts the next step: one router
+// call, or a decision proposed for a person. Triggers come from naive.config.json `triggers`, and from
+// the automations of the Mentura kits the venture lists in `kits`. A kit's automation runs only once
+// the package it needs is complete; until then its run waits, and is retried on every later event.
+//
+// React's error boundaries do not catch errors in event handlers or async code: you catch and store
+// them yourself. So does this. Every run is stored in <venture>/.naive/triggers.json before the cursor
+// moves past its event. A run that fails, or throws, is raised as a decision for the founder (retry,
+// skip this event, or turn the trigger off) and settled when the founder decides it. A crash of the
+// runner itself is kept by the provenance hook and raised on the next run. Nothing is lost.
+//
+//   node schema/triggers.mjs <venture dir> [--json]     the triggers, their recent runs and open failures
+//   node schema/triggers.mjs <venture dir> --fire        run what the new events start (the provenance hook does this)
+//
+// Trigger runs act as agents (id trigger-<id>, via router), so their writes meet the same gates as any
+// agent's: a gated record is drafted for a person. A trigger never fires on its own writes.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { entries } from "../interface/provenance.mjs";
+import { call, glob } from "../interface/router.mjs";
+import { decisions, propose } from "./decisions.mjs";
+import { kit } from "./kits.mjs";
+import { CONFIG, readConfig, writeConfig } from "./naive-config.mjs";
+import { packages } from "./packages.mjs";
+
+export const STATE = ".naive/triggers.json";
+export const ERRORS = ".naive/trigger-errors.jsonl";
+const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+const now = () => new Date().toISOString();
+
+/** The venture's triggers, from its config and its kits, with what is wrong with any of them. */
+export function triggersOf(dir) {
+  const cfg = readConfig(dir);
+  const off = new Set(cfg.triggers_off ?? []);
+  const problems = [];
+  const out = (cfg.triggers ?? []).map((t) => ({ ...t, from: "naive.config.json" }));
+  for (const name of cfg.kits ?? []) {
+    const k = kit(name);
+    if (!k) { problems.push(`kit ${name} is listed in ${CONFIG} kits but is not installed (platform/kits/${name}/kit.json)`); continue; }
+    for (const a of k.automations ?? []) {
+      if (!a.needs) { problems.push(`kit ${name}: automation ${a.id} names no package it needs, so it never runs (a kit's automation runs only once its package is complete)`); continue; }
+      out.push({ ...a, id: `${name}-${a.id}`, from: `kit ${name}` });
+    }
+  }
+  const seen = new Set();
+  for (const t of out) { if (seen.has(t.id)) problems.push(`trigger ${t.id} is defined twice; the first one runs`); seen.add(t.id); }
+  return { triggers: out.filter((t, i) => out.findIndex((x) => x.id === t.id) === i).map((t) => ({ ...t, enabled: t.enabled !== false && !off.has(t.id) })), problems };
+}
+
+/** Whether a provenance entry starts a trigger. */
+export function matches(t, e) {
+  const on = t.on ?? {};
+  const acts = on.activity ? [on.activity].flat() : null;
+  if (acts && !acts.includes(e.activity)) return false;
+  if (on.route && !(e.route && glob(on.route).test(e.route))) return false;
+  if (on.entity && !glob(on.entity).test(e.entity)) return false;
+  if (on.by && e.agent?.kind !== on.by) return false;
+  return true;
+}
+
+function readState(dir) {
+  const f = join(dir, STATE);
+  if (existsSync(f)) {
+    try { const s = load(f); if (Array.isArray(s.runs) && Array.isArray(s.waiting)) return s; } catch {}
+    // A state file that cannot be read is kept beside it, and the failure is raised; runs start again from now.
+    const kept = `.naive/triggers.unreadable-${Date.now()}.json`;
+    renameSync(f, join(dir, kept));
+    return { since: now(), cursor: null, runs: [], waiting: [], unreadable: kept };
+  }
+  // Triggers start with the events after they were configured, not the venture's whole history.
+  const cfg = join(dir, CONFIG);
+  return { since: existsSync(cfg) ? statSync(cfg).mtime.toISOString() : now(), cursor: null, runs: [], waiting: [] };
+}
+const saveState = (dir, s) => { mkdirSync(join(dir, ".naive"), { recursive: true }); writeFileSync(join(dir, STATE), JSON.stringify(s, null, 2) + "\n"); };
+
+const complete = (dir, name) => { try { return packages(dir).complete.includes(name); } catch { return false; } };
+const brief = (x) => (x == null ? null : typeof x === "string" ? x.slice(0, 300) : JSON.stringify(x).slice(0, 300));
+
+// E-7: a failed run becomes a decision the founder owes. It fails open: the rest of the venture goes on.
+function raise(dir, run) {
+  const v = load(join(dir, "venture.json"));
+  // A runner failure can recur across state files, so its id carries the time instead of the run number.
+  const id = `trigger-${run.trigger}-failed-${run.trigger === "runner" ? Date.now().toString(36) : run.n}`.replace(/[^a-z0-9-]+/g, "-").slice(0, 80);
+  const r = propose(dir, { id, question: `Trigger ${run.trigger} ${run.outcome === "uncaught" ? "crashed" : "failed"} on ${run.activity ?? "an event"} of ${run.entity ?? "the venture"}: ${String(run.error).split("\n")[0].slice(0, 300)}. Retry it, skip this event, or turn the trigger off?`,
+    options: ["Retry", "Skip this event", "Turn the trigger off"], layer: "operations", boundary: "fail-open", needed_in: v.phase, decides: { path: CONFIG },
+    note: `Raised by schema/triggers.mjs (E-7). The run is kept in ${STATE} as run ${run.n}.` }, { agentId: "naive-triggers", via: "router" });
+  return r.ok ? id : null;
+}
+
+async function runOne(dir, t, e, state, extra = {}) {
+  const v = load(join(dir, "venture.json"));
+  const run = { n: state.runs.length + 1, trigger: t.id, from: t.from, event: e?.hash ?? null, entity: e?.entity ?? null, activity: e?.activity ?? null, at: now(), ...extra };
+  try {
+    let r;
+    if (t.run.propose) r = propose(dir, t.run.propose, { agentId: `trigger-${t.id}`, via: "router" });
+    else if (typeof t.run.route !== "string") throw new Error(`trigger ${t.id} names no route to run`); // a malformed trigger crashes; the router would read it as a broken route table
+    else r = await call({ venture: v.id, workspace: dir, route: t.run.route, action: t.run.action, input: t.run.input, actor: "agent", actor_id: `trigger-${t.id}`, via: "router",
+      provenance: { derived_from: e?.entity && !/:\/\//.test(e.entity) ? [e.entity] : undefined, note: `trigger ${t.id} on ${e?.activity ?? "retry"} of ${e?.entity ?? "?"}` } });
+    run.outcome = r.ok ? "ran" : "failed";
+    if (r.ok) run.result = brief(r.result); else run.error = r.error ?? brief(r.result) ?? "the call did not succeed";
+  } catch (err) { run.outcome = "uncaught"; run.error = String(err?.stack ?? err).slice(0, 2000); }
+  if (run.outcome !== "ran") { const d = raise(dir, run); run.status = d ? "raised" : "unraised"; if (d) run.decision = d; }
+  state.runs.push(run);
+  saveState(dir, state);
+  return run;
+}
+
+/** Settles failures the founder has decided: retry the run, skip its event, or turn the trigger off. */
+export async function settle(dir, state = readState(dir)) {
+  const raised = state.runs.filter((r) => r.status === "raised");
+  if (!raised.length) return [];
+  const ds = new Map(decisions(dir).decisions.map((d) => [d.id, d]));
+  const { triggers } = triggersOf(dir);
+  const log = entries(dir);
+  const done = [];
+  for (const run of raised) {
+    const d = ds.get(run.decision);
+    if (!d || !["decided", "withdrawn"].includes(d.status)) continue;
+    const answer = String(d.answer ?? "").toLowerCase();
+    if (d.status === "withdrawn" || answer.startsWith("skip")) run.status = "skipped";
+    else if (/\boff\b|disable|turn/.test(answer)) {
+      const cfg = readConfig(dir);
+      cfg.triggers_off = [...new Set([...(cfg.triggers_off ?? []), run.trigger])];
+      writeConfig(dir, cfg);
+      run.status = "turned off";
+    } else if (answer.startsWith("retry")) {
+      run.status = "retried";
+      const t = triggers.find((x) => x.id === run.trigger);
+      const e = log.find((x) => x.hash === run.event);
+      saveState(dir, state);
+      if (t && t.enabled) { const again = await runOne(dir, t, e, state, { retry_of: run.n }); run.retried_as = again.n; }
+      else run.status = "retried, but the trigger is gone or off";
+    } else continue;
+    run.settled_at = now();
+    done.push(run);
+    saveState(dir, state);
+  }
+  return done;
+}
+
+/** Runs what the events since the last run start. Returns the runs it made. */
+export async function fire(dir, { rounds = 20 } = {}) {
+  const held = process.env.NAIVE_TRIGGERS_ACTIVE;
+  process.env.NAIVE_TRIGGERS_ACTIVE = "fire";
+  const state = readState(dir);
+  const made = [];
+  try {
+    if (state.unreadable) {
+      const run = { n: 1, trigger: "runner", from: "schema/triggers.mjs", at: now(), outcome: "failed", error: `${STATE} could not be read; it is kept at ${state.unreadable} and triggers start again from now` };
+      const d = raise(dir, run); run.status = d ? "raised" : "unraised"; if (d) run.decision = d;
+      delete state.unreadable; state.runs.push(run); made.push(run); saveState(dir, state);
+    }
+    // A crash the provenance hook kept is a failure too.
+    const ef = join(dir, ERRORS);
+    if (existsSync(ef)) {
+      for (const l of readFileSync(ef, "utf8").split("\n").filter(Boolean)) {
+        const x = JSON.parse(l);
+        const run = { n: state.runs.length + 1, trigger: "runner", from: "provenance hook", event: null, entity: null, activity: null, at: x.at, outcome: "uncaught", error: x.error };
+        const d = raise(dir, run); run.status = d ? "raised" : "unraised"; if (d) run.decision = d;
+        state.runs.push(run); made.push(run);
+      }
+      writeFileSync(ef, "");
+      saveState(dir, state);
+    }
+    made.push(...await settle(dir, state));
+    const { triggers } = triggersOf(dir);
+    const active = triggers.filter((t) => t.enabled);
+    const ranOnce = (t) => t.once && state.runs.some((r) => r.trigger === t.id && r.outcome === "ran");
+    for (let round = 0; round < rounds; round++) {
+      const log = entries(dir);
+      const at = state.cursor ? log.findIndex((e) => e.hash === state.cursor) + 1 : log.findIndex((e) => e.at >= state.since);
+      const pending = at < 0 ? [] : log.slice(at);
+      // Runs waiting on a package go first, once the package is complete.
+      for (const w of [...state.waiting]) {
+        const t = active.find((x) => x.id === w.trigger);
+        if (!t || ranOnce(t)) { state.waiting = state.waiting.filter((x) => x !== w); continue; }
+        if (!complete(dir, t.needs)) continue;
+        state.waiting = state.waiting.filter((x) => x !== w);
+        made.push(await runOne(dir, t, log.find((e) => e.hash === w.event), state, { waited_since: w.at }));
+      }
+      if (!pending.length) break;
+      for (const e of pending) {
+        for (const t of active) {
+          if (!matches(t, e) || e.agent?.id === `trigger-${t.id}` || ranOnce(t)) continue;
+          if (t.needs && !complete(dir, t.needs)) {
+            if (!state.waiting.some((w) => w.trigger === t.id)) state.waiting.push({ trigger: t.id, event: e.hash, at: now(), needs: t.needs });
+            continue;
+          }
+          made.push(await runOne(dir, t, e, state));
+        }
+        state.cursor = e.hash;
+        saveState(dir, state);
+      }
+      if (round === rounds - 1 && entries(dir).at(-1)?.hash !== state.cursor) {
+        const run = { n: state.runs.length + 1, trigger: "runner", from: "schema/triggers.mjs", at: now(), outcome: "failed", error: `triggers kept starting each other for ${rounds} rounds; the rest wait for the next event` };
+        const d = raise(dir, run); run.status = d ? "raised" : "unraised"; if (d) run.decision = d;
+        state.runs.push(run); made.push(run); saveState(dir, state);
+      }
+    }
+    return made;
+  } finally {
+    if (held === undefined) delete process.env.NAIVE_TRIGGERS_ACTIVE; else process.env.NAIVE_TRIGGERS_ACTIVE = held;
+  }
+}
+
+/** The triggers, the latest runs, what waits on a package, and the failures still open. */
+export function report(dir) {
+  const { triggers, problems } = triggersOf(dir);
+  // Read only: a listing never moves an unreadable state file aside (the next run does, and raises it).
+  const s = (() => { try { return load(join(dir, STATE)); } catch { return { runs: [], waiting: [] }; } })();
+  return { triggers: triggers.map((t) => ({ id: t.id, from: t.from, on: t.on, run: t.run.propose ? { propose: t.run.propose.id } : { route: t.run.route, action: t.run.action }, needs: t.needs ?? null, needs_complete: t.needs ? complete(dir, t.needs) : null, enabled: t.enabled, once: !!t.once })),
+    problems, runs: s.runs.slice(-10), waiting: s.waiting, open: s.runs.filter((r) => r.status === "raised").map((r) => ({ run: r.n, trigger: r.trigger, error: r.error, decision: r.decision, decide: `mentura decide ${r.decision} --venture ${load(join(dir, "venture.json")).id} --by <your name> --answer "Retry" (or "Skip this event", "Turn the trigger off")` })) };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const dir = process.argv[2];
+  if (!dir || !existsSync(join(dir, "venture.json"))) { console.error("usage: node schema/triggers.mjs <venture dir> [--fire] [--json]"); process.exit(2); }
+  const json = process.argv.includes("--json"), quiet = process.argv.includes("--quiet");
+  if (process.argv.includes("--fire")) {
+    const made = await fire(dir);
+    if (json) console.log(JSON.stringify(made, null, 2));
+    else if (!quiet) for (const r of made) console.log(`${(r.outcome ?? r.status).padEnd(9)} ${r.trigger}${r.entity ? ` on ${r.activity} of ${r.entity}` : ""}${r.error ? `: ${String(r.error).split("\n")[0]}` : ""}${r.decision && r.status === "raised" ? ` (raised as decision ${r.decision})` : ""}`);
+    process.exit(0);
+  }
+  const r = report(dir);
+  if (json) { console.log(JSON.stringify(r, null, 2)); process.exit(0); }
+  if (!r.triggers.length) console.log(`no triggers: add them to ${CONFIG} triggers, or list a kit in kits`);
+  for (const t of r.triggers) console.log(`trigger   ${t.id} (${t.from})${t.enabled ? "" : " [off]"}: on ${JSON.stringify(t.on)} run ${JSON.stringify(t.run)}${t.needs ? `, needs ${t.needs} (${t.needs_complete ? "complete" : "not complete yet"})` : ""}`);
+  for (const p of r.problems) console.log(`problem   ${p}`);
+  for (const x of r.runs) console.log(`run ${String(x.n).padEnd(5)} ${x.outcome.padEnd(9)} ${x.trigger}${x.entity ? ` on ${x.activity} of ${x.entity}` : ""}${x.status ? ` [${x.status}]` : ""}`);
+  for (const w of r.waiting) console.log(`waiting   ${w.trigger}: needs the ${w.needs} package complete`);
+  for (const o of r.open) console.log(`failed    ${o.trigger} (run ${o.run}): ${String(o.error).split("\n")[0]}\n          ${o.decide}`);
+}

package/schema/upgrade-registry.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "upgrade-registry.schema.json",
+  "title": "Upgrade registry",
+  "description": "Naive's versions, the migrations between them, and each package's version and channel (schema/upgrades.json, EE-076). naive upgrade reads it from the installed copy. A migration rewrites a venture's records when the framework or one package changes, like a Next.js codemod; a version's guide is bundled in docs/upgrades/.",
+  "type": "object",
+  "required": ["framework", "versions", "migrations", "packages"],
+  "additionalProperties": false,
+  "properties": {
+    "framework": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$", "description": "The installed framework version" },
+    "note": { "type": "string" },
+    "channels": { "type": "object", "additionalProperties": { "type": "string" } },
+    "versions": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["version", "date", "summary", "guide", "migrations"],
+        "additionalProperties": false,
+        "properties": {
+          "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+          "date": { "type": "string", "format": "date" },
+          "summary": { "type": "string" },
+          "guide": { "type": ["string", "null"], "description": "The upgrade guide for this version, a repository path, or null for the first version" },
+          "migrations": { "type": "array", "items": { "type": "string" }, "description": "Framework migrations that move a venture onto this version, in order" }
+        }
+      }
+    },
+    "migrations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "module", "package"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+          "module": { "type": "string", "description": "A module exporting id, describe and apply(dir, ctx)" },
+          "package": { "type": ["string", "null"], "description": "The package whose schema changed, or null for a framework migration" },
+          "from": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$", "description": "A package migration: the oldest package version it upgrades" },
+          "to": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$", "description": "A package migration: the package version it upgrades to" },
+          "decision": { "type": "string" },
+          "aliases": { "type": "string", "description": "The route aliases file that keeps the old routes working" }
+        }
+      }
+    },
+    "packages": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["version", "channel"],
+        "additionalProperties": false,
+        "properties": {
+          "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+          "channel": { "enum": ["stable", "experimental"] },
+          "note": { "type": "string" }
+        }
+      }
+    }
+  }
+}