@crediolabs/policy-synth 0.2.0 → 0.3.0

package/dist/run/index.d.ts

@@ -1,11 +1,9 @@
 import { type ErrorCode, type PredicateNode, type ProposedPolicy, type RecordedTransaction, type ToolError, type ToolResponse } from '../index.ts';
-import { type AuthorityOverlap } from '../install/authority-overlap.ts';
 import { type BuildInstallPolicyResult, type BuildRevokePolicyResult } from '../install/build-install-policy.ts';
 import { getInterpreterInfo } from '../install/get-interpreter-info.ts';
-import type { SimulationResult } from '../verify/envelope.ts';
 import { type RecordTransactionInput, type SimulatePolicyInput, type SynthesizePolicyInput, type VerifyPolicyInput } from './schemas.ts';
 export type { GetInterpreterInfoInput, InstallPolicyInput, RecordTransactionInput, RevokePolicyInput, SimulatePolicyInput, SynthesizePolicyInput, VerifyPolicyInput, } from './schemas.ts';
-export { ComposeUserResponsesSchema, GetInterpreterInfoInputSchema, InstallPolicyInputSchema, InterpreterOptionsSchema, MAINNET_RPC_URL, MandateSpecSchema, NetworkSchema, OraclePriceFixtureSchema, OzAdapterConfigSchema, PINNED_INTERPRETER_ADDRESS_BY_NETWORK, PINNED_INTERPRETER_GRAMMAR_VERSION, PINNED_INTERPRETER_MAINNET_ADDRESS, PINNED_INTERPRETER_TESTNET_ADDRESS, PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK, PredicateLeafSchema, PredicateNodeSchema, RecordedTransactionSchema, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SimulatePolicyInputSchema, SynthesizePolicyInputSchema, TESTNET_RPC_URL, ToolErrorSchema, VerifyPolicyInputSchema, } from './schemas.ts';
+export { ComposeUserResponsesSchema, GetInterpreterInfoInputSchema, InstallPolicyInputSchema, InterpreterOptionsSchema, MAINNET_RPC_URL, NetworkSchema, PINNED_INTERPRETER_ADDRESS_BY_NETWORK, PINNED_INTERPRETER_GRAMMAR_VERSION, PINNED_INTERPRETER_MAINNET_ADDRESS, PINNED_INTERPRETER_TESTNET_ADDRESS, PINNED_INTERPRETER_WASM_SHA256, PredicateLeafSchema, PredicateNodeSchema, RecordedTransactionSchema, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SynthesizePolicyInputSchema, TESTNET_RPC_URL, ToolErrorSchema, } from './schemas.ts';
 export type RunRecordTransactionInput = RecordTransactionInput;
 export type RunSynthesizePolicyInput = SynthesizePolicyInput;
 export type RunSimulatePolicyInput = SimulatePolicyInput;
