@crediolabs/policy-synth 0.3.1 → 0.5.0

package/dist/simulate/evaluate.js

@@ -1,4 +1,4 @@
-// src/simulate/evaluate.ts - TypeScript reference evaluator for grammar version 3.
+// src/simulate/evaluate.ts - TypeScript reference evaluator for grammar version 4.
 //
 // Pure function. Determinism: same `(predicate, ctx)` -> byte-identical result,
 // no clock, no randomness. Deny order (deny on FIRST violation, stable reason):
@@ -8,12 +8,13 @@
 //   3. `in` membership; empty haystack ALWAYS denies         -> 'NOT_IN_ALLOWLIST'
 //   4. otherwise permit.
 //
-// Grammar version 3 nodes: and, eq, lte
-// Grammar version 3 leaves: call_contract, call_fn, call_arg(i),
+// Grammar version 4 nodes: and, or, eq, lt, lte, gt, gte, in
+// Grammar version 4 leaves: call_contract, call_fn, call_arg(i),
 //   call_arg_len(i), call_arg_field(i, element, field),
+//   call_arg_scaled(i, num, den),
 //   literal_address, literal_i128, literal_symbol, literal_u32, literal_vec
-// Grammar version 3 deny reasons: ARG_MISMATCH, CONTRACT_SCOPE,
-//   UNSUPPORTED_NODE, NOT_IN_ALLOWLIST
+// Grammar version 4 deny reasons: ARG_MISMATCH, CONTRACT_SCOPE,
+//   ARITHMETIC_OVERFLOW, UNSUPPORTED_NODE, NOT_IN_ALLOWLIST, SLIPPAGE_FLOOR
 /** Evaluate a `PredicateNode` against the candidate call described by `ctx`.
  *  Pure function. Returns `{ permit: true }` or `{ permit: false; reason }`. */
 export function evaluate(predicate, ctx) {
@@ -33,8 +34,25 @@ function walk(node, ctx) {
             }
             return lastDeny ?? { permit: true };
         }
+        // Permits on the first branch that holds; when none does, reports the
+        // FIRST branch's reason. Mirrors `Node::Or` in the Rust evaluator, which
+        // the conformance suite pins.
+        case 'or': {
+            let firstDeny = null;
+            for (const child of node.children) {
+                const r = walk(child, ctx);
+                if (r.permit)
+                    return r;
+                if (firstDeny === null)
+                    firstDeny = r;
+            }
+            return firstDeny ?? { permit: false, reason: 'UNSUPPORTED_NODE' };
+        }
         case 'eq':
+        case 'lt':
         case 'lte':
+        case 'gt':
+        case 'gte':
             return evalCompare(node.op, node.left, node.right, ctx);
         case 'in':
             return evalIn(node.needle, node.haystack, ctx);
