@crediolabs/policy-synth 0.1.4 → 0.1.6

package/dist-cjs/registry/identify.js

@@ -0,0 +1,87 @@
+"use strict";
+// src/registry/identify.ts - protocol identification (fail-closed).
+//
+// Given a (contract, method, args) triple, decide whether the call belongs
+// to a known protocol. Returns null when it does NOT - the caller MUST
+// preserve the fail-closed posture for null results.
+//
+// Recognition rules:
+//   1. SEP-41: recognised by INTERFACE - any contract calling one of the
+//      SEP-41 fns (transfer / mint / burn / approve) with a matching arg
+//      shape is a SEP-41 token. No address pin is needed.
+//   2. Blend: recognised by INTERFACE - real pool `submit` / `claim` calls
+//      hit per-pool instances, not the factory. The arg shape must match
+//      the Blend pool ABI (verified against the pool contract source).
+//      Address recognition still applies when the call is against the
+//      pinned factory address, with the same arg-shape check.
+//   3. SoroSwap: recognised by ADDRESS only - the router is a single pinned
+//      contract. FIX 4: the method must ALSO be present in the protocol's
+//      ABI; an unknown method on a pinned router -> null (fail-closed).
+//
+// Method lookup uses `Object.hasOwn` rather than `in` so prototype-chain
+// names like `constructor`, `toString`, `hasOwnProperty` do NOT register as
+// valid method calls. Arg-shape validation compares arg count + each arg's
+// ScVal subset type against the ABI signature; mismatch -> null.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identifyProtocol = identifyProtocol;
+const known_addresses_ts_1 = require("./known-addresses.js");
+const protocols_ts_1 = require("./protocols.js");
+/** Identify the protocol for a single (contract, method, args) invocation.
+ *  Returns null on ANY mismatch (method not in ABI, arg count off, arg type
+ *  off, or unknown method on a pinned address). The caller MUST keep the
+ *  null path fail-closed. */
+function identifyProtocol(contract, method, args, network) {
+    // 1) SEP-41 by interface. Any contract whose (method, args) matches a
+    //    SEP-41 ABI signature is a SEP-41 token.
+    if (Object.hasOwn(protocols_ts_1.SEP41_ABI, method)) {
+        const sig = protocols_ts_1.SEP41_ABI[method];
+        if (sig && argsMatchAbi(sig.args, args)) {
+            return { protocol: 'sep41', fn: method };
+        }
+        return null;
+    }
+    // 2) Blend by interface. Real pool calls hit per-pool instances; pinned
+    //    factory calls also match here when the method is in the pool ABI.
+    if (Object.hasOwn(protocols_ts_1.BLEND_ABI, method)) {
+        const sig = protocols_ts_1.BLEND_ABI[method];
+        if (sig && argsMatchAbi(sig.args, args)) {
+            return { protocol: 'blend', fn: method };
+        }
+        return null;
+    }
+    // 3) Pinned-address recognition (Blend factory + SoroSwap router/factory).
+    //    FIX 4: the method must also be in the protocol's ABI; an unknown
+    //    method on a pinned address -> null.
+    if (network) {
+        const pinned = (0, known_addresses_ts_1.addressToProtocol)(contract, network);
+        if (pinned) {
+            const abi = pinned === 'blend' ? protocols_ts_1.BLEND_ABI : protocols_ts_1.SOROSWAP_ABI;
+            if (Object.hasOwn(abi, method)) {
+                const sig = abi[method];
+                if (sig && argsMatchAbi(sig.args, args)) {
+                    return { protocol: pinned, fn: method };
+                }
+            }
+        }
+    }
+    void contract;
+    return null;
+}
+/** Compare the decoded args against the ABI signature. Returns true only when
+ *  the arg count matches AND every arg's ScVal subset type matches the ABI's
+ *  declared type. `other` is intentionally NOT a valid ABI match - it means
+ *  the decoder couldn't classify the value, which is exactly the signal
+ *  fail-closed should refuse. */
+function argsMatchAbi(expected, actual) {
+    if (expected.length !== actual.length)
+        return false;
+    for (let i = 0; i < expected.length; i += 1) {
+        const want = expected[i];
+        const got = actual[i];
+        if (!want || !got)
+            return false;
+        if (want.type !== got.type)
+            return false;
+    }
+    return true;
+}

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

