naive-framework 0.0.0-stage → 0.2.0

package/schema/need-now.mjs

@@ -0,0 +1,108 @@
+// Says which records a venture needs now, which come soon, and which to hold back (EE-028), so a
+// builder works only on what matters at this moment instead of overbuilding. Priors per record
+// type and phase are in schema/need-now.json; facts about the venture raise or lower them:
+//   phase, ambition, funding, legal_form, offering (of any product), software (any product),
+//   path (go-to-market record), people, founders, agents, products (counts), publishes (a handoff
+//   under public-commitment), team (the answer to Naive's team question: solo, cofounders, looking),
+//   type (the venture type, EE-082).
+// Departments (EE-047) are scored the same way, from their priors in operations/departments.json, and
+// held once venture.json lists them. Records that already exist are listed as held; a record in a layer the venture has turned off is
+// listed as layer off, not suggested. Jev re-scores the priors per venture once the
+// scorer runs; until then the priors are the default.
+//
+//   node schema/need-now.mjs <venture dir> [--json]
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { catalog } from "./departments.mjs";
+
+const root = new URL("..", import.meta.url).pathname;
+const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+const PHASES = load(join(root, "purpose/frameworks/product-anatomy/phases.json")).phases.map((p) => p.id);
+
+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, "(?:[^/]+/)*") + "$");
+
+/** Facts about a venture that the need-now conditions test. */
+export function factsOf(dir) {
+  const v = load(join(dir, "venture.json"));
+  const json = (p) => existsSync(join(dir, p)) ? load(join(dir, p)) : null;
+  const products = existsSync(join(dir, "products")) ? readdirSync(join(dir, "products")).filter((f) => f.endsWith(".json")).map((f) => load(join(dir, "products", f))) : [];
+  const members = (v.members ?? []).map((m) => typeof m === "string" ? { kind: "person", role: m } : m);
+  const own = json("governance/ownership.json");
+  const hDir = join(dir, "operations/handoffs");
+  const handoffs = existsSync(hDir) ? readdirSync(hDir).filter((f) => f.endsWith(".json")).map((f) => load(join(hDir, f))) : [];
+  // The founding team, as the founder answered Naive's team question (EE-060): solo, cofounders or looking.
+  const teamFile = join(dir, "decisions/venture.team.decision.json");
+  const td = existsSync(teamFile) ? load(teamFile) : null;
+  const team = td?.status === "decided" ? ["solo", "cofounders", "looking"].find((t) => (td.answer ?? "").toLowerCase().startsWith(t)) ?? null : null;
+  return {
+    team, type: v.type ?? null, phase: v.phase, ambition: v.ambition, funding: v.form?.funding, legal_form: v.form?.legal_form,
+    offering: products.map((p) => p.offering), software: products.some((p) => p.software),
+    path: json("purpose/validation/go-to-market.json")?.path,
+    people: members.filter((m) => m.kind !== "agent").length + (v.owner === "self" && !members.some((m) => m.kind !== "agent") ? 1 : 0),
+    founders: own ? own.holders.filter((h) => h.kind === "founder").length : members.filter((m) => m.role === "founder").length,
+    agents: members.filter((m) => m.kind === "agent").length, products: products.length,
+    publishes: handoffs.some((h) => (h.decision_classes ?? []).includes("public-commitment") || (h.escalations ?? []).some((e) => e.class === "public-commitment")),
+  };
+}
+
+export function holds(cond, f) {
+  const m = cond.match(/^([a-z_]+)(>=|:)?(.*)$/);
+  const [, key, op, val] = m;
+  if (!op) return !!f[key];
+  if (op === ">=") return (f[key] ?? 0) >= Number(val);
+  return Array.isArray(f[key]) ? f[key].includes(val) : f[key] === val;
+}
+
+export function probability(spec, phase, f) {
+  let p = spec.base[phase] ?? 0;
+  for (const w of spec.when ?? []) {
+    if (w.phase && w.phase !== phase) continue;
+    if (!holds(w.if, f)) continue;
+    if (w.at_least !== undefined) p = Math.max(p, w.at_least);
+    if (w.at_most !== undefined) p = Math.min(p, w.at_most);
+  }
+  return p;
+}
+
+export function needNow(dir) {
+  const N = load(join(root, "schema/need-now.json"));
+  const model = load(join(root, "schema/data-model.json"));
+  const f = factsOf(dir);
+  const v = load(join(dir, "venture.json"));
+  const here = files(dir);
+  const phase = PHASES.includes(f.phase) ? f.phase : "discovery";
+  const next = PHASES[PHASES.indexOf(phase) + 1];
+  const rows = Object.entries(N.records).map(([type, spec]) => {
+    const rec = model.records.find((r) => r.id === type);
+    const rels = (rec?.paths ?? []).filter((p) => p.startsWith("instance/**/")).map((p) => p.slice("instance/**/".length));
+    const held = rels.some((g) => here.some((x) => glob(g).test(x)));
+    const now = probability(spec, phase, f), soon = next ? probability(spec, next, f) : now;
+    const off = rec?.layer && v.layers?.[rec.layer] === false;
+    const status = held ? "held" : off ? "layer off" : now >= N.suggest ? "suggest now" : soon >= N.suggest ? "coming soon" : "hold back";
+    return { type, layer: rec?.layer, now, next: soon, status, why: spec.why };
+  });
+  // Departments are imported one by one (EE-047, EE-048), each with its own priors in the catalog.
+  const departments = catalog().map((d) => {
+    const now = probability(d, phase, f), soon = next ? probability(d, next, f) : now;
+    const status = (v.departments ?? []).includes(d.id) ? "held" : now >= N.suggest ? "suggest now" : soon >= N.suggest ? "coming soon" : "hold back";
+    return { type: `department:${d.id}`, layer: "operations", now, next: soon, status, why: d.why };
+  });
+  return { phase, next: next ?? null, facts: f, rows, departments };
+}
+
+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/need-now.mjs <venture dir> [--json]"); process.exit(2); }
+  const r = needNow(dir);
+  if (process.argv.includes("--json")) { console.log(JSON.stringify(r, null, 2)); process.exit(0); }
+  console.log(`Phase ${r.phase}${r.next ? `, next ${r.next}` : ""}. Work on what is needed now; the rest waits until it is.`);
+  for (const status of ["suggest now", "coming soon", "held", "hold back", "layer off"]) {
+    const rows = [...r.rows, ...r.departments].filter((x) => x.status === status);
+    if (!rows.length) continue;
+    console.log(`\n${status} (${rows.length})`);
+    for (const x of rows.sort((a, b) => b.now - a.now)) console.log(`  ${x.type.padEnd(32)} now ${x.now.toFixed(2)}  next ${x.next.toFixed(2)}  ${["hold back", "layer off"].includes(status) ? "" : x.why}`);
+  }
+}

