@graview/core 0.1.0 → 0.1.3

package/dist/document/compile.js

@@ -0,0 +1,807 @@
+import { RuleBudgetError, withArticle, brandFromAccent, checkApp, createSchema, defineInvariant, defineMutation, defineNode, nodeRef, SCHEMES, } from "../index.js";
+import { z } from "zod";
+import { analyzeExpr } from "./expr/analyze.js";
+import { rememberDocument } from "./to-document.js";
+import { evaluateExpr, ExprBudgetError, ExprEvalError } from "./expr/evaluate.js";
+import { ExprSyntaxError, parseExpr } from "./expr/parse.js";
+import { error, hasErrors, warning } from "./findings.js";
+import { DocumentSpec, MAX_DOCUMENT_BYTES, } from "./schema.js";
+import { parseTemplate, renderTemplate, TemplateError } from "./template.js";
+import { upgradeDocument } from "./upgrade.js";
+import { validateViews } from "./views.js";
+const BUILTIN_REFS = new Set(["subject", "now", "today"]);
+const SUBJECT_ARG = "id";
+/** Parse and validate without compiling — the document's own sentences, before the framework's. */
+export function readDocument(raw) {
+    if (typeof raw === "string") {
+        if (raw.length > MAX_DOCUMENT_BYTES)
+            return { findings: [error("too-large", "", `a document may be at most ${MAX_DOCUMENT_BYTES / 1024} KB`)] };
+        try {
+            raw = JSON.parse(raw);
+        }
+        catch (e) {
+            return { findings: [error("not-json", "", `this is not JSON: ${e.message}`)] };
+        }
+    }
+    else if (JSON.stringify(raw ?? null).length > MAX_DOCUMENT_BYTES) {
+        return { findings: [error("too-large", "", `a document may be at most ${MAX_DOCUMENT_BYTES / 1024} KB`)] };
+    }
+    // An older format is upgraded before it is read (upgrade.ts); the host records that as a new version.
+    try {
+        raw = upgradeDocument(raw).document;
+    }
+    catch (e) {
+        return { findings: [error("format", "formatVersion", e.message)] };
+    }
+    const parsed = DocumentSpec.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            findings: parsed.error.issues.map((issue) => {
+                const path = issue.path.map(String).join(".");
+                if (issue.code === "unrecognized_keys")
+                    return error("unknown-key", path, `${issue.keys.map((k) => `"${k}"`).join(", ")} ${issue.keys.length === 1 ? "is" : "are"} not part of a Graview document here`, "check the spelling against docs/declaration-document.md");
+                if (issue.code === "invalid_union" && /\.effects\.\d+$/.test(path)) {
+                    return error("effect-shape", path, "this effect is not one Graview knows", 'an effect is one of {"create": kind, "as"?: name, "set"?: {field: value}}, {"set": {field: value, …}, "target"?: "$ref"}, {"connect"|"sever": relation, "from": "$ref", "to": "$ref"}, {"remove": "$ref"}');
+                }
+                if (issue.code === "invalid_key") {
+                    const inner = issue.issues?.[0]?.message;
+                    return error("shape", path, `the name "${String(issue.path.at(-1))}" is not allowed here${inner ? `: ${inner}` : ""}`);
+                }
+                return error("shape", path, issue.message);
+            }),
+        };
+    }
+    const document = parsed.data;
+    return { document, findings: validate(document) };
+}
+const asArray = (v) => (v === undefined ? [] : Array.isArray(v) ? v : [v]);
+function edgeIndex(document) {
+    const edges = new Map();
+    for (const [kind, spec] of Object.entries(document.kinds)) {
+        for (const [name, edge] of Object.entries(spec.edges ?? {})) {
+            const prior = edges.get(name);
+            edges.set(name, {
+                name,
+                from: [...(prior?.from ?? []), kind],
+                to: edge.to === "*" || prior?.to === "*" ? "*" : [...new Set([...(prior?.to ?? []), ...edge.to])],
+                cardinality: edge.cardinality ?? "many",
+            });
+        }
+    }
+    return edges;
+}
+export function kindShapes(document) {
+    const shapes = new Map();
+    for (const [kind, spec] of Object.entries(document.kinds)) {
+        shapes.set(kind, {
+            fields: new Set(Object.keys(spec.fields)),
+            edges: new Map(Object.entries(spec.edges ?? {}).map(([name, e]) => [name, e.cardinality ?? "many"])),
+        });
+    }
+    return shapes;
+}
+/** The effects an act's shorthands mean, in order. */
+export function effectsOf(act, document) {
+    // Shorthands first, then any listed effects: an act may say "writes quote" and also set a status.
+    const effects = [];
+    if (act.creates) {
+        const kind = document.kinds[act.creates];
+        const set = {};
+        for (const field of Object.keys(kind?.fields ?? {}))
+            set[field] = `$${field}`;
+        // Fields a later effect fills in on the new record are part of making it, not questions to ask.
+        for (const e of act.effects ?? [])
+            if ("set" in e && !("create" in e) && refName(e.target) === "new")
+                Object.assign(set, e.set);
+        effects.push({ create: act.creates, as: "new", set });
+    }
+    if (act.sets)
+        effects.push({ set: act.sets });
+    // An act that makes a record already asks for each of its fields: `writes` beside `creates` (and no `on`) names some of them again, not a subject.
+    if (act.writes && !(act.creates && act.on === undefined))
+        effects.push({ set: Object.fromEntries(act.writes.map((f) => [f, `$${f}`])) });
+    if (act.connects)
+        effects.push({ connect: act.connects, from: "$subject", to: "$to" });
+    if (act.severs)
+        effects.push({ sever: act.severs, from: "$subject", to: "$to" });
+    if (act.removes)
+        effects.push({ remove: "$subject" });
+    if (act.effects)
+        effects.push(...act.effects.filter((e) => !(act.creates && "set" in e && !("create" in e) && refName(e.target) === "new")));
+    return effects;
+}
+const refName = (v) => (typeof v === "string" && /^\$[A-Za-z][A-Za-z0-9]*$/.test(v) ? v.slice(1) : undefined);
+function tryExpr(source, path, findings) {
+    try {
+        const expr = parseExpr(source);
+        const shape = analyzeExpr(expr);
+        for (const fn of shape.unknownFunctions)
+            findings.push(error("unknown-function", path, `"${fn}" is not a function the rule language knows`, "see docs/declaration-document.md#expression-language"));
+        return expr;
+    }
+    catch (e) {
+        if (e instanceof ExprSyntaxError) {
+            findings.push(error("expression", path, e.sentence + ` (at character ${e.at + 1})`));
+            return undefined;
+        }
+        throw e;
+    }
+}
+function tryTemplate(source, path, findings) {
+    try {
+        return parseTemplate(source);
+    }
+    catch (e) {
+        if (e instanceof TemplateError || e instanceof ExprSyntaxError) {
+            findings.push(error("template", path, e instanceof ExprSyntaxError ? e.sentence : e.sentence));
+            return undefined;
+        }
+        throw e;
+    }
+}
+/** The document's own sentences: references that do not resolve, expressions that do not parse. */
+function validate(document) {
+    const findings = [];
+    const kinds = new Set(Object.keys(document.kinds));
+    const edges = edgeIndex(document);
+    const acts = document.acts ?? {};
+    const roles = new Set(document.roles ?? []);
+    for (const [kind, spec] of Object.entries(document.kinds)) {
+        const at = `kinds.${kind}`;
+        for (const [name, edge] of Object.entries(spec.edges ?? {})) {
+            if (edge.to !== "*")
+                for (const target of edge.to)
+                    if (!kinds.has(target))
+                        findings.push(error("edge-target", `${at}.edges.${name}.to`, `"${target}" is not a kind this document declares`));
+            if (spec.fields[name])
+                findings.push(error("edge-field-clash", `${at}.edges.${name}`, `"${name}" is both a field and a relation of ${kind}`, "rename one of them"));
+        }
+        if (spec.lifecycle && !spec.fields[spec.lifecycle.field])
+            findings.push(error("lifecycle-field", `${at}.lifecycle.field`, `${kind} has no field "${spec.lifecycle.field}"`));
+        for (const field of spec.glance ?? []) {
+            if (!spec.fields[field])
+                findings.push(error("glance-field", `${at}.glance`, `a glance at ${kind} is to say "${field}", and ${kind} has no field called that`, `use one of: ${Object.keys(spec.fields).join(", ")}`));
+        }
+        for (const key of ["label", "describe"]) {
+            const source = spec[key];
+            if (!source)
+                continue;
+            const parts = tryTemplate(source, `${at}.${key}`, findings);
+            for (const part of parts ?? []) {
+                if (!part.expr)
+                    continue;
+                for (const name of analyzeExpr(part.expr).names) {
+                    if (!spec.fields[name])
+                        findings.push(error("template-field", `${at}.${key}`, `${kind} has no field "${name}" for its ${key} to show`, key === "label" ? "a label can only show the record's own fields" : undefined));
+                }
+            }
+        }
+        for (const [field, f] of Object.entries(spec.fields)) {
+            if (f.default !== undefined && f.type === "enum" && !f.options?.includes(String(f.default))) {
+                findings.push(error("default-option", `${at}.fields.${field}.default`, `"${String(f.default)}" is not one of ${field}'s options`));
+            }
+        }
+    }
+    for (const [name, act] of Object.entries(acts)) {
+        const at = `acts.${name}`;
+        for (const kind of asArray(act.on))
+            if (!kinds.has(kind))
+                findings.push(error("act-kind", `${at}.on`, `"${kind}" is not a kind this document declares`));
+        const subjectKinds = asArray(act.on);
+        const effects = effectsOf(act, document);
+        if (act.creates && act.on === undefined && act.writes && kinds.has(act.creates)) {
+            for (const field of act.writes)
+                if (!document.kinds[act.creates].fields[field])
+                    findings.push(error("act-field", `${at}.writes`, `${act.creates} has no field "${field}"`));
+        }
+        if (effects.length === 0)
+            findings.push(error("act-empty", at, `"${name}" does nothing`, "give it effects or a shorthand such as sets or creates"));
+        const created = new Map();
+        effects.forEach((effect, i) => {
+            const shorthands = effects.length - (act.effects?.length ?? 0);
+            const where = act.effects && i >= shorthands ? `${at}.effects.${i - shorthands}` : at;
+            if ("create" in effect) {
+                if (!kinds.has(effect.create))
+                    findings.push(error("act-kind", `${where}.create`, `"${effect.create}" is not a kind this document declares`));
+                else
+                    for (const field of Object.keys(effect.set ?? {}))
+                        if (!document.kinds[effect.create].fields[field])
+                            findings.push(error("act-field", `${where}.set.${field}`, `${effect.create} has no field "${field}"`));
+                if (effect.as)
+                    created.set(effect.as, effect.create);
+            }
+            else if ("connect" in effect || "sever" in effect) {
+                const edgeName = "connect" in effect ? effect.connect : effect.sever;
+                if (!edges.has(edgeName))
+                    findings.push(error("act-edge", `${where}.${"connect" in effect ? "connect" : "sever"}`, `"${edgeName}" is not a relation any kind declares`));
+                if (refName(effect.from) === "subject" && subjectKinds.length === 0)
+                    findings.push(error("act-subject", `${at}.on`, `"${name}" acts on "$subject" but does not say which kinds it is "on"`));
+            }
+            else if ("set" in effect) {
+                const target = refName(effect.target ?? "$subject");
+                const targetKinds = target === "subject" ? subjectKinds : created.has(target ?? "") ? [created.get(target)] : [];
+                if (target === "subject" && subjectKinds.length === 0)
+                    findings.push(error("act-subject", `${at}.on`, `"${name}" changes "$subject" but does not say which kinds it is "on"`));
+                for (const field of Object.keys(effect.set)) {
+                    for (const kind of targetKinds)
+                        if (kinds.has(kind) && !document.kinds[kind].fields[field])
+                            findings.push(error("act-field", `${where}.set.${field}`, `${kind} has no field "${field}"`));
+                }
+            }
+            else if ("remove" in effect) {
+                if (refName(effect.remove) === "subject" && subjectKinds.length === 0)
+                    findings.push(error("act-subject", `${at}.on`, `"${name}" removes "$subject" but does not say which kinds it is "on"`));
+            }
+            const values = "set" in effect && effect.set ? Object.values(effect.set) : [];
+            values.forEach((v) => {
+                if (v && typeof v === "object" && !Array.isArray(v) && "expr" in v)
+                    tryExpr(v.expr, `${where}.set`, findings);
+            });
+        });
+        if (act.allowedWhen)
+            tryExpr(act.allowedWhen, `${at}.allowedWhen`, findings);
+        if (act.refusal)
+            tryTemplate(act.refusal, `${at}.refusal`, findings);
+    }
+    for (const [name, rule] of Object.entries(document.rules ?? {})) {
+        const at = `rules.${name}`;
+        if (rule.over !== "graph" && !kinds.has(rule.over))
+            findings.push(error("rule-kind", `${at}.over`, `"${rule.over}" is not a kind this document declares`));
+        const spec = rule.over === "graph" ? undefined : document.kinds[rule.over];
+        for (const key of ["when", "require"]) {
+            const source = rule[key];
+            if (!source)
+                continue;
+            const expr = tryExpr(source, `${at}.${key}`, findings);
+            if (!expr)
+                continue;
+            const shape = analyzeExpr(expr);
+            for (const n of shape.names) {
+                if (rule.over === "graph")
+                    findings.push(error("rule-name", `${at}.${key}`, `"${n}" means nothing in a rule over the whole graph`, "name a kind in \"over\", or use all('kind')"));
+                else if (spec && !spec.fields[n] && !spec.edges?.[n]) {
+                    const hyphenated = Object.keys(spec.edges ?? {}).find((e) => e.includes("-") && e.split("-").includes(n));
+                    findings.push(error("rule-name", `${at}.${key}`, `${rule.over} has no field or relation called "${n}"`, hyphenated ? `"${hyphenated}" reads as a subtraction in a rule; rename the relation to one camelCase word, like "${hyphenated.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase())}"` : undefined));
+                }
+            }
+            for (const e of shape.edges)
+                if (!edges.has(e))
+                    findings.push(error("rule-edge", `${at}.${key}`, `"${e}" is not a relation any kind declares`));
+            for (const k of shape.sweeps) {
+                if (!kinds.has(k))
+                    findings.push(error("rule-kind", `${at}.${key}`, `"${k}" is not a kind this document declares`));
+                else if (rule.over !== "graph")
+                    findings.push(warning("rule-cost", `${at}.${key}`, `this rule looks at every ${k} for every ${rule.over}, which grows slowly as the app grows`, "walk a relation with out()/in() instead of all() where you can"));
+            }
+        }
+        if (rule.says)
+            tryTemplate(rule.says, `${at}.says`, findings);
+        (rule.repairs ?? []).forEach((repair, i) => {
+            if (!acts[repair.act] && !/^(edit|remove)-/.test(repair.act))
+                findings.push(error("repair-act", `${at}.repairs.${i}.act`, `"${repair.act}" is not an act this document declares`));
+        });
+    }
+    const policy = document.policy;
+    if (policy) {
+        policy.grants.forEach((grant, i) => {
+            if (grant.roles !== "*" && roles.size > 0)
+                for (const r of grant.roles)
+                    if (!roles.has(r))
+                        findings.push(error("grant-role", `policy.grants.${i}.roles`, `"${r}" is not one of the document's roles`));
+            if (grant.mutations !== "*")
+                for (const m of grant.mutations)
+                    if (!acts[m] && !/^(edit|remove)-/.test(m))
+                        findings.push(error("grant-act", `policy.grants.${i}.mutations`, `"${m}" is not an act this document declares`));
+        });
+        (policy.sees ?? []).forEach((sight, i) => {
+            for (const k of sight.kinds)
+                if (!kinds.has(k))
+                    findings.push(error("sight-kind", `policy.sees.${i}.kinds`, `"${k}" is not a kind this document declares`));
+            if (sight.roles !== "*" && roles.size > 0)
+                for (const r of sight.roles)
+                    if (!roles.has(r))
+                        findings.push(error("sight-role", `policy.sees.${i}.roles`, `"${r}" is not one of the document's roles`));
+        });
+    }
+    findings.push(...validateViews(document));
+    return findings;
+}
+function fieldSchema(spec, optional) {
+    let schema;
+    switch (spec.type) {
+        case "string":
+            schema = z.string().max(500);
+            break;
+        case "text":
+            schema = z.string().max(20_000);
+            break;
+        case "number":
+            schema = z.number();
+            break;
+        case "integer":
+            schema = z.number().int();
+            break;
+        case "boolean":
+            schema = z.boolean();
+            break;
+        case "date":
+            schema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "a date like 2026-10-02");
+            break;
+        case "datetime":
+            schema = z.string().refine((s) => !Number.isNaN(Date.parse(s)), "a date and time like 2026-10-02T14:30:00Z");
+            break;
+        case "enum":
+            schema = z.enum(spec.options);
+            break;
+        case "list":
+            schema = z.array(spec.of === "number" ? z.number() : spec.of === "date" ? z.string().regex(/^\d{4}-\d{2}-\d{2}$/) : z.string().max(500)).max(200);
+            break;
+        case "url":
+            schema = z.url();
+            break;
+        case "email":
+            schema = z.email();
+            break;
+    }
+    if (spec.description)
+        schema = schema.describe(spec.description);
+    return optional ? schema.optional() : schema;
+}
+/** What one of these is called, when the kind says nothing: the first required word-ish field. */
+function defaultLabelField(spec) {
+    const entries = Object.entries(spec.fields);
+    return (entries.find(([, f]) => f.required && (f.type === "string" || f.type === "text"))?.[0] ??
+        entries.find(([, f]) => f.type === "string")?.[0]);
+}
+/** The arguments an act asks for: declared ones, then whatever its effects reference. */
+function argsOf(name, act, effects, document, edges) {
+    const args = new Map();
+    const subjectKinds = asArray(act.on);
+    const created = new Map();
+    const usesSubject = subjectKinds.length > 0 ||
+        effects.some((e) => ("remove" in e && refName(e.remove) === "subject") || ("from" in e && (refName(e.from) === "subject" || refName(e.to) === "subject")) || ("set" in e && !("create" in e) && refName(e.target ?? "$subject") === "subject"));
+    if (usesSubject)
+        args.set(SUBJECT_ARG, { schema: nodeRef(subjectKinds.length > 0 ? subjectKinds : "*"), required: true });
+    const declared = act.args ?? {};
+    const writesOnlyOne = act.writes?.length === 1;
+    const note = (arg, schema) => {
+        if (arg === SUBJECT_ARG || BUILTIN_REFS.has(arg) || created.has(arg) || args.has(arg))
+            return;
+        const d = declared[arg];
+        args.set(arg, d ? { schema: fieldSchema(d, !d.required), required: Boolean(d.required) } : schema());
+    };
+    for (const effect of effects) {
+        if ("create" in effect) {
+            const kind = document.kinds[effect.create];
+            for (const [field, value] of Object.entries(effect.set ?? {})) {
+                const arg = refName(value);
+                const spec = kind?.fields[field];
+                if (arg && spec) {
+                    const required = Boolean(spec.required) && spec.default === undefined;
+                    note(arg, () => ({ schema: fieldSchema(spec, !required), required }));
+                }
+            }
+            if (effect.as)
+                created.set(effect.as, effect.create);
+        }
+        else if ("connect" in effect || "sever" in effect) {
+            const edge = edges.get("connect" in effect ? effect.connect : effect.sever);
+            for (const [end, value] of [["from", effect.from], ["to", effect.to]]) {
+                const arg = refName(value);
+                if (!arg)
+                    continue;
+                const kinds = end === "to" ? edge?.to ?? "*" : edge?.from ?? "*";
+                note(arg, () => ({ schema: nodeRef(kinds === "*" ? "*" : kinds), required: true }));
+            }
+        }
+        else if ("set" in effect) {
+            const target = refName(effect.target ?? "$subject");
+            const targetKind = target === "subject" ? subjectKinds[0] : created.get(target ?? "");
+            if (target && target !== "subject" && !created.has(target))
+                note(target, () => ({ schema: nodeRef("*"), required: true }));
+            for (const [field, value] of Object.entries(effect.set)) {
+                const arg = refName(value);
+                if (!arg)
+                    continue;
+                const spec = targetKind ? document.kinds[targetKind]?.fields[field] : undefined;
+                note(arg, () => (spec ? { schema: fieldSchema(spec, !writesOnlyOne), required: writesOnlyOne } : { schema: z.unknown().optional(), required: false }));
+            }
+        }
+        else if ("remove" in effect) {
+            const arg = refName(effect.remove);
+            if (arg)
+                note(arg, () => ({ schema: nodeRef("*"), required: true }));
+        }
+    }
+    for (const [arg, d] of Object.entries(declared))
+        if (!args.has(arg))
+            args.set(arg, { schema: fieldSchema(d, !d.required), required: Boolean(d.required) });
+    void name;
+    return args;
+}
+class Refused extends Error {
+}
+export function compileDocument(raw, options = {}) {
+    const read = readDocument(raw);
+    if (!read.document || hasErrors(read.findings))
+        return { ok: false, findings: read.findings };
+    const document = read.document;
+    const findings = [...read.findings];
+    if (options.previous)
+        findings.push(...renamesFromNothing(document, options.previous));
+    const today = options.today ?? (() => new Date().toISOString().slice(0, 10));
+    const shapes = kindShapes(document);
+    const edges = edgeIndex(document);
+    // ── kinds ────────────────────────────────────────────────────────────────
+    const definitions = Object.entries(document.kinds).map(([kind, spec]) => {
+        const shape = {};
+        for (const [field, f] of Object.entries(spec.fields))
+            shape[field] = fieldSchema(f, !f.required);
+        const labelSource = spec.label ?? (defaultLabelField(spec) ? `{${defaultLabelField(spec)}}` : undefined);
+        const labelParts = labelSource ? parseTemplate(labelSource) : undefined;
+        const describeParts = spec.describe ? parseTemplate(spec.describe) : undefined;
+        const labels = Object.fromEntries(Object.entries(spec.fields).filter(([, f]) => f.label).map(([n, f]) => [n, f.label]));
+        // Defaults stay out of the zod schema (hydration must not invent values) and ride beside it, for a repair to read.
+        const defaults = Object.fromEntries(Object.entries(spec.fields).filter(([, f]) => f.default !== undefined).map(([n, f]) => [n, f.default]));
+        const edgeDecls = Object.fromEntries(Object.entries(spec.edges ?? {}).map(([n, e]) => [
+            n,
+            {
+                to: e.to,
+                ...(e.cardinality ? { cardinality: e.cardinality } : {}),
+                ...(e.description ? { description: e.description } : {}),
+                ...(e.inverse ? { inverse: e.inverse } : {}),
+                ...(e.appendOnly ? { appendOnly: e.appendOnly } : {}),
+            },
+        ]));
+        return defineNode(kind, {
+            fields: z.object(shape),
+            edges: edgeDecls,
+            ...(spec.plural ? { plural: spec.plural } : {}),
+            ...(spec.noun ? { noun: spec.noun } : {}),
+            ...(spec.description ? { description: spec.description } : {}),
+            ...(labelParts ? { label: (node) => renderTemplate(labelParts, { node: node, kinds: shapes, today: today() }) || node.id } : {}),
+            ...(describeParts ? { describe: (node) => renderTemplate(describeParts, { node: node, kinds: shapes, today: today() }) } : {}),
+            ...(spec.lifecycle ? { lifecycle: { field: spec.lifecycle.field, retired: spec.lifecycle.retired } } : {}),
+            ...(spec.figure ? { figure: spec.figure } : {}),
+            ...(Object.keys(labels).length > 0 || spec.glance ? { display: { ...(Object.keys(labels).length > 0 ? { labels } : {}), ...(spec.glance ? { glance: [...spec.glance] } : {}) } } : {}),
+            ...(Object.keys(defaults).length > 0 ? { defaults } : {}),
+        });
+    });
+    const schema = createSchema(definitions);
+    // ── acts ─────────────────────────────────────────────────────────────────
+    const mutations = [];
+    for (const [name, act] of Object.entries(document.acts ?? {})) {
+        const effects = effectsOf(act, document);
+        const args = argsOf(name, act, effects, document, edges);
+        const shape = {};
+        for (const [arg, a] of args)
+            shape[arg] = a.schema;
+        const subjectKinds = asArray(act.on);
+        const title = act.title ?? name.replace(/-/g, " ");
+        const guard = act.allowedWhen ? parseExpr(act.allowedWhen) : undefined;
+        const refusal = act.refusal ? parseTemplate(act.refusal) : undefined;
+        const destructive = act.destructive ?? effects.some((e) => "remove" in e || "sever" in e);
+        const creates = [...new Set(effects.flatMap((e) => ("create" in e ? [e.create] : [])))];
+        const connects = [...new Set(effects.flatMap((e) => ("connect" in e ? [e.connect] : [])))];
+        const severs = [...new Set(effects.flatMap((e) => ("sever" in e ? [e.sever] : [])))];
+        // An act WRITES only what it sets on its subject; setting fields on a record it just made is part of making it.
+        const writes = [...new Set(effects.flatMap((e) => ("set" in e && !("create" in e) && (refName(e.target ?? "$subject") === "subject") ? Object.keys(e.set) : [])))];
+        /*
+         * Twice is once when nothing is made and every value set is given
+         * (a literal or an argument), never computed from what is there.
+         */
+        const idempotent = creates.length === 0 &&
+            effects.every((e) => !("set" in e) || !e.set || Object.values(e.set).every((v) => !(v && typeof v === "object" && !Array.isArray(v) && "expr" in v)));
+        const exprs = new Map();
+        for (const effect of effects) {
+            if (!("set" in effect) || !effect.set)
+                continue;
+            for (const v of Object.values(effect.set))
+                if (v && typeof v === "object" && !Array.isArray(v) && "expr" in v)
+                    exprs.set(v.expr, parseExpr(v.expr));
+        }
+        mutations.push(defineMutation(name, {
+            input: z.object(shape),
+            title,
+            ...(act.description ? { description: act.description } : {}),
+            ...(act.fromTheOtherEnd ? { fromTheOtherEnd: act.fromTheOtherEnd } : {}),
+            ...(args.has(SUBJECT_ARG) ? { subject: { kinds: subjectKinds.length > 0 ? subjectKinds : "*", arg: SUBJECT_ARG } } : {}),
+            ...(destructive ? { destructive: true } : {}),
+            ...(idempotent ? { idempotent: true } : {}),
+            ...(creates.length > 0 ? { creates } : {}),
+            ...(connects.length > 0 ? { connects } : {}),
+            ...(severs.length > 0 ? { severs } : {}),
+            ...(writes.length > 0 ? { writes } : {}),
+            describe: (input, graph) => {
+                const subject = typeof input[SUBJECT_ARG] === "string" ? graph.getNode(input[SUBJECT_ARG]) : undefined;
+                const what = subject ? labelFor(subject) : Object.values(input).find((v) => typeof v === "string");
+                return what ? `${title}: ${String(what)}` : title;
+            },
+            apply(context, input) {
+                const graph = context.graph;
+                const subjectId = typeof input[SUBJECT_ARG] === "string" ? input[SUBJECT_ARG] : undefined;
+                const subject = subjectId ? graph.getNode(subjectId) : undefined;
+                if (subjectId && !subject)
+                    throw new Refused(`there is no record "${subjectId}"`);
+                if (subject && subjectKinds.length > 0 && !subjectKinds.includes(subject.kind))
+                    throw new Refused(`"${title}" acts on ${subjectKinds.join(" or ")}, not on ${withArticle(subject.kind)}`);
+                const bindings = {};
+                for (const [k, v] of Object.entries(input))
+                    if (v !== undefined)
+                        bindings[k] = v;
+                if (guard && subject) {
+                    let allowed;
+                    try {
+                        allowed = evaluateExpr(guard, { graph, subject, kinds: shapes, bindings, today: today() });
+                    }
+                    catch (e) {
+                        if (e instanceof ExprEvalError)
+                            throw new Refused(`"${title}" could not be judged: ${e.sentence}`);
+                        throw e;
+                    }
+                    if (allowed !== true) {
+                        throw new Refused(refusal ? renderTemplate(refusal, { node: subject, kinds: shapes, graph, bindings, today: today() }) : `"${title}" is not allowed for ${labelFor(subject)} right now`);
+                    }
+                }
+                const made = new Map();
+                const resolve = (value, current) => {
+                    if (value && typeof value === "object" && !Array.isArray(value) && "expr" in value) {
+                        try {
+                            return evaluateExpr(exprs.get(value.expr), { graph, subject: current ?? subject ?? null, kinds: shapes, bindings, today: today() });
+                        }
+                        catch (e) {
+                            if (e instanceof ExprEvalError)
+                                throw new Refused(`"${title}" could not work out a value: ${e.sentence}`);
+                            throw e;
+                        }
+                    }
+                    const ref = refName(value);
+                    if (ref === undefined)
+                        return typeof value === "string" && value.startsWith("$$") ? value.slice(1) : value;
+                    if (ref === "subject")
+                        return subjectId;
+                    if (ref === "now")
+                        return new Date().toISOString();
+                    if (ref === "today")
+                        return today();
+                    if (made.has(ref))
+                        return made.get(ref);
+                    return input[ref];
+                };
+                for (const effect of effects) {
+                    if ("create" in effect) {
+                        const kind = document.kinds[effect.create];
+                        const node = { kind: effect.create };
+                        for (const [field, f] of Object.entries(kind.fields))
+                            if (f.default !== undefined)
+                                node[field] = f.default;
+                        for (const [field, value] of Object.entries(effect.set ?? {})) {
+                            const v = resolve(value, undefined);
+                            if (v !== undefined)
+                                node[field] = v;
+                        }
+                        const labelField = defaultLabelField(kind);
+                        const id = context.freshId(String((labelField && node[labelField]) ?? effect.create), effect.create);
+                        context.addNode({ id, ...node });
+                        if (effect.as)
+                            made.set(effect.as, id);
+                    }
+                    else if ("connect" in effect || "sever" in effect) {
+                        const kind = "connect" in effect ? effect.connect : effect.sever;
+                        const from = String(resolve(effect.from, undefined) ?? "");
+                        const to = String(resolve(effect.to, undefined) ?? "");
+                        if (!graph.has(from) && ![...made.values()].includes(from))
+                            throw new Refused(`there is no record "${from}"`);
+                        if (!graph.has(to) && ![...made.values()].includes(to))
+                            throw new Refused(`there is no record "${to}"`);
+                        if ("connect" in effect) {
+                            if (edges.get(kind)?.cardinality === "one")
+                                for (const existing of graph.out(from, kind))
+                                    if (existing.id !== to)
+                                        context.removeEdge({ kind, from, to: existing.id });
+                            if (!graph.out(from, kind).some((n) => n.id === to))
+                                context.addEdge({ kind, from, to });
+                        }
+                        else {
+                            context.removeEdge({ kind, from, to });
+                        }
+                    }
+                    else if ("set" in effect) {
+                        const targetId = String(resolve(effect.target ?? "$subject", undefined) ?? "");
+                        const target = graph.getNode(targetId);
+                        if (!target && ![...made.values()].includes(targetId))
+                            throw new Refused(`there is no record "${targetId}"`);
+                        const patch = {};
+                        for (const [field, value] of Object.entries(effect.set)) {
+                            const v = resolve(value, target);
+                            if (v !== undefined)
+                                patch[field] = v;
+                        }
+                        if (Object.keys(patch).length > 0)
+                            context.patchNode(targetId, patch);
+                    }
+                    else if ("remove" in effect) {
+                        const id = String(resolve(effect.remove, undefined) ?? "");
+                        if (!graph.has(id))
+                            throw new Refused(`there is no record "${id}"`);
+                        context.removeNode(id);
+                    }
+                }
+            },
+        }));
+    }
+    function labelFor(node) {
+        const definition = schema.tryDefinition(node.kind);
+        return definition?.label?.(node) ?? node.id;
+    }
+    // ── rules ────────────────────────────────────────────────────────────────
+    const invariants = [];
+    for (const [name, rule] of Object.entries(document.rules ?? {})) {
+        const require = parseExpr(rule.require);
+        const when = rule.when ? parseExpr(rule.when) : undefined;
+        const says = rule.says ? parseTemplate(rule.says) : undefined;
+        const title = rule.title ?? name.replace(/-/g, " ");
+        const repairs = rule.repairs ?? [];
+        const judge = (graph, subject) => {
+            const ctx = { graph, subject, kinds: shapes, today: today() };
+            let holds;
+            /*
+             * A RULE THAT CANNOT ANSWER IS THE ENGINE'S TO SAY (FR-29). Out of
+             * budget it throws RuleBudgetError, and the violation's status is
+             * `over-budget`; any other mistake (a word added to a number) is
+             * `could-not-judge`. Both name the rule and its subject, and neither
+             * is a hang or a crash that takes the other rules down.
+             */
+            try {
+                if (when && evaluateExpr(when, ctx) !== true)
+                    return [];
+                holds = evaluateExpr(require, ctx) === true;
+            }
+            catch (e) {
+                if (e instanceof ExprBudgetError)
+                    throw new RuleBudgetError(e.sentence);
+                if (e instanceof ExprEvalError)
+                    throw new Error(e.sentence);
+                throw e;
+            }
+            if (holds)
+                return [];
+            const repairList = repairs.flatMap((r) => {
+                const act = document.acts?.[r.act];
+                const args = {};
+                if (subject && (act?.on || /^(edit|remove)-/.test(r.act)))
+                    args[SUBJECT_ARG] = subject.id;
+                for (const [k, v] of Object.entries(r.args ?? {}))
+                    args[k] = refName(v) === "subject" ? subject?.id : v;
+                const declared = act ? argsOf(r.act, act, effectsOf(act, document), document, edges) : new Map();
+                const missing = [...declared].filter(([k, a]) => a.required && args[k] === undefined).map(([k]) => k);
+                return [{ mutation: r.act, label: r.label ?? act?.title ?? r.act.replace(/-/g, " "), args, ...(missing.length > 0 ? { missing } : {}) }];
+            });
+            return [
+                {
+                    invariant: name,
+                    ...(subject ? { subjectId: subject.id } : {}),
+                    label: title,
+                    message: (says ? renderTemplate(says, { node: subject, kinds: shapes, graph, today: today() }) : subject ? `${labelFor(subject)}: ${title}` : title),
+                    nodeIds: subject ? [subject.id] : [],
+                    repairs: repairList,
+                },
+            ];
+        };
+        invariants.push((rule.over === "graph"
+            ? defineInvariant(name, {
+                scope: "graph",
+                label: title,
+                judgement: { require: rule.require, ...(rule.when ? { when: rule.when } : {}), ...(rule.says ? { says: rule.says } : {}) },
+                ...(rule.description ? { description: rule.description } : {}),
+                ...(repairs.length > 0 ? { repairs: repairs.map((r) => r.act) } : {}),
+                evaluate: ({ graph }) => judge(graph, null),
+            })
+            : defineInvariant(name, {
+                scope: { kind: rule.over },
+                label: title,
+                judgement: { require: rule.require, ...(rule.when ? { when: rule.when } : {}), ...(rule.says ? { says: rule.says } : {}) },
+                ...(rule.description ? { description: rule.description } : {}),
+                ...(repairs.length > 0 ? { repairs: repairs.map((r) => r.act) } : {}),
+                evaluate: ({ graph, subject }) => judge(graph, subject),
+            })));
+    }
+    // ── policy, brand, the rest ──────────────────────────────────────────────
+    /*
+     * WHO SEES WHAT is the app's, in the framework's one meaning (FR-02):
+     * absent, everybody sees everything; present, a kind no sight names is
+     * seen by nobody but the system, and `own` is the principal's own records.
+     */
+    const policy = document.policy
+        ? {
+            grants: document.policy.grants,
+            ...(document.policy.sees ? { sees: document.policy.sees } : {}),
+            ...(document.roles ? { roles: document.roles } : {}),
+        }
+        : undefined;
+    let brand;
+    if (document.brand) {
+        const derived = brandFromAccent({ accent: document.brand.accent, base: SCHEMES });
+        if (derived.ok)
+            brand = { name: document.brand.name ?? document.name, schemes: derived.schemes };
+        // A colour that cannot be read is not a reason to refuse an app: it wears the default colours and says why.
+        else
+            findings.push(warning("brand", "brand.accent", `that accent cannot make a readable brand, so the app keeps Graview's colours: ${derived.why}`, "pick a colour further from orange-red, or a darker one"));
+    }
+    if (hasErrors(findings))
+        return { ok: false, findings };
+    const app = {
+        name: document.name,
+        schema,
+        mutations,
+        invariants,
+        ...(policy ? { policy } : {}),
+        ...(brand ? { brand } : {}),
+        ...(document.modules ? { modules: document.modules } : {}),
+        ...(document.lenses ? { lenses: document.lenses } : {}),
+        ...(document.settings ? { settings: document.settings } : {}),
+        // The document's views are the declaration's view specs (FR-03): data the framework draws.
+        ...(document.views && Object.keys(document.views).length > 0 ? { viewSpecs: document.views } : {}),
+        version: document.version ?? 1,
+    };
+    if (!options.skipFrameworkCheck) {
+        const check = checkApp(app);
+        for (const f of check.findings) {
+            const finding = { severity: f.severity === "error" ? "error" : f.severity === "warning" ? "warning" : "note", code: `check:${f.code}`, path: frameworkPath(f.where, document), message: f.message, ...(f.fix ? { fix: f.fix } : {}) };
+            findings.push(f.code === "glance-unchosen" ? inDocumentWords(finding, f.where, document) : finding);
+        }
+        if (hasErrors(findings))
+            return { ok: false, findings };
+    }
+    // `toDocument(app)` gives this document back, byte for byte.
+    rememberDocument(app, document);
+    return { ok: true, app, document, findings, sights: document.policy?.sees, kinds: shapes };
+}
+/** Map a framework check's "where" (a kind, an act, a rule by name) back to a document path when we can. */
+function frameworkPath(where, document) {
+    const word = where.split(/[\s:·]/).find((w) => w.length > 0) ?? where;
+    if (document.kinds[word])
+        return `kinds.${word}`;
+    if (document.acts?.[word])
+        return `acts.${word}`;
+    if (document.rules?.[word])
+        return `rules.${word}`;
+    return where;
+}
+/**
+ * The check tells a TypeScript author to write `display: { glance }`; a
+ * document's author writes `kinds.<kind>.glance` (FR-39) — the same choice
+ * and the same first three, in the words of the format they hold.
+ */
+function inDocumentWords(finding, where, document) {
+    const kind = /^defineNode\("([^"]+)"\)/.exec(where)?.[1];
+    const spec = kind ? document.kinds[kind] : undefined;
+    if (!kind || !spec)
+        return finding;
+    const first = Object.keys(spec.fields).filter((field) => field !== "label").slice(0, 3);
+    return { ...finding, path: `kinds.${kind}.glance`, fix: `Say which: "glance": [${first.map((field) => `"${field}"`).join(", ")}] on kinds.${kind} — the facts a person compares one by, at a glance.` };
+}
+export { Refused as ActRefusal };
+/** Every `renamedFrom` that names nothing in the version before: the values it was meant to carry would be lost. */
+function renamesFromNothing(document, previous) {
+    const out = [];
+    const previousEdges = new Set(Object.values(previous.kinds).flatMap((kind) => Object.keys(kind.edges ?? {})));
+    for (const [kind, spec] of Object.entries(document.kinds)) {
+        const from = spec.renamedFrom;
+        if (from && !previous.kinds[from])
+            out.push(error("renamed-from-nothing", `kinds.${kind}.renamedFrom`, `${kind} says it was ${from}, and the previous version has no kind called ${from}`, "name the kind it was, or drop renamedFrom"));
+        const before = previous.kinds[from ?? kind];
+        for (const [field, fieldSpec] of Object.entries(spec.fields)) {
+            const was = fieldSpec.renamedFrom;
+            if (was && !before?.fields[was])
+                out.push(error("renamed-from-nothing", `kinds.${kind}.fields.${field}.renamedFrom`, `${field} says it was ${was}, and the previous ${from ?? kind} has no field called ${was}`, "name the field it was, or drop renamedFrom"));
+        }
+        for (const [edge, edgeSpec] of Object.entries(spec.edges ?? {})) {
+            const was = edgeSpec.renamedFrom;
+            if (was && !previousEdges.has(was))
+                out.push(error("renamed-from-nothing", `kinds.${kind}.edges.${edge}.renamedFrom`, `${edge} says it was ${was}, and the previous version has no relation called ${was}`, "name the relation it was, or drop renamedFrom"));
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=compile.js.map