@crediolabs/policy-synth 0.1.4 → 0.1.5

package/dist-cjs/types.d.ts

@@ -0,0 +1,288 @@
+export type Network = 'mainnet' | 'testnet';
+/** Decoded Soroban value - the normalised subset synthesis needs. */
+export type ScVal = {
+    type: 'address';
+    value: string;
+} | {
+    type: 'i128';
+    value: string;
+} | {
+    type: 'u64';
+    value: string;
+} | {
+    type: 'u32';
+    value: string;
+} | {
+    type: 'symbol';
+    value: string;
+} | {
+    type: 'vec';
+    value: ScVal[];
+} | {
+    type: 'bytes';
+    value: string;
+} | {
+    type: 'other';
+    value: string;
+};
+/** OZ Accounts framework hard limits (verified against canonical OZ source). */
+export declare const OZ_LIMITS: {
+    readonly maxPoliciesPerRule: 5;
+    readonly maxSignersPerRule: 15;
+};
+/** Soroban / Stellar protocol limits used to bound inputs fail-closed. Single
+ *  source so the schema boundary and the core validators cannot drift. */
+export declare const SOROBAN_LIMITS: {
+    /** `valid_until` and other ledger-sequence fields are u32. */
+    readonly u32Max: 4294967295;
+    /** Upper bound on top-level invocations in a recorded transaction; a real
+     *  Stellar tx caps operations well below this. Bounds a hand-crafted payload. */
+    readonly maxInvocations: 512;
+    /** Stellar targets a ~5s ledger close time (DAY_IN_LEDGERS = 17280 = 86400/5),
+     *  used to convert a spend window in seconds to OZ `period_ledgers`. */
+    readonly secondsPerLedger: 5;
+};
+/** Maximum recursion depth for decoding Recursive `ScVal` shapes (vec-in-vec).
+ *  A real Stellar tx caps nesting well below this; the bound hard-caps a
+ *  hand-crafted payload so the recorder fails CLOSED (records the over-depth
+ *  branch as opaque `depth-exceeded`) rather than RangeErroring the JS stack.
+ *  Mirrors the `MAX_AUTH_TREE_DEPTH = 16` boundary the auth-tree decoder
+ *  already enforces; lifted to 30 so legitimate nested args (a path vec
+ *  inside an order vec inside a market-data vec) decode cleanly while a
+ *  malformed ~10000-deep payload still trips the cap. */
+export declare const MAX_SCVAL_DEPTH: 30;
+/** Maximum recursion depth for cloning nested `ScVal` shapes (vec-in-vec) into
+ *  the simulator / verify / harness contexts. Mirrors `MAX_SCVAL_DEPTH` above
+ *  so a hand-crafted nested-vec payload cannot RangeError the JS stack during
+ *  context building. Over-depth throws a ToolError (caught by the
+ *  `synthesizeFromRecording` envelope + the simulator/verify boundaries) so
+ *  the caller gets a structured `{ok:false, error}` instead of a thrown
+ *  RangeError. */
+export declare const MAX_SCVAL_CLONE_DEPTH: 30;
+/** Predicate-document caps - enforced fail-closed at install by BOTH the synth (TS)
+ *  AND the interpreter (Rust). Single source: a CI test asserts the two cap sets are
+ *  byte-identical (TS reads the same JSON manifest the Rust build emits). If they
+ *  disagree, the interpreter is authoritative. Rationale per cap:
+ *    - MAX_DEPTH = 5:             3 walkthroughs need depth 2; budget = 2x growth + 1 for `not` chain.
+ *    - MAX_LEAVES = 200:         allowlists (recipients, paths) typically < 100; budget = 2x + 1 nested allowlist.
+ *    - MAX_PREDICATE_BYTES = 32 KB: well under the per-ledger-entry 64 KB persistent-storage limit.
+ *    - MAX_ORACLE_READS = 6:     two-round confirmation per asset consumes 2 reads; cap accommodates a predicate that references up to 3 unique oracle assets (3 * 2 = 6 reads). Stays a fail-closed install-time cap.
+ *    - MAX_IN_OPERAND_COUNT = 32: allowlist < 32 is a UX-natural bound. */
+export declare const PREDICATE_CAPS: {
+    readonly MAX_DEPTH: 5;
+    readonly MAX_LEAVES: 200;
+    readonly MAX_PREDICATE_BYTES: number;
+    readonly MAX_ORACLE_READS: 6;
+    readonly MAX_IN_OPERAND_COUNT: 32;
+};
+/** OZ context-rule draft - the unit the install builder builds add_context_rule from. */
+export type ContextRuleDraft = {
+    contextRuleType: {
+        kind: 'default';
+    } | {
+        kind: 'call_contract';
+        contract: string;
+    } | {
+        kind: 'create_contract';
+        wasmHash: string;
+    };
+    name: string;
+    /** Ledger sequence (u32). Soroban `valid_until: Option<u32>`. */
+    validUntilLedger: number | null;
+    /** Mirrors OZ `Signer` enum exactly: `Delegated(Address) | External(Address, Bytes)`.
+     *  The verifier address + key bytes for an external signer are carried in the
+     *  `External` variant - there is no `Key` or `SmartAccount` variant, and no
+     *  master/non-master discriminator lives on the type itself. */
+    signers: SignerDraft[];
+    policies: PolicyRef[];
+};
+/** Mirrors OZ `Signer` exactly: `Signer::Delegated(Address) | Signer::External(Address, Bytes)`. */
+export type SignerDraft = {
+    kind: 'delegated';
+    address: string;
+} | {
+    kind: 'external';
+    verifier: string;
+    keyBytes: string;
+};
+/** Reference to one policy attached to a context rule. */
+export type PolicyRef = {
+    kind: 'oz_builtin';
+    primitive: OZPrimitiveConfig;
+    instanceAddress: string;
+} | {
+    kind: 'interpreter';
+    interpreterAddress: string;
+    predicateBlobBase64: string;
+};
+/** A serialised predicate document stored against a (smart_account, rule_id) pair. */
+export interface PolicyDocument {
+    /** Grammar version baked into the interpreter wasm. Fail-closed strict match at install
+     *  AND at evaluate (defence in depth). NOT the per-edit revision. */
+    grammarVersion: 1;
+    /** Per-rule install nonce. Must equal the interpreter's stored nonce + 1 at install.
+     *  First install accepts nonce = 1 with stored nonce = 0. Re-install is structurally
+     *  possible by incrementing the nonce; uninstall removes the nonce with state so a
+     *  subsequent install returns to nonce = 1. Replay of an old install denied. */
+    installNonce: number;
+    /** Canonical ScVal encoding (NOT JSON) - the version-match bypass is closed by the
+     *  on-chain serialisation, not by a parser. */
+    encodedPredicate: string;
+    /** Hash of the post-canonicalisation bytes of encodedPredicate. Stored alongside the
+     *  doc and re-verified at evaluate. */
+    predicateHash: string;
+    /** Per-policy overrides of oracle thresholds; absent = use defaults.
+     *  Overrides may TIGHTEN only (never widen) - the interpreter rejects any per-policy
+     *  value looser than the wasm-level defaults at install. */
+    oracleParams?: {
+        /** Seconds; must be <= MAX_ORACLE_STALENESS_SECONDS (600). */
+        maxStalenessSeconds?: number;
+        /** Basis points; must be <= MAX_ORACLE_DEVIATION_BPS (200). */
+        maxDeviationBps?: number;
+    };
+}
+/** The versioned predicate AST (interpreter side). Tagged union. */
+export type PredicateNode = {
+    op: 'and';
+    children: PredicateNode[];
+} | {
+    op: 'or';
+    children: PredicateNode[];
+} | {
+    op: 'not';
+    child: PredicateNode;
+} | {
+    op: 'eq';
+    left: PredicateLeaf;
+    right: PredicateLeaf;
+} | {
+    op: 'lt' | 'lte' | 'gt' | 'gte';
+    left: PredicateLeaf;
+    right: PredicateLeaf;
+} | {
+    op: 'in';
+    needle: PredicateLeaf;
+    haystack: PredicateLeaf[]; /** set-valued only - the haystack is always sorted by canonical XDR bytes (pure membership). */
+};
+export type PredicateLeaf = {
+    kind: 'call_contract';
+} | {
+    kind: 'call_fn';
+} | {
+    kind: 'call_arg';
+    index: number;
+} | {
+    kind: 'amount';
+    token: string;
+} | {
+    kind: 'window_spent';
+    token: string;
+    windowSeconds: number;
+} | {
+    kind: 'now';
+} | {
+    kind: 'valid_until';
+} | {
+    kind: 'invocation_count_in_window';
+    windowSecs: number;
+} | {
+    kind: 'oracle_price';
+    asset: string;
+} | {
+    kind: 'literal_address';
+    value: string;
+} | {
+    kind: 'literal_i128';
+    value: string;
+} | {
+    kind: 'literal_symbol';
+    value: string;
+} | {
+    kind: 'literal_u32';
+    value: number;
+} | {
+    kind: 'literal_u64';
+    value: string;
+} | {
+    kind: 'literal_bytes';
+    value: string;
+} | {
+    kind: 'literal_vec';
+    elements: PredicateLeaf[];
+};
+export interface OZPrimitiveConfig {
+    primitive: 'spending_limit' | 'simple_threshold' | 'weighted_threshold';
+    params: Record<string, unknown>;
+}
+export interface ContractInvocation {
+    contract: string;
+    fn: string;
+    args: ScVal[];
+    subInvocations: ContractInvocation[];
+}
+export interface TokenMovement {
+    token: string;
+    from: string;
+    to: string;
+    amount: string;
+}
+export interface OnChainEvent {
+    contract: string;
+    topics: string[];
+    data: ScVal;
+}
+export interface RecordedTransaction {
+    network: Network;
+    /** Authorising signers (the agent / owner set). */
+    signers: string[];
+    /** Top-level call + nested sub-invocations captured for analysis:
+     *  v1 grammar matches only the top-level call's own `(contract, fn_name, args)`
+     *  that `Policy::enforce` receives - sub-invocations are NOT walked in v1. */
+    invocations: ContractInvocation[];
+    /** All token movements (from events). */
+    tokenMovements: TokenMovement[];
+    /** Raw on-chain events from getTransaction (used for validation). */
+    events: OnChainEvent[];
+    /** Soroban auth entries (which signers, which contracts, which fns). */
+    authEntries: unknown[];
+    ledgerSequence: number;
+    fetchedAt: number;
+    /** The parsed-decoding freshness, computed by the recorder. The synth refuses on
+     *  parseConfidence.overall < parseConfidence.thresholdUsed. */
+    parseConfidence: ParseConfidence;
+    /** Source account (already recorded, needed by install + reviewer). */
+    sourceAccount: string;
+}
+export interface ProposedPolicy {
+    contextRule: ContextRuleDraft;
+    policyDocuments: PolicyDocument[];
+    policyRefs: PolicyRef[];
+    /** Parsed-decoding freshness mirror; the orchestrator refuses when below threshold. */
+    parseConfidence: ParseConfidence;
+    warnings: string[];
+    ambiguities: AmbiguityPrompt[];
+}
+export interface AmbiguityPrompt {
+    code: AmbiguityCode;
+    question: string;
+}
+/** Catalogue of named ambiguity codes (the skill's prompt files are one-per-code).
+ *  Adding a code is a synthesizer decision; the prompt authoring must not
+ *  invent codes outside this union. */
+export type AmbiguityCode = 'DURATION_UNSPECIFIED' | 'AMOUNT_BOUND_MISSING' | 'RECIPIENT_ALLOWLIST_EMPTY' | 'FREQUENCY_BOUND_MISSING' | 'ORACLE_ASSET_UNKNOWN' | 'MULTIPLE_UNRELATED_TARGETS';
+/** Structured recording freshness. `overall` is the gate threshold (default 1.0); the
+ *  breakdown is the diagnostic the user / agent sees when the gate fires. The
+ *  computation rule is pinned: `overall = 1 - (unknownContracts + opaqueScVals) / total`. */
+export interface ParseConfidence {
+    overall: number;
+    knownContracts: string[];
+    unknownContracts: Array<{
+        contract: string;
+        reason: 'no-abi' | 'version-mismatch' | 'opaque-result';
+    }>;
+    opaqueScVals: Array<{
+        path: string;
+        type: string;
+    }>;
+    thresholdUsed: number;
+}

