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

package/dist/policies.decider.d.ts

@@ -0,0 +1,103 @@
+import { type AccessWhere } from "./aventara-where.translator.js";
+import type { AccessAction, AccessOrigin, AccessPolicies } from "./policies-contract.js";
+import { type AccessExists, type AccessLookup, type AccessRow } from "./predicate.evaluator.js";
+import { type FoldedDeny, type FoldedGrant } from "./scope.resolver.js";
+/** What every question states. */
+export type AccessQuestion = {
+    /** What the host derived for the request: an object, or `null` (anonymous). */
+    readonly principal: unknown;
+    readonly origin: AccessOrigin;
+    readonly resource: string;
+};
+/** `can`: without a row, admission; with one, the row a create inserts or an update leaves. */
+export type AccessCanQuestion = AccessQuestion & {
+    readonly action: AccessAction;
+    readonly row?: AccessRow;
+    /**
+     * On an update with a `row` only: the row as it was before the update. One update
+     * grant must then cover both rows, its `where` this one and its `where` and
+     * `after` the row the update leaves. Without it, any update grant that covers the
+     * row the update leaves lets it in. Read nowhere else.
+     */
+    readonly before?: AccessRow;
+    /**
+     * On an update with a `row` only: what `grantsOf` answered about the row before the
+     * update, asked before the write. The grant that covers `row` (its `where` and
+     * `after`) must then be one of these. With `before` too, each such grant's `where`
+     * is checked on `before` in memory, so a list from another row or principal fails
+     * on a scalar condition; a relation condition on it is not asked again: it was
+     * decided before anything the update wrote. Read nowhere else.
+     */
+    readonly beforeGrants?: readonly string[];
+    readonly exists?: AccessExists;
+};
+/**
+ * `grantsOf`: the update grants that cover `row`, the row an update will change, as it
+ * is now. Ask it before the write, and hand its answer back to `can` as `beforeGrants`.
+ */
+export type AccessGrantsQuestion = AccessQuestion & {
+    readonly action: "update";
+    readonly row: AccessRow;
+    readonly exists?: AccessExists;
+};
+/** `scopeOf`: the rows the principal may read, update or delete. */
+export type AccessScopeQuestion = AccessQuestion & {
+    readonly action: "read" | "update" | "delete";
+};
+/** `fieldsOf`: reading, or writing by one action. */
+export type AccessFieldsQuestion = AccessQuestion & ({
+    readonly access: "read";
+} | {
+    readonly access: "write";
+    readonly action?: "create" | "update";
+});
+/** `fieldsOf`'s answer: fields usable on every reachable row, and fields usable on some rows. */
+export type AccessFields = {
+    readonly always: "all" | readonly string[];
+    readonly perRow: {
+        readonly [field: string]: AccessWhere;
+    };
+};
+/** How one rule took part in a decision. */
+export type AccessRuleOutcome = "matched" | "not matched" | "unknown" | "not asked";
+/** How each rule took part in one `can` decision, and the `exists` lookups it made. */
+export type DecisionTrace = {
+    readonly grants: Map<FoldedGrant, AccessRuleOutcome>;
+    readonly denies: Map<FoldedDeny, AccessRuleOutcome>;
+    readonly lookups: AccessLookup[];
+};
+/** A trace with nothing in it yet. */
+export declare const newTrace: () => DecisionTrace;
+/**
+ * The Resources where the row an update leaves can fail what allowed the update:
+ * an update grant whose condition reads the row (a `where`, an `after`, a role held
+ * on a row), or an update deny with a `where`. Core asks `can` about each row such
+ * an update changed, and refuses these updates where it has no interactive
+ * transaction to roll one back in.
+ */
+export declare const afterChecksOf: (policies: AccessPolicies) => Record<string, "update"[]>;
+/**
+ * What is wrong with a `fieldsOf` question the types rule out but a caller can still
+ * send, or `undefined`: answered as asked, it would read as a read, or as no field.
+ */
+export declare const fieldsQuestionProblem: (question: AccessFieldsQuestion) => string | undefined;
+/**
+ * What is wrong with a `grantsOf` question the types rule out but a caller can still
+ * send, or `undefined`: it asks about an update, and nothing else.
+ */
+export declare const grantsQuestionProblem: (question: AccessGrantsQuestion) => string | undefined;
+/** The questions a policies file answers. */
+export type PoliciesDecider = {
+    /** `can`, recording each rule's part in the answer in `trace`. */
+    can(question: AccessCanQuestion, trace: DecisionTrace): boolean | Promise<boolean>;
+    /**
+     * The keys of the update grants whose `where`, and their subject's row condition,
+     * hold on `row` as it is now: opaque and stable for this file, never rule data.
+     * None when an update deny is decided on `row` in memory.
+     */
+    grantsOf(question: AccessGrantsQuestion): readonly string[] | Promise<readonly string[]>;
+    scopeOf(question: AccessScopeQuestion): boolean | AccessWhere;
+    fieldsOf(question: AccessFieldsQuestion): AccessFields;
+};
+/** The decisions of one policies file, already checked. */
+export declare const createDecider: (file: AccessPolicies) => PoliciesDecider;

