@crediolabs/policy-synth 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,84 @@
+# @crediolabs/policy-synth
+
+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.
+
+The package is pure ESM, node-compatible, and has a single runtime dependency
+(`@stellar/stellar-sdk`). MIT-licensed.
+
+## Install
+
+```sh
+npm install @crediolabs/policy-synth
+```
+
+## Usage
+
+There are two front-ends, both co-equal:
+
+- **Recording** — decode a real transaction, then infer the minimal policy.
+- **Mandate** — a declarative spec that lowers deterministically (no inference).
+
+```ts
+import {
+  recordTransaction,
+  synthesizeFromRecording,
+  synthesizeFromMandate,
+  placeholderOzConfig,
+  type MandateSpec,
+} from '@crediolabs/policy-synth'
+
+const oz = placeholderOzConfig('mainnet')
+
+// --- Recording front-end -------------------------------------------------
+const recorded = await recordTransaction({ network: 'mainnet', hash: '<tx-hash>' })
+if (!recorded.ok) throw new Error(recorded.error.message)
+
+const inferred = synthesizeFromRecording(recorded.data, { network: 'mainnet' }, oz)
+if (inferred.ok) console.log(inferred.data)
+
+// --- Mandate front-end (deterministic) -----------------------------------
+const spec: MandateSpec = {
+  chain: 'stellar',
+  contract: 'CTOKEN',
+  method: 'transfer',
+  spendingLimit: { token: 'CTOKEN', limit: '5000000', windowSeconds: 2592000 },
+}
+const deterministic = synthesizeFromMandate(spec, oz)
+if (deterministic.ok) console.log(deterministic.data)
+```
+
+Every entry point returns a discriminated `ToolResponse<T>`:
+
+```ts
+type ToolResponse<T> = { ok: true; data: T } | { ok: false; error: ToolError }
+```
+
+`ToolError` carries a machine-readable `code`, a `message`, a `severity`, and a
+`retryable` flag, so callers (and agents) can branch without parsing prose.
+
+### Recording modes and the confidence gate
+
+- **On-chain** (`hash` set): fetched via the injected RPC fetcher (default: the
+  public Soroban RPC for the requested `network`). Pass your own `fetcher` to use
+  a custom endpoint or to test offline.
+- **Simulation / XDR** (`xdr` set): the envelope XDR is decoded directly.
+
+XDR/simulation mode has no raw on-chain events, so the recorder cannot run its
+events cross-check and lowers `parseConfidence`. It therefore **fails closed** at
+the default threshold; to accept a simulation-only recording, pass an explicit
+`confidenceOverride` that clears the gate.
+
+## Status
+
+The recorder, both synthesizer front-ends, and the OZ Accounts adapter (Path A)
+are implemented and unit-test covered. Install, on-chain verify, simulate, and the
+Rust interpreter (Path-B predicate enforcement) are later phases.
+
+## License
+
+MIT.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-synth",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",
@@ -12,7 +12,8 @@
       "bun": "./src/index.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",