naive-framework 0.1.0 → 0.3.0

package/schema/systems-catalog.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "systems-catalog.schema.json",
+  "title": "Systems catalog",
+  "description": "The systems of record create-venture offers per function (schema/systems-catalog.json): each system's kind, what its address looks like, and the code that connects to it, if any.",
+  "type": "object",
+  "required": [
+    "version",
+    "systems",
+    "functions"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "string"
+    },
+    "note": {
+      "type": "string"
+    },
+    "systems": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "label",
+          "kind",
+          "address",
+          "connect"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "label": {
+            "type": "string"
+          },
+          "kind": {
+            "type": "string"
+          },
+          "address": {
+            "type": "string"
+          },
+          "connect": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        }
+      }
+    },
+    "functions": {
+      "type": "object",
+      "propertyNames": {
+        "enum": [
+          "strategy",
+          "products",
+          "marketing-and-sales",
+          "supply-chain",
+          "service-delivery",
+          "customer-service",
+          "human-capital",
+          "it",
+          "finance",
+          "assets",
+          "risk-and-compliance",
+          "external-relationships",
+          "capabilities",
+          "legal"
+        ]
+      },
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/schema/time-to-ready.mjs

@@ -15,6 +15,7 @@ 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";
+import { ventureFile } from "./venture-paths.mjs";
 
 const load = (p) => JSON.parse(readFileSync(p, "utf8"));
 const day = (d) => d ? d.slice(0, 10) : null;
@@ -43,19 +44,19 @@ export function timeToReady(dir) {
     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; };
+  const seen = (type) => { const fs = where(type); return fs.length ? fs.map((f) => firstSeen(ventureFile(dir, f))).sort()[0] : null; };
 
   // Running.
   const nn = needNow(dir);
-  const products = where("product").map((f) => ({ f, p: load(join(dir, f)) }));
+  const products = where("product").map((f) => ({ f, p: load(ventureFile(dir, f)) }));
   const offered = products.filter(({ p }) => p.status === "live");
   const telosFile = where("telos")[0];
-  const telos = telosFile ? load(join(dir, telosFile)) : null;
+  const telos = telosFile ? load(ventureFile(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,
+    product_offered: offered.length ? offered.map(({ f }) => firstSeen(ventureFile(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,
+    next_exit_criteria: nn.next && telos?.phases?.some((p) => p.phase === nn.next) ? firstSeen(ventureFile(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);
@@ -75,7 +76,7 @@ export function timeToReady(dir) {
 
   // 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) })) : [];
+  const tiers = opsFile ? load(ventureFile(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 };
 }

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,238 @@
+#!/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";
+import { ventureFile } from "./venture-paths.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 = ventureFile(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, ventureFile(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 = ventureFile(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(ventureFile(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 = ventureFile(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(ventureFile(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" }
+        }
+      }
+    }
+  }
+}