package/dist/policies.decider.js

@@ -0,0 +1,390 @@
+// The decisions a policies file makes: `can`, `grantsOf`, `scopeOf` and `fieldsOf`,
+// answered from the file alone. Default deny, any grant allows, any deny wins, order
+// never matters. The engine (`access.engine.ts`) runs this with its lock, guardrails,
+// decision observer and `explain` around it; `avaccess generate` copies this module,
+// with the modules it imports, into a service's generated client.
+//
+// Like those modules, it imports nothing but them: no Node.js, no package.
+import { translateAnswer, translateWhere, } from "./aventara-where.translator.js";
+import { canonicalJson } from "./canonical-json.writer.js";
+import { decideOnRow, evaluateOnRow, } from "./predicate.evaluator.js";
+import { FALSE, foldDenies, foldGrants, governedFor, nullSafe, orOf, ownOf, principalFactsOf, rulesFor, scopeCondition, TRUE, } from "./scope.resolver.js";
+import { sha256Hex } from "./sha256.digest.js";
+/** A trace with nothing in it yet. */
+export const newTrace = () => ({
+    grants: new Map(),
+    denies: new Map(),
+    lookups: [],
+});
+/**
+ * The Resources where the row an update leaves can fail what allowed the update:
+ * an update grant whose condition reads the row (a `where`, an `after`, a role held
+ * on a row), or an update deny with a `where`. Core asks `can` about each row such
+ * an update changed, and refuses these updates where it has no interactive
+ * transaction to roll one back in.
+ */
+export const afterChecksOf = (policies) => {
+    const afterChecks = {};
+    const reads = (grant) => grant.where !== undefined ||
+        grant.after !== undefined ||
+        grant.in !== undefined ||
+        grant.subjects.some((subject) => {
+            const role = ownOf(policies.roles, subject);
+            return role !== undefined && "on" in role;
+        });
+    for (const grant of policies.grants) {
+        if (grant.resource !== "*" &&
+            grant.actions.includes("update") &&
+            reads(grant)) {
+            afterChecks[grant.resource] = ["update"];
+        }
+    }
+    for (const deny of policies.denies) {
+        if (deny.resource !== "*" &&
+            deny.where !== undefined &&
+            (deny.actions === "*" || deny.actions.includes("update"))) {
+            afterChecks[deny.resource] = ["update"];
+        }
+    }
+    return afterChecks;
+};
+/**
+ * The fields each grant's `write.except` locks. A relation and its reference fields
+ * are locked together: writing the relation (`$connect`, `$set`) writes those
+ * fields, and writing a reference field moves the relation, so naming either one
+ * locks both.
+ */
+const lockedFieldsOf = (policies) => {
+    const locks = new Map();
+    for (const grant of policies.grants) {
+        if (grant.write === undefined) {
+            continue;
+        }
+        const named = new Set(grant.write.except);
+        const locked = new Set(named);
+        const relations = ownOf(policies.schema, grant.resource)?.relations ?? {};
+        for (const [relation, fact] of Object.entries(relations)) {
+            const references = fact.referenceFields ?? [];
+            if (named.has(relation) || references.some((field) => named.has(field))) {
+                locked.add(relation);
+                for (const field of references) {
+                    locked.add(field);
+                }
+            }
+        }
+        locks.set(grant, locked);
+    }
+    return locks;
+};
+/**
+ * What is wrong with a `fieldsOf` question the types rule out but a caller can still
+ * send, or `undefined`: answered as asked, it would read as a read, or as no field.
+ */
+export const fieldsQuestionProblem = (question) => {
+    const { access, action } = question;
+    const fits = access === "read"
+        ? action === undefined
+        : access === "write" &&
+            (action === undefined || action === "create" || action === "update");
+    return fits
+        ? undefined
+        : `fieldsOf takes \`access: "read"\`, or \`access: "write"\` with an optional \`action\` ("create" or "update"); it was asked ${JSON.stringify({ access, action })}`;
+};
+const outcomeOf = (truth) => truth === "unknown" ? "unknown" : truth ? "matched" : "not matched";
+const isDecided = (node) => node.k === "true" || node.k === "false";
+/**
+ * What is wrong with a `grantsOf` question the types rule out but a caller can still
+ * send, or `undefined`: it asks about an update, and nothing else.
+ */
+export const grantsQuestionProblem = (question) => {
+    const { action } = question;
+    return action === "update"
+        ? undefined
+        : `grantsOf takes \`action: "update"\`; it was asked ${JSON.stringify({ action })}`;
+};
+/** Whether two field lists name the same fields. */
+const sameFields = (a, b) => a.length === b.length && a.every((field) => b.includes(field));
+/** The decisions of one policies file, already checked. */
+export const createDecider = (file) => {
+    const locks = lockedFieldsOf(file);
+    // A grant's key: a short hash of the file's grants, in their order, then its place
+    // in the file and its subject's place in the grant. It names a grant for one
+    // subject without carrying any of its data, a list from another file names no grant
+    // of this one, and it is the same for the folded grant `grantsOf` reads (its
+    // `where`) and the one `can` reads (its `where` and `after`).
+    const mark = sha256Hex(canonicalJson(file.grants)).slice(0, 8);
+    const places = new Map(file.grants.map((grant, index) => [grant, index]));
+    const keyOf = (grant) => `${mark}:${places.get(grant.grant) ?? -1}.${grant.grant.subjects.indexOf(grant.subject)}`;
+    const can = (question, trace) => {
+        const facts = principalFactsOf(question.principal, question.origin);
+        const { grants, denies } = rulesFor(file, question.resource, question.action);
+        const { row } = question;
+        if (row === undefined) {
+            // Admission: could this principal ever do this? Row conditions are the scope's.
+            const folded = foldGrants(file, grants, facts);
+            const foldedDenies = foldDenies(file, denies, facts);
+            for (const grant of folded) {
+                trace.grants.set(grant, grant.condition.k === "false" ? "not matched" : "matched");
+            }
+            for (const deny of foldedDenies) {
+                trace.denies.set(deny, deny.condition.k === "true" ? "matched" : "not matched");
+            }
+            return (folded.some((grant) => grant.condition.k !== "false") &&
+                !foldedDenies.some((deny) => deny.condition.k === "true"));
+        }
+        if (typeof row !== "object" || row === null) {
+            return false;
+        }
+        // The row a create inserts, or the row an update leaves (core's after check, or
+        // any caller's): an update's row must still meet the `where` and the `after` of
+        // one update grant, and no update deny may match it.
+        const isUpdate = question.action === "update";
+        const kind = question.action === "create" ? "new" : "existing";
+        // With the row before the update: the grant that covers the row
+        // the update leaves must be one whose `where` covered the row before it, so no
+        // update moves a row from the rows one grant reaches to another's. With
+        // `beforeGrants`, what covered it was decided before the write (`grantsOf`):
+        // `before` is still held to each listed grant's `where` in memory, since the list
+        // is the caller's to hand back, but a relation condition on it is not asked again.
+        const beforeGrants = isUpdate ? question.beforeGrants : undefined;
+        if (beforeGrants !== undefined &&
+            (!Array.isArray(beforeGrants) ||
+                beforeGrants.some((key) => typeof key !== "string"))) {
+            return false;
+        }
+        const coveredBefore = beforeGrants === undefined ? undefined : new Set(beforeGrants);
+        const before = isUpdate ? question.before : undefined;
+        if (before !== undefined &&
+            (typeof before !== "object" || before === null)) {
+            return false;
+        }
+        const folded = foldGrants(file, grants, facts, isUpdate);
+        const reached = before === undefined ? undefined : foldGrants(file, grants, facts);
+        const foldedDenies = foldDenies(file, denies, facts);
+        const grantResiduals = [];
+        let granted = false;
+        for (const [index, grant] of folded.entries()) {
+            if (coveredBefore !== undefined && !coveredBefore.has(keyOf(grant))) {
+                // It did not cover the row before the update.
+                trace.grants.set(grant, "not matched");
+                continue;
+            }
+            const residual = evaluateOnRow(file, question.resource, grant.condition, row);
+            // Folded alike, the two lists pair grant for grant; a missing pair covers nothing.
+            const evaluated = reached === undefined || before === undefined
+                ? undefined
+                : evaluateOnRow(file, question.resource, reached?.[index]?.condition ?? FALSE, before);
+            // Listed in `beforeGrants`: what is left of its `where` on `before` is a relation
+            // condition `grantsOf` decided before the write; only a decided false, or a
+            // value of the wrong type, refuses.
+            const prior = coveredBefore !== undefined &&
+                evaluated?.k !== "false" &&
+                evaluated?.k !== "unknown"
+                ? undefined
+                : evaluated;
+            if (residual.k === "unknown" || prior?.k === "unknown") {
+                // A value of the wrong type: no grant.
+                trace.grants.set(grant, "unknown");
+            }
+            else if (residual.k === "false" || prior?.k === "false") {
+                trace.grants.set(grant, "not matched");
+            }
+            else if (residual.k === "true" &&
+                (prior === undefined || prior.k === "true")) {
+                trace.grants.set(grant, "matched");
+                granted = true;
+            }
+            else {
+                trace.grants.set(grant, "not asked");
+                grantResiduals.push({
+                    grant,
+                    residual,
+                    prior: prior === undefined || prior.k === "true" ? undefined : prior,
+                });
+            }
+        }
+        const denyResiduals = [];
+        for (const deny of foldedDenies) {
+            const residual = evaluateOnRow(file, question.resource, deny.condition, row);
+            if (residual.k === "unknown") {
+                // A value of the wrong type: the deny counts (fail closed).
+                trace.denies.set(deny, "unknown");
+                return false;
+            }
+            if (isDecided(residual)) {
+                trace.denies.set(deny, residual.k === "true" ? "matched" : "not matched");
+                if (residual.k === "true") {
+                    return false;
+                }
+            }
+            else {
+                trace.denies.set(deny, "not asked");
+                denyResiduals.push({ deny, residual });
+            }
+        }
+        if (!granted && grantResiduals.length === 0) {
+            return false;
+        }
+        if (denyResiduals.length === 0 && granted) {
+            return true;
+        }
+        const ask = (condition, on = row) => decideOnRow({
+            policies: file,
+            resource: question.resource,
+            condition,
+            row: on,
+            kind,
+            exists: question.exists,
+            lookups: trace.lookups,
+        });
+        return (async () => {
+            for (const { deny, residual } of denyResiduals) {
+                const truth = await ask(residual);
+                trace.denies.set(deny, outcomeOf(truth));
+                // A deny that cannot be decided counts: fail closed.
+                if (truth !== false) {
+                    return false;
+                }
+            }
+            if (granted) {
+                return true;
+            }
+            for (const { grant, residual, prior } of grantResiduals) {
+                let truth = await ask(residual);
+                if (truth === true && prior !== undefined && before !== undefined) {
+                    truth = await ask(prior, before);
+                }
+                trace.grants.set(grant, outcomeOf(truth));
+                if (truth === true) {
+                    return true;
+                }
+            }
+            return false;
+        })();
+    };
+    const fieldsOf = (question) => {
+        const problem = fieldsQuestionProblem(question);
+        if (problem !== undefined) {
+            throw new Error(`Aventara Access: ${problem}`);
+        }
+        const facts = principalFactsOf(question.principal, question.origin);
+        // The fields governed for this access: only a grant that names one opens it.
+        const governed = governedFor(file, question.resource, question.access);
+        // `"all"` stands for every field the read side does not govern (the framework's
+        // default projection, whatever the access): a write answers it only when the
+        // write side governs the same fields.
+        const allStandsFor = question.access === "read" ||
+            sameFields(governed, governedFor(file, question.resource, "read"));
+        const actions = question.access === "read"
+            ? ["read"]
+            : question.action !== undefined
+                ? [question.action]
+                : ["create", "update"];
+        const grants = [
+            ...new Set(actions.flatMap((action) => rulesFor(file, question.resource, action).grants)),
+        ];
+        const live = foldGrants(file, grants, facts).filter((grant) => grant.condition.k !== "false");
+        if (live.length === 0) {
+            return { always: [], perRow: {} };
+        }
+        const excludes = (grant, field) => question.access === "write" &&
+            (locks.get(grant.grant)?.has(field) ?? false);
+        const names = (grant, field) => grant.grant.fields?.includes(`${question.resource}.${field}`) ?? false;
+        const answer = (condition) => condition.k === "true"
+            ? {}
+            : translateWhere(nullSafe(file, question.resource, condition));
+        const perRow = {};
+        for (const field of governed) {
+            const condition = orOf(live
+                .filter((grant) => names(grant, field) && !excludes(grant, field))
+                .map((grant) => grant.condition));
+            if (condition.k !== "false") {
+                perRow[field] = answer(condition);
+            }
+        }
+        const excluded = new Set(live.flatMap((grant) => question.access === "write" ? [...(locks.get(grant.grant) ?? [])] : []));
+        if (excluded.size === 0 && allStandsFor) {
+            return { always: "all", perRow };
+        }
+        const always = [];
+        for (const field of ownOf(file.schema, question.resource)?.fields ?? []) {
+            if (governed.includes(field)) {
+                continue;
+            }
+            if (!excluded.has(field)) {
+                always.push(field);
+                continue;
+            }
+            const condition = orOf(live
+                .filter((grant) => !excludes(grant, field))
+                .map((grant) => grant.condition));
+            if (condition.k === "true") {
+                always.push(field);
+            }
+            else if (condition.k !== "false") {
+                perRow[field] = answer(condition);
+            }
+        }
+        return { always, perRow };
+    };
+    const scopeOf = (question) => {
+        const facts = principalFactsOf(question.principal, question.origin);
+        const { grants, denies } = rulesFor(file, question.resource, question.action);
+        return translateAnswer(nullSafe(file, question.resource, scopeCondition(foldGrants(file, grants, facts), foldDenies(file, denies, facts))));
+    };
+    const grantsOf = (question) => {
+        const problem = grantsQuestionProblem(question);
+        if (problem !== undefined) {
+            throw new Error(`Aventara Access: ${problem}`);
+        }
+        const { row } = question;
+        if (typeof row !== "object" || row === null) {
+            // No row, no grant: a `can` handed this answer refuses.
+            return [];
+        }
+        const facts = principalFactsOf(question.principal, question.origin);
+        const { grants, denies } = rulesFor(file, question.resource, "update");
+        // An update deny decided on the row as it is (or on a value of the wrong type,
+        // failing closed): no grant lets the update in. A deny on a relation is the row
+        // after's to answer.
+        if (foldDenies(file, denies, facts).some((deny) => {
+            const truth = evaluateOnRow(file, question.resource, deny.condition, row).k;
+            return truth === "true" || truth === "unknown";
+        })) {
+            return [];
+        }
+        // Each grant's `where` and its subject's row condition, without its `after`: the
+        // condition `scopeOf` reads, asked about the row as it is. The answer lists the
+        // keys in the file's order.
+        const decided = foldGrants(file, grants, facts).map((grant) => ({
+            key: keyOf(grant),
+            residual: evaluateOnRow(file, question.resource, grant.condition, row),
+        }));
+        const covering = () => decided.flatMap(({ key, residual }) => residual.k === "true" ? [key] : []);
+        if (decided.every(({ residual }) => isDecided(residual) || residual.k === "unknown")) {
+            return covering();
+        }
+        return (async () => {
+            const lookups = [];
+            for (const entry of decided) {
+                const { residual } = entry;
+                if (isDecided(residual) || residual.k === "unknown") {
+                    continue;
+                }
+                const truth = await decideOnRow({
+                    policies: file,
+                    resource: question.resource,
+                    condition: residual,
+                    row,
+                    kind: "existing",
+                    exists: question.exists,
+                    lookups,
+                });
+                // A grant that cannot be decided does not cover the row.
+                entry.residual = truth === true ? TRUE : FALSE;
+            }
+            return covering();
+        })();
+    };
+    return { can, grantsOf, scopeOf, fieldsOf };
+};

