@crediolabs/policy-synth 0.1.9 → 0.1.11

package/dist-cjs/synth/permit-context.js

@@ -0,0 +1,119 @@
+"use strict";
+// src/synth/permit-context.ts - build the EvalContext that represents the
+// recorded call being replayed.
+//
+// Extracted from the over-permissiveness harness so the same construction
+// feeds both the in-process battery and the on-chain replay
+// (scripts/verify-mutations-testnet.ts). Two callers building this
+// separately would be two chances to disagree about what "the recorded
+// call" means, which is the one thing both must share.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPermitContext = buildPermitContext;
+const deny_cases_ts_1 = require("./deny-cases.js");
+function buildPermitContext(tx, responses, predicate) {
+    const amountByToken = {};
+    const totals = new Map();
+    for (const m of tx.tokenMovements) {
+        const current = totals.get(m.token) ?? 0n;
+        totals.set(m.token, current + BigInt(m.amount));
+    }
+    for (const [token, total] of totals) {
+        amountByToken[token] = total.toString();
+    }
+    const topLevel = tx.invocations[0];
+    const scopeContract = topLevel?.contract ?? '';
+    const oraclePriceByAsset = {};
+    visitOracleLeaves(predicate, (asset, op, bound) => {
+        let price;
+        switch (op) {
+            case 'lt':
+                price = bound - 1n;
+                break;
+            case 'gt':
+                price = bound + 1n;
+                break;
+            default:
+                price = bound;
+        }
+        if (price < 0n)
+            price = 0n;
+        oraclePriceByAsset[asset] = { price: price.toString(), timestampSeconds: tx.fetchedAt };
+    });
+    const ctx = {
+        contract: scopeContract,
+        fn: topLevel?.fn ?? '',
+        args: (topLevel?.args ?? []).map(deny_cases_ts_1.cloneScVal),
+        atLedger: tx.ledgerSequence,
+        nowSeconds: tx.fetchedAt,
+        amountByToken,
+        windowSpentByToken: {},
+        invocationCountByWindow: {},
+        oraclePriceByAsset,
+    };
+    if (responses.validUntilLedger !== undefined) {
+        ctx.validUntilLedger = responses.validUntilLedger;
+    }
+    return ctx;
+}
+function visitOracleLeaves(node, visit) {
+    switch (node.op) {
+        case 'and':
+        case 'or':
+            for (const child of node.children)
+                visitOracleLeaves(child, visit);
+            return;
+        case 'not':
+            visitOracleLeaves(node.child, visit);
+            return;
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte': {
+            const leftIsOracle = node.left.kind === 'oracle_price';
+            const rightIsOracle = node.right.kind === 'oracle_price';
+            let asset;
+            let literal;
+            if (leftIsOracle) {
+                asset = node.left.kind === 'oracle_price' ? node.left.asset : undefined;
+                literal = oracleThresholdNormalised(node.right);
+            }
+            else if (rightIsOracle) {
+                asset = node.right.kind === 'oracle_price' ? node.right.asset : undefined;
+                literal = oracleThresholdNormalised(node.left);
+            }
+            if (asset !== undefined && literal !== undefined) {
+                visit(asset, node.op, literal);
+            }
+            return;
+        }
+        case 'in':
+            return;
+    }
+}
+/** Oracle prices normalise to 9 decimals; mirrors NORMALISED_DECIMALS in
+ *  oracle.rs. */
+const NORMALISED_DECIMALS = 9n;
+/** A threshold restated on the normalised basis, so a derived permit price is
+ *  comparable to it. Thresholds carry their own basis, so the conversion has
+ *  to happen here - reading the digits raw would build a context off by a
+ *  factor of 10^(decimals-9). Returns undefined for any other leaf. */
+function oracleThresholdNormalised(leaf) {
+    if (leaf.kind !== 'oracle_threshold')
+        return undefined;
+    let value;
+    try {
+        value = BigInt(leaf.value);
+    }
+    catch {
+        return undefined;
+    }
+    const decimals = BigInt(leaf.decimals);
+    if (decimals <= NORMALISED_DECIMALS) {
+        return value * 10n ** (NORMALISED_DECIMALS - decimals);
+    }
+    // Floor: a finer-grained threshold has no exact 9-dp representation. The
+    // caller only needs a price that lands on the right side of the bound, and
+    // it offsets by one from here.
+    return value / 10n ** (decimals - NORMALISED_DECIMALS);
+}

