@parmanasystems/execution 1.0.19

package/README.md

@@ -0,0 +1,314 @@
+# @parmanasystems/execution
+
+Deterministic runtime execution and governance attestation infrastructure for parmanasystems.
+
+[![npm](https://img.shields.io/npm/v/@parmanasystems/execution)](https://www.npmjs.com/package/@parmanasystems/execution)
+
+## 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
+
+```bash
+npm install @parmanasystems/execution
+```
+
+## Quick start
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+function resolveOverride(
+  executionId: string,
+  signer: Signer,
+  replayStore: AsyncReplayStore & { get?; del? }
+): Promise<{ success: boolean; signature: string }>
+```
+
+### evaluatePolicy
+
+Pure, deterministic policy rule evaluation.
+
+```typescript
+function evaluatePolicy(
+  policy: PolicyDefinition,
+  signals: Record<string, unknown>
+): DecisionResult
+```
+
+### issueToken
+
+```typescript
+function issueToken(input: {
+  execution_id: string;
+  policy_id: string;
+  decision_payload: DecisionOutcome;
+  schema_version: string;
+  runtime_version: string;
+}): ExecutionToken
+```
+
+### getRuntimeManifest
+
+```typescript
+function getRuntimeManifest(): RuntimeManifest
+```
+
+## Types
+
+### ExecutionAttestation
+
+```typescript
+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
+
+```typescript
+interface ExecutionToken {
+  execution_id: string;
+  policy_id: string;
+  decision_payload: DecisionOutcome;
+  schema_version: string;
+  runtime_version: string;
+}
+```
+
+### ExecutionContext
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+interface Signer   { sign(payload: string): string; }
+interface Verifier { verify(payload: string, signature: string): boolean; }
+```
+
+### InvariantViolation
+
+```typescript
+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
+
+```typescript
+const signer = new LocalSigner(privateKeyPem);
+// privateKeyPem: PEM-encoded Ed25519 private key
+```
+
+### LocalVerifier
+
+```typescript
+const verifier = new LocalVerifier(publicKeyPem);
+```
+
+### AwsKmsSigner
+
+```typescript
+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.
+
+```typescript
+const store = new MemoryReplayStore();
+```
+
+### RedisReplayStore
+
+Uses Redis `SET NX` for atomic distributed replay protection.
+
+```typescript
+const store = new RedisReplayStore(redisClient);
+```
+
+## Invariant registry
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+import {
+  stageCanonicalizeSignals,
+  stageValidateSignals,
+  stageVerify,
+  stageCheckReplay,
+  stageExecute,
+  stageSign,
+} from "@parmanasystems/execution";
+```
+
+## License
+
+Apache-2.0