@crediolabs/policy-synth 0.1.17 → 0.2.0

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

@@ -1,36 +1,11 @@
 "use strict";
 // 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).
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.synthesizeFromRecording = synthesizeFromRecording;
 exports.throwToolError = throwToolError;
@@ -47,13 +22,11 @@ const minimize_ts_1 = require("./minimize.js");
 const scope_ts_1 = require("./scope.js");
 const UNCOVERED_PREFIX = 'Not covered by OZ built-in primitives: ';
 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);
     }
@@ -72,10 +45,9 @@ 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;
@@ -92,17 +64,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 {
@@ -130,15 +99,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 {
@@ -168,9 +131,7 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
             },
         };
     }
-    // 2. lower.
     const facts = (0, lower_ts_1.lower)(tx);
-    // 3. decideScope.
     const scopeRes = (0, scope_ts_1.decideScope)(facts, {
         network: opts.network,
         ...(opts.userResponses?.validUntilLedger !== undefined
@@ -200,11 +161,8 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
     };
     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.
+    // 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).
@@ -227,6 +185,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,
@@ -235,8 +197,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 {
@@ -353,7 +324,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'
             ? (0, minimize_ts_1.minimize)(startingPredicate, permitCtx, deny_cases_ts_1.ORIGINAL_DIMENSIONS)
             : startingPredicate;
@@ -384,12 +360,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 = [
@@ -415,10 +388,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 } = (0, encode_ts_1.encodePredicate)(finalPredicate);
         if (testSeam !== undefined) {
             interpreterPolicyDocument = {
@@ -491,9 +463,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.',
@@ -508,16 +478,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) {
@@ -540,21 +508,20 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
     }
     return envelope;
 }
-/** 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)}`);
@@ -586,13 +553,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}`);
         }
@@ -600,9 +563,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 > types_ts_1.SOROBAN_LIMITS.u32Max)) {
             return synthesisError(`interpreter.installNonce must be a positive u32 integer (<= ${types_ts_1.SOROBAN_LIMITS.u32Max}), got: ${nonce}`);
         }
@@ -622,7 +583,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
@@ -630,16 +591,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;
@@ -673,20 +633,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();
@@ -697,7 +654,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,
@@ -712,16 +670,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 >= types_ts_1.MAX_SCVAL_CLONE_DEPTH) {
             throw cloneDepthError(value);
@@ -733,25 +689,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 (${types_ts_1.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;
@@ -769,18 +719,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':
@@ -801,8 +758,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;
         }
@@ -812,9 +788,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-synth",
-  "version": "0.1.17",
+  "version": "0.2.0",
   "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",