@parmanasystems/core 1.71.12 → 1.71.18

package/README.md

@@ -20,6 +20,82 @@ npm install @parmanasystems/core
 
 ---
 
+## ESM / CJS note
+
+`@parmanasystems/core` bundles CJS dependencies. Do **not** set `"type": "module"` in `package.json` — it will break bundled transitive imports. Wrap all SDK calls in an `async` function instead of using top-level `await`:
+
+```typescript
+// ✅ Correct
+async function main() {
+  const result = await executeFromSignals(...);
+}
+main().catch(console.error);
+
+// ❌ Incorrect — top-level await fails in CJS mode
+const result = await executeFromSignals(...);
+```
+
+---
+
+## Policy files
+
+`executeFromSignals` reads policy rules from disk at:
+
+```
+./policies/{policyId}/{policyVersion}/policy.json
+```
+
+Create this directory structure **before** calling `executeFromSignals`. Example for `policyId: "trade-risk-approval"`, `policyVersion: "1.0.0"`:
+
+```
+policies/
+  trade-risk-approval/
+    1.0.0/
+      policy.json
+```
+
+Minimal `policy.json` with all required fields:
+
+```json
+{
+  "policyId": "trade-risk-approval",
+  "policyVersion": "1.0.0",
+  "schemaVersion": "1.0.0",
+  "signalsSchema": {
+    "amount_usd":   { "type": "integer" },
+    "risk_score":   { "type": "integer" },
+    "counterparty": { "type": "string" }
+  },
+  "rules": [
+    {
+      "id": "low-risk-approve",
+      "condition": {
+        "all": [
+          { "signal": "risk_score",  "less_than": 30 },
+          { "signal": "amount_usd",  "less_than": 500000 }
+        ]
+      },
+      "outcome": { "action": "approve", "requires_override": false, "reason": "low_risk_trade" }
+    },
+    {
+      "id": "catch-all-reject",
+      "condition": { "all": [] },
+      "outcome": { "action": "reject", "requires_override": true, "reason": "requires_review" }
+    }
+  ]
+}
+```
+
+| Field | Required | Description |
+|---|---|---|
+| `policyId` | ✅ | Must match the directory name under `policies/` |
+| `policyVersion` | ✅ | Must match the subdirectory name (e.g. `"1.0.0"`) |
+| `schemaVersion` | ✅ | Always `"1.0.0"` for the current schema |
+| `signalsSchema` | ✅ | Map of signal names to `{ "type": "integer" \| "boolean" \| "string" }` |
+| `rules` | ✅ | Ordered list — evaluated top-to-bottom, first match wins |
+
+---
+
 ## Usage
 
 ```typescript
@@ -33,38 +109,42 @@ import {
   getRuntimeManifest,
 } from "@parmanasystems/core";
 
-const { privateKey, publicKey } = crypto.generateKeyPairSync("ed25519", {
-  privateKeyEncoding: { type: "pkcs8", format: "pem" },
-  publicKeyEncoding:  { type: "spki",  format: "pem" },
-});
-
-const signer      = new LocalSigner(privateKey);
-const verifier    = new LocalVerifier(publicKey);
-const replayStore = new MemoryReplayStore();
-
-const attestation = await executeFromSignals(
-  {
-    policyId:      "trade-risk-approval",
-    policyVersion: "1.0.0",
-    signals: {
-      amount_usd:   450_000,
-      risk_score:   18,
-      counterparty: "acme-corp",
+async function main() {
+  const { privateKey, publicKey } = crypto.generateKeyPairSync("ed25519", {
+    privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    publicKeyEncoding:  { type: "spki",  format: "pem" },
+  });
+
+  const signer      = new LocalSigner(privateKey);
+  const verifier    = new LocalVerifier(publicKey);
+  const replayStore = new MemoryReplayStore();
+
+  const attestation = await executeFromSignals(
+    {
+      policyId:      "trade-risk-approval",
+      policyVersion: "1.0.0",
+      signals: {
+        amount_usd:   450_000,
+        risk_score:   18,
+        counterparty: "acme-corp",
+      },
     },
-  },
-  signer,
-  verifier,
-  replayStore
-);
-
-console.log(attestation.execution_state); // "completed"
-console.log(attestation.decision.action); // "approve"
-console.log(attestation.signature);       // Ed25519 over canonical attestation JSON
-
-// Independently verify — no runtime state required beyond the manifest
-const manifest = getRuntimeManifest();
-const result = verifyAttestation(attestation, verifier, manifest);
-console.log(result.valid); // true
+    signer,
+    verifier,
+    replayStore
+  );
+
+  console.log(attestation.execution_state); // "completed"
+  console.log(attestation.decision.action); // "approve"
+  console.log(attestation.signature);       // Ed25519 over canonical attestation JSON
+
+  // Independently verify — no runtime state required beyond the manifest
+  const manifest = getRuntimeManifest();
+  const result = verifyAttestation(attestation, verifier, manifest);
+  console.log(result.valid); // true
+}
+
+main().catch(console.error);
 ```
 
 ---

package/dist/index.js

@@ -10499,7 +10499,8 @@ import {
   evaluatePolicy,
   loadPolicy,
   canonicalizeForSigning,
-  validateSignalsStrict
+  validateSignalsStrict,
+  violate
 } from "@parmanasystems/execution";
 import crypto from "crypto";
 import {
@@ -10535,6 +10536,17 @@ async function executeFromSignals(input, signer, verifier, replayStore) {
       signals: input.signals
     })
   ).digest("hex");
+  const hasRun = await replayStore.hasExecuted(
+    execution_fingerprint
+  );
+  if (hasRun) {
+    violate(
+      "INV-013",
+      "replay",
+      `[INV-013@replay] Replay detected: execution_fingerprint ${execution_fingerprint} has already been consumed`,
+      execution_fingerprint
+    );
+  }
   await replayStore.markExecuted(
     execution_fingerprint
   );
@@ -10640,7 +10652,7 @@ import {
 import {
   INVARIANT_REGISTRY,
   InvariantViolation,
-  violate,
+  violate as violate2,
   hashInput
 } from "@parmanasystems/execution";
 
@@ -10877,6 +10889,6 @@ export {
   verifyRuntime,
   verifyRuntimeCompatibility,
   verifyRuntimeManifest,
-  violate
+  violate2 as violate
 };
 //# sourceMappingURL=index.js.map