worldvm 0.0.0-stage → 0.1.0

package/dist/manual/projections.d.ts

@@ -0,0 +1,77 @@
+import type { Citation, Expr, SourceFile, Span, WorldIR } from "../_internal/forma/world/index.js";
+import { type Description } from "./prose.js";
+export { describe } from "./prose.js";
+export type { Description, Context } from "./prose.js";
+import { type RequirementExample } from "./examples.js";
+export interface CitationView {
+    readonly title: string;
+    readonly clause: string;
+    readonly kind: string;
+    readonly asOf: string;
+    readonly url: string | null;
+    readonly caveat: string;
+    readonly at: Span;
+}
+export declare const citationView: (ir: WorldIR, cite: Citation) => CitationView;
+export interface RequirementView {
+    readonly id: string;
+    readonly component: string;
+    readonly title: string;
+    readonly at: Span;
+    readonly rows: readonly {
+        readonly label: string;
+        readonly description: Description;
+    }[];
+    readonly citations: readonly CitationView[];
+    readonly examples: readonly string[];
+    readonly exampleDetails: readonly RequirementExample[];
+    readonly actions: readonly {
+        readonly name: string;
+        readonly title: string;
+        readonly interaction: string | null;
+        readonly at: Span;
+    }[];
+}
+export declare const projectRequirements: (ir: WorldIR, files: readonly SourceFile[]) => readonly RequirementView[];
+export interface RecordView {
+    readonly id: string;
+    readonly kind: string;
+    readonly title: string;
+    readonly doc: string;
+    readonly at: Span;
+    readonly component: string;
+    readonly rows: readonly {
+        readonly label: string;
+        readonly description: Description;
+    }[];
+    readonly citations: readonly CitationView[];
+}
+export declare const projectPeople: (ir: WorldIR, files: readonly SourceFile[]) => readonly RecordView[];
+export declare const projectHomes: (ir: WorldIR) => {
+    id: string;
+    title: string;
+    at: Span;
+    key: string;
+    home: string;
+    owners: string;
+    inputs: string;
+    edges: {
+        name: string;
+        target: string;
+        mode: "child" | "attach";
+        at: Span;
+        bindings: readonly {
+            readonly input: string;
+            readonly expr: Expr;
+        }[];
+    }[];
+    library: string;
+}[];
+export declare const componentPath: (ir: WorldIR, account: string, target: string) => readonly string[];
+export declare const projectManual: (ir: WorldIR, files: readonly SourceFile[], account: string) => {
+    account: import("../_internal/world-ir/types.generated.js").Account | undefined;
+    used: RequirementView[];
+    examples: RequirementView[];
+    people: readonly RecordView[];
+    sources: readonly import("../_internal/world-ir/types.generated.js").Source[];
+};

package/dist/manual/projections.js

