@atlasauth/pca-analyzer 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# @atlasauth/pca-analyzer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Static analyzability of authority.** Proof-Carrying Authority can prove a quantitative trust-budget
+bound and verify one action, but on its own it cannot statically answer *"what can this whole delegated
+authority ever do?"* This package decides that over PCA's predicate/caveat policy — the conceptual gap
+the roadmap flagged — without a heavyweight SMT dependency.
+
+It is a sound, **bounded** decision procedure in the spirit of AWS Cedar's symbolic compiler (SymCC,
+arXiv:2403.04651), which decides policy equivalence / subsumption / always-allow-deny with
+counterexamples. Instead of discharging to Z3, this analyzer exploits a *finite-distinguishing-value*
+property of PCA's predicate theory and decides by enumeration against the **real** `evaluatePredicates`
+from `@atlasauth/pca`.
+
+## Queries
+
+All take a `CompiledPolicy` (from `compilePolicy` / `agent().policy`) or a bare
+`{ predicates, caveats? }`. Every negative/relational verdict carries a concrete counterexample or
+witness.
+
+| Function | Decides |
+|---|---|
+| `reachable(policy, action)` | Can any input complete `(verb, resource, params)` into an ALLOW? Returns a verified `witness`. |
+| `alwaysDenies(policy, verb?)` | Is the policy vacuous (denies everything / everything for `verb`)? |
+| `alwaysAllows(policy, verb)` | Is the policy total for `verb` (admits every action of it)? |
+| `subsumes(a, b)` | Does `a` permit everything `b` does (`admitted(b) ⊆ admitted(a)`)? The delegation-safety check: a child must be subsumed by its parent. |
+| `disjoint(a, b)` | Do the two admit no common action? |
+| `equivalent(a, b)` | Do the two admit exactly the same actions? |
+| `intentConformance(policy, intent)` | Does the policy admit **only** actions inside a declared intent envelope (verbs + resource scopes + amount ceiling)? |
+
+`intentConformance` is the safety check distinct from the runtime trust-budget. It catches the
+*"a $14k renewal under a $10k cap on an approved vendor still violates intent"* class: an action that
+passes the policy's predicates and stays under budget, yet falls outside what the principal intended,
+because the policy's own ceiling is higher than (or absent relative to) the intent cap.
+
+```ts
+import { subsumes, intentConformance } from '@atlasauth/pca-analyzer';
+
+// Delegation safety: a child capability must not widen its parent.
+const ok = subsumes(parentPolicy, childPolicy).subsumes; // false => counterexample attached
+
+// Intent conformance: does the authority stay inside what was meant?
+const r = intentConformance(policy, { verbs: ['stripe.refund'], maxAmount: 10000 });
+// r.conforms === false, r.violations[].kinds includes 'over-amount' for the $14k action
+```
+
+## How it decides (the engine)
+
+PCA's `where` conditions are a conjunction of threshold tests (`lt/lte/gt/gte/eq` on numbers),
+membership tests (`eq/ne/in/nin` over finite values) and string `prefix` tests; predicates match on a
+verb allowlist and a resource matcher; the envelope caveats are append-only and conjunctive. The
+admitted region of a policy is therefore a **union of cells** of the arrangement defined by the literals
+that appear in it. The analyzer builds one representative value per cell — every literal and numeric
+threshold, the midpoints between consecutive thresholds, boundary points just outside the range, prefix
+probes, a *fresh* verb / resource / value matching none of the literals, and an *absent* probe for each
+field — then evaluates both policies at every representative with the real evaluator. Because that set
+is distinguishing, agreeing on all representatives implies agreeing on all actions, so the relational
+queries are decided exactly, and any mismatch is a real counterexample. Caveat satisfiability is decided
+separately (`analyzeCaveats`): the context (time window, blast radius, depth, rate) is taken as
+favourably chosen, and the one action-tied caveat, `reversibility_max`, becomes a per-action cap.
+
+## Decided exactly vs. sound-over-approximated
+
+**Decided exactly** (the fragment):
+
+- verb allowlists (`string`, `string[]`, `'*'`);
+- resource matchers that are exact, `'*'`, or a trailing-`*` **prefix**;
+- numeric `where` over `lt/lte/gt/gte/eq` (the interval engine; merges bounds, detects empty
+  conjunctions such as `amount >= 100 AND amount <= 10`);
+- finite-domain `eq/ne/in/nin` and string `prefix` (the set engine — the fresh/absent probes make
+  unbounded string domains decidable for these operators);
+- `exists` (via the absent probe);
+- the conjunctive envelope caveats: `expires`, `not_before` (empty-window detection), `rate`,
+  `max_blast_radius`, `reversibility_max`, `delegation_depth`, `budget_alloc`.
+
+**Sound but over-approximated** — the result is reported with `approximate: true` and **fails safe**
+(never claims *subsumed / always-deny / disjoint / equivalent / conforms* without proof; falls back to
+*not-subsumed / reachable / not-disjoint / not-equivalent / non-conforming*):
+
+- **`re:` regex resource matchers** — a regex relation (containment/overlap) is not decided; the
+  resource dimension cannot be soundly enumerated. (A regex is still evaluated *exactly* against a fully
+  concrete resource in `reachable`, where there is nothing to enumerate.)
+- **cross-field `ref` conditions** — a comparison whose operand is another field (`a != env.b`); the two
+  fields co-vary and are not resolved statically.
+- **whole-`action.params` conditions** (a condition on the container rather than a `.subfield`).
+- **grid overflow** — a representative grid larger than `maxCombinations` (default 200,000); no
+  enumeration is performed.
+
+The soundness contract: a proven verdict (`approximate` falsy) is correct for the fragment above; an
+`approximate` verdict is never a false "safe". An external Z3 / SMT-LIB backend for the regex and
+cross-field fragments is a possible future stretch; it is **not** required for the guarantees here.