package/dist-cjs/types.js

@@ -0,0 +1,55 @@
+"use strict";
+// src/types.ts - shared domain types (single source of truth)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREDICATE_CAPS = exports.MAX_SCVAL_CLONE_DEPTH = exports.MAX_SCVAL_DEPTH = exports.SOROBAN_LIMITS = exports.OZ_LIMITS = void 0;
+/** OZ Accounts framework hard limits (verified against canonical OZ source). */
+exports.OZ_LIMITS = {
+    maxPoliciesPerRule: 5,
+    maxSignersPerRule: 15,
+    // NO per-account rule cap - OZ imposes none.
+};
+/** Soroban / Stellar protocol limits used to bound inputs fail-closed. Single
+ *  source so the schema boundary and the core validators cannot drift. */
+exports.SOROBAN_LIMITS = {
+    /** `valid_until` and other ledger-sequence fields are u32. */
+    u32Max: 4294967295,
+    /** Upper bound on top-level invocations in a recorded transaction; a real
+     *  Stellar tx caps operations well below this. Bounds a hand-crafted payload. */
+    maxInvocations: 512,
+    /** Stellar targets a ~5s ledger close time (DAY_IN_LEDGERS = 17280 = 86400/5),
+     *  used to convert a spend window in seconds to OZ `period_ledgers`. */
+    secondsPerLedger: 5,
+};
+/** Maximum recursion depth for decoding Recursive `ScVal` shapes (vec-in-vec).
+ *  A real Stellar tx caps nesting well below this; the bound hard-caps a
+ *  hand-crafted payload so the recorder fails CLOSED (records the over-depth
+ *  branch as opaque `depth-exceeded`) rather than RangeErroring the JS stack.
+ *  Mirrors the `MAX_AUTH_TREE_DEPTH = 16` boundary the auth-tree decoder
+ *  already enforces; lifted to 30 so legitimate nested args (a path vec
+ *  inside an order vec inside a market-data vec) decode cleanly while a
+ *  malformed ~10000-deep payload still trips the cap. */
+exports.MAX_SCVAL_DEPTH = 30;
+/** Maximum recursion depth for cloning nested `ScVal` shapes (vec-in-vec) into
+ *  the simulator / verify / harness contexts. Mirrors `MAX_SCVAL_DEPTH` above
+ *  so a hand-crafted nested-vec payload cannot RangeError the JS stack during
+ *  context building. Over-depth throws a ToolError (caught by the
+ *  `synthesizeFromRecording` envelope + the simulator/verify boundaries) so
+ *  the caller gets a structured `{ok:false, error}` instead of a thrown
+ *  RangeError. */
+exports.MAX_SCVAL_CLONE_DEPTH = 30;
+/** Predicate-document caps - enforced fail-closed at install by BOTH the synth (TS)
+ *  AND the interpreter (Rust). Single source: a CI test asserts the two cap sets are
+ *  byte-identical (TS reads the same JSON manifest the Rust build emits). If they
+ *  disagree, the interpreter is authoritative. Rationale per cap:
+ *    - MAX_DEPTH = 5:             3 walkthroughs need depth 2; budget = 2x growth + 1 for `not` chain.
+ *    - MAX_LEAVES = 200:         allowlists (recipients, paths) typically < 100; budget = 2x + 1 nested allowlist.
+ *    - MAX_PREDICATE_BYTES = 32 KB: well under the per-ledger-entry 64 KB persistent-storage limit.
+ *    - MAX_ORACLE_READS = 6:     two-round confirmation per asset consumes 2 reads; cap accommodates a predicate that references up to 3 unique oracle assets (3 * 2 = 6 reads). Stays a fail-closed install-time cap.
+ *    - MAX_IN_OPERAND_COUNT = 32: allowlist < 32 is a UX-natural bound. */
+exports.PREDICATE_CAPS = {
+    MAX_DEPTH: 5,
+    MAX_LEAVES: 200,
+    MAX_PREDICATE_BYTES: 32 * 1024,
+    MAX_ORACLE_READS: 6,
+    MAX_IN_OPERAND_COUNT: 32,
+};

