@crediolabs/policy-synth 0.1.3 → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Untangled Finance Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,8 +4,13 @@ Off-chain TypeScript synthesis core for the OpenZeppelin Accounts Policy Builder
 
 It records a Soroban transaction (from an on-chain hash or a raw envelope XDR),
 synthesises the **minimal** policy that permits exactly that flow, and compiles it
-through the OZ Accounts adapter into a proposed policy. On-chain verify, simulate,
-and the unsigned install transaction are later phases.
+through the OZ Accounts adapter into a proposed policy. When the policy needs
+constraint shapes OZ built-ins cannot express (exact ordered swap paths, oracle
+price bounds, per-method scoping, recipient allowlists), the **interpreter
+adapter** is opted in to emit a parallel predicate-shaped `PolicyDocument` that
+installs alongside the OZ primitives. The synthesis is self-verified end-to-end
+via `simulatePolicy` / `verifyPolicy` and the runner of the deny-case harness
+before any bytes are emitted.
 
 The package is pure ESM, node-compatible, and has a single runtime dependency
 (`@stellar/stellar-sdk`). MIT-licensed.
@@ -73,11 +78,194 @@ events cross-check and lowers `parseConfidence`. It therefore **fails closed** a
 the default threshold; to accept a simulation-only recording, pass an explicit
 `confidenceOverride` that clears the gate.
 
+## Interpreter predicate emission (the `interpreter` opt-in)
+
+OZ built-ins express spending limits, simple thresholds, and weighted
+thresholds. They **cannot** express an exact ordered swap path, an oracle
+price bound, per-method scoping, a recipient allowlist, or an
+invocation-count window. The recording path surfaces those gaps as warnings
+by default ("Not covered by OZ built-in primitives: ..."). When the caller
+opts in to the **interpreter adapter**, the same constraint set is routed to
+the parallel interpreter IR; the adapter compiles it into a canonical
+predicate `PolicyDocument` and merges it with the OZ refs. The byte blob on
+the wire is the canonical XDR the on-chain interpreter will consume.
+
+The opt-in is purely additive — every `ToolResponse` shape is unchanged; the
+two new fields are `policyDocuments` (the predicate-shaped interpreter doc)
+and one `policyRef` of `kind: 'interpreter'`.
+
+```ts
+import { Address } from '@stellar/stellar-sdk'
+import {
+  synthesizeFromRecording,
+  placeholderOzConfig,
+} from '@crediolabs/policy-synth'
+
+const oz = placeholderOzConfig('mainnet')
+const smartAccount = Address.contract(Buffer.alloc(32, 0xee)).toString()
+
+const result = synthesizeFromRecording(
+  recordedTx,
+  {
+    network: 'mainnet',
+    userResponses: {
+      windowSeconds: 2592000,                    // 30 days
+      limitAmount: '1000000000',                 // supplied cap
+      validUntilLedger: 200000000,               // future ledger
+      oraclePriceBound: [                        // optional oracle bound
+        { asset: 'CEURC', operator: 'lt', value: '1000000000' },
+      ],
+      swapRecipientAllowlist: ['GOWNER'],        // optional allowlist
+    },
+    interpreter: {
+      smartAccountAddress: smartAccount,         // MUST be a C... contract address
+      installNonce: 1,                           // first install -> 1
+      // oracleParams: { maxStalenessSeconds: 60, maxDeviationBps: 100 }
+      // (tighten-only vs the wasm defaults; widening is rejected)
+    },
+  },
+  oz
+)
+
+if (result.ok) {
+  console.log(result.data.policyDocuments.length)  // >= 1 when constraints are routable
+  const interpreterRef = result.data.policyRefs.find((r) => r.kind === 'interpreter')
+  console.log(interpreterRef?.predicateBlobBase64) // canonical XDR, base64
+  console.log(result.data.contextRule.validUntilLedger)
+}
+```
+
+The interpreter compile path is **fail-closed**:
+
+- `SCOPE_SELF_CALL` — the call's recipient equals the smart account.
+- `ORACLE_LEAF_INVALID_POSITION` — an oracle leaf is wrongly nested.
+- `ORACLE_PARAMS_OUT_OF_RANGE` — `oracleParams` widening vs the wasm defaults.
+- `SYNTHESIS_ERROR` — the interpreter IR is not fully covered.
+- `DENY_CASE_FAILURE` — the emitted predicate fails the deny-case battery;
+  `details.failures` lists the flipped dimension(s).
+
+A recorded swap that compiles to a permissive policy under OZ alone therefore
+stays permissive unless the interpreter opt-in is supplied AND the predicate
+self-verifies end-to-end.
+
+### Self-verify + minimise (always-on with the opt-in)
+
+Opting in to the interpreter also turns on the **self-verify pipeline**:
+
+1. The adapter emits the candidate predicate.
+2. The synth builds a permit `EvalContext` from the recorded transaction (the
+   only call the user actually performed).
+3. The candidate is **minimised** — load-bearing-free top-level conjuncts are
+   dropped (`and` predicates only; other shapes are returned unchanged).
+4. The minimised predicate is run through the deny-case battery — a structural
+   fingerprint across `contract`, `function`, `args`, `amount`, `window`,
+   `oracle`, `recipient`, `frequency`. Each case must deny.
+5. The intended recorded call is evaluated against the predicate; it must
+   permit.
+6. The (possibly minimised) predicate is re-encoded; the canonical bytes + the
+   SHA-256 hash are stamped back onto the `PolicyDocument` and the
+   `interpreter` `policyRef`.
+
+A successful `ok: true` is the proof that the emitted document is minimal AND
+self-verified. A failure surfaces the matching gate code (see above).
+
+## Simulate and verify (the `verify/` surface)
+
+The same self-verify pipeline is exposed as a public API for callers that want
+to re-run a check on a proposed predicate without re-synthesising:
+
+```ts
+import { simulatePolicy, verifyPolicy } from '@crediolabs/policy-synth'
+
+// Runtime check: re-evaluate the predicate against the recorded call.
+const runtime = simulatePolicy(predicate, recordedTx, {
+  validUntilLedger: 200000000,
+  oraclePricesByAsset: { CEURC: { price: '999999999', timestampSeconds: now } },
+})
+
+// Static minimality check: prove no top-level conjunct is load-bearing-free.
+const staticCheck = verifyPolicy(predicate, recordedTx)
+```
+
+The boundary is pinned:
+
+- `SIMULATION_ERROR` — runtime evaluation failed (malformed fixture, missing
+  oracle price, uncontrolled throw). The policy may still be minimal.
+- `VERIFICATION_FAILED` — the static minimality check failed. The policy is
+  structurally over-broad regardless of how any concrete call evaluates.
+
+Both are deterministic: same `(predicate, recordedTx, opts)` → byte-identical
+envelope.
+
+## Review-card (the human-audit surface)
+
+The package emits a deterministic review-card summary so a human auditor can
+sanity-check the inferred policy without re-running the synthesis:
+
+```ts
+import {
+  buildReviewCardSummary,
+  classifyConflict,
+  summaryCrossCheck,
+} from '@crediolabs/policy-synth'
+
+const summary = buildReviewCardSummary(proposedPolicy, recordedTx)
+const conflict = classifyConflict(proposedPolicy, recordedTx)
+const crossCheck = summaryCrossCheck(proposedPolicy, recordedTx)
+```
+
+The summary is the canonical human-readable digest of the proposed policy;
+`classifyConflict` flags refs that contradict the recording; `summaryCrossCheck`
+re-derives the summary from the raw refs and the recording, and reports
+discrepancies. All three are pure and deterministic.
+
+## Codegen escape hatch (the Rust interpreter)
+
+When the canonical verifier is unavailable, the recorder can emit a Rust
+source file that performs the same predicate evaluation off-chain via a
+`cargo` build. The escape hatch is OUT of the audited happy path: the
+synthesiser never calls `generateRust` itself; the CLI subcommand is the only
+entry point.
+
+```ts
+import { generateRust, compileCheck, hasRustToolchain } from '@crediolabs/policy-synth'
+
+if (await hasRustToolchain()) {
+  const { source, path } = generateRust(predicate, { out: 'policy.rs' })
+  const gate = await compileCheck({ crateDir: '.', predicate })
+  if (!gate.ok) console.error('compile gate failed:', gate.error)
+}
+```
+
+The escape hatch is toolchain-gated: `hasRustToolchain()` returns `false`
+when `cargo` is not installed, and `compileCheck()` refuses to run on a
+machine without one. The generated source is **not** the on-chain interpreter
+— it is a deterministic off-chain reference that re-evaluates the same
+predicate for parity testing.
+
+## Composition rules
+
+The merged `policyRefs` on a `ProposedPolicy` are ordered
+`[interpreterRef?, ...oz_builtinRefs]` and bounded by
+`OZ_LIMITS.maxPoliciesPerRule` (5). The orchestrator refuses to install a
+policy that exceeds this cap (`POLICY_CAP_EXCEEDED`). The OZ-side `uncovered`
+warnings that the interpreter actually lowered (per-method scoping, recipient
+allowlists, exact ordered sequences, oracle price bounds, invocation-count
+windows, token-mismatch spending limits) are dropped from the user-facing
+warnings when the interpreter succeeds — the warning list reflects what is
+still UN-enforced, not what OZ alone could not do.
+
 ## Status
 