package/dist/policies.hash.d.ts

@@ -0,0 +1,10 @@
+import type { AccessPolicies } from "./policies-contract.js";
+/** The canonical text of a `@1` file (see the header). The file is not checked here. */
+export declare const canonicalPolicies: (policies: AccessPolicies) => string;
+/**
+ * The canonical hash of a policies file: `sha256:` and the SHA-256 of its canonical
+ * byte form, in lowercase hex. The same rules give the same hash however the file's
+ * members and rules are ordered; any changed name or literal gives a different one.
+ * The file is checked first, so a file the engine would refuse has no hash.
+ */
+export declare const policiesHash: (policies: AccessPolicies) => string;

package/dist/policies.hash.js

@@ -0,0 +1,54 @@
+// The canonical byte form of a `policies@1` file and its hash. The
+// registry keys revisions by this hash, `avAccess.lock.json` pins it, and the build
+// and the CLI both call this code to check a pulled file, so one function decides
+// what "the same file" means.
+//
+// The canonical form is the file's JSON text, written by `canonical-json.writer.ts`
+// (members sorted by key, no whitespace) and encoded as UTF-8, with:
+// - the lists whose order the format gives no meaning sorted: `grants` and `denies`
+//   by `id`; a rule's `subjects`, `actions`, `fields` and `write.except`; each
+//   `govern` list; each schema entry's `fields` and `nullable`. `governModes` is objects
+//   only, so its members are sorted like any other.
+// Every other list keeps its order: identifiers (the first is the primary one),
+// relation reference pairs, principal and claim paths, a condition's arguments and
+// an `in` list's values.
+import { byId, canonicalJson, sortedNames as sorted, } from "./canonical-json.writer.js";
+import { checkPolicies } from "./policies.compiler.js";
+import { sha256Hex } from "./sha256.digest.js";
+const canonicalGrant = (grant) => ({
+    ...grant,
+    subjects: sorted(grant.subjects),
+    actions: sorted(grant.actions),
+    ...(grant.fields !== undefined ? { fields: sorted(grant.fields) } : {}),
+    ...(grant.write !== undefined
+        ? { write: { except: sorted(grant.write.except) } }
+        : {}),
+});
+const canonicalDeny = (deny) => ({
+    ...deny,
+    actions: deny.actions === "*" ? "*" : sorted(deny.actions),
+});
+const canonicalFacts = (facts) => ({
+    ...facts,
+    fields: sorted(facts.fields),
+    ...(facts.nullable !== undefined ? { nullable: sorted(facts.nullable) } : {}),
+});
+const mapValues = (record, map) => Object.fromEntries(Object.entries(record).map(([key, value]) => [key, map(value)]));
+/** The canonical text of a `@1` file (see the header). The file is not checked here. */
+export const canonicalPolicies = (policies) => canonicalJson({
+    ...policies,
+    schema: mapValues(policies.schema, canonicalFacts),
+    govern: mapValues(policies.govern, (fields) => sorted(fields)),
+    grants: [...policies.grants].map(canonicalGrant).sort(byId),
+    denies: [...policies.denies].map(canonicalDeny).sort(byId),
+});
+/**
+ * The canonical hash of a policies file: `sha256:` and the SHA-256 of its canonical
+ * byte form, in lowercase hex. The same rules give the same hash however the file's
+ * members and rules are ordered; any changed name or literal gives a different one.
+ * The file is checked first, so a file the engine would refuse has no hash.
+ */
+export const policiesHash = (policies) => {
+    checkPolicies(policies);
+    return `sha256:${sha256Hex(canonicalPolicies(policies))}`;
+};