@@ -0,0 +1,3 @@
+export { type IdentifiedProtocol, identifyProtocol, } from './identify.ts';
+export { addressToProtocol, KNOWN_ADDRESSES, type KnownAddressesByNetwork, type KnownAddressesByProtocol, } from './known-addresses.ts';
+export { type AbiArg, type AbiEntry, BLEND_ABI, getAbi, PROTOCOL_ABIS, type ProtocolAbi, type ProtocolId, SEP41_ABI, SOROSWAP_ABI, } from './protocols.ts';

package/dist-cjs/registry/index.js

@@ -0,0 +1,15 @@
+"use strict";
+// src/registry/index.ts - re-export the protocol adjacency registry.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SOROSWAP_ABI = exports.SEP41_ABI = exports.PROTOCOL_ABIS = exports.getAbi = exports.BLEND_ABI = exports.KNOWN_ADDRESSES = exports.addressToProtocol = exports.identifyProtocol = void 0;
+var identify_ts_1 = require("./identify.js");
+Object.defineProperty(exports, "identifyProtocol", { enumerable: true, get: function () { return identify_ts_1.identifyProtocol; } });
+var known_addresses_ts_1 = require("./known-addresses.js");
+Object.defineProperty(exports, "addressToProtocol", { enumerable: true, get: function () { return known_addresses_ts_1.addressToProtocol; } });
+Object.defineProperty(exports, "KNOWN_ADDRESSES", { enumerable: true, get: function () { return known_addresses_ts_1.KNOWN_ADDRESSES; } });
+var protocols_ts_1 = require("./protocols.js");
+Object.defineProperty(exports, "BLEND_ABI", { enumerable: true, get: function () { return protocols_ts_1.BLEND_ABI; } });
+Object.defineProperty(exports, "getAbi", { enumerable: true, get: function () { return protocols_ts_1.getAbi; } });
+Object.defineProperty(exports, "PROTOCOL_ABIS", { enumerable: true, get: function () { return protocols_ts_1.PROTOCOL_ABIS; } });
+Object.defineProperty(exports, "SEP41_ABI", { enumerable: true, get: function () { return protocols_ts_1.SEP41_ABI; } });
+Object.defineProperty(exports, "SOROSWAP_ABI", { enumerable: true, get: function () { return protocols_ts_1.SOROSWAP_ABI; } });

package/dist-cjs/registry/known-addresses.d.ts

@@ -0,0 +1,16 @@
+import type { ProtocolId } from './protocols.ts';
+/** Pinned contract addresses per (network, protocol). Empty list = no
+ *  addresses pinned for that cell. */
+export interface KnownAddressesByProtocol {
+    blend: string[];
+    soroswap: string[];
+}
+export interface KnownAddressesByNetwork {
+    mainnet: KnownAddressesByProtocol;
+    testnet: KnownAddressesByProtocol;
+}
+export declare const KNOWN_ADDRESSES: KnownAddressesByNetwork;
+/** Map a (contract, network) pair to its pinned protocol id. Returns null
+ *  when the address is not pinned for that network - callers MUST preserve
+ *  the fail-closed posture for unpinned contracts. */
+export declare function addressToProtocol(contract: string, network: 'mainnet' | 'testnet'): ProtocolId | null;

package/dist-cjs/registry/known-addresses.js