package/dist-cjs/synth/synthesize-from-mandate.d.ts

@@ -1,5 +1,20 @@
 import type { OzAdapterConfig } from '../adapters/oz/adapter.ts';
 import type { ToolResponse } from '../errors.ts';
 import type { MandateSpec } from '../mandate/types.ts';
-import type { ProposedPolicy } from '../types.ts';
-export declare function synthesizeFromMandate(spec: MandateSpec, ozConfig: OzAdapterConfig): ToolResponse<ProposedPolicy>;
+import type { PredicateNode, ProposedPolicy } from '../types.ts';
+import type { SimulationResult } from '../verify/envelope.ts';
+export declare function synthesizeFromMandate(spec: MandateSpec, ozConfig: OzAdapterConfig, 
+/** --explain opt-in. When true, the success envelope carries the
+ *  in-memory predicate tree (always null for the mandate path - the
+ *  declarative MandateSpec lowers to OZ built-ins, not to an
+ *  interpreter predicate) + a minimal honest SimulationResult. The
+ *  flag is ADDITIVE: the existing ProposedPolicy fields are never
+ *  altered. */
+opts?: {
+    explain?: true;
+}): ToolResponse<ProposedPolicy> & {
+    explain?: {
+        predicateTree: PredicateNode | null;
+        simulation: SimulationResult;
+    };
+};

package/dist-cjs/synth/synthesize-from-mandate.js

@@ -13,7 +13,14 @@ exports.synthesizeFromMandate = synthesizeFromMandate;
 const adapter_ts_1 = require("../adapters/oz/adapter.js");
 const to_ir_ts_1 = require("../mandate/to-ir.js");
 const UNCOVERED_PREFIX = 'Not covered by OZ built-in primitives: ';
-function synthesizeFromMandate(spec, ozConfig) {
+function synthesizeFromMandate(spec, ozConfig, 
+/** --explain opt-in. When true, the success envelope carries the
+ *  in-memory predicate tree (always null for the mandate path - the
+ *  declarative MandateSpec lowers to OZ built-ins, not to an
+ *  interpreter predicate) + a minimal honest SimulationResult. The
+ *  flag is ADDITIVE: the existing ProposedPolicy fields are never
+ *  altered. */
+opts) {
     const ir = (0, to_ir_ts_1.mandateToPolicyIR)(spec);
     const adapter = (0, adapter_ts_1.createOzAdapter)(ozConfig);
     const result = adapter.compile(ir);
@@ -33,5 +40,23 @@ function synthesizeFromMandate(spec, ozConfig) {
         ...result.proposed,
         warnings: result.uncovered.map((u) => `${UNCOVERED_PREFIX}${u}`),
     };
-    return { ok: true, data: proposed };
+    // Same --explain envelope pattern as the recording path. The mandate path
+    // never produces an interpreter predicate, so predicateTree is null and
+    // the simulation is a minimal honest deny (no self-verify was performed).
+    const envelope = { ok: true, data: proposed };
+    if (opts?.explain) {
+        envelope.explain = {
+            predicateTree: null,
+            simulation: {
+                permit: {
+                    tx: 'deny',
+                    reason: 'No self-verification was performed (mandate path is OZ-only)',
+                },
+                evaluatedCases: [],
+                backend: 'ts-model',
+                simulatorVersion: 'not-run',
+            },
+        };
+    }
+    return envelope;
 }

package/dist-cjs/synth/synthesize-from-recording.d.ts

@@ -1,6 +1,7 @@
 import type { OzAdapterConfig } from '../adapters/oz/adapter.ts';
 import type { ToolError, ToolResponse } from '../errors.ts';
 import { type Network, type PredicateNode, type ProposedPolicy, type RecordedTransaction } from '../types.ts';
+import type { SimulationResult } from '../verify/envelope.ts';
 import { type ComposeUserResponses } from './compose-from-recording.ts';
 /** Per-policy interpreter adapter config the caller opts into. Absent ->
  *  recording path runs in week-1 mode (OZ adapter only, warnings for the
@@ -41,8 +42,31 @@ export interface SynthesizeFromRecordingOptions {
         threshold: number;
     };
     interpreter?: InterpreterAdapterOptions;
+    /** --explain opt-in. When true, the orchestrator attaches the
+     *  in-memory `PredicateNode` + the corresponding `SimulationResult`
+     *  to the success envelope so the CLI can render a human-readable
+     *  review card. Absent or false -> the success envelope is unchanged
+     *  (byte-identical to today). The flag is ADDITIVE: the existing
+     *  ProposedPolicy fields (encodedPredicate, predicateHash, etc.) are
+     *  never altered by enabling explain. */
+    explain?: true;
 }