package/dist-cjs/verify/envelope.d.ts

@@ -0,0 +1,15 @@
+export type SimulationResult = {
+    permit: {
+        tx: 'permit';
+    } | {
+        tx: 'deny';
+        reason: string;
+    };
+    evaluatedCases: Array<{
+        dimension: string;
+        outcome: 'permit' | 'deny';
+        reason: string;
+    }>;
+    backend: 'interpreter-v1' | 'ts-model';
+    simulatorVersion: string;
+};

package/dist-cjs/verify/envelope.js

@@ -0,0 +1,23 @@
+"use strict";
+// src/verify/envelope.ts - the post-simulation result envelope used by
+// review-card rendering and verification.
+//
+// `SimulationResult` is the structured verdict a `simulate_policy` run
+// produces; the review-card builder reads it as one of its inputs (so the
+// rendered card can quote the backend that evaluated the policy) and the
+// verification pipeline reads `permit` + `evaluatedCases` to confirm every
+// generated deny case really did deny.
+//
+// This envelope is intentionally separate from the CustodyAdapter
+// `SimulationResult` in `src/seams/types.ts` (which is the dry-run stub
+// returned by `adapter.simulate(ir, permitTx)`); the seam result is the
+// adapter contract, this envelope is the post-simulation record consumed by
+// downstream rendering + verification.
+//
+// Fields:
+//   - `permit` is the single verdict for the candidate recorded tx.
+//   - `evaluatedCases` is the deny-case battery outcome (every dimension
+//     must report `deny` when the policy is minimal).
+//   - `backend` is the actual evaluator that produced the verdict.
+//   - `simulatorVersion` lets the reviewer / audit log distinguish runs.
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,3 @@
+export type { SimulationResult } from './envelope.ts';
+export { type SimulateOptions, simulatePolicy } from './simulate.ts';
+export { type VerifyOptions, verifyPolicy } from './verify.ts';

