@aventara/access 0.0.0-stage → 1.0.0-rc.1

package/dist/policies.compiler.js

@@ -0,0 +1,1433 @@
+// Builder → `@1` policies file, and the checks every policies file must pass before an
+// engine runs from it: the format and the file's shape, unknown Resources, fields,
+// relations and roles, role cycles, misplaced `in` / `after` / `fields` /
+// `write.except`, grants, denies and governed fields on a foreign Resource, and
+// create rules through a relation whose references discovery did not confirm.
+// Errors name the rule.
+// Nothing here runs per request.
+import { POLICIES_FORMAT, RETIRED_POLICIES_FORMAT, } from "./policies-contract.js";
+import { decimalParts, instantOf } from "./predicate.evaluator.js";
+import { warnReadGovernedUnique } from "./read-governed-unique.check.js";
+import { governedFor, isPlainObject, ownOf } from "./scope.resolver.js";
+/** The marker a `me` value carries; the compiler writes it as `{ principal: [...] }`. */
+export const PRINCIPAL_REF = Symbol.for("aventara.access.principal-ref");
+export const ACTIONS = [
+    "read",
+    "create",
+    "update",
+    "delete",
+];
+export const ORIGINS = [
+    "application",
+    "client",
+    "agent",
+];
+const BUILT_IN_SUBJECTS = new Set(["signedIn", "anyone"]);
+export const CLAIM_SCALARS = ["string", "number", "boolean"];
+/** A namespace name: a lowercase letter, then lowercase letters, digits, `_` or `-`; at most 63 characters. */
+const NAMESPACE = /^[a-z][a-z0-9_-]{0,62}$/;
+/** The members of a `@1` file, and of one of its schema entries. Anything else is refused. */
+const FILE_KEYS = new Set([
+    "format",
+    "namespace",
+    "claims",
+    "schema",
+    "roles",
+    "govern",
+    "governModes",
+    "grants",
+    "denies",
+]);
+const SCHEMA_ENTRY_KEYS = new Set([
+    "identifiers",
+    "fields",
+    "nullable",
+    "types",
+    "relations",
+    "foreign",
+]);
+/** The scalar types `can` compares by more than their JavaScript value: a schema entry's `types`. */
+const COMPARED_TYPES = new Set(["bigint", "datetime", "decimal"]);
+export const fail = (where, message) => {
+    throw new Error(`Aventara Access: ${where}: ${message}`);
+};
+export const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export const asList = (value) => Array.isArray(value) ? value : [value];
+// ---------------------------------------------------------------------------
+// Schema facts
+// ---------------------------------------------------------------------------
+/** The type `can` compares a scalar field by, when it is not its JavaScript value's. */
+const comparedType = (field) => field.kind === "scalar" &&
+    !field.list &&
+    "scalar" in field.type &&
+    COMPARED_TYPES.has(field.type.scalar)
+    ? field.type.scalar
+    : undefined;
+const schemaFacts = (schema) => {
+    const facts = {};
+    for (const [resource, definition] of Object.entries(schema.resources)) {
+        const relations = {};
+        const nullable = [];
+        const types = {};
+        for (const [name, field] of Object.entries(definition.fields)) {
+            if (field.kind !== "relation") {
+                if (field.nullable) {
+                    nullable.push(name);
+                }
+                const type = comparedType(field);
+                if (type !== undefined) {
+                    types[name] = type;
+                }
+                continue;
+            }
+            const paired = field.referenceFields !== undefined &&
+                field.references !== undefined &&
+                field.referenceFields.length === field.references.length;
+            relations[name] = {
+                target: field.target,
+                cardinality: field.cardinality,
+                ...(paired && field.referenceFields && field.references
+                    ? {
+                        referenceFields: [...field.referenceFields],
+                        references: [...field.references],
+                    }
+                    : {}),
+            };
+        }
+        facts[resource] = {
+            identifiers: definition.identifiers.map((identifier) => [...identifier]),
+            fields: Object.keys(definition.fields),
+            ...(nullable.length > 0 ? { nullable } : {}),
+            ...(Object.keys(types).length > 0 ? { types } : {}),
+            relations,
+            ...(definition.foreign !== undefined
+                ? { foreign: definition.foreign }
+                : {}),
+        };
+    }
+    return facts;
+};
+const fieldOf = (context, resource, name) => {
+    const owner = context.schema.resources;
+    const fields = Object.hasOwn(owner, resource)
+        ? owner[resource]?.fields
+        : undefined;
+    const field = fields !== undefined && Object.hasOwn(fields, name)
+        ? fields[name]
+        : undefined;
+    return (field ?? fail(context.rule, `Resource "${resource}" has no field "${name}"`));
+};
+/** A decimal's canonical text: no exponent, no leading or trailing zero, `-` only when not zero. */
+const decimalText = (parts) => {
+    const { sign, digits, point } = parts;
+    if (digits === "") {
+        return "0";
+    }
+    const text = point <= 0
+        ? `0.${"0".repeat(-point)}${digits}`
+        : point >= digits.length
+            ? `${digits}${"0".repeat(point - digits.length)}`
+            : `${digits.slice(0, point)}.${digits.slice(point)}`;
+    return `${sign}${text}`;
+};
+/** The longest decimal text a rule may compare with: far past any database's precision. */
+const DECIMAL_TEXT_MAX = 1000;
+/**
+ * A literal as the file writes it for a field of the given type: a `datetime` as its
+ * canonical ISO instant (`toISOString()`), a `decimal` as its canonical text, a
+ * `bigint` as a number when it is a safe integer and as its digits otherwise.
+ */
+const literalFor = (context, at, value, field) => {
+    const refuse = (what) => fail(context.rule, `${at}: ${what} (got ${value === undefined ? "undefined" : value instanceof Date ? "an invalid Date" : typeof value === "object" && value !== null ? "an object" : typeof value === "string" ? JSON.stringify(value) : typeof value})`);
+    if (value === null) {
+        return null;
+    }
+    if (typeof value === "number" && !Number.isFinite(value)) {
+        return refuse("a rule compares with a finite number");
+    }
+    const type = field === undefined ? undefined : comparedType(field);
+    const scalar = field !== undefined && "scalar" in field.type
+        ? field.type.scalar
+        : undefined;
+    switch (type) {
+        case "datetime": {
+            const instant = value instanceof Date || typeof value === "string"
+                ? instantOf(value)
+                : undefined;
+            return instant === undefined
+                ? refuse("a datetime field compares with a valid Date or an ISO-8601 instant (a date, or a date and time with `Z` or an offset)")
+                : new Date(instant).toISOString();
+        }
+        case "decimal": {
+            const parts = typeof value === "number" || typeof value === "string"
+                ? decimalParts(String(value))
+                : undefined;
+            const text = parts === undefined ? undefined : decimalText(parts);
+            return text === undefined || text.length > DECIMAL_TEXT_MAX
+                ? refuse("a decimal field compares with a number or a decimal string")
+                : text;
+        }
+        case "bigint": {
+            if (typeof value === "bigint") {
+                return value >= BigInt(Number.MIN_SAFE_INTEGER) &&
+                    value <= BigInt(Number.MAX_SAFE_INTEGER)
+                    ? Number(value)
+                    : value.toString();
+            }
+            return typeof value === "number" && Number.isSafeInteger(value)
+                ? value
+                : refuse("a bigint field compares with a bigint, or a number that is a safe integer");
+        }
+        default:
+            break;
+    }
+    if (typeof value !== "string" &&
+        typeof value !== "number" &&
+        typeof value !== "boolean") {
+        return refuse("a rule compares with a string, number, boolean, null or a `me` value");
+    }
+    const expected = field !== undefined && "enum" in field.type
+        ? "string"
+        : scalar === "string" || scalar === "boolean"
+            ? scalar
+            : scalar === "int" || scalar === "float"
+                ? "number"
+                : undefined;
+    if (expected !== undefined && typeof value !== expected) {
+        return refuse(`a ${scalar ?? "enum"} field compares with a ${expected}`);
+    }
+    if (scalar === "int" && !Number.isInteger(value)) {
+        return refuse("an int field compares with an integer");
+    }
+    return value;
+};
+const operandOf = (context, at, value, field) => {
+    if (isRecord(value) && PRINCIPAL_REF in value) {
+        const path = value.path;
+        return { principal: [...path] };
+    }
+    return literalFor(context, at, value, field);
+};
+const andOf = (args) => args.length === 0
+    ? { op: "true" }
+    : args.length === 1
+        ? args[0]
+        : { op: "and", args };
+const compileScalar = (context, resource, name, field, value) => {
+    const at = `${resource}.${name}`;
+    if (field.list) {
+        return fail(context.rule, `${at} is a list; a rule cannot compare it`);
+    }
+    // Only a plain object is an operator object: a `Date` is a literal, and any other
+    // object (a class instance, a `Map`) is refused, never read as "no operator".
+    const operators = isPlainObject(value) && !(PRINCIPAL_REF in value) ? value : undefined;
+    if (operators === undefined) {
+        return {
+            op: "cmp",
+            field: name,
+            cmp: "eq",
+            value: operandOf(context, at, value, field),
+        };
+    }
+    if (Object.keys(operators).length === 0) {
+        fail(context.rule, `${at}: an empty operator object compares nothing; name one of equals, not, in, notIn`);
+    }
+    const parts = [];
+    for (const [operator, operand] of Object.entries(operators)) {
+        switch (operator) {
+            case "equals":
+                parts.push({
+                    op: "cmp",
+                    field: name,
+                    cmp: "eq",
+                    value: operandOf(context, at, operand, field),
+                });
+                break;
+            case "not":
+                parts.push({
+                    op: "cmp",
+                    field: name,
+                    cmp: "ne",
+                    value: operandOf(context, at, operand, field),
+                });
+                break;
+            case "in":
+            case "notIn": {
+                if (!Array.isArray(operand)) {
+                    fail(context.rule, `${at}.${operator} takes a list`);
+                }
+                parts.push({
+                    op: "cmp",
+                    field: name,
+                    cmp: operator,
+                    value: operand.map((item) => operandOf(context, at, item, field)),
+                });
+                break;
+            }
+            default:
+                fail(context.rule, `${at}: unknown operator "${operator}" (equals, not, in, notIn)`);
+        }
+    }
+    return andOf(parts);
+};
+const compileWhere = (context, resource, where) => {
+    if (!isPlainObject(where)) {
+        return fail(context.rule, `a condition on ${resource} must be an object`);
+    }
+    const parts = [];
+    for (const [key, value] of Object.entries(where)) {
+        if (value === undefined) {
+            fail(context.rule, `${resource}.${key} is undefined`);
+        }
+        if (key === "AND" || key === "OR") {
+            if (!Array.isArray(value)) {
+                fail(context.rule, `${resource}.${key} takes a list`);
+            }
+            const args = value.map((item) => compileWhere(context, resource, item));
+            parts.push(key === "AND" ? { op: "and", args } : { op: "or", args });
+            continue;
+        }
+        if (key === "NOT") {
+            parts.push({ op: "not", arg: compileWhere(context, resource, value) });
+            continue;
+        }
+        if (key === "$role") {
+            if (typeof value !== "string") {
+                fail(context.rule, `${resource}.$role takes a role name`);
+            }
+            parts.push({ op: "role", role: value });
+            continue;
+        }
+        const field = fieldOf(context, resource, key);
+        if (field.kind === "scalar") {
+            parts.push(compileScalar(context, resource, key, field, value));
+            continue;
+        }
+        if (field.cardinality === "one") {
+            if (value === null) {
+                fail(context.rule, `${resource}.${key}: comparing a relation with null is not supported in v0`);
+            }
+            parts.push({
+                op: "rel",
+                relation: key,
+                target: field.target,
+                where: compileWhere(context, field.target, value),
+            });
+            continue;
+        }
+        if (!isRecord(value)) {
+            fail(context.rule, `${resource}.${key} is a to-many relation: use some, every or none`);
+        }
+        for (const [quantifier, sub] of Object.entries(value)) {
+            if (quantifier !== "some" &&
+                quantifier !== "every" &&
+                quantifier !== "none") {
+                fail(context.rule, `${resource}.${key}: unknown filter "${quantifier}" (some, every, none)`);
+            }
+            parts.push({
+                op: quantifier,
+                relation: key,
+                target: field.target,
+                where: compileWhere(context, field.target, sub),
+            });
+        }
+    }
+    return andOf(parts);
+};
+const claimTypeOf = (value) => typeof value === "string"
+    ? "string"
+    : typeof value === "number"
+        ? "number"
+        : typeof value === "boolean"
+            ? "boolean"
+            : undefined;
+const compileClaims = (rule, claims, types) => {
+    if (!isPlainObject(claims)) {
+        return fail(rule, "`claims` must be an object");
+    }
+    return Object.entries(claims).map(([claim, value]) => {
+        const scalar = claimTypeOf(value);
+        if (scalar === undefined ||
+            (typeof value === "number" && !Number.isFinite(value))) {
+            return fail(rule, `claim "${claim}" compares with a string, number or boolean`);
+        }
+        const known = types[claim];
+        if (known !== undefined && known.scalar !== scalar) {
+            fail(rule, `claim "${claim}" is compared as ${known.scalar} elsewhere and as ${scalar} here`);
+        }
+        types[claim] = { scalar };
+        return {
+            op: "cmp",
+            claim: [claim],
+            cmp: "eq",
+            value: value,
+        };
+    });
+};
+const principalAnd = (args) => args.length === 1
+    ? args[0]
+    : { op: "and", args };
+// ---------------------------------------------------------------------------
+// Rule ids
+// ---------------------------------------------------------------------------
+export const idAllocator = () => {
+    const seen = new Map();
+    const named = new Set();
+    return (prefix, name) => {
+        if (name !== undefined) {
+            if (typeof name !== "string" || name.length === 0) {
+                return fail(prefix, "`name` must be a non-empty string");
+            }
+            if (named.has(name)) {
+                return fail(name, "two rules have this name");
+            }
+            named.add(name);
+            return name;
+        }
+        const count = (seen.get(prefix) ?? 0) + 1;
+        seen.set(prefix, count);
+        return `${prefix}#${count}`;
+    };
+};
+// ---------------------------------------------------------------------------
+// Compile
+// ---------------------------------------------------------------------------
+const GRANT_OPTIONS = new Set([
+    "name",
+    "where",
+    "in",
+    "fields",
+    "write",
+    "after",
+]);
+const DENY_OPTIONS = new Set(["name", "where", "if"]);
+const compileRoles = (definition, claimTypes) => {
+    const roles = {};
+    for (const [name, role] of Object.entries(definition.roles)) {
+        const context = { schema: definition.schema, rule: `role "${name}"` };
+        if (BUILT_IN_SUBJECTS.has(name)) {
+            fail(context.rule, "is a built-in subject");
+        }
+        if (isRecord(role) && "global" in role) {
+            const global = role.global;
+            if (!isRecord(global) ||
+                Object.keys(global).some((key) => key !== "claims")) {
+                fail(context.rule, "a global role is `{ global: { claims } }`");
+            }
+            const claims = compileClaims(context.rule, global.claims, claimTypes);
+            if (claims.length === 0) {
+                fail(context.rule, "a global role compares at least one claim; `{ claims: {} }` would hold for everyone, anonymous included");
+            }
+            roles[name] = { global: principalAnd(claims) };
+            continue;
+        }
+        if (isRecord(role) && typeof role.on === "string") {
+            if (!Object.hasOwn(definition.schema.resources, role.on)) {
+                fail(context.rule, `unknown Resource "${role.on}"`);
+            }
+            roles[name] = {
+                on: role.on,
+                where: compileWhere(context, role.on, role.where),
+            };
+            continue;
+        }
+        fail(context.rule, "a role is `{ global: { claims } }` or `{ on, where }`");
+    }
+    return roles;
+};
+const compileGrant = (definition, rule, allocate) => {
+    const subjects = [...asList(rule.subjects)];
+    const actions = [...asList(rule.actions)];
+    const prefix = `${rule.resource}/${actions.join(",")}/${subjects.join(",")}`;
+    for (const key of Object.keys(rule.options)) {
+        if (!GRANT_OPTIONS.has(key)) {
+            fail(prefix, `unknown grant option "${key}"`);
+        }
+    }
+    const { name, where, in: inRelation, fields, write, after } = rule.options;
+    const id = allocate(prefix, name);
+    const context = { schema: definition.schema, rule: id };
+    const onResource = rule.resource === "*" ? undefined : rule.resource;
+    if (onResource === undefined &&
+        (where !== undefined ||
+            inRelation !== undefined ||
+            after !== undefined ||
+            write !== undefined)) {
+        fail(id, 'a grant on "*" takes no where, in, write or after');
+    }
+    let except;
+    if (write !== undefined) {
+        if (!isRecord(write) ||
+            !Array.isArray(write.except) ||
+            Object.keys(write).some((key) => key !== "except")) {
+            fail(id, "`write` is `{ except: [fields] }`");
+        }
+        except = [...write.except];
+    }
+    if (fields !== undefined && !Array.isArray(fields)) {
+        fail(id, "`fields` is a list of `Resource.field`");
+    }
+    if (inRelation !== undefined && typeof inRelation !== "string") {
+        fail(id, "`in` names a to-one relation");
+    }
+    return {
+        id,
+        subjects,
+        actions,
+        resource: rule.resource,
+        ...(inRelation !== undefined ? { in: inRelation } : {}),
+        ...(where !== undefined && onResource !== undefined
+            ? { where: compileWhere(context, onResource, where) }
+            : {}),
+        ...(fields !== undefined
+            ? { fields: [...fields] }
+            : {}),
+        ...(except !== undefined ? { write: { except } } : {}),
+        ...(after !== undefined && onResource !== undefined
+            ? { after: compileWhere(context, onResource, after) }
+            : {}),
+    };
+};
+const compileDeny = (definition, rule, allocate, claimTypes) => {
+    const actions = rule.actions === "*" ? "*" : [...asList(rule.actions)];
+    const prefix = `${rule.resource}/${actions === "*" ? "*" : actions.join(",")}/deny`;
+    for (const key of Object.keys(rule.options)) {
+        if (!DENY_OPTIONS.has(key)) {
+            fail(prefix, `unknown deny option "${key}"`);
+        }
+    }
+    const { name, where, if: condition } = rule.options;
+    const id = allocate(prefix, name);
+    const context = { schema: definition.schema, rule: id };
+    if (rule.resource === "*" && where !== undefined) {
+        fail(id, 'a deny on "*" takes no where');
+    }
+    const principal = condition === undefined
+        ? undefined
+        : compilePrincipalIf(id, condition, claimTypes);
+    return {
+        id,
+        actions,
+        resource: rule.resource,
+        ...(where !== undefined
+            ? { where: compileWhere(context, rule.resource, where) }
+            : {}),
+        ...(principal !== undefined ? { if: principal } : {}),
+    };
+};
+/**
+ * A rule's `if` (`{ claims?, origin? }`), compiled to a condition on the principal
+ * alone. Each claim's type is recorded in `claimTypes`, and a claim compared as two
+ * types is refused.
+ */
+export const compilePrincipalIf = (rule, condition, claimTypes) => {
+    if (!isRecord(condition) ||
+        Object.keys(condition).some((key) => key !== "claims" && key !== "origin")) {
+        fail(rule, "`if` is `{ claims?, origin? }`");
+    }
+    const { claims, origin } = condition;
+    const parts = [];
+    if (claims !== undefined) {
+        parts.push(...compileClaims(rule, claims, claimTypes));
+    }
+    if (origin !== undefined) {
+        if (!ORIGINS.includes(origin)) {
+            fail(rule, `unknown origin "${String(origin)}" (application, client, agent)`);
+        }
+        parts.push({ op: "origin", value: origin });
+    }
+    if (parts.length === 0) {
+        fail(rule, "`if` names no condition");
+    }
+    return principalAnd(parts);
+};
+/** Compiles the builder's rules to the `@1` policies file and checks it. */
+export const compilePolicies = (definition) => {
+    const claimTypes = {};
+    const roles = compileRoles(definition, claimTypes);
+    const allocate = idAllocator();
+    const grants = definition.grants.map((rule) => compileGrant(definition, rule, allocate));
+    const denies = definition.denies.map((rule) => compileDeny(definition, rule, allocate, claimTypes));
+    // Each governed field once, with one mode: "both" in `govern` alone, "read" or
+    // "write" in `governModes` too.
+    const govern = {};
+    const governModes = {};
+    for (const [resource, entries] of Object.entries(definition.govern)) {
+        const at = `govern("${resource}")`;
+        const modes = new Map();
+        for (const { field, mode } of entries) {
+            fieldOf({ schema: definition.schema, rule: at }, resource, field);
+            if (mode !== "read" && mode !== "write" && mode !== "both") {
+                fail(at, `"${field}" is ${JSON.stringify(mode)}; a mode is "read", "write" or "both"`);
+            }
+            const prior = modes.get(field);
+            if (prior !== undefined && prior !== mode) {
+                fail(at, `"${field}" is governed twice, as "${prior}" and as "${mode}"; govern each field once, with one mode`);
+            }
+            modes.set(field, mode);
+        }
+        govern[resource] = [...modes.keys()];
+        const moded = [...modes].filter(([, mode]) => mode !== "both");
+        if (moded.length > 0) {
+            governModes[resource] = Object.fromEntries(moded);
+        }
+    }
+    const policies = {
+        format: POLICIES_FORMAT,
+        ...(definition.namespace !== undefined
+            ? { namespace: definition.namespace }
+            : {}),
+        claims: Object.fromEntries(Object.entries(claimTypes).sort(([a], [b]) => a.localeCompare(b))),
+        schema: schemaFacts(definition.schema),
+        roles,
+        govern: govern,
+        ...(Object.keys(governModes).length > 0 ? { governModes } : {}),
+        grants,
+        denies,
+    };
+    checkPolicies(policies);
+    warnReadGovernedUnique(policies);
+    return policies;
+};
+// ---------------------------------------------------------------------------
+// Checks every policies file passes (a compiled one, or one loaded from JSON)
+// ---------------------------------------------------------------------------
+const walk = (predicate, visit, depth = 0) => {
+    visit(predicate, depth);
+    switch (predicate.op) {
+        case "and":
+        case "or":
+            for (const arg of predicate.args) {
+                walk(arg, visit, depth);
+            }
+            return;
+        case "not":
+            walk(predicate.arg, visit, depth);
+            return;
+        case "rel":
+        case "some":
+        case "every":
+        case "none":
+            walk(predicate.where, visit, depth + 1);
+            return;
+        default:
+            return;
+    }
+};
+/** Refuses a member of `node` that is not one of `keys`, naming the node. */
+const only = (rule, node, what, keys) => {
+    for (const key of Object.keys(node)) {
+        if (!keys.includes(key)) {
+            fail(rule, `"${key}" is not a member of ${what} (${keys.join(", ")})`);
+        }
+    }
+};
+const COMPARISONS = new Set(["eq", "ne", "in", "notIn"]);
+const isFiniteLiteral = (value) => value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value));
+/** Whether `value` is a non-empty list of non-empty strings. */
+const isPath = (value) => Array.isArray(value) &&
+    value.length > 0 &&
+    value.every((segment) => typeof segment === "string" && segment !== "");
+/**
+ * One operand of a comparison on `resource.field`: a finite literal in the form the
+ * compiler writes for the field's type, or a `me` value (`{ principal: [path] }`).
+ */
+const checkOperand = (rule, at, type, value) => {
+    if (isPlainObject(value)) {
+        only(rule, value, `${at}'s \`me\` value`, ["principal"]);
+        if (!isPath(value.principal)) {
+            fail(rule, `${at}: a \`me\` value is \`{ "principal": [path] }\`, a non-empty list of names`);
+        }
+        return;
+    }
+    if (!isFiniteLiteral(value)) {
+        fail(rule, `${at} compares with a string, a finite number, a boolean, null or a \`me\` value`);
+    }
+    if (value === null || type === undefined) {
+        return;
+    }
+    const canonical = type === "datetime"
+        ? typeof value === "string" &&
+            instantOf(value) !== undefined &&
+            new Date(value).toISOString() === value
+        : type === "decimal"
+            ? typeof value === "string" &&
+                value.length <= DECIMAL_TEXT_MAX &&
+                (() => {
+                    const parts = decimalParts(value);
+                    return parts !== undefined && decimalText(parts) === value;
+                })()
+            : typeof value === "number"
+                ? Number.isSafeInteger(value)
+                : typeof value === "string" &&
+                    /^-?[1-9]\d*$/.test(value) &&
+                    !Number.isSafeInteger(Number(value));
+    if (!canonical) {
+        fail(rule, `${at} is a ${type} field: it compares with ${type === "datetime" ? "an instant as toISOString() writes it" : type === "decimal" ? "a decimal string with no exponent and no leading or trailing zero" : "a safe integer, or the digits of a bigint past it"}; it was ${JSON.stringify(value)}`);
+    }
+};
+/**
+ * Checks a predicate member by member, and its Resources, fields, relations and role
+ * references against the file's own schema facts, starting at `resource`.
+ */
+const checkPredicate = (policies, rule, resource, predicate) => {
+    const facts = ownOf(policies.schema, resource) ??
+        fail(rule, `unknown Resource "${resource}"`);
+    if (!isPlainObject(predicate)) {
+        fail(rule, `a condition on ${resource} is an object`);
+    }
+    const node = predicate;
+    const what = `a "${String(node.op)}" condition`;
+    switch (predicate.op) {
+        case "true":
+        case "false":
+            only(rule, node, what, ["op"]);
+            return;
+        case "and":
+        case "or":
+            only(rule, node, what, ["op", "args"]);
+            if (!Array.isArray(node.args)) {
+                fail(rule, `${what} takes an \`args\` list`);
+            }
+            for (const arg of predicate.args) {
+                checkPredicate(policies, rule, resource, arg);
+            }
+            return;
+        case "not":
+            only(rule, node, what, ["op", "arg"]);
+            checkPredicate(policies, rule, resource, predicate.arg);
+            return;
+        case "cmp": {
+            only(rule, node, what, ["op", "field", "cmp", "value"]);
+            const field = String(predicate.field);
+            if (typeof predicate.field !== "string" ||
+                !facts.fields.includes(field) ||
+                ownOf(facts.relations, field) !== undefined) {
+                fail(rule, `${resource} has no scalar field "${field}"`);
+            }
+            const at = `${resource}.${field}`;
+            if (!COMPARISONS.has(predicate.cmp)) {
+                fail(rule, `${at}: unknown comparison ${JSON.stringify(predicate.cmp)} (eq, ne, in, notIn)`);
+            }
+            const type = ownOf(facts.types, field);
+            const list = predicate.cmp === "in" || predicate.cmp === "notIn";
+            if (list !== Array.isArray(predicate.value)) {
+                fail(rule, list
+                    ? `${at}: "${predicate.cmp}" compares with a list`
+                    : `${at}: "${predicate.cmp}" compares with one value, not a list`);
+            }
+            for (const operand of list
+                ? predicate.value
+                : [predicate.value]) {
+                checkOperand(rule, at, type, operand);
+            }
+            return;
+        }
+        case "rel":
+        case "some":
+        case "every":
+        case "none": {
+            only(rule, node, what, ["op", "relation", "target", "where"]);
+            const relation = typeof predicate.relation === "string"
+                ? ownOf(facts.relations, predicate.relation)
+                : undefined;
+            if (relation === undefined || relation.target !== predicate.target) {
+                fail(rule, `${resource} has no relation "${String(predicate.relation)}" to ${String(predicate.target)}`);
+            }
+            const expected = predicate.op === "rel" ? "one" : "many";
+            if (relation?.cardinality !== expected) {
+                fail(rule, `${resource}.${predicate.relation} is to-${relation?.cardinality}; "${predicate.op}" needs to-${expected}`);
+            }
+            checkPredicate(policies, rule, predicate.target, predicate.where);
+            return;
+        }
+        case "role": {
+            only(rule, node, what, ["op", "role"]);
+            const role = (typeof predicate.role === "string"
+                ? ownOf(policies.roles, predicate.role)
+                : undefined) ??
+                fail(rule, `unknown role "${String(predicate.role)}"`);
+            if (!("on" in role)) {
+                fail(rule, `$role "${predicate.role}" is a global role; $role names a role held on a row`);
+            }
+            if ("on" in role && role.on !== resource) {
+                fail(rule, `$role "${predicate.role}" is held on ${role.on}, not on ${resource}`);
+            }
+            return;
+        }
+        default:
+            fail(rule, `unknown condition ${JSON.stringify(node.op)} (true, false, and, or, not, cmp, rel, some, every, none, role)`);
+    }
+};
+/** The roles a predicate references directly (not through other roles). */
+const rolesIn = (predicate) => {
+    const found = [];
+    walk(predicate, (node) => {
+        if (node.op === "role") {
+            found.push(node.role);
+        }
+    });
+    return found;
+};
+const checkRoleCycles = (policies) => {
+    const state = new Map();
+    const visit = (role, trail) => {
+        if (state.get(role) === "done") {
+            return;
+        }
+        if (state.get(role) === "visiting") {
+            fail(`role "${role}"`, `role cycle: ${[...trail, role].join(" → ")}`);
+        }
+        state.set(role, "visiting");
+        const definition = ownOf(policies.roles, role);
+        if (definition !== undefined && "on" in definition) {
+            for (const next of rolesIn(definition.where)) {
+                visit(next, [...trail, role]);
+            }
+        }
+        state.set(role, "done");
+    };
+    for (const role of Object.keys(policies.roles)) {
+        visit(role, []);
+    }
+};
+/**
+ * A created row carries its reference fields, never its relations: a to-one step
+ * at the row's own level is asked through `exists` on the target, which needs the
+ * relation's `references`. Without them the rule is refused.
+ * Roles are followed, since a role's condition is part of the rule.
+ */
+const checkCreateReferences = (policies, rule, resource, predicate, seenRoles = new Set()) => {
+    walk(predicate, (node, depth) => {
+        if (depth !== 0) {
+            return;
+        }
+        if (node.op === "rel") {
+            const relation = ownOf(ownOf(policies.schema, resource)?.relations, node.relation);
+            if (relation?.references === undefined ||
+                relation.referenceFields === undefined) {
+                fail(rule, `a create rule goes through ${resource}.${node.relation}, whose references discovery does not state; Access never guesses them (needs @aventara/* rc.5 and a regenerated discovery artifact)`);
+            }
+        }
+        if (node.op === "role" && !seenRoles.has(node.role)) {
+            const role = ownOf(policies.roles, node.role);
+            if (role !== undefined && "on" in role) {
+                checkCreateReferences(policies, rule, resource, role.where, new Set([...seenRoles, node.role]));
+            }
+        }
+    });
+};
+/**
+ * A condition on the principal, member by member: a non-empty `and`, an `origin`, or
+ * an `eq` on one claim the file's `claims` block declares, with a value of its type.
+ */
+const checkPrincipalCondition = (rule, condition, claims) => {
+    if (!isPlainObject(condition)) {
+        fail(rule, "a condition on the principal is an object");
+    }
+    const node = condition;
+    const what = `a "${String(node.op)}" condition on the principal`;
+    switch (condition.op) {
+        case "and":
+            only(rule, node, what, ["op", "args"]);
+            if (!Array.isArray(node.args) || node.args.length === 0) {
+                fail(rule, 'an "and" condition takes a non-empty `args` list: an empty one would hold for everyone');
+            }
+            for (const arg of condition.args) {
+                checkPrincipalCondition(rule, arg, claims);
+            }
+            return;
+        case "origin":
+            only(rule, node, what, ["op", "value"]);
+            if (!ORIGINS.includes(condition.value)) {
+                fail(rule, `unknown origin ${JSON.stringify(condition.value)} (application, client, agent)`);
+            }
+            return;
+        case "cmp": {
+            only(rule, node, what, ["op", "claim", "cmp", "value"]);
+            const path = condition.claim;
+            if (!Array.isArray(path) ||
+                path.length !== 1 ||
+                typeof path[0] !== "string") {
+                fail(rule, 'a claim comparison names one claim: `"claim": ["<name>"]`');
+            }
+            const claim = path[0];
+            if (condition.cmp !== "eq") {
+                fail(rule, `a claim comparison is "eq"; it was ${JSON.stringify(condition.cmp)}`);
+            }
+            const value = condition.value;
+            if (typeof value !== "string" &&
+                typeof value !== "boolean" &&
+                !(typeof value === "number" && Number.isFinite(value))) {
+                fail(rule, `claim "${claim}" compares with a string, a finite number or a boolean`);
+            }
+            const declared = ownOf(claims, claim);
+            if (declared === undefined) {
+                fail(rule, `compares the claim "${claim}", which the file's "claims" block does not list`);
+            }
+            if (declared?.scalar !== typeof value) {
+                fail(rule, `compares the claim "${claim}" with a ${typeof value}, and the file's "claims" block lists it as ${declared?.scalar}`);
+            }
+            return;
+        }
+        default:
+            fail(rule, `unknown condition ${JSON.stringify(node.op)}: a condition on the principal is "and", "cmp" on a claim, or "origin"`);
+    }
+};
+export const checkActions = (rule, actions) => {
+    if (actions.length === 0) {
+        fail(rule, "names no action");
+    }
+    for (const action of actions) {
+        if (!ACTIONS.includes(action)) {
+            fail(rule, `unknown action "${action}" (read, create, update, delete)`);
+        }
+    }
+};
+/** The subject condition of a grant, as a predicate on its Resource (for the create-reference check). */
+const subjectPredicate = (policies, grant, subject) => {
+    const role = ownOf(policies.roles, subject);
+    if (role === undefined || !("on" in role)) {
+        return undefined;
+    }
+    if (grant.in !== undefined) {
+        return {
+            op: "rel",
+            relation: grant.in,
+            target: role.on,
+            where: { op: "role", role: subject },
+        };
+    }
+    return { op: "role", role: subject };
+};
+const GRANT_KEYS = [
+    "id",
+    "subjects",
+    "actions",
+    "resource",
+    "in",
+    "where",
+    "fields",
+    "write",
+    "after",
+];
+const DENY_KEYS = ["id", "actions", "resource", "where", "if"];
+/** Whether `value` is a list of strings. */
+const isNames = (value) => Array.isArray(value) && value.every((name) => typeof name === "string");
+/** A rule's members and their types, before what they name is checked. */
+const checkRuleShape = (rule, index, kind) => {
+    const at = `${kind} ${index + 1}`;
+    if (!isPlainObject(rule)) {
+        return fail(at, `a ${kind} is an object`);
+    }
+    if (typeof rule.id !== "string" || rule.id === "") {
+        return fail(at, "`id` is a non-empty string");
+    }
+    const id = rule.id;
+    only(id, rule, `a ${kind}`, kind === "grant" ? GRANT_KEYS : DENY_KEYS);
+    if (typeof rule.resource !== "string" || rule.resource === "") {
+        fail(id, '`resource` is a Resource name or "*"');
+    }
+    if (kind === "grant"
+        ? !isNames(rule.actions)
+        : rule.actions !== "*" && !isNames(rule.actions)) {
+        fail(id, kind === "grant"
+            ? "`actions` is a list of actions"
+            : '`actions` is "*" or a list of actions');
+    }
+    if (kind === "deny") {
+        return id;
+    }
+    if (!isNames(rule.subjects)) {
+        fail(id, "`subjects` is a list of subjects");
+    }
+    if (rule.in !== undefined && typeof rule.in !== "string") {
+        fail(id, "`in` names a to-one relation");
+    }
+    if (rule.fields !== undefined && !isNames(rule.fields)) {
+        fail(id, "`fields` is a list of `Resource.field`");
+    }
+    if (rule.write !== undefined &&
+        !(isPlainObject(rule.write) &&
+            Object.keys(rule.write).every((key) => key === "except") &&
+            isNames(rule.write.except))) {
+        fail(id, "`write` is `{ except: [fields] }`");
+    }
+    return id;
+};
+const checkGrant = (policies, grant) => {
+    const rule = grant.id;
+    checkActions(rule, grant.actions);
+    if (grant.subjects.length === 0) {
+        fail(rule, "names no subject");
+    }
+    const star = grant.resource === "*";
+    if (!star && ownOf(policies.schema, grant.resource) === undefined) {
+        fail(rule, `unknown Resource "${grant.resource}"`);
+    }
+    const owner = star
+        ? undefined
+        : ownOf(policies.schema, grant.resource)?.foreign;
+    if (owner !== undefined) {
+        fail(rule, `grants on ${grant.resource}, which namespace "${owner}" owns (foreign). A file reads a foreign Resource in conditions and never grants on it; ask "${owner}" to add the grant`);
+    }
+    for (const subject of grant.subjects) {
+        if (BUILT_IN_SUBJECTS.has(subject)) {
+            if (grant.in !== undefined) {
+                fail(rule, `\`in\` needs every subject to be a role held on a row; "${subject}" is not`);
+            }
+            continue;
+        }
+        const role = ownOf(policies.roles, subject) ??
+            fail(rule, `unknown subject "${subject}"`);
+        if ("global" in role) {
+            if (grant.in !== undefined) {
+                fail(rule, `\`in\` needs every subject to be a role held on a row; "${subject}" is global`);
+            }
+            continue;
+        }
+        if (star) {
+            fail(rule, `"${subject}" is held on ${role.on}; a grant on "*" takes global roles and built-in subjects only`);
+        }
+        if (grant.in === undefined) {
+            if (role.on !== grant.resource) {
+                fail(rule, `"${subject}" is held on ${role.on}; on ${grant.resource} name the relation that leads there with \`in\``);
+            }
+            continue;
+        }
+        const relation = ownOf(ownOf(policies.schema, grant.resource)?.relations, grant.in);
+        if (relation === undefined || relation.cardinality !== "one") {
+            fail(rule, `\`in: "${grant.in}"\` is not a to-one relation of ${grant.resource}`);
+        }
+        if (relation?.target !== role.on) {
+            fail(rule, `\`in: "${grant.in}"\` leads to ${relation?.target}, but "${subject}" is held on ${role.on}`);
+        }
+    }
+    if (grant.where !== undefined) {
+        checkPredicate(policies, rule, grant.resource, grant.where);
+    }
+    if (grant.after !== undefined) {
+        if (!grant.actions.includes("update")) {
+            fail(rule, "`after` applies to updates; this grant names no update");
+        }
+        checkPredicate(policies, rule, grant.resource, grant.after);
+    }
+    if (grant.write !== undefined) {
+        if (!grant.actions.includes("create") &&
+            !grant.actions.includes("update")) {
+            fail(rule, "`write.except` applies to creates and updates; this grant names neither");
+        }
+        for (const field of grant.write.except) {
+            if (!ownOf(policies.schema, grant.resource)?.fields.includes(field)) {
+                fail(rule, `write.except: ${grant.resource} has no field "${field}"`);
+            }
+        }
+    }
+    for (const ref of grant.fields ?? []) {
+        const [resource, field, ...rest] = ref.split(".");
+        if (resource === undefined || field === undefined || rest.length > 0) {
+            fail(rule, `fields: "${ref}" is not \`Resource.field\``);
+        }
+        if (!star && resource !== grant.resource) {
+            fail(rule, `fields: "${ref}" is not a field of ${grant.resource}`);
+        }
+        const fieldOwner = ownOf(policies.schema, resource)?.foreign;
+        if (fieldOwner !== undefined) {
+            fail(rule, `fields: "${ref}" opens a field of ${resource}, which namespace "${fieldOwner}" owns (foreign); a file never grants on a foreign Resource`);
+        }
+        if (!(ownOf(policies.govern, resource) ?? []).includes(field)) {
+            fail(rule, `fields: "${ref}" is not governed; only governed fields are named in a grant`);
+        }
+    }
+    if (grant.actions.includes("create") && !star) {
+        const parts = [
+            grant.where,
+            ...grant.subjects.map((subject) => subjectPredicate(policies, grant, subject)),
+        ];
+        for (const part of parts) {
+            if (part !== undefined) {
+                checkCreateReferences(policies, rule, grant.resource, part);
+            }
+        }
+    }
+};
+const checkDeny = (policies, deny) => {
+    const rule = deny.id;
+    if (deny.actions !== "*") {
+        checkActions(rule, deny.actions);
+    }
+    if (deny.resource !== "*" &&
+        ownOf(policies.schema, deny.resource) === undefined) {
+        fail(rule, `unknown Resource "${deny.resource}"`);
+    }
+    const owner = deny.resource === "*"
+        ? undefined
+        : ownOf(policies.schema, deny.resource)?.foreign;
+    if (owner !== undefined) {
+        fail(rule, `denies on ${deny.resource}, which namespace "${owner}" owns (foreign). A file's denies narrow only its own Resources; narrowing another namespace's is an org guardrail`);
+    }
+    if (deny.where !== undefined) {
+        if (deny.resource === "*") {
+            fail(rule, 'a deny on "*" takes no where');
+        }
+        checkPredicate(policies, rule, deny.resource, deny.where);
+        if (deny.actions === "*" || deny.actions.includes("create")) {
+            checkCreateReferences(policies, rule, deny.resource, deny.where);
+        }
+    }
+    if (deny.if !== undefined) {
+        checkPrincipalCondition(rule, deny.if, policies.claims);
+    }
+};
+/** The format, the namespace, the members of the file and of its schema entries, and the claim types. */
+const checkShape = (policies) => {
+    if (!isRecord(policies)) {
+        fail("policies", "a policies file is a JSON object");
+    }
+    const format = policies.format;
+    if (format === RETIRED_POLICIES_FORMAT) {
+        fail("policies", `this file is "${RETIRED_POLICIES_FORMAT}", a format Access no longer reads. Compile the rules again with definePolicies(model).contract() to get an "${POLICIES_FORMAT}" file`);
+    }
+    if (format !== POLICIES_FORMAT) {
+        fail("policies", `format is ${JSON.stringify(format) ?? "missing"}, expected "${POLICIES_FORMAT}"`);
+    }
+    for (const key of Object.keys(policies)) {
+        if (!FILE_KEYS.has(key)) {
+            fail("policies", `"${key}" is not a member of ${POLICIES_FORMAT}`);
+        }
+    }
+    const namespace = policies.namespace;
+    if (namespace !== undefined && !isNamespace(namespace)) {
+        fail("policies", `namespace ${JSON.stringify(namespace)} is not a namespace name (a lowercase letter, then lowercase letters, digits, "_" or "-"; at most 63 characters)`);
+    }
+    for (const block of ["claims", "schema", "roles", "govern"]) {
+        if (!isRecord(policies[block])) {
+            fail("policies", `"${block}" is an object`);
+        }
+    }
+    if (policies.governModes !== undefined && !isRecord(policies.governModes)) {
+        fail("policies", '"governModes" is an object');
+    }
+    // One set of rules, one file: a file whose fields are all governed for both
+    // leaves the member out.
+    if (policies.governModes !== undefined &&
+        Object.keys(policies.governModes).length === 0) {
+        fail("policies", '"governModes" names at least one Resource; a file whose governed fields are all governed for both has no "governModes"');
+    }
+    for (const block of ["grants", "denies"]) {
+        if (!Array.isArray(policies[block])) {
+            fail("policies", `"${block}" is a list`);
+        }
+    }
+    for (const [claim, type] of Object.entries(policies.claims)) {
+        if (!isRecord(type) ||
+            Object.keys(type).some((key) => key !== "scalar") ||
+            !CLAIM_SCALARS.includes(type.scalar)) {
+            fail(`claim "${claim}"`, 'a claim\'s type is { "scalar": "string" | "number" | "boolean" }');
+        }
+    }
+    for (const [resource, facts] of Object.entries(policies.schema)) {
+        if (!isRecord(facts)) {
+            fail(`schema "${resource}"`, "a schema entry is an object");
+        }
+        for (const key of Object.keys(facts)) {
+            if (!SCHEMA_ENTRY_KEYS.has(key)) {
+                fail(`schema "${resource}"`, `"${key}" is not a member of a schema entry (identifiers, fields, nullable, types, relations, foreign)`);
+            }
+        }
+        checkFacts(resource, facts);
+        checkNullable(resource, facts);
+        checkTypes(resource, facts);
+        const owner = facts.foreign;
+        if (owner === undefined) {
+            continue;
+        }
+        if (!isNamespace(owner)) {
+            fail(`schema "${resource}"`, `foreign ${JSON.stringify(owner)} is not a namespace name`);
+        }
+        if (owner === namespace) {
+            fail(`schema "${resource}"`, `is marked foreign to namespace "${owner}", which is this file's own namespace`);
+        }
+    }
+    checkRelationTargets(policies);
+};
+/**
+ * A schema entry's `nullable`: a non-empty list of its own scalar fields, each named
+ * once. An entry without it has no nullable field, so each meaning has one encoding.
+ */
+const checkNullable = (resource, facts) => {
+    const nullable = facts.nullable;
+    if (nullable === undefined) {
+        return;
+    }
+    if (!Array.isArray(nullable) ||
+        nullable.some((field) => typeof field !== "string")) {
+        fail(`schema "${resource}"`, "nullable is a list of field names");
+    }
+    if (nullable.length === 0) {
+        fail(`schema "${resource}"`, "nullable is never empty: an entry with no nullable field has no nullable member");
+    }
+    const seen = [];
+    for (const field of nullable) {
+        if (!Array.isArray(facts.fields) ||
+            !facts.fields.includes(field) ||
+            (isRecord(facts.relations) && field in facts.relations)) {
+            fail(`schema "${resource}"`, `nullable names "${field}", which is not a scalar field of ${resource}`);
+        }
+        if (seen.includes(field)) {
+            fail(`schema "${resource}"`, `nullable names "${field}" twice`);
+        }
+        seen.push(field);
+    }
+};
+/** A schema entry's identifiers, fields and relations, member by member. */
+const checkFacts = (resource, facts) => {
+    const at = `schema "${resource}"`;
+    checkName(at, "a Resource", resource);
+    if (!isNames(facts.fields)) {
+        fail(at, "fields is a list of field names");
+    }
+    for (const field of facts.fields) {
+        checkName(at, "a field", field);
+    }
+    if (!Array.isArray(facts.identifiers) ||
+        !facts.identifiers.every((identifier) => isNames(identifier) &&
+            identifier.every((field) => facts.fields.includes(field)))) {
+        fail(at, "identifiers is a list of lists of its own field names");
+    }
+    if (!isPlainObject(facts.relations)) {
+        fail(at, "relations is an object");
+    }
+    for (const [name, fact] of Object.entries(facts.relations)) {
+        const where = `${at}: relation "${name}"`;
+        if (!facts.fields.includes(name)) {
+            fail(where, "is not one of the entry's fields");
+        }
+        if (!isPlainObject(fact)) {
+            fail(where, "is an object");
+        }
+        const relation = fact;
+        only(where, relation, "a relation", [
+            "target",
+            "cardinality",
+            "referenceFields",
+            "references",
+        ]);
+        if (typeof relation.target !== "string" ||
+            (relation.cardinality !== "one" && relation.cardinality !== "many")) {
+            fail(where, 'is `{ target, cardinality: "one" | "many" }`');
+        }
+        const pairs = [relation.referenceFields, relation.references];
+        if (pairs.some((list) => list !== undefined) &&
+            !(isPath(relation.referenceFields) &&
+                isPath(relation.references) &&
+                relation.referenceFields.length === relation.references.length)) {
+            fail(where, "referenceFields and references are two lists of field names of the same length, or neither is there");
+        }
+        for (const field of isPath(relation.referenceFields)
+            ? relation.referenceFields
+            : []) {
+            if (!facts.fields.includes(field) ||
+                ownOf(facts.relations, field) !== undefined) {
+                fail(where, `referenceFields names "${field}", which is not a scalar field of ${resource}`);
+            }
+        }
+    }
+};
+/**
+ * A relation's `references` are fields of its target. A target the schema does not
+ * list is left alone here (an author may trim the model); a rule that steps there is
+ * refused as an unknown Resource.
+ */
+const checkRelationTargets = (policies) => {
+    for (const [resource, facts] of Object.entries(policies.schema)) {
+        for (const [name, relation] of Object.entries(facts.relations)) {
+            const where = `schema "${resource}": relation "${name}"`;
+            const target = ownOf(policies.schema, relation.target);
+            if (target === undefined) {
+                continue;
+            }
+            for (const field of relation.references ?? []) {
+                if (!target.fields.includes(field)) {
+                    fail(where, `references names "${field}", which is not a field of ${relation.target}`);
+                }
+            }
+        }
+    }
+};
+/** A name a file uses for a Resource or a field: an identifier, never `__proto__`. */
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Whether `value` is a name a file may give a Resource or a field. */
+export const isName = (value) => typeof value === "string" && NAME.test(value) && value !== "__proto__";
+const checkName = (at, what, name) => {
+    if (!isName(name)) {
+        fail(at, `${JSON.stringify(name)} is not ${what} name: a name is a letter or "_", then letters, digits or "_", and never "__proto__"`);
+    }
+};
+/**
+ * A schema entry's `types`: a non-empty map of its own scalar fields to `bigint`,
+ * `datetime` or `decimal`. An entry without it has none of them.
+ */
+const checkTypes = (resource, facts) => {
+    const types = facts.types;
+    if (types === undefined) {
+        return;
+    }
+    const at = `schema "${resource}"`;
+    if (!isPlainObject(types) || Object.keys(types).length === 0) {
+        fail(at, "types is never empty: an entry with no bigint, datetime or decimal field has no types member");
+    }
+    for (const [field, type] of Object.entries(types)) {
+        if (!facts.fields.includes(field) ||
+            ownOf(facts.relations, field) !== undefined) {
+            fail(at, `types names "${field}", which is not a scalar field of ${resource}`);
+        }
+        if (typeof type !== "string" || !COMPARED_TYPES.has(type)) {
+            fail(at, `types: "${field}" is ${JSON.stringify(type)}; a type there is "bigint", "datetime" or "decimal"`);
+        }
+    }
+};
+/**
+ * A governed relation seals its reference fields, and a governed reference field its
+ * relation: reading either one tells the other. So `govern` names both or neither.
+ */
+const checkGovernPairs = (policies, resource) => {
+    const relations = ownOf(policies.schema, resource)?.relations ?? {};
+    const read = governedFor(policies, resource, "read");
+    const write = governedFor(policies, resource, "write");
+    for (const [relation, fact] of Object.entries(relations)) {
+        const references = fact.referenceFields ?? [];
+        if (references.length === 0) {
+            continue;
+        }
+        const pair = [relation, ...references];
+        // Checked for each access: reading either one tells the other, and writing
+        // either one sets the other.
+        const gapIn = (fields) => {
+            const named = pair.filter((field) => fields.includes(field));
+            return named.length > 0 && named.length < pair.length ? named : undefined;
+        };
+        const readGap = gapIn(read);
+        const writeGap = gapIn(write);
+        const named = readGap ?? writeGap;
+        if (named === undefined) {
+            continue;
+        }
+        const fields = readGap !== undefined ? read : write;
+        const missing = pair.filter((field) => !fields.includes(field));
+        const access = readGap !== undefined &&
+            writeGap !== undefined &&
+            readGap.join() === writeGap.join()
+            ? ""
+            : readGap !== undefined
+                ? " for reading"
+                : " for writing";
+        fail(`govern("${resource}")`, `governs ${named.map((field) => `"${field}"`).join(", ")} and not ${missing.map((field) => `"${field}"`).join(", ")}${access}: the relation "${relation}" and its reference fields (${references.join(", ")}) each tell the other, so govern them together`);
+    }
+};
+/**
+ * `governModes`: each entry a Resource's fields `govern` lists, each `"read"` or
+ * `"write"`; a field governed for both has no entry, so one set of rules has one file.
+ */
+const checkGovernModes = (policies) => {
+    for (const [resource, modes] of Object.entries(policies.governModes ?? {})) {
+        const at = `governModes("${resource}")`;
+        if (!isRecord(modes)) {
+            fail(at, 'an entry is an object of fields to "read" or "write"');
+        }
+        if (Object.keys(modes).length === 0) {
+            fail(at, "an entry names at least one field");
+        }
+        const governed = ownOf(policies.govern, resource) ?? [];
+        for (const [field, mode] of Object.entries(modes)) {
+            if (!governed.includes(field)) {
+                fail(at, `"${field}" is not governed; govern("${resource}") lists every governed field`);
+            }
+            if (mode !== "read" && mode !== "write") {
+                fail(at, `"${field}" is ${JSON.stringify(mode)}; a mode there is "read" or "write" (a field governed for both has no entry)`);
+            }
+        }
+    }
+};
+/** Whether `value` is a namespace name. */
+export const isNamespace = (value) => typeof value === "string" && NAMESPACE.test(value);
+/**
+ * The prefixes of the deny ids the engine composes itself: the org's guardrails and
+ * the built-in rules over Better Auth's tables. A file's own deny never takes one.
+ */
+const RESERVED_IDS = ["guardrail:", "better-auth:"];
+/**
+ * Checks a policies file before an engine runs from it. Throws an `Error` naming
+ * the rule. The file is trusted for nothing it can be checked for. `composed`: the
+ * file the engine composed itself, whose denies may take the reserved ids.
+ */
+export const checkPolicies = (policies, composed = false) => {
+    checkShape(policies);
+    for (const [name, role] of Object.entries(policies.roles)) {
+        const rule = `role "${name}"`;
+        if (BUILT_IN_SUBJECTS.has(name)) {
+            fail(rule, "is a built-in subject");
+        }
+        if (!isPlainObject(role)) {
+            fail(rule, "a role is `{ global }` or `{ on, where }`");
+        }
+        if ("global" in role) {
+            only(rule, role, "a global role", ["global"]);
+            checkPrincipalCondition(rule, role.global, policies.claims);
+        }
+        else {
+            only(rule, role, "a role held on a row", ["on", "where"]);
+            if (typeof role.on !== "string") {
+                fail(rule, "`on` names the Resource the role is held on");
+            }
+            checkPredicate(policies, rule, role.on, role.where);
+        }
+    }
+    checkRoleCycles(policies);
+    for (const [resource, fields] of Object.entries(policies.govern)) {
+        const at = `govern("${resource}")`;
+        if (!isNames(fields)) {
+            fail(at, "a governed list is a list of field names");
+        }
+        const facts = ownOf(policies.schema, resource) ??
+            fail(at, `unknown Resource "${resource}"`);
+        if (facts.foreign !== undefined) {
+            fail(at, `${resource} is namespace "${facts.foreign}"'s (foreign); only the owner governs a Resource's fields`);
+        }
+        for (const field of fields) {
+            if (!facts.fields.includes(field)) {
+                fail(at, `${resource} has no field "${field}"`);
+            }
+        }
+    }
+    checkGovernModes(policies);
+    for (const resource of Object.keys(policies.govern)) {
+        checkGovernPairs(policies, resource);
+    }
+    policies.grants.forEach((grant, index) => {
+        checkRuleShape(grant, index, "grant");
+    });
+    policies.denies.forEach((deny, index) => {
+        checkRuleShape(deny, index, "deny");
+    });
+    const ids = new Set();
+    for (const rule of [...policies.grants, ...policies.denies]) {
+        if (ids.has(rule.id)) {
+            fail(rule.id, "two rules have this id");
+        }
+        ids.add(rule.id);
+        if (!composed &&
+            RESERVED_IDS.some((prefix) => rule.id.startsWith(prefix))) {
+            fail(rule.id, `the id is reserved: "guardrail:" and "better-auth:" name the denies the engine adds itself (the org's guardrails, Better Auth's tables)`);
+        }
+    }
+    for (const grant of policies.grants) {
+        checkGrant(policies, grant);
+    }
+    for (const deny of policies.denies) {
+        checkDeny(policies, deny);
+    }
+};