-export declare function synthesizeFromRecording(tx: RecordedTransaction, opts: SynthesizeFromRecordingOptions, ozConfig: OzAdapterConfig): ToolResponse<ProposedPolicy>;
+export declare function synthesizeFromRecording(tx: RecordedTransaction, opts: SynthesizeFromRecordingOptions, ozConfig: OzAdapterConfig): ToolResponse<ProposedPolicy> & {
+    /** Present iff `opts.explain === true` and the synthesis succeeded. The
+     *  `predicateTree` is the exact in-memory `PredicateNode` (canonical
+     *  JSON shape) that was encoded into `proposed.policyDocuments[*].encodedPredicate`
+     *  - reading the predicate tree from the policy document is therefore
+     *  unnecessary; the orchestrator carries it through. The `simulation`
+     *  is the verdict produced by the same self-verify pipeline that already
+     *  runs in the recording path (runHarness + evaluate), so the value is
+     *  REAL not synthetic. Absent when the synthesis did not engage the
+     *  interpreter (no interpreter opts supplied) - in that case the CLI
+     *  builds a minimal honest SimulationResult downstream. */
+    explain?: {
+        predicateTree: PredicateNode | null;
+        simulation: SimulationResult;
+    };
+};
 /** ToolError-shaped error helper used by the body to surface a structured
  *  failure that the envelope converts to `{ok:false, error}`. */
 declare function throwToolError(code: ToolError['code'], message: string): never;

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

@@ -199,6 +199,14 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
         ...(opts.userResponses !== undefined ? { userResponses: opts.userResponses } : {}),
     };
     const composed = (0, compose_from_recording_ts_1.composeFromRecording)(facts, scope.contract, topLevel, composeOpts);
+    // --explain hook: capture the in-memory predicate tree + the real
+    // self-verify verdict so the CLI can render a faithful review card.
+    // The verdict below is built from the SAME runHarness + evaluate that
+    // already gates the synthesis (it is not a parallel simulation); the
+    // intermediate inputs (harnessCases, evalResult) are otherwise discarded
+    // after the gate, so the explain hook reuses them - no extra work.
+    let explain = null;
+    let explainSim = null;
     // 5. OZ compile (always runs).
     const ozAdapter = (0, adapter_ts_2.createOzAdapter)(ozConfig);
     const compileRes = ozAdapter.compile(composed.ir);
@@ -376,6 +384,36 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
                 },
             };
         }
