@crediolabs/policy-synth 0.1.17 → 0.2.0

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

@@ -20,21 +20,18 @@ export interface InterpreterAdapterOptions {
         maxStalenessSeconds?: number;
         maxDeviationBps?: number;
     };
-    /** @internal Test-only seam. When set, the orchestrator uses this
-     *  PredicateNode as the starting point for self-verify + minimise instead
-     *  of calling the interpreter adapter's compile(). Production callers MUST
-     *  NOT set this; the field exists so the self-verify pipeline can be
-     *  exercised on hand-crafted predicates (redundant conjuncts for
-     *  minimise, deliberately over-broad leaves for DENY_CASE_FAILURE). The
-     *  `smartAccountAddress` + `installNonce` + `oracleParams` are still
-     *  carried through so the emitted PolicyRef + PolicyDocument match the
-     *  recorded call shape. */
-    __testPredicateNode?: PredicateNode;
 }
-/** Top-level orchestrator inputs. `userResponses` carries the LLM-collected
- *  answers to the ambiguity prompts (windowSeconds, validUntilLedger,
- *  limitAmount, invocationLimit, oraclePriceBound, swapRecipientAllowlist).
- *  `interpreter` opts the recording path into the interpreter adapter. */
+/** PRIVATE test-only extension of `InterpreterAdapterOptions` for the
+ *  `__testPredicateNode` seam. Exported under a `__` prefix so production
+ *  callers can grep for it and see it is a test hook. The seam is read in
+ *  `synthesizeFromRecordingInner` only when `process.env.NODE_ENV === 'test'`
+ *  - a hard RUNTIME guard throws otherwise so a misconfigured production
+ *  caller cannot bypass the recording -> interpreter adapter compile path. */
+export type __TestInterpreterAdapterOptions = InterpreterAdapterOptions & {
+    /** @internal Test-only seam. Throws at runtime when NODE_ENV !== 'test'. */
+    __testPredicateNode?: PredicateNode;
+};
+/** Top-level orchestrator inputs. */
 export interface SynthesizeFromRecordingOptions {
     network: Network;
     userResponses?: ComposeUserResponses;
@@ -42,13 +39,8 @@ 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 opt-in. The flag is ADDITIVE: existing ProposedPolicy fields are
+     *  never altered by enabling explain. Absent -> success envelope is byte-identical. */
     explain?: true;
 }
 export declare function synthesizeFromRecording(tx: RecordedTransaction, opts: SynthesizeFromRecordingOptions, ozConfig: OzAdapterConfig): ToolResponse<ProposedPolicy> & {
@@ -71,3 +63,21 @@ export declare function synthesizeFromRecording(tx: RecordedTransaction, opts: S
  *  failure that the envelope converts to `{ok:false, error}`. */
 declare function throwToolError(code: ToolError['code'], message: string): never;
 export { throwToolError };
+/** Diagnostic reported by `visitOracleLeaves` when an oracle comparison
+ *  cannot be normalised to oracle-on-left. Currently only "oracle-on-right
+ *  with a non-literal LHS" - the other branches already produce a parseable
+ *  threshold and are returned to the caller. */
+export interface OracleNormalisationWarning {
+    /** The dimension name (currently always "oracle_normalisation_dropped"). */
+    dimension: 'oracle_normalisation_dropped';
+    /** The operator as written. */
+    op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte';
+    /** The asset the oracle leaf is bound to. */
+    asset: string;
+    /** The non-literal RHS (oracle-on-left) or LHS (oracle-on-right) leaf
+     *  whose shape stopped the normalisation. Surfaced for diagnostics;
+     *  intentionally a partial view - the full leaf is the caller's job. */
+    otherKind: string;
+    /** Human-readable message (matches the warn-on-drop text). */
+    message: string;
+}

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

@@ -1,35 +1,10 @@
 // src/synth/synthesize-from-recording.ts - recording-path orchestrator.
 //
-// `synthesizeFromRecording` is the second Synthesizer front-end: it INFERS a
-// bounded policy from a `RecordedTransaction` via the same `PolicyIR` + adapter
-// pair used by the deterministic Mandate path. The flow:
-//
-//   1. parseConfidence gate - refuse when `overall < threshold` (default 1.0;
-//      the caller may relax via `confidenceOverride.threshold`).
-//   2. `lower(tx)` -> IntentFacts.
-//   3. `decideScope(facts)` -> scope | SCOPE_UNRESOLVED ToolError.
-//   4. `composeFromRecording(facts, scope, opts)` -> { ir (OZ-shape),
-//      interpreterIr (predicate-shape), ambiguities, warnings }.
-//   5. `ozAdapter.compile(ir)` -> CompileResult.
-//   6. If `interpreterIr.rules[0].constraints.length > 0` AND the caller
-//      opted in to the interpreter adapter:
-//        a. Run `interpreterAdapter.compile(interpreterIr)`.
-//        b. Throw -> SYNTHESIS_ERROR carrying the gate code
-//           (SCOPE_SELF_CALL, ORACLE_LEAF_INVALID_POSITION,
-//           ORACLE_PARAMS_OUT_OF_RANGE). Never install an OZ-only partial
-//           policy - a warning can be ignored and yields an over-broad rule.
-//        c. `covered === false` -> SYNTHESIS_ERROR carrying the uncovered
-//           descriptor (the user asked for the interpreter to enforce these
-//           constraints; refusing them silently is the audit failure mode).
-//        d. `covered === true` -> merge its PolicyDocument + PolicyRef into
-//           the OZ-shaped ProposedPolicy; the merged `contextRule.policies`
-//           is `[interpreterRef?, ...oz_builtinRefs]` and must satisfy
-//           `OZ_LIMITS.maxPoliciesPerRule` (= 5).
-//   7. Assemble ProposedPolicy carrying parseConfidence (from tx), warnings
-//      (the OZ `uncovered` markers, prefixed), and ambiguities.
-//
-// Determinism: same (tx, opts, ozConfig) -> byte-identical ProposedPolicy.
-// No randomness, no clock, no globals.
+// `synthesizeFromRecording` INFERS a bounded policy from a `RecordedTransaction`
+// via the same `PolicyIR` + adapter pair used by the deterministic Mandate path.
+// Flow: validate -> parseConfidence gate -> lower -> decideScope -> composeFromRecording
+// -> OZ compile -> (opt-in) interpreter compile + self-verify + minimise -> merge.
+// Same (tx, opts, ozConfig) -> byte-identical ProposedPolicy (no randomness, clock, globals).
 import { createInterpreterAdapter, lowerRuleToPredicate, PLACEHOLDER_INTERPRETER_ADDRESS, } from "../adapters/interpreter/adapter.js";
 import { createOzAdapter } from "../adapters/oz/adapter.js";
 import { encodePredicate } from "../predicate/encode.js";
@@ -43,13 +18,11 @@ import { minimize } from "./minimize.js";
 import { decideScope } from "./scope.js";
 const UNCOVERED_PREFIX = 'Not covered by OZ built-in primitives: ';
 export function synthesizeFromRecording(tx, opts, ozConfig) {
-    // Item 3: ToolError try/catch envelope. Any ToolError-shaped throw (object
-    // with a string `.code`) inside the body is converted to a structured
-    // `{ok:false, error}`; anything else is rethrown so genuine bugs crash
-    // instead of being silently swallowed. The envelope must wrap the entire
-    // synthesis body so a thrown `encodePredicate` cap error (PREDICATE_TOO_DEEP,
-    // TOO_MANY_LEAVES, etc.) or a depth-cap throw from `cloneScVal` surfaces as
-    // a structured ToolError rather than a thrown RangeError.
+    // Convert any ToolError-shaped throw (object with a string `.code`) to a
+    // structured `{ok:false, error}`; anything else is rethrown so genuine bugs
+    // crash instead of being silently swallowed. Wraps the entire body so
+    // cap errors (PREDICATE_TOO_DEEP, TOO_MANY_LEAVES) and cloneScVal depth
+    // throws surface as structured ToolErrors rather than RangeErrors.
     try {
         return synthesizeFromRecordingInner(tx, opts, ozConfig);
     }
@@ -68,10 +41,9 @@ export function synthesizeFromRecording(tx, opts, ozConfig) {
         throw e;
     }
 }
-/** True when `e` is the ToolError-shaped throw the internal pipeline uses to
- *  signal a structured failure (e.g. `encodePredicate` cap errors, `cloneScVal`
- *  depth-cap throws). Detected by a string `code` field — the only contract
- *  the body's internal helpers agree on. */
+/** True when `e` is a ToolError-shaped throw (object with a string `code`).
+ *  Detected by string `code` field — the only contract the body's internal
+ *  helpers agree on. */
 function isToolErrorShape(e) {
     if (e === null || typeof e !== 'object')
         return false;
@@ -88,17 +60,14 @@ function throwToolError(code, message) {
     err.retryable = false;
     throw err;
 }
-/** Synthesize a ProposedPolicy from a recorded transaction. */
 function synthesizeFromRecordingInner(tx, opts, ozConfig) {
     // 0. validate inputs (fail closed - never synthesize from garbage).
     const invalid = validateOptions(opts);
     if (invalid)
         return { ok: false, error: invalid };
-    // 0a. per-movement amount validation (item 2). Synthesizing from a recording
-    //     whose `tokenMovements[].amount` does not match the canonical positive
-    //     decimal integer format is a malformed-input failure, not a runtime
-    //     one - reject it here so the downstream `BigInt(m.amount)` in
-    //     `buildPermitContext` cannot throw a SyntaxError past the envelope.
+    // 0a. per-movement amount validation. Reject malformed recordings here so
+    //     the downstream `BigInt(m.amount)` in `buildPermitContext` cannot throw
+    //     a SyntaxError past the envelope.
     for (const [i, m] of tx.tokenMovements.entries()) {
         if (!/^[0-9]+$/.test(m.amount)) {
             return {
@@ -126,15 +95,9 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
             },
         };
     }
-    // 1a. Zero-invocation refusal (item 1). A recording with zero contract
-    //     invocations cleared the parseConfidence gate legitimately (the
-    //     `denom === 0` short-circuit pins overall to 1.0 for that case), but a
-    //     policy must scope to an authorized contract call. Refuse before any
-    //     lower/scope work so the failure is specific and actionable. The
-    //     recorder's silence is also made visible via `parseConfidence.noInvocations`
-    //     so consumers can pattern-match without inferring from `invocations: []`
-    //     next to `overall: 1.0`. The message does NOT ask for an ABI - the
-    //     failure mode is the recording shape, not decoding coverage.
+    // 1a. Zero-invocation refusal. A recording with zero invocations clears
+    //     parseConfidence legitimately (denom === 0 short-circuits overall to 1.0),
+    //     but a policy must scope to an authorized contract call. Refuse early.
     const hasNoInvocations = tx.parseConfidence.noInvocations === true || tx.invocations.length === 0;
     if (hasNoInvocations) {
         return {
@@ -164,9 +127,7 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
             },
         };
     }
-    // 2. lower.
     const facts = lower(tx);
-    // 3. decideScope.
     const scopeRes = decideScope(facts, {
         network: opts.network,
         ...(opts.userResponses?.validUntilLedger !== undefined
@@ -196,11 +157,8 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
     };
     const composed = 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.
+    // self-verify verdict (built from the SAME runHarness + evaluate that gated
+    // the synthesis, not a parallel simulation).
     let explain = null;
     let explainSim = null;
     // 5. OZ compile (always runs).
@@ -223,6 +181,10 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
     const interpreterOpts = opts.interpreter;
     let interpreterPolicyDocument = null;
     let interpreterPolicyRef = null;
+    // Cross-layer L3: declared OUTSIDE the `if (interpreterOpts)` block so the
+    // warnings folded into `proposed.warnings[]` (which lives after that block)
+    // can read it. The block assigns it; the default is empty.
+    let permitCtxWarnings = [];
     if (interpreterOpts) {
         const interpreterConfig = {
             network: opts.network,
@@ -231,8 +193,17 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
             ...(interpreterOpts.oracleParams ? { oracleParams: interpreterOpts.oracleParams } : {}),
         };
         let startingPredicate = null;
+        // `__testPredicateNode` is a test-only seam. It is NOT in the public
+        // `InterpreterAdapterOptions` type, so a production caller cannot set it
+        // without bypassing the type system. We read it via a private cast and
+        // enforce a runtime NODE_ENV check so a misconfigured production caller
+        // that smuggles it in (any-cast, JSON-driven opt, etc.) is caught here
+        // rather than silently overriding the compiled predicate.
         const testSeam = interpreterOpts.__testPredicateNode;
         if (testSeam !== undefined) {
+            if (process.env.NODE_ENV !== 'test') {
+                throw new Error('synthesizeFromRecording: __testPredicateNode is a test-only seam and is refused outside NODE_ENV=test');
+            }
             startingPredicate = testSeam;
         }
         else {
@@ -349,7 +320,12 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
                 },
             };
         }
-        const permitCtx = buildPermitContext(tx, scope, topLevel, opts.userResponses, startingPredicate);
+        // Cross-layer L3: warnings collected from `buildPermitContext` (currently
+        // only the oracle-on-right normaliser) and folded into the proposed
+        // policy's `warnings[]` so the caller sees them on the success envelope.
+        const permitCtxResult = buildPermitContext(tx, scope, topLevel, opts.userResponses, startingPredicate);
+        const permitCtx = permitCtxResult.ctx;
+        permitCtxWarnings = permitCtxResult.warnings;
         const finalPredicate = startingPredicate.op === 'and'
             ? minimize(startingPredicate, permitCtx, ORIGINAL_DIMENSIONS)
             : startingPredicate;
@@ -380,12 +356,9 @@ 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.
+        // --explain capture: quote the SAME verdict that gated the synthesis.
+        // 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 = [
@@ -411,10 +384,9 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
             };
         }
         // 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
-        //     breaches (PREDICATE_TOO_DEEP, TOO_MANY_LEAVES, etc.) - the outer
-        //     envelope converts them to a structured `{ok:false, error}`.
+        //     canonical bytes back onto the PolicyDocument + PolicyRef. Cap breaches
+        //     (PREDICATE_TOO_DEEP, TOO_MANY_LEAVES) throw ToolError-shaped errors;
+        //     the outer envelope converts them to structured `{ok:false, error}`.
         const { encodedPredicate, predicateHash } = encodePredicate(finalPredicate);
         if (testSeam !== undefined) {
             interpreterPolicyDocument = {
@@ -487,9 +459,7 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
     // When nothing installable was synthesised (no interpreter doc AND no OZ
     // policy refs), an empty `policies` array reads as "no restrictions" rather
     // than "I synthesised nothing". Surface that explicitly so the empty result
-    // is never mistaken for a permissive policy - the context rule still exists,
-    // but it constrains nothing. (Kept as `{ok:true}` so the documented
-    // Path-A/Path-B demo behaviour is preserved - see F3.)
+    // is never mistaken for a permissive policy.
     const zeroPolicyWarning = mergedRefs.length === 0 && !interpreterPolicyDocument
         ? [
             'No policy constraints were synthesised: the call to this contract is UNCONSTRAINED by this policy. Enable the interpreter (supply a smart account) to enforce the surfaced constraints.',
@@ -504,16 +474,14 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
             ...zeroPolicyWarning,
             ...ozUncovered.map((u) => `${UNCOVERED_PREFIX}${u}`),
             ...composed.warnings.map((w) => `${UNCOVERED_PREFIX}${w}`),
+            ...permitCtxWarnings,
         ],
         ambiguities: mergeAmbiguities(composed.ambiguities, scope.ambiguities),
     };
-    // --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.
+    // --explain success envelope. 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) {
@@ -536,24 +504,21 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
     }
     return envelope;
 }
-// Re-export the throwToolError helper for callers that need to surface a
-// ToolError-shaped throw inside the body (e.g. tests).
 export { throwToolError };
-/** OZ-side `uncovered` warning patterns that the interpreter adapter
- *  actually lowers when wired in. When the interpreter adapter succeeds, we
- *  drop matching entries from the OZ uncovered list so the user-facing
- *  warnings reflect what is still UN-enforced rather than what OZ alone
- *  could not do. Match the exact descriptor strings the OZ adapter emits
- *  (see `src/adapters/oz/adapter.ts#describeCondition` /
- *  `describeSelector`). */
+/** OZ-side `uncovered` warning patterns the interpreter adapter actually lowers
+ *  when wired in. When the interpreter adapter succeeds, matching entries are
+ *  dropped from the OZ uncovered list so user-facing warnings reflect what is
+ *  still UN-enforced rather than what OZ alone could not do. Matches the
+ *  exact descriptor strings the OZ adapter emits (see `src/adapters/oz/adapter.ts`
+ *  `describeCondition` / `describeSelector`). */
 const INTERPRETER_COVERED_OZ_PATTERN = /^per-method scoping to|^value allowlist on arg|^exact ordered sequence on arg|^oracle price condition on|^invocation-count window|^spending_limit on token .+ needs a CallContract context scoped to that token/;
 /** Reject non-sane inputs before any policy is synthesized. windowSeconds /
  *  validUntilLedger / invocationLimit must be positive integers; limitAmount a
- *  positive i128 decimal string; network mainnet|testnet. When the caller
- *  opts into the interpreter adapter, `smartAccountAddress` must be a C...
- *  contract address (the on-chain policy-bound account, NOT the G... source
- *  account from the recording), `installNonce` must be a positive integer
- *  (default 1), and `oracleParams` must tighten-only vs the wasm defaults. */
+ *  positive i128 decimal string; network mainnet|testnet. When the interpreter
+ *  adapter is opted in, `smartAccountAddress` must be a C... contract address
+ *  (the on-chain policy-bound account, NOT the G... source account),
+ *  `installNonce` must fit u32 (default 1), and `oracleParams` must
+ *  tighten-only vs the wasm defaults. */
 function validateOptions(opts) {
     if (opts.network !== 'mainnet' && opts.network !== 'testnet') {
         return synthesisError(`network must be 'mainnet' or 'testnet', got: ${String(opts.network)}`);
@@ -585,13 +550,9 @@ function validateOptions(opts) {
         if (typeof sa !== 'string' || sa.length === 0) {
             return synthesisError(`interpreter.smartAccountAddress must be a non-empty string, got: ${String(sa)}`);
         }
-        // Blocklist placeholder / stub prefixes (item 5). Runs BEFORE the
-        // C.../56-char shape check so a fixture/LLM-seam marker is reported
-        // with the specific placeholder error (not a generic "must be a
-        // C... contract" message). A real install routes a C... contract
-        // address derivable from the on-chain account; any
-        // 'VERIFY-*' / 'PLACEHOLDER-*' / 'TODO-*' prefix is an LLM seam /
-        // fixture marker that must never reach the install payload.
+        // Block placeholder/stub prefixes BEFORE the C.../56-char shape check so
+        // a fixture/LLM-seam marker is reported with the specific placeholder
+        // error. 'VERIFY-*' / 'PLACEHOLDER-*' / 'TODO-*' must never reach install.
         if (PLACEHOLDER_SMART_ACCOUNT_PREFIX.test(sa)) {
             return synthesisError(`interpreter.smartAccountAddress must not be a placeholder/stub address (matches /${PLACEHOLDER_SMART_ACCOUNT_PREFIX.source}/), got: ${sa}`);
         }
@@ -599,9 +560,7 @@ function validateOptions(opts) {
             return synthesisError(`interpreter.smartAccountAddress must be a C... Stellar contract address (the on-chain policy-bound account, not the G... source account), got: ${sa}`);
         }
         const nonce = opts.interpreter.installNonce;
-        // Item 4: installNonce must fit u32 (the on-chain per-rule nonce is a
-        // u32; values above SOROBAN_LIMITS.u32Max cannot be installed). Mirrors
-        // the validUntilLedger SOROBAN_LIMITS.u32Max check above.
+        // installNonce must fit u32 (the on-chain per-rule nonce is a u32).
         if (nonce !== undefined && (!isPositiveInt(nonce) || nonce > SOROBAN_LIMITS.u32Max)) {
             return synthesisError(`interpreter.installNonce must be a positive u32 integer (<= ${SOROBAN_LIMITS.u32Max}), got: ${nonce}`);
         }
@@ -621,7 +580,7 @@ function validateOptions(opts) {
     }
     return null;
 }
-/** Placeholder/stub smart-account prefixes (item 5). Mirrors the
+/** Placeholder/stub smart-account prefixes. Mirrors the
  *  `PLACEHOLDER_INTERPRETER_ADDRESS` marker the interpreter adapter uses for
  *  the interpreter-contract strkey; a real install must point at a C...
  *  contract address derivable from the on-chain account, never a
@@ -629,16 +588,15 @@ function validateOptions(opts) {
 const PLACEHOLDER_SMART_ACCOUNT_PREFIX = /^(VERIFY-|PLACEHOLDER-|TODO-)/i;
 /** Maximum value a signed i128 can hold (2^127-1). A limitAmount above this
  *  cannot be represented on-chain, so reject it at the synthesis boundary
- *  (fail-closed) instead of passing it through as an over-broad spending_limit.
- *  Mirrors the SOROBAN_LIMITS.u32Max bound the ledger-sequence fields enforce. */
+ *  (fail-closed) instead of passing it through as an over-broad spending_limit. */
 const I128_MAX = 2n ** 127n - 1n;
 function isPositiveInt(n) {
     return Number.isInteger(n) && n > 0;
 }
-/** True when `s` is a canonical positive decimal integer inside the signed-i128
- *  range [1, 2^127-1]. A value above the i128 ceiling is rejected (fail-closed):
- *  it cannot be installed on-chain, and accepting it would emit a spending_limit
- *  with an effectively unbounded cap. */
+/** True when `s` is a canonical positive decimal integer inside [1, 2^127-1].
+ *  Values above the i128 ceiling are rejected fail-closed: they cannot be
+ *  installed on-chain, and accepting them would emit a spending_limit with an
+ *  effectively unbounded cap. */
 function isPositiveI128(s) {
     if (!/^[0-9]+$/.test(s))
         return false;
@@ -672,20 +630,17 @@ function mergeAmbiguities(...lists) {
     }
     return out;
 }
-/** Build the permit `EvalContext` the self-verify harness drives. The shape
- *  mirrors the intended recorded call (the only call the user actually
- *  performed) so:
- *    - `evaluate(predicate, ctx).permit === true` must hold (the predicate
- *      permits the recorded call it was derived from); a failure surfaces
- *      as DENY_CASE_FAILURE.
+/** Build the permit `EvalContext` the self-verify harness drives. Shape
+ *  mirrors the intended recorded call so:
+ *    - `evaluate(predicate, ctx).permit === true` must hold (a failure
+ *      surfaces as DENY_CASE_FAILURE).
  *    - `generateCases(predicate, ctx)` produces a deny battery that reflects
- *      the actual recorded move (real amount, real args, real window start).
- *  Amounts are summed per-token over all movements of the recorded tx
- *  (BigInt accumulation; never lossy). The `oraclePriceByAsset` map
- *  contains a price+timestamp satisfying each `oracle_price` leaf in the
- *  predicate so the intended call permits under every bound; the harness
- *  then mutates those entries (stale / missing / deviation / paused) to
- *  exercise the ORACLE_* deny paths. */
+ *      the actual recorded move (real amount, args, window start).
+ *  Amounts are summed per-token over all movements (BigInt, never lossy).
+ *  `oraclePriceByAsset` contains a price+timestamp satisfying each
+ *  `oracle_price` leaf so the intended call permits under every bound;
+ *  the harness mutates those entries (stale / missing / deviation / paused)
+ *  to exercise the ORACLE_* deny paths. */
 function buildPermitContext(tx, scope, topLevel, userResponses, predicate) {
     const amountByToken = {};
     const totals = new Map();
@@ -696,7 +651,8 @@ function buildPermitContext(tx, scope, topLevel, userResponses, predicate) {
     for (const [token, total] of totals) {
         amountByToken[token] = total.toString();
     }
-    const oraclePriceByAsset = oracleSatisfyingPrices(predicate, tx.fetchedAt);
+    const warnings = [];
+    const oraclePriceByAsset = oracleSatisfyingPrices(predicate, tx.fetchedAt, warnings);
     const ctx = {
         contract: scope.contract,
         fn: topLevel.fn,
@@ -711,16 +667,14 @@ function buildPermitContext(tx, scope, topLevel, userResponses, predicate) {
     if (userResponses?.validUntilLedger !== undefined) {
         ctx.validUntilLedger = userResponses.validUntilLedger;
     }
-    return ctx;
+    return { ctx, warnings };
 }
 function cloneScVal(value, depth = 0) {
-    // EvalContext.args is an ScVal[]; the recorded args are already ScVal-shaped
-    // (decoded by the recorder). We clone top-level shells so the harness can
-    // mutate deny cases without aliasing the recorded call. Recursion is
-    // bounded by MAX_SCVAL_CLONE_DEPTH so a hand-crafted nested-vec payload
-    // cannot RangeError the JS stack; the over-depth branch throws a
-    // ToolError-shaped error that the `synthesizeFromRecording` envelope
-    // (item 3) converts to `{ok:false, error}`.
+    // Clone top-level shells so the harness can mutate deny cases without
+    // aliasing the recorded call. Recursion bounded by MAX_SCVAL_CLONE_DEPTH so
+    // a hand-crafted nested-vec cannot RangeError the JS stack; the over-depth
+    // branch throws a ToolError-shaped error the envelope converts to
+    // `{ok:false, error}`.
     if (value.type === 'vec') {
         if (depth >= MAX_SCVAL_CLONE_DEPTH) {
             throw cloneDepthError(value);
@@ -732,25 +686,19 @@ function cloneScVal(value, depth = 0) {
     }
     return { ...value };
 }
-/** Throw a ToolError-shaped error when the clone exceeds MAX_SCVAL_CLONE_DEPTH.
- *  The shape (object with string `code`) is what the `synthesizeFromRecording`
- *  envelope detects and converts to a structured `{ok:false, error}`. */
 function cloneDepthError(value) {
     const err = new Error(`ScVal clone depth exceeds MAX_SCVAL_CLONE_DEPTH (${MAX_SCVAL_CLONE_DEPTH})`);
     err.code = 'SYNTHESIS_ERROR';
     err.severity = 'error';
     err.retryable = false;
-    // Tag the offending value so failures are diagnosable.
     err.depthContext = value.type;
     throw err;
 }
-/** Walk every `oracle_price` leaf in the predicate and return a price map
- *  whose entries satisfy the bound so the intended call permits. The
- *  timestamp is pinned to `nowSeconds` (the recorded `fetchedAt`) so the
- *  fresh-oracle deny case in `generateCases` is the only path that flips
- *  this map. Negatives are clamped at 0 - oracle prices are non-negative on
- *  Stellar. */
-function oracleSatisfyingPrices(predicate, nowSeconds) {
+/** Walk every `oracle_price` leaf and return a price map whose entries satisfy
+ *  the bound. Timestamp pinned to `nowSeconds` (the recorded `fetchedAt`) so
+ *  the fresh-oracle deny case in `generateCases` is the only path that flips
+ *  this map. Negatives clamped at 0 - oracle prices are non-negative on Stellar. */
+function oracleSatisfyingPrices(predicate, nowSeconds, warnings) {
     const out = {};
     visitOracleLeaves(predicate, (asset, op, bound) => {
         let price;
@@ -768,18 +716,25 @@ function oracleSatisfyingPrices(predicate, nowSeconds) {
         if (price < 0n)
             price = 0n;
         out[asset] = { price: price.toString(), timestampSeconds: nowSeconds };
+    }, (warning) => {
+        // Cross-layer L3: oracle-on-right that cannot be normalised is
+        // surfaced as a warning, not silently dropped. The Rust interpreter
+        // would surface this as `UnsupportedNode`; the warning lets the
+        // caller decide whether to fix the predicate shape or accept the
+        // over-permissive hole.
+        warnings.push(warning.message);
     });
     return out;
 }
-function visitOracleLeaves(node, visit) {
+function visitOracleLeaves(node, visit, onWarning) {
     switch (node.op) {
         case 'and':
         case 'or':
             for (const child of node.children)
-                visitOracleLeaves(child, visit);
+                visitOracleLeaves(child, visit, onWarning);
             return;
         case 'not':
-            visitOracleLeaves(node.child, visit);
+            visitOracleLeaves(node.child, visit, onWarning);
             return;
         case 'eq':
         case 'lt':
@@ -800,8 +755,27 @@ function visitOracleLeaves(node, visit) {
                 oracleAsset = rightLeaf.asset;
                 literal = oracleLiteralFromLeaf(leftLeaf);
             }
-            if (oracleAsset === undefined || literal === undefined)
+            if (oracleAsset === undefined || literal === undefined) {
+                // Two reasons the case cannot be normalised:
+                //   - neither side is an oracle leaf (visitor has nothing to do)
+                //   - oracle-on-right with a non-literal LHS (Rust dispatch would
+                //     hit UnsupportedNode; the TS model cannot build a permit ctx
+                //     for it)
+                // Only the second is a meaningful warning; the first is a no-op
+                // (the visitor was called for a non-oracle comparison). Emit the
+                // warning when an oracle IS present on one side but the other
+                // side is not a parseable threshold literal.
+                if (rightIsOracle) {
+                    onWarning?.({
+                        dimension: 'oracle_normalisation_dropped',
+                        op: node.op,
+                        asset: rightLeaf.kind === 'oracle_price' ? rightLeaf.asset : '',
+                        otherKind: leftLeaf.kind,
+                        message: `oracle-on-right cannot be normalised: the LHS (kind=${leftLeaf.kind}) is not an oracle_threshold literal; the Rust interpreter would surface UnsupportedNode here`,
+                    });
+                }
                 return;
+            }
             visit(oracleAsset, node.op, literal);
             return;
         }
@@ -811,9 +785,9 @@ 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
+/** Restate an oracle threshold 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 !== 'oracle_threshold')

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

@@ -4,7 +4,7 @@ import type { Network, PredicateNode } from '../../types.ts';
 /** [VERIFY] NOT a real deployed address. The interpreter is a per-network
  *  deploy artifact we do not have yet; install is a later phase. */
 export declare const PLACEHOLDER_INTERPRETER_ADDRESS = "VERIFY-interpreter-address";
-/** Wasm-level oracle defaults (mirrors INTERPRETER_INSTALL_PARAMS.md OracleParams).
+/** Wasm-level oracle defaults (mirrors the interpreter's `OracleParams`).
  *  Per-policy overrides may TIGHTEN only - they may never exceed these. */
 export declare const ORACLE_DEFAULTS: {
     readonly maxStalenessSeconds: 600;
@@ -29,10 +29,9 @@ export interface InterpreterAdapterConfig {
 export declare function createInterpreterAdapter(config: InterpreterAdapterConfig): CustodyAdapter;
 /** Lower a single IR rule to the canonical pre-encoding `PredicateNode`. The
  *  orchestrator uses this to wire the self-verify + minimise pipeline: after
- *  `compile(ir)` succeeds (`covered === true`, `proposed` set), the
- *  orchestrator re-derives the PredicateNode via this helper to drive
- *  `minimize` and `runHarness` on the SAME shape the encoder saw. Pure and
- *  deterministic: same `rule + config` -> byte-identical PredicateNode. The
- *  `uncovered` list the adapter surfaces during compile is NOT re-derived
- *  here; callers that need it should use the result of `compile(ir)`. */
+ *  `compile(ir)` succeeds it re-derives the PredicateNode via this helper to
+ *  drive `minimize` and `runHarness` on the SAME shape the encoder saw. Pure
+ *  and deterministic: same `rule + config` -> byte-identical PredicateNode.
+ *  The `uncovered` list is NOT re-derived - callers needing it must use
+ *  `compile(ir)`. */
 export declare function lowerRuleToPredicate(rule: IRPolicyRule, config: InterpreterAdapterConfig): PredicateNode;