@@ -42,6 +60,16 @@ function walk(node, ctx) {
 }
 /** Comparison leaf evaluation. */
 function evalCompare(op, left, right, ctx) {
+    // Scaled operands first, so the dedicated reasons reach the caller instead
+    // of a generic mismatch. Right-hand dispatch leads because
+    // `out >= in * num / den` is the canonical swap form. Mirrors the order in
+    // `eval_compare` on the Rust side.
+    if (right.kind === 'call_arg_scaled') {
+        return evalScaledCompare(op, left, right, true, ctx);
+    }
+    if (left.kind === 'call_arg_scaled') {
+        return evalScaledCompare(op, right, left, false, ctx);
+    }
     // CONTRACT_SCOPE on call_contract eq
     if (left.kind === 'call_contract' && op === 'eq') {
         if (right.kind !== 'literal_address')
@@ -96,6 +124,53 @@ function evalCompare(op, left, right, ctx) {
     // Unknown leaf/op combination - structural fail-closed.
     return { permit: false, reason: 'UNSUPPORTED_NODE' };
 }
+/** i128 bounds. The contract computes in i128 and denies on overflow, so the
+ *  reference has to draw the same line or the two layers disagree on inputs
+ *  near the boundary. */
+const I128_MIN = -(2n ** 127n);
+const I128_MAX = 2n ** 127n - 1n;
+/** Comparison where one side is `call_arg_scaled`. Mirrors
+ *  `eval_scaled_arg_compare`: `args[index] * num / den` truncating toward
+ *  zero, ARITHMETIC_OVERFLOW on arithmetic that does not fit or a zero
+ *  denominator, SLIPPAGE_FLOOR on a comparison that simply fails. */
+function evalScaledCompare(op, other, scaled, scaledOnRight, ctx) {
+    // Chaining two computed operands has no meaning a review card could state.
+    if (other.kind === 'call_arg_scaled')
+        return { permit: false, reason: 'UNSUPPORTED_NODE' };
+    // Could not READ the operand is a different failure from read-and-missed.
+    const input = argNumericBigInt(ctx.args[scaled.index]);
+    if (input === null)
+        return { permit: false, reason: 'ARG_MISMATCH' };
+    let num;
+    let den;
+    try {
+        num = BigInt(scaled.num);
+        den = BigInt(scaled.den);
+    }
+    catch {
+        return { permit: false, reason: 'ARG_MISMATCH' };
+    }
+    if (den === 0n)
+        return { permit: false, reason: 'ARITHMETIC_OVERFLOW' };
+    const product = input * num;
+    if (product < I128_MIN || product > I128_MAX) {
+        return { permit: false, reason: 'ARITHMETIC_OVERFLOW' };
+    }
+    // BigInt division already truncates toward zero, matching i128 semantics.
+    const quotient = product / den;
+    if (quotient < I128_MIN || quotient > I128_MAX) {
+        return { permit: false, reason: 'ARITHMETIC_OVERFLOW' };
+    }
+    const otherVal = other.kind === 'call_arg'
+        ? argNumericBigInt(ctx.args[other.index])
+        : literalNumericBigInt(other);
+    if (otherVal === null)
+        return { permit: false, reason: 'ARG_MISMATCH' };
+    const [a, b] = scaledOnRight ? [otherVal, quotient] : [quotient, otherVal];
+    return bigintCmp(op, a.toString(), b.toString())
+        ? { permit: true }
+        : { permit: false, reason: 'SLIPPAGE_FLOOR' };
+}
 /** Per-ScVal equality. Handles literal_vec as an EXACT ordered sequence:
  *  compare element-by-element in order; deny if length or any element differs.
  *  Opaque args (`type: 'other'`) fail closed. */
@@ -265,7 +340,13 @@ function bigintCmp(op, aStr, bStr) {
     switch (op) {
         case 'eq':
             return a === b;
+        case 'lt':
+            return a < b;
         case 'lte':
             return a <= b;
+        case 'gt':
+            return a > b;
+        case 'gte':
+            return a >= b;
     }
 }

package/dist/synth/declare.d.ts

@@ -0,0 +1,43 @@
+import type { PredicateNode } from '../types.ts';
+export interface PolicyDeclaration {
+    /** Method to pin. Required: a predicate with no selector leaf constrains
+     *  nothing and the contract refuses it at install. */
+    fn: string;
+    /** Contract to pin, already resolved to a `C...` address. */
+    contract?: string;
+    /** Upper bound on the call's amount argument, in the token's SMALLEST
+     *  unit as an unsigned decimal string (25 XLM = "250000000"). */
+    maxAmount?: string;
+    /** Which argument carries the amount. Defaults to the SEP-41 position. */
+    amountArgIndex?: number;
+    /** Recipient allowlist. */
+    recipients?: string[];
+    /** Which argument carries the recipient. Defaults to the SEP-41 position. */
+    recipientArgIndex?: number;
+    /** A cap of "0" denies every call, so it is refused unless asked for
+     *  explicitly. A rule that permits nothing is a plausible thing to want and
+     *  an implausible thing to want by accident. */
+    allowZeroCap?: boolean;
+    /** Minimum output as a ratio of the call's own input: the output argument
+     *  must be at least `input * num / den`.
+     *
+     *  A swap's acceptable output depends on the size of the trade, so a fixed
+     *  floor would pin the policy to one trade size. The ratio is DECLARED, never
+     *  inferred from a recording: a recorded rate is a price at one moment, and
+     *  freezing it as policy would deny ordinary trades later. */
+    minOutputRatio?: {
+        num: string;
+        den: string;
+        inputArgIndex: number;
+        outputArgIndex: number;
+    };
+}
+export interface DeclaredPredicate {
+    predicate: PredicateNode;
+    /** Assumptions the caller should check. Never empty when an argument index
+     *  was defaulted rather than supplied. */
+    warnings: string[];
+}
+/** Lower a declared constraint to a grammar-3 predicate. Pure and total:
+ *  the same declaration always produces the same predicate. */
+export declare function declarePredicate(d: PolicyDeclaration): DeclaredPredicate;

package/dist/synth/declare.js

@@ -0,0 +1,127 @@
+// src/synth/declare.ts - build a predicate from a DECLARED constraint.
+//
+// The second synthesis front-end, beside `synthesizeFromRecording`. That one
+// infers a predicate from a transaction that happened; this one takes the
+// constraint the user states outright. No transaction, no decoding, no
+// inference, no RPC: the same declaration always lowers to a byte-identical
+// predicate.
+//
+// This is the surviving half of the removed `MandateSpec`. Two of that type's
+// five fields lowered to things that do not exist - `spendingLimit` became a
+// `window_spent` compare the interpreter cannot evaluate (it is handed one
+// call and keeps no state), and `approvalThreshold` needed OZ built-in policy
+// contracts that were never deployed. Both are deliberately absent here, and
+// the per-call `maxAmount` bound below is the honest replacement for the
+// first: it constrains the amount in THIS call rather than implying a rolling
+// total nothing tracks.
+//
+// What a declaration can say maps one-to-one onto grammar 4:
+//   fn            -> eq(call_fn, literal_symbol)
+//   contract      -> eq(call_contract, literal_address)
+//   maxAmount     -> lte(call_arg(i), literal_i128)
+//   recipients    -> in(call_arg(j), [literal_address, ...])
+//   minOutputRatio-> gte(call_arg(out), call_arg_scaled(in, num, den))
+import { isStellarAddress } from "./address.js";
+/** Argument positions of the SEP-41 `transfer(from, to, amount)` shape. A
+ *  declaration that names a different method almost certainly has different
+ *  positions, which is why using either default emits a warning naming the
+ *  index it assumed - a bound on the wrong argument constrains something the
+ *  user did not mean and fails silently. */
+const SEP41_RECIPIENT_ARG = 1;
+const SEP41_AMOUNT_ARG = 2;
+/** Lower a declared constraint to a grammar-3 predicate. Pure and total:
+ *  the same declaration always produces the same predicate. */
+export function declarePredicate(d) {
+    if (!d.fn || d.fn.trim() === '') {
+        throw declareError('SYNTHESIS_ERROR', 'a declaration needs `fn`: the method to pin');
+    }
+    const warnings = [];
+    const children = [
+        { op: 'eq', left: { kind: 'call_fn' }, right: { kind: 'literal_symbol', value: d.fn } },
+    ];
+    if (d.contract !== undefined) {
+        if (!isStellarAddress(d.contract) || !d.contract.startsWith('C')) {
+            throw declareError('SYNTHESIS_ERROR', `contract must be a Stellar contract address (C...), got ${d.contract}`);
+        }
+        children.push({
+            op: 'eq',
+            left: { kind: 'call_contract' },
+            right: { kind: 'literal_address', value: d.contract },
+        });
+    }
+    if (d.recipients !== undefined) {
+        if (d.recipients.length === 0) {
+            throw declareError('SYNTHESIS_ERROR', 'recipients was supplied but empty; an empty `in` haystack is refused at decode. Omit it to leave recipients unconstrained.');
+        }
+        for (const r of d.recipients) {
+            if (!isStellarAddress(r)) {
+                throw declareError('SYNTHESIS_ERROR', `recipient is not a Stellar address: ${r}`);
+            }
+        }
+        const idx = d.recipientArgIndex ?? SEP41_RECIPIENT_ARG;
+        if (d.recipientArgIndex === undefined) {
+            warnings.push(`recipient allowlist bound to call_arg(${idx}), the SEP-41 \`transfer\` position. If \`${d.fn}\` carries the recipient elsewhere this constrains the wrong argument - pass recipientArgIndex.`);
+        }
+        children.push({
+            op: 'in',
+            needle: { kind: 'call_arg', index: idx },
+            haystack: d.recipients.map((value) => ({ kind: 'literal_address', value })),
+        });
+    }
+    if (d.maxAmount !== undefined) {
+        if (!/^[0-9]+$/.test(d.maxAmount)) {
+            throw declareError('SYNTHESIS_ERROR', `maxAmount must be an unsigned integer in the token's smallest unit, got "${d.maxAmount}" (25 XLM = "250000000")`);
+        }
+        if (d.maxAmount === '0' && d.allowZeroCap !== true) {
+            throw declareError('SYNTHESIS_ERROR', 'maxAmount "0" denies every call: no amount satisfies the bound. Set allowZeroCap to declare that deliberately.');
+        }
+        const idx = d.amountArgIndex ?? SEP41_AMOUNT_ARG;
+        if (d.amountArgIndex === undefined) {
+            warnings.push(`amount cap bound to call_arg(${idx}), the SEP-41 \`transfer\` position. If \`${d.fn}\` carries the amount elsewhere this caps the wrong argument - pass amountArgIndex.`);
+        }
+        children.push({
+            op: 'lte',
+            left: { kind: 'call_arg', index: idx },
+            right: { kind: 'literal_i128', value: d.maxAmount },
+        });
+    }
+    if (d.minOutputRatio !== undefined) {
+        const { num, den, inputArgIndex, outputArgIndex } = d.minOutputRatio;
+        if (!/^[0-9]+$/.test(num) || !/^[0-9]+$/.test(den)) {
+            throw declareError('SYNTHESIS_ERROR', `minOutputRatio num/den must be unsigned integers, got "${num}"/"${den}" (a 1% slippage tolerance is num "99", den "100")`);
+        }
+        // Both are refused on chain at install (INVALID_SCALED_RATIO). Refusing
+        // here too means the caller learns before a transaction is built.
+        if (den === '0') {
+            throw declareError('SYNTHESIS_ERROR', 'minOutputRatio.den is zero: the ratio has no value');
+        }
+        if (num === '0') {
+            throw declareError('SYNTHESIS_ERROR', 'minOutputRatio.num is zero: the floor would be zero, which constrains nothing. Omit it instead.');
+        }
+        if (inputArgIndex === outputArgIndex) {
+            throw declareError('SYNTHESIS_ERROR', `minOutputRatio bounds arg[${inputArgIndex}] against itself, which is true for any ratio at or below 1 and false above it - never a slippage floor. Pass the distinct input and output positions.`);
+        }
+        if (BigInt(num) > BigInt(den)) {
+            // Demanding MORE out than went in is not slippage protection; it is a
+            // rule that denies every honest trade. Loud beats a policy that never
+            // permits.
+            warnings.push(`minOutputRatio ${num}/${den} is above 1: it requires the output to EXCEED the input, which no ordinary swap satisfies. Check the ratio is not inverted.`);
+        }
+        children.push({
+            op: 'gte',
+            left: { kind: 'call_arg', index: outputArgIndex },
+            right: { kind: 'call_arg_scaled', index: inputArgIndex, num, den },
+        });
+    }
+    // A single conjunct is emitted bare. `and` with one child encodes to
+    // different bytes than the child alone, and the extra node buys nothing.
+    const predicate = children.length === 1 ? children[0] : { op: 'and', children };
+    return { predicate, warnings };
+}
+function declareError(code, message) {
+    const err = new Error(message);
+    err.code = code;
+    err.severity = 'error';
+    err.retryable = false;
+    throw err;
+}

package/dist/synth/index.d.ts

@@ -1,5 +1,6 @@
 export { isStellarAddress } from './address.ts';
 export { type ComposeOptions, type ComposeResult, composeFromRecording, } from './compose-from-recording.ts';
+export { type DeclaredPredicate, declarePredicate, type PolicyDeclaration, } from './declare.ts';
 export { type IntentFacts, lower } from './lower.ts';
 export { type DecideScopeOptions, decideScope, type ScopeDecision, scopeToContextRuleType, } from './scope.ts';
 export { type __TestInterpreterAdapterOptions, type SynthesizeFromRecordingOptions, synthesizeFromRecording, } from './synthesize-from-recording.ts';

package/dist/synth/index.js

@@ -4,6 +4,7 @@
 // and re-deriving it elsewhere means a second address check that can drift.
 export { isStellarAddress } from "./address.js";
 export { composeFromRecording, } from "./compose-from-recording.js";
+export { declarePredicate, } from "./declare.js";
 export { lower } from "./lower.js";
 export { decideScope, scopeToContextRuleType, } from "./scope.js";
 export { synthesizeFromRecording, } from "./synthesize-from-recording.js";

package/dist/synth/synthesize-from-recording.js

@@ -1,7 +1,7 @@
 // src/synth/synthesize-from-recording.ts - recording-path orchestrator.
 //
 // `synthesizeFromRecording` INFERS a bounded policy from a `RecordedTransaction`
-// via the `PolicyIR` + interpreter adapter pair.
+// via the composer + interpreter adapter pair.
 // Flow: validate -> parseConfidence gate -> lower -> decideScope -> composeFromRecording
 // -> interpreter compile + self-verify.
 // Same (tx, opts) -> byte-identical ProposedPolicy (no randomness, clock, globals).

package/dist/types.d.ts

@@ -124,7 +124,7 @@ export type PolicyRef = {
  *  `contracts/policy-interpreter/src/version.rs`. Every value this package puts on
  *  the wire derives from here; `grammar-version-parity.test.ts` pins it to the
  *  contract so a skew cannot pass a green test run. */
-export declare const GRAMMAR_VERSION: 3;
+export declare const GRAMMAR_VERSION: 4;
 /** A serialised predicate document stored against a (smart_account, rule_id) pair. */
 export interface PolicyDocument {
     /** Grammar version baked into the interpreter wasm. Fail-closed strict match at install
@@ -146,14 +146,29 @@ export interface PolicyDocument {
 export type PredicateNode = {
     op: 'and';
     children: PredicateNode[];
+} | {
+    op: 'or';
+    children: PredicateNode[];
 } | {
     op: 'eq';
     left: PredicateLeaf;
     right: PredicateLeaf;
+} | {
+    op: 'lt';
+    left: PredicateLeaf;
+    right: PredicateLeaf;
 } | {
     op: 'lte';
     left: PredicateLeaf;
     right: PredicateLeaf;
+} | {
+    op: 'gt';
+    left: PredicateLeaf;
+    right: PredicateLeaf;
+} | {
+    op: 'gte';
+    left: PredicateLeaf;
+    right: PredicateLeaf;
 } | {
     op: 'in';
     needle: PredicateLeaf;
@@ -174,6 +189,11 @@ export type PredicateLeaf = {
     index: number;
     element: number;
     field: string;
+} | {
+    kind: 'call_arg_scaled';
+    index: number;
+    num: string;
+    den: string;
 } | {
     kind: 'literal_address';
     value: string;

package/dist/types.js

@@ -52,4 +52,4 @@ export const PREDICATE_CAPS = {
  *  `contracts/policy-interpreter/src/version.rs`. Every value this package puts on
  *  the wire derives from here; `grammar-version-parity.test.ts` pins it to the
  *  contract so a skew cannot pass a green test run. */
-export const GRAMMAR_VERSION = 3;
+export const GRAMMAR_VERSION = 4;

package/dist-cjs/adapters/interpreter/adapter.d.ts

@@ -12,9 +12,9 @@ export interface InterpreterAdapterConfig {
      *  rejected as `SCOPE_SELF_CALL`. */
     smartAccountAddress: string;
 }
-/** The result of compiling a PolicyIR for this backend. */
+/** The result of compiling a `ComposedRule` for this backend. */
 export interface CompileResult {
-    /** false => some IR construct this backend cannot express (see `uncovered`). */
+    /** false => some constraint this backend cannot express (see `uncovered`). */
     covered: boolean;
     /** Human-readable list of unsupported constructs. */
     uncovered: string[];

package/dist-cjs/adapters/interpreter/adapter.js

@@ -1,7 +1,7 @@
 "use strict";
-// src/adapters/interpreter/adapter.ts - the interpreter-policy CustodyAdapter.
+// src/adapters/interpreter/adapter.ts - the interpreter-policy adapter.
 //
-// Compiles a PolicyIR to a single interpreter `PolicyDocument` + `PolicyRef`
+// Compiles a `ComposedRule` to a single interpreter `PolicyDocument` + `PolicyRef`
 // carrying the canonical predicate encoding from `predicate/encode.ts`. This is
 // the only backend; the compose step lowers every constraint to it.
 //
@@ -138,7 +138,11 @@ function assertNoSelfCall(node, config) {
         }
     };
     switch (node.op) {
+        // Both boolean nodes recurse. `or` is listed explicitly rather than left
+        // to a default branch: this is a security check, and a new node kind must
+        // fail to compile here rather than silently skip it.
         case 'and':
+        case 'or':
             for (const c of node.children)
                 assertNoSelfCall(c, config);
             return;
@@ -147,7 +151,11 @@ function assertNoSelfCall(node, config) {
             for (const h of node.haystack)
                 checkLeaf(h);
             return;
-        default:
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte':
             checkLeaf(node.left);
             checkLeaf(node.right);
     }

package/dist-cjs/errors.d.ts

@@ -1,4 +1,9 @@
-export type ErrorCode = 'RECORDING_FAILED' | 'RECORDING_VALIDATION_FAILED' | 'SCOPE_UNRESOLVED' | 'SYNTHESIS_ERROR' | 'MALFORMED_PREDICATE' | 'SIMULATION_ERROR' | 'VERIFICATION_FAILED' | 'DENY_CASE_FAILURE' | 'PERMIT_CASE_FAILED' | 'SUMMARY_DRIFT' | 'INSTALL_BUILD_FAILED' | 'INSTALL_CONFIRM_MISSING' | 'INSTALL_CONFIRM_EXPIRED' | 'REVOKE_BUILD_FAILED' | 'REVOKE_CONFIRM_MISSING' | 'USER_REJECTED_SIGN' | 'WALLET_TIMEOUT' | 'WALLET_UNAVAILABLE' | 'PREDICATE_TOO_LARGE' | 'PREDICATE_TOO_DEEP' | 'TOO_MANY_LEAVES' | 'IN_OPERAND_LIMIT' | 'POLICY_CAP_EXCEEDED' | 'WASM_TOO_LARGE' | 'MASTER_AUTH_REQUIRED' | 'NONCE_REPLAY' | 'VERSION_MISMATCH' | 'ARITHMETIC_OVERFLOW' | 'AMOUNT_OVERFLOW' | 'RULE_SIGNERS_CHANGED' | 'SCOPE_SELF_CALL' | 'ARG_MISMATCH' | 'CONTRACT_SCOPE' | 'UNSUPPORTED_NODE' | 'STATEFUL_BOUND' | 'NOT_IN_ALLOWLIST' | 'COMPILE_OK' | 'COMPILE_GATE_FAILED';
+export type ErrorCode = 'RECORDING_FAILED' | 'RECORDING_VALIDATION_FAILED' | 'SCOPE_UNRESOLVED' | 'SYNTHESIS_ERROR' | 'MALFORMED_PREDICATE' | 'SIMULATION_ERROR' | 'VERIFICATION_FAILED' | 'DENY_CASE_FAILURE' | 'PERMIT_CASE_FAILED' | 'SUMMARY_DRIFT' | 'INSTALL_BUILD_FAILED' | 'INSTALL_CONFIRM_MISSING' | 'INSTALL_CONFIRM_EXPIRED' | 'REVOKE_BUILD_FAILED' | 'REVOKE_CONFIRM_MISSING' | 'USER_REJECTED_SIGN' | 'WALLET_TIMEOUT' | 'WALLET_UNAVAILABLE' | 'PREDICATE_TOO_LARGE' | 'PREDICATE_TOO_DEEP' | 'TOO_MANY_LEAVES' | 'IN_OPERAND_LIMIT' | 'POLICY_CAP_EXCEEDED' | 'WASM_TOO_LARGE' | 'MASTER_AUTH_REQUIRED' | 'NONCE_REPLAY' | 'VERSION_MISMATCH' | 'ARITHMETIC_OVERFLOW' | 'AMOUNT_OVERFLOW' | 'RULE_SIGNERS_CHANGED' | 'SCOPE_SELF_CALL' | 'ARG_MISMATCH' | 'CONTRACT_SCOPE' | 'UNSUPPORTED_NODE' | 'STATEFUL_BOUND' | 'NOT_IN_ALLOWLIST'
+/** A comparison against a `call_arg_scaled` operand failed (contract 107). */
+ | 'SLIPPAGE_FLOOR'
+/** A `call_arg_scaled` ratio is zero or non-positive. Refused at install
+ *  (contract 214) and mirrored at encode. */
+ | 'INVALID_SCALED_RATIO' | 'COMPILE_OK' | 'COMPILE_GATE_FAILED';
 export interface ToolError {
     code: ErrorCode;
     message: string;

package/dist-cjs/install/authority-overlap.d.ts

@@ -0,0 +1,101 @@
+import type { PredicateNode, SignerDraft } from '../types.ts';
+/** Wildcard component of a `Selector`: the predicate does not pin this half. */
+export declare const ANY = "*";
+/** A (contract, function) pair a predicate may permit. `ANY` in either half
+ *  means unconstrained, so `{contract: ANY, fn: ANY}` is "any call at all". */
+export interface Selector {
+    contract: string;
+    fn: string;
+}
+export type ContextType = {
+    kind: 'default';
+} | {
+    kind: 'call_contract';
+    contract: string;
+} | {
+    kind: 'create_contract';
+    wasmHash: string;
+};
+/** How much can be said about a neighbouring rule.
+ *  - `interpreter`: policed by our interpreter and the predicate was readable,
+ *    so its authority is known exactly.
+ *  - `foreign`: policed by some other contract. The address is visible, the
+ *    semantics are not, so it needs review by hand.
+ *  - `unpoliced`: no policy at all. Whatever its context type allows, its
+ *    signers may do without constraint. */
+export type RuleClass = 'interpreter' | 'foreign' | 'unpoliced';
+export interface ObservedRule {
+    id: number;
+    contextType: ContextType;
+    signers: SignerDraft[];
+    /** Policy contract addresses attached to the rule, in OZ's order. */
+    policyAddresses: string[];
+    /** Decoded predicate. Present only when the rule is policed by OUR
+     *  interpreter and the stored document was readable. */
+    predicate?: PredicateNode;
+}
+export interface IntendedInstall {
+    /** Rule the predicate is being installed onto. A re-install onto the same
+     *  id REPLACES its predicate rather than adding a second source of
+     *  authority, so that id is skipped. */
+    ruleId: number;
+    contextType: ContextType;
+    signers: SignerDraft[];
+    predicate: PredicateNode;
+}
+export type OverlapSeverity = 
+/** A neighbouring rule imposes no constraint at all on the shared calls. */
+'bypass'
+/** A neighbouring policy exists but what it permits cannot be read. */
+ | 'unknown'
+/** Both rules are ours. The new rule will not restrict the shared calls,
+ *  because the signer names whichever is more permissive. */
+ | 'not-restricting';
+export interface AuthorityOverlap {
+    ruleId: number;
+    ruleClass: RuleClass;
+    severity: OverlapSeverity;
+    /** Signers present in BOTH rules. An overlap is only reachable by a signer
+     *  who can name both, so a rule sharing no signer is not a collision. */
+    sharedSigners: SignerDraft[];
+    /** The selectors both rules can serve. Non-empty by construction. */
+    sharedSelectors: Selector[];
+    advice: string;
+}
+/** Canonical key for signer equality. Mirrors OZ's `Signer` enum: a delegated
+ *  signer is its address, an external signer is the verifier plus the key
+ *  bytes, since one verifier may hold many keys. */
+export declare function signerKey(s: SignerDraft): string;
+/** Intersection of two selector SETS: every compatible pairing survives. */
+export declare function intersectSelectors(a: Selector[], b: Selector[]): Selector[];
+/**
+ * The set of `(contract, fn)` selectors a predicate may permit.
+ *
+ * A deliberate OVER-approximation: every call the predicate actually permits is
+ * covered by some returned selector, and unrecognised structure widens to the
+ * wildcard rather than narrowing. That direction is what makes the emptiness
+ * test sound. A call carries exactly one `(contract, fn)`, so if two
+ * predicates' over-approximations do not intersect, no single call can be
+ * routed to either and the rules provably cannot collide.
+ *
+ * Narrowing instead would be the fail-OPEN direction: it would let this report
+ * "no overlap" for rules that do collide.
+ */
+export declare function permittedSelectors(node: PredicateNode): Selector[];
+/** Selectors a context type admits, before the predicate narrows them. */
+export declare function selectorsForContextType(ct: ContextType): Selector[];
+/** What a rule can actually authorise: its context type narrowed by its
+ *  predicate. An unpoliced or unreadable rule contributes no narrowing. */
+export declare function effectiveSelectors(rule: ObservedRule): Selector[];
+/**
+ * Every existing rule a signer of the intended install could name instead.
+ *
+ * A rule collides when it shares at least one signer AND at least one selector.
+ * Both are needed for the signer to have a choice: same signer but disjoint
+ * calls means no call can be rerouted, and same calls but no shared signer
+ * means nobody can reroute them.
+ */
+export declare function findAuthorityOverlaps(args: {
+    intended: IntendedInstall;
+    existing: ObservedRule[];
+}): AuthorityOverlap[];