naive-framework 0.0.0-stage → 0.2.0

package/schema/publication-policy.schema.json

@@ -0,0 +1,293 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "publication-policy.schema.json",
+  "title": "Publication policy",
+  "description": "Where a venture publishes and who may publish what there, at <venture>/governance/publication-policy.json (EE-025). Every publication passes the gate: it runs as a handoff under the public-commitment decision class, names its channel, passes the channel's checks and preview, and is approved by a person. Agents may draft and check; they never approve.",
+  "type": "object",
+  "required": [
+    "venture",
+    "channels"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "venture": {
+      "type": "string"
+    },
+    "updated": {
+      "type": "string",
+      "format": "date"
+    },
+    "note": {
+      "type": "string"
+    },
+    "teams": {
+      "type": "array",
+      "description": "Groups that draft or approve, such as a marketing team or a governance team. Members are role ids from the role registry.",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "members"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "pillar": {
+            "enum": [
+              "product",
+              "brand",
+              "business"
+            ]
+          },
+          "members": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "guidelines": {
+      "type": "array",
+      "description": "The rules a publication must follow: the venture's own (brand guidelines, editorial guidelines) and outside ones (a platform's rules, advertising or disclosure law).",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "title",
+          "kind"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "kind": {
+            "enum": [
+              "brand",
+              "editorial",
+              "legal",
+              "platform",
+              "disclosure",
+              "security",
+              "other"
+            ]
+          },
+          "owner": {
+            "type": "string",
+            "description": "Pillar or role that keeps it"
+          },
+          "path": {
+            "type": "string",
+            "description": "Relative to the venture folder"
+          },
+          "url": {
+            "type": "string"
+          },
+          "checked": {
+            "type": "string",
+            "format": "date",
+            "description": "When an outside guideline's URL was last checked"
+          }
+        }
+      }
+    },
+    "channels": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "name",
+          "kind",
+          "destination",
+          "rules",
+          "checks",
+          "preview"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "kind": {
+            "enum": [
+              "website",
+              "docs-site",
+              "blog",
+              "social",
+              "newsletter",
+              "email",
+              "app-store",
+              "press",
+              "investor-update",
+              "regulatory-filing",
+              "open-source-repository",
+              "other"
+            ]
+          },
+          "destination": {
+            "type": "string",
+            "description": "Where it lands: a URL, an account, a repository or a recipient list"
+          },
+          "audience": {
+            "type": "string"
+          },
+          "guidelines": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Guideline ids that apply here"
+          },
+          "rules": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Who may publish what on this channel",
+            "items": {
+              "type": "object",
+              "required": [
+                "content",
+                "approvers"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "content": {
+                  "type": "string",
+                  "description": "The kind of content, e.g. methodology pages, release notes, a funding announcement"
+                },
+                "from_layers": {
+                  "type": "array",
+                  "items": {
+                    "enum": [
+                      "purpose",
+                      "knowledge",
+                      "operations",
+                      "evidence",
+                      "governance",
+                      "interface"
+                    ]
+                  },
+                  "description": "The layers whose records it may publish"
+                },
+                "drafters": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Role or team ids; agents may draft"
+                },
+                "approvers": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Role or team ids; at least one is a person, and no agent approves"
+                }
+              }
+            }
+          },
+          "checks": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "required": [
+                "id",
+                "check"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "check": {
+                  "type": "string",
+                  "description": "A command run from the repository root; for a review, what the reviewer checks"
+                },
+                "kind": {
+                  "enum": [
+                    "conformance",
+                    "review"
+                  ]
+                }
+              }
+            }
+          },
+          "preview": {
+            "type": "string",
+            "description": "How to see exactly what would go out before it does, e.g. a dry run"
+          },
+          "config": {
+            "type": "string",
+            "description": "The channel's tool configuration, relative to the venture folder (e.g. the publisher's allowlist)"
+          },
+          "platform": {
+            "enum": [
+              "substack",
+              "medium",
+              "x",
+              "facebook",
+              "instagram",
+              "threads",
+              "linkedin",
+              "youtube",
+              "tiktok",
+              "reddit",
+              "bluesky",
+              "mastodon",
+              "discord",
+              "app-store",
+              "google-play",
+              "github",
+              "other"
+            ],
+            "description": "The third-party platform the channel runs on, if any. A channel on a platform cites that platform's rules (a guideline of kind platform)"
+          },
+          "replies": {
+            "type": "object",
+            "required": [
+              "mode"
+            ],
+            "additionalProperties": false,
+            "description": "Required on social, newsletter and blog channels: replies, comments and direct messages speak for the venture in public. gated means each reply passes the gate like any publication; delegated means named people may reply within the guidelines without a handoff each time; none means the venture does not reply there",
+            "properties": {
+              "mode": {
+                "enum": [
+                  "gated",
+                  "delegated",
+                  "none"
+                ]
+              },
+              "delegates": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Role or team ids, when delegated; each must include a person"
+              },
+              "note": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schema/raw-source.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "raw-source.schema.json",
+  "title": "Raw source",
+  "description": "Where a founder-supplied source came from, at raw/sources/<id>/source.json (EE-070). text.md is the text. original.* stays out of git. Raw is immutable.",
+  "type": "object",
+  "required": ["id", "origin"],
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "origin": { "type": "string", "description": "Where this source came from: a url, a person, or a note such as founder-supplied" },
+    "title": { "type": "string" },
+    "fetched": { "type": "string", "format": "date" }
+  }
+}