@@ -0,0 +1,53 @@
+"use strict";
+// src/registry/known-addresses.ts - pinned real protocol contract addresses.
+//
+// Addresses here are fetched from authoritative public sources:
+//   - Blend mainnet: docs.blend.capital/mainnet-deployments
+//     https://docs.blend.capital/mainnet-deployments
+//   - SoroSwap mainnet: github.com/soroswap (organisation README)
+//     https://github.com/soroswap
+//
+// Testnet addresses are intentionally NOT pinned: the public docs do not
+// publish them, and per the task brief, unconfirmed addresses are marked
+// [VERIFY] and excluded from the active set rather than invented.
+//
+// SEP-41 is recognised by interface (any token), so no address list is needed
+// for it - see identify.ts.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWN_ADDRESSES = void 0;
+exports.addressToProtocol = addressToProtocol;
+// Source: https://docs.blend.capital/mainnet-deployments (Blend Pool Factory
+// mainnet deployment, fetched 2026-07-23).
+const BLEND_MAINNET_POOL_FACTORY = 'CDSYOAVXFY7SM5S64IZPPPYB4GVGGLMQVFREPSQQEZVIWXX5R23G4QSU';
+// Source: https://github.com/soroswap (organisation README, fetched 2026-07-23)
+// SoroswapRouter mainnet deployment.
+const SOROSWAP_MAINNET_ROUTER = 'CAG5LRYQ5JVEUI5TEID72EYOVX44TTUJT5BQR2J6J77FH65PCCFAJDDH';
+// Source: https://github.com/soroswap (organisation README, fetched 2026-07-23)
+// SoroswapFactory mainnet deployment.
+const SOROSWAP_MAINNET_FACTORY = 'CA4HEQTL2WPEUYKYKCDOHCDNIV4QHNJ7EL4J4NQ6VADP7SYHVRYZ7AW2';
+exports.KNOWN_ADDRESSES = {
+    mainnet: {
+        blend: [BLEND_MAINNET_POOL_FACTORY],
+        soroswap: [SOROSWAP_MAINNET_ROUTER, SOROSWAP_MAINNET_FACTORY],
+    },
+    testnet: {
+        // [VERIFY] Blend testnet pool factory address: not published in the
+        // public docs as of 2026-07-23. Excluded from the active set until an
+        // authoritative source is found.
+        blend: [],
+        // [VERIFY] SoroSwap testnet router / factory addresses: not published in
+        // the public docs as of 2026-07-23. Excluded from the active set.
+        soroswap: [],
+    },
+};
+/** Map a (contract, network) pair to its pinned protocol id. Returns null
+ *  when the address is not pinned for that network - callers MUST preserve
+ *  the fail-closed posture for unpinned contracts. */
+function addressToProtocol(contract, network) {
+    for (const protocol of ['blend', 'soroswap']) {
+        if (exports.KNOWN_ADDRESSES[network][protocol].includes(contract)) {
+            return protocol;
+        }
+    }
+    return null;
+}

package/dist-cjs/registry/protocols.d.ts