-The recorder, both synthesizer front-ends, and the OZ Accounts adapter are
-implemented and unit-test covered. Install, on-chain verify, simulate, and the
-Rust interpreter are later phases.
+Implemented and unit-test covered: the recorder, both synthesizer
+front-ends, the OZ Accounts adapter, the interpreter adapter, the
+predicate encoder, the evaluator, the deny-case battery, the minimiser, the
+self-verify pipeline, the simulate / verify surface, the review-card
+builder, the cross-check, and the Rust codegen escape hatch.
+
+The on-chain Rust interpreter, install-transaction assembly, and live RPC
+integration are wired in the @crediolabs/policy-builder-cli layer (separate
+package).
 
 ## License
 

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

@@ -0,0 +1,38 @@
+import type { IRPolicyRule } from '../../ir/types.ts';
+import type { CustodyAdapter } from '../../seams/types.ts';
+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).
+ *  Per-policy overrides may TIGHTEN only - they may never exceed these. */
+export declare const ORACLE_DEFAULTS: {
+    readonly maxStalenessSeconds: 600;
+    readonly maxDeviationBps: 200;
+};
+export interface InterpreterAdapterConfig {
+    network: Network;
+    /** Per-rule install nonce (first install = 1; replay-protected). */
+    installNonce: number;
+    /** The smart account this interpreter policy will be installed against. Used
+     *  by the self-call gate: any `in`-allowlist containing this address is
+     *  rejected as `SCOPE_SELF_CALL`. */
+    smartAccountAddress: string;
+    /** Optional per-policy oracle overrides. Must TIGHTEN vs ORACLE_DEFAULTS
+     *  (i.e. <= each default). A widening value throws ORACLE_PARAMS_OUT_OF_RANGE
+     *  at compile time. */
+    oracleParams?: {
+        maxStalenessSeconds?: number;
+        maxDeviationBps?: number;
+    };
+}
+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)`. */
+export declare function lowerRuleToPredicate(rule: IRPolicyRule, config: InterpreterAdapterConfig): PredicateNode;