package/schema/reference.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "reference.schema.json",
+  "title": "References",
+  "description": "A layer's references (EE-014): the sources behind its opinionated defaults and the alternatives it considered. One file per layer at <layer>/references/references.json. A URL is recorded when one exists and re-checked; the find-reference skill fills gaps from title, authors and year.",
+  "type": "object",
+  "required": [
+    "layer",
+    "references"
+  ],
+  "properties": {
+    "layer": {
+      "enum": [
+        "purpose",
+        "knowledge",
+        "operations",
+        "evidence",
+        "governance",
+        "interface"
+      ]
+    },
+    "references": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "title",
+          "authors",
+          "year",
+          "kind",
+          "summary",
+          "informs",
+          "stance"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "title": {
+            "type": "string"
+          },
+          "authors": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "year": {
+            "type": "integer"
+          },
+          "kind": {
+            "enum": [
+              "book",
+              "article",
+              "paper",
+              "standard",
+              "law",
+              "dataset",
+              "conversation"
+            ]
+          },
+          "summary": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string",
+            "format": "uri"
+          },
+          "checked": {
+            "type": "string",
+            "format": "date",
+            "description": "When the url last resolved"
+          },
+          "informs": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^(noun|phase|gate|rule|field):[a-z0-9-_.]+$"
+            }
+          },
+          "stance": {
+            "type": "object",
+            "required": [
+              "is",
+              "why"
+            ],
+            "properties": {
+              "is": {
+                "enum": [
+                  "adopted",
+                  "adapted",
+                  "alternative",
+                  "rejected"
+                ]
+              },
+              "why": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "dependentRequired": {
+          "checked": [
+            "url"
+          ]
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schema/release-read.mjs

@@ -0,0 +1,111 @@
+// Reading a release without the router (C-12, I-17). A release is the venture's static shell
+// (C-11): the confirmed records frozen in, and named holes for what stays live. Everything here
+// reads <venture>/.release/ and nothing else, so a release can be read after the venture's records
+// change, on a machine with no router, or handed to an investor as files. It never imports
+// interface/router.mjs; schema/releases-test.mjs checks that.
+//
+// The answer to a path is { status, type, body }:
+//   /                    the release index: venture, phase, release id, routes in the release, holes
+//   /release.json        the manifest;  /card.json  the release card's data (P-25, O-7)
+//   /records/<file>      one frozen record, as it was when it was confirmed
+//   /<route>             a route as the release holds it: a frozen record, a collection's frozen items,
+//                        a frozen command answer (H-4), or a hole that names where to read it live.
+//                        An item the release does not hold answers 404 with the items it does and the
+//                        command that adds it without rebuilding the rest (C-18, N-10).
+// Any method other than GET or HEAD answers 405: a release is read-only.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, normalize } from "node:path";
+
+export const RELEASE_DIR = ".release";
+export const MANIFEST = ".release/release.json";
+export const CARD = ".release/card.json";
+export const RECORDS = ".release/records";
+
+/** The release manifest of a venture, or null when it has none. */
+export function readRelease(dir) {
+  const f = join(dir, MANIFEST);
+  return existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : null;
+}
+
+/** The frozen copy of one record in a release, as text, or null. */
+export function frozenText(dir, file) {
+  const rel = normalize(file);
+  if (rel.startsWith("..") || rel.startsWith("/")) return null;
+  const f = join(dir, RECORDS, rel);
+  return existsSync(f) ? readFileSync(f, "utf8") : null;
+}
+
+const parse = (file, text) => file.endsWith(".json") ? JSON.parse(text) : text;
+const json = (status, body) => ({ status, type: "application/json; charset=utf-8", body: JSON.stringify(body, null, 2) + "\n" });
+
+/** The index a reader starts from. */
+export function index(m) {
+  return { release: m.release, venture: m.venture, name: m.name, phase: m.phase, built_at: m.built_at, now: m.now,
+    routes: m.routes.filter((r) => r.in === "release").map((r) => r.route),
+    holes: m.holes.map((h) => ({ kind: h.kind, route: h.route, name: h.name, why: h.why })),
+    card: "/card.json", manifest: "/release.json",
+    note: "A release is read-only. Holes stay live: read them in the venture through the router." };
+}
+
+/** What a route holds in a release: { status, body }. Matches a concrete route (product/kettle) to its entry. */
+export function resolveRoute(dir, m, route) {
+  route = route.replace(/^\/+|\/+$/g, "");
+  const exact = m.routes.find((r) => r.route === route);
+  const entry = exact ?? m.routes.find((r) => r.route.endsWith("/[id]") && route.startsWith(r.route.slice(0, -4)) && !route.slice(r.route.length - 4).includes("/"));
+  if (!entry) return { status: 404, body: { error: `no route ${route} in release ${m.release}` } };
+  const id = exact ? null : route.slice(entry.route.length - 4);
+  const holes = m.holes.filter((h) => h.route === route || h.route_template === entry.route);
+  // A decision is also found by its id (decisions/founding-team), whatever its file is called.
+  const own = holes.find((h) => (h.route === route || (h.kind === "decision" && `decisions/${h.name}` === route)) && h.kind !== "attribute");
+  if (entry.in === "hole") return { status: 200, body: { route, hole: true, kind: own?.kind ?? entry.kind, why: own?.why ?? entry.why, live: own?.live ?? entry.live ?? null, ...(own ? {} : { holes }) } };
+  if (entry.in === "left out") return { status: 404, body: { route, left_out: true, why: entry.why } };
+  if (entry.kind === "command") {
+    const out = m.commands?.[entry.route];
+    return out === undefined ? { status: 404, body: { route, empty: true, why: entry.why ?? "not in this release" } } : { status: 200, body: { route, frozen: true, built_from: out.built_from, result: out.result } };
+  }
+  const recs = m.records.filter((r) => r.route_template === entry.route);
+  const fieldHoles = (r) => m.holes.filter((h) => h.kind === "attribute" && h.file === r.file).map((h) => h.field);
+  const one = (r) => ({ file: r.file, as_of: r.as_of, confirmed_by: r.confirmed_by, ...(fieldHoles(r).length ? { live_fields: fieldHoles(r) } : {}), record: parse(r.file, frozenText(dir, r.file)) });
+  if (entry.collection === "list") {
+    const items = m.records.filter((r) => r.route_template === `${entry.route}/[id]`);
+    return { status: 200, body: { route, items: Object.fromEntries(items.map((r) => [r.id, one(r)])), holes } };
+  }
+  if (entry.collection === "item") {
+    const hit = recs.find((r) => r.id === id);
+    if (own) return { status: 200, body: { route, hole: true, kind: own.kind, why: own.why, live: own.live ?? null } };
+    if (!hit) return { status: 404, body: { route, not_in_release: true, release: m.release, items: recs.map((r) => r.id), ...(holes.length ? { live_items: holes.filter((h) => h.kind !== "attribute").map((h) => h.name) } : {}),
+      note: `${route} was not known when release ${m.release} was built`, add: `node schema/build-release.mjs <venture dir> --add ${route}` } };
+    return { status: 200, body: { route, ...one(hit) } };
+  }
+  if (!recs.length) return { status: 404, body: { route, empty: true, why: entry.why ?? "no confirmed record when the release was built" } };
+  return { status: 200, body: { route, ...(recs.length === 1 ? one(recs[0]) : { records: recs.map(one) }) } };
+}
+
+/**
+ * Answers one request against a venture's release. draw, when given, turns the card's data into an
+ * image (the interface's job, O-7): draw(card) -> SVG text.
+ */
+export function answer(dir, method, path, { draw } = {}) {
+  if (method !== "GET" && method !== "HEAD") return { ...json(405, { error: "a release is read-only: only GET and HEAD" }), allow: "GET, HEAD" };
+  const m = readRelease(dir);
+  if (!m) return json(503, { error: `no release in ${dir}: run node schema/build-release.mjs ${dir} first` });
+  const p = decodeURIComponent(path.split("?")[0]);
+  if (p.split("/").includes("..")) return json(400, { error: "no .. in a release path" });
+  if (p === "/" || p === "") return json(200, index(m));
+  if (p === "/release.json") return json(200, m);
+  if (p === "/card.json") return existsSync(join(dir, CARD)) ? json(200, JSON.parse(readFileSync(join(dir, CARD), "utf8"))) : json(404, { error: "this release has no card" });
+  if (p === "/card.svg") {
+    if (!draw) return json(404, { error: "no card drawing here" });
+    return { status: 200, type: "image/svg+xml; charset=utf-8", body: draw(JSON.parse(readFileSync(join(dir, CARD), "utf8"))) };
+  }
+  if (p.startsWith("/records/")) {
+    const file = p.slice("/records/".length);
+    const r = m.records.find((x) => x.file === file);
+    const text = r ? frozenText(dir, file) : null;
+    if (text === null) return json(404, { error: `${file} is not in release ${m.release}` });
+    return { status: 200, type: file.endsWith(".json") ? "application/json; charset=utf-8" : "text/markdown; charset=utf-8", body: text };
+  }
+  const r = resolveRoute(dir, m, p);
+  return json(r.status, r.body);
+}