+        // --explain capture: the interpreter path already produced the real
+        // self-verify verdict (runHarness passed, evalResult.permit is true).
+        // Build the SimulationResult from those outputs so the CLI card
+        // quotes the SAME verdict that gated the synthesis. We re-evaluate
+        // each deny case to surface its concrete reason; the harness only
+        // records whether the got-matches-expected boundary held.
+        if (opts.explain) {
+            explain = finalPredicate;
+            const evaluatedCases = [
+                {
+                    dimension: 'permit',
+                    outcome: evalResult.permit ? 'permit' : 'deny',
+                    reason: 'matches recorded call',
+                },
+            ];
+            for (const deny of harnessCases.denies) {
+                const r = (0, evaluate_ts_1.evaluate)(finalPredicate, deny.ctx);
+                evaluatedCases.push({
+                    dimension: deny.dimension,
+                    outcome: r.permit ? 'permit' : 'deny',
+                    reason: r.permit ? 'no matching deny' : r.reason,
+                });
+            }
+            explainSim = {
+                permit: { tx: 'permit' },
+                evaluatedCases,
+                backend: 'ts-model',
+                simulatorVersion: 'ts-model-1.0.0',
+            };
+        }
         // 6c. Re-encode the (possibly minimised) PredicateNode and stamp the
         //     canonical bytes back onto the PolicyDocument + PolicyRef. The
         //     `encodePredicate` helper throws ToolError-shaped errors on cap
@@ -473,7 +511,34 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
         ],
         ambiguities: mergeAmbiguities(composed.ambiguities, scope.ambiguities),
     };
-    return { ok: true, data: proposed };
+    // --explain success envelope. The interpreter path populated
+    // `explain` + `explainSim` from the real self-verify verdict above;
+    // the OZ-only path did not (no predicate tree exists). When opts.explain
+    // is set and the OZ-only path ran, construct the minimal honest
+    // SimulationResult: the verdict is NOT a passing simulation - the
+    // interpreter was never engaged, so permit is deny with a truthful
+    // reason and evaluatedCases is empty.
+    const envelope = { ok: true, data: proposed };
+    if (opts.explain) {
+        if (explainSim) {
+            envelope.explain = { predicateTree: explain, simulation: explainSim };
+        }
+        else {
+            envelope.explain = {
+                predicateTree: null,
+                simulation: {
+                    permit: {
+                        tx: 'deny',
+                        reason: 'No self-verification was performed (interpreter adapter was not engaged)',
+                    },
+                    evaluatedCases: [],
+                    backend: 'ts-model',
+                    simulatorVersion: 'not-run',
+                },
+            };
+        }
+    }
+    return envelope;
 }
 /** OZ-side `uncovered` warning patterns that the interpreter adapter
  *  actually lowers when wired in. When the interpreter adapter succeeds, we
@@ -747,13 +812,25 @@ function visitOracleLeaves(node, visit) {
             return;
     }
 }
+/** An oracle threshold restated on the normalised 9-dp basis prices use.
+ *  Thresholds carry their own basis, so reading the digits raw would build a
+ *  permit context off by 10^(decimals-9) and the intended call would not
+ *  satisfy its own bound. Mirrors NORMALISED_DECIMALS in oracle.rs. */
 function oracleLiteralFromLeaf(leaf) {
-    if (leaf.kind !== 'literal_i128')
+    if (leaf.kind !== 'oracle_threshold')
         return undefined;
+    let value;
     try {
-        return BigInt(leaf.value);
+        value = BigInt(leaf.value);
     }
     catch {
         return undefined;
     }
+    const normalised = 9n;
+    const decimals = BigInt(leaf.decimals);
+    if (decimals <= normalised)
+        return value * 10n ** (normalised - decimals);
+    // Floor: a finer-grained threshold has no exact 9-dp representation; the
+    // caller offsets by one from here to land on the right side of the bound.
+    return value / 10n ** (decimals - normalised);
 }

package/dist-cjs/types.d.ts