package/schema/nextjs-status.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "nextjs-status.schema.json",
+  "title": "Next.js translation status",
+  "description": "Whether each concept of the Next.js translation ledger is built, and the docs page that explains it. Checked by schema/check-nextjs-status.mjs.",
+  "type": "object",
+  "required": ["about", "checked", "rows"],
+  "additionalProperties": false,
+  "properties": {
+    "about": { "type": "string" },
+    "checked": { "type": "string", "format": "date" },
+    "rows": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "chapter", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[A-Z]-[0-9]+$" },
+          "chapter": { "type": "string" },
+          "status": { "enum": ["built", "partial", "not built", "n/a"] },
+          "evidence": { "type": "array", "items": { "type": "string" } },
+          "page": { "type": "string" },
+          "note": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/schema/ownership.schema.json

@@ -0,0 +1,282 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "ownership.schema.json",
+  "title": "Ownership (cap table)",
+  "description": "Who owns the venture and on what terms, at <venture>/governance/ownership.json (EE-022): share classes and the rights each carries, holders, grants with vesting, the option pool, and unpriced instruments such as SAFEs. It is a record of what was agreed, not the legal document: the signed documents are the truth, and decisions to change this file are founder decisions made with counsel (decision class ownership-or-control). schema/check-governance.mjs checks it; schema/payouts.mjs computes payouts from it.",
+  "type": "object",
+  "required": [
+    "updated",
+    "unit",
+    "classes",
+    "holders",
+    "grants"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "updated": {
+      "type": "string",
+      "format": "date"
+    },
+    "unit": {
+      "enum": [
+        "shares",
+        "units",
+        "percent"
+      ],
+      "description": "shares for a corporation, units for an LLC, percent for a partnership or an informal split"
+    },
+    "currency": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "classes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "kind"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "name": {
+            "type": "string"
+          },
+          "kind": {
+            "enum": [
+              "common",
+              "preferred",
+              "units"
+            ],
+            "description": "common and units are paid last; preferred carries a liquidation preference"
+          },
+          "votes_per_share": {
+            "type": "number",
+            "minimum": 0,
+            "description": "1 by default; more than 1 for super-voting (dual-class) shares, 0 for non-voting"
+          },
+          "price_per_share": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Original issue price; the basis of a liquidation preference"
+          },
+          "liquidation": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "multiple": {
+                "type": "number",
+                "minimum": 0,
+                "description": "1 is standard (1x)"
+              },
+              "participating": {
+                "type": "boolean",
+                "description": "true: takes its preference and then shares the rest; false (standard): takes the greater of its preference or what it would get as common"
+              },
+              "seniority": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Higher is paid first; equal ranks share pro rata (pari passu)"
+              }
+            }
+          },
+          "rights": {
+            "type": "array",
+            "items": {
+              "enum": [
+                "board-seat",
+                "board-observer",
+                "information",
+                "pro-rata",
+                "protective-provisions",
+                "anti-dilution-broad-based",
+                "anti-dilution-full-ratchet",
+                "drag-along",
+                "tag-along",
+                "right-of-first-refusal",
+                "co-sale",
+                "registration",
+                "redemption"
+              ]
+            },
+            "description": "Investor rights this class carries"
+          }
+        }
+      }
+    },
+    "holders": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "name",
+          "kind"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "name": {
+            "type": "string"
+          },
+          "kind": {
+            "enum": [
+              "founder",
+              "employee",
+              "advisor",
+              "investor",
+              "pool",
+              "other"
+            ],
+            "description": "pool is the reserved option pool: its unissued amount is paid nothing"
+          },
+          "role": {
+            "type": "string",
+            "description": "The venture role they hold, if any"
+          },
+          "agreement": {
+            "type": "string",
+            "description": "Path to their signed agreement (advisor, employee, investment)"
+          }
+        }
+      }
+    },
+    "grants": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "holder",
+          "class",
+          "amount"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "holder": {
+            "type": "string"
+          },
+          "class": {
+            "type": "string"
+          },
+          "amount": {
+            "type": "number",
+            "exclusiveMinimum": 0
+          },
+          "granted": {
+            "type": "string",
+            "format": "date"
+          },
+          "vesting": {
+            "type": "object",
+            "required": [
+              "start",
+              "months"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "start": {
+                "type": "string",
+                "format": "date"
+              },
+              "months": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "48 is common for founders and employees, 24 for advisors"
+              },
+              "cliff_months": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "12 is common"
+              },
+              "acceleration": {
+                "enum": [
+                  "none",
+                  "single-trigger",
+                  "double-trigger"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "instruments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "holder",
+          "kind",
+          "amount"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "holder": {
+            "type": "string"
+          },
+          "kind": {
+            "enum": [
+              "safe-post-money",
+              "safe-pre-money",
+              "convertible-note"
+            ]
+          },
+          "amount": {
+            "type": "number",
+            "exclusiveMinimum": 0
+          },
+          "signed": {
+            "type": "string",
+            "format": "date"
+          },
+          "valuation_cap": {
+            "type": "number",
+            "exclusiveMinimum": 0
+          },
+          "discount": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "converts_to": {
+            "type": "string",
+            "description": "The class it converts into at the next priced round"
+          },
+          "rights": {
+            "type": "array",
+            "items": {
+              "enum": [
+                "board-seat",
+                "board-observer",
+                "information",
+                "pro-rata",
+                "protective-provisions",
+                "anti-dilution-broad-based",
+                "anti-dilution-full-ratchet",
+                "drag-along",
+                "tag-along",
+                "right-of-first-refusal",
+                "co-sale",
+                "registration",
+                "redemption"
+              ]
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schema/packages.json

@@ -0,0 +1,4 @@
+{
+  "alias_of": "packages/",
+  "note": "Split into packages/<name>/package.json and packages/catalog.json (EE-071). This file remains as the alias for one release. Loaders read the package files, not this stub."
+}