worldvm 0.0.0-stage → 0.1.0

package/dist/_internal/ir-checks/contract-validation.d.ts

@@ -0,0 +1,3 @@
+import type * as IR from "../world-ir/types.generated.js";
+/** Contract checks use declarations only; runtime inputs and entity enumeration play no part. */
+export declare const componentContractDiagnostics: (ir: IR.WorldIR) => IR.Diagnostic[];

package/dist/_internal/ir-checks/contract-validation.js

@@ -0,0 +1,307 @@
+import { operationDeclarationProblem } from "./component-operations.js";
+import { canonicalJson, contentDigest } from "./content-digest.js";
+import { componentContractDigest, componentContractSurface } from "./contracts.js";
+/** Contract checks use declarations only; runtime inputs and entity enumeration play no part. */
+export const componentContractDiagnostics = (ir) => {
+    if (!ir.componentContracts?.length &&
+        !ir.componentImports?.length &&
+        !ir.components.some((c) => c.library || c.operations !== undefined))
+        return [];
+    const diagnostics = ir.components.flatMap((c) => {
+        const d = operationDeclarationProblem(ir, c);
+        return d ? [d] : [];
+    });
+    const report = (code, message, at) => diagnostics.push({
+        code,
+        severity: "error",
+        message,
+        at,
+        help: "Import the provider's completed component contract at its declared version. Read published outputs or explicitly public inputs; keep private requirements/state inside the component and invoke declared operations for changes.",
+    });
+    const unique = (names) => new Set(names).size === names.length;
+    const contracts = ir.componentContracts ?? [], imports = ir.componentImports ?? [];
+    for (const values of [
+        ir.libraries,
+        ir.components,
+        ir.roles,
+        ir.types,
+        ir.derives,
+        ir.evidence,
+        ir.interactions,
+        ir.connectors,
+        ir.decisions ?? [],
+        contracts,
+        imports,
+    ])
+        if (!unique(values.map((v) => v.name))) {
+            report("E_COMPONENT_CONTRACT", "Contract models require unambiguous named declarations.", values[0].at);
+            return diagnostics;
+        }
+    const components = new Map(ir.components.map((c) => [c.name, c]));
+    for (const component of ir.components) {
+        if (component.library && !ir.libraries.some((l) => l.name === component.library))
+            report("E_COMPONENT_CONTRACT", `Unknown owner of ${component.name}.`, component.at);
+        for (const values of [
+            component.inputs,
+            component.params,
+            component.outputs,
+            component.actions,
+            ...(contracts.some((c) => c.component === component.name) ? [component.requirements] : []),
+            component.slots,
+        ])
+            if (!unique(values.map((v) => v.name)))
+                report("E_COMPONENT_CONTRACT", `${component.name} has ambiguous members.`, component.at);
+    }
+    for (const c of contracts) {
+        const target = components.get(c.component);
+        if (!target ||
+            target.library !== c.library ||
+            !ir.libraries.some((l) => l.name === c.library)) {
+            report("E_COMPONENT_CONTRACT", `${c.name} must export its own declared component.`, c.at);
+            continue;
+        }
+        if (target.operations && c.operations.some((o) => !target.operations.includes(o.name))) {
+            report("E_NOT_AN_OPERATION", `${c.name} exports an operation private to ${target.name}.`, c.at);
+            continue;
+        }
+        const outputs = c.outputs.map((o) => o.name), operations = c.operations.map((o) => o.name), capabilities = c.capabilities.map((o) => o.connector);
+        if (!unique(outputs) ||
+            !unique(operations) ||
+            !unique(capabilities) ||
+            outputs.some((n) => !target.outputs.some((o) => o.name === n)) ||
+            operations.some((n) => {
+                return (Number(target.actions.some((a) => a.name === n)) +
+                    (ir.decisions ?? []).filter((d) => d.of === target.name && d.name === n).length !==
+                    1);
+            }) ||
+            capabilities.some((n) => !ir.connectors.some((connector) => connector.name === n))) {
+            report("E_COMPONENT_CONTRACT", `${c.name} exposes an undeclared or ambiguous member.`, c.at);
+            continue;
+        }
+        const expected = {
+            name: c.name,
+            library: c.library,
+            ...componentContractSurface(ir, target, outputs, operations, capabilities),
+        };
+        const { digest, doc: _doc, at: _at, ...actual } = c;
+        if (componentContractDigest(expected) !== digest || contentDigest(actual) !== digest)
+            report("E_COMPONENT_CONTRACT", `${c.name} has a stale or forged public surface/digest.`, c.at);
+        for (const action of target.actions)
+            if (action.via.kind === "connector" && !capabilities.includes(action.via.connector))
+                report("E_COMPONENT_CONTRACT", `${c.name} omits required service ${action.via.connector}.`, c.at);
+        for (const resource of target.resources ?? [])
+            for (const call of [resource.acquire, resource.release])
+                if (!capabilities.includes(call.connector))
+                    report("E_COMPONENT_CONTRACT", `${c.name} omits required service ${call.connector}.`, c.at);
+    }
+    const importKeys = new Set();
+    for (const i of imports) {
+        const c = contracts.find((c) => c.name === i.contract), key = JSON.stringify([i.library, c?.component]);
+        if (!ir.libraries.some((l) => l.name === i.library) ||
+            !ir.libraries.some((l) => l.name === i.from && l.version === i.version) ||
+            !c ||
+            c.library !== i.from ||
+            c.digest !== i.digest ||
+            importKeys.has(key))
+            report("E_COMPONENT_IMPORT", `${i.name} has an invalid or ambiguous contract pin.`, i.at);
+        importKeys.add(key);
+    }
+    if (diagnostics.length)
+        return diagnostics;
+    const libraryOf = (c) => c.library ?? ir.libraries[0]?.name;
+    const visible = (owner, target, at) => {
+        const candidates = contracts.filter((c) => c.component === target.name);
+        if (!candidates.length)
+            return undefined;
+        const imported = imports.find((i) => i.library === libraryOf(owner) && candidates.some((c) => c.name === i.contract));
+        const contract = imported
+            ? candidates.find((c) => c.name === imported.contract)
+            : libraryOf(owner) === libraryOf(target) && candidates.length === 1
+                ? candidates[0]
+                : undefined;
+        if (!contract)
+            report("E_COMPONENT_IMPORT", `${owner.name} needs an unambiguous imported contract for ${target.name}.`, at);
+        return contract;
+    };
+    for (const owner of ir.components) {
+        for (const slot of owner.slots) {
+            const target = components.get(slot.component);
+            if (!target) {
+                report("E_COMPONENT_IMPORT", `${slot.name} names no component.`, slot.at);
+                continue;
+            }
+            if (target.library &&
+                libraryOf(owner) !== target.library &&
+                !contracts.some((c) => c.component === target.name))
+                report("E_COMPONENT_IMPORT", `${target.name} is private to ${target.library}.`, slot.at);
+            visible(owner, target, slot.at);
+        }
+        for (const output of owner.outputs)
+            for (const path of output.paths) {
+                let current = owner;
+                for (const [index, segment] of path.segments.entries()) {
+                    const boundary = current.name === owner.name ? undefined : visible(owner, current, path.at);
+                    if (boundary && !boundary.outputs.some((o) => o.name === segment)) {
+                        report("E_COMPONENT_PRIVATE", `${current.name}.${segment} is outside its public contract.`, path.at);
+                        break;
+                    }
+                    const slot = current.slots.find((s) => s.name === segment);
+                    if (slot) {
+                        const next = components.get(slot.component);
+                        if (next) {
+                            current = next;
+                            if (index === path.segments.length - 1) {
+                                const whole = visible(owner, next, path.at);
+                                if (whole &&
+                                    next.outputs.some((o) => !whole.outputs.some((p) => p.name === o.name)))
+                                    report("E_COMPONENT_PRIVATE", `${next.name} has unexported outputs; name a published output explicitly.`, path.at);
+                            }
+                        }
+                    }
+                }
+            }
+    }
+    const unwrap = (t, seen = new Set()) => {
+        if (typeof t === "string") {
+            const a = ir.types.find((a) => a.name === t);
+            if (a && !seen.has(t))
+                return unwrap(a.type, new Set([...seen, t]));
+        }
+        if (Array.isArray(t) && (t[0] === "Option" || t[0] === "Brand"))
+            return unwrap(t[1], seen);
+        return t;
+    };
+    const reference = (t) => {
+        const v = unwrap(t);
+        return Array.isArray(v) && v[0] === "Id" && typeof v[1] === "string" ? v[1] : undefined;
+    };
+    const fieldType = (t, field) => {
+        const name = reference(t), c = components.get(name ?? "");
+        if (c) {
+            const slot = c.slots.find((s) => s.name === field);
+            if (slot)
+                return ["Id", slot.component];
+            if (field === "attached")
+                return ["List", ["Id", ir.libraries[0].subject]];
+            return [...c.inputs, ...c.params].find((f) => f.name === field)?.type ?? "Status";
+        }
+        return [...ir.roles, ...ir.entities]
+            .find((r) => r.name === name)
+            ?.fields.find((f) => f.name === field)?.type;
+    };
+    const typeOf = (e, scope) => {
+        switch (e.k) {
+            case "var":
+                return scope.get(e.name);
+            case "inst":
+                return fieldType(typeOf(e.of, scope), e.field);
+            case "read":
+                return ir.roles.find((r) => r.name === e.role)?.fields.find((f) => f.name === e.field)
+                    ?.type;
+            case "attr":
+                return ir.entities
+                    .find((r) => e.attr.startsWith(r.ns + "/"))
+                    ?.fields.find((f) => f.attr === e.attr)?.type;
+            case "if": {
+                const a = typeOf(e.then, scope), b = typeOf(e.else, scope);
+                return canonicalJson(a) === canonicalJson(b) ? a : undefined;
+            }
+            case "list":
+                return ["List", e.items[0] ? (typeOf(e.items[0], scope) ?? "Unknown") : "Unknown"];
+            case "call": {
+                const derive = ir.derives.find((d) => d.name === e.fn);
+                if (derive)
+                    return derive.returns;
+                if (e.fn === "filter" || e.fn === "spells")
+                    return typeOf(e.args[e.fn === "filter" ? 1 : 0], scope);
+                return undefined;
+            }
+            default:
+                return undefined;
+        }
+    };
+    const walk = (e, scope, owner, active = new Set()) => {
+        if (e.k === "inst") {
+            const target = components.get(reference(typeOf(e.of, scope)) ?? "");
+            if (!target)
+                report("E_COMPONENT_PRIVATE", "A component read needs a statically resolved public receiver.", e.at);
+            else if (target.name !== owner?.name) {
+                const boundary = owner
+                    ? visible(owner, target, e.at)
+                    : contracts.find((c) => c.component === target.name);
+                if (boundary &&
+                    ![...boundary.inputs, ...boundary.params, ...boundary.outputs].some((f) => f.name === e.field))
+                    report("E_COMPONENT_PRIVATE", `${target.name}.${e.field} is outside its public contract.`, e.at);
+            }
+            walk(e.of, scope, owner, active);
+        }
+        else if (e.k === "read" || e.k === "attr")
+            walk(e.of, scope, owner, active);
+        else if (e.k === "if") {
+            walk(e.test, scope, owner, active);
+            walk(e.then, scope, owner, active);
+            walk(e.else, scope, owner, active);
+        }
+        else if (e.k === "list")
+            e.items.forEach((x) => walk(x, scope, owner, active));
+        else if (e.k === "fn") {
+            const inner = new Map(scope);
+            e.params.forEach((p) => inner.delete(p));
+            walk(e.body, inner, owner, active);
+        }
+        else if (e.k === "call") {
+            for (const [i, arg] of e.args.entries()) {
+                if (arg.k === "fn" && i === 0 && (e.fn === "map" || e.fn === "filter")) {
+                    const list = unwrap(typeOf(e.args[1], scope)), inner = new Map(scope);
+                    arg.params.forEach((p) => inner.set(p, Array.isArray(list) && list[0] === "List" ? list[1] : "Unknown"));
+                    walk(arg.body, inner, owner, active);
+                }
+                else
+                    walk(arg, scope, owner, active);
+            }
+            const d = ir.derives.find((d) => d.name === e.fn);
+            if (d && !active.has(d.name))
+                walk(d.body, new Map(d.params.map((p) => [p.name, p.type])), owner, new Set([...active, d.name]));
+        }
+    };
+    const visit = (value, scope, owner) => {
+        if (!value || typeof value !== "object")
+            return;
+        if ("k" in value)
+            walk(value, scope, owner);
+        else
+            for (const [key, child] of Object.entries(value))
+                if (key !== "at")
+                    visit(child, scope, owner);
+    };
+    for (const c of ir.components) {
+        const scope = new Map([...c.inputs, ...c.params].map((f) => [f.name, f.type]));
+        scope.set("self", ["Id", c.name]);
+        scope.set("attached", ["List", ["Id", ir.libraries[0].subject]]);
+        visit(c, scope, c);
+        for (const d of ir.decisions ?? [])
+            if (d.of === c.name)
+                visit(d, scope, c);
+        for (const e of ir.evidence)
+            if (e.of === c.name) {
+                visit(e, scope, c);
+                for (const i of ir.interactions)
+                    if (i.produces === e.name)
+                        visit(i, scope, c);
+            }
+        for (const a of ir.accounts)
+            for (const p of a.policies ?? [])
+                if (p.of === c.name)
+                    visit(p, scope, c);
+    }
+    for (const d of ir.derives)
+        walk(d.body, new Map(d.params.map((p) => [p.name, p.type])), undefined);
+    const seen = new Set();
+    return diagnostics.filter((d) => {
+        const key = JSON.stringify([d.code, d.at]);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+};

package/dist/_internal/ir-checks/contracts.d.ts

@@ -0,0 +1,25 @@
+import type * as IR from "../world-ir/types.generated.js";
+export declare const componentContractSurface: (ir: Pick<IR.WorldIR, "types" | "roles" | "components" | "evidence" | "interactions" | "decisions" | "connectors" | "vaults">, component: IR.Component, outputs: readonly string[], operations: readonly string[], capabilities: readonly string[]) => {
+    component: string;
+    key: readonly string[];
+    home: IR.InputHome;
+    inputs: IR.Field[];
+    params: IR.Field[];
+    paramBounds: IR.ParamBound[];
+    types: IR.Field[];
+    roles: {
+        name: string;
+        fields: readonly IR.Field[];
+    }[];
+    outputs: {
+        name: string;
+        type: "Status";
+    }[];
+    operations: IR.ContractOperation[];
+    capabilities: {
+        connector: string;
+        capabilities: string[];
+    }[];
+    vaults?: readonly [IR.Vault, ...IR.Vault[]];
+};
+export declare const componentContractDigest: (contract: Omit<IR.ComponentContract, "digest" | "doc" | "at">) => string;

package/dist/_internal/ir-checks/contracts.js

@@ -0,0 +1,80 @@
+import { contentDigest } from "./content-digest.js";
+export const componentContractSurface = (ir, component, outputs, operations, capabilities) => {
+    const sorted = (values) => [...values].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    const selectedOperations = operations.map((name) => {
+        const action = component.actions.find((a) => a.name === name);
+        if (action) {
+            const via = action.via;
+            const interaction = via.kind === "interaction" ? ir.interactions.find((i) => i.name === via.name) : undefined;
+            const evidence = interaction
+                ? ir.evidence.find((e) => e.name === interaction.produces)
+                : undefined;
+            return {
+                name,
+                kind: "action",
+                input: sorted(evidence?.fields ?? []),
+                result: evidence ? "Evidence" : "Command",
+                ...(evidence?.sealedBy ? { sealedBy: evidence.sealedBy } : {}),
+                ...(evidence?.amend && evidence.of === component.name ? { amendable: true } : {}),
+                ...(evidence?.attest?.audit
+                    ? { signature: { method: evidence.attest.method, audit: evidence.attest.audit } }
+                    : {}),
+            };
+        }
+        const decision = ir.decisions?.find((d) => d.name === name && d.of === component.name);
+        if (!decision)
+            throw Error(`No operation ${component.name}/${name}`);
+        return {
+            name,
+            kind: "decision",
+            input: [{ name: "reason", type: decision.reason }],
+            result: "Decision",
+        };
+    });
+    const types = new Map(), roles = new Map();
+    const visit = (type) => {
+        if (Array.isArray(type)) {
+            type.forEach(visit);
+            return;
+        }
+        const alias = ir.types.find((t) => t.name === type), role = ir.roles.find((r) => r.name === type);
+        if (alias && !types.has(alias.name)) {
+            types.set(alias.name, { name: alias.name, type: alias.type });
+            visit(alias.type);
+        }
+        if (role && !roles.has(role.name)) {
+            roles.set(role.name, { name: role.name, fields: sorted(role.fields) });
+            role.fields.forEach((f) => visit(f.type));
+        }
+    };
+    [...component.inputs, ...component.params, ...selectedOperations.flatMap((o) => o.input)].forEach((f) => visit(f.type));
+    const seals = new Set([
+        ...component.inputs,
+        ...component.params,
+        ...[...roles.values()].flatMap((r) => r.fields),
+        ...selectedOperations.flatMap((o) => o.input),
+    ].flatMap((f) => (f.sealedBy ? [f.sealedBy.vault] : [])));
+    selectedOperations.forEach((o) => {
+        if (o.sealedBy)
+            seals.add(o.sealedBy.vault);
+    });
+    const vaults = sorted((ir.vaults ?? []).filter((v) => seals.has(v.name)));
+    return {
+        ...(vaults.length ? { vaults: [vaults[0], ...vaults.slice(1)] } : {}),
+        component: component.name,
+        key: component.key,
+        home: component.home,
+        inputs: sorted(component.inputs),
+        params: sorted(component.params),
+        paramBounds: sorted(component.paramBounds ?? []),
+        types: sorted([...types.values()]),
+        roles: sorted([...roles.values()]),
+        outputs: [...outputs].sort().map((name) => ({ name, type: "Status" })),
+        operations: sorted(selectedOperations),
+        capabilities: [...capabilities].sort().map((name) => ({
+            connector: name,
+            capabilities: [...ir.connectors.find((c) => c.name === name).capabilities].sort(),
+        })),
+    };
+};
+export const componentContractDigest = (contract) => contentDigest(contract);

package/dist/_internal/ir-checks/dates.d.ts

@@ -0,0 +1,2 @@
+/** Four-digit ISO local dates, checked without consulting the clock or a time zone. */
+export declare const isLocalDate: (value: unknown) => value is string;

package/dist/_internal/ir-checks/dates.js

@@ -0,0 +1,7 @@
+/** Four-digit ISO local dates, checked without consulting the clock or a time zone. */
+export const isLocalDate = (value) => {
+    if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const ms = Date.parse(`${value}T00:00:00Z`);
+    return Number.isFinite(ms) && new Date(ms).toISOString().slice(0, 10) === value;
+};

package/dist/_internal/ir-checks/documents.d.ts

@@ -0,0 +1,3 @@
+import type * as IR from "../world-ir/types.generated.js";
+export declare const documentHelp = "Use :of Component :from [OwnEvidence] :edition \"1\" :effective {:from \"YYYY-MM-DD\"} :template {:title \"Document\" :fields [{:label \"Field\" :from [OwnEvidence field]}]}. Map fixed scalar fields of the owning component only; use unique nonempty sources/labels and a fixed template.";
+export declare const documentDiagnostics: (ir: Pick<IR.WorldIR, "documents" | "components" | "evidence" | "types">) => IR.Diagnostic[];

package/dist/_internal/ir-checks/documents.js

@@ -0,0 +1,45 @@
+import { resourceProofRequirement } from "./resource-proofs.js";
+import { collectionType } from "./collect-types.js";
+import { isLocalDate } from "./dates.js";
+export const documentHelp = 'Use :of Component :from [OwnEvidence] :edition "1" :effective {:from "YYYY-MM-DD"} :template {:title "Document" :fields [{:label "Field" :from [OwnEvidence field]}]}. Map fixed scalar fields of the owning component only; use unique nonempty sources/labels and a fixed template.';
+export const documentDiagnostics = (ir) => {
+    const errors = [], names = new Set();
+    for (const d of ir.documents ?? []) {
+        const error = (code, message, at = d.at) => errors.push({ code, severity: "error", message, at, help: documentHelp });
+        if (names.has(d.name))
+            error("E_DOCUMENT_TEMPLATE", "Document names must be unique.");
+        names.add(d.name);
+        if (!d.edition.trim() ||
+            !d.title.trim() ||
+            !d.fields.length ||
+            new Set(d.fields.map((f) => f.label)).size !== d.fields.length ||
+            d.fields.some((f) => !f.label.trim()))
+            error("E_DOCUMENT_TEMPLATE", "Templates need fixed nonempty editions, titles and unique labels.");
+        const { from, until } = d.effective;
+        if ((!from && !until) ||
+            (from !== undefined && !isLocalDate(from)) ||
+            (until !== undefined && !isLocalDate(until)) ||
+            (from && until && from >= until))
+            error("E_DOCUMENT_TEMPLATE", "Template effective dates must form a fixed valid window.", d.effective.at);
+        if (!ir.components.some((c) => c.name === d.of) ||
+            !d.sources.length ||
+            new Set(d.sources).size !== d.sources.length ||
+            d.sources.some((name) => !ir.evidence.some((e) => e.name === name && e.of === d.of)))
+            error("E_DOCUMENT_SOURCE", "A document reads unique evidence types owned by its component.");
+        if (d.resource) {
+            const component = ir.components.find((c) => c.name === d.of);
+            if (!component?.resources?.some((r) => r.name === d.resource.name) ||
+                d.sources.some((type) => !resourceProofRequirement(component, d.resource.name, type)))
+                error("E_DOCUMENT_RESOURCE", "A resource-scoped document needs an owned resource and uniquely generation-cycled source proofs.", d.resource.at);
+        }
+        for (const f of d.fields) {
+            const evidence = ir.evidence.find((e) => e.name === f.evidence), field = evidence?.fields.find((x) => x.name === f.field);
+            if (!d.sources.includes(f.evidence) ||
+                evidence?.of !== d.of ||
+                !field ||
+                !collectionType(field.type, ir.types))
+                error("E_DOCUMENT_SOURCE", "Document fields must name scalar fields of the selected own evidence.", f.at);
+        }
+    }
+    return errors;
+};

package/dist/_internal/ir-checks/evidence.d.ts

@@ -0,0 +1,20 @@
+import type { Span } from "./index.js";
+interface Model {
+    readonly evidence?: readonly {
+        readonly expires?: unknown;
+    }[];
+    readonly derives: readonly {
+        readonly name: string;
+        readonly body: unknown;
+    }[];
+}
+export interface EvidenceScopeDiagnostic {
+    readonly code: "E_EXPIRES_SCOPE";
+    readonly severity: "error";
+    readonly message: string;
+    readonly help: string;
+    readonly at?: Span;
+}
+/** Expiry is a function of a signed record, not its owner's live operational context. */
+export declare const evidenceScopeDiagnostics: (ir: Model) => EvidenceScopeDiagnostic[];
+export {};

package/dist/_internal/ir-checks/evidence.js

@@ -0,0 +1,56 @@
+/** Expiry is a function of a signed record, not its owner's live operational context. */
+export const evidenceScopeDiagnostics = (ir) => {
+    const derives = new Map(ir.derives.map((d) => [d.name, d.body]));
+    const diagnostics = [];
+    const checked = new Set();
+    const scan = (value, active) => {
+        if (Array.isArray(value)) {
+            for (const child of value)
+                scan(child, active);
+            return;
+        }
+        if (!value || typeof value !== "object")
+            return;
+        const node = value;
+        const forbidden = ["read", "attr", "inst"].includes(String(node.k)) ||
+            (node.k === "ref" && node.kind !== "calendar") ||
+            (node.k === "call" &&
+                [
+                    "attested",
+                    "resource-generation",
+                    "entered-at",
+                    "attested-for",
+                    "notice-delivered?",
+                    "notice-acknowledged?",
+                    "valid",
+                    "decided",
+                    "added-on",
+                    "carried-over?",
+                    "started?",
+                    "final?",
+                    "in-state?",
+                ].includes(String(node.fn)));
+        const name = node.k === "call" && node.derive === true ? String(node.fn) : undefined;
+        if (forbidden || (name && active.has(name))) {
+            diagnostics.push({
+                code: "E_EXPIRES_SCOPE",
+                severity: "error",
+                message: "Expiry must use signed fields and pure, acyclic date logic.",
+                help: "Use a date field or a pure derive over the signed fields. Put live facts, evidence and decisions in requirement predicates.",
+                ...(node.at ? { at: node.at } : {}),
+            });
+            return;
+        }
+        if (name && !checked.has(name)) {
+            scan(derives.get(name), new Set([...active, name]));
+            checked.add(name);
+        }
+        for (const [key, child] of Object.entries(node))
+            if (key !== "at")
+                scan(child, active);
+    };
+    for (const evidence of ir.evidence ?? [])
+        if (evidence.expires)
+            scan(evidence.expires, new Set());
+    return diagnostics;
+};

package/dist/_internal/ir-checks/files.d.ts

@@ -0,0 +1,7 @@
+import type * as IR from "../world-ir/types.generated.js";
+export declare const fileDigest: (value: unknown) => value is string;
+export declare const filePolicyHelp = "Use a File (including classified, optional or aliased File) field with :files {:field {:accept [\"application/pdf\"] :max-bytes 1048576}}. Declare fixed unique lowercase media types and a positive safe-integer byte limit; do not use wildcards, expressions or structured File collections.";
+export declare const fileShape: (type: IR.TypeRef, aliases: readonly IR.TypeAlias[], seen?: Set<string>) => "file" | "other" | "unsupported";
+export declare const fileMediaType: (value: unknown) => value is string;
+export declare const filePolicyValid: (value: IR.FilePolicy) => boolean;
+export declare const fileFieldDiagnostics: (ir: Pick<IR.WorldIR, "types" | "roles" | "entities" | "evidence">) => IR.Diagnostic[];

package/dist/_internal/ir-checks/files.js

@@ -0,0 +1,47 @@
+import { sensitivePayload } from "./sensitivity.js";
+export const fileDigest = (value) => typeof value === "string" && /^sha256:[a-f0-9]{64}$/.test(value);
+export const filePolicyHelp = 'Use a File (including classified, optional or aliased File) field with :files {:field {:accept ["application/pdf"] :max-bytes 1048576}}. Declare fixed unique lowercase media types and a positive safe-integer byte limit; do not use wildcards, expressions or structured File collections.';
+export const fileShape = (type, aliases, seen = new Set()) => {
+    if (type === "File")
+        return "file";
+    if (typeof type === "string") {
+        const alias = aliases.find((a) => a.name === type);
+        return alias && !seen.has(type)
+            ? fileShape(alias.type, aliases, new Set([...seen, type]))
+            : "other";
+    }
+    if (type[0] === "Sensitive") {
+        const payload = sensitivePayload(type);
+        return payload ? fileShape(payload, aliases, seen) : "unsupported";
+    }
+    if (type[0] === "Option" || type[0] === "Brand")
+        return type[1] ? fileShape(type[1], aliases, seen) : "other";
+    return type.slice(1).some((t) => fileShape(t, aliases, seen) !== "other")
+        ? "unsupported"
+        : "other";
+};
+export const fileMediaType = (value) => typeof value === "string" &&
+    /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/.test(value);
+export const filePolicyValid = (value) => Number.isSafeInteger(value.maxBytes) &&
+    value.maxBytes > 0 &&
+    value.accept.length > 0 &&
+    value.accept.every(fileMediaType) &&
+    new Set(value.accept).size === value.accept.length;
+export const fileFieldDiagnostics = (ir) => {
+    const errors = [];
+    for (const owner of [...ir.roles, ...ir.entities, ...ir.evidence])
+        for (const field of owner.fields) {
+            const shape = fileShape(field.type, ir.types);
+            if (shape === "unsupported" ||
+                (shape === "file" && !field.file) ||
+                (field.file && (shape !== "file" || !filePolicyValid(field.file))))
+                errors.push({
+                    code: "E_FILE_POLICY",
+                    severity: "error",
+                    message: `${owner.name}/${field.name} needs a fixed policy for a single File reference.`,
+                    at: field.file?.at ?? owner.at,
+                    help: filePolicyHelp,
+                });
+        }
+    return errors;
+};