package/dist/predicate.evaluator.d.ts

@@ -0,0 +1,62 @@
+import { type AccessWhere } from "./aventara-where.translator.js";
+import type { AccessPolicies } from "./policies-contract.js";
+import { type Resolved } from "./scope.resolver.js";
+/**
+ * A row as core hands it to `can`: its scalar fields. A relation member on it is
+ * ignored; never put relation data a client sent on it.
+ */
+export type AccessRow = {
+    readonly [field: string]: unknown;
+};
+/** Core's `exists`: whether a row of `resource` meets `where`, unscoped. */
+export type AccessExists = (resource: string, where: AccessWhere) => Promise<boolean>;
+/** One `exists` question the engine asked, and its answer. */
+export type AccessLookup = {
+    readonly resource: string;
+    readonly where: AccessWhere;
+    readonly answer: boolean;
+};
+/** A three-valued answer: decided, or not decidable from what the engine has. */
+export type AccessTruth = boolean | "unknown";
+/** Whether the row is about to be created, or already exists (an after check). */
+export type AccessRowKind = "new" | "existing";
+/**
+ * A decimal's value as `{ sign, digits, point }`: `0.<digits> × 10^point`, with no
+ * leading or trailing zero in `digits` (zero is `{ sign: "", digits: "", point: 0 }`).
+ * `undefined` for text that is no decimal.
+ */
+export declare const decimalParts: (text: string) => {
+    readonly sign: "" | "-";
+    readonly digits: string;
+    readonly point: number;
+} | undefined;
+/** An instant's epoch milliseconds, from a valid `Date` or an ISO-8601 string that reads back as written. */
+export declare const instantOf: (value: unknown) => number | undefined;
+/** A condition a row decided as neither true nor false: a value of the wrong type. */
+export type Unknown = {
+    readonly k: "unknown";
+};
+/** What evaluating on a row gives: `TRUE`, `FALSE`, `UNKNOWN`, or the residual. */
+export type Evaluated = Resolved | Unknown;
+/**
+ * Evaluates what the row carries. The answer is `TRUE`, `FALSE`, `UNKNOWN` (a value
+ * of another type than its field's), or the residual condition: the part the row
+ * could not decide, with the decided parts folded away. A relation member on the row
+ * is ignored: every relation step stays whole in the residual, for `exists`. Each comparison is made by its
+ * field's type (`types`): a decimal by its digits, a datetime by its instant, a
+ * bigint exactly.
+ */
+export declare const evaluateOnRow: (policies: AccessPolicies, resource: string, node: Resolved, row: AccessRow) => Evaluated;
+/**
+ * Decides a folded condition on a row: in memory first, then through `exists` for
+ * what the row does not carry. `"unknown"` when neither can decide.
+ */
+export declare const decideOnRow: (args: {
+    readonly policies: AccessPolicies;
+    readonly resource: string;
+    readonly condition: Resolved;
+    readonly row: AccessRow;
+    readonly kind: AccessRowKind;
+    readonly exists: AccessExists | undefined;
+    readonly lookups: AccessLookup[];
+}) => Promise<AccessTruth>;