How It Works

The Parmana Systems execution pipeline from governed signals to signed attestation

Overview

Every call to executeFromSignals passes through a six-stage deterministic pipeline. Each stage either succeeds or throws a typed invariant violation — there is no partial or ambiguous outcome.

Governed Signals
      ↓
  Canonicalize
      ↓
    Validate
      ↓
    Evaluate
      ↓
 Replay Check
      ↓
  Issue Token
      ↓
    Execute
      ↓
      Sign
      ↓
ExecutionAttestation

---

Pipeline stages

1. Canonicalize

   Input signals are recursively sorted by key and serialized to a canonical JSON string. This guarantees that { b: 2, a: 1 } and { a: 1, b: 2 } produce identical hashes.

   A SHA-256 execution_fingerprint is derived from the canonical form of (policyId, policyVersion, signals). This fingerprint is the stable identity of this logical decision — if you replay the exact same inputs against the exact same policy version, you always get the same fingerprint.

   // Conceptually:
   const execution_fingerprint = sha256(
     JSON.stringify({ policyId, policyVersion, signals })
   );
   
2. Validate

   The signal values are validated against the policy’s signalsSchema. Each signal has a declared type (boolean, integer, string). A missing or wrong-type signal throws before any evaluation occurs.

   "signalsSchema": {
     "risk_score":   { "type": "integer" },
     "vip_customer": { "type": "boolean" }
   }
   

   This schema is part of the policy definition and is version-pinned — it cannot silently change.

3. Evaluate

   Policy rules are evaluated in order. The first rule whose condition matches the signals wins. Conditions support:

   • equals — exact value match
   • greater_than — numeric comparison
   • less_than — numeric comparison
   • all — logical AND of sub-conditions (can be empty as a catch-all)

   A well-formed policy always ends with a catch-all rule ("all": []) to ensure every input resolves to a decision.

   {
     "id": "high-risk-reject",
     "condition": { "signal": "risk_score", "greater_than": 80 },
     "outcome": { "action": "reject", "requires_override": false, "reason": "risk_score_exceeded_threshold" }
   }
   
4. Replay Check

   The execution_fingerprint is submitted to the ReplayStore. If it has been seen before, execution is rejected with a replay violation. This ensures a given logical decision cannot execute twice — protecting against double-spend, double-approval, and replay attacks.

   • MemoryReplayStore — in-process, suitable for tests
   • RedisReplayStore — distributed, suitable for multi-instance production deployments
5. Issue Token

   A signed ExecutionToken is created, binding the executionId, policyId, policyVersion, schemaVersion, runtimeVersion, decision_payload, and signalsHash. The token is signed with the Signer before execution proceeds.

   The token is the cryptographic bridge between the governance decision and the execution attestation.

6. Execute and Sign

   The token signature is verified. The decision payload is enforced. An execution_state is derived:

   Decision	requires_override	execution_state
   approve	false	completed
   reject	false	blocked
   reject or approve	true	pending_override

   The final ExecutionAttestation is assembled and signed. The signature covers the canonical form of all attestation fields — any modification to any field after signing is detectable.

---

Key properties

Determinism — Given identical (policyId, policyVersion, signals), the pipeline produces an identical execution_fingerprint and identical decision. The runtime has no access to wall-clock time, random state, or external calls during evaluation.

Portability — The attestation signature can be verified by any party with the public key. Verification does not require access to the runtime, the replay store, or any internal state.

Versioning — The runtimeVersion and runtimeHash are embedded in every attestation. An attestation produced by a different runtime version will not verify against an expected runtime hash.

Invariant enforcement — Violations throw InvariantViolation errors with a typed ViolationReport. These are not soft warnings — they are hard stops.