@@ -0,0 +1,38 @@
+import type { ScVal } from '../types.ts';
+export type ProtocolId = 'sep41' | 'blend' | 'soroswap';
+/** ScVal subset type vocabulary the ABI uses. Mirrors `ScVal['type']` minus
+ *  `other` (which by definition cannot be matched against an ABI arg). */
+export type AbiArgType = Exclude<ScVal['type'], 'other'>;
+export interface AbiArg {
+    name: string;
+    /** ScVal subset type the decoded arg must conform to. */
+    type: AbiArgType;
+    /** Human-readable meaning for the downstream reviewer. */
+    meaning: string;
+}
+export interface AbiEntry {
+    args: AbiArg[];
+}
+export type ProtocolAbi = Record<string, AbiEntry>;
+/** SEP-41 token interface - pinned from the SEP-41 spec (any token). */
+export declare const SEP41_ABI: ProtocolAbi;
+/** Blend pool interface (v2). Pinning the two fns the recorder surfaces.
+ *  Pool-level recognition is by INTERFACE (real pool calls hit per-pool
+ *  instances, not the factory). Arg shapes verified against the Blend v2
+ *  pool contract source (blend-capital/blend-contracts-v2 `pool/src/contract.rs`,
+ *  fetched 2026-07-23):
+ *    submit(env, from: Address, spender: Address, to: Address, requests: Vec<Request>)
+ *      -> Positions
+ *    claim(env, from: Address, reserve_token_ids: Vec<u32>, to: Address) -> i128
+ *  Other pool fns (add_reserves, withdraw, etc.) are intentionally omitted -
+ *  they are too version-sensitive to bind by interface. */
+export declare const BLEND_ABI: ProtocolAbi;
+/** SoroSwap router interface. Standard Uniswap-V2-style swap fn signatures
+ *  pinned from the SoroSwap router source. Recognised by address only (the
+ *  router is a single pinned contract); FIX 4 requires the method to also be
+ *  in this ABI for address recognition to succeed. The `path` arg is a
+ *  `vec<address>` - we record it as the outer `vec` subset and leave the
+ *  per-element shape to the downstream reviewer. */
+export declare const SOROSWAP_ABI: ProtocolAbi;
+export declare const PROTOCOL_ABIS: Record<ProtocolId, ProtocolAbi>;
+export declare function getAbi(protocol: ProtocolId): ProtocolAbi;

package/dist-cjs/registry/protocols.js

