Package Exports

@parmanasystems/execution

Readme

@parmanasystems/execution

Deterministic runtime execution and governance attestation infrastructure for parmanasystems.

Overview

@parmanasystems/execution is the core execution engine. It handles:

Execution tokens — single-use authorization tokens binding a decision to specific inputs
Deterministic execution — identical inputs always produce identical signed results
Replay protection — each execution_id is consumed exactly once
Cryptographic attestation — results are signed at execution time and independently verifiable
Invariant enforcement — 60+ registered invariants with structured violation reports
Audit trail — hash-chained JSONL log at ./runtime-audit/executions.jsonl

Installation

npm install @parmanasystems/execution

Quick start

import {
  executeFromSignals,
  LocalSigner,
  LocalVerifier,
  RedisReplayStore,
} from "@parmanasystems/execution";
import { createClient } from "redis";

const redis = createClient();
await redis.connect();

const privateKeyPem = process.env.Parmana_PRIVATE_KEY!;
const publicKeyPem  = process.env.Parmana_PUBLIC_KEY!;

const signer   = new LocalSigner(privateKeyPem);
const verifier = new LocalVerifier(publicKeyPem);
const store    = new RedisReplayStore(redis);

const result = await executeFromSignals(
  {
    policyId:      "claims-approval",
    policyVersion: "v1",
    signals: {
      insurance_active: true,
      risk_score: 42,
      claim_amount: 50000,
    },
  },
  signer,
  verifier,
  store
);

if (result.status === "success") {
  console.log(result.execution_state);  // "completed" | "blocked" | "pending_override"
  console.log(result.signature);        // base64 Ed25519 signature
}

API

executeFromSignals

The primary high-level entry point. Loads the policy from ./policies/{policyId}/{policyVersion}/policy.json, validates signals, evaluates rules, issues a token, and runs the full pipeline.

function executeFromSignals(
  input: {
    policyId: string;
    policyVersion: string;
    signals: Record<string, unknown>;
    metadata?: Record<string, unknown>;
  },
  signer: Signer,
  verifier: Verifier,
  replayStore: AsyncReplayStore & { get?; set?; del? }
): Promise<ExecuteFromSignalsResult>

Returns { status: "success", execution_id, decision, execution_state, signature? } or { status: "pending_override", execution_id, ... } or { status: "error", error }.

executeDecision

Lower-level synchronous execution. Takes an already-constructed ExecutionContext and runs verify → replay → execute → sign stages.

function executeDecision(
  context: ExecutionContext,
  replayStore: ReplayStore
): ExecutionAttestation

executeSimple

Convenience wrapper for the server route. Issues a token from { policyId, policyVersion, decisionType, signalsHash } without loading a policy file.

function executeSimple(
  input: { policyId: string; policyVersion: string; decisionType: string; signalsHash: string },
  signer: Signer,
  verifier: Verifier,
  store?: ReplayStore
): ExecutionAttestation

resolveOverride

Resolves a pending_override execution stored in Redis.

function resolveOverride(
  executionId: string,
  signer: Signer,
  replayStore: AsyncReplayStore & { get?; del? }
): Promise<{ success: boolean; signature: string }>

evaluatePolicy

Pure, deterministic policy rule evaluation.

function evaluatePolicy(
  policy: PolicyDefinition,
  signals: Record<string, unknown>
): DecisionResult

issueToken

function issueToken(input: {
  execution_id: string;
  policy_id: string;
  decision_payload: DecisionOutcome;
  schema_version: string;
  runtime_version: string;
}): ExecutionToken

getRuntimeManifest

function getRuntimeManifest(): RuntimeManifest

Types

ExecutionAttestation

interface ExecutionAttestation {
  execution_id: string;
  decision: {
    action: "approve" | "reject";
    requires_override: boolean;
    reason?: string;
  };
  execution_state: "completed" | "blocked" | "pending_override";
  signature: string;     // base64 Ed25519
  runtime_hash: string;  // SHA-256 of runtime manifest
}

ExecutionToken

interface ExecutionToken {
  execution_id: string;
  policy_id: string;
  decision_payload: DecisionOutcome;
  schema_version: string;
  runtime_version: string;
}

ExecutionContext

interface ExecutionContext {
  token: ExecutionToken;
  token_signature: string;
  signer: Signer;
  verifier: Verifier;
  runtime_manifest: RuntimeManifest;
  runtime_requirements: RuntimeRequirements;
  governed_time?: string;  // ISO 8601 — injected deterministic timestamp
}

RuntimeManifest

interface RuntimeManifest {
  runtime_version: "1.0.0";
  runtime_hash: string;
  supported_schema_versions: readonly ["1.0.0"];
  capabilities: readonly [
    "deterministic-evaluation",
    "attestation-signing",
    "replay-protection",
    "bundle-verification",
  ];
}

Signer / Verifier

interface Signer   { sign(payload: string): string; }
interface Verifier { verify(payload: string, signature: string): boolean; }

InvariantViolation

class InvariantViolation extends Error {
  readonly report: ViolationReport;
}

interface ViolationReport {
  invariant_id: string;   // e.g., "INV-013"
  boundary: string;       // e.g., "replay"
  reason: string;
  input_hash: string;     // SHA-256 of offending input
  timestamp_seq: number;  // monotonic counter
}

Signers

LocalSigner

const signer = new LocalSigner(privateKeyPem);
// privateKeyPem: PEM-encoded Ed25519 private key

LocalVerifier

const verifier = new LocalVerifier(publicKeyPem);

AwsKmsSigner

import { AwsKmsSigner } from "@parmanasystems/execution";
const signer = new AwsKmsSigner({ keyId: "arn:aws:kms:...", region: "us-east-1" });

Replay stores

MemoryReplayStore

In-process Set. Use for testing and single-process deployments.

const store = new MemoryReplayStore();

RedisReplayStore

Uses Redis SET NX for atomic distributed replay protection.

const store = new RedisReplayStore(redisClient);

Invariant registry

import { INVARIANT_REGISTRY, violate, InvariantViolation } from "@parmanasystems/execution";

// Access registry
console.log(INVARIANT_REGISTRY["INV-013"].description);

// Throw a violation
violate("INV-013", "replay", "execution_id already consumed", executionId);

All new invariant IDs must be registered in src/invariant-registry.ts. The CI gate enforces this.

Audit

import { appendAuditRecord, verifyAudit } from "@parmanasystems/execution";

await appendAuditRecord(attestation);  // appends to ./runtime-audit/executions.jsonl
await verifyAudit("./runtime-audit/executions.jsonl");  // verifies hash chain

Pipeline stages

import {
  stageCanonicalizeSignals,
  stageValidateSignals,
  stageVerify,
  stageCheckReplay,
  stageExecute,
  stageSign,
} from "@parmanasystems/execution";

License

Apache-2.0