package/dist/caveats.d.ts

@@ -0,0 +1,22 @@
+import type { Caveat } from '@atlasauth/pca';
+/**
+ * Static satisfiability of a PCA envelope caveat set (the leaf's cumulative, append-only, conjunctive
+ * caveats). This answers "is there ANY runtime context under which these caveats can all hold?" — the
+ * global gate on whether the authority can ever admit anything.
+ *
+ * The caveats constrain the runtime CaveatContext (now, blast radius, delegation depth, rate window,
+ * reversibility class), not the action's predicate fields. The analyzer treats the context as chosen
+ * favourably (the most permissive the authority could ever encounter) — the right stance for "what can
+ * this authority EVER do". The one caveat tied to the action itself is `reversibility_max`, whose cap
+ * is returned so the per-action check can enforce `class(action) <= cap`.
+ *
+ * Mirrors `envelopeCaveatEvaluator` in @atlasauth/pca (unknown/ malformed => fail closed).
+ */
+export interface CaveatAnalysis {
+    /** Some context satisfies every caveat. */
+    sat: boolean;
+    reason?: string;
+    /** Strictest `reversibility_max` cap as an index into REVERSIBILITY_ORDER, if any caveat sets one. */
+    revCap?: number;
+}
+export declare function analyzeCaveats(caveats: readonly Caveat[] | undefined): CaveatAnalysis;