@@ -24,7 +22,6 @@ type RunToolName = 'record_transaction' | 'synthesize_policy' | 'simulate_policy
  *  the agent always sees a machine-readable error code. */
 export declare function runRecordTransaction(raw: unknown): Promise<ToolResponse<RecordedTransaction>>;
 /** `synthesize_policy` body - discriminated union on `source`:
- *    - `mandate`   -> synthesizeFromMandate
  *    - `recording` -> synthesizeFromRecording
  *  Exposing BOTH front-ends through ONE tool keeps the MCP surface tiny while
  *  letting the agent pick the deterministic or the inferred path. The CLI
@@ -38,120 +35,9 @@ export declare function runRecordTransaction(raw: unknown): Promise<ToolResponse
 export declare function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<ProposedPolicy> & {
     explain?: {
         predicateTree: PredicateNode | null;
-        simulation: SimulationResult;
     };
 }>;
-/** `simulate_policy` body - thin wrapper over `simulatePolicy`. The engine
- *  already returns fail-closed `{ok:false, error}` for runtime failures
- *  (SIMULATION_ERROR), so the try/catch envelope is for raw SDK throws
- *  only - same pattern as the other two wrappers. The predicate is
- *  passed inline (stateless by design; no `proposed_policy_id` lookup). */
-export declare function runSimulatePolicy(raw: unknown): Promise<ToolResponse<SimulationResult>>;
-/** `verify_policy` body - thin wrapper over `verifyPolicy`. The engine
- *  already returns `{ok:false, error}` with code VERIFICATION_FAILED when
- *  the minimality check fails; the try/catch envelope is for raw SDK
- *  throws only. Mirrors `runSimulatePolicy` exactly. */
-export declare function runVerifyPolicy(raw: unknown): Promise<ToolResponse<true>>;
-/** `install_policy` body - thin wrapper over `buildInstallPolicyXdr`.
- *  Returns the unsigned Soroban transaction envelope (base64 XDR) the
- *  wallet signs. The wallet signature IS the user-confirmation step - no
- *  `action_id` two-call pair (the server is stateless, see server.ts:10-12).
- *  One call installs the policy outright: `add_context_rule` carries the
- *  predicate to the interpreter in its `policies` install_param, so no
- *  separate `interpreter.install` call is needed or possible.
- *
- *  Default-deny: an interpreter policy address other than the pinned
- *  interpreter for the selected network is REFUSED (the smart account
- *  would delegate to an interpreter the caller controls); the same
- *  applies to a non-pinned RPC URL (the auth nonce the wallet signs
- *  comes from the RPC). Both gates accept an explicit opt-in flag.
- *  Pin selection follows `input.network` (defaults to `testnet` so the
- *  pre-mainnet callers keep working unchanged). */
-export declare function runInstallPolicy(raw: unknown): Promise<ToolResponse<InstallPolicyResult>>;
-/** Default-deny on the cross-rule scan.
- *
- *  Refuses whenever the scan cannot establish that this policy binds the calls
- *  it names. An unpoliced neighbour provably does not constrain them. An
- *  opaque one, policed by a contract this tool cannot decode, is not KNOWN to,
- *  and "not known to" is not "safe" - the same posture as the interpreter and
- *  RPC pins. An incomplete scan is refused for the same reason: the overlap
- *  list is then a subset of the account, so an empty list proves nothing.
- *
- *  `not-restricting` is reported but does NOT block. Both rules are ours and
- *  both constrain the calls, and the conjunction remedy is offered; refusing
- *  there would also block the legitimate act of adding a separate capability,
- *  which OZ composes correctly as a union.
- *
- *  Returns a ToolError or null, matching `enforceInterpreterPin`. */
-export declare function enforceAuthorityScan(scan: AuthorityScanReport | undefined, allowOverlap: boolean | undefined): ToolError | null;
-/** The install response, plus what the cross-rule scan found. The scan is
- *  advisory data about the account, not part of the transaction, so it is
- *  additive: a caller that ignores it gets exactly the previous shape. */
-export type InstallPolicyResult = BuildInstallPolicyResult & {
-    authorityScan?: AuthorityScanReport;
-};
-/** What the cross-rule scan found, carried on the install response so the
- *  review surface can show it alongside the transaction being signed.
- *
- *  SCOPE, and it is narrow: this answers "can a signer OF THIS RULE reach the
- *  same calls through a different rule". A rule sharing no signer with this
- *  one cannot be reached by this rule's signers, so it is not a way around
- *  this policy; it is a different principal's authority, which no policy
- *  installed here was ever going to constrain. Other rules keep their own
- *  signers, and an account administrator can add signers or rules afterwards.
- *
- *  An empty `overlaps` is therefore NOT a statement that the account is safe,
- *  only that this rule's own signers gain no unconstrained path through the
- *  rules that exist right now. */
-export interface AuthorityScanReport {
-    /** False when the scan did not run. `reason` then says why, and the absence
-     *  of overlaps proves nothing. */
-    ran: boolean;
-    /** True when the caller passed `skipAuthorityScan`. Distinguishes a
-     *  deliberate skip from a scan that tried and failed: both carry
-     *  `ran: false`, but only the failure refuses the install. Recorded rather
-     *  than omitted so the response shows that no opinion was formed, instead
-     *  of looking like a version that never had the check. */
-    skipped?: boolean;
-    /** True when the account has more rules than the scan accounted for, so the
-     *  overlap list is a subset. */
-    incomplete?: boolean;
-    reason?: string;
-    overlaps: AuthorityOverlap[];
-}
-/** The merge response: one step's transaction plus what it will cost. */
-export interface MergePolicyResult {
-    unsignedXdr: string;
-    smartAccount: string;
-    sourceAccount: string;
-    step: 'detach' | 'reinstall';
-    call: {
-        contract: string;
-        fn: string;
-        ruleId: number;
-    };
-    authNonce: string;
-    authValidUntilLedger: number;
-    rootInvocationXdr: string;
-    /** sha256 of the merged predicate, so the caller can pin what step 2 will
-     *  install while they are still looking at step 1. */
-    mergedPredicateHash: string;
-    mergedPredicateBlobBase64: string;
-    warnings: string[];
-    followUp: string;
-}
-/** `merge_policy` body - the tightening remedy for a cross-rule overlap.
- *
- *  Replaces a rule's predicate with the conjunction of it and a new one. This
- *  is the action `install_policy` recommends when it reports an overlap
- *  between two rules our interpreter polices, and it is deliberately NOT
- *  something `install_policy` does on its own: it detaches a live policy, so
- *  the operator has to ask for it.
- *
- *  Two transactions in order. `add_policy` refuses a policy already on the
- *  rule, so the old attachment goes first, and the second transaction cannot
- *  be simulated until the first confirms. */
-export declare function runMergePolicy(raw: unknown): Promise<ToolResponse<MergePolicyResult>>;
+export declare function runInstallPolicy(raw: unknown): Promise<ToolResponse<BuildInstallPolicyResult>>;
 /** `revoke_policy` body - thin wrapper over `buildRevokePolicyXdr`.
  *  Emits an unsigned XDR for `account.remove_context_rule(ruleId)`; the
  *  smart account itself handles uninstalling each attached policy. Auth
@@ -162,30 +48,41 @@ export declare function runMergePolicy(raw: unknown): Promise<ToolResponse<Merge
  *  policy payload, so the interpreter pin is not re-checked here.
  *  Pin selection follows `input.network` (defaults to `testnet`). */
 export declare function runRevokePolicy(raw: unknown): Promise<ToolResponse<BuildRevokePolicyResult>>;