@@ -0,0 +1,153 @@
+"use strict";
+// src/registry/protocols.ts - protocol ABI definitions (no addresses).
+//
+// A protocol is identified by EITHER:
+//   - by interface (function-name signature + arg shape): a contract calling
+//     one of these well-known fns with the expected arg shape IS that
+//     protocol, regardless of address. SEP-41 is the canonical case - ANY
+//     token contract calling `transfer` with the right arg shape is a
+//     SEP-41 token. Blend pool `submit`/`claim` are similarly recognised by
+//     interface (the pool factory address doesn't cover per-pool instances).
+//   - by address: the contract is in the pinned `known-addresses` set (see
+//     known-addresses.ts). SoroSwap uses address recognition because the
+//     router is a single deployed contract; Blend uses it to recognise factory
+//     calls in addition to its interface recognition.
+//
+// Args entries pin a ScVal subset type (matching the normalised `ScVal`
+// vocabulary in src/types.ts) plus a human meaning string. The registry
+// fails closed: a method call whose decoded args do NOT match the ABI
+// signature is treated as unknown.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTOCOL_ABIS = exports.SOROSWAP_ABI = exports.BLEND_ABI = exports.SEP41_ABI = void 0;
+exports.getAbi = getAbi;
+/** SEP-41 token interface - pinned from the SEP-41 spec (any token). */
+exports.SEP41_ABI = {
+    transfer: {
+        args: [
+            {
+                name: 'from',
+                type: 'address',
+                meaning: 'source address (the `from` of the token transfer)',
+            },
+            {
+                name: 'to',
+                type: 'address',
+                meaning: 'destination address (the `to` of the token transfer)',
+            },
+            {
+                name: 'amount',
+                type: 'i128',
+                meaning: 'amount of tokens to move (i128, signed-decimal string)',
+            },
+        ],
+    },
+    mint: {
+        args: [
+            { name: 'to', type: 'address', meaning: 'recipient of the newly minted tokens' },
+            { name: 'amount', type: 'i128', meaning: 'amount to mint (i128, signed-decimal string)' },
+        ],
+    },
+    burn: {
+        args: [
+            { name: 'from', type: 'address', meaning: 'address whose balance is decremented' },
+            { name: 'amount', type: 'i128', meaning: 'amount to burn (i128, signed-decimal string)' },
+        ],
+    },
+    approve: {
+        args: [
+            { name: 'from', type: 'address', meaning: 'token holder granting the allowance' },
+            {
+                name: 'spender',
+                type: 'address',
+                meaning: 'address authorised to move tokens on behalf of `from`',
+            },
+            { name: 'amount', type: 'i128', meaning: 'allowance amount (i128, signed-decimal string)' },
+            {
+                name: 'expiration_ledger',
+                type: 'u32',
+                meaning: 'ledger sequence after which the allowance is invalid',
+            },
+        ],
+    },
+};
+/** Blend pool interface (v2). Pinning the two fns the recorder surfaces.
+ *  Pool-level recognition is by INTERFACE (real pool calls hit per-pool
+ *  instances, not the factory). Arg shapes verified against the Blend v2
+ *  pool contract source (blend-capital/blend-contracts-v2 `pool/src/contract.rs`,
+ *  fetched 2026-07-23):
+ *    submit(env, from: Address, spender: Address, to: Address, requests: Vec<Request>)
+ *      -> Positions
+ *    claim(env, from: Address, reserve_token_ids: Vec<u32>, to: Address) -> i128
+ *  Other pool fns (add_reserves, withdraw, etc.) are intentionally omitted -
+ *  they are too version-sensitive to bind by interface. */
+exports.BLEND_ABI = {
+    submit: {
+        args: [
+            { name: 'from', type: 'address', meaning: 'address supplying collateral or repaying debt' },
+            { name: 'spender', type: 'address', meaning: 'address authorising the supply / repay' },
+            { name: 'to', type: 'address', meaning: 'address receiving the resulting position shares' },
+            { name: 'requests', type: 'vec', meaning: 'vec<Request> describing the action per reserve' },
+        ],
+    },
+    claim: {
+        args: [
+            { name: 'from', type: 'address', meaning: 'address whose position is being claimed against' },
+            {
+                name: 'reserve_token_ids',
+                type: 'vec',
+                meaning: 'vec<u32> reserve token ids to claim emissions for',
+            },
+            { name: 'to', type: 'address', meaning: 'address receiving the claimed tokens' },
+        ],
+    },
+};
+/** SoroSwap router interface. Standard Uniswap-V2-style swap fn signatures
+ *  pinned from the SoroSwap router source. Recognised by address only (the
+ *  router is a single pinned contract); FIX 4 requires the method to also be
+ *  in this ABI for address recognition to succeed. The `path` arg is a
+ *  `vec<address>` - we record it as the outer `vec` subset and leave the
+ *  per-element shape to the downstream reviewer. */
+exports.SOROSWAP_ABI = {
+    swap_exact_tokens_for_tokens: {
+        args: [
+            { name: 'amount_in', type: 'i128', meaning: 'exact input amount (i128)' },
+            { name: 'amount_out_min', type: 'i128', meaning: 'minimum acceptable output (i128)' },
+            { name: 'path', type: 'vec', meaning: 'vec<address> hop path through pools' },
+            { name: 'to', type: 'address', meaning: 'recipient of the output tokens' },
+            {
+                name: 'deadline',
+                type: 'u64',
+                meaning: 'unix-seconds deadline after which the swap is refused',
+            },
+        ],
+    },
+    swap_tokens_for_exact_tokens: {
+        args: [
+            { name: 'amount_out', type: 'i128', meaning: 'exact output amount desired (i128)' },
+            { name: 'amount_in_max', type: 'i128', meaning: 'maximum input willing to spend (i128)' },
+            { name: 'path', type: 'vec', meaning: 'vec<address> hop path through pools' },
+            { name: 'to', type: 'address', meaning: 'recipient of the output tokens' },
+            {
+                name: 'deadline',
+                type: 'u64',
+                meaning: 'unix-seconds deadline after which the swap is refused',
+            },
+        ],
+    },
+    swap_exact_in_for_tokens: {
+        args: [
+            { name: 'amount_in', type: 'i128', meaning: 'exact input amount (i128)' },
+            { name: 'amount_out_min', type: 'i128', meaning: 'minimum acceptable output (i128)' },
+            { name: 'path', type: 'vec', meaning: 'vec<address> hop path through pools' },
+            { name: 'to', type: 'address', meaning: 'recipient of the output tokens' },
+        ],
+    },
+};
+exports.PROTOCOL_ABIS = {
+    sep41: exports.SEP41_ABI,
+    blend: exports.BLEND_ABI,
+    soroswap: exports.SOROSWAP_ABI,
+};
+function getAbi(protocol) {
+    return exports.PROTOCOL_ABIS[protocol];
+}

