@parmanasystems/core 1.56.0 → 1.65.0

package/README.md

@@ -1,24 +1,87 @@
 # @parmanasystems/core
 
-Portable runtime SDK for the parmanasystems deterministic governance ecosystem.
+Deterministic governance SDK and evaluation foundation for the Parmana Systems ecosystem.
 
 [![npm](https://img.shields.io/npm/v/@parmanasystems/core)](https://www.npmjs.com/package/@parmanasystems/core)
 
-## Overview
+---
 
-`@parmanasystems/core` is the recommended single-package install for most applications. It re-exports the full governance lifecycle, execution runtime, and verification layer, and adds the deterministic validator and canonical JSON utilities.
+# Overview
 
-Install this instead of separately installing `@parmanasystems/execution`, `@parmanasystems/governance`, and `@parmanasystems/verifier`.
+`@parmanasystems/core` is the primary integration package for the Parmana deterministic governance ecosystem.
 
-## Installation
+It provides a unified governance SDK combining:
 
-```bash
-npm install @parmanasystems/core
-```
+- deterministic policy evaluation
+- governed execution
+- independent verification
+- replay-safe execution infrastructure
+- runtime provenance validation
+- canonical governance utilities
+
+For most applications, this is the recommended entry point into the Parmana ecosystem.
+
+---
+
+# Mental Model
+
+```txt id="o5f0r2"
+Signals
+  ↓
+Deterministic Evaluation
+  ↓
+Governed Decision
+  ↓
+Governed Execution
+  ↓
+Execution Attestation
+  ↓
+Independent Verification
+
+The core package unifies the full deterministic governance lifecycle.
+
+What this package does
+
+@parmanasystems/core combines:
+
+Capability	Description
+deterministic evaluation	governed decision evaluation
+governed execution	replay-safe enforcement
+verification	independent proof validation
+governance utilities	canonical governance infrastructure
+runtime lineage	provenance validation
+replay protection	deterministic execution safety
+
+This package acts as the unified developer-facing governance SDK.
+
+When to use this package
+
+Use this package when:
 
-## Quick start
+integrating deterministic governance into applications
+building governed AI systems
+implementing governed execution workflows
+deploying deterministic execution pipelines
+verifying execution attestations
+building replay-safe governance infrastructure
+adopting Parmana without managing multiple packages individually
 
-```typescript
+Do NOT use this package when:
+
+requiring only low-level runtime primitives
+implementing only cryptographic infrastructure
+building custom governance internals
+
+In those cases use lower-level packages directly:
+
+Package	Responsibility
+@parmanasystems/execution	governed execution runtime
+@parmanasystems/verifier	independent verification
+@parmanasystems/governance	governance lifecycle
+@parmanasystems/crypto	signing infrastructure
+Installation
+npm install @parmanasystems/core
+Quick Start
 import {
   executeFromSignals,
   verifyAttestation,
@@ -27,94 +90,268 @@ import {
   getRuntimeManifest,
   RedisReplayStore,
 } from "@parmanasystems/core";
+
 import { createClient } from "redis";
 
-const redis    = createClient();
+const redis =
+  createClient();
+
 await redis.connect();
 
-const signer   = new LocalSigner(process.env.Parmana_PRIVATE_KEY!);
-const verifier = new LocalVerifier(process.env.Parmana_PUBLIC_KEY!);
-const store    = new RedisReplayStore(redis);
-const manifest = getRuntimeManifest();
-
-// Execute a governance decision
-const result = await executeFromSignals(
-  {
-    policyId:      "claims-approval",
-    policyVersion: "v1",
-    signals: { insurance_active: true, risk_score: 42 },
-  },
-  signer,
-  verifier,
-  store
-);
-
-if (result.status === "success" && result.signature) {
-  // Independently verify
-  const verification = verifyAttestation(
-    { execution_id: result.execution_id, ...result },
+const signer =
+  new LocalSigner(
+    process.env.Parmana_PRIVATE_KEY!
+  );
+
+const verifier =
+  new LocalVerifier(
+    process.env.Parmana_PUBLIC_KEY!
+  );
+
+const store =
+  new RedisReplayStore(
+    redis
+  );
+
+const manifest =
+  getRuntimeManifest();
+
+const result =
+  await executeFromSignals(
+    {
+      policyId:
+        "claims-approval",
+
+      policyVersion:
+        "v1",
+
+      signals: {
+        insurance_active: true,
+        risk_score: 42,
+      },
+    },
+    signer,
     verifier,
-    manifest
+    store
+  );
+
+if (
+  result.status === "success"
+  &&
+  result.signature
+) {
+
+  const verification =
+    verifyAttestation(
+      {
+        execution_id:
+          result.execution_id,
+
+        ...result
+      },
+      verifier,
+      manifest
+    );
+
+  console.log(
+    verification.valid
   );
-  console.log(verification.valid);  // true
 }
-```
-
-## Exports
-
-### Governance lifecycle (from `@parmanasystems/governance`)
-
-| Export | Description |
-|---|---|
-| `createPolicy` | Scaffold a new policy directory |
-| `upgradePolicy` | Create an upgraded policy version |
-| `validatePolicy` | Validate a policy structure |
-| `generateBundle` | Generate a content-addressed policy bundle |
-| `definePolicy` | Build a PolicyDefinition in memory |
-
-### Deterministic execution (from `@parmanasystems/execution`)
-
-| Export | Description |
-|---|---|
-| `executeFromSignals` | Full pipeline: load policy → evaluate → sign |
-| `executeDecision` | Lower-level: token → verify → replay → sign |
-| `executeSimple` | Token-based execution without policy file |
-| `resolveOverride` | Complete a pending_override execution |
-| `evaluatePolicy` | Pure policy rule evaluation |
-| `issueToken` | Issue a single-use execution token |
-| `signExecutionToken` | Sign a token |
-| `verifyExecutionToken` | Verify a token signature |
-| `getRuntimeManifest` | Return the active runtime manifest |
-| `signRuntimeManifest` | Sign a runtime manifest |
-| `verifyRuntimeManifest` | Verify a runtime manifest signature |
-| `LocalSigner` | Ed25519 signer (Node.js crypto) |
-| `LocalVerifier` | Ed25519 verifier (Node.js crypto) |
-| `MemoryReplayStore` | In-process replay protection |
-| `RedisReplayStore` | Distributed Redis replay protection |
-| `INVARIANT_REGISTRY` | All 60+ registered invariants |
-| `InvariantViolation` | Invariant violation error class |
-| `violate` | Throw a structured invariant violation |
-
-### Portable verification (from `@parmanasystems/verifier`)
-
-| Export | Description |
-|---|---|
-| `verifyAttestation` | Four-check attestation verification |
-| `verifyBundle` | Bundle signature and hash verification |
-| `verifyRuntime` | Runtime manifest comparison |
-| `verifyRuntimeCompatibility` | Runtime requirements check |
-| `verifyExecutionRequirements` | Execution requirements check |
-
-### Canonical utilities (from `@parmanasystems/bundle`)
-
-```typescript
-import { canonicalize } from "@parmanasystems/core";
-// Deterministic JSON serialization (sorted keys, stable bytes)
-```
-
-### Types
-
-```typescript
+Core Concepts
+Deterministic Evaluation
+
+Governance evaluation is deterministic.
+
+The runtime guarantees:
+
+same signals + same policy → same governed outcome
+
+Evaluation does not depend on:
+
+randomness
+mutable runtime state
+probabilistic execution
+timestamps
+Signals vs Rules vs Execution
+
+Parmana separates:
+
+Component	Responsibility
+signals	governed facts and inputs
+rules	deterministic governance logic
+execution	governed enforcement
+
+This separation improves:
+
+auditability
+reproducibility
+governance clarity
+execution trust boundaries
+signalsSchema
+
+Policies define governed signal structure explicitly.
+
+Example:
+
+{
+  "signalsSchema": {
+    "risk_score": {
+      "type": "number"
+    }
+  }
+}
+
+Signals are:
+
+typed
+deterministic
+explicitly governed
+schema-validated
+Governed Decisions
+
+The evaluator produces governed outcomes:
+
+{
+  "action": "approve",
+  "requires_override": false
+}
+
+Possible outcomes include:
+
+Outcome	Meaning
+approve	execution allowed
+reject	execution denied
+requires_override	human escalation required
+
+The evaluator determines governance outcomes.
+
+Execution authority is enforced separately.
+
+execution_id
+
+Operational execution lineage identifier.
+
+Used for:
+
+audit tracking
+governance event identity
+operational lineage
+execution_fingerprint
+
+Deterministic replay identity.
+
+Replay protection operates on execution fingerprints.
+
+Identical governed inputs produce identical execution fingerprints.
+
+signals_hash
+
+Canonicalized governed input proof.
+
+Used for:
+
+deterministic reconstruction
+execution verification
+audit integrity
+replay-safe governance
+Example Policy
+{
+  "policyId": "loan-approval",
+
+  "version": "v1",
+
+  "signalsSchema": {
+
+    "risk_score": {
+      "type": "number"
+    }
+  },
+
+  "rules": [
+
+    {
+      "id": "approve-low-risk",
+
+      "condition": {
+        "all": [
+          {
+            "signal": "risk_score",
+            "less_than": 0.25
+          }
+        ]
+      },
+
+      "outcome": {
+        "action": "approve",
+        "requires_override": false
+      }
+    }
+  ]
+}
+Governance Lifecycle
+Signals
+  ↓
+Validation
+  ↓
+Deterministic Evaluation
+  ↓
+Governed Decision
+  ↓
+Execution Token
+  ↓
+Governed Execution
+  ↓
+Execution Attestation
+  ↓
+Independent Verification
+Major Exports
+Governance Lifecycle
+
+From @parmanasystems/governance
+
+Export	Description
+createPolicy	scaffold governance policy
+upgradePolicy	create new immutable policy version
+validatePolicy	validate governance policy
+generateBundle	generate governance bundle
+definePolicy	define policy in memory
+Deterministic Execution
+
+From @parmanasystems/execution
+
+Export	Description
+executeFromSignals	full governed execution pipeline
+executeDecision	low-level execution pipeline
+executeSimple	simplified token execution
+resolveOverride	resolve override workflow
+evaluatePolicy	deterministic policy evaluation
+issueToken	issue execution token
+getRuntimeManifest	active runtime lineage
+LocalSigner	local Ed25519 signer
+LocalVerifier	local Ed25519 verifier
+MemoryReplayStore	in-memory replay protection
+RedisReplayStore	distributed replay protection
+Independent Verification
+
+From @parmanasystems/verifier
+
+Export	Description
+verifyAttestation	deterministic attestation verification
+verifyBundle	governance bundle verification
+verifyRuntime	runtime lineage verification
+verifyRuntimeCompatibility	runtime compatibility validation
+verifyExecutionRequirements	execution requirement validation
+Canonical Utilities
+
+From @parmanasystems/bundle
+
+import {
+  canonicalize
+} from "@parmanasystems/core";
+
+Provides deterministic canonical serialization.
+
+Types
 import type {
   ExecutionContext,
   ExecutionAttestation,
@@ -128,8 +365,43 @@ import type {
   AsyncReplayStore,
   ViolationReport,
 } from "@parmanasystems/core";
-```
+Recommended Architecture
+Application
+    ↓
+@parmanasystems/core
+    ↓
+Deterministic Governance
+    ↓
+Execution Attestation
+    ↓
+Independent Verification
+
+For most applications, @parmanasystems/core is the recommended integration surface.
+
+Security Model
+
+The core governance SDK enforces:
+
+deterministic evaluation
+fail-closed governance
+replay-safe execution
+immutable attestations
+runtime provenance validation
+independent verification
+governed execution boundaries
+canonical deterministic serialization
+
+The system is designed so that:
 
-## License
+AI may recommend actions.
+Deterministic governance controls execution authority.
+Relationship to Other Parmana Packages
+Package	Responsibility
+@parmanasystems/core	unified governance SDK
+@parmanasystems/execution	governed execution runtime
+@parmanasystems/verifier	independent verification
+@parmanasystems/server	deployable runtime
+@parmanasystems/sdk-client	HTTP integration
+License
 
-Apache-2.0
+Apache-2.0

package/dist/index.d.ts

@@ -1,12 +1,13 @@
 export { RuntimeRequirements, createPolicy, generateBundle, upgradePolicy, validatePolicy } from '@parmanasystems/governance';
 export { signBundle } from '@parmanasystems/crypto';
-export { ExecutionAttestation, ExecutionContext, ExecutionToken, INVARIANT_REGISTRY, InvariantBoundary, InvariantEntry, InvariantId, InvariantViolation, LocalSigner, LocalVerifier, MemoryReplayStore, ReplayStore, RuntimeManifest, Signer, Verifier, ViolationReport, executeDecision, executeFromSignals, getRuntimeManifest, hashInput, issueToken, signRuntimeManifest, verifyExecutionToken, verifyRuntimeManifest, violate } from '@parmanasystems/execution';
+export { ExecutionAttestation, ExecutionContext, ExecutionToken, INVARIANT_REGISTRY, InvariantBoundary, InvariantEntry, InvariantId, InvariantViolation, LocalSigner, LocalVerifier, ReplayStore, RuntimeManifest, Signer, Verifier, ViolationReport, executeDecision, getRuntimeManifest, hashInput, issueToken, signRuntimeManifest, verifyExecutionToken, verifyRuntimeManifest, violate } from '@parmanasystems/execution';
+export { MemoryReplayStore, RedisReplayStore, executeFromSignals } from '@parmanasystems/execution-runtime';
 export { verifyAttestation, verifyBundle, verifyExecutionRequirements, verifyRuntime, verifyRuntimeCompatibility } from '@parmanasystems/verifier';
 export { DecisionOutcome, DecisionResult } from '@parmanasystems/contracts';
 import { AuditOverride } from '@parmanasystems/audit-db';
 
 interface ApproveOverrideInput {
-    execution_id: string;
+    executionId: string;
     approved_by: string;
     approver_role: string;
     reason: string;