-/** `get_interpreter_info` body - thin wrapper over `getInterpreterInfo`.
- *  Returns the pinned deployment fingerprint + an optional live
- *  `grammar_version()` comparison. The audit field is deliberately
- *  OMITTED (phase-04's "audit #44" has no source of truth in the repo -
- *  fabricating it would be a lie on a security surface; the live
- *  mismatch check is worth MORE).
+/** `simulate_policy` body - evaluate a predicate against one recorded call.
  *
- *  Network-aware: `input.network` selects the interpreter address, the RPC
- *  and the wasm hash. The networks run different binaries - testnet carries
- *  the selector-leaf minimum and the signer-set cap, mainnet predates both -
- *  so the hash is read through
- *  `PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK`. UNAUDITED at the time of
- *  writing.
+ *  The evaluator is a second implementation of the on-chain semantics, and the
+ *  conformance harness asserts it agrees with the Rust interpreter case for
+ *  case. A verdict here is therefore a claim about what the contract would do,
+ *  not a guess. */
+export declare function runSimulatePolicy(raw: unknown): ToolResponse<{
+    permitted: boolean;
+    reason: string | null;
+    call: {
+        contract: string;
+        fn: string;
+        argCount: number;
+    };
+}>;
+/** `verify_policy` body - the permit case plus a generated deny case per
+ *  dimension.
  *
- *  Same RPC pin as install/revoke: when `verifyLive` triggers an outbound
- *  call, the auth-digest + the answer bind to whichever RPC answered, so
- *  a non-pinned `rpcUrl` would silently bind the caller to a host they
- *  picked. The pin is enforced here too, with the same `allowUnpinnedRpcUrl`
- *  opt-in as install/revoke. */
+ *  Two failure modes are being checked, and they are not the same thing. A
+ *  permit case that denies means the policy is too STRICT: it would refuse the
+ *  very transaction it was synthesised from. A deny case that permits means it
+ *  is too LOOSE: some mutation of that transaction still gets through. `ok` is
+ *  true only when neither holds. */
+export declare function runVerifyPolicy(raw: unknown): ToolResponse<{
+    ok: boolean;
+    permit: {
+        permitted: boolean;
+        reason: string | null;
+    };
+    denies: Array<{
+        dimension: string;
+        denied: boolean;
+        reason: string | null;
+    }>;
+    dimensionsCovered: number;
+}>;
 export declare function runGetInterpreterInfo(raw: unknown): Promise<ToolResponse<ReturnType<typeof getInterpreterInfo>>>;
-/** Build a canonical ToolError for a thrown exception caught by the tool
- *  envelope. The MCP SDK stringifies thrown objects as "[object Object]" by
- *  default, so we extract a string-friendly message and tag the original
- *  error in `details` for the agent to inspect. Exported as a test-only seam
- *  so the suite in run/index.test.ts can drive the envelope path without
- *  standing up a full recordTransaction pipeline. */
 export declare function caughtError(toolName: RunToolName, code: ErrorCode, e: unknown): ToolError;