package/dist-cjs/review-card/builder.d.ts

@@ -0,0 +1,14 @@
+import type { ContextRuleDraft, PolicyRef, PredicateNode } from '../types.ts';
+import type { SimulationResult } from '../verify/envelope.ts';
+export interface ReviewCardSummary {
+    ruleName: string;
+    plainEnglish: string;
+    constraints: string[];
+    expiry: string;
+    backend: 'interpreter-v1' | 'ts-model';
+    /** Stable hash of the builder inputs - identical policy + summary = identical hash. */
+    contentHash: string;
+}
+/** Build a deterministic review-card summary from a policy + context rule +
+ *  simulation result. Pure: same inputs -> byte-identical output. */
+export declare function buildReviewCardSummary(predicate: PredicateNode | null, policyRefs: PolicyRef[], contextRule: ContextRuleDraft, simulation: SimulationResult): ReviewCardSummary;

package/dist-cjs/review-card/builder.js

@@ -0,0 +1,264 @@
+"use strict";
+// src/review-card/builder.ts - deterministic, pure review-card summary
+// builder.
+//
+// `buildReviewCardSummary` renders the per-policy text the user-facing review
+// card quotes. The whole DX win of non-engineer reviewability hinges on the
+// summary being REPRODUCIBLE + TESTABLE + NON-HALLUCINABLE, so this module is
+// pure: same inputs -> byte-identical output, no clock, no randomness, no I/O.
+//
+// The builder walks two inputs and emits ONE constraint string per leaf or
+// primitive, in a fixed deterministic order:
+//
+//   1. The OZ built-in `PolicyRef`s. Each `spending_limit` primitive becomes a
+//      `spending_limit(token, limitAmount, windowSecs)` line; other OZ
+//      primitives (threshold) are skipped - the review card does not quote
+//      them (they are signer-config concerns, not transactional bounds).
+//
+//   2. The interpreter `PredicateNode`. One string per constraint leaf,
+//      rendered by enclosing-comparison kind. Templates (Task 7b):
+//        - invocation_count_in_window <= N    -> Invocations <= N per <window> seconds
+//        - call_arg[i] in [list]              -> Recipient/arg must be one of [list]
+//        - eq(call_arg[i], literal_vec[...])  -> Path must be exactly [list]
+//        - oracle_price(asset) OP price       -> Only when oracle_price(asset) OP price
+//        - call_fn == x                       -> Function must be x
+//        - call_contract == c                 -> Contract must be c
+//        - amount <= v                        -> Amount <= v
+//
+// The content hash is a stable sha256 hex of a canonical JSON of
+// { ruleName, plainEnglish, constraints, expiry, backend } - identical
+// inputs (incl. the context-rule expiry and simulation backend) -> identical
+// hash. There is no clock; the hash never includes a timestamp.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildReviewCardSummary = buildReviewCardSummary;
+const node_crypto_1 = require("node:crypto");
+/** Build a deterministic review-card summary from a policy + context rule +
+ *  simulation result. Pure: same inputs -> byte-identical output. */
+function buildReviewCardSummary(predicate, policyRefs, contextRule, simulation) {
+    const constraints = [];
+    for (const ref of policyRefs) {
+        const line = renderOzPrimitive(ref);
+        if (line !== null)
+            constraints.push(line);
+    }
+    if (predicate !== null) {
+        walkPredicate(predicate, (node) => {
+            const line = renderConstraint(node);
+            if (line !== null)
+                constraints.push(line);
+        });
+    }
+    const ruleName = contextRule.name;
+    const plainEnglish = renderPlainEnglish(ruleName, constraints);
+    const expiry = renderExpiry(contextRule.validUntilLedger);
+    const backend = simulation.backend;
+    const contentHash = computeContentHash({
+        ruleName,
+        plainEnglish,
+        constraints,
+        expiry,
+        backend,
+    });
+    return { ruleName, plainEnglish, constraints, expiry, backend, contentHash };
+}
+/** Render the OZ built-in primitive summary line. Only `spending_limit` is
+ *  quoted by the review card (it is the only primitive that defines a
+ *  transactional bound). Other primitives (threshold) are signer-config
+ *  concerns handled by the OZ adapter's own `uncovered` machinery.
+ *  Spending_limit takes `period_ledgers` on-chain (~5s/ledger); the card
+ *  states the window in seconds so the user reads it consistently with the
+ *  interpreter templates. */
+function renderOzPrimitive(ref) {
+    if (ref.kind !== 'oz_builtin')
+        return null;
+    const primitive = ref.primitive;
+    if (primitive.primitive !== 'spending_limit')
+        return null;
+    const params = primitive.params;
+    const limit = params.spending_limit ?? '0';
+    const periodLedgers = params.period_ledgers ?? 0;
+    const windowSecs = periodLedgers * 5;
+    return `spending_limit(${limit}, ${windowSecs})`;
+}
+/** Walk every comparison / membership node of the predicate and invoke
+ *  `visit` on each. The walk is depth-first, left-to-right, so the
+ *  constraint list is stable across runs. Pure boolean nodes contribute no
+ *  constraint lines themselves; their leaf children do, via the visitor. */
+function walkPredicate(node, visit) {
+    switch (node.op) {
+        case 'and':
+        case 'or':
+            for (const child of node.children)
+                walkPredicate(child, visit);
+            return;
+        case 'not':
+            walkPredicate(node.child, visit);
+            return;
+        case 'in':
+            visit(node);
+            return;
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte':
+            visit(node);
+            return;
+    }
+}
+/** Render ONE constraint sentence for ONE interpreter predicate node. The
+ *  shape of the output is pinned by Task 7b so the test suite can assert
+ *  byte-for-byte equality. Returns `null` when the node is a structural
+ *  boolean (`and` / `or` / `not`) - those are not constraint leaves. */
+function renderConstraint(node) {
+    switch (node.op) {
+        case 'and':
+        case 'or':
+        case 'not':
+            return null;
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte':
+            return renderComparison(node);
+        case 'in':
+            return renderMembership(node);
+    }
+}
+function renderComparison(node) {
+    const left = node.left;
+    const right = node.right;
+    // eq(call_contract, literal_address) -> Contract must be <addr>
+    if (left.kind === 'call_contract' && node.op === 'eq' && right.kind === 'literal_address') {
+        return `Contract must be ${right.value}`;
+    }
+    // eq(call_fn, literal_symbol) -> Function must be <sym>
+    if (left.kind === 'call_fn' && node.op === 'eq' && right.kind === 'literal_symbol') {
+        return `Function must be ${right.value}`;
+    }
+    // eq(call_arg[i], literal_vec) -> Path must be exactly [list]
+    if (left.kind === 'call_arg' && node.op === 'eq' && right.kind === 'literal_vec') {
+        return `Path must be exactly [${right.elements.map(renderVecElement).join(', ')}]`;
+    }
+    // invocation_count_in_window <= N -> Invocations <= N per <window> seconds
+    if (left.kind === 'invocation_count_in_window' && right.kind === 'literal_u32') {
+        return `Invocations <= ${right.value} per ${left.windowSecs} seconds`;
+    }
+    // amount <= v -> Amount <= v
+    if (left.kind === 'amount' && right.kind === 'literal_i128') {
+        return `Amount <= ${right.value}`;
+    }
+    // oracle_price(asset) OP price -> Only when oracle_price(asset) OP price
+    if (left.kind === 'oracle_price' && right.kind === 'literal_i128') {
+        return `Only when oracle_price(${left.asset}) ${comparisonOpText(node.op)} ${right.value}`;
+    }
+    // Any other comparison shape is a structural fail-closed: do not surface
+    // a misleading line. Cross-check still requires every leaf produce a
+    // constraint string; the only leaves we emit lines for are the ones we
+    // recognise above, so the test fixtures cover exactly the supported
+    // shapes.
+    return null;
+}
+function renderMembership(node) {
+    // call_arg[i] in [list] -> Recipient/arg must be one of [list]
+    if (node.needle.kind === 'call_arg') {
+        const list = node.haystack.map(renderHaystackElement).join(', ');
+        return `Recipient/arg must be one of [${list}]`;
+    }
+    return null;
+}
+function renderVecElement(leaf) {
+    switch (leaf.kind) {
+        case 'literal_address':
+            return leaf.value;
+        case 'literal_i128':
+            return leaf.value;
+        case 'literal_symbol':
+            return leaf.value;
+        case 'literal_u32':
+            return String(leaf.value);
+        case 'literal_u64':
+            return leaf.value;
+        case 'literal_bytes':
+            return leaf.value;
+        case 'literal_vec':
+            return `[${leaf.elements.map(renderVecElement).join(', ')}]`;
+        case 'call_contract':
+        case 'call_fn':
+        case 'call_arg':
+        case 'amount':
+        case 'window_spent':
+        case 'now':
+        case 'valid_until':
+        case 'invocation_count_in_window':
+        case 'oracle_price':
+            return `<${leaf.kind}>`;
+    }
+}
+function renderHaystackElement(leaf) {
+    if (leaf.kind === 'literal_address')
+        return leaf.value;
+    if (leaf.kind === 'literal_i128')
+        return leaf.value;
+    if (leaf.kind === 'literal_symbol')
+        return leaf.value;
+    if (leaf.kind === 'literal_u32')
+        return String(leaf.value);
+    if (leaf.kind === 'literal_u64')
+        return leaf.value;
+    if (leaf.kind === 'literal_bytes')
+        return leaf.value;
+    if (leaf.kind === 'literal_vec') {
+        return `[${leaf.elements.map(renderHaystackElement).join(', ')}]`;
+    }
+    return `<${leaf.kind}>`;
+}
+function comparisonOpText(op) {
+    switch (op) {
+        case 'lt':
+            return '<';
+        case 'lte':
+            return '<=';
+        case 'gt':
+            return '>';
+        case 'gte':
+            return '>=';
+        case 'eq':
+            return '==';
+    }
+}
+/** Render the plain-English one-liner. Format: `<ruleName>: <constraints>`,
+ *  joined by `; ` so the user reads one sentence per constraint. */
+function renderPlainEnglish(ruleName, constraints) {
+    if (constraints.length === 0)
+        return `${ruleName}: (no constraints)`;
+    return `${ruleName}: ${constraints.join('; ')}`;
+}
+/** Render the expiry line. `null` -> "No expiry"; a ledger sequence -> the
+ *  ledger number so the user reads it in the same units the OZ context rule
+ *  applies it. */
+function renderExpiry(validUntilLedger) {
+    if (validUntilLedger === null)
+        return 'No expiry';
+    return `Valid until ledger ${validUntilLedger}`;
+}
+function computeContentHash(input) {
+    return (0, node_crypto_1.createHash)('sha256').update(canonicalStringify(input)).digest('hex');
+}
+/** Canonical JSON with recursively sorted object keys (stable across runs). */
+function canonicalStringify(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            out[key] = sortKeys(value[key]);
+        }
+        return out;
+    }
+    return value;
+}