package/dist/caveats.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeCaveats = analyzeCaveats;
+const types_1 = require("./types");
+function finite(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+}
+function analyzeCaveats(caveats) {
+    if (!Array.isArray(caveats))
+        return { sat: false, reason: 'caveats are not an array' };
+    let notBeforeMax = -Infinity; // the action can only happen at now >= this
+    let expiresMin = Infinity; // ...and now < this
+    let revCap;
+    for (const cv of caveats) {
+        if (cv === null || typeof cv !== 'object' || typeof cv.type !== 'string') {
+            return { sat: false, reason: 'malformed caveat (not an object with a string type)' };
+        }
+        switch (cv.type) {
+            case 'expires': {
+                const at = finite(cv.at);
+                if (at === undefined)
+                    return { sat: false, reason: 'expires.at is not a finite number' };
+                expiresMin = Math.min(expiresMin, at);
+                break;
+            }
+            case 'not_before': {
+                const at = finite(cv.at);
+                if (at === undefined)
+                    return { sat: false, reason: 'not_before.at is not a finite number' };
+                notBeforeMax = Math.max(notBeforeMax, at);
+                break;
+            }
+            case 'rate': {
+                const max = finite(cv.max);
+                const per = finite(cv.per_secs);
+                if (max === undefined || per === undefined || per <= 0) {
+                    return { sat: false, reason: 'rate caveat requires finite max and per_secs > 0' };
+                }
+                // With zero prior actions the count is 0, so the gate `0 < max` needs max >= 1.
+                if (max < 1)
+                    return { sat: false, reason: `rate.max ${max} < 1 forbids every action` };
+                break;
+            }
+            case 'max_blast_radius': {
+                const max = finite(cv.max);
+                if (max === undefined)
+                    return { sat: false, reason: 'max_blast_radius.max is not a finite number' };
+                // The least blast radius is 0, so this is satisfiable iff max >= 0.
+                if (max < 0)
+                    return { sat: false, reason: 'max_blast_radius.max < 0 forbids every action' };
+                break;
+            }
+            case 'reversibility_max': {
+                const idx = types_1.REVERSIBILITY_ORDER.indexOf(String(cv.class));
+                if (idx < 0)
+                    return { sat: false, reason: `reversibility_max.class '${String(cv.class)}' is unknown` };
+                revCap = revCap === undefined ? idx : Math.min(revCap, idx);
+                break;
+            }
+            case 'delegation_depth': {
+                const max = finite(cv.max);
+                if (max === undefined)
+                    return { sat: false, reason: 'delegation_depth.max is not a finite number' };
+                // The least depth is 0, so this is satisfiable iff max >= 0.
+                if (max < 0)
+                    return { sat: false, reason: 'delegation_depth.max < 0 forbids every action' };
+                break;
+            }
+            case 'budget_alloc': {
+                const lim = finite(cv.limit);
+                if (lim === undefined || lim < 0) {
+                    return { sat: false, reason: 'budget_alloc.limit must be a finite number >= 0' };
+                }
+                break;
+            }
+            default:
+                return { sat: false, reason: `unknown caveat type '${cv.type}' (fail closed)` };
+        }
+    }
+    if (notBeforeMax !== -Infinity && expiresMin !== Infinity && notBeforeMax >= expiresMin) {
+        return {
+            sat: false,
+            reason: `not_before (${notBeforeMax}) >= expires (${expiresMin}): the validity window is empty`,
+        };
+    }
+    return { sat: true, revCap };
+}
+//# sourceMappingURL=caveats.js.map

package/dist/caveats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caveats.js","sourceRoot":"","sources":["../src/caveats.ts"],"names":[],"mappings":"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"}

package/dist/enumerate.d.ts

