naive-framework 0.1.0 → 0.2.0

package/schema/assets.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+// Assets in public/ (I-23, J-2, J-3, J-4): the files a venture ships as they are, each with a source,
+// a license and a credit, the way raw sources answer where they came from. The register is
+// public/assets.json (schema/public-assets.schema.json). Rendering work (sizes, lazy loading) is the
+// interface's; the framework's part is rights and facts.
+//
+//   J-2  every file in public/ has a register entry naming its source and license
+//   J-3  a remote image is a link with a note in raw/sources/<id>/; a full copy in public/ needs a
+//        license that allows copying. remote_hosts is the list of hosts an agent may fetch from
+//        (the platform fetcher, platform/integrations/remote-image.mjs, enforces it)
+//   J-4  facts (type, width, height, bytes, sha256) are read from the file by code, never guessed:
+//        the check fails when recorded facts differ from the file. Alt text an agent wrote carries
+//        agent provenance until a person confirms it (a confirm entry in provenance.jsonl, bound
+//        to the exact text); a missing credit fails the check
+//
+// No model is called and nothing here reaches the network.
+//
+//   node schema/assets.mjs <venture dir> facts [--json]       the facts code reads from each file in public/
+//   node schema/assets.mjs <venture dir> check [--json]       the register check (also schema/check-assets.mjs)
+
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+import { entries } from "../interface/provenance.mjs";
+
+export const REGISTER = "public/assets.json";
+const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+
+// ---------------------------------------------------------------------------------------------
+// Facts read from the bytes. The type comes from the file's signature, not its name.
+
+const EXT = { png: ["png"], gif: ["gif"], jpeg: ["jpg", "jpeg"], webp: ["webp"], ico: ["ico"], svg: ["svg"], pdf: ["pdf"], woff2: ["woff2"], woff: ["woff"], ttf: ["ttf"], otf: ["otf"] };
+export const IMAGE = new Set(["png", "gif", "jpeg", "webp", "ico", "svg"]);
+export const FONT = new Set(["woff2", "woff", "ttf", "otf"]);
+export const MIME = { png: "image/png", gif: "image/gif", jpeg: "image/jpeg", webp: "image/webp", ico: "image/x-icon", svg: "image/svg+xml", pdf: "application/pdf", woff2: "font/woff2", woff: "font/woff", ttf: "font/ttf", otf: "font/otf" };
+
+const ascii = (b, s, n) => b.subarray(s, s + n).toString("latin1");
+
+function jpegSize(b) {
+  let i = 2;
+  while (i + 9 < b.length) {
+    if (b[i] !== 0xff) { i++; continue; }
+    const m = b[i + 1];
+    if (m === 0xff) { i++; continue; }
+    if ((m >= 0xc0 && m <= 0xc3) || (m >= 0xc5 && m <= 0xc7) || (m >= 0xc9 && m <= 0xcb) || (m >= 0xcd && m <= 0xcf)) return { height: b.readUInt16BE(i + 5), width: b.readUInt16BE(i + 7) };
+    if (m === 0xd8 || m === 0x01 || (m >= 0xd0 && m <= 0xd7)) { i += 2; continue; }
+    i += 2 + b.readUInt16BE(i + 2);
+  }
+  return {};
+}
+
+function webpSize(b) {
+  const chunk = ascii(b, 12, 4);
+  if (chunk === "VP8 " && b.length >= 30) return { width: b.readUInt16LE(26) & 0x3fff, height: b.readUInt16LE(28) & 0x3fff };
+  if (chunk === "VP8L" && b.length >= 25) {
+    const [b0, b1, b2, b3] = [b[21], b[22], b[23], b[24]];
+    return { width: 1 + (((b1 & 0x3f) << 8) | b0), height: 1 + (((b3 & 0x0f) << 10) | (b2 << 2) | ((b1 & 0xc0) >> 6)) };
+  }
+  if (chunk === "VP8X" && b.length >= 30) return { width: 1 + b.readUIntLE(24, 3), height: 1 + b.readUIntLE(27, 3) };
+  return {};
+}
+
+function svgSize(text) {
+  const tag = text.match(/<svg\b[^>]*>/i)?.[0] ?? "";
+  const attr = (n) => tag.match(new RegExp(`\\s${n}\\s*=\\s*["']\\s*([0-9.]+)(px)?\\s*["']`, "i"));
+  const w = attr("width"), h = attr("height");
+  if (w && h) return { width: Math.round(Number(w[1])), height: Math.round(Number(h[1])) };
+  const vb = tag.match(/viewBox\s*=\s*["']\s*[-0-9.]+[\s,]+[-0-9.]+[\s,]+([0-9.]+)[\s,]+([0-9.]+)\s*["']/i);
+  return vb ? { width: Math.round(Number(vb[1])), height: Math.round(Number(vb[2])) } : {};
+}
+
+/** What the bytes say: type, width and height for images, the sizes an icon holds, bytes and sha256. */
+export function factsOf(buf) {
+  const b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
+  let type = "unknown", dims = {}, sizes;
+  if (b.length >= 24 && b[0] === 0x89 && ascii(b, 1, 3) === "PNG") { type = "png"; dims = { width: b.readUInt32BE(16), height: b.readUInt32BE(20) }; }
+  else if (b.length >= 10 && /^GIF8[79]a$/.test(ascii(b, 0, 6))) { type = "gif"; dims = { width: b.readUInt16LE(6), height: b.readUInt16LE(8) }; }
+  else if (b.length >= 4 && b[0] === 0xff && b[1] === 0xd8) { type = "jpeg"; dims = jpegSize(b); }
+  else if (b.length >= 16 && ascii(b, 0, 4) === "RIFF" && ascii(b, 8, 4) === "WEBP") { type = "webp"; dims = webpSize(b); }
+  else if (b.length >= 6 && b.readUInt16LE(0) === 0 && b.readUInt16LE(2) === 1 && b.readUInt16LE(4) > 0) {
+    type = "ico";
+    const n = b.readUInt16LE(4);
+    sizes = [];
+    for (let k = 0; k < n && 6 + 16 * k + 1 < b.length; k++) { const w = b[6 + 16 * k] || 256, h = b[7 + 16 * k] || 256; sizes.push(`${w}x${h}`); }
+    const big = sizes.map((s) => s.split("x").map(Number)).sort((x, y) => y[0] * y[1] - x[0] * x[1])[0];
+    if (big) dims = { width: big[0], height: big[1] };
+  }
+  else if (ascii(b, 0, 5) === "%PDF-") type = "pdf";
+  else if (ascii(b, 0, 4) === "wOF2") type = "woff2";
+  else if (ascii(b, 0, 4) === "wOFF") type = "woff";
+  else if (ascii(b, 0, 4) === "OTTO") type = "otf";
+  else if (b.length >= 4 && b.readUInt32BE(0) === 0x00010000) type = "ttf";
+  else {
+    const head = b.subarray(0, 4096).toString("utf8");
+    if (/<svg\b/i.test(head)) { type = "svg"; dims = svgSize(b.toString("utf8")); }
+  }
+  return { type, ...(dims.width ? { width: dims.width, height: dims.height } : {}), ...(sizes ? { sizes } : {}), bytes: b.length, sha256: createHash("sha256").update(b).digest("hex") };
+}
+
+/** The file's extension agrees with what its bytes are. */
+export const extensionFits = (path, type) => (EXT[type] ?? []).includes(extname(path).slice(1).toLowerCase());
+
+// ---------------------------------------------------------------------------------------------
+// Licenses. Copying a work into public/ (so a release ships it) needs a license that allows it.
+
+const COPYABLE = ["cc0-1.0", "cc-by-4.0", "cc-by-3.0", "cc-by-sa-4.0", "cc-by-sa-3.0", "mit", "apache-2.0", "ofl-1.1", "bsd-2-clause", "bsd-3-clause", "isc", "unlicense", "public-domain", "owned", "licensed"];
+/** Whether a license lets the venture keep and ship a full copy. Unknown, all-rights-reserved and editorial-only do not. */
+export const allowsCopy = (license) => COPYABLE.includes(String(license ?? "").trim().toLowerCase());
+export const LICENSES_THAT_COPY = COPYABLE;
+
+/** A host allowlist entry matches a host exactly, or "*.example.com" matches any subdomain of it. */
+export const hostAllowed = (host, hosts = []) => hosts.some((h) => h === host || (h.startsWith("*.") && host.endsWith(h.slice(1))));
+
+/** The hash a person's confirmation of one alt text is bound to: the statement id in provenance. */
+export const altStatement = (path, text) => `alt-${createHash("sha256").update(`${path}\n${text}`).digest("hex").slice(0, 16)}`;
+
+// ---------------------------------------------------------------------------------------------
+// The register and its check.
+
+/** The files in public/, relative to the venture folder, without the register itself. */
+export function publicFiles(dir) {
+  const root = join(dir, "public");
+  const walk = (d) => existsSync(d) ? readdirSync(d, { withFileTypes: true }).flatMap((e) => e.name.startsWith(".") ? [] : e.isDirectory() ? walk(join(d, e.name)) : [join(d, e.name)]) : [];
+  return walk(root).map((f) => f.slice(dir.length + 1)).filter((f) => f !== REGISTER).sort();
+}
+
+export const registerOf = (dir) => existsSync(join(dir, REGISTER)) ? load(join(dir, REGISTER)) : null;
+
+/** The facts code reads from every file in public/. */
+export function facts(dir) {
+  return publicFiles(dir).map((path) => ({ path, ...factsOf(readFileSync(join(dir, path))) }));
+}
+
+/** Which alt texts a person has confirmed, from the provenance log. */
+export function confirmedAlts(dir) {
+  return new Set(entries(dir).filter((e) => e.activity === "confirm" && e.agent?.kind === "person" && e.statement?.startsWith("alt-")).map((e) => e.statement));
+}
+
+/**
+ * The register check. errors fail it; pending lists alt text an agent wrote that no person has
+ * confirmed yet (not an error: it ships with agent provenance until then).
+ */
+export function checkAssets(dir) {
+  const errors = [], warnings = [], pending = [];
+  const reg = registerOf(dir);
+  const files = publicFiles(dir);
+  if (!reg) {
+    for (const f of files) errors.push(`${f}: no entry in ${REGISTER}, so nothing says where it came from or whether the venture may ship it (J-2)`);
+    return { ok: !errors.length, errors, warnings, pending, assets: 0, remote: 0 };
+  }
+  const listed = new Map((reg.assets ?? []).map((a) => [a.path, a]));
+  const confirmed = confirmedAlts(dir);
+  const remoteByUrl = new Map((reg.remote ?? []).map((r) => [r.url, r]));
+  for (const f of files) if (!listed.has(f)) errors.push(`${f}: no entry in ${REGISTER}, so nothing says where it came from or whether the venture may ship it (J-2)`);
+  const seen = new Set();
+  for (const a of reg.assets ?? []) {
+    if (seen.has(a.path)) errors.push(`${a.path}: listed twice`);
+    seen.add(a.path);
+    if (!existsSync(join(dir, a.path))) { errors.push(`${a.path}: listed in ${REGISTER} but the file is not there`); continue; }
+    const real = factsOf(readFileSync(join(dir, a.path)));
+    if (String(a.license).trim().toLowerCase() === "unknown") errors.push(`${a.path}: the license is unknown; find it before the venture ships the file (J-2)`);
+    if (!a.credit || !String(a.credit).trim()) errors.push(`${a.path}: no credit; say who made it (J-4)`);
+    if (real.type !== "unknown" && !extensionFits(a.path, real.type)) errors.push(`${a.path}: the bytes are ${real.type}, the name says otherwise`);
+    // Facts are code's: recorded facts must equal what the file says now.
+    if (!a.facts) errors.push(`${a.path}: no facts yet; run mentura assets fill so code records them (J-4)`);
+    else for (const k of ["type", "width", "height", "bytes", "sha256"]) if ((a.facts[k] ?? null) !== (real[k] ?? null)) { errors.push(`${a.path}: recorded ${k} ${a.facts[k] ?? "none"} is not the file's ${real[k] ?? "none"}; facts are filled by code, run mentura assets fill (J-4)`); break; }
+    // Alt text: an image needs it unless it is decorative; an agent's stays pending until a person confirms it.
+    if (IMAGE.has(real.type)) {
+      if (!a.alt?.text && !a.decorative) errors.push(`${a.path}: an image with no alt text; write it, or mark it decorative (J-4)`);
+      if (a.alt?.text) {
+        const ok = confirmed.has(altStatement(a.path, a.alt.text));
+        if (a.alt.by === "person" && !ok) errors.push(`${a.path}: alt text says a person wrote it, but provenance has no person's confirmation of this text (J-4)`);
+        if (a.alt.by !== "person" && !ok) pending.push({ path: a.path, alt: a.alt.text, by: a.alt.by ?? "agent", confirm: `mentura assets confirm ${a.path} --by <name> --confirm ${a.path}` });
+      }
+    }
+    // A copy of a remote work (J-3): its link must be in the register, and its license must allow a copy.
+    if (a.origin_url) {
+      const r = remoteByUrl.get(a.origin_url);
+      if (!r) errors.push(`${a.path}: copied from ${a.origin_url}, which has no remote entry with a note in raw/ (J-3)`);
+      if (!allowsCopy(a.license)) errors.push(`${a.path}: a full copy of ${a.origin_url} under license ${a.license}; keep it private (raw/sources/*/original.*) unless the license allows a copy (J-3)`);
+    }
+  }
+  for (const r of reg.remote ?? []) {
+    const src = join(dir, "raw/sources", r.id, "source.json");
+    if (!existsSync(src)) errors.push(`remote ${r.url}: no note in raw/sources/${r.id}/ (J-3)`);
+    else if (load(src).origin !== r.url) errors.push(`remote ${r.url}: raw/sources/${r.id}/source.json names another origin`);
+    let host = null;
+    try { host = new URL(r.url).host; } catch { errors.push(`remote ${r.url}: not a URL`); }
+    if (r.fetched && host && !hostAllowed(host, reg.remote_hosts ?? [])) errors.push(`remote ${r.url}: fetched from ${host}, which is not in remote_hosts, the hosts an agent may fetch from (J-3)`);
+    if (!r.credit) errors.push(`remote ${r.url}: no credit; say who made it (J-4)`);
+    if (r.copy && !allowsCopy(r.license)) errors.push(`remote ${r.url}: copied to ${r.copy} under license ${r.license}, which does not allow a copy (J-3)`);
+    if (r.copy && !listed.has(r.copy)) errors.push(`remote ${r.url}: copied to ${r.copy}, which is not in the register`);
+  }
+  return { ok: !errors.length, errors, warnings, pending, assets: (reg.assets ?? []).length, remote: (reg.remote ?? []).length };
+}
+
+// ---------------------------------------------------------------------------------------------
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const [dir, mode = "check"] = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+  const json = process.argv.includes("--json");
+  if (!dir || !existsSync(join(dir, "venture.json")) || !statSync(dir).isDirectory()) { console.error("usage: node schema/assets.mjs <venture dir> facts|check [--json]"); process.exit(2); }
+  if (mode === "facts") { const f = facts(dir); console.log(json ? JSON.stringify({ facts: f }, null, 2) : f.map((x) => `${x.path}  ${x.type}${x.width ? ` ${x.width}x${x.height}` : ""}  ${x.bytes} bytes`).join("\n") || "public/ is empty"); process.exit(0); }
+  const r = checkAssets(dir);
+  if (json) console.log(JSON.stringify(r, null, 2));
+  else {
+    for (const e of r.errors) console.log(`error  ${e}`);
+    for (const p of r.pending) console.log(`pending  ${p.path}: alt text by ${p.by}, not confirmed by a person`);
+    console.log(r.ok ? `assets: ${r.assets} files and ${r.remote} remote links have a source, license, credit and facts` : `assets: ${r.errors.length} errors`);
+  }
+  process.exit(r.ok ? 0 : 1);
+}

package/schema/brand.mjs

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+// The venture's brand (Next.js CSS, Fonts and file-based metadata, translated): brand tokens in the
+// marketing package, read by every view and every agent. Styling itself stays with the interface;
+// what converts is the brand.
+//
+//   Y-3  brand tokens (colors, typefaces, voice rules) live in marketing/brand.json, the global
+//        stylesheet. Voice rules are the global stylesheet for words: every agent's layout carries
+//        them, and the voice check holds marketing content to them
+//   Y-5  nearer context wins. brand.json scopes override the venture brand for a route prefix,
+//   T-2  a package's scope under an item's; a typeface is defined once and assigned to a role at
+//        the root (everywhere) or in a scope (only there), like next/font
+//   T-1  typefaces are brand tokens recorded with their license, self-hosted from public/ so a
+//        browser makes no outside request
+//   Y-4  an outside design system is a reference: linked, with its version and license, not copied
+//   Y-2  a package's own terms stay local: glossary/<package>.json terms reach other packages
+//        only when the glossary exports them
+//   P-24 the venture's logo and marks (logo, icon, apple-icon, favicon) are brand marks pointing at
+//        registered assets in public/, checked for type and size
+//   P-26 the sitemap is a marketing record (marketing/sitemap.json); sitemap.xml is rendered from
+//        it for a release, never from the framework's routes
+//
+// No model is called and nothing here reaches the network.
+//
+//   node schema/brand.mjs <venture dir> tokens [--json]            DTCG tokens, CSS and head links for the venture
+//   node schema/brand.mjs <venture dir> --for <route> [--json]     the brand resolved at a route (nearer wins)
+//   node schema/brand.mjs <venture dir> voice [--json]             marketing content against the voice rules
+//   node schema/brand.mjs <venture dir> --package <id> [--json]    the terms a package sees (its own and exported ones)
+//   node schema/brand.mjs <venture dir> --base <url> [--json]      sitemap.xml from the marketing sitemap
+//   node schema/brand.mjs <venture dir> check [--json]             the brand check (also schema/check-brand.mjs)
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { allowsCopy, factsOf, registerOf, REGISTER } from "./assets.mjs";
+
+export const BRAND = "marketing/brand.json";
+export const SITEMAPS = ["marketing/sitemap.json", "operations/marketing/sitemap.json"];
+const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+export const brandOf = (dir) => dir && existsSync(join(dir, BRAND)) ? load(join(dir, BRAND)) : null;
+
+// ---------------------------------------------------------------------------------------------
+// Router hooks. interface/router.mjs spreads these into its tables; this module never imports the router.
+
+/** Where the new record types route (package folder layout, EE-070). */
+export const BRAND_ROUTES = { "marketing-brand": "marketing/brand", "public-assets": "public/assets", glossary: "glossary" };
+
+/** The command routes this module adds, built with the router's own cmd(). */
+export const brandCommands = (cmd) => [
+  cmd("marketing/brand/tokens", "schema/brand.mjs", "The venture's brand tokens (Y-3): colors and typefaces as W3C design tokens, the CSS custom properties and @font-face rules an interface loads, each scope as its own selector, and the head links for the venture's marks (P-24)", { args: ["tokens"] }),
+  cmd("marketing/brand/resolve", "schema/brand.mjs", "The brand at one route (Y-5, T-2): the venture brand with every scope that covers the route applied, nearer last, and which scope set each value; input value is the route", { value_flag: "--for" }),
+  cmd("marketing/voice", "schema/brand.mjs", "Marketing content held to the voice rules, the global stylesheet for words (Y-3): each phrase to avoid, where it is and what to use instead; and terms another package keeps local (Y-2)", { args: ["voice"] }),
+  cmd("glossary/terms", "schema/brand.mjs", "The terms one package sees (Y-2): its own glossary and the terms other packages export; their local terms stay with them. Input value is the package", { value_flag: "--package" }),
+  cmd("marketing/sitemap/xml", "schema/brand.mjs", "sitemap.xml rendered from the marketing sitemap record (P-26), for a release; input value is the site's base URL", { value_flag: "--base" }),
+  cmd("public/assets/facts", "schema/assets.mjs", "What code reads from each file in public/ (J-4): type from the bytes, width and height, icon sizes, bytes and sha256. Agents copy these, never guess them", { args: ["facts"] }),
+];
+
+/** What a layout adds for an agent: the brand and voice at this route, and the terms its package sees. */
+export function brandLayout(dir, route) {
+  if (!dir) return null;
+  const brand = brandOf(dir);
+  const pkg = route.split("/")[0];
+  const terms = glossaries(dir).size ? termsFor(dir, pkg) : null;
+  if (!brand && !terms) return null;
+  const at = brand ? resolveBrand(brand, route) : null;
+  return {
+    ...(at ? { name: at.name, tone: at.voice.tone, voice: at.voice.rules.map((r) => ({ id: r.id, avoid: r.avoid, use: r.use ?? null, why: r.why ?? null })), fonts: Object.fromEntries(Object.entries(at.fonts).map(([role, t]) => [role, t.family])), colors: at.colors, scopes: at.scopes } : {}),
+    ...(terms ? { terms: terms.terms.map((t) => ({ term: t.term, meaning: t.meaning, from: t.from })) } : {}),
+  };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Resolution: nearer context wins (Y-5, T-2).
+
+const covers = (scope, route) => route === scope || route.startsWith(`${scope}/`);
+const depth = (s) => s.split("/").filter(Boolean).length;
+
+/**
+ * The brand at a route: the venture's colors, font roles and voice rules, then each scope whose
+ * `for` covers the route, shallowest first, so the nearest scope wins. set_by says which scope set
+ * each value (the venture brand is "venture").
+ */
+export function resolveBrand(brand, route = "") {
+  const faces = new Map((brand.typefaces ?? []).map((t) => [t.id, t]));
+  const colors = { ...(brand.colors ?? {}) };
+  const roles = { ...(brand.fonts ?? {}) };
+  const rules = new Map((brand.voice?.rules ?? []).map((r) => [r.id, r]));
+  let tone = brand.voice?.tone ?? [];
+  const set_by = {};
+  for (const k of Object.keys(colors)) set_by[`color.${k}`] = "venture";
+  for (const k of Object.keys(roles)) set_by[`font.${k}`] = "venture";
+  for (const k of rules.keys()) set_by[`voice.${k}`] = "venture";
+  const scopes = (brand.scopes ?? []).filter((s) => covers(s.for, route)).sort((a, b) => depth(a.for) - depth(b.for));
+  for (const s of scopes) {
+    for (const [k, v] of Object.entries(s.colors ?? {})) { colors[k] = v; set_by[`color.${k}`] = s.for; }
+    for (const [k, v] of Object.entries(s.fonts ?? {})) { roles[k] = v; set_by[`font.${k}`] = s.for; }
+    for (const r of s.voice?.rules ?? []) { rules.set(r.id, r); set_by[`voice.${r.id}`] = s.for; }
+    if (s.voice?.tone) tone = s.voice.tone;
+  }
+  const fonts = Object.fromEntries(Object.entries(roles).filter(([, id]) => faces.has(id)).map(([role, id]) => [role, faces.get(id)]));
+  return { route, name: brand.name ?? null, colors, fonts, voice: { tone, rules: [...rules.values()] }, scopes: scopes.map((s) => s.for), set_by };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Tokens: W3C design tokens (DTCG), CSS custom properties and head links.
+
+const cssName = (s) => String(s).toLowerCase().replace(/[^a-z0-9-]+/g, "-");
+const familyList = (t) => [JSON.stringify(t.family), ...(t.fallback ?? [])].join(", ");
+const FORMAT = { woff2: "woff2", woff: "woff", ttf: "truetype", otf: "opentype" };
+const url = (path) => `/${path.replace(/^public\//, "")}`;
+
+/** The marks as head links: the file-based icons Next.js turns into <link> tags. */
+export function headLinks(dir, brand) {
+  const reg = registerOf(dir);
+  const factsFor = (p) => reg?.assets?.find((a) => a.path === p)?.facts ?? (existsSync(join(dir, p)) ? factsOf(readFileSync(join(dir, p))) : null);
+  const out = [];
+  for (const m of brand.marks ?? []) {
+    if (m.kind === "logo") continue;
+    const f = factsFor(m.asset);
+    const sizes = m.kind === "favicon" ? "any" : f?.width ? `${f.width}x${f.height}` : undefined;
+    const type = { png: "image/png", svg: "image/svg+xml", ico: "image/x-icon" }[f?.type];
+    out.push(Object.fromEntries(Object.entries({ rel: m.kind === "apple-icon" ? "apple-touch-icon" : "icon", href: url(m.asset), type, sizes }).filter(([, v]) => v)));
+  }
+  return out;
+}
+
+/** DTCG tokens, CSS (custom properties, @font-face, one selector per scope) and head links. */
+export function tokens(dir, brand = brandOf(dir)) {
+  if (!brand) return null;
+  const at = resolveBrand(brand, "");
+  const dtcg = { color: {}, font: {} };
+  for (const [k, v] of Object.entries(at.colors)) dtcg.color[k] = { $type: "color", $value: v };
+  for (const [role, t] of Object.entries(at.fonts)) dtcg.font[role] = { $type: "fontFamily", $value: [t.family, ...(t.fallback ?? [])], $description: `${t.family}, ${t.license}` };
+  const faces = (brand.typefaces ?? []).filter((t) => t.source === "self-hosted").flatMap((t) => (t.files ?? []).map((f) => {
+    const ext = f.split(".").pop().toLowerCase();
+    return `@font-face {\n  font-family: ${JSON.stringify(t.family)};\n  src: url("${url(f)}") format("${FORMAT[ext] ?? ext}");\n  font-display: swap;\n}`;
+  }));
+  const decl = (colors, fonts) => [...Object.entries(colors).map(([k, v]) => `  --color-${cssName(k)}: ${v};`), ...Object.entries(fonts).map(([role, t]) => `  --font-${cssName(role)}: ${familyList(t)};`)].join("\n");
+  const blocks = [...faces, `:root {\n${decl(at.colors, at.fonts)}\n}`];
+  const faceById = new Map((brand.typefaces ?? []).map((t) => [t.id, t]));
+  for (const s of [...(brand.scopes ?? [])].sort((a, b) => depth(a.for) - depth(b.for))) {
+    const f = Object.fromEntries(Object.entries(s.fonts ?? {}).filter(([, id]) => faceById.has(id)).map(([role, id]) => [role, faceById.get(id)]));
+    const d = decl(s.colors ?? {}, f);
+    if (d) blocks.push(`[data-naive-scope="${s.for}"] {\n${d}\n}`);
+  }
+  return { name: brand.name ?? null, tokens: dtcg, css: blocks.join("\n\n") + "\n", head: headLinks(dir, brand), voice: brand.voice ?? null, design_systems: brand.design_systems ?? [] };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Glossaries (Y-2): a package's terms stay local unless it exports them.
+
+/** Every package glossary in the venture (glossary/<package>.json): package -> record. */
+export function glossaries(dir) {
+  const out = new Map();
+  const g = dir ? join(dir, "glossary") : null;
+  if (!g || !existsSync(g)) return out;
+  for (const f of readdirSync(g).filter((n) => n.endsWith(".json")).sort()) out.set(f.slice(0, -5), load(join(g, f)));
+  return out;
+}
+
+/** The terms a package sees: its own (all of them), then other packages' exported ones. Its own win. */
+export function termsFor(dir, pkg) {
+  const all = glossaries(dir);
+  const own = (all.get(pkg)?.terms ?? []).map((t) => ({ ...t, from: pkg }));
+  const names = new Set(own.map((t) => t.term.toLowerCase()));
+  const imported = [], shadows = [];
+  let hidden = 0;
+  for (const [p, g] of all) {
+    if (p === pkg) continue;
+    for (const t of g.terms ?? []) {
+      if (!t.export) { hidden++; continue; }
+      if (names.has(t.term.toLowerCase())) { shadows.push({ term: t.term, from: p, kept: pkg }); continue; }
+      imported.push({ ...t, from: p });
+    }
+  }
+  return { package: pkg, terms: [...own, ...imported], shadows, hidden };
+}
+
+function checkGlossaries(dir) {
+  const errors = [], warnings = [];
+  const exported = new Map();
+  for (const [p, g] of glossaries(dir)) {
+    if (g.package !== p) errors.push(`glossary/${p}.json: names package ${g.package}; the file for ${g.package} is glossary/${g.package}.json (Y-2)`);
+    const seen = new Set();
+    for (const t of g.terms ?? []) {
+      const k = t.term.toLowerCase();
+      if (seen.has(k)) errors.push(`glossary/${p}.json: ${t.term} is defined twice`);
+      seen.add(k);
+      if (!t.export) continue;
+      const prior = exported.get(k);
+      if (prior && prior.meaning !== t.meaning) errors.push(`${t.term}: exported by ${prior.from} and ${p} with different meanings; one of them keeps it local or they agree (Y-2)`);
+      else exported.set(k, { ...t, from: p });
+    }
+  }
+  return { errors, warnings };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Voice (Y-3): the global stylesheet for words.
+
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const phrase = (p) => new RegExp(`(^|[^\\p{L}\\p{N}])(${escape(p)})(?=$|[^\\p{L}\\p{N}])`, "giu");
+
+/** Text held to voice rules: every phrase to avoid, by line, with what to use instead. Frontmatter and code are skipped. */
+export function voiceCheck(text, rules) {
+  const out = [];
+  let fence = false, front = false;
+  text.split("\n").forEach((line, i) => {
+    if (i === 0 && line.trim() === "---") { front = true; return; }
+    if (front) { if (line.trim() === "---") front = false; return; }
+    if (/^\s*(```|~~~)/.test(line)) { fence = !fence; return; }
+    if (fence) return;
+    const plain = line.replace(/`[^`]*`/g, "");
+    for (const r of rules) for (const a of [].concat(r.avoid ?? [])) for (const m of plain.matchAll(phrase(a))) out.push({ rule: r.id, line: i + 1, found: m[2], use: r.use ?? null, why: r.why ?? null });
+  });
+  return out;
+}
+
+/** The venture's marketing content files, venture-relative. */
+export function contentFiles(dir) {
+  const walk = (d) => existsSync(d) ? readdirSync(d, { withFileTypes: true }).flatMap((e) => e.isDirectory() ? walk(join(d, e.name)) : /\.(mdx?|txt)$/.test(e.name) ? [join(d, e.name)] : []) : [];
+  return ["marketing/content", "operations/marketing/content"].flatMap((p) => walk(join(dir, p))).map((f) => f.slice(dir.length + 1)).sort();
+}
+
+/** Every marketing content file held to the voice rules in force at its path, and to other packages' local terms (warnings). */
+export function voice(dir, brand = brandOf(dir)) {
+  const violations = [], leaks = [];
+  const local = [...glossaries(dir)].filter(([p]) => p !== "marketing").flatMap(([p, g]) => (g.terms ?? []).filter((t) => !t.export).map((t) => ({ ...t, from: p })));
+  for (const f of contentFiles(dir)) {
+    const text = readFileSync(join(dir, f), "utf8");
+    const route = f.replace(/^operations\//, "").replace(/\.(mdx?|txt)$/, "");
+    if (brand) for (const v of voiceCheck(text, resolveBrand(brand, route).voice.rules)) violations.push({ file: f, ...v });
+    for (const t of local) for (const v of voiceCheck(text, [{ id: t.term, avoid: t.term }])) leaks.push({ file: f, line: v.line, term: t.term, local_to: t.from });
+  }
+  return { ok: !violations.length, files: contentFiles(dir).length, violations, local_terms: leaks };
+}
+
+// ---------------------------------------------------------------------------------------------
+// The brand check.
+
+const HEX = /^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+
+export function checkBrand(dir) {
+  const errors = [], warnings = [];
+  const brand = brandOf(dir);
+  const g = checkGlossaries(dir);
+  errors.push(...g.errors); warnings.push(...g.warnings);
+  if (!brand) return { ok: !errors.length, errors, warnings, brand: false };
+  const reg = registerOf(dir);
+  const asset = (p) => reg?.assets?.find((a) => a.path === p);
+  const faces = new Map((brand.typefaces ?? []).map((t) => [t.id, t]));
+  // Colors (Y-3).
+  const colorsOk = (cs, where) => { for (const [k, v] of Object.entries(cs ?? {})) if (!HEX.test(v)) errors.push(`${where}: color ${k} is ${v}, not a hex color`); };
+  colorsOk(brand.colors, BRAND);
+  // Typefaces (T-1): licensed, self-hosted from registered files, never fetched from another host by the browser.
+  for (const t of brand.typefaces ?? []) {
+    if (t.source !== "system" && !String(t.license ?? "").trim()) errors.push(`typeface ${t.id}: no license (T-1)`);
+    if (t.source === "remote") errors.push(`typeface ${t.id}: served from ${t.url ?? "another host"}, so every reader's browser makes an outside request; self-host its files in public/ (T-1)`);
+    if (t.source === "self-hosted") {
+      if (!(t.files ?? []).length) errors.push(`typeface ${t.id}: self-hosted but names no files in public/ (T-1)`);
+      for (const f of t.files ?? []) {
+        if (!f.startsWith("public/")) { errors.push(`typeface ${t.id}: ${f} is not in public/ (T-1)`); continue; }
+        if (!existsSync(join(dir, f))) { errors.push(`typeface ${t.id}: ${f} is not there (T-1)`); continue; }
+        const a = asset(f);
+        if (!a) errors.push(`typeface ${t.id}: ${f} has no entry in ${REGISTER} (T-1, J-2)`);
+        else if (String(a.license).toLowerCase() !== String(t.license).toLowerCase()) errors.push(`typeface ${t.id}: licensed ${t.license}, but ${REGISTER} says ${f} is ${a.license} (T-1)`);
+        const type = factsOf(readFileSync(join(dir, f))).type;
+        if (!["woff2", "woff", "ttf", "otf"].includes(type)) errors.push(`typeface ${t.id}: ${f} is ${type}, not a font file (T-1)`);
+      }
+    }
+  }
+  // Font roles, at the root and in scopes (T-2).
+  for (const [role, id] of Object.entries(brand.fonts ?? {})) if (!faces.has(id)) errors.push(`fonts.${role}: no typeface ${id} (T-2)`);
+  for (const s of brand.scopes ?? []) {
+    colorsOk(s.colors, `scope ${s.for}`);
+    for (const [role, id] of Object.entries(s.fonts ?? {})) if (!faces.has(id)) errors.push(`scope ${s.for}: fonts.${role} names no typeface ${id} (T-2)`);
+  }
+  const fors = (brand.scopes ?? []).map((s) => s.for);
+  for (const f of new Set(fors.filter((x, i) => fors.indexOf(x) !== i))) errors.push(`scope ${f} is declared twice; merge them (Y-5)`);
+  // Voice rules (Y-3).
+  const ids = (brand.voice?.rules ?? []).map((r) => r.id);
+  for (const id of new Set(ids.filter((x, i) => ids.indexOf(x) !== i))) errors.push(`voice rule ${id} is declared twice`);
+  // Marks (P-24): registered assets of the right type and size.
+  const KINDS = { favicon: ["ico"], icon: ["png", "svg", "ico"], "apple-icon": ["png"], logo: ["png", "svg", "jpeg", "webp"] };
+  for (const m of brand.marks ?? []) {
+    if (!existsSync(join(dir, m.asset))) { errors.push(`mark ${m.kind}: ${m.asset} is not there (P-24)`); continue; }
+    if (!asset(m.asset)) errors.push(`mark ${m.kind}: ${m.asset} has no entry in ${REGISTER}, so its source and license are unknown (P-24, J-2)`);
+    const f = factsOf(readFileSync(join(dir, m.asset)));
+    if (!KINDS[m.kind].includes(f.type)) errors.push(`mark ${m.kind}: ${m.asset} is ${f.type}; a ${m.kind} is ${KINDS[m.kind].join(" or ")} (P-24)`);
+    if (m.kind === "apple-icon" && f.type === "png" && (f.width !== 180 || f.height !== 180)) errors.push(`mark apple-icon: ${m.asset} is ${f.width}x${f.height}; an apple-icon is 180x180 (P-24)`);
+    if (m.kind === "icon" && f.width && f.width !== f.height) errors.push(`mark icon: ${m.asset} is ${f.width}x${f.height}; an icon is square (P-24)`);
+  }
+  const kinds = (brand.marks ?? []).map((m) => m.kind).filter((k) => k !== "icon");
+  for (const k of new Set(kinds.filter((x, i) => kinds.indexOf(x) !== i))) errors.push(`mark ${k} is declared twice (P-24)`);
+  // Design systems (Y-4): linked, not copied.
+  const systems = new Map((brand.design_systems ?? []).map((d) => [d.id, d]));
+  for (const d of brand.design_systems ?? []) if (!/^https?:\/\//.test(d.url ?? "")) errors.push(`design system ${d.id}: ${d.url ?? "no url"} is not a link; a design system is referenced, not copied (Y-4)`);
+  for (const a of reg?.assets ?? []) if (a.design_system) {
+    const d = systems.get(a.design_system);
+    if (!d) errors.push(`${a.path}: from design system ${a.design_system}, which the brand does not reference (Y-4)`);
+    else if (!allowsCopy(d.license)) errors.push(`${a.path}: a copy from design system ${d.id} (license ${d.license}); link to it at ${d.url} instead (Y-4)`);
+  }
+  // Content held to the voice.
+  const v = voice(dir, brand);
+  for (const x of v.violations) errors.push(`${x.file}:${x.line}: "${x.found}" breaks voice rule ${x.rule}${x.use ? `; use "${x.use}"` : ""} (Y-3)`);
+  for (const x of v.local_terms) warnings.push(`${x.file}:${x.line}: "${x.term}" is a term local to ${x.local_to}; export it from glossary/${x.local_to}.json or say it plainly (Y-2)`);
+  return { ok: !errors.length, errors, warnings, brand: true };
+}
+
+// ---------------------------------------------------------------------------------------------
+// The sitemap (P-26): rendered from the marketing record, for a release.
+
+const xmlEscape = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+
+export function sitemapOf(dir) {
+  const f = SITEMAPS.find((p) => existsSync(join(dir, p)));
+  return f ? { file: f, record: load(join(dir, f)) } : null;
+}
+
+/** sitemaps.org XML from a marketing sitemap record: one <url> per planned page, home first. */
+export function sitemapXml(record, base) {
+  let root;
+  try { root = new URL(base); } catch { throw new Error(`${base} is not a URL`); }
+  if (!/^https?:$/.test(root.protocol)) throw new Error(`${base} is not an http or https URL`);
+  const origin = base.replace(/\/+$/, "");
+  const lastmod = /^\d{4}-\d{2}-\d{2}/.test(record.planned_at ?? "") ? record.planned_at.slice(0, 10) : null;
+  const pages = [...record.pages].sort((a, b) => (a.level === "home" ? -1 : b.level === "home" ? 1 : 0));
+  const urls = pages.map((p) => {
+    const path = p.path.startsWith("/") ? p.path : `/${p.path}`;
+    return `  <url>\n    <loc>${xmlEscape(origin + (path === "/" ? "/" : path))}</loc>${lastmod ? `\n    <lastmod>${lastmod}</lastmod>` : ""}\n  </url>`;
+  });
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls.join("\n")}\n</urlset>\n`;
+}
+
+// ---------------------------------------------------------------------------------------------
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const argv = process.argv.slice(2);
+  const opt = (n) => { const i = argv.indexOf(`--${n}`); return i >= 0 ? argv[i + 1] : undefined; };
+  const json = argv.includes("--json");
+  const dir = argv[0];
+  const mode = argv[1] && !argv[1].startsWith("--") ? argv[1] : null;
+  if (!dir || !existsSync(join(dir, "venture.json"))) { console.error("usage: node schema/brand.mjs <venture dir> tokens|voice|check | --for <route> | --package <id> | --base <url> [--json]"); process.exit(2); }
+  const print = (x, text) => console.log(json ? JSON.stringify(x, null, 2) : text ?? JSON.stringify(x, null, 2));
+  if (opt("for") !== undefined) {
+    const brand = brandOf(dir);
+    if (!brand) { console.error(`no brand yet: write ${BRAND} (mentura marketing/brand template)`); process.exit(1); }
+    print(resolveBrand(brand, opt("for")));
+  } else if (opt("package") !== undefined) {
+    const t = termsFor(dir, opt("package"));
+    print(t, t.terms.map((x) => `${x.term.padEnd(24)} ${x.from.padEnd(12)} ${x.meaning}`).join("\n") || `no terms reach ${opt("package")}`);
+  } else if (opt("base") !== undefined) {
+    const s = sitemapOf(dir);
+    if (!s) { console.error("no marketing sitemap yet: plan it (mentura operations/marketing/sitemap run) and write marketing/sitemap.json"); process.exit(1); }
+    let xml;
+    try { xml = sitemapXml(s.record, opt("base")); } catch (e) { console.error(e.message); process.exit(1); }
+    print({ from: s.file, pages: s.record.pages.length, xml }, xml);
+  } else if (mode === "tokens") {
+    const t = tokens(dir);
+    if (!t) { console.error(`no brand yet: write ${BRAND}`); process.exit(1); }
+    print(t, t.css);
+  } else if (mode === "voice") {
+    const v = voice(dir);
+    print(v, v.violations.map((x) => `${x.file}:${x.line}  "${x.found}" (${x.rule})${x.use ? ` -> ${x.use}` : ""}`).join("\n") || `voice: ${v.files} files keep to the voice rules`);
+  } else {
+    const r = checkBrand(dir);
+    if (json) console.log(JSON.stringify(r, null, 2));
+    else {
+      for (const e of r.errors) console.log(`error  ${e}`);
+      for (const w of r.warnings) console.log(`warn   ${w}`);
+      console.log(r.ok ? `brand: ${r.brand ? "tokens, typefaces, marks, design systems and voice check out" : "no brand record yet; glossaries check out"}` : `brand: ${r.errors.length} errors`);
+    }
+    process.exit(r.ok ? 0 : 1);
+  }
+}