package/dist-cjs/verify/index.js

@@ -0,0 +1,8 @@
+"use strict";
+// src/verify/index.ts - re-export the simulation / verification surface.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyPolicy = exports.simulatePolicy = void 0;
+var simulate_ts_1 = require("./simulate.js");
+Object.defineProperty(exports, "simulatePolicy", { enumerable: true, get: function () { return simulate_ts_1.simulatePolicy; } });
+var verify_ts_1 = require("./verify.js");
+Object.defineProperty(exports, "verifyPolicy", { enumerable: true, get: function () { return verify_ts_1.verifyPolicy; } });

package/dist-cjs/verify/simulate.d.ts

@@ -0,0 +1,31 @@
+import type { ToolResponse } from '../errors.ts';
+import type { PredicateNode, RecordedTransaction } from '../types.ts';
+import type { SimulationResult } from './envelope.ts';
+/** Options for `simulatePolicy`. `validUntilLedger` is propagated onto the
+ *  permit EvalContext so the simulator exercises the expiry gate; absent ->
+ *  no expiry check (mirrors the orchestrator's "no `validUntilLedger`
+ *  supplied" path). `oraclePricesByAsset` is the test fixture the simulator
+ *  uses to satisfy `oracle_price` leaves so the permit call evaluates under
+ *  the bound; absent -> derive satisfying prices from the predicate itself
+ *  (the orchestrator's oracle-satisfying-price logic). */
+export interface SimulateOptions {
+    validUntilLedger?: number;
+    /** Pre-populated oracle-price entries keyed by asset address. The fixture
+     *  must satisfy every `oracle_price` leaf in the predicate; absent or
+     *  unsatisfying entries cause `SIMULATION_ERROR`. */
+    oraclePricesByAsset?: Record<string, {
+        price: string;
+        timestampSeconds: number;
+    } | {
+        error: 'stale' | 'missing' | 'deviation' | 'paused' | 'decimals' | 'fingerprint';
+    }>;
+}
+/** Replay a recorded transaction against a proposed predicate and emit the
+ *  `SimulationResult` envelope. The simulator returns the SAME permit
+ *  verdict `runHarness` expects: the intended recorded call must permit; every
+ *  generated deny dimension must deny. A runtime evaluation failure
+ *  (malformed input, missing oracle fixture, etc.) returns a `SIMULATION_ERROR`
+ *  `ToolError` - NOT a deny verdict, NOT `VERIFICATION_FAILED`. The boundary
+ *  is pinned: minimality is a verify-time concern, runtime evaluation is a
+ *  simulate-time concern. */
+export declare function simulatePolicy(predicate: PredicateNode | null, permitTx: RecordedTransaction, opts?: SimulateOptions): ToolResponse<SimulationResult>;