@crediolabs/policy-synth 0.3.1 → 0.5.0

package/dist/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/adapters/interpreter/adapter.js

@@ -1,6 +1,6 @@
-// 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.
 //
@@ -133,7 +133,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;
@@ -142,7 +146,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/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/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[];

package/dist/install/authority-overlap.js

@@ -0,0 +1,239 @@
+// src/install/authority-overlap.ts - cross-rule authority analysis.
+//
+// An OZ smart account selects a context rule by CALLER DECLARATION and enforces
+// only the policies of the rule that was named. A signer belonging to several
+// rules therefore picks which one applies, so for any given call their
+// authority is the MAXIMUM over the matching rules, never the intersection.
+//
+// The consequence is the one that catches people: installing a second, tighter
+// rule restricts nothing. A key that also sits on an unpoliced rule is not
+// constrained at all - it names that rule and the predicate never runs. This
+// module detects that at install time, before the caller acts on a policy that
+// looks binding and is not.
+//
+// Not theoretical. Proven on chain 2026-08-22: the same key, the same account
+// and the same forbidden call was denied `#100` naming the policed rule and
+// PERMITTED naming an unpoliced one. It happened in this project's own end-to-
+// end harness, written by the author of the grammar, and was caught by review
+// rather than by tooling - which is why the tooling now exists.
+//
+// Adapted to grammar 3 from the version published in `@crediolabs/policy-synth`
+// 0.2.0, which came from the `octogate` repository and was lost when the npm
+// lineage moved here. `or` and `not` are gone from the grammar, so the cases
+// handling them are gone too; oracle bounds are gone from the stored document.
+//
+// Pure: no network. The caller supplies the account's rules.
+/** Wildcard component of a `Selector`: the predicate does not pin this half. */
+export const ANY = '*';
+// ---- signer identity ----
+/** 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 function signerKey(s) {
+    return s.kind === 'delegated' ? `delegated:${s.address}` : `external:${s.verifier}:${s.keyBytes}`;
+}
+function sharedSigners(a, b) {
+    const bKeys = new Set(b.map(signerKey));
+    return a.filter((s) => bKeys.has(signerKey(s)));
+}
+// ---- selector extraction ----
+const WILDCARD = { contract: ANY, fn: ANY };
+function selectorKey(s) {
+    return `${s.contract} ${s.fn}`;
+}
+function dedupe(sels) {
+    const seen = new Map();
+    for (const s of sels)
+        seen.set(selectorKey(s), s);
+    return [...seen.values()];
+}
+/** Intersect one pair. `ANY` absorbs, equal literals survive, and two
+ *  different literals cannot both hold for a single call. */
+function intersectOne(a, b) {
+    const contract = a.contract === ANY
+        ? b.contract
+        : b.contract === ANY
+            ? a.contract
+            : a.contract === b.contract
+                ? a.contract
+                : null;
+    if (contract === null)
+        return null;
+    const fn = a.fn === ANY ? b.fn : b.fn === ANY ? a.fn : a.fn === b.fn ? a.fn : null;
+    if (fn === null)
+        return null;
+    return { contract, fn };
+}
+/** Intersection of two selector SETS: every compatible pairing survives. */
+export function intersectSelectors(a, b) {
+    const out = [];
+    for (const x of a) {
+        for (const y of b) {
+            const hit = intersectOne(x, y);
+            if (hit)
+                out.push(hit);
+        }
+    }
+    return dedupe(out);
+}
+function literalAddress(leaf) {
+    return leaf.kind === 'literal_address' ? leaf.value : null;
+}
+function literalSymbol(leaf) {
+    return leaf.kind === 'literal_symbol' ? leaf.value : null;
+}
+/** Selector pinned by a single `eq`, whichever side the literal sits on. */
+function selectorFromEq(left, right) {
+    if (left.kind === 'call_contract') {
+        const addr = literalAddress(right);
+        return addr === null ? null : { contract: addr, fn: ANY };
+    }
+    if (right.kind === 'call_contract') {
+        const addr = literalAddress(left);
+        return addr === null ? null : { contract: addr, fn: ANY };
+    }
+    if (left.kind === 'call_fn') {
+        const sym = literalSymbol(right);
+        return sym === null ? null : { contract: ANY, fn: sym };
+    }
+    if (right.kind === 'call_fn') {
+        const sym = literalSymbol(left);
+        return sym === null ? null : { contract: ANY, fn: sym };
+    }
+    return null;
+}
+/**
+ * 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 function permittedSelectors(node) {
+    switch (node.op) {
+        case 'and': {
+            // Every conjunct must hold at once, so the permitted set is the
+            // intersection. Intersecting over-approximations stays one.
+            let acc = [WILDCARD];
+            for (const child of node.children)
+                acc = intersectSelectors(acc, permittedSelectors(child));
+            return acc;
+        }
+        case 'or': {
+            // Any branch may hold, so the permitted set is the UNION. A union of
+            // over-approximations is still an over-approximation, so this keeps the
+            // fail-safe direction while staying tighter than the wildcard the
+            // default branch would give. Precision matters here: `or` is how a
+            // policy says "pair A or pair B", and widening that to the wildcard
+            // would report an overlap against every rule on the account.
+            const acc = [];
+            for (const child of node.children)
+                acc.push(...permittedSelectors(child));
+            return dedupe(acc);
+        }
+        case 'eq': {
+            const sel = selectorFromEq(node.left, node.right);
+            return sel === null ? [WILDCARD] : [sel];
+        }
+        case 'in': {
+            // Set membership over the selector halves: `call_fn in {a, b}` permits
+            // both. A haystack element that is not the matching literal kind makes
+            // the node uninformative rather than narrower.
+            if (node.needle.kind === 'call_contract') {
+                const addrs = node.haystack.map(literalAddress);
+                if (addrs.some((a) => a === null))
+                    return [WILDCARD];
+                return dedupe(addrs.map((a) => ({ contract: a, fn: ANY })));
+            }
+            if (node.needle.kind === 'call_fn') {
+                const syms = node.haystack.map(literalSymbol);
+                if (syms.some((s) => s === null))
+                    return [WILDCARD];
+                return dedupe(syms.map((s) => ({ contract: ANY, fn: s })));
+            }
+            return [WILDCARD];
+        }
+        default:
+            // `lte` binds an amount, never the selector.
+            return [WILDCARD];
+    }
+}
+/** Selectors a context type admits, before the predicate narrows them. */
+export function selectorsForContextType(ct) {
+    switch (ct.kind) {
+        case 'default':
+            return [WILDCARD];
+        case 'call_contract':
+            return [{ contract: ct.contract, fn: ANY }];
+        case 'create_contract':
+            // A contract-creation context is a different `Context` shape. The
+            // interpreter refuses anything that is not `Context::Contract`, and a
+            // creation rule can never serve a call, so it shares no selector.
+            return [];
+    }
+}
+/** What a rule can actually authorise: its context type narrowed by its
+ *  predicate. An unpoliced or unreadable rule contributes no narrowing. */
+export function effectiveSelectors(rule) {
+    const fromType = selectorsForContextType(rule.contextType);
+    if (!rule.predicate)
+        return fromType;
+    return intersectSelectors(fromType, permittedSelectors(rule.predicate));
+}
+function classifyRule(rule) {
+    if (rule.policyAddresses.length === 0)
+        return 'unpoliced';
+    return rule.predicate ? 'interpreter' : 'foreign';
+}
+function adviceFor(cls, ruleId) {
+    switch (cls) {
+        case 'unpoliced':
+            return `rule ${ruleId} has no policy attached, so a shared signer may make these calls with no constraint at all - the predicate you are installing will never run for them. Remove the shared signer from rule ${ruleId}, or attach a policy to it.`;
+        case 'foreign':
+            return `rule ${ruleId} is policed by a contract this tool cannot decode, so its authority over these calls is unknown. Review it by hand before relying on the new rule.`;
+        case 'interpreter':
+            return `a shared signer may name rule ${ruleId} instead, so the new rule will not restrict these calls. To TIGHTEN, edit rule ${ruleId} itself rather than adding a second rule. To ADD a separate capability, keep both and expect neither to constrain the other.`;
+    }
+}
+/**
+ * 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 function findAuthorityOverlaps(args) {
+    const intendedSelectors = intersectSelectors(selectorsForContextType(args.intended.contextType), permittedSelectors(args.intended.predicate));
+    const out = [];
+    for (const rule of args.existing) {
+        if (rule.id === args.intended.ruleId)
+            continue;
+        const shared = sharedSigners(args.intended.signers, rule.signers);
+        if (shared.length === 0)
+            continue;
+        const sharedSelectors = intersectSelectors(intendedSelectors, effectiveSelectors(rule));
+        if (sharedSelectors.length === 0)
+            continue;
+        const ruleClass = classifyRule(rule);
+        out.push({
+            ruleId: rule.id,
+            ruleClass,
+            severity: ruleClass === 'unpoliced'
+                ? 'bypass'
+                : ruleClass === 'foreign'
+                    ? 'unknown'
+                    : 'not-restricting',
+            sharedSigners: shared,
+            sharedSelectors,
+            advice: adviceFor(ruleClass, rule.id),
+        });
+    }
+    return out;
+}

package/dist/install/build-add-context-rule.d.ts

@@ -23,7 +23,7 @@ export interface BuildAddContextRuleArgs {
      *  before the chain does; the contract will refuse a mismatch again. */
     grammarVersion?: number;
 }
-export declare const DEFAULT_GRAMMAR_VERSION: 3;
+export declare const DEFAULT_GRAMMAR_VERSION: 4;
 /** The verb `add_context_rule` takes on the wire. */
 export declare const ADD_CONTEXT_RULE_SYMBOL: "add_context_rule";
 /** Tuple of `ScVal` arguments to pass to `Operation.invokeHostFunction` for

package/dist/install/index.d.ts

@@ -1 +1,2 @@
+export { ANY, type AuthorityOverlap, type ContextType, effectiveSelectors, findAuthorityOverlaps, type IntendedInstall, intersectSelectors, type ObservedRule, type OverlapSeverity, permittedSelectors, type RuleClass, type Selector, selectorsForContextType, signerKey, } from './authority-overlap.ts';
 export { ADD_CONTEXT_RULE_SYMBOL, type AddContextRuleArgs, type BuildAddContextRuleArgs, buildAddContextRuleArgs, DEFAULT_GRAMMAR_VERSION, } from './build-add-context-rule.ts';

package/dist/install/index.js

@@ -12,4 +12,8 @@
 // Exported here rather than from the package root to keep the root surface
 // about synthesis, and because these are transaction-building primitives whose
 // callers should know they are reaching for them.
+// Cross-rule authority analysis. Exported because the check has to happen
+// wherever an install is BUILT, and a client that assembles its own
+// `add_context_rule` call never reaches `runInstallPolicy`.
+export { ANY, effectiveSelectors, findAuthorityOverlaps, intersectSelectors, permittedSelectors, selectorsForContextType, signerKey, } from "./authority-overlap.js";
 export { ADD_CONTEXT_RULE_SYMBOL, buildAddContextRuleArgs, DEFAULT_GRAMMAR_VERSION, } from "./build-add-context-rule.js";

package/dist/install/read-account-rules.d.ts

@@ -0,0 +1,79 @@
+import { rpc, xdr } from '@stellar/stellar-sdk';
+import type { SignerDraft } from '../types.ts';
+import type { ContextType, ObservedRule } from './authority-overlap.ts';
+/** `storage.rs` - the third element of the persistent doc key tuple. */
+export declare const K_DOC = 1;
+/** Persistent-storage key for a rule's stored document:
+ *  `(account, rule_id, K_DOC)`. */
+export declare function docKeyScVal(smartAccount: string, ruleId: number): xdr.ScVal;
+/** Ledger key for the interpreter's persistent entry holding that document. */
+export declare function docLedgerKey(interpreter: string, smartAccount: string, ruleId: number): xdr.LedgerKey;
+/** OZ `ContextRuleType`. An unrecognised tag is reported as `default`, which
+ *  is the widest reading and therefore the safe one: it makes the rule look
+ *  like it could serve any call, so overlap is over-reported, never missed. */
+export declare function decodeContextType(v: xdr.ScVal | undefined): ContextType;
+/** OZ `Signer::Delegated(Address) | Signer::External(Address, Bytes)`. */
+export declare function decodeSigner(v: xdr.ScVal): SignerDraft | undefined;
+/** A full OZ `ContextRule` as returned by `get_context_rule(id)`.
+ *  `predicate` is filled in separately from the ledger entry. */
+export declare function decodeContextRule(v: xdr.ScVal): ObservedRule | undefined;
+/** The interpreter's `StoredDoc { predicate_bytes }`. */
+export declare function decodeStoredPredicateBytes(v: xdr.ScVal): Buffer | undefined;
+/** The three reads the scan needs. Kept as an interface so the collection
+ *  below is testable without a network. */
+export interface AccountRuleReader {
+    /** OZ `get_context_rules_count()`. */
+    getContextRuleCount(smartAccount: string): Promise<number>;
+    /** OZ `get_context_rule(id)`. Undefined when the id is absent. */
+    getContextRule(smartAccount: string, ruleId: number): Promise<xdr.ScVal | undefined>;
+    /** The interpreter's persistent `StoredDoc` entry, read as a ledger entry.
+     *  Undefined when no document is stored for that rule. */
+    getStoredDoc(interpreter: string, smartAccount: string, ruleId: number): Promise<xdr.ScVal | undefined>;
+}
+/** How far the id scan will probe before giving up. OZ imposes no per-account
+ *  rule cap, so there is no exact bound to derive; this one is far above any
+ *  realistic account and keeps a malformed `Count` from spinning forever. */
+export declare const MAX_RULE_ID_SCAN = 512;
+export interface CollectedRules {
+    rules: ObservedRule[];
+    /** Rule ids whose stored predicate could not be read even though the
+     *  interpreter is attached. Such a rule is reported without a predicate,
+     *  which classifies it as opaque rather than as safely narrow. */
+    unreadablePredicateRuleIds: number[];
+    /** True when the scan stopped before accounting for every live rule. The
+     *  result is then a SUBSET of the account's rules, so an empty overlap list
+     *  proves nothing and the caller must not present it as safety. */
+    incomplete: boolean;
+}
+/**
+ * Every context rule on the account, with predicates filled in for the rules
+ * our interpreter polices.
+ *
+ * Rule ids are NOT contiguous. OZ assigns them from a monotonic `NextId` and
+ * decrements `Count` on removal without ever reusing an id, so after any
+ * removal `Count < NextId` and the live ids have gaps. Iterating `0..Count-1`
+ * would silently skip live rules at higher ids, and a skipped rule is a missed
+ * overlap - the one error that reports safety which does not exist. Instead the
+ * scan walks ids upward until it has accounted for `Count` live rules.
+ *
+ * A rule whose predicate cannot be read is deliberately left without one. That
+ * demotes it to the `foreign` class, so the scan reports it as opaque instead
+ * of assuming it is narrow.
+ */
+export declare function collectObservedRules(args: {
+    reader: AccountRuleReader;
+    smartAccount: string;
+    interpreterAddress: string;
+    maxRuleIdScan?: number;
+}): Promise<CollectedRules>;
+/**
+ * An `AccountRuleReader` over a live RPC server.
+ *
+ * The two OZ getters are read-only simulations: the source account is
+ * constructed locally because a simulation never checks its sequence number,
+ * and asking the network for a random key would 404.
+ *
+ * The stored document is fetched as a ledger entry rather than a contract
+ * call, because the interpreter publishes no getter for it.
+ */
+export declare function accountRuleReaderFromServer(server: rpc.Server, networkPassphrase: string): AccountRuleReader;