@@ -190,6 +190,11 @@ export type PredicateLeaf = {
     index: number;
     element: number;
     field: string;
+} | {
+    kind: 'call_arg_scaled';
+    index: number;
+    num: string;
+    den: string;
 } | {
     kind: 'amount';
     token: string;
@@ -207,6 +212,10 @@ export type PredicateLeaf = {
 } | {
     kind: 'oracle_price';
     asset: string;
+} | {
+    kind: 'oracle_threshold';
+    value: string;
+    decimals: number;
 } | {
     kind: 'literal_address';
     value: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-synth",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "license": "MIT",
   "description": "Off-chain TypeScript synthesis core for the OZ Accounts Policy Builder. Records Soroban transactions, synthesises the minimal policy that permits exactly that flow, verifies it, and returns an unsigned install transaction.",
   "type": "module",
@@ -67,11 +67,14 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@stellar/stellar-sdk": "14.4.0",
     "zod": "3.25.76"
   },
+  "peerDependencies": {
+    "@stellar/stellar-sdk": "^14.4.0"
+  },
   "devDependencies": {
     "@biomejs/biome": "2.5.5",
+    "@stellar/stellar-sdk": "14.4.0",
     "@types/node": "^26.1.1",
     "typescript": "5.9.3"
   }

package/src/adapters/interpreter/adapter.ts

@@ -90,7 +90,10 @@ export interface InterpreterAdapterConfig {
 const CAPABILITIES: CustodyCapabilities = {
   supportsSpendWindow: true,
   supportsThreshold: false, // thresholds are the OZ adapter's job
-  supportsTimeExpiry: true, // via valid_until ledger expiry
+  // False for the predicate-leaf path: the interpreter refuses a `valid_until`
+  // leaf at install. Expiry is still available, but as the context rule's
+  // validUntilLedger, which the smart account enforces - not as a predicate.
+  supportsTimeExpiry: false,
   supportsOraclePrice: true,
   supportsInvocationCount: true,
   supportsGeneralPredicate: true,
@@ -296,24 +299,64 @@ function lowerRule(rule: IRPolicyRule, config: InterpreterAdapterConfig): Lowere
 function unsupportedConstruct(cond: IRCondition): string | null {
   switch (cond.op) {
     case 'in':
-      return cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
-        ? `EVM \`${cond.selector.kind}\` selector on allowlist (predicate DSL)`
-        : null
+      // The oracle position rule is a hard error and must be raised before a
+      // construct can be written off as uncovered - otherwise a subtree that
+      // is BOTH misplaced-oracle and unsourceable would be silently dropped
+      // instead of rejected.
+      assertNoOracleDescendants(cond)
+      return (
+        unsourceableSelector(cond.selector) ??
+        (cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
+          ? `EVM \`${cond.selector.kind}\` selector on allowlist (predicate DSL)`
+          : null)
+      )
     case 'eq_seq':
-      return cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
-        ? `EVM \`${cond.selector.kind}\` selector on ordered-sequence equality (predicate DSL)`
-        : null
+      return (
+        unsourceableSelector(cond.selector) ??
+        (cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
+          ? `EVM \`${cond.selector.kind}\` selector on ordered-sequence equality (predicate DSL)`
+          : null)
+      )
     case 'compare': {
       const s = cond.compare.selector
       if (s.kind === 'calldata') return 'EVM calldata comparison (predicate DSL)'
       if (s.kind === 'value') return 'tx.value comparison (predicate DSL)'
-      return null
+      // The on-chain interpreter sees ONE authorized call - there is no
+      // `Context.sub_invocations` in v1 - so it cannot observe the
+      // transaction's token movements. `amount` has no value to read, and
+      // `window_spent` accumulates BY that amount, so its counter would never
+      // move. Deriving either from the call payload would quietly swap "value
+      // actually moved" for "value the caller declared" - a weaker guarantee
+      // than the review card would be claiming.
+      //
+      // Rolling spend caps belong to the OZ `spending_limit` primitive, which
+      // is already audited and which the OZ adapter emits. A per-call cap is
+      // expressible here as `arg_field`; bounding it with `invocation_count`
+      // gives an enforceable ceiling per window.
+      return unsourceableSelector(s)
     }
+    // Recurse: a nested `and`/`or`/`not` must not smuggle a selector past the
+    // pre-scan, which only sees top-level constraints.
     case 'and':
+      return cond.children.map(unsupportedConstruct).find((u) => u !== null) ?? null
     case 'or':
+      assertNoOracleDescendants(cond)
+      return cond.children.map(unsupportedConstruct).find((u) => u !== null) ?? null
     case 'not':
-      return null
+      assertNoOracleDescendants(cond)
+      return unsupportedConstruct(cond.child)
+  }
+}
+
+/** Selectors whose value the on-chain interpreter has no way to obtain. */
+function unsourceableSelector(s: IRSelector): string | null {
+  if (s.kind === 'amount') {
+    return `per-call amount comparison on ${s.token} - the interpreter cannot observe token movements; express a per-call cap with arg_field, or a rolling cap with the OZ spending_limit primitive`
+  }
+  if (s.kind === 'window_spent') {
+    return `rolling spend cap on ${s.token} over ${s.windowSeconds}s - not enforceable by the interpreter; use the OZ spending_limit primitive, or bound per-call value with arg_field plus invocation_count`
   }
+  return null
 }
 
 /** Lower one IR condition to a PredicateNode. Enforces the oracle position
@@ -393,10 +436,15 @@ function lowerSelector(s: IRSelector): PredicateLeaf {
       return { kind: 'call_arg_len', index: s.argIndex }
     case 'arg_field':
       return { kind: 'call_arg_field', index: s.argIndex, element: s.element, field: s.field }
+    // `amount` / `window_spent` are filtered out by `unsupportedConstruct`
+    // before lowering - the interpreter cannot source either on chain. Reaching
+    // here means the pre-scan was bypassed, so fail loudly rather than emit a
+    // leaf the contract will refuse.
     case 'amount':
-      return { kind: 'amount', token: s.token }
     case 'window_spent':
-      return { kind: 'window_spent', token: s.token, windowSeconds: s.windowSeconds }
+      throw new Error(
+        `interpreter adapter cannot lower \`${s.kind}\`: it should have been reported as uncovered`
+      )
     case 'invocation_count':
       return { kind: 'invocation_count_in_window', windowSecs: s.windowSeconds }
     case 'now':
@@ -427,6 +475,19 @@ function lowerSelector(s: IRSelector): PredicateLeaf {
  *    - invocation_count -> u32 (counts are small non-negative integers)
  *    - now / valid_until -> u64 (unix timestamps in seconds) */
 function literalFromIRCompare(c: IRCompare): PredicateLeaf {
+  // An oracle comparand is not a bare literal: the interpreter refuses one,
+  // because assuming it shares the normalised 9-dp basis is what made a raw
+  // 14-dp threshold permit everything it was written to deny.
+  if (c.selector.kind === 'oracle_price') {
+    if (c.valueDecimals === undefined) {
+      throw toolError(
+        'ORACLE_THRESHOLD_BASIS_REQUIRED',
+        'An oracle price bound must declare the decimal basis of its threshold ' +
+          '(oracle prices normalise to 9 decimals).'
+      )
+    }
+    return { kind: 'oracle_threshold', value: c.value, decimals: c.valueDecimals }
+  }
   const scalarType: IRScalarType = selectorScalarType(c.selector)
   return literalFromScalar(c.value, scalarType)
 }

package/src/contracts/policy-template/OZ_POLICY_TRAIT.md

@@ -113,15 +113,40 @@ pub fn add_context_rule(
 - `add_context_rule` is called by the **smart account itself** (the contract owning the context rules).
 - Auth is enforced by Soroban's `require_auth` on the calling context — the smart account's master signer (or a delegated signer with sufficient weight) must authorize the call.
 - The interpreter's `install` function is called **within the same transaction** as `add_context_rule` and receives the same `smart_account` address.
-- **The interpreter does NOT need to read the smart account's master set** — the master signer authorizes `add_context_rule` directly; the interpreter receives the already-authorized `ContextRule` and `smart_account` address.
+- The interpreter **cannot** read the smart account's master set; it receives only the already-authorized `ContextRule` and `smart_account` address.
+
+> **CORRECTED 2026-07-27 - do not read the line above as a safety guarantee.**
+> An earlier version of this file said the interpreter "does NOT need to" read the
+> master set because the master authorizes `add_context_rule` directly. The master
+> *can* authorize it. It is **not** true that only the master can.
+>
+> Verified at this pinned commit: `storage.rs` states `add_policy` /
+> `add_context_rule` modify storage "without requiring authorization. Ensure proper
+> access control is implemented at the contract level"; `mod.rs:439` and `mod.rs:246`
+> implement that as `e.current_contract_address().require_auth()`, a self-auth
+> resolved through the account's own context rules; and `mod.rs:80` states that
+> "a `Default` rule matches any context".
+>
+> Therefore any signer on a `Default` rule can attach or replace a policy - including
+> a delegated agent, on its own rule. See `plans/security-finding-install-authorization.md`.
 
 ### Safe mechanism for master-only install
 
-The committed safe mechanism is **two-step install** (not out-of-band master const):
+Two-step install is the install **path**. It is NOT relied on as the authorization
+**guarantee**, because the auth it inherits is whatever the account's own rules permit:
+
 1. Owner calls `add_context_rule` with the interpreter address + initial rule.
-2. Interpreter's `install` is called within the same auth context — the `Context` passed to `Policy::enforce` confirms the call is authorized by the smart account's current signer set.
+2. Interpreter's `install` is called within the same auth context.
 3. Re-install is structurally possible via `install_nonce` (stored nonce + 1 check).
 
+The guarantee comes from the interpreter pinning its own authorized installer set at
+first install for `(smart_account, rule_id)`, and denying later installs and
+uninstalls from outside that set with `MASTER_AUTH_REQUIRED`. Rotation goes through
+`rotate_master_signer_set(new_set)`, gated by the old set.
+
+`install_nonce` alone does not close this: it blocks replay of an *old* document, but
+a *fresh* looser document with `nonce + 1` would otherwise be accepted.
+
 ---
 
 ## Framework Limits (OZ Hard Limits)

package/src/errors.ts

@@ -39,9 +39,20 @@ export type ErrorCode =
   | 'AMOUNT_OVERFLOW'
   | 'RULE_SIGNERS_CHANGED'
   | 'SCOPE_SELF_CALL'
+  | 'ARG_MISMATCH'
+  | 'CONTRACT_SCOPE'
+  | 'UNSUPPORTED_NODE'
+  | 'STATEFUL_BOUND'
+  | 'NOT_IN_ALLOWLIST'
+  | 'FREQUENCY'
+  // A `call_arg >= call_arg_scaled(..)` slippage floor was not met. Distinct
+  // from the generic ARG_MISMATCH/STATEFUL_BOUND so a violated swap floor
+  // reads as itself on the review card.
+  | 'SLIPPAGE_FLOOR'
   // --- oracle denies (fatal evaluator errors) ---
   | 'ORACLE_STALE'
   | 'ORACLE_MISSING'
+  | 'ORACLE_NO_CONFIRMATION'
   | 'ORACLE_DEVIATION_EXCEEDED'
   | 'ORACLE_MALFORMED_HISTORY'
   | 'ORACLE_FINGERPRINT_DRIFT'
@@ -49,6 +60,8 @@ export type ErrorCode =
   | 'ORACLE_LEAF_INVALID_POSITION'
   | 'ORACLE_PARAMS_OUT_OF_RANGE'
   | 'ORACLE_DECIMALS_MISMATCH'
+  | 'ORACLE_THRESHOLD_DECIMALS_OUT_OF_RANGE'
+  | 'ORACLE_THRESHOLD_BASIS_REQUIRED'
   // --- escape-hatch compile gate ---
   | 'COMPILE_OK'
   | 'COMPILE_GATE_FAILED'