@@ -0,0 +1,68 @@
+import type { Caveat, Condition, Predicate } from '@atlasauth/pca';
+import type { AnalyzerAction, PolicyInput } from './types';
+type Cell = unknown;
+/** Default cap on the representative grid size (product of all dimensions). */
+export declare const DEFAULT_MAX_COMBINATIONS = 200000;
+export interface PolicyModel {
+    predicates: Predicate[];
+    caveats: Caveat[];
+    caveatSat: boolean;
+    caveatReason?: string;
+    /** Strictest `reversibility_max` cap (index into REVERSIBILITY_ORDER), if any. */
+    revCap?: number;
+    /** Non-empty when the policy uses features the analyzer cannot decide exactly. */
+    undecidable: string[];
+}
+export declare function normalizePolicy(p: PolicyInput): {
+    predicates: Predicate[];
+    caveats: Caveat[];
+};
+export declare function toModel(p: PolicyInput): PolicyModel;
+export interface Probes {
+    verbs: string[];
+    resources: string[];
+    /** `undefined` means "no reversibility dimension" (no policy sets a `reversibility_max`). */
+    revClasses: (string | undefined)[];
+    fields: {
+        path: string;
+        values: Cell[];
+    }[];
+}
+export interface ProbeInputs {
+    predicateSets: Predicate[][];
+    extraVerbs?: string[];
+    extraResources?: string[];
+    extraFieldConditions?: {
+        path: string;
+        cond: Condition;
+    }[];
+    /** Vary the reversibility class over all three classes (needed when any policy caps reversibility). */
+    varyReversibility: boolean;
+}
+export declare function collectProbes(inputs: ProbeInputs): Probes;
+export declare function productSize(pr: Probes): number;
+export interface Rep {
+    verb: string;
+    resource: string;
+    revClass: string | undefined;
+    /** Field path -> value, excluding absent fields. */
+    assignments: ReadonlyMap<string, unknown>;
+}
+export declare function representatives(pr: Probes): Generator<Rep>;
+/** Does the policy admit this representative action? (predicate match AND static caveat gate.) */
+export declare function admits(model: PolicyModel, rep: Rep): boolean;
+/** Concrete admission of a fully-specified action (used by reachable's fast path; exact). */
+export declare function admitsAction(model: PolicyModel, action: AnalyzerAction): boolean;
+export declare function repToAction(rep: Rep): AnalyzerAction;
+export interface SearchOutcome {
+    /** A representative for which the predicate returned true, if the search stopped on one. */
+    hit?: Rep;
+    /** The grid exceeded the configured bound; no enumeration was performed. */
+    overflow: boolean;
+}
+/**
+ * Walk the representative grid, stopping at the first rep for which `predicate` is true. Returns
+ * `overflow: true` (without walking) when the grid is larger than `max`.
+ */
+export declare function search(pr: Probes, predicate: (rep: Rep) => boolean, max: number): SearchOutcome;
+export {};

package/dist/enumerate.js