@@ -0,0 +1,344 @@
+import { definitionReferences } from "../_internal/forma/world/index.js";
+import { accountComponents, requirementCards } from "./catalog.js";
+import { firstLine, humanize, safeUrl, sourceTitle } from "./text.js";
+import { describe, actorDescription, sentence } from "./prose.js";
+export { describe } from "./prose.js";
+import { requirementExamples } from "./examples.js";
+const words = (name) => humanize(name).replace(/\//g, " / ");
+const join = (text, parts = []) => ({
+    text,
+    fallbacks: parts.flatMap((p) => p.fallbacks),
+    notes: parts.flatMap((p) => p.notes ?? []),
+});
+export const citationView = (ir, cite) => {
+    const source = ir.references?.find((s) => s.name === cite.source);
+    return {
+        title: source ? sourceTitle(source) : words(cite.source),
+        clause: cite.clause.replace(/\s*\(illustrative mapping\)/gi, ""),
+        kind: source?.kind ?? "undeclared source",
+        asOf: source?.asOf ?? "unknown",
+        url: source ? safeUrl(source.url) : null,
+        caveat: source?.doc ?? "",
+        at: cite.at,
+    };
+};
+export const projectRequirements = (ir, files) => {
+    const refs = definitionReferences(ir);
+    return requirementCards(ir).map(({ id, component: c, requirement: r, at }) => {
+        const actions = c.actions.filter((a) => (Array.isArray(a.advances) ? a.advances : [a.advances]).includes(r.name));
+        const ctx = { ir, files, component: c, actors: actions };
+        const timing = [];
+        if (r.remind)
+            timing.push({
+                label: "Reminder",
+                description: join(`${describe(ctx, r.remind).text} before the due date.`, [
+                    describe(ctx, r.remind),
+                ]),
+            });
+        if (r.recur)
+            timing.push({
+                label: "Repeats",
+                description: join(`Every ${r.recur.every.n} ${r.recur.every.unit} from ${describe(ctx, r.recur.from).text}; each period keeps independent proof.`, [describe(ctx, r.recur.from)]),
+            });
+        if (r.effective)
+            timing.push({
+                label: "Effective",
+                description: join(`${r.effective.from ? `From ${r.effective.from} (inclusive)` : "No fixed start"}${r.effective.until ? ` until ${r.effective.until} (exclusive)` : "; no fixed end"}.`),
+            });
+        const evidenceRefs = new Set();
+        const visit = (value) => {
+            if (!value || typeof value !== "object")
+                return;
+            if (Array.isArray(value)) {
+                value.forEach(visit);
+                return;
+            }
+            const object = value;
+            if (object.k === "ref" && object.kind === "evidence")
+                evidenceRefs.add(String(object.name));
+            for (const [key, v] of Object.entries(object))
+                if (key !== "at")
+                    visit(v);
+        };
+        visit(r.satisfiedBy);
+        for (const name of evidenceRefs) {
+            const evidence = ir.evidence.find((e) => e.name === name);
+            if (evidence?.expires)
+                timing.push({ label: "Proof expires", description: describe(ctx, evidence.expires) });
+        }
+        if (r.renewWithin)
+            timing.push({
+                label: "Renewal",
+                description: join(`New work ${r.renewWithin.n} ${r.renewWithin.unit} before proof expires; current proof remains in history.`),
+            });
+        if (r.accepts)
+            timing.push({
+                label: "Prior proof",
+                description: join(`Prior-cycle proof may be offered${r.accepts.within ? ` within ${describe(ctx, r.accepts.within).text}` : ""}${r.accepts.confirm ? `, confirmed by ${describe(ctx, r.accepts.confirm).text}` : " under its declared acceptance rule"}.`),
+            });
+        if (r.reuse)
+            timing.push({
+                label: "Reuse",
+                description: join(`Proof may be shared within ${r.reuse.within.n} ${r.reuse.within.unit}${r.reuse.confirm ? `, confirmed by ${describe(ctx, r.reuse.confirm).text}` : " under the declared scope"}.`),
+            });
+        const examples = requirementExamples(ir, c.name, r.name, (refs.get(id) ?? []).filter((ref) => ref.kind === "scenario").map((ref) => ref.name));
+        return {
+            id,
+            component: c.name,
+            title: r.label ?? words(r.name),
+            at,
+            rows: [
+                {
+                    label: "Done when",
+                    description: describe({ ...ctx, conditionOnly: true }, r.satisfiedBy),
+                },
+                {
+                    label: "Who",
+                    description: actions.length
+                        ? join(actions
+                            .map((a) => actorDescription(ctx, a.assignee, a.assigneeKind).text)
+                            .join("; "), actions.map((a) => actorDescription(ctx, a.assignee, a.assigneeKind)))
+                        : join("No action is declared. Read the condition and any awaited signal in source."),
+                },
+                { label: "Due", description: sentence(describe(ctx, r.due, "No explicit deadline.")) },
+                ...(r.appliesWhen
+                    ? [{ label: "Applies when", description: describe(ctx, r.appliesWhen) }]
+                    : []),
+                ...timing,
+            ],
+            citations: (r.cites ?? []).map((cite) => citationView(ir, cite)),
+            examples: examples.map((e) => e.name),
+            exampleDetails: examples,
+            actions: actions.map((a) => ({
+                name: a.name,
+                title: a.label ?? words(a.name),
+                interaction: a.via.kind === "interaction" ? a.via.name : null,
+                at: a.at,
+            })),
+        };
+    });
+};
+export const projectPeople = (ir, files) => {
+    const records = [];
+    for (const c of ir.components)
+        for (const a of c.actions) {
+            const ctx = { ir, files, component: c }, via = a.via;
+            records.push({
+                id: `${c.name}/${a.name}`,
+                kind: "Action",
+                component: c.name,
+                title: a.label ?? words(a.name),
+                doc: c.doc ?? "",
+                at: a.at,
+                citations: [],
+                rows: [
+                    { label: "Who", description: actorDescription(ctx, a.assignee, a.assigneeKind) },
+                    {
+                        label: "Advances",
+                        description: join((Array.isArray(a.advances) ? a.advances : [a.advances])
+                            .map((name) => c.requirements.find((r) => r.name === name)?.label ?? words(name))
+                            .join("; ")),
+                    },
+                    {
+                        label: "Needs",
+                        description: join(a.needs.map((n) => describe(ctx, n.expr).text).join("; ") || "No additional gate.", a.needs.map((n) => describe(ctx, n.expr))),
+                    },
+                    {
+                        label: "Via",
+                        description: join(via.kind === "interaction"
+                            ? (ir.interactions.find((i) => i.name === via.name)?.doc ?? words(via.name))
+                            : `${words(via.connector)} / ${words(via.capability)}`),
+                    },
+                    ...(a.dispatch || a.onIneligible
+                        ? [
+                            {
+                                label: "Dispatch",
+                                description: join([
+                                    a.dispatch ? `Dispatch: ${a.dispatch}` : "",
+                                    a.onIneligible ? `If ineligible: ${a.onIneligible}` : "",
+                                ]
+                                    .filter(Boolean)
+                                    .join("; ")),
+                            },
+                        ]
+                        : []),
+                ],
+            });
+        }
+    for (const c of ir.components) {
+        const ctx = { ir, files, component: c };
+        for (const invariant of c.invariants)
+            records.push({
+                id: `${c.name}/${invariant.name}`,
+                component: c.name,
+                kind: "Prohibition",
+                title: words(invariant.name),
+                doc: "Admission checks apply while the declared condition holds.",
+                at: invariant.at,
+                citations: (invariant.cites ?? []).map((cite) => citationView(ir, cite)),
+                rows: [
+                    {
+                        label: "Forbids",
+                        description: join(`${words(invariant.forbids.action)} for ${describe(ctx, invariant.forbids.subject).text}`),
+                    },
+                    { label: "While", description: describe(ctx, invariant.while) },
+                ],
+            });
+        if (c.retention)
+            records.push({
+                id: `${c.name}/retention`,
+                component: c.name,
+                kind: "Retention",
+                title: "Record retention",
+                doc: "A declared retention deadline does not itself delete evidence.",
+                at: c.retention.at,
+                citations: (c.retention.cites ?? []).map((cite) => citationView(ir, cite)),
+                rows: [
+                    { label: "Keep until", description: describe(ctx, c.retention.until) },
+                    { label: "Disposition", description: join(c.retention.disposal) },
+                ],
+            });
+    }
+    for (const d of ir.decisions ?? []) {
+        const ctx = { ir, files, component: ir.components.find((c) => c.name === d.of) };
+        records.push({
+            id: d.name,
+            kind: "Decision",
+            component: d.of,
+            title: d.doc ? firstLine(d.doc) : words(d.name),
+            doc: "Declared human authority; actual membership is checked by the host.",
+            at: d.at,
+            citations: (d.cites ?? []).map((c) => citationView(ir, c)),
+            rows: [
+                { label: "Who", description: describe(ctx, d.by) },
+                { label: "Effect", description: join(`${d.effect} ${words(d.applies)}`) },
+                { label: "Quorum", description: describe(ctx, d.approvals, "1 distinct human") },
+                {
+                    label: "Must differ from",
+                    description: join((d.distinctFrom ?? []).map((e) => describe(ctx, e).text).join("; ") ||
+                        "No extra exclusion declared."),
+                },
+                { label: "When", description: describe(ctx, d.when, "No additional condition.") },
+                {
+                    label: "Expires",
+                    description: describe(ctx, d.expires, d.until ? describe(ctx, d.until).text : "No declared expiry."),
+                },
+            ],
+        });
+    }
+    for (const d of ir.documents ?? [])
+        records.push({
+            id: d.name,
+            kind: "Document",
+            component: d.of,
+            title: d.title,
+            doc: d.doc ?? "",
+            at: d.at,
+            citations: [],
+            rows: [
+                { label: "Edition", description: join(d.edition) },
+                {
+                    label: "Signed sources",
+                    description: join(d.sources
+                        .map((s) => ir.evidence.find((e) => e.name === s)?.label ?? words(s))
+                        .join("; ")),
+                },
+                {
+                    label: "Fields",
+                    description: join(d.fields.map((f) => `${f.label} ← ${words(f.evidence)} / ${words(f.field)}`).join("; ")),
+                },
+                {
+                    label: "Effective",
+                    description: join(`${d.effective.from ?? "No fixed start"} → ${d.effective.until ?? "no fixed end"}`),
+                },
+            ],
+        });
+    for (const n of ir.notices ?? [])
+        records.push({
+            id: n.name,
+            kind: "Notice",
+            component: n.of,
+            title: n.doc ? firstLine(n.doc) : words(n.name),
+            doc: "Delivery and human acknowledgment are separate observations.",
+            at: n.at,
+            citations: [],
+            rows: [
+                {
+                    label: "Copy of",
+                    description: join(ir.documents?.find((d) => d.name === n.document)?.title ?? words(n.document)),
+                },
+                { label: "Recipient", description: describe({ ir, files }, n.to) },
+            ],
+        });
+    return records;
+};
+const homeRole = (ir, c, path = c.home.path, seen = new Set()) => {
+    const key = `${c.name}/${path.join(".")}`;
+    if (seen.has(key))
+        return null;
+    const field = c.inputs.find((f) => f.name === path[0]);
+    if (!field)
+        return null;
+    let type = field.type;
+    if (Array.isArray(type) && type[0] === "Option")
+        type = type[1];
+    if (!Array.isArray(type) || type[0] !== "Id" || typeof type[1] !== "string")
+        return null;
+    const target = ir.components.find((component) => component.name === type[1]);
+    return target
+        ? homeRole(ir, target, path.length > 1 ? path.slice(1) : target.home.path, new Set([...seen, key]))
+        : type[1];
+};
+export const projectHomes = (ir) => ir.components.map((c) => ({
+    id: c.name,
+    title: c.doc ? firstLine(c.doc) : words(c.name),
+    at: c.at,
+    key: c.key.join(" × "),
+    home: c.home.path.join(" → "),
+    owners: ir.entities
+        .filter((e) => e.name === homeRole(ir, c) || e.implements.some((b) => b.role === homeRole(ir, c)))
+        .map((e) => words(e.name))
+        .join(" / ") || `Declared role: ${homeRole(ir, c) ?? "unresolved; read source"}`,
+    inputs: c.inputs
+        .map((i) => `${words(i.name)}: ${Array.isArray(i.type) ? i.type.join(" ") : i.type}`)
+        .join("; "),
+    edges: c.slots.map((s) => ({
+        name: s.name,
+        target: s.component,
+        mode: s.mode,
+        at: s.at,
+        bindings: s.bind,
+    })),
+    library: c.library ?? "local package",
+}));
+export const componentPath = (ir, account, target) => {
+    const visit = (name, path) => {
+        if (path.includes(name))
+            return [];
+        const next = [...path, name];
+        if (name === target)
+            return next;
+        for (const slot of ir.components.find((c) => c.name === name)?.slots ?? []) {
+            const found = visit(slot.component, next);
+            if (found.length)
+                return found;
+        }
+        return [];
+    };
+    for (const root of ir.accounts.find((a) => a.name === account)?.forEach ?? []) {
+        const found = visit(root.component, []);
+        if (found.length)
+            return found;
+    }
+    return [];
+};
+export const projectManual = (ir, files, account) => {
+    const used = accountComponents(ir, account), requirements = projectRequirements(ir, files);
+    return {
+        account: ir.accounts.find((a) => a.name === account),
+        used: requirements.filter((r) => used.has(r.component)),
+        examples: requirements.filter((r) => !used.has(r.component)),
+        people: projectPeople(ir, files),
+        sources: ir.references ?? [],
+    };
+};

package/dist/manual/prose.d.ts

@@ -0,0 +1,19 @@
+import type { Action, Component, Expr, SourceFile, WorldIR } from "../_internal/forma/world/index.js";
+export interface Description {
+    readonly text: string;
+    readonly fallbacks: readonly {
+        readonly at: Expr["at"];
+        readonly text: string;
+    }[];
+    readonly notes?: readonly string[];
+}
+export interface Context {
+    readonly ir: WorldIR;
+    readonly files: readonly SourceFile[];
+    readonly component?: Component;
+    readonly actors?: readonly Action[];
+    readonly conditionOnly?: boolean;
+}
+export declare const sentence: (d: Description) => Description;
+export declare const actorDescription: (ctx: Context, expr: Expr | undefined, kind?: string) => Description;
+export declare const describe: (ctx: Context, expr: Expr | undefined, absent?: string) => Description;

package/dist/manual/prose.js

@@ -0,0 +1,215 @@
+import { firstLine, humanize } from "./text.js";
+const words = (name) => humanize(name)
+    .replace(/\//g, " / ")
+    .replace(/\b([a-z])(\d+)\b/gi, (_, letter, digits) => `${letter.toUpperCase()}-${digits}`);
+const unitFor = (n, unit) => n === "1" ? unit.replace(/s$/, "") : unit;
+const fragment = (text) => text.replace(/[.!?]+$/u, "").replace(/^[A-Z](?=[a-z])/, (c) => c.toLowerCase());
+const join = (text, parts = []) => ({
+    text,
+    fallbacks: parts.flatMap((p) => p.fallbacks),
+    notes: [...new Set(parts.flatMap((p) => p.notes ?? []))],
+});
+const phrase = (doc, name) => {
+    const first = firstLine(doc)
+        .split(":")[0]
+        .trim()
+        .replace(/[.!?]+$/u, "");
+    return fragment(first.length <= 75 ? first : words(name).replace(/\?$/, ""));
+};
+export const sentence = (d) => ({
+    ...d,
+    text: `${d.text.replace(/^[a-z]/, (c) => c.toUpperCase()).replace(/[.!?]+$/u, "")}.`,
+});
+export const actorDescription = (ctx, expr, kind) => {
+    if (!expr)
+        return join("No assignee declared");
+    if (expr.k === "var")
+        return join(`the ${words(expr.name)}`);
+    if (expr.k === "call" && expr.fn === "members" && expr.args[0]) {
+        const group = expr.args[0];
+        if (group.k === "read" || group.k === "attr") {
+            const field = words(group.k === "read" ? group.field : group.attr.split("/").at(-1));
+            const owner = describe(ctx, group.of).text;
+            if (/\b(reviewers|approvers|owners|operators|leads|managers|admins|developers)$/.test(field)) {
+                const role = field.replace(/s$/u, "");
+                return join(`${/^[aeiou]/i.test(role) ? "an" : "a"} ${role} ${/employer|company|organization/.test(owner) ? "at" : "for"} the ${owner}`);
+            }
+        }
+        const value = describe(ctx, group);
+        return join(`a member of ${value.text}`, [value]);
+    }
+    const value = describe(ctx, expr);
+    return join(`${kind === "group" ? "a member of " : "the "}${value.text}`, [value]);
+};
+export const describe = (ctx, expr, absent = "Not declared.") => {
+    if (!expr)
+        return join(absent);
+    const child = (e) => describe(ctx, e);
+    const fallback = () => ({
+        text: "Read the declared expression in source.",
+        fallbacks: [
+            {
+                at: expr.at,
+                text: ctx.files.find((f) => f.id === expr.at.src)?.text.slice(expr.at.from, expr.at.to) ??
+                    JSON.stringify(expr),
+            },
+        ],
+    });
+    switch (expr.k) {
+        case "lit":
+            return join(expr.v === null ? "unknown" : String(expr.v));
+        case "kw":
+            return join(words(expr.v));
+        case "var": {
+            const bound = ctx.component?.paramBounds?.find((p) => p.name === expr.name);
+            return bound
+                ? {
+                    text: String(bound.default.n),
+                    fallbacks: [],
+                    notes: [
+                        `${bound.name}, default ${bound.default.n}${bound.default.unit === "integer" ? "" : ` ${bound.default.unit}`}`,
+                    ],
+                }
+                : join(ctx.component?.requirements.find((r) => r.name === expr.name)?.label ??
+                    words(expr.name));
+        }
+        case "ref": {
+            if (expr.kind === "calendar") {
+                const calendar = ctx.ir.calendars.find((c) => c.name === expr.name);
+                return {
+                    text: words(calendar?.name ?? expr.name).replace(/\b[a-z]{2}\b/g, (w) => w.toUpperCase()),
+                    fallbacks: [],
+                    notes: calendar ? [`${calendar.doc ?? calendar.name} · version ${calendar.version}`] : [],
+                };
+            }
+            return join(ctx.ir.evidence.find((e) => e.name === expr.name)?.label ?? words(expr.name));
+        }
+        case "read":
+        case "attr": {
+            const base = child(expr.of);
+            return join(`${base.text}’s ${words(expr.k === "read" ? expr.field : expr.attr.split("/").at(-1))}`, [base]);
+        }
+        case "inst": {
+            const base = child(expr.of);
+            return join(`${base.text}’s ${words(expr.field)}`, [base]);
+        }
+        case "list": {
+            const parts = expr.items.map(child);
+            return join(parts.map((p) => p.text).join(", "), parts);
+        }
+        case "fn":
+            return fallback();
+        case "if": {
+            const yes = child(expr.then), no = child(expr.else);
+            if (expr.test.k === "call" &&
+                ["false?", "true?"].includes(expr.test.fn) &&
+                expr.test.args[0]) {
+                const test = child(expr.test.args[0]);
+                return join(`${yes.text} when “${fragment(test.text)}” is known ${expr.test.fn === "false?" ? "false" : "true"}; otherwise, including when unknown, ${fragment(no.text)}`, [yes, test, no]);
+            }
+            const test = child(expr.test);
+            return join(`If ${fragment(test.text)}, ${fragment(yes.text)}; otherwise ${fragment(no.text)}`, [test, yes, no]);
+        }
+        case "call": {
+            const parts = expr.args.map(child), a = parts.map((p) => p.text), first = expr.args[0];
+            const finish = (text) => join(text, parts);
+            if (["attested", "valid"].includes(expr.fn) && first?.k === "ref") {
+                const evidence = ctx.ir.evidence.find((e) => e.name === first.name), label = evidence?.label ?? words(first.name);
+                if (expr.fn === "valid")
+                    return finish(`there is current, unexpired attested ${label} evidence`);
+                if (ctx.conditionOnly && evidence?.attest)
+                    return finish(`${label} is signed`);
+                let actor = `the ${words(evidence?.attest?.signer ?? "signer")}`;
+                if (evidence?.attest?.signer === "assignee") {
+                    const choices = [
+                        ...new Set((ctx.actors ?? []).map((action) => actorDescription(ctx, action.assignee, action.assigneeKind).text)),
+                    ];
+                    actor = choices.length ? choices.join(" or ") : "the assigned person";
+                }
+                return finish(evidence?.attest ? `${actor} signs ${label}` : `there is attested ${label} evidence`);
+            }
+            switch (expr.fn) {
+                case "members":
+                    return finish(`members of ${a[0]}`);
+                case "days":
+                case "months":
+                case "years":
+                case "hours":
+                case "minutes":
+                    return finish(`${a[0]} ${unitFor(a[0], expr.fn)}`);
+                case "first":
+                    return finish(`the first of ${a[0]}`);
+                case "earliest":
+                case "latest":
+                    return finish(`the ${expr.fn} of ${a[0]}`);
+                case "days-after":
+                case "months-after":
+                case "years-after":
+                case "hours-after":
+                case "minutes-after":
+                case "days-before": {
+                    const [unit, direction] = expr.fn.split("-");
+                    return finish(`${a[1]} ${unitFor(a[1], unit)} ${direction} ${fragment(a[0] ?? "unknown")}`);
+                }
+                case "business-days-after": {
+                    const calendar = expr.args.findIndex((arg) => arg.k === "ref" && arg.kind === "calendar");
+                    return finish(`${a[1]} business ${unitFor(a[1], "days")} after ${fragment(a[0] ?? "unknown")}${calendar >= 0 ? ` (${a[calendar]} calendar)` : ""}`);
+                }
+                case "=":
+                    return finish(`${a[0]} is ${a[1]}`);
+                case "not=":
+                    return finish(`${a[0]} differs from ${a[1]}`);
+                case "<":
+                    return finish(`${a[0]} is less than ${a[1]}`);
+                case "<=":
+                    return finish(`${a[0]} is at most ${a[1]}`);
+                case ">":
+                    return finish(`${a[0]} is greater than ${a[1]}`);
+                case ">=":
+                    return finish(`${a[0]} is at least ${a[1]}`);
+                case "known?":
+                    return finish(`${a[0]} is known`);
+                case "true?":
+                    return finish(`“${a[0]}” is known true`);
+                case "false?":
+                    return finish(`“${a[0]}” is known false`);
+                case "unknown?":
+                    return finish(`${a[0]} is unknown`);
+                case "negate":
+                    return finish(`not (${a[0]})`);
+                case "all?":
+                    return finish(`all of: ${a[0] || "no additional conditions"}`);
+                case "any?":
+                    return finish(`at least one of: ${a[0]}`);
+                case "in?":
+                    return finish(`${a[0]} is one of ${a[1]}`);
+                case "satisfied?":
+                    return finish(`${a[0]} is satisfied`);
+                case "met?":
+                    return finish(`${a[0]} is satisfied or does not apply`);
+                case "carried-over?":
+                    return finish(`${a[0]} uses accepted prior proof`);
+                case "decided":
+                    return finish(`the ${a[0]} decision stands`);
+                case "notice-delivered?":
+                    return finish(`${a[0]} has been delivered`);
+                case "notice-acknowledged?":
+                    return finish(`the recipient acknowledges ${a[0]}`);
+                case "final?":
+                    return finish(`${a[0]} reaches a declared final state`);
+                case "started?":
+                    return finish(`${a[0]} has started`);
+                case "in-state?":
+                    return finish(`${a[0]} is in one of these states: ${a[1]}`);
+            }
+            const derive = ctx.ir.derives.find((d) => d.name === expr.fn);
+            if (derive?.doc)
+                return {
+                    text: phrase(derive.doc, derive.name),
+                    fallbacks: [],
+                    notes: [derive.doc, ...parts.flatMap((p) => p.notes ?? [])],
+                };
+            return fallback();
+        }
+    }
+};