@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/analyze.js

@@ -0,0 +1,2438 @@
+import { validateBrowserSignIn } from "./sign-in.js";
+import { checkWarehouseSource } from "./warehouse-backed.js";
+import { Result, Schema } from "effect";
+import { BLOB_UPLOAD_ANNOTATION } from "./blob.js";
+import { isBlobAccept, MAX_BLOB_BYTES } from "./blob.js";
+import { isAction } from "./action.js";
+import { CONNECTION_KEY, isConnection } from "./connection.js";
+import { isEntity } from "./entity.js";
+import { QUERY_METRICS_ROUTE, LEGACY_MEMBER_NAME, ENTITY_ID, GENERATED_ACTIONS, GENERATED_UPSERT_PREFIX, HISTORY_SUFFIX, MCP_METRIC_TOOLS, MCP_READ_TOOLS, MCP_TOOL_NAME_MAX_LENGTH, MEMBER_ROLE, FEEDBACK_REPORTER_ROLE, mcpToolName, RESERVED_ENTITY_NAMES, RESERVED_MEMBER_NAMES, RESERVED_RELATIONSHIP_NAMES, SNAKE_CASE_NAME, SYSTEM_PROPERTIES, isSystemProperty, toCamelCase, } from "./names.js";
+import { REFERENCE_ANNOTATION, propertyDefinition, propertyOptionNames, unknownPropertyOptions, referenceTarget, } from "./property.js";
+import { generatedActionPermissions, grants, isAllowed, normalizePermission, parsePermission, parseWorkflowPermission, permissionOf, READ_VERB, rolesGranting, USER_MEMBER_VERBS, WILDCARD, wildcardEntityCovers, } from "./permissions.js";
+import { ON_DELETE, isRelationship } from "./relationship.js";
+import { isRole, member, role } from "./role.js";
+import { CHANNEL_PROVIDERS, DEFAULT_SIGN_IN_POLICY, isSignInPolicy, } from "./sign-in.js";
+import { emailOptions } from "./emails.js";
+import { AgentChat } from "./agent-chat.js";
+import { APP_FEEDBACK_ENTITIES } from "./app-feedback.js";
+import { feedbackOptions, feedbackRoles, checkFeedbackResponders, } from "./feedback-config.js";
+import { User } from "./user.js";
+import { UserIdentity } from "./user-identity.js";
+import { authoringToWire } from "./authoring.js";
+import { nameToWire } from "./authoring-names.js";
+import { buildManifest, canonicalJson, } from "./manifest.js";
+import { MAX_ME_HOPS, mePathOf } from "./me.js";
+import { entityQuerySchemas, findEntityManifest, queryFields, queryLinks, } from "./query.js";
+import { EARLIER_QUERY_METRICS_ROUTE, earlierNamesOf } from "./legacy.js";
+import { resolveModelMetrics } from "./model-metrics.js";
+import { cronNeverFires, cronProblem, isAsyncFunction, isWorkflow, isWorkflowTrigger, MAX_ACTION_TRIGGERS, MAX_WORKFLOWS, } from "./workflow.js";
+import { MAX_WEBHOOK_HEADERS, MAX_WEBHOOKS, WEBHOOK_SIGNATURE_SCHEMES, webhookDelivery, webhookHeaderProblem, WORKSPACE_SECRET_NAME, } from "./webhooks.js";
+import { actionInputToWire } from "./authoring-input.js";
+import { validate } from "./runtime/validation.js";
+const GENERATED_UPSERT = new RegExp(`^${GENERATED_UPSERT_PREFIX}`);
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isBlank(value) {
+    return typeof value !== "string" || value.trim().length === 0;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Resolves an ontology definition and checks it. It never throws: every problem, including a thunk
+ * that throws, becomes a diagnostic.
+ */
+export function analyze(config, options = {}) {
+    const diagnostics = [];
+    const report = (code, path, message, severity = "error") => {
+        diagnostics.push({ severity, code, path, message });
+    };
+    const original = config;
+    const feedbackSetting = feedbackOptions(config.feedback, report);
+    const normalized = authoringToWire(config, [
+        options.user ?? User,
+        AgentChat,
+        UserIdentity,
+        ...(feedbackSetting !== false ? APP_FEEDBACK_ENTITIES : []),
+    ], report);
+    config = normalized.config;
+    reportEarlierNames(original, report);
+    let entities = collectEntities(config, normalized.builtIns, report);
+    const declaredRoles = collectRoles(config, report);
+    if (config.hooks !== undefined &&
+        (!isPlainObject(config.hooks) ||
+            Object.keys(config.hooks).some((key) => key !== "role") ||
+            typeof config.hooks.role !== "string" ||
+            nameToWire(config.hooks.role) === FEEDBACK_REPORTER_ROLE ||
+            !declaredRoles.some((candidate) => candidate.name === nameToWire(config.hooks.role)))) {
+        report("invalid-permission", "hooks.role", "hooks.role must name a declared ontology role.");
+    }
+    const signIn = signInOptions(config, report);
+    const discovery = config.discovery;
+    if (discovery !== undefined &&
+        (!isPlainObject(discovery) ||
+            Object.keys(discovery).some((key) => key !== "model") ||
+            typeof discovery.model !== "string" ||
+            !/^[a-z0-9][a-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(discovery.model))) {
+        report("invalid-discovery", "discovery", 'discovery takes { model: "<provider>/<model>" }, a decision model on AI Gateway such as ' +
+            '"typesafe-ai/jev-1.14.0".');
+    }
+    const emails = emailOptions(config.emails, report, (name, path) => camelCaseName(name, path, "agreementReview", "Email", report));
+    const connections = collectConnections(config, report);
+    const entitiesByName = new Map();
+    for (const candidate of entities) {
+        if (!entitiesByName.has(candidate.name)) {
+            entitiesByName.set(candidate.name, candidate);
+        }
+    }
+    let scope = {
+        report,
+        builtIns: new Set(normalized.builtIns.map((candidate) => candidate.definition)),
+        entitiesByName,
+        definitions: new Set(entities.map((candidate) => candidate.definition)),
+        entityProperties: new Set([...entities, ...(original.entities ?? []).filter(isEntity)].flatMap((candidate) => Object.values(candidate.definition.properties ?? {}))),
+        connections: new Set(connections.map((candidate) => candidate.key)),
+    };
+    // Resolve authored properties first. The feedback blob must never enable itself.
+    const properties = new Map(entities
+        .filter((candidate) => !APP_FEEDBACK_ENTITIES.some((feedback) => feedback.name === candidate.name))
+        .map((candidate) => [candidate, resolveProperties(candidate, scope)]));
+    const hasOtherBlob = [...properties.values()].some((values) => values.some((property) => property.definition.type === "blob"));
+    const files = feedbackSetting !== false &&
+        (feedbackSetting === true ||
+            feedbackSetting.files === true ||
+            (feedbackSetting.files === undefined && hasOtherBlob));
+    if (!files && feedbackSetting !== false) {
+        const file = normalized.builtIns.find((candidate) => candidate.name === "app_feedback_file");
+        entities = entities.filter((candidate) => candidate !== file);
+        entitiesByName.delete("app_feedback_file");
+        scope = {
+            ...scope,
+            builtIns: new Set(normalized.builtIns
+                .filter((candidate) => candidate !== file)
+                .map((candidate) => candidate.definition)),
+            definitions: new Set(entities.map((candidate) => candidate.definition)),
+        };
+    }
+    const { feedback, roles } = feedbackRoles(feedbackSetting, files, declaredRoles, report);
+    // Resolve authored entities before the optional feedback entities, preserving their ordering.
+    const isFeedback = (candidate) => APP_FEEDBACK_ENTITIES.some((feedback) => feedback.name === candidate.name);
+    let resolved = [
+        ...entities
+            .filter((candidate) => !isFeedback(candidate))
+            .map((candidate) => resolveEntity(candidate, scope, properties.get(candidate))),
+        ...entities.filter(isFeedback).map((candidate) => resolveEntity(candidate, scope)),
+    ];
+    let chat;
+    if (config.chat !== undefined) {
+        if (!isPlainObject(config.chat) ||
+            Object.keys(config.chat).some((key) => key !== "telegram" && key !== "attribution") ||
+            (config.chat.telegram !== undefined &&
+                (!isPlainObject(config.chat.telegram) ||
+                    Object.keys(config.chat.telegram).some((key) => key !== "connection") ||
+                    !isConnection(config.chat.telegram.connection)))) {
+            report("invalid-connection", "chat", "chat.telegram.connection must reference a declared connection handle.");
+        }
+        else if (config.chat.telegram !== undefined) {
+            const handle = config.chat.telegram.connection;
+            if (!(config.connections ?? []).includes(handle)) {
+                report("invalid-connection", "chat.telegram.connection", "The chat provider connection must be listed in connections.");
+            }
+            else {
+                chat = {
+                    telegram: { connection: handle.key },
+                    ...(config.chat.attribution === undefined
+                        ? {}
+                        : { attribution: config.chat.attribution }),
+                };
+                resolved = resolved.map((entity) => entity.name !== "agent_chat"
+                    ? entity
+                    : {
+                        ...entity,
+                        actions: entity.actions.map((candidate) => candidate.name !== "post_message"
+                            ? candidate
+                            : {
+                                ...candidate,
+                                connections: [handle.key],
+                                action: { ...candidate.action, connections: [handle] },
+                            }),
+                    });
+            }
+        }
+    }
+    const attribution = config.chat?.attribution;
+    if (attribution !== undefined &&
+        (!isPlainObject(attribution) ||
+            Object.keys(attribution).some((key) => key !== "template" && key !== "separator") ||
+            (attribution.template !== undefined &&
+                (typeof attribution.template !== "string" ||
+                    attribution.template.length > 512 ||
+                    !attribution.template.includes("{name}"))) ||
+            (attribution.separator !== undefined &&
+                (typeof attribution.separator !== "string" || attribution.separator.length > 100)))) {
+        report("invalid-connection", "chat.attribution", "Attribution requires a template containing {name} (at most 512 characters) " +
+            "and a separator of at most 100 characters.");
+    }
+    checkEntityIdentities(resolved, report);
+    checkMemberNames(resolved, report);
+    checkToolNames(resolved, report);
+    checkWarehouseSource(resolved, report);
+    const metrics = resolveModelMetrics({ metrics: config.metrics, entities: resolved, report });
+    const workflows = resolveWorkflows({
+        workflows: original.workflows,
+        entities: resolved,
+        roles,
+        scope,
+        checkGrants: options.checkPermissions !== false,
+    });
+    checkConnectionsUsed(resolved, connections, config.connections ?? [], workflows, report);
+    if (options.checkPermissions !== false) {
+        // Validate authored grants before augmentation can replace a scoped grant with an unscoped
+        // builder grant. Invalid authored scopes must remain errors; generated redundancy needs no warning.
+        checkPermissions(resolved, roles, workflows, report, [
+            ...declaredRoles,
+            ...roles.filter((candidate) => candidate.name === FEEDBACK_REPORTER_ROLE),
+        ]);
+        checkOpenWarehouseReads({ entities: resolved, roles, signIn, report });
+        checkOpenChannels({ config, entities: resolved, roles, signIn, report });
+        checkNewUserAction({ entities: resolved, roles, signIn, report });
+        if (feedback.enabled) {
+            checkFeedbackResponders(roles, report);
+        }
+        if (Object.values(signIn.channels ?? {}).includes("open") &&
+            options.agentConfig !== undefined) {
+            const contact = options.agentConfig.firstContact;
+            const hasNotice = isPlainObject(contact) &&
+                isPlainObject(contact.notice) &&
+                Object.values(contact.notice).some((notice) => typeof notice === "string" && notice.trim().length > 0);
+            const limits = options.agentConfig.limits;
+            const hasLimits = isPlainObject(limits) && Object.keys(limits).length > 0;
+            for (const [key, present] of [
+                ["firstContact.notice", hasNotice],
+                ["limits", hasLimits],
+            ]) {
+                if (!present) {
+                    report("invalid-sign-in", `agent.${key}`, `Open channels have no agent ${key} configuration.`, "warning");
+                }
+            }
+        }
+    }
+    return {
+        feedback,
+        entities: resolved,
+        roles,
+        signIn,
+        emails,
+        connections,
+        metrics,
+        workflows,
+        diagnostics,
+        ...(chat === undefined ? {} : { chat }),
+    };
+}
+/**
+ * Warns where workspace code declares a field by the name an earlier SDK gave it, naming the current
+ * one, so that authors move to it while the earlier name is still accepted.
+ */
+function reportEarlierNames(config, report) {
+    const declared = config.entities;
+    // Where each definition's fields are: an entity listed before and after `.actions(…)` shares one.
+    const paths = new Map([[config, ""]]);
+    for (const candidate of Array.isArray(declared) ? declared : []) {
+        if (isEntity(candidate) && !paths.has(candidate.definition)) {
+            paths.set(candidate.definition, `${candidate.name}.`);
+        }
+    }
+    for (const [definition, path] of paths) {
+        for (const { earlier, current } of earlierNamesOf(definition)) {
+            report("earlier-name", `${path}${current}`, `${earlier} is the deprecated earlier name of ${current}; rename it to ${current}.`, "warning");
+        }
+    }
+}
+/** The wire form of a camelCase declaration name, reporting a name that cannot round-trip. */
+function camelCaseName(name, path, example, kind, report) {
+    if (typeof name !== "string" || !/^[a-z][a-zA-Z0-9]*$/.test(name)) {
+        report("invalid-name", path, `${kind} names are lower camelCase identifiers, for example ${example}.`);
+        return undefined;
+    }
+    const wire = nameToWire(name);
+    if (toCamelCase(wire) !== name || !SNAKE_CASE_NAME.test(wire)) {
+        report("invalid-name", path, `Use lower camelCase ${toCamelCase(wire)} so the TypeScript and wire names round-trip.`);
+        return undefined;
+    }
+    return wire;
+}
+/** An input as JSON Schema (draft 2020-12), as the manifest describes action inputs. */
+function inputJsonSchema(input) {
+    const document = Schema.toJsonSchemaDocument(input, {
+        includeAnnotationKey: (key) => key === REFERENCE_ANNOTATION || key === BLOB_UPLOAD_ANNOTATION,
+        onExcessProperty: "error",
+    });
+    const schema = document.schema;
+    return Object.keys(document.definitions).length === 0
+        ? schema
+        : { ...schema, $defs: document.definitions };
+}
+/** The input of a workflow that declares none: exactly `{}`. */
+export const NO_INPUT = Schema.Record(Schema.String, Schema.Never);
+/** A workflow's input schema, `{}` when it declares none, or a message when it is not a struct. */
+function workflowInputSchema(input) {
+    if (input === undefined) {
+        return NO_INPUT;
+    }
+    if (!Schema.isSchema(input) || Schema.toEncoded(input).ast._tag !== "Objects") {
+        return "must be a Schema.Struct of the workflow's input.";
+    }
+    return input;
+}
+/**
+ * Whether `member`'s and the role's permissions together let the workflow's runs do anything:
+ * create, change or delete records of some entity, or run some action. Reads alone do not count.
+ */
+function grantsSomeAction(entities, permissions) {
+    const holder = { permissions };
+    return entities.some((entity) => entity.actions.some((candidate) => isAllowed(candidate.permission, holder)) ||
+        Object.entries(entity.permissions).some(([verb, permission]) => verb !== READ_VERB && permission !== undefined && isAllowed(permission, holder)));
+}
+/**
+ * Checks the workflows and resolves them to their manifest form: wire names, the input as JSON
+ * Schema, the connections' keys, and each trigger's input decoded with the workflow's input and
+ * stored in its wire form. A workflow runs as a declared role other than `member`.
+ */
+function resolveWorkflows(input) {
+    const { entities, roles, scope } = input;
+    const { report } = scope;
+    if (input.workflows === undefined) {
+        return [];
+    }
+    if (!Array.isArray(input.workflows)) {
+        report("invalid-workflow", "workflows", "workflows is a list of workflow(name, { … }).");
+        return [];
+    }
+    if (input.workflows.length > MAX_WORKFLOWS) {
+        report("invalid-workflow", "workflows", `An ontology may declare at most ${MAX_WORKFLOWS} workflows; it declares ` +
+            `${input.workflows.length}.`);
+    }
+    const memberPermissions = roles.find((candidate) => candidate.name === MEMBER_ROLE)?.permissions;
+    const names = new Set();
+    const resolved = [];
+    input.workflows.forEach((candidate, index) => {
+        if (!isWorkflow(candidate)) {
+            report("invalid-workflow", `workflows[${index}]`, "is not a workflow; declare workflows with workflow(name, { description, role, input, " +
+                "run, triggers }).");
+            return;
+        }
+        const path = `workflows.${String(candidate.name)}`;
+        const name = camelCaseName(candidate.name, path, "remindStaleLeads", "workflow", report);
+        let valid = name !== undefined;
+        if (name !== undefined) {
+            if (names.has(name)) {
+                report("duplicate-name", path, `workflow "${name}" is declared twice.`);
+                valid = false;
+            }
+            names.add(name);
+        }
+        if (isBlank(candidate.description)) {
+            report("missing-description", path, "every workflow needs a description.");
+            valid = false;
+        }
+        if (typeof candidate.run !== "function") {
+            report("workflow_run_missing", `${path}.run`, 'run is the workflow\'s "use workflow" function, such as run: remindStaleLeads.');
+            valid = false;
+        }
+        const role = typeof candidate.role === "string" ? nameToWire(candidate.role) : undefined;
+        const declared = roles.find((existing) => existing.name === role);
+        if (role === FEEDBACK_REPORTER_ROLE) {
+            report("workflow_role_unknown", `${path}.role`, "feedback_reporter is implicit human authority and cannot be a workflow role.");
+            valid = false;
+        }
+        else if (role === MEMBER_ROLE) {
+            report("workflow_role_is_member", `${path}.role`, "a workflow runs as a declared role of its own; its runs hold member's permissions " +
+                "anyway, so name the role that adds what the workflow does.");
+            valid = false;
+        }
+        else if (declared === undefined) {
+            report("workflow_role_unknown", `${path}.role`, `${JSON.stringify(candidate.role) ?? "undefined"} is not a declared role; a workflow ` +
+                "runs as one of the ontology's roles, other than member.");
+            valid = false;
+        }
+        else if (Array.isArray(declared.permissions) && declared.permissions.includes("*:*")) {
+            report("workflow_role_wildcard", `${path}.role`, `${declared.name} grants *:*, everything now and later; a workflow runs as a role that ` +
+                "names what it does.");
+            valid = false;
+        }
+        else if (input.checkGrants &&
+            !grantsSomeAction(entities, [
+                ...(Array.isArray(memberPermissions) ? memberPermissions : []),
+                ...(Array.isArray(declared.permissions) ? declared.permissions : []),
+            ])) {
+            report("workflow_role_grants_nothing", `${path}.role`, `${declared.name}, with member's permissions, grants no action, so the workflow can only ` +
+                "read; add the actions it runs to the role's permissions.", "warning");
+        }
+        if (input.checkGrants &&
+            declared !== undefined &&
+            role !== MEMBER_ROLE &&
+            (declared.scopes ?? []).length > 0) {
+            const scoped = [...new Set((declared.scopes ?? []).map((scope) => scope.permission))];
+            report("workflow_role_scoped", `${path}.role`, `${declared.name} scopes ${scoped.join(", ")}; bare me is the workflow service user's ID. ` +
+                "Paths from me require relationships of that service user; verify the scope matches the intended records.", "warning");
+        }
+        const schema = workflowInputSchema(candidate.input);
+        if (typeof schema !== "string" && "fields" in schema) {
+            for (const [field, value] of Object.entries(schema.fields)) {
+                checkPropertyOptions(`${path}.input.${field}`, value, report);
+            }
+        }
+        let wire;
+        let jsonSchema;
+        if (typeof schema === "string") {
+            report("workflow_input_invalid", `${path}.input`, schema);
+            valid = false;
+        }
+        else {
+            try {
+                wire = actionInputToWire(schema);
+                // A workflow without input takes exactly `{}`.
+                jsonSchema =
+                    candidate.input === undefined
+                        ? { type: "object", properties: {}, additionalProperties: false }
+                        : inputJsonSchema(wire);
+            }
+            catch (error) {
+                report("workflow_input_invalid", `${path}.input`, `has no JSON Schema form: ${errorMessage(error)}`);
+                valid = false;
+            }
+        }
+        const connections = workflowConnections(path, candidate.connections, scope);
+        const triggers = [];
+        const triggerNames = new Set();
+        if (!Array.isArray(candidate.triggers)) {
+            report("invalid-workflow", `${path}.triggers`, "triggers is a list of cron(name, …), after(name, …) and webhook(name, …).");
+            valid = false;
+        }
+        else {
+            candidate.triggers.forEach((trigger, position) => {
+                if (!isWorkflowTrigger(trigger) ||
+                    (trigger.kind !== "cron" && trigger.kind !== "action" && trigger.kind !== "webhook")) {
+                    report("invalid-workflow", `${path}.triggers[${position}]`, "is not a trigger; declare triggers with cron(name, expression, { description }), " +
+                        "after(name, target, { description }) or webhook(name, { description }).");
+                    valid = false;
+                    return;
+                }
+                const at = `${path}.triggers.${String(trigger.name)}`;
+                const example = trigger.kind === "cron"
+                    ? "weekdayMorning"
+                    : trigger.kind === "action"
+                        ? "qualified"
+                        : "stripe";
+                const triggerName = camelCaseName(trigger.name, at, example, "trigger", report);
+                if (triggerName === undefined) {
+                    valid = false;
+                }
+                else if (triggerNames.has(triggerName)) {
+                    report("duplicate-name", at, `the trigger ${String(trigger.name)} of ${String(candidate.name)} is declared twice.`);
+                    valid = false;
+                }
+                else {
+                    triggerNames.add(triggerName);
+                }
+                if (isBlank(trigger.description)) {
+                    report("missing-description", at, "every trigger needs a description.");
+                    valid = false;
+                }
+                const resolvedTrigger = trigger.kind === "cron"
+                    ? resolveCronTrigger(trigger, at, schema, wire, report)
+                    : trigger.kind === "action"
+                        ? resolveActionTrigger(trigger, at, entities, schema, wire, report)
+                        : resolveWebhookTrigger(trigger, at, report);
+                if (resolvedTrigger === undefined) {
+                    valid = false;
+                }
+                else if (triggerName !== undefined && !isBlank(trigger.description)) {
+                    triggers.push({ ...resolvedTrigger, name: triggerName });
+                }
+            });
+        }
+        const kinds = new Set((Array.isArray(candidate.triggers) ? candidate.triggers : [])
+            .filter(isWorkflowTrigger)
+            .map((trigger) => trigger.kind));
+        if (kinds.has("webhook")) {
+            if (kinds.size > 1) {
+                report("workflow_webhook_mixed_triggers", `${path}.triggers`, "a workflow that a webhook starts takes a delivery as its input, so it has only webhook " +
+                    "triggers; start other work from a second workflow.");
+                valid = false;
+            }
+            if (jsonSchema !== undefined &&
+                canonicalJson(jsonSchema) !== canonicalJson(webhookDeliveryJsonSchema())) {
+                report("workflow_webhook_input_invalid", `${path}.input`, "a workflow that a webhook starts takes one delivery: set input: webhookDelivery, from " +
+                    "@segmentstream/ontology/workflows.");
+                valid = false;
+            }
+        }
+        if (valid &&
+            name !== undefined &&
+            declared !== undefined &&
+            jsonSchema !== undefined &&
+            connections !== undefined) {
+            resolved.push({
+                name,
+                description: candidate.description,
+                role: declared.name,
+                input: jsonSchema,
+                connections,
+                triggers,
+            });
+        }
+    });
+    const actionTriggers = input.workflows
+        .filter(isWorkflow)
+        .flatMap((candidate) => (Array.isArray(candidate.triggers) ? candidate.triggers : []))
+        .filter((trigger) => isWorkflowTrigger(trigger) && trigger.kind === "action").length;
+    if (actionTriggers > MAX_ACTION_TRIGGERS) {
+        report("workflow_trigger_limit_exceeded", "workflows", `An ontology may declare at most ${MAX_ACTION_TRIGGERS} action triggers; it declares ` +
+            `${actionTriggers}.`);
+    }
+    // A webhook's wire name is its URL, so it is unique across the ontology, not only its workflow.
+    const webhooks = new Map();
+    for (const candidate of input.workflows.filter(isWorkflow)) {
+        for (const trigger of Array.isArray(candidate.triggers) ? candidate.triggers : []) {
+            if (!isWorkflowTrigger(trigger) || trigger.kind !== "webhook") {
+                continue;
+            }
+            if (typeof trigger.name !== "string") {
+                continue;
+            }
+            const wire = nameToWire(trigger.name);
+            const owner = webhooks.get(wire);
+            if (owner !== undefined) {
+                report("workflow_webhook_duplicate", `workflows.${String(candidate.name)}.triggers.${trigger.name}`, `the webhook ${trigger.name} is also declared on ${owner}; a webhook's name is its URL, ` +
+                    `/api/webhooks/${wire}, so it is unique across the ontology.`);
+            }
+            else {
+                webhooks.set(wire, String(candidate.name));
+            }
+        }
+    }
+    if (webhooks.size > MAX_WEBHOOKS) {
+        report("workflow_webhook_limit_exceeded", "workflows", `An ontology may declare at most ${MAX_WEBHOOKS} webhooks; it declares ${webhooks.size}.`);
+    }
+    return resolved;
+}
+let deliveryJsonSchema;
+/**
+ * The JSON Schema of `webhookDelivery`, the input every webhook-started workflow declares, as the
+ * manifest writes it. Publication compares a workflow's input with it.
+ */
+export function webhookDeliveryJsonSchema() {
+    deliveryJsonSchema ??= inputJsonSchema(actionInputToWire(webhookDelivery));
+    return deliveryJsonSchema;
+}
+/**
+ * A webhook trigger's manifest form, without its name: the signature when declared and the headers
+ * when listed. `undefined` after reporting a problem.
+ */
+function resolveWebhookTrigger(trigger, at, report) {
+    let valid = true;
+    const signature = trigger.signature;
+    if (signature !== undefined) {
+        const scheme = typeof signature === "object" && signature !== null
+            ? signature.scheme
+            : undefined;
+        const secret = typeof signature === "object" && signature !== null
+            ? signature.secret
+            : undefined;
+        if (!WEBHOOK_SIGNATURE_SCHEMES.includes(scheme)) {
+            report("workflow_webhook_signature_invalid", `${at}.signature.scheme`, `${JSON.stringify(scheme) ?? "undefined"} is not a signature scheme; use one of ` +
+                `${WEBHOOK_SIGNATURE_SCHEMES.join(", ")}, or omit signature for a provider that signs ` +
+                "nothing.");
+            valid = false;
+        }
+        if (typeof secret !== "string" || !WORKSPACE_SECRET_NAME.test(secret)) {
+            report("workflow_webhook_signature_invalid", `${at}.signature.secret`, `${JSON.stringify(secret) ?? "undefined"} is not a workspace secret name; name the ` +
+                "secret that holds the provider's signing secret, such as stripe-webhook-signing-secret.");
+            valid = false;
+        }
+    }
+    const verification = trigger.verification;
+    if (verification !== undefined) {
+        const declared = verification;
+        if (typeof declared !== "object" ||
+            declared === null ||
+            declared.scheme !== "meta" ||
+            typeof declared.verifyToken !== "string" ||
+            !WORKSPACE_SECRET_NAME.test(declared.verifyToken) ||
+            trigger.signature?.scheme !== "meta") {
+            report("workflow_webhook_verification_invalid", `${at}.verification`, 'Use { scheme: "meta", verifyToken: <workspace secret name> } with a Meta signature.');
+            valid = false;
+        }
+    }
+    const headers = trigger.headers;
+    if (!Array.isArray(headers) || headers.length > MAX_WEBHOOK_HEADERS) {
+        report("workflow_webhook_headers_invalid", `${at}.headers`, `headers is a list of at most ${MAX_WEBHOOK_HEADERS} lowercase header names.`);
+        valid = false;
+    }
+    else {
+        const seen = new Set();
+        for (const header of headers) {
+            const problem = webhookHeaderProblem(header);
+            if (problem !== undefined) {
+                report("workflow_webhook_headers_invalid", `${at}.headers`, problem);
+                valid = false;
+            }
+            else if (seen.has(header)) {
+                report("workflow_webhook_headers_invalid", `${at}.headers`, `${String(header)} is listed twice.`);
+                valid = false;
+            }
+            else {
+                seen.add(header);
+            }
+        }
+    }
+    if (!valid) {
+        return undefined;
+    }
+    const listed = trigger.headers;
+    return {
+        kind: "webhook",
+        name: trigger.name,
+        description: trigger.description,
+        ...(trigger.signature === undefined
+            ? {}
+            : { signature: { scheme: trigger.signature.scheme, secret: trigger.signature.secret } }),
+        ...(trigger.verification === undefined ? {} : { verification: { ...trigger.verification } }),
+        ...(listed.length === 0 ? {} : { headers: [...listed] }),
+    };
+}
+/**
+ * A cron trigger's manifest form, without its name: the expression normalized and the input in
+ * wire form. `undefined` after reporting a problem.
+ */
+function resolveCronTrigger(trigger, at, schema, wire, report) {
+    const problem = typeof trigger.cron === "string" ? cronProblem(trigger.cron) : "fields";
+    let valid = true;
+    if (problem !== undefined) {
+        report("workflow_cron_invalid", `${at}.cron`, `${JSON.stringify(trigger.cron) ?? "undefined"} is not a cron expression (${problem}): ` +
+            "write five fields in UTC with numbers, *, ranges, steps and lists, such as " +
+            "0 8 * * 1-5, and restrict at most one of day-of-month and day-of-week.");
+        valid = false;
+    }
+    if (problem === undefined && cronNeverFires(trigger.cron)) {
+        report("workflow_cron_never_fires", `${at}.cron`, `${trigger.cron} names no day that exists, such as the 31st of a 30-day month; it ` +
+            "never fires.", "warning");
+    }
+    const wireInput = typeof schema === "string" || wire === undefined
+        ? undefined
+        : workflowWireInput(schema, wire, trigger.input);
+    if (typeof wireInput === "string") {
+        report("workflow_input_invalid", `${at}.input`, wireInput);
+        return undefined;
+    }
+    // An input schema without a wire form is reported on the workflow, which is then left out.
+    if (!valid || wireInput === undefined) {
+        return undefined;
+    }
+    return {
+        kind: "cron",
+        name: trigger.name,
+        description: trigger.description,
+        cron: trigger.cron.trim().split(/\s+/).join(" "),
+        input: wireInput,
+    };
+}
+/**
+ * An action trigger's manifest form, without its name: the entity's and the action's wire names.
+ * The target must be a handle of a declared stored entity or of one of its actions; `when` and
+ * `input` must be synchronous functions; without `input`, the workflow's input must accept `{}`.
+ * `undefined` after reporting a problem.
+ */
+function resolveActionTrigger(trigger, at, entities, schema, wire, report) {
+    let valid = true;
+    const target = trigger.target;
+    const isActionHandle = typeof target === "function" &&
+        isAction(target) &&
+        typeof target.entity === "string";
+    if (!isActionHandle && !isEntity(target)) {
+        report("invalid-trigger", `${at}.target`, "the target is an action handle, such as Lead.actions.changeStatus, or an entity handle, " +
+            "such as Lead.");
+        return undefined;
+    }
+    const owner = entities.find((candidate) => candidate.name === trigger.entity);
+    if (owner === undefined || owner.entity.definition.source !== undefined) {
+        report("invalid-trigger", `${at}.target`, owner === undefined
+            ? `${JSON.stringify(trigger.entity)} is not an entity of this ontology; list it in ` +
+                "defineOntology({ entities })."
+            : `${owner.name} is warehouse-backed and has no actions; trigger on a stored entity.`);
+        valid = false;
+    }
+    else if (trigger.action !== undefined &&
+        !owner.actions.some((candidate) => candidate.name === trigger.action)) {
+        report("trigger_action_unknown", `${at}.target`, `${trigger.action} is not an action of ${owner.name}; name one of its declared actions, ` +
+            "or the entity for any of them.");
+        valid = false;
+    }
+    for (const key of ["when", "input"]) {
+        const fn = trigger[key];
+        if (fn === undefined) {
+            continue;
+        }
+        if (typeof fn !== "function") {
+            report("invalid-trigger", `${at}.${key}`, `${key} is a function of the event and the record, (event, { record, before, after }).`);
+            valid = false;
+        }
+        else if (isAsyncFunction(fn)) {
+            report("trigger_function_async", `${at}.${key}`, `${key} runs inside the action's transaction, so it is synchronous: drop async and ` +
+                "read only the event and the record; the workflow's steps read the rest.");
+            valid = false;
+        }
+    }
+    if (trigger.input === undefined && typeof schema !== "string" && wire !== undefined) {
+        const empty = workflowWireInput(schema, wire, undefined);
+        if (typeof empty === "string") {
+            report("workflow_input_invalid", `${at}.input`, `without input the trigger starts the workflow with {}, which ${empty}; map the event ` +
+                "to the workflow's input with input: (event, record) => ({ … }).");
+            valid = false;
+        }
+    }
+    return valid && owner !== undefined
+        ? {
+            kind: "action",
+            name: trigger.name,
+            description: trigger.description,
+            entity: owner.name,
+            ...(trigger.action === undefined ? {} : { action: trigger.action }),
+        }
+        : undefined;
+}
+/** The keys of the connections a workflow's steps call, each listed in `defineOntology`. */
+function workflowConnections(path, declared, scope) {
+    if (declared === undefined) {
+        return [];
+    }
+    if (!Array.isArray(declared)) {
+        scope.report("invalid-connection", `${path}.connections`, "connections is a list of connection(…) handles.");
+        return undefined;
+    }
+    const keys = [];
+    let valid = true;
+    declared.forEach((candidate, index) => {
+        const at = `${path}.connections[${index}]`;
+        if (!isConnection(candidate)) {
+            scope.report("invalid-connection", at, "is not a connection; declare it with connection(key, { … }).");
+            valid = false;
+        }
+        else if (!scope.connections.has(candidate.key)) {
+            scope.report("unknown-connection", at, `the connection ${String(candidate.key)} is not listed in defineOntology({ connections }).`);
+            valid = false;
+        }
+        else if (keys.includes(candidate.key)) {
+            scope.report("duplicate-name", at, `the connection ${candidate.key} is listed twice.`);
+            valid = false;
+        }
+        else {
+            keys.push(candidate.key);
+        }
+    });
+    return valid ? keys : undefined;
+}
+/**
+ * A trigger's input as the cron route sends it: decoded with the workflow's input schema as
+ * declared, then encoded with its wire form. A message when it does not decode.
+ */
+function workflowWireInput(authored, wire, value) {
+    if (value !== undefined && !isPlainObject(value)) {
+        return "a workflow's input is an object of its fields.";
+    }
+    const decoded = validate(authored, value === undefined ? {} : value);
+    if (!decoded.ok) {
+        return ("does not decode with the workflow's input: " +
+            decoded.issues
+                .map((issue) => `${issue.path.length > 0 ? issue.path.join(".") : "input"}: ${issue.message}`)
+                .join("; "));
+    }
+    const encoded = Schema.encodeUnknownResult(wire)(decoded.value);
+    if (Result.isFailure(encoded)) {
+        return `has no wire form: ${errorMessage(encoded.failure)}`;
+    }
+    return encoded.success;
+}
+/**
+ * The operations of a stored entity that become MCP tools, each with the path a problem is reported
+ * at: the reads, the generated actions and the authored actions.
+ */
+function toolOperations(candidate) {
+    const { permissions } = candidate;
+    const generated = [
+        ...["create", "update", "delete"].filter((verb) => permissions[verb] !== undefined),
+        ...(permissions.create !== undefined
+            ? candidate.properties
+                .filter(({ definition }) => definition.unique)
+                .map(({ name }) => `${GENERATED_UPSERT_PREFIX}${name}`)
+            : []),
+        ...(permissions.link !== undefined ? ["link", "unlink"] : []),
+        ...(candidate.builtIn && candidate.name === User.name ? USER_MEMBER_VERBS : []),
+    ];
+    return [
+        ...[...MCP_READ_TOOLS, ...generated].map((operation) => ({ operation, path: candidate.name })),
+        // An authored action with a generated action's name is already refused as a reserved name.
+        ...candidate.actions
+            .filter(({ name }) => !GENERATED_ACTIONS.includes(name) &&
+            !GENERATED_UPSERT.test(name) &&
+            !generated.includes(name))
+            .map(({ name }) => ({ operation: name, path: `${candidate.name}.actions.${name}` })),
+    ];
+}
+/**
+ * Every MCP tool needs a name of its own, at most 64 characters long. A tool's name joins the
+ * entity's and the operation's with an underscore, so entity `pilot` with an action `request_find`
+ * would take the name of entity `pilot_request`'s `find`.
+ */
+function checkToolNames(entities, report) {
+    const owners = new Map(MCP_METRIC_TOOLS.map((name) => [name, "the ontology's metric tools"]));
+    const seen = new Set();
+    for (const candidate of entities) {
+        // A second entity with the same name is already refused as a duplicate.
+        if (candidate.entity.definition.source !== undefined || seen.has(candidate.name)) {
+            continue;
+        }
+        seen.add(candidate.name);
+        for (const { operation, path } of toolOperations(candidate)) {
+            const name = mcpToolName(candidate.name, operation);
+            const owner = owners.get(name);
+            if (owner !== undefined) {
+                report("invalid-tool-name", path, `its MCP tool ${name} is already the tool of ${owner}; rename one of them.`);
+                continue;
+            }
+            owners.set(name, `${candidate.name}'s ${operation}`);
+            if (name.length > MCP_TOOL_NAME_MAX_LENGTH) {
+                report("invalid-tool-name", path, `its MCP tool ${name} is ${name.length} characters long; agents accept at most ` +
+                    `${MCP_TOOL_NAME_MAX_LENGTH}. Shorten the entity or the action name.`);
+            }
+        }
+    }
+}
+/** The handles `defineOntology({ connections })` lists, each with a valid key and a description. */
+function collectConnections(config, report) {
+    const declared = config.connections;
+    if (declared === undefined) {
+        return [];
+    }
+    if (!Array.isArray(declared)) {
+        report("invalid-connection", "connections", "connections is a list of connection(…) handles.");
+        return [];
+    }
+    const connections = [];
+    const keys = new Set();
+    declared.forEach((candidate, index) => {
+        const path = `connections[${index}]`;
+        if (!isConnection(candidate)) {
+            report("invalid-connection", path, "is not a connection; declare it with connection(key, { … }).");
+            return;
+        }
+        if (typeof candidate.key !== "string" || !CONNECTION_KEY.test(candidate.key)) {
+            report("invalid-connection", path, `${JSON.stringify(candidate.key)} is not a connection key: lowercase letters, digits and ` +
+                "underscores, starting with a letter, as connections/connections.py declares it.");
+            return;
+        }
+        if (keys.has(candidate.key)) {
+            report("duplicate-name", path, `the connection ${candidate.key} is listed twice.`);
+            return;
+        }
+        if (isBlank(candidate.description)) {
+            report("missing-description", path, `the connection ${candidate.key} needs a description of what the ontology uses it for.`);
+        }
+        keys.add(candidate.key);
+        connections.push({
+            key: candidate.key,
+            description: typeof candidate.description === "string" ? candidate.description : "",
+            delivers: candidate.delivers === true,
+            handle: candidate,
+        });
+    });
+    return connections;
+}
+/** A listed connection that no action calls is a leftover: it grants the deployment for nothing. */
+function checkConnectionsUsed(entities, connections, declared, workflows, report) {
+    const used = new Set([
+        ...entities.flatMap((entity) => entity.actions.flatMap((candidate) => candidate.connections)),
+        ...workflows.flatMap((candidate) => candidate.connections),
+    ]);
+    connections.forEach((candidate) => {
+        if (!used.has(candidate.key)) {
+            report("unused-connection", `connections[${declared.indexOf(candidate.handle)}]`, `no action or workflow calls the connection ${candidate.key}; list it in an action's ` +
+                "or a workflow's connections or remove it.");
+        }
+    });
+}
+/**
+ * The keys of an action's connections, each listed in `defineOntology({ connections })`, and the
+ * phases they require: `prepare` with connections and only with them, except for built-in actions,
+ * and `prepare` or `handler` always.
+ */
+function resolveActionConnections(path, action, scope, builtIn) {
+    const { report } = scope;
+    const declared = action.connections;
+    const keys = [];
+    if (!Array.isArray(declared)) {
+        report("invalid-connection", `${path}.connections`, "connections is a list of connection(…) handles.");
+    }
+    else {
+        declared.forEach((candidate, index) => {
+            const at = `${path}.connections[${index}]`;
+            if (!isConnection(candidate)) {
+                report("invalid-connection", at, "is not a connection; declare it with connection(key, { … }).");
+            }
+            else if (!scope.connections.has(candidate.key)) {
+                report("unknown-connection", at, `the connection ${String(candidate.key)} is not listed in defineOntology({ connections }).`);
+            }
+            else if (keys.includes(candidate.key)) {
+                report("duplicate-name", at, `the connection ${candidate.key} is listed twice.`);
+            }
+            else {
+                keys.push(candidate.key);
+            }
+        });
+    }
+    const hasPrepare = typeof action.prepare === "function";
+    const hasHandler = typeof action.handler === "function";
+    if (Array.isArray(declared) && declared.length > 0 && !hasPrepare) {
+        report("invalid-prepare", `${path}.prepare`, "an action with connections calls them in prepare, which runs before the transaction.");
+    }
+    // A built-in action's prepare reaches the platform, such as the workspace's agent, instead.
+    if (hasPrepare &&
+        !builtIn &&
+        Array.isArray(declared) &&
+        declared.length === 0 &&
+        action.files === undefined) {
+        report("invalid-prepare", `${path}.prepare`, "prepare requires connections or file access; declare files: [] for file reads.");
+    }
+    if (!hasPrepare && !hasHandler) {
+        report("invalid-action", `${path}.handler`, "every action needs a handler.");
+    }
+    return keys;
+}
+function collectEntities(config, builtIns, report) {
+    const entities = [...builtIns];
+    (config.entities ?? []).forEach((candidate, index) => {
+        if (!isEntity(candidate)) {
+            report("invalid-entity", `entities[${index}]`, "is not an entity; declare entities with entity(name, { … }).");
+            return;
+        }
+        const listed = entities.findIndex((existing) => existing.definition === candidate.definition);
+        if (listed === -1) {
+            entities.push(candidate);
+        }
+        else if (isDraft(entities[listed]) && !isDraft(candidate)) {
+            // The same entity, listed before and after `.actions(…)`: keep the form with actions.
+            entities[listed] = candidate;
+        }
+    });
+    return entities;
+}
+// @legacy ontology.removed-allow-option
+const REMOVED_ALLOW = "allow was removed: each action requires one permission (its permission option, by default " +
+    "<entity>:<action name>), and roles grant permissions in their permissions list.";
+/** The built-in `member` role with the ontology's member permissions. */
+function memberRole(config, report) {
+    const options = config.member;
+    if (options === undefined) {
+        return member;
+    }
+    if (!isPlainObject(options)) {
+        report("missing-permissions", "member", 'member takes { permissions: ["*:read", …] }.');
+        return member;
+    }
+    if ("allow" in options) {
+        report("removed-allow", "member.allow", REMOVED_ALLOW);
+    }
+    return role(MEMBER_ROLE, {
+        description: member.description,
+        permissions: options.permissions,
+    });
+}
+/** The sign-in policy, which decides whether a stranger who signs in becomes a member. */
+function signInOptions(config, report) {
+    const options = config.signIn;
+    const fallback = { policy: DEFAULT_SIGN_IN_POLICY };
+    if (options === undefined) {
+        return fallback;
+    }
+    if (!isPlainObject(options)) {
+        report("invalid-sign-in", "signIn", 'signIn takes { policy: "invited" } or { policy: "open" }.');
+        return fallback;
+    }
+    for (const key of Object.keys(options)) {
+        if (!["policy", "channels", "onNewUser", "browser", "codeLink"].includes(key)) {
+            report("invalid-sign-in", `signIn.${key}`, `Unknown signIn key: ${key}.`);
+        }
+    }
+    if (!isSignInPolicy(options.policy)) {
+        report("invalid-sign-in", "signIn.policy", `${JSON.stringify(options.policy) ?? "undefined"} is not a sign-in policy; use "invited" ` +
+            '(only people invited as members) or "open" (anyone who signs in becomes a member).');
+        return fallback;
+    }
+    const channels = {};
+    if (options.channels !== undefined) {
+        if (!isPlainObject(options.channels)) {
+            report("invalid-sign-in", "signIn.channels", "channels must map providers to admission policies.");
+        }
+        else {
+            for (const [provider, policy] of Object.entries(options.channels)) {
+                if (!CHANNEL_PROVIDERS.includes(provider)) {
+                    report("invalid-sign-in", `signIn.channels.${provider}`, `Unsupported channel provider: ${provider}.`);
+                }
+                else if (isPlainObject(policy)) {
+                    report("invalid-sign-in", `signIn.channels.${provider}`, "The object form is reserved; use a policy string.");
+                }
+                else if (!isSignInPolicy(policy)) {
+                    report("invalid-sign-in", `signIn.channels.${provider}`, 'Use "open" or "invited".');
+                }
+                else {
+                    const adapters = config.chat;
+                    if (adapters?.[provider] === undefined) {
+                        report("invalid-sign-in", `signIn.channels.${provider}`, `Configure a matching chat.${provider} adapter.`);
+                    }
+                    channels[provider] = policy;
+                }
+            }
+        }
+    }
+    const browserError = options.browser === undefined ? undefined : validateBrowserSignIn(options.browser);
+    if (browserError) {
+        report("invalid-sign-in", "signIn.browser", browserError);
+    }
+    const hook = options.onNewUser;
+    if (hook !== undefined &&
+        (typeof hook !== "string" || !parsePermission(hook) || hook.includes("*"))) {
+        report("invalid-sign-in", "signIn.onNewUser", "Use an action name: <entity>:<action>.");
+    }
+    const codeLink = options.codeLink;
+    if (codeLink !== undefined && typeof codeLink !== "boolean") {
+        report("invalid-sign-in", "signIn.codeLink", "codeLink takes true or false.");
+    }
+    return {
+        policy: options.policy,
+        ...(options.browser === undefined || browserError
+            ? {}
+            : { browser: options.browser }),
+        ...(Object.keys(channels).length > 0 ? { channels } : {}),
+        ...(typeof hook === "string" ? { onNewUser: hook } : {}),
+        ...(typeof codeLink === "boolean" ? { codeLink } : {}),
+    };
+}
+function collectRoles(config, report) {
+    const roles = [memberRole(config, report)];
+    (config.roles ?? []).forEach((candidate, index) => {
+        if (!isRole(candidate)) {
+            report("invalid-role", `roles[${index}]`, "is not a role; declare roles with role(name, { description, permissions }).");
+            return;
+        }
+        // Listing the built-in role is harmless: its permissions come from defineOntology({ member }).
+        if (candidate === member || roles.includes(candidate)) {
+            return;
+        }
+        const path = `roles.${candidate.name}`;
+        if (candidate.name === MEMBER_ROLE || candidate.name === FEEDBACK_REPORTER_ROLE) {
+            report("reserved-name", path, `${candidate.name} is a reserved built-in role.`);
+            return;
+        }
+        if (roles.some((existing) => existing.name === candidate.name)) {
+            report("duplicate-name", path, `role "${candidate.name}" is declared twice.`);
+            return;
+        }
+        if (!SNAKE_CASE_NAME.test(candidate.name)) {
+            report("invalid-name", path, "role names are lowercase snake_case, for example sales_lead.");
+        }
+        if (isBlank(candidate.description)) {
+            report("missing-description", path, "every role needs a description.");
+        }
+        if ("allow" in candidate) {
+            report("removed-allow", `${path}.allow`, REMOVED_ALLOW);
+        }
+        roles.push(candidate);
+    });
+    return roles;
+}
+function resolveEntity(candidate, scope, resolvedProperties) {
+    const { report } = scope;
+    const { definition, name } = candidate;
+    if (!SNAKE_CASE_NAME.test(name)) {
+        report("invalid-name", name, "entity names are lowercase snake_case, for example pilot_request.");
+    }
+    else if (name.endsWith(HISTORY_SUFFIX)) {
+        report("reserved-name", name, `names ending in ${HISTORY_SUFFIX} are reserved for history tables.`);
+    }
+    else if (name === QUERY_METRICS_ROUTE || name === EARLIER_QUERY_METRICS_ROUTE) {
+        report("reserved-name", name, `/api/ontology/${name} answers metric queries across the ontology's entities; ` +
+            "choose another entity name.");
+    }
+    else if (RESERVED_ENTITY_NAMES.includes(name)) {
+        report("reserved-name", name, `/api/ontology/${name} is a route of the ontology service.`);
+    }
+    else if (APP_FEEDBACK_ENTITIES.some((feedback) => feedback.name === name) &&
+        !scope.builtIns.has(definition)) {
+        report("reserved-name", name, `${name} is the SDK's app feedback; configure feedback on defineOntology ` +
+            "instead of declaring or listing it.");
+    }
+    if (isBlank(definition.label) || isBlank(definition.plural)) {
+        report("missing-label", name, "every entity needs a label and a plural.");
+    }
+    if (isBlank(definition.description)) {
+        report("missing-description", name, "every entity needs a description.");
+    }
+    if (definition.guide !== undefined && !/^(?!\/)[^\s]*\.md$/.test(definition.guide)) {
+        report("invalid-guide", `${name}.guide`, "must be a relative path to a Markdown file, such as ./lead.md.");
+    }
+    checkWrites(name, definition, report);
+    const properties = resolvedProperties ?? resolveProperties(candidate, scope);
+    const relationships = resolveRelationships(candidate, scope);
+    if (isBlank(definition.title)) {
+        report("invalid-title", `${name}.title`, "every entity needs a title property that names its records.");
+    }
+    else if (!properties.some((property) => property.name === definition.title)) {
+        report("invalid-title", `${name}.title`, `"${definition.title}" is not a declared property of ${name}.`);
+    }
+    const builtIn = scope.builtIns.has(candidate.definition);
+    const writes = writesOf(candidate);
+    if (writes === "generated" && !builtIn && definition.source === undefined) {
+        checkGeneratedUpdate(name, properties, relationships, report);
+    }
+    return {
+        entity: candidate,
+        name,
+        builtIn,
+        properties,
+        relationships,
+        indexes: resolveIndexes(candidate, properties, relationships, scope),
+        actions: resolveActions(candidate, scope),
+        permissions: entityPermissions(name, builtIn || definition.source !== undefined, writes, relationships, scope),
+        writes,
+    };
+}
+/**
+ * Whether a `rel.many` to `target` keeps its generated `link` and `unlink`: not when the target
+ * declares `writes: "actions"`, whose links change only through authored actions on either side.
+ */
+function generatedLinkTarget(target, scope) {
+    const candidate = target === undefined ? undefined : scope.entitiesByName.get(target);
+    return candidate === undefined || writesOf(candidate) === "generated";
+}
+/** Who writes an entity's records: `"actions"` only when it declares it, as `check` accepts it. */
+function writesOf(candidate) {
+    return candidate.definition.writes === "actions" && candidate.definition.source === undefined
+        ? "actions"
+        : "generated";
+}
+function checkWrites(name, definition, report) {
+    const writes = definition.writes;
+    if (writes === undefined) {
+        return;
+    }
+    if (writes !== "generated" && writes !== "actions") {
+        report("invalid-writes", `${name}.writes`, 'writes is "generated", the default, or "actions", when only the entity\'s own actions ' +
+            "write its records.");
+    }
+    else if (definition.source !== undefined) {
+        report("invalid-writes", `${name}.writes`, "a warehouse-backed entity has no writes; remove writes.");
+    }
+}
+/**
+ * Warns when the generated `update` could change nothing: every property is `managed` and the
+ * entity holds no `rel.one` key or `rel.many` list to change. The tool is listed for every caller
+ * with `update` and does nothing; `writes: "actions"` removes it, with the other generated writes.
+ */
+function checkGeneratedUpdate(name, properties, relationships, report) {
+    const editable = properties.some((property) => property.definition.managed !== true);
+    const declared = relationships.some(({ relationship }) => !("on" in relationship && relationship.on !== undefined));
+    if (editable || declared) {
+        return;
+    }
+    report("generated-update-empty", `${name}.writes`, `every property of ${name} is managed and it declares no relationship, so its generated ` +
+        `update changes nothing. Declare writes: "actions" when only its actions write its records.`, "warning");
+}
+/**
+ * Reads need `<entity>:read`; each generated action needs the permission named after it. Built-in
+ * entities hold the platform's records: `agent_chat` has one generated action, `update`, for the
+ * properties members edit, and `user` the member actions of `USER_MEMBER_VERBS`, which are not
+ * listed here. An entity that declares `writes: "actions"` has only `read`. `link` and `unlink`
+ * exist with a `rel.many` whose two ends both keep their generated writes.
+ */
+function entityPermissions(name, builtIn, writes, relationships, scope) {
+    const read = permissionOf(name, READ_VERB);
+    if (builtIn) {
+        return name === AgentChat.name ? { read, update: permissionOf(name, "update") } : { read };
+    }
+    if (writes === "actions") {
+        return { read };
+    }
+    const many = relationships.some(({ relationship, target }) => relationship.cardinality === "many" && generatedLinkTarget(target, scope));
+    return {
+        read,
+        create: permissionOf(name, "create"),
+        update: permissionOf(name, "update"),
+        delete: permissionOf(name, "delete"),
+        ...(many ? { link: permissionOf(name, "link"), unlink: permissionOf(name, "unlink") } : {}),
+    };
+}
+function checkMemberName(kind, path, name, report) {
+    if (!SNAKE_CASE_NAME.test(name)) {
+        report("invalid-name", path, `${kind} names are lowercase snake_case, for example owned_leads.`);
+    }
+    else if (isSystemProperty(name)) {
+        report("reserved-name", path, `${name} is a system property of every entity.`);
+    }
+    else if (RESERVED_MEMBER_NAMES.includes(name)) {
+        report("reserved-name", path, `${name} is a combinator of the query language.`);
+    }
+    else if (kind !== "property" &&
+        RESERVED_RELATIONSHIP_NAMES.includes(name)) {
+        report("reserved-name", path, `${name} is the route of a record's history.`);
+    }
+}
+/** Reports the options a property constructor was given but does not take. */
+function checkPropertyOptions(path, schema, report) {
+    const unknown = unknownPropertyOptions(schema);
+    const definition = propertyDefinition(schema);
+    if (unknown.length > 0 && definition !== undefined) {
+        report("invalid-property", path, `p.${definition.type} does not take ${unknown.join(", ")}; it takes ` +
+            `${propertyOptionNames(definition.type).join(", ")}.`);
+    }
+}
+function resolveProperties(candidate, scope) {
+    const { report } = scope;
+    const entries = Object.entries(candidate.definition.properties ?? {});
+    const names = new Set(entries.map(([name]) => name));
+    const properties = [];
+    for (const [name, schema] of entries) {
+        const path = `${candidate.name}.properties.${name}`;
+        const originalDefinition = propertyDefinition(schema);
+        const definition = !Array.isArray(originalDefinition?.scope)
+            ? originalDefinition
+            : { ...originalDefinition, scope: originalDefinition.scope.map(nameToWire) };
+        checkMemberName("property", path, name, report);
+        checkPropertyOptions(path, schema, report);
+        if (definition === undefined) {
+            const hint = referenceTarget(schema) === undefined
+                ? "create properties with p.text(), p.select() and the other p constructors."
+                : "references are for action inputs; declare relationships with rel.one or rel.many.";
+            report("invalid-property", path, `is not a property; ${hint}`);
+            continue;
+        }
+        checkProperty(path, schema, definition, report);
+        if (definition.type === "list" &&
+            !(scope.builtIns.has(candidate.definition) && candidate.name === User.name)) {
+            report("invalid-property", path, "p.list is kept by the platform and only the built-in user has one, roles; " +
+                "declare a rel.many to another entity, or a p.json property, for several values.");
+        }
+        if (definition.renamedFrom !== undefined) {
+            // @legacy ontology.camelcase-member-names
+            checkRenamedFrom(path, name, definition.renamedFrom, names, LEGACY_MEMBER_NAME, report);
+        }
+        properties.push({ name, schema: schema, definition });
+    }
+    return properties;
+}
+function checkProperty(path, schema, definition, report) {
+    if (definition.type === "blob") {
+        if (definition.unique || "default" in definition) {
+            report("invalid-property", path, "Blob properties cannot be unique or have a default.");
+        }
+        if (!definition.accept?.length ||
+            definition.accept.some((type) => !isBlobAccept(type)) ||
+            new Set(definition.accept.map((type) => type.toLowerCase())).size !==
+                definition.accept.length ||
+            !Number.isInteger(definition.maxBytes) ||
+            definition.maxBytes < 1 ||
+            definition.maxBytes > MAX_BLOB_BYTES) {
+            report("invalid-constraint", path, "Use MIME types or ranges and a limit from 1 byte to 250 MiB.");
+        }
+    }
+    if (definition.type === "select") {
+        checkSelectOptions(path, definition, report);
+    }
+    if (definition.min !== undefined &&
+        definition.max !== undefined &&
+        definition.min > definition.max) {
+        report("invalid-constraint", path, `min (${definition.min}) is greater than max (${definition.max}).`);
+    }
+    if (definition.maxLength !== undefined &&
+        (!Number.isInteger(definition.maxLength) || definition.maxLength < 1)) {
+        report("invalid-constraint", path, "maxLength must be a positive integer.");
+    }
+    if ("default" in definition && !Schema.is(valueSchema(schema))(definition.default)) {
+        report("invalid-default", path, `the default ${JSON.stringify(definition.default)} is not a valid value.`);
+    }
+}
+function checkSelectOptions(path, definition, report) {
+    const options = definition.options ?? [];
+    const seen = new Set();
+    if (options.length === 0) {
+        report("invalid-options", path, "a select property needs at least one option.");
+    }
+    options.forEach((option, index) => {
+        const optionPath = `${path}.options[${index}]`;
+        if (!SNAKE_CASE_NAME.test(option.value)) {
+            report("invalid-options", optionPath, "option values must be lowercase snake_case.");
+        }
+        else if (seen.has(option.value)) {
+            report("invalid-options", optionPath, `the option value "${option.value}" is listed twice.`);
+        }
+        seen.add(option.value);
+        if (isBlank(option.description)) {
+            report("missing-description", optionPath, `option "${option.value}" needs a description: { value, label, description }.`);
+        }
+    });
+}
+/** The schema of a property's value, without the optional-key wrapper. */
+function valueSchema(schema) {
+    return "schema" in schema && Schema.isSchema(schema.schema) ? schema.schema : schema;
+}
+function checkRenamedFrom(path, name, renamedFrom, currentNames, pattern, report) {
+    if (!pattern.test(renamedFrom)) {
+        report("invalid-renamed-from", path, `renamedFrom "${renamedFrom}" is not a valid name.`);
+    }
+    else if (renamedFrom === name) {
+        report("invalid-renamed-from", path, "renamedFrom must be the previous name, not the current one.");
+    }
+    else if (currentNames.has(renamedFrom)) {
+        report("invalid-renamed-from", path, `renamedFrom "${renamedFrom}" is a current name; a rename must free the old name.`);
+    }
+}
+function resolveTarget(target, scope) {
+    let candidate = target;
+    if (typeof candidate === "function") {
+        try {
+            candidate = candidate();
+        }
+        catch (error) {
+            return { problem: `its target thunk threw: ${errorMessage(error)}` };
+        }
+        if (!isEntity(candidate)) {
+            return {
+                problem: "its target thunk must return an entity; is the entity defined and exported?",
+            };
+        }
+    }
+    if (typeof candidate === "string") {
+        return scope.entitiesByName.has(candidate)
+            ? { name: candidate }
+            : { problem: `it points at "${candidate}", which is not an entity of this ontology.` };
+    }
+    if (isEntity(candidate)) {
+        const problem = `it points at ${candidate.name}, which is not part of the ontology; ` +
+            "add it to defineOntology({ entities }).";
+        return scope.definitions.has(candidate.definition) ? { name: candidate.name } : { problem };
+    }
+    return { problem: "it must point at an entity, a thunk returning one, or an entity name." };
+}
+function resolveRelationships(candidate, scope) {
+    const { report } = scope;
+    const relationships = [];
+    for (const [name, relationship] of Object.entries(candidate.definition.relationships ?? {})) {
+        const path = `${candidate.name}.relationships.${name}`;
+        checkMemberName("relationship", path, name, report);
+        if (!isRelationship(relationship)) {
+            report("invalid-relationship", path, "is not a relationship; declare it with rel.one or rel.many.");
+            continue;
+        }
+        const target = resolveTarget(relationship.target, scope);
+        if ("problem" in target) {
+            report("unknown-relationship-target", path, target.problem);
+        }
+        checkRelationship(path, relationship, report);
+        relationships.push({ name, relationship, target: "name" in target ? target.name : undefined });
+    }
+    return relationships;
+}
+function checkRelationship(path, relationship, report) {
+    if (isBlank(relationship.description)) {
+        report("missing-description", path, "every relationship needs a description.");
+    }
+    checkMemberName("inverse", `${path}.inverse`, relationship.inverse, report);
+    if (relationship.phrase !== undefined &&
+        (relationship.phrase.length !== 2 || relationship.phrase.some((part) => isBlank(part)))) {
+        report("invalid-phrase", path, "phrase names both directions: [forward, inverse].");
+    }
+    // checkWarehouseSource refuses a delete rule or optionality on a relationship matched by value.
+    if (relationship.cardinality === "many" || relationship.on !== undefined) {
+        return;
+    }
+    // Undeclared means restrict.
+    const onDelete = relationship.onDelete ?? "restrict";
+    if (!ON_DELETE.includes(onDelete)) {
+        report("invalid-on-delete", path, `onDelete is one of ${ON_DELETE.join(", ")}.`);
+    }
+    else if (onDelete === "setNull" && !relationship.optional) {
+        report("invalid-on-delete", path, 'onDelete "setNull" needs an optional relationship; use "cascade" or "restrict".');
+    }
+}
+/**
+ * A relationship with a warehouse-backed end is matched by value, through `on`, and has no
+ * `<name>_id` key. Its declaration may still lack `on`, which checkWarehouseSource reports.
+ */
+function isValueMatchedDeclaration(input) {
+    const { owner, relationship, target } = input;
+    return (relationship.cardinality === "one" &&
+        (relationship.on !== undefined ||
+            owner.definition.source !== undefined ||
+            target?.definition.source !== undefined));
+}
+function resolveIndexes(candidate, properties, relationships, scope) {
+    const valueMatched = new Set(relationships
+        .filter(({ relationship, target }) => isValueMatchedDeclaration({
+        owner: candidate,
+        relationship,
+        target: target === undefined ? undefined : scope.entitiesByName.get(target),
+    }))
+        .map((relationship) => relationship.name));
+    const fields = new Set([
+        ...SYSTEM_PROPERTIES,
+        ...properties.map((property) => property.name),
+        ...relationships
+            .filter((relationship) => relationship.relationship.cardinality === "one")
+            .filter((relationship) => !valueMatched.has(relationship.name))
+            .map((relationship) => relationship.name),
+    ]);
+    const indexes = candidate.definition.indexes ?? [];
+    return indexes.map((index, position) => {
+        const path = `${candidate.name}.indexes[${position}]`;
+        const resolved = Array.isArray(index)
+            ? { properties: index, unique: false }
+            : {
+                properties: index.properties ?? [],
+                unique: index.unique === true,
+            };
+        if (resolved.properties.length === 0) {
+            scope.report("invalid-index", path, "an index covers at least one field.");
+        }
+        for (const field of resolved.properties) {
+            if (valueMatched.has(field)) {
+                scope.report("invalid-index", path, `"${field}" is matched by value and has no key column. Index the property named in on instead.`);
+            }
+            else if (!fields.has(field)) {
+                scope.report("invalid-index", path, `"${field}" is not a property, system property or rel.one relationship of ${candidate.name}.`);
+            }
+        }
+        return resolved;
+    });
+}
+/** An entity whose `.actions(…)` was never called: `actions` is still the builder. */
+function isBuiltInUser(candidate, scope) {
+    return scope.builtIns.has(candidate.definition) && candidate.name === User.name;
+}
+function isDraft(candidate) {
+    return typeof candidate.actions === "function";
+}
+function actionEntries(candidate, report) {
+    const actions = candidate.actions;
+    const path = `${candidate.name}.actions`;
+    if ("actions" in candidate.definition) {
+        report("invalid-actions", path, "declare actions with entity(…).actions((self) => ({ … })), not in the definition.");
+    }
+    if (isDraft(candidate)) {
+        return [];
+    }
+    if (!isPlainObject(actions)) {
+        report("invalid-actions", path, ".actions((self) => ({ … })) must return an object of actions.");
+        return [];
+    }
+    return Object.entries(actions);
+}
+function resolveActions(candidate, scope) {
+    const { report } = scope;
+    const actions = [];
+    for (const [name, action] of actionEntries(candidate, report)) {
+        const path = `${candidate.name}.actions.${name}`;
+        if (!SNAKE_CASE_NAME.test(name)) {
+            report("invalid-name", path, "action names are lowercase snake_case, for example change_status.");
+        }
+        else if (GENERATED_ACTIONS.includes(name) ||
+            GENERATED_UPSERT.test(name)) {
+            report("reserved-name", path, `${name} is generated for every entity; choose another name.`);
+        }
+        else if (isBuiltInUser(candidate, scope) &&
+            USER_MEMBER_VERBS.includes(name)) {
+            report("reserved-name", path, `${name} is generated for the built-in user; choose another name, and call ` +
+                "the User handle's member writes from its handler.");
+        }
+        if (!isAction(action)) {
+            report("invalid-action", path, "is not an action; declare it with action({ … }).");
+            continue;
+        }
+        if (isBlank(action.description)) {
+            report("missing-description", path, "every action needs a description.");
+        }
+        if ("allow" in action) {
+            report("removed-allow", `${path}.allow`, REMOVED_ALLOW);
+        }
+        if (action.retryOnDeadlock !== undefined &&
+            (typeof action.retryOnDeadlock !== "boolean" ||
+                (action.retryOnDeadlock && !action.transactional))) {
+            report("invalid-action", `${path}.retryOnDeadlock`, "retryOnDeadlock is a boolean and requires a transactional handler when true.");
+        }
+        if (action.files !== undefined) {
+            if (!Array.isArray(action.files) ||
+                action.prepare === undefined ||
+                (action.files.length > 0 && (!action.transactional || action.hints?.readOnly === true))) {
+                report("invalid-action", `${path}.files`, "file staging requires prepare and a transactional handler.");
+            }
+            else {
+                const targets = new Set();
+                for (const target of action.files) {
+                    const entity = scope.entitiesByName.get(target?.entity);
+                    const definition = entity?.definition;
+                    const property = definition?.properties[target?.property];
+                    const identity = `${target?.entity}.${target?.property}`;
+                    if (!entity ||
+                        definition?.source ||
+                        propertyDefinition(property)?.type !== "blob" ||
+                        targets.has(identity)) {
+                        report("invalid-action", `${path}.files`, "file targets must name distinct stored blob properties.");
+                    }
+                    targets.add(identity);
+                }
+            }
+        }
+        actions.push({
+            name,
+            action,
+            permission: resolvePermission(path, permissionOf(candidate.name, name), action, scope),
+            input: resolveInput(path, action.input, scope),
+            connections: resolveActionConnections(path, action, scope, scope.builtIns.has(candidate.definition)),
+            hints: resolveHints(path, action, report),
+            writes: resolveActionWrites(path, action, scope),
+        });
+    }
+    return actions;
+}
+/**
+ * The entity an action's `writes` names. Handles are matched by their stable id: the handles a
+ * handler closes over are the authored ones, which the analysis has converted to wire names.
+ */
+function resolveWriteTarget(target, scope) {
+    let candidate = target;
+    if (typeof candidate === "function" && !isEntity(candidate)) {
+        try {
+            candidate = candidate();
+        }
+        catch (error) {
+            return { problem: `its thunk threw: ${errorMessage(error)}` };
+        }
+    }
+    if (typeof candidate === "string") {
+        const name = nameToWire(candidate);
+        return scope.entitiesByName.has(name)
+            ? { name }
+            : { problem: `"${candidate}" is not an entity of this ontology.` };
+    }
+    if (!isEntity(candidate)) {
+        return { problem: "it must be an entity, a thunk returning one, or an entity name." };
+    }
+    const id = candidate.definition.id;
+    for (const [name, entity] of scope.entitiesByName) {
+        if (entity.definition.id === id) {
+            return { name };
+        }
+    }
+    return {
+        problem: `${candidate.name} is not part of the ontology; add it to defineOntology({ entities }).`,
+    };
+}
+/**
+ * The entities an action declares it writes, by wire name: stored entities of the ontology, each
+ * once. `undefined` when it declares none, so the handler may write any entity.
+ */
+function resolveActionWrites(path, action, scope) {
+    const declared = action.writes;
+    if (declared === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(declared)) {
+        scope.report("invalid-action", `${path}.writes`, "writes lists the entities the handler writes, such as [self, Note].");
+        return undefined;
+    }
+    const names = [];
+    declared.forEach((target, index) => {
+        const at = `${path}.writes[${index}]`;
+        const resolved = resolveWriteTarget(target, scope);
+        if ("problem" in resolved) {
+            scope.report("invalid-action", at, `writes names an entity the handler writes, but ${resolved.problem}`);
+            return;
+        }
+        const name = nameToWire(resolved.name);
+        const entity = scope.entitiesByName.get(name);
+        if (entity?.definition.source !== undefined) {
+            scope.report("invalid-action", at, `${name} is warehouse-backed, so no action writes it; remove it from writes.`);
+        }
+        else if (names.includes(name)) {
+            scope.report("invalid-action", at, `${name} is listed twice in writes.`);
+        }
+        else {
+            names.push(name);
+        }
+    });
+    return names;
+}
+const HINT_NAMES = [
+    "readOnly",
+    "connectionsReadOnly",
+    "destructive",
+    "irreversible",
+    "idempotent",
+];
+/** Validate safety labels before publishing them to callers. */
+function resolveHints(path, action, report) {
+    const declared = action.hints;
+    if (declared === undefined) {
+        return undefined;
+    }
+    const at = `${path}.hints`;
+    if (!isPlainObject(declared)) {
+        report("invalid-action", at, "hints is an object such as { destructive: false }.");
+        return undefined;
+    }
+    const hints = {};
+    for (const [key, value] of Object.entries(declared)) {
+        if (!HINT_NAMES.includes(key)) {
+            report("invalid-action", `${at}.${key}`, `is not a hint; use ${HINT_NAMES.join(" or ")}.`);
+        }
+        else if (typeof value !== "boolean") {
+            report("invalid-action", `${at}.${key}`, "is true or false.");
+        }
+        else {
+            hints[key] = value;
+        }
+    }
+    if (hints.readOnly === true) {
+        if (action.prepare === undefined || action.transactional) {
+            report("invalid-action", `${at}.readOnly`, "readOnly requires prepare without a handler.");
+        }
+        if (hints.destructive === true || hints.irreversible === true) {
+            report("invalid-action", `${at}.readOnly`, "A read-only action cannot be destructive or irreversible.");
+        }
+    }
+    return hints;
+}
+/** The action's own `permission`, which names an entity and a verb without wildcards. */
+function resolvePermission(path, fallback, action, scope) {
+    const declared = action.permission;
+    if (declared === undefined) {
+        return fallback;
+    }
+    const parsed = parsePermission(declared);
+    if (parsed === undefined || parsed.entity === WILDCARD || parsed.verb === WILDCARD) {
+        scope.report("invalid-permission", `${path}.permission`, `${JSON.stringify(declared)} is not a permission an action can require; ` +
+            `write <entity>:<verb> without wildcards, such as ${fallback}.`);
+        return fallback;
+    }
+    if (!scope.entitiesByName.has(parsed.entity)) {
+        scope.report("unknown-permission", `${path}.permission`, `${parsed.entity} is not an entity of this ontology.`);
+    }
+    return permissionOf(parsed.entity, parsed.verb);
+}
+function resolveInput(path, input, scope) {
+    const inputPath = `${path}.input`;
+    if (!Schema.isSchema(input) || Schema.toEncoded(input).ast._tag !== "Objects") {
+        scope.report("invalid-action-input", inputPath, "must be a Schema.Struct of the action's inputs.");
+        return undefined;
+    }
+    if ("fields" in input) {
+        checkInputFields(inputPath, input.fields, scope);
+    }
+    try {
+        const document = Schema.toJsonSchemaDocument(input, {
+            includeAnnotationKey: (key) => key === REFERENCE_ANNOTATION || key === BLOB_UPLOAD_ANNOTATION,
+            onExcessProperty: "error",
+        });
+        const schema = document.schema;
+        checkEncodedInputNames(schema, inputPath, scope, !("fields" in input));
+        for (const definition of Object.values(document.definitions)) {
+            checkEncodedInputNames(definition, inputPath, scope, !("fields" in input));
+        }
+        return Object.keys(document.definitions).length === 0
+            ? schema
+            : { ...schema, $defs: document.definitions };
+    }
+    catch (error) {
+        scope.report("invalid-action-input", inputPath, `has no JSON Schema form: ${errorMessage(error)}`);
+        return undefined;
+    }
+}
+/** Check named input fields on the wire side; codecs may decode them to camelCase handler values. */
+function checkEncodedInputNames(schema, path, scope, checkReferences) {
+    const { report } = scope;
+    const reference = schema[REFERENCE_ANNOTATION];
+    if (checkReferences && typeof reference === "string" && !scope.entitiesByName.has(reference)) {
+        report("unknown-reference", path, `references "${reference}", which is not an entity of this ontology.`);
+    }
+    const properties = schema.properties;
+    if (properties !== null && typeof properties === "object" && !Array.isArray(properties)) {
+        for (const [name, child] of Object.entries(properties)) {
+            if (name === "_segmentstream" || name === "_confirmation") {
+                report("reserved-name", `${path}.${name}`, `${name} is reserved for runtime call metadata and confirmation presentation.`);
+            }
+            if (!SNAKE_CASE_NAME.test(name)) {
+                report("invalid-name", `${path}.${name}`, "action input names are lowercase snake_case.");
+            }
+            if (child !== null && typeof child === "object" && !Array.isArray(child)) {
+                checkEncodedInputNames(child, `${path}.${name}`, scope, checkReferences);
+            }
+        }
+    }
+    for (const key of ["items", "additionalProperties", "anyOf", "oneOf", "allOf"]) {
+        const children = schema[key];
+        for (const child of Array.isArray(children) ? children : [children]) {
+            if (child !== null && typeof child === "object" && !Array.isArray(child)) {
+                checkEncodedInputNames(child, path, scope, checkReferences);
+            }
+        }
+    }
+}
+function checkInputFields(path, fields, scope) {
+    for (const [name, field] of Object.entries(fields)) {
+        const fieldPath = `${path}.${name}`;
+        const reference = referenceTarget(field);
+        if (reference !== undefined && !scope.entitiesByName.has(nameToWire(reference))) {
+            scope.report("unknown-reference", fieldPath, `references "${reference}", which is not an entity of this ontology.`);
+        }
+        if (scope.entityProperties.has(field)) {
+            continue;
+        }
+        const definition = propertyDefinition(field);
+        if (definition === undefined) {
+            continue;
+        }
+        checkPropertyOptions(fieldPath, field, scope.report);
+        if (definition.type === "select") {
+            checkSelectOptions(fieldPath, definition, scope.report);
+        }
+        if (definition.managed) {
+            scope.report("managed-without-effect", fieldPath, "managed only affects entity properties; this input field is never written by update.", "warning");
+        }
+    }
+}
+function checkEntityIdentities(entities, report) {
+    const names = new Map();
+    const ids = new Map();
+    for (const candidate of entities) {
+        const { definition } = candidate.entity;
+        const existingName = names.get(candidate.name);
+        const existingId = ids.get(definition.id);
+        if (existingName !== undefined) {
+            const builtIn = existingName.builtIn
+                ? ` (the built-in ${existingName.entity.definition.label})`
+                : "";
+            report("duplicate-name", candidate.name, `another entity is named ${candidate.name}${builtIn}.`);
+        }
+        else {
+            names.set(candidate.name, candidate);
+        }
+        if (!ENTITY_ID.test(definition.id ?? "")) {
+            report("invalid-entity-id", candidate.name, "entity ids look like ent_01J9Q4M8ZK and never change.");
+        }
+        else if (existingId !== undefined) {
+            report("duplicate-entity-id", candidate.name, `${existingId.name} already has the id ${definition.id}.`);
+        }
+        else {
+            ids.set(definition.id, candidate);
+        }
+    }
+    const currentNames = new Set(entities.map((candidate) => candidate.name));
+    for (const candidate of entities) {
+        const { renamedFrom } = candidate.entity.definition;
+        if (renamedFrom !== undefined) {
+            checkRenamedFrom(candidate.name, candidate.name, renamedFrom, currentNames, SNAKE_CASE_NAME, report);
+        }
+    }
+}
+/**
+ * Properties, relationships, `<relationship>_id` fields and the inverses that land on an entity share
+ * one namespace: they are the record's fields and the API's traversal paths.
+ */
+function checkMemberNames(entities, report) {
+    const entitiesByName = new Map();
+    for (const candidate of [...entities].reverse()) {
+        entitiesByName.set(candidate.name, candidate);
+    }
+    const members = new Map(entities.map((candidate) => [candidate, ownMembers(candidate, entitiesByName)]));
+    for (const candidate of entities) {
+        for (const { name, relationship, target } of candidate.relationships) {
+            const landing = target === undefined ? undefined : entitiesByName.get(target);
+            if (landing === undefined) {
+                continue;
+            }
+            const path = `${candidate.name}.relationships.${name}.inverse`;
+            members.get(landing)?.push({ name: relationship.inverse, path, inverse: true });
+            if (Object.hasOwn(landing.entity.definition.metrics ?? {}, relationship.inverse)) {
+                report("inverse-collision", path, `${relationship.inverse} is already a metric of ${landing.name}.`);
+            }
+        }
+    }
+    for (const [candidate, list] of members) {
+        const seen = new Map();
+        for (const current of list) {
+            const previous = seen.get(current.name);
+            if (previous === undefined) {
+                seen.set(current.name, current);
+                continue;
+            }
+            const code = previous.inverse || current.inverse ? "inverse-collision" : "duplicate-name";
+            report(code, current.path, `${current.name} is already a field of ${candidate.name} (${previous.path}).`);
+        }
+    }
+}
+function ownMembers(candidate, entitiesByName) {
+    const properties = candidate.properties.map((property) => ({
+        name: property.name,
+        path: `${candidate.name}.properties.${property.name}`,
+        inverse: false,
+    }));
+    const relationships = candidate.relationships.flatMap(({ name, relationship, target }) => {
+        const path = `${candidate.name}.relationships.${name}`;
+        const own = { name, path, inverse: false };
+        const landing = target === undefined ? undefined : entitiesByName.get(target);
+        // Only a stored → stored rel.one has a `<name>_id` key.
+        const keyed = relationship.cardinality === "one" &&
+            !isValueMatchedDeclaration({
+                owner: candidate.entity,
+                relationship,
+                target: landing?.entity,
+            });
+        return keyed ? [own, { ...own, name: `${name}_id` }] : [own];
+    });
+    return [...properties, ...relationships];
+}
+/**
+ * The verbs each entity has: `read`, its generated actions, and what its actions require. The
+ * built-in user also has its member management verbs, which roles may grant.
+ */
+function knownVerbs(entities) {
+    const verbs = new Map();
+    for (const candidate of entities) {
+        const own = verbs.get(candidate.name) ?? new Set();
+        for (const permission of Object.values(candidate.permissions)) {
+            const parsed = parsePermission(permission);
+            if (parsed !== undefined) {
+                own.add(parsed.verb);
+            }
+        }
+        if (candidate.builtIn && candidate.name === User.name) {
+            for (const verb of USER_MEMBER_VERBS) {
+                own.add(verb);
+            }
+        }
+        verbs.set(candidate.name, own);
+    }
+    for (const candidate of entities) {
+        for (const { permission } of candidate.actions) {
+            const parsed = parsePermission(permission);
+            if (parsed !== undefined) {
+                verbs.get(parsed.entity)?.add(parsed.verb);
+            }
+        }
+    }
+    return verbs;
+}
+/** Why a role's permission matches nothing in the ontology, or `undefined` when it matches. */
+function unknownPermission(value, { entity, verb }, verbs) {
+    if (entity === WILDCARD) {
+        // A wildcard entity does not reach what only a named permission covers.
+        const matched = verb === WILDCARD ||
+            [...verbs].some(([name, own]) => own.has(verb) && wildcardEntityCovers(name, verb));
+        return matched ? undefined : `${value} matches nothing: no entity has ${verb}.`;
+    }
+    const own = verbs.get(entity);
+    if (own === undefined) {
+        return `${value} names ${entity}, which is not an entity of this ontology.`;
+    }
+    if (verb === WILDCARD || own.has(verb)) {
+        return undefined;
+    }
+    if (verb.startsWith(GENERATED_UPSERT_PREFIX)) {
+        const [create, update] = generatedActionPermissions(entity, verb);
+        return `${value} is not a permission: ${verb} requires ${create} and ${update}.`;
+    }
+    return `${value} is not a permission of this ontology; ${entity} has ${[...own].join(", ")}.`;
+}
+function checkRolePermissions(candidate, verbs, workflows, report) {
+    const builtIn = candidate.name === MEMBER_ROLE;
+    const path = builtIn ? "member.permissions" : `roles.${candidate.name}.permissions`;
+    const permissions = candidate.permissions;
+    if (!Array.isArray(permissions)) {
+        report("missing-permissions", path, "list what the role may do as <entity>:<verb> permissions, such as " +
+            'permissions: ["lead:read"].');
+        return;
+    }
+    // An empty member list is a choice: members then hold only the roles they are given.
+    if (permissions.length === 0 && !builtIn) {
+        report("missing-permissions", path, "a role without permissions can do nothing; list at least one, such as lead:read.");
+    }
+    permissions.forEach((value, index) => {
+        const at = `${path}[${index}]`;
+        const workflow = parseWorkflowPermission(value);
+        if (workflow !== undefined) {
+            if (workflow.workflow !== WILDCARD && !workflows.has(workflow.workflow)) {
+                report("unknown-permission", at, `${String(value)} names ${workflow.workflow}, which is not a workflow of this ontology.`);
+            }
+            return;
+        }
+        const parsed = parsePermission(value);
+        if (parsed === undefined) {
+            report("invalid-permission", at, `${JSON.stringify(value)} is not a permission; write <entity>:<verb>, such as lead:read, ` +
+                "lead:* or *:read, or workflow:<workflow>:start or workflow:<workflow>:read.");
+            return;
+        }
+        if (parsed.entity === WILDCARD && parsed.verb === WILDCARD) {
+            report("wildcard-permission", at, "*:* grants every entity and action, including those added later, except agent_chat, " +
+                "app_feedback, app_feedback_file, user_identity and " +
+                `administering users (${USER_MEMBER_VERBS.map((verb) => `user:${verb}`).join(", ")} ` +
+                "and user's authored actions), which only user:<verb> or user:* grants.", "warning");
+            return;
+        }
+        const problem = unknownPermission(`${parsed.entity}:${parsed.verb}`, parsed, verbs);
+        if (problem !== undefined) {
+            report("unknown-permission", at, problem);
+        }
+    });
+}
+/**
+ * Under the open policy anyone who signs in holds `member`. Warehouse-backed entities hold company
+ * figures, such as revenue or stock, that metric queries read with `<entity>:read`; a wildcard of
+ * member's (`*:read`, the default, or `*:*`) must not hand them to strangers. Granting a
+ * warehouse-backed entity by name, `<entity>:read` or `<entity>:*`, is a deliberate choice.
+ */
+function checkOpenWarehouseReads(input) {
+    const { entities, roles, signIn, report } = input;
+    const warehouseBacked = entities
+        .filter((candidate) => candidate.entity.definition.source !== undefined)
+        .map((candidate) => candidate.name);
+    const memberPermissions = roles.find((candidate) => candidate.name === MEMBER_ROLE)?.permissions;
+    if (signIn.policy !== "open" ||
+        warehouseBacked.length === 0 ||
+        !Array.isArray(memberPermissions)) {
+        return;
+    }
+    const wildcards = memberPermissions.filter((permission) => {
+        const parsed = parsePermission(permission);
+        return (parsed !== undefined &&
+            parsed.entity === WILDCARD &&
+            (parsed.verb === WILDCARD || parsed.verb === READ_VERB));
+    });
+    if (wildcards.length === 0) {
+        return;
+    }
+    report("invalid-sign-in", "signIn.policy", `signIn policy open lets anyone who signs in hold member; member's ${wildcards.join(", ")} ` +
+        `${wildcards.length === 1 ? "reaches" : "reach"} warehouse-backed entities ` +
+        `(${warehouseBacked.join(", ")}). Grant them to member by name, such as ` +
+        `${warehouseBacked[0]}:read, or use the invited policy.`);
+}
+/** Public channels admit strangers with explicitly reviewed baseline grants. */
+function checkOpenChannels(input) {
+    const { config, entities, roles, signIn, report } = input;
+    if (!Object.values(signIn.channels ?? {}).includes("open")) {
+        return;
+    }
+    const hint = "move staff reads into a named role";
+    if (config.member === undefined) {
+        report("invalid-sign-in", "member", `Open channels require explicit member permissions; ${hint}.`);
+        return;
+    }
+    const permissions = roles.find((candidate) => candidate.name === MEMBER_ROLE)?.permissions;
+    if (!Array.isArray(permissions)) {
+        report("invalid-sign-in", "member.permissions", "Open channels require an explicit permissions array.");
+        return;
+    }
+    for (const permission of permissions) {
+        const parsed = parsePermission(permission);
+        const entity = entities.find((candidate) => candidate.name === parsed?.entity);
+        const generatedWrite = entity !== undefined &&
+            [
+                entity.permissions.create,
+                entity.permissions.update,
+                entity.permissions.delete,
+                entity.permissions.link,
+                entity.permissions.unlink,
+            ].some((required) => required !== undefined && isAllowed(required, { permissions: [permission] }));
+        if (parsed?.entity === WILDCARD || generatedWrite) {
+            report("invalid-sign-in", "member.permissions", `Open channels cannot grant member ${permission}; ${hint}. Use ownership-checked app actions.`);
+        }
+        else if (entity !== undefined &&
+            isAllowed(entity.permissions.read, { permissions: [permission] })) {
+            report("invalid-sign-in", "member.permissions", `${permission} permits shared reads; review public catalogs and ${hint}.`, "warning");
+        }
+    }
+}
+/** The hook has only member authority and cannot enter the external preparation phase. */
+function checkNewUserAction(input) {
+    const { entities, roles, signIn, report } = input;
+    if (signIn.onNewUser === undefined) {
+        return;
+    }
+    const parsed = parsePermission(signIn.onNewUser);
+    const found = entities
+        .find((entity) => entity.name === parsed?.entity)
+        ?.actions.find((candidate) => candidate.name === parsed?.verb);
+    const fail = (message) => report("invalid-sign-in", "signIn.onNewUser", message);
+    if (found === undefined) {
+        fail("onNewUser must name an existing authored action.");
+        return;
+    }
+    if (Result.isFailure(Schema.decodeUnknownResult(found.action.input)({}))) {
+        fail("onNewUser cannot have required input; it is called with {}.");
+    }
+    if (!isAllowed(found.permission, { permissions: roles[0]?.permissions ?? [] })) {
+        fail("onNewUser must be runnable by member.");
+    }
+    if (found.action.hints?.idempotent !== true) {
+        fail("onNewUser must declare hints.idempotent: true.");
+    }
+    if (found.action.prepare !== undefined || found.action.connections.length > 0) {
+        fail("onNewUser cannot prepare or use external connections.");
+    }
+}
+/** The member management verbs that act on members a page or an agent must first find. */
+const ROSTER_VERBS = ["invite", "grant_roles"];
+/**
+ * A role that may invite members or grant roles must be able to read users, or it has no roster to
+ * act on. A member holds `member` beside their roles, so member's permissions count for every role.
+ */
+function checkRosterReads(roles, report) {
+    const permissionsOf = (candidate) => Array.isArray(candidate?.permissions) ? candidate.permissions : [];
+    const memberPermissions = permissionsOf(roles.find((candidate) => candidate.name === MEMBER_ROLE));
+    for (const candidate of roles) {
+        const builtIn = candidate.name === MEMBER_ROLE;
+        const permissions = builtIn
+            ? memberPermissions
+            : [...permissionsOf(candidate), ...memberPermissions];
+        const holder = { permissions };
+        const writes = ROSTER_VERBS.map((verb) => permissionOf(User.name, verb)).filter((permission) => isAllowed(permission, holder));
+        if (writes.length > 0 && !isAllowed(permissionOf(User.name, READ_VERB), holder)) {
+            report("missing-permissions", builtIn ? "member.permissions" : `roles.${candidate.name}.permissions`, `${writes.join(" and ")} without user:read cannot find the members to act on; ` +
+                "add user:read.");
+        }
+    }
+}
+/**
+ * Every permission a role lists must match an entity and a verb of the ontology, and an authored
+ * action that no role grants is a warning. Generated actions are not warned about: they stay closed
+ * until a role grants them.
+ */
+function checkPermissions(entities, roles, workflows, report, authoredRoles = roles) {
+    const verbs = knownVerbs(entities);
+    const workflowNames = new Set(workflows.map((candidate) => candidate.name));
+    for (const candidate of authoredRoles) {
+        checkRolePermissions(candidate, verbs, workflowNames, report);
+    }
+    checkRosterReads(authoredRoles, report);
+    checkScopes(entities, authoredRoles, verbs, report);
+    const granting = roles.map((candidate) => ({
+        name: candidate.name,
+        permissions: Array.isArray(candidate.permissions) ? candidate.permissions : [],
+    }));
+    // Built-in actions are granted by the workspace's roles when it wants them.
+    for (const candidate of entities.filter((entity) => !entity.builtIn)) {
+        for (const { name, permission } of candidate.actions) {
+            const parsed = parsePermission(permission);
+            // An invalid name or permission is already an error; it needs no warning on top.
+            const checkable = parsed !== undefined && verbs.has(parsed.entity);
+            if (checkable && rolesGranting(granting, permission).length === 0) {
+                report("unreachable-action", `${candidate.name}.actions.${name}`, `no role grants ${permission}, so nobody can run this action; ` +
+                    "add it to a role's permissions or to member's.", "warning");
+            }
+        }
+    }
+}
+/** The id a `me` marker stands for while the entity's query schema validates a scope. */
+const SCOPE_PLACEHOLDER_ID = "00000000-0000-4000-8000-000000000000";
+const SCOPE_KEYS = ["permission", "where", "readsAll"];
+const FIELD_OPERATOR_NAMES = [
+    "eq",
+    "ne",
+    "in",
+    "is_null",
+    "isNull",
+    "contains",
+    "starts_with",
+    "startsWith",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "between",
+];
+/** Whether a condition is a field filter: an object whose keys are all operators. */
+function isFieldOperators(value) {
+    return (isPlainObject(value) &&
+        Object.keys(value).length > 0 &&
+        Object.keys(value).every((key) => FIELD_OPERATOR_NAMES.includes(key)));
+}
+/** `me.staffMember.division`, as the author wrote it. */
+function mePathText(hops) {
+    return ["me", ...hops.map(toCamelCase)].join(".");
+}
+function scopeProblem(walk, code, path, message) {
+    walk.problems += 1;
+    walk.report(code, path, message);
+}
+/**
+ * Checks that a path walks relationship names from the built-in user, in at most
+ * {@link MAX_ME_HOPS} hops, and ends on `expected`, the entity whose ids the field compares.
+ */
+function checkMePath(walk, hops, expected, field, path) {
+    const text = mePathText(hops);
+    if (hops.length > MAX_ME_HOPS) {
+        scopeProblem(walk, "invalid-scope-path", path, `${text} takes ${hops.length} relationships; a path takes at most ${MAX_ME_HOPS} from the ` +
+            "user. Keep a relationship closer to the user, maintained by a workflow, and walk that.");
+        return;
+    }
+    let current = User.name;
+    for (const hop of hops) {
+        const links = queryLinks(walk.manifest, current);
+        const link = links.find((candidate) => candidate.name === hop);
+        if (link === undefined) {
+            const names = links.map((candidate) => toCamelCase(candidate.name));
+            scopeProblem(walk, "invalid-scope-path", path, `${toCamelCase(hop)} in ${text} is not a relationship of ${current}; each hop names a ` +
+                `relationship as seen from the entity before it, ${names.length === 0 ? `and ${current} has none` : `here one of ${names.join(", ")}`}.`);
+            return;
+        }
+        current = link.target;
+    }
+    if (expected !== undefined && current !== expected) {
+        scopeProblem(walk, "invalid-scope-path", path, `${text} ends on ${current}, but ${field} compares ${expected} ids; end the path on ` +
+            `${expected}, or compare it with a relationship to ${current} or with id on ${current}.`);
+    }
+}
+/**
+ * A comparison of a field with `me`, a path or literal values, checked, with every marker replaced
+ * by an id so that the query schema can validate the rest. `target` is the entity whose ids the
+ * field holds: the entity itself for `id`, the related entity for a `<relationship>_id`, the user
+ * for `created_by` and `updated_by`; `undefined` for any other field.
+ */
+function scopeComparison(input) {
+    const { walk, field, target, name, condition, path } = input;
+    const ids = field.storage === "uuid";
+    const literalId = () => scopeProblem(walk, "invalid-scope", path, `${name} compares record ids, which differ between environments, with a literal value; ` +
+        "compare it with me or a path, such as { in: me.staffMember.division }, or declare a " +
+        "role per unit.");
+    const marker = (value, operator) => {
+        const hops = mePathOf(value);
+        if (hops === undefined) {
+            return value;
+        }
+        if (!ids || target === undefined) {
+            scopeProblem(walk, "invalid-scope", path, `${mePathText(hops)} stands for record ids, and ${name} holds none; compare me with a ` +
+                "relationship to user or with id, and a path with a relationship to the entity it " +
+                "ends on.");
+            return SCOPE_PLACEHOLDER_ID;
+        }
+        if (operator === "in") {
+            if (hops.length === 0) {
+                scopeProblem(walk, "invalid-scope", path, `me is one id and does not take in; write ${name}: me or { eq: me }, or a path such ` +
+                    "as { in: me.staffMember.division } for a set.");
+            }
+            else {
+                checkMePath(walk, hops, target, name, path);
+            }
+            return [SCOPE_PLACEHOLDER_ID];
+        }
+        if (operator !== "eq" && operator !== "ne") {
+            scopeProblem(walk, "invalid-scope", path, `${operator} does not compare with ${mePathText(hops)}; compare me with eq or ne, and a ` +
+                "path with in.");
+        }
+        else if (hops.length > 0) {
+            scopeProblem(walk, "invalid-scope", path, `${mePathText(hops)} is a set of ids and does not take ${operator}; write ` +
+                `{ in: ${mePathText(hops)} }.`);
+        }
+        else {
+            checkMePath(walk, hops, target, name, path);
+        }
+        return SCOPE_PLACEHOLDER_ID;
+    };
+    if (mePathOf(condition) !== undefined) {
+        return marker(condition, "eq");
+    }
+    if (isFieldOperators(condition)) {
+        return Object.fromEntries(Object.entries(condition).map(([operator, value]) => {
+            if (mePathOf(value) !== undefined) {
+                return [operator, marker(value, operator)];
+            }
+            if (ids &&
+                (operator === "eq" || operator === "ne" || operator === "in") &&
+                value !== null &&
+                value !== undefined) {
+                literalId();
+            }
+            return [operator, value];
+        }));
+    }
+    if (ids && condition !== null && condition !== undefined && !isPlainObject(condition)) {
+        literalId();
+    }
+    return condition;
+}
+/** Reports an empty condition, which in a scope would match every record while counting as scoped. */
+function emptyScopeCondition(walk, condition, path) {
+    const empty = condition === undefined ||
+        (isPlainObject(condition) && Object.keys(condition).length === 0) ||
+        (Array.isArray(condition) && condition.length === 0);
+    if (empty) {
+        scopeProblem(walk, "invalid-scope", path, "an empty condition matches every record, so the scope would grant them all while " +
+            "counting as scoped; write the condition, or list the permission as a string to grant " +
+            "every record.");
+    }
+    return empty;
+}
+/**
+ * Walks a scope's `where` on an entity: checks every comparison with `me`, paths and record ids,
+ * and returns the `where` the query schema validates, with a relationship compared by key renamed
+ * to its `<relationship>_id` and every marker replaced by an id. An empty `where`, field filter,
+ * relationship filter or `and` is refused; `some: {}` and `none: {}` ask whether a related record
+ * exists and are accepted.
+ */
+function scopeWhere(walk, entityName, where, path, anyRecord = false) {
+    const entity = findEntityManifest(walk.manifest, entityName);
+    if (where === undefined) {
+        emptyScopeCondition(walk, where, path);
+        return where;
+    }
+    if (!isPlainObject(where) || entity === undefined) {
+        return where;
+    }
+    if (!anyRecord && emptyScopeCondition(walk, where, path)) {
+        return where;
+    }
+    const fields = new Map(queryFields(entity).map((field) => [field.name, field]));
+    const links = new Map(queryLinks(walk.manifest, entityName).map((link) => [link.name, link]));
+    const keyTarget = (field) => {
+        if (field.name === "id") {
+            return entityName;
+        }
+        if (field.name === "created_by" || field.name === "updated_by") {
+            return User.name;
+        }
+        const link = field.name.endsWith("_id") ? links.get(field.name.slice(0, -3)) : undefined;
+        return link !== undefined && link.cardinality === "one" && !link.inverse
+            ? link.target
+            : undefined;
+    };
+    const result = {};
+    for (const [key, condition] of Object.entries(where)) {
+        const at = `${path}.${key}`;
+        const field = fields.get(key);
+        const link = links.get(key);
+        // `or: []` matches nothing, which is narrow, not wide.
+        if (!(key === "or" && Array.isArray(condition)) && emptyScopeCondition(walk, condition, at)) {
+            continue;
+        }
+        if ((key === "and" || key === "or") && Array.isArray(condition)) {
+            result[key] = condition.map((child, index) => scopeWhere(walk, entityName, child, `${at}[${index}]`));
+        }
+        else if (key === "not") {
+            result[key] = scopeWhere(walk, entityName, condition, at);
+        }
+        else if (field !== undefined) {
+            result[key] = scopeComparison({
+                walk,
+                field,
+                target: keyTarget(field),
+                name: key,
+                condition,
+                path: at,
+            });
+        }
+        else if (link !== undefined) {
+            const compared = mePathOf(condition) !== undefined || isFieldOperators(condition);
+            const key_ = fields.get(`${key}_id`);
+            if (compared && link.cardinality === "one" && key_ !== undefined) {
+                result[key_.name] = scopeComparison({
+                    walk,
+                    field: key_,
+                    target: link.target,
+                    name: key,
+                    condition,
+                    path: at,
+                });
+            }
+            else if (compared) {
+                scopeProblem(walk, "invalid-scope", at, `${key} relates many ${link.target} records and is not compared with ids; filter ` +
+                    `the related records instead, as in { ${key}: { some: { id: { in: me.… } } } }.`);
+            }
+            else if (link.cardinality === "one") {
+                result[key] = scopeWhere(walk, link.target, condition, at);
+            }
+            else if (isPlainObject(condition)) {
+                result[key] = Object.fromEntries(Object.entries(condition).map(([quantifier, child]) => [
+                    quantifier,
+                    scopeWhere(walk, link.target, child, `${at}.${quantifier}`, quantifier === "some" || quantifier === "none"),
+                ]));
+            }
+            else {
+                result[key] = condition;
+            }
+        }
+        else {
+            result[key] = condition;
+        }
+    }
+    return result;
+}
+/** Whether an authored action cannot carry a scope: it writes nothing a scope could check. */
+function writesNothing(candidate) {
+    return (candidate.hints?.readOnly === true ||
+        (candidate.action.prepare !== undefined && candidate.action.transactional === false));
+}
+function checkScope(input) {
+    const { scope, path, entities, verbs, report } = input;
+    if (!isPlainObject(scope) ||
+        typeof scope.permission !== "string" ||
+        !isPlainObject(scope.where) ||
+        mePathOf(scope.where) !== undefined ||
+        Object.keys(scope).some((key) => !SCOPE_KEYS.includes(key)) ||
+        (scope.readsAll !== undefined && scope.readsAll !== true)) {
+        report("invalid-scope", path, 'a scoped permission is { permission: "<entity>:<verb>", where: { … } }, optionally with ' +
+            "readsAll: true; write it so, or list the permission as a string to grant every record.");
+        return;
+    }
+    const permission = scope.permission;
+    if (parseWorkflowPermission(permission) !== undefined) {
+        report("invalid-scope", path, `${permission} is a workflow permission, which has no records to scope; list it as a string.`);
+        return;
+    }
+    const parsed = parsePermission(permission);
+    // An invalid or unknown permission is already an error of the role's permissions.
+    if (parsed === undefined) {
+        return;
+    }
+    if (parsed.entity === WILDCARD || parsed.verb === WILDCARD) {
+        report("invalid-scope", path, `${permission} has a wildcard, and a scope names one entity and one verb; scope each ` +
+            "permission by name, such as staff_member:update, or list the wildcard as a string.");
+        return;
+    }
+    const entity = entities.find((candidate) => candidate.name === parsed.entity);
+    if (entity === undefined || verbs.get(parsed.entity)?.has(parsed.verb) !== true) {
+        return;
+    }
+    if (entity.entity.definition.source !== undefined) {
+        report("invalid-scope", path, `${parsed.entity} is warehouse-backed, and scopes apply to stored entities only; list ` +
+            `${permission} as a string in the roles that may read every row.`);
+        return;
+    }
+    // Member writes (`grantRoles`, `invite`, …) do not pass through the write guard, and an authored
+    // `User` action may make them, so only reads of the built-in user are scoped.
+    if (entity.builtIn && entity.name === User.name && parsed.verb !== READ_VERB) {
+        report("invalid-scope", path, `${permission} may administer members, which a scope does not check; scope only ` +
+            "user:read, and list user actions as strings in the roles that may run them on every member.");
+        return;
+    }
+    const unscopable = entities
+        .flatMap((candidate) => candidate.actions.map((action) => ({ entity: candidate.name, action })))
+        .find(({ action }) => action.permission === permission && writesNothing(action));
+    if (unscopable !== undefined) {
+        report("invalid-scope", path, `${permission} runs ${unscopable.entity}.${unscopable.action.name}, a readOnly or ` +
+            "prepare-only action that writes nothing a scope could check; list it as a string, or " +
+            "give the action a handler that writes the record.");
+        return;
+    }
+    const manifest = input.manifest();
+    if (manifest === undefined) {
+        return;
+    }
+    const walk = { manifest, report, problems: 0 };
+    const where = scopeWhere(walk, parsed.entity, scope.where, `${path}.where`);
+    if (walk.problems > 0) {
+        return;
+    }
+    const validated = validate(entityQuerySchemas(manifest, parsed.entity, true).where, where);
+    if (!validated.ok) {
+        const issues = validated.issues
+            .map((issue) => issue.path.length === 0 ? issue.message : `${issue.path.join(".")}: ${issue.message}`)
+            .join("; ");
+        report("invalid-scope", `${path}.where`, `the where is not a query of ${parsed.entity} (${issues}); write it as a find on ` +
+            `${parsed.entity} would, with me for the caller.`);
+    }
+}
+/** A role's permissions its scoped entries do not name: those it grants every record of. */
+function unscopedPermissions(candidate) {
+    const permissions = Array.isArray(candidate.permissions) ? candidate.permissions : [];
+    const scopes = Array.isArray(candidate.scopes) ? candidate.scopes : [];
+    const scoped = new Set(scopes.map((scope) => isPlainObject(scope) && typeof scope.permission === "string"
+        ? normalizePermission(scope.permission)
+        : undefined));
+    return permissions.filter((permission) => typeof permission === "string" && !scoped.has(normalizePermission(permission)));
+}
+/**
+ * Checks every scoped permission of the roles; warns about a scope that never applies because the
+ * role grants the same permission unscoped, and about a role that scopes a write of an entity while
+ * reading every record of it. A scope `member` grants unscoped is only noted: it narrows nothing for
+ * members, but applies to API keys, which hold exactly the roles they were given.
+ */
+function checkScopes(entities, roles, verbs, report) {
+    if (!roles.some((candidate) => (Array.isArray(candidate.scopes) && candidate.scopes.length > 0) ||
+        (candidate.unusedScopes ?? []).length > 0)) {
+        return;
+    }
+    const memberRole = roles.find((candidate) => candidate.name === MEMBER_ROLE);
+    const memberGrants = memberRole === undefined ? [] : unscopedPermissions(memberRole);
+    let built;
+    // The manifest of the entities, for their query schemas; a definition it cannot be built from
+    // has errors of its own.
+    const manifest = () => {
+        if (built === undefined) {
+            try {
+                built = buildManifest({ entities, roles: [], signIn: { policy: DEFAULT_SIGN_IN_POLICY } });
+            }
+            catch {
+                built = null;
+            }
+        }
+        return built ?? undefined;
+    };
+    for (const candidate of roles) {
+        const scopes = Array.isArray(candidate.scopes) ? candidate.scopes : [];
+        const base = candidate.name === MEMBER_ROLE ? MEMBER_ROLE : `roles.${candidate.name}`;
+        const unscoped = unscopedPermissions(candidate);
+        const unused = (permission, grant, by, path) => report("scope-unused", path, `${candidate.name} scopes ${permission}, but ${by} grants it on every record through ` +
+            `${grant}, so the scope never applies; remove ${grant} from ${by}, or the scoped entry ` +
+            "if every record is intended.", "warning");
+        (candidate.unusedScopes ?? []).forEach((scope) => {
+            const grant = unscoped.find((permission) => normalizePermission(permission) === normalizePermission(scope.permission));
+            unused(scope.permission, grant ?? scope.permission, `${candidate.name} itself`, base);
+        });
+        scopes.forEach((scope, index) => {
+            const path = `${base}.scopes[${index}]`;
+            checkScope({ scope, path, entities, verbs, manifest, report });
+            const parsed = isPlainObject(scope) ? parsePermission(scope.permission) : undefined;
+            if (parsed !== undefined && parsed.entity !== WILDCARD && parsed.verb !== WILDCARD) {
+                const permission = scope.permission;
+                const own = unscoped.find((granted) => grants(granted, permission));
+                const fromMember = candidate.name === MEMBER_ROLE
+                    ? undefined
+                    : memberGrants.find((granted) => grants(granted, permission));
+                if (own !== undefined) {
+                    unused(permission, own, `${candidate.name} itself`, path);
+                    return;
+                }
+                if (fromMember !== undefined) {
+                    report("scope-member-overlap", path, `${candidate.name} scopes ${permission}, which ${MEMBER_ROLE} grants on every record ` +
+                        `through ${fromMember}, so the scope narrows nothing for members; it still applies ` +
+                        "to API keys holding this role.", "info");
+                    return;
+                }
+            }
+            if (parsed === undefined ||
+                parsed.entity === WILDCARD ||
+                parsed.verb === WILDCARD ||
+                parsed.verb === READ_VERB ||
+                scope.readsAll === true) {
+                return;
+            }
+            const read = permissionOf(parsed.entity, READ_VERB);
+            const reading = unscoped.find((permission) => grants(permission, read));
+            if (reading !== undefined) {
+                report("scope-reads-all", path, `${candidate.name} scopes ${parsed.entity}:${parsed.verb} but reads every ` +
+                    `${parsed.entity} through ${reading}; scope ${read} with the same where, or set ` +
+                    "readsAll: true on this entry if reading every record is intended.", "warning");
+            }
+        });
+    }
+}