@@ -0,0 +1,375 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_COMBINATIONS = void 0;
+exports.normalizePolicy = normalizePolicy;
+exports.toModel = toModel;
+exports.collectProbes = collectProbes;
+exports.productSize = productSize;
+exports.representatives = representatives;
+exports.admits = admits;
+exports.admitsAction = admitsAction;
+exports.repToAction = repToAction;
+exports.search = search;
+const pca_1 = require("@atlasauth/pca");
+const caveats_1 = require("./caveats");
+const field_1 = require("./field");
+const types_1 = require("./types");
+/**
+ * The bounded decision engine. It builds a finite set of representative actions ("the grid") from the
+ * literals, thresholds, prefixes, verbs and resource matchers that appear in the policies (and, for
+ * intent conformance, the intent). Because PCA's `where` theory is a boolean combination of
+ * threshold/membership/prefix tests, each policy's admitted region is a union of grid cells, so one
+ * representative per cell is DISTINGUISHING: any two policies that differ on some action also differ on
+ * some representative. Evaluating the REAL `evaluatePredicates` at each representative (plus the static
+ * caveat gate) therefore decides reachability, subsumption, disjointness and equivalence EXACTLY for
+ * the decided fragment, and yields a concrete counterexample whenever a relation fails.
+ *
+ * Out-of-fragment features (`re:` regex resources, cross-field `ref` conditions) and grids larger than
+ * the bound are detected and reported as `approximate`, and every verdict then fails safe.
+ */
+const ABSENT = Symbol('analyzer-absent-field');
+const FRESH_VERB = '\u0000atlas-analyzer::fresh-verb\u0000';
+const FRESH_RESOURCE = '\u0000atlas-analyzer::fresh-resource\u0000';
+/** Default cap on the representative grid size (product of all dimensions). */
+exports.DEFAULT_MAX_COMBINATIONS = 200_000;
+function normalizePolicy(p) {
+    const predicates = Array.isArray(p.predicates) ? p.predicates : [];
+    const caveats = 'caveats' in p && Array.isArray(p.caveats) ? p.caveats : [];
+    return { predicates, caveats };
+}
+/**
+ * Collect over-approximation reasons from one condition tree. Boolean groupings (all_of/any_of/not)
+ * are DECIDED EXACTLY as long as every leaf uses a decidable op — the admitted region stays a boolean
+ * combination of the same per-field cells, so the representative grid remains distinguishing — so the
+ * grouping itself is not undecidable; only its hard leaves are. The genuinely-hard leaf ops
+ * (`like`/`matches`/`is_a`/`member_of`), a cross-field `ref`, and a whole-`action.params` condition
+ * force a conservative over-approximation (verdict fails safe).
+ */
+function conditionUndecidable(c, reasons) {
+    if (c === null || typeof c !== 'object')
+        return;
+    if ((0, pca_1.isGroupCondition)(c)) {
+        if ('all_of' in c && Array.isArray(c.all_of))
+            for (const x of c.all_of)
+                conditionUndecidable(x, reasons);
+        else if ('any_of' in c && Array.isArray(c.any_of))
+            for (const x of c.any_of)
+                conditionUndecidable(x, reasons);
+        else if ('not' in c)
+            conditionUndecidable(c.not, reasons);
+        return;
+    }
+    if (!(0, pca_1.isLeafCondition)(c))
+        return;
+    if (c.ref !== undefined) {
+        reasons.add('cross-field `ref` condition — the relation between two fields is not resolved');
+    }
+    if (c.field === 'action.params') {
+        reasons.add('condition on the whole `action.params` object is not enumerated precisely');
+    }
+    if (c.op === 'like' || c.op === 'matches' || c.op === 'is_a' || c.op === 'member_of') {
+        reasons.add(`\`${c.op}\` condition — matched by over-approximation, not enumerated exactly`);
+    }
+}
+function detectUndecidable(predicates) {
+    const reasons = new Set();
+    for (const p of predicates) {
+        if (p === null || typeof p !== 'object')
+            continue;
+        const r = p.resource;
+        if (typeof r === 'string' && r.startsWith('re:')) {
+            reasons.add('re: regex resource matcher — resource dimension cannot be soundly enumerated');
+        }
+        if (Array.isArray(p.where))
+            for (const c of p.where)
+                conditionUndecidable(c, reasons);
+    }
+    return [...reasons];
+}
+function toModel(p) {
+    const { predicates, caveats } = normalizePolicy(p);
+    const ca = (0, caveats_1.analyzeCaveats)(caveats);
+    return {
+        predicates,
+        caveats,
+        caveatSat: ca.sat,
+        caveatReason: ca.reason,
+        revCap: ca.revCap,
+        undecidable: detectUndecidable(predicates),
+    };
+}
+function addVerbLiterals(c, into) {
+    const v = c.value;
+    if (c.op === 'eq' || c.op === 'ne' || c.op === 'prefix' || c.op === 'like' || c.op === 'is_a') {
+        if (typeof v === 'string')
+            into.add(v);
+    }
+    else if ((c.op === 'in' || c.op === 'nin') && Array.isArray(v)) {
+        for (const x of v)
+            if (typeof x === 'string')
+                into.add(x);
+    }
+}
+function collectProbes(inputs) {
+    const verbLiterals = new Set(inputs.extraVerbs ?? []);
+    const resourceLiterals = new Set();
+    const fieldConds = new Map();
+    const addFieldCond = (path, c) => {
+        const arr = fieldConds.get(path) ?? [];
+        arr.push(c);
+        fieldConds.set(path, arr);
+    };
+    const classifyResource = (r) => {
+        if (r === undefined || r === '*')
+            return; // universal: FRESH_RESOURCE represents it
+        if (r.startsWith('re:'))
+            return; // undecidable: FRESH_RESOURCE stands in (flagged on the model)
+        if (r.endsWith('*')) {
+            const body = r.slice(0, -1);
+            resourceLiterals.add(body);
+            resourceLiterals.add(body + 'x');
+            return;
+        }
+        resourceLiterals.add(r);
+    };
+    const handleCond = (c) => {
+        if (c === null || typeof c !== 'object')
+            return;
+        // Recurse through boolean groupings and bucket their leaves (keeps the grid distinguishing for
+        // nested boolean logic over decidable ops).
+        if ((0, pca_1.isGroupCondition)(c)) {
+            if ('all_of' in c && Array.isArray(c.all_of))
+                for (const x of c.all_of)
+                    handleCond(x);
+            else if ('any_of' in c && Array.isArray(c.any_of))
+                for (const x of c.any_of)
+                    handleCond(x);
+            else if ('not' in c)
+                handleCond(c.not);
+            return;
+        }
+        if (!(0, pca_1.isLeafCondition)(c))
+            return;
+        if (c.field === 'action.verb') {
+            addVerbLiterals(c, verbLiterals);
+            return;
+        }
+        if (c.field === 'action.resource') {
+            if (c.op === 'prefix' && typeof c.value === 'string')
+                classifyResource(c.value + '*');
+            else if (typeof c.value === 'string')
+                classifyResource(c.value);
+            else if (Array.isArray(c.value))
+                for (const x of c.value)
+                    if (typeof x === 'string')
+                        classifyResource(x);
+            return;
+        }
+        addFieldCond(c.field, c);
+    };
+    for (const list of inputs.predicateSets) {
+        for (const p of list) {
+            if (p === null || typeof p !== 'object')
+                continue;
+            if (typeof p.verb === 'string') {
+                if (p.verb !== '*')
+                    verbLiterals.add(p.verb);
+            }
+            else if (Array.isArray(p.verb)) {
+                for (const v of p.verb)
+                    if (typeof v === 'string' && v !== '*')
+                        verbLiterals.add(v);
+            }
+            classifyResource(p.resource);
+            if (Array.isArray(p.where))
+                for (const c of p.where)
+                    handleCond(c);
+        }
+    }
+    for (const r of inputs.extraResources ?? [])
+        classifyResource(r);
+    for (const ec of inputs.extraFieldConditions ?? [])
+        handleCond({ ...ec.cond, field: ec.path });
+    const fields = [...fieldConds.entries()].map(([path, conds]) => ({
+        path,
+        values: [...(0, field_1.fieldProbes)(conds), ABSENT],
+    }));
+    return {
+        verbs: [...verbLiterals, FRESH_VERB],
+        resources: [...resourceLiterals, FRESH_RESOURCE],
+        revClasses: inputs.varyReversibility ? [...types_1.REVERSIBILITY_ORDER] : [undefined],
+        fields,
+    };
+}
+function productSize(pr) {
+    let n = pr.verbs.length * pr.resources.length * pr.revClasses.length;
+    for (const f of pr.fields)
+        n *= f.values.length;
+    return n;
+}
+function* enumerateFields(fields, i, acc) {
+    if (i >= fields.length) {
+        yield new Map(acc);
+        return;
+    }
+    const f = fields[i];
+    if (f === undefined) {
+        yield new Map(acc);
+        return;
+    }
+    for (const v of f.values) {
+        if (v === ABSENT) {
+            acc.delete(f.path);
+        }
+        else {
+            acc.set(f.path, v);
+        }
+        yield* enumerateFields(fields, i + 1, acc);
+    }
+    acc.delete(f.path);
+}
+function* representatives(pr) {
+    for (const verb of pr.verbs) {
+        for (const resource of pr.resources) {
+            for (const revClass of pr.revClasses) {
+                for (const assignments of enumerateFields(pr.fields, 0, new Map())) {
+                    yield { verb, resource, revClass, assignments };
+                }
+            }
+        }
+    }
+}
+function branch() {
+    return { leaf: false, children: new Map() };
+}
+function insert(root, segs, value) {
+    let node = root;
+    for (let i = 0; i < segs.length - 1; i++) {
+        const key = segs[i];
+        if (key === undefined || node.leaf)
+            return;
+        const next = node.children.get(key);
+        if (next === undefined || next.leaf) {
+            const created = branch();
+            node.children.set(key, created);
+            node = created;
+        }
+        else {
+            node = next;
+        }
+    }
+    const last = segs[segs.length - 1];
+    if (last !== undefined && !node.leaf)
+        node.children.set(last, { leaf: true, value });
+}
+function materialize(node) {
+    const out = {};
+    if (node.leaf)
+        return out;
+    for (const [key, child] of node.children) {
+        out[key] = child.leaf ? child.value : materialize(child);
+    }
+    return out;
+}
+function buildRoots(rep) {
+    const roots = new Map([
+        ['action', branch()],
+        ['subject', branch()],
+        ['env', branch()],
+    ]);
+    for (const [path, value] of rep.assignments) {
+        const segs = path.split('.');
+        const first = segs[0];
+        if (first === undefined || segs.length < 2)
+            continue;
+        const root = roots.get(first);
+        if (root === undefined)
+            continue; // only action / subject / env roots are addressable
+        insert(root, segs.slice(1), value);
+    }
+    const actionTree = roots.get('action');
+    const subjectTree = roots.get('subject');
+    const envTree = roots.get('env');
+    const action = { verb: rep.verb, resource: rep.resource, params: {} };
+    if (actionTree !== undefined && !actionTree.leaf) {
+        for (const [key, child] of actionTree.children) {
+            if (key === 'verb' || key === 'resource')
+                continue; // fixed from the rep
+            if (key === 'params') {
+                // `action.params.*` branches materialize to a typed record; a whole-`params` leaf is flagged
+                // undecidable upstream, so it is safe to ignore here (params stays an empty, present object).
+                if (!child.leaf)
+                    action.params = materialize(child);
+            }
+            else {
+                action[key] = child.leaf ? child.value : materialize(child);
+            }
+        }
+    }
+    if (rep.revClass !== undefined)
+        action.reversibility_class = rep.revClass;
+    const subject = subjectTree === undefined || subjectTree.leaf ? {} : materialize(subjectTree);
+    const env = envTree === undefined || envTree.leaf ? {} : materialize(envTree);
+    return { action, subject, env };
+}
+function contextFromRoots(roots) {
+    return { action: roots.action, subject: roots.subject, env: roots.env };
+}
+function reversibilityOk(model, revClass) {
+    if (model.revCap === undefined)
+        return true;
+    if (revClass === undefined)
+        return false; // a reversibility_max caveat denies an action with no class
+    const idx = types_1.REVERSIBILITY_ORDER.indexOf(revClass);
+    return idx >= 0 && idx <= model.revCap;
+}
+/** Does the policy admit this representative action? (predicate match AND static caveat gate.) */
+function admits(model, rep) {
+    if (!model.caveatSat)
+        return false;
+    if (!reversibilityOk(model, rep.revClass))
+        return false;
+    const ctx = contextFromRoots(buildRoots(rep));
+    return (0, pca_1.evaluatePredicates)(model.predicates, ctx).allowed;
+}
+/** Concrete admission of a fully-specified action (used by reachable's fast path; exact). */
+function admitsAction(model, action) {
+    if (!model.caveatSat)
+        return false;
+    if (!reversibilityOk(model, action.reversibilityClass))
+        return false;
+    const act = { verb: action.verb, resource: action.resource, params: { ...(action.params ?? {}) } };
+    if (action.reversibilityClass !== undefined)
+        act.reversibility_class = action.reversibilityClass;
+    const ctx = {
+        action: act,
+        subject: { ...(action.subject ?? {}) },
+        env: { ...(action.env ?? {}) },
+    };
+    return (0, pca_1.evaluatePredicates)(model.predicates, ctx).allowed;
+}
+function repToAction(rep) {
+    const roots = buildRoots(rep);
+    const action = { verb: rep.verb, resource: rep.resource, params: { ...roots.action.params } };
+    if (rep.revClass !== undefined)
+        action.reversibilityClass = rep.revClass;
+    if (Object.keys(roots.subject).length > 0)
+        action.subject = roots.subject;
+    if (Object.keys(roots.env).length > 0)
+        action.env = roots.env;
+    return action;
+}
+/**
+ * Walk the representative grid, stopping at the first rep for which `predicate` is true. Returns
+ * `overflow: true` (without walking) when the grid is larger than `max`.
+ */
+function search(pr, predicate, max) {
+    if (productSize(pr) > max)
+        return { overflow: true };
+    for (const rep of representatives(pr)) {
+        if (predicate(rep))
+            return { hit: rep, overflow: false };
+    }
+    return { overflow: false };
+}
+//# sourceMappingURL=enumerate.js.map