@crediolabs/policy-synth 0.3.1 → 0.4.0

package/dist/run/schemas.js

@@ -246,6 +246,26 @@ export const VerifyPolicyInputSchema = SimulatePolicyInputSchema;
  *  the temporal dead zone (no JS hoisting for `const`). */
 const MAX_SIGNERS_PER_RULE = 15;
 const MAX_POLICIES_PER_RULE = 5;
+const SignerDraftSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('delegated'), address: z.string() }),
+    z.object({ kind: z.literal('external'), verifier: z.string(), keyBytes: z.string() }),
+]);
+const ContextTypeSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('default') }),
+    z.object({ kind: z.literal('call_contract'), contract: z.string() }),
+    z.object({ kind: z.literal('create_contract'), wasmHash: z.string() }),
+]);
+/** A rule ALREADY on the account, as the caller observed it. Supplying these
+ *  turns on the cross-rule authority scan: a signer belonging to several rules
+ *  picks which one applies, so a predicate only constrains a key when the
+ *  policed rule is the only rule that key is on. */
+export const ObservedRuleSchema = z.object({
+    id: z.number().int().nonnegative(),
+    contextType: ContextTypeSchema,
+    signers: z.array(SignerDraftSchema),
+    policyAddresses: z.array(z.string()),
+    predicate: PredicateNodeSchema.optional(),
+});
 const ContextRuleDraftSchema = z
     .object({
     contextRuleType: z.discriminatedUnion('kind', [
@@ -335,8 +355,40 @@ export const NETWORK_PASSPHRASES = {
 // `sourceAccount` is the signing wallet (G...).
 const STELLAR_CONTRACT_ADDRESS = /^C[2-7A-Z]{55}$/;
 const STELLAR_ACCOUNT_ADDRESS = /^G[2-7A-Z]{55}$/;
+// ===== declare_policy =====
+//
+// The declarative front-end: the constraint stated outright, with no
+// transaction to decode. Deliberately NOT a revival of the removed
+// `MandateSpec` - that carried a rolling `spendingLimit` the interpreter
+// cannot evaluate and an `approvalThreshold` needing OZ primitives nobody
+// deployed. Only fields grammar 3 can actually enforce appear here.
+export const DeclarePolicyInputSchema = z
+    .object({
+    fn: z.string().min(1, 'fn must name the method to pin'),
+    contract: z
+        .string()
+        .regex(STELLAR_CONTRACT_ADDRESS, 'contract must be a Stellar contract address (C...)')
+        .optional(),
+    /** Smallest unit, unsigned decimal STRING - an i128 is wider than
+     *  Number.MAX_SAFE_INTEGER, so a number here would silently round. */
+    maxAmount: z
+        .string()
+        .regex(/^[0-9]+$/, 'maxAmount must be an unsigned integer in the smallest unit')
+        .optional(),
+    amountArgIndex: z.number().int().nonnegative().max(U32_MAX).optional(),
+    recipients: z.array(z.string()).min(1, 'recipients must not be empty').optional(),
+    recipientArgIndex: z.number().int().nonnegative().max(U32_MAX).optional(),
+    allowZeroCap: z.boolean().optional(),
+})
+    .strict();
 export const InstallPolicyInputSchema = z
     .object({
+    /** Rules already on the account. Supplying them turns on the cross-rule
+     *  authority scan, which reports every existing rule a signer of this
+     *  install could name INSTEAD - including an unpoliced one, against which
+     *  the predicate never runs. Absent means the scan is skipped, and the
+     *  result says so rather than reporting "no overlaps found". */
+    existingRules: z.array(ObservedRuleSchema).optional(),
     /** The smart account contract address (C...) that will receive the rule. */
     smartAccount: z
         .string()

package/dist/synth/declare.d.ts

@@ -0,0 +1,30 @@
+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;
+}
+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,98 @@
+// 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 3:
+//   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, ...])
+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 },
+        });
+    }
+    // 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-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[];

package/dist-cjs/install/authority-overlap.js

@@ -0,0 +1,236 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANY = void 0;
+exports.signerKey = signerKey;
+exports.intersectSelectors = intersectSelectors;
+exports.permittedSelectors = permittedSelectors;
+exports.selectorsForContextType = selectorsForContextType;
+exports.effectiveSelectors = effectiveSelectors;
+exports.findAuthorityOverlaps = findAuthorityOverlaps;
+/** Wildcard component of a `Selector`: the predicate does not pin this half. */
+exports.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. */
+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: exports.ANY, fn: exports.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 === exports.ANY
+        ? b.contract
+        : b.contract === exports.ANY
+            ? a.contract
+            : a.contract === b.contract
+                ? a.contract
+                : null;
+    if (contract === null)
+        return null;
+    const fn = a.fn === exports.ANY ? b.fn : b.fn === exports.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. */
+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: exports.ANY };
+    }
+    if (right.kind === 'call_contract') {
+        const addr = literalAddress(left);
+        return addr === null ? null : { contract: addr, fn: exports.ANY };
+    }
+    if (left.kind === 'call_fn') {
+        const sym = literalSymbol(right);
+        return sym === null ? null : { contract: exports.ANY, fn: sym };
+    }
+    if (right.kind === 'call_fn') {
+        const sym = literalSymbol(left);
+        return sym === null ? null : { contract: exports.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.
+ */
+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 '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: exports.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: exports.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. */
+function selectorsForContextType(ct) {
+    switch (ct.kind) {
+        case 'default':
+            return [WILDCARD];
+        case 'call_contract':
+            return [{ contract: ct.contract, fn: exports.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. */
+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.
+ */
+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-cjs/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-cjs/install/index.js

@@ -1,6 +1,4 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_GRAMMAR_VERSION = exports.buildAddContextRuleArgs = exports.ADD_CONTEXT_RULE_SYMBOL = void 0;
 // Public entry for the install-argument builders.
 //
 // `buildAddContextRuleArgs` is the encoder `runInstallPolicy` uses to turn a
@@ -15,6 +13,19 @@ exports.DEFAULT_GRAMMAR_VERSION = exports.buildAddContextRuleArgs = exports.ADD_
 // 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_GRAMMAR_VERSION = exports.buildAddContextRuleArgs = exports.ADD_CONTEXT_RULE_SYMBOL = exports.signerKey = exports.selectorsForContextType = exports.permittedSelectors = exports.intersectSelectors = exports.findAuthorityOverlaps = exports.effectiveSelectors = exports.ANY = void 0;
+// 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`.
+var authority_overlap_ts_1 = require("./authority-overlap.js");
+Object.defineProperty(exports, "ANY", { enumerable: true, get: function () { return authority_overlap_ts_1.ANY; } });
+Object.defineProperty(exports, "effectiveSelectors", { enumerable: true, get: function () { return authority_overlap_ts_1.effectiveSelectors; } });
+Object.defineProperty(exports, "findAuthorityOverlaps", { enumerable: true, get: function () { return authority_overlap_ts_1.findAuthorityOverlaps; } });
+Object.defineProperty(exports, "intersectSelectors", { enumerable: true, get: function () { return authority_overlap_ts_1.intersectSelectors; } });
+Object.defineProperty(exports, "permittedSelectors", { enumerable: true, get: function () { return authority_overlap_ts_1.permittedSelectors; } });
+Object.defineProperty(exports, "selectorsForContextType", { enumerable: true, get: function () { return authority_overlap_ts_1.selectorsForContextType; } });
+Object.defineProperty(exports, "signerKey", { enumerable: true, get: function () { return authority_overlap_ts_1.signerKey; } });
 var build_add_context_rule_ts_1 = require("./build-add-context-rule.js");
 Object.defineProperty(exports, "ADD_CONTEXT_RULE_SYMBOL", { enumerable: true, get: function () { return build_add_context_rule_ts_1.ADD_CONTEXT_RULE_SYMBOL; } });
 Object.defineProperty(exports, "buildAddContextRuleArgs", { enumerable: true, get: function () { return build_add_context_rule_ts_1.buildAddContextRuleArgs; } });

package/dist-cjs/record/index.d.ts

@@ -1,4 +1,5 @@
 import type { ToolResponse } from '../errors.ts';
+import { type SpecFetcher } from '../registry/on-chain-spec.ts';
 import type { Network, RecordedTransaction } from '../types.ts';
 import { type RpcFetcher } from './rpc.ts';
 /** Public input shape. The brief pins:
@@ -27,6 +28,15 @@ export interface RecordInput {
      *  automatically; tests can pass a deterministic stub. */
     crossNetworkFetcher?: RpcFetcher;
     confidenceOverride?: number;
+    /** Read a contract's own interface off chain when the compiled-in registry
+     *  does not recognise it. Default ON: the registry covers the protocols we
+     *  pinned by hand, and refusing everything else reported `no-abi` for
+     *  contracts that publish a full typed spec. Set false to record against
+     *  the registry alone (no extra RPC). */
+    resolveContractSpecs?: boolean;
+    /** Test seam for the spec lookup. Unset in production, where it is built
+     *  from the network's pinned RPC URL. */
+    specFetcher?: SpecFetcher;
 }
 export type RecordResult = ToolResponse<RecordedTransaction>;
 export declare function recordTransaction(input: RecordInput): Promise<RecordResult>;

package/dist-cjs/record/index.js

@@ -19,11 +19,40 @@
 // defined in src/errors.ts.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.recordTransaction = recordTransaction;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const on_chain_spec_ts_1 = require("../registry/on-chain-spec.js");
 const decode_ts_1 = require("./decode.js");
 const freshness_ts_1 = require("./freshness.js");
 const movements_ts_1 = require("./movements.js");
 const rpc_ts_1 = require("./rpc.js");
 const validate_ts_1 = require("./validate.js");
+/** Second pass over the contracts the compiled-in registry did not recognise.
+ *
+ *  Each candidate's own interface is read off chain and every call it received
+ *  is checked against it; the ones that verify are fed back through the decoder
+ *  as known. Re-decoding rather than patching the first result keeps ONE code
+ *  path computing parseConfidence - a hand-adjusted count here would be a
+ *  second implementation of the gate, free to drift from the real one.
+ *
+ *  Only ever ADDS recognition. A missing spec, an unreachable RPC or a call the
+ *  interface does not describe all leave the recording exactly as it was. */
+async function resolveByOnChainSpec(input, decoded, redecode) {
+    if (input.resolveContractSpecs === false)
+        return decoded;
+    if (decoded.unknownContracts.length === 0)
+        return decoded;
+    const fetcher = input.specFetcher ??
+        (0, on_chain_spec_ts_1.specFetcherFromRpc)(rpc_ts_1.PUBLIC_RPC_URLS[input.network], input.network === 'mainnet' ? stellar_sdk_1.Networks.PUBLIC : stellar_sdk_1.Networks.TESTNET);
+    let resolved;
+    try {
+        resolved = await (0, on_chain_spec_ts_1.resolveContractsByOnChainSpec)(decoded.invocations, decoded.unknownContracts.map((u) => u.contract), fetcher);
+    }
+    catch {
+        // A lookup failure must not fail the recording that already succeeded.
+        return decoded;
+    }
+    return resolved.size === 0 ? decoded : redecode(resolved);
+}
 async function recordTransaction(input) {
     if (!input.network) {
         return err('RECORDING_FAILED', 'network required', false);
@@ -79,6 +108,7 @@ async function recordTransaction(input) {
                 return err('RECORDING_FAILED', e.message, false);
             throw e;
         }
+        decoded = await resolveByOnChainSpec(input, decoded, (known) => (0, decode_ts_1.decodeEnvelope)(fetched.envelopeXdr, events, [], fetched.ledger, known, input.network));
         return finish(input.network, decoded, input.confidenceOverride);
     }
     // XDR mode has no raw on-chain events, so the events-based cross-check is
@@ -96,6 +126,7 @@ async function recordTransaction(input) {
             return err('RECORDING_FAILED', e.message, false);
         return err('RECORDING_FAILED', `failed to decode base64 envelope XDR: ${e.message}`, false);
     }
+    decoded = await resolveByOnChainSpec(input, decoded, (known) => (0, decode_ts_1.decodeEnvelopeXdr)(xdrStr, [], [], 0, known, input.network));
     return finish(input.network, decoded, input.confidenceOverride);
 }
 function combineEvents(raw) {