@parmanasystems/core 1.69.0 → 1.71.2

package/README.md

@@ -1,407 +1,155 @@
 # @parmanasystems/core
 
-Deterministic governance SDK and evaluation foundation for the Parmana Systems ecosystem.
+Unified public SDK for Parmana Systems deterministic governance.
 
 [![npm](https://img.shields.io/npm/v/@parmanasystems/core)](https://www.npmjs.com/package/@parmanasystems/core)
 
 ---
 
-# Overview
+## Overview
 
-`@parmanasystems/core` is the primary integration package for the Parmana deterministic governance ecosystem.
-
-It provides a unified governance SDK combining:
-
-- 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.
+`@parmanasystems/core` is the single entry point for most Parmana Systems integrations. It re-exports the complete public API from the underlying packages — execution, runtime orchestration, portable verification, governance lifecycle, and cryptographic primitives — under one install.
 
 ---
 
-# 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.
+## Install
 
-When to use this package
-
-Use this package when:
-
-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
-
-Do NOT use this package when:
+```bash
+npm install @parmanasystems/core
+```
 
-requiring only low-level runtime primitives
-implementing only cryptographic infrastructure
-building custom governance internals
+---
 
-In those cases use lower-level packages directly:
+## Usage
 
-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
+```typescript
+import crypto from "crypto";
 import {
   executeFromSignals,
-  verifyAttestation,
   LocalSigner,
   LocalVerifier,
+  MemoryReplayStore,
+  verifyAttestation,
   getRuntimeManifest,
-  RedisReplayStore,
 } from "@parmanasystems/core";
 
-import { createClient } from "redis";
-
-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();
-
-const result =
-  await executeFromSignals(
-    {
-      policyId:
-        "claims-approval",
-
-      policyVersion:
-        "v1",
-
-      signals: {
-        insurance_active: true,
-        risk_score: 42,
-      },
+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,
-    store
-  );
-
-if (
-  result.status === "success"
-  &&
-  result.signature
-) {
-
-  const verification =
-    verifyAttestation(
-      {
-        execution_id:
-          result.execution_id,
-
-        ...result
-      },
-      verifier,
-      manifest
-    );
-
-  console.log(
-    verification.valid
-  );
-}
-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.
+  },
+  signer,
+  verifier,
+  replayStore
+);
 
-signals_hash
+console.log(attestation.execution_state); // "completed"
+console.log(attestation.decision.action); // "approve"
+console.log(attestation.signature);       // Ed25519 over canonical attestation JSON
 
-Canonicalized governed input proof.
+// Independently verify — no runtime state required beyond the manifest
+const manifest = getRuntimeManifest();
+const result = verifyAttestation(attestation, verifier, manifest);
+console.log(result.valid); // true
+```
 
-Used for:
+---
 
-deterministic reconstruction
-execution verification
-audit integrity
-replay-safe governance
-Example Policy
-{
-  "policyId": "loan-approval",
+## Exports
+
+### Runtime orchestration
+
+| Export | Description |
+|---|---|
+| `executeFromSignals` | Primary execution entry point — evaluates a policy, signs the result, returns `ExecutionAttestation` |
+| `MemoryReplayStore` | In-process replay store for development and testing |
+| `RedisReplayStore` | Distributed replay store for production use |
+
+### Core execution primitives
+
+| Export | Description |
+|---|---|
+| `executeDecision` | Deterministic execution pipeline (verify → execute → sign) |
+| `issueToken` | Issue a signed `ExecutionToken` |
+| `verifyExecutionToken` | Verify an `ExecutionToken` signature |
+| `getRuntimeManifest` | Return the current `RuntimeManifest` |
+| `signRuntimeManifest` | Sign a `RuntimeManifest` |
+| `verifyRuntimeManifest` | Verify a signed `RuntimeManifest` |
+| `LocalSigner` | Ed25519 signer backed by a local PEM private key |
+| `LocalVerifier` | Ed25519 verifier backed by a local PEM public key |
+
+### Portable verification
+
+| Export | Description |
+|---|---|
+| `verifyAttestation` | Verify an `ExecutionAttestation` signature and runtime binding |
+| `verifyBundle` | Verify a governance bundle's content-addressed integrity |
+| `verifyRuntime` | Verify runtime state against a manifest |
+| `verifyRuntimeCompatibility` | Check runtime version compatibility with a policy's requirements |
+| `verifyExecutionRequirements` | Verify execution requirements before running |
+
+### Governance lifecycle
+
+| Export | Description |
+|---|---|
+| `createPolicy` | Scaffold a new policy directory |
+| `upgradePolicy` | Create a new version of an existing policy |
+| `validatePolicy` | Validate a policy definition against the governance schema |
+| `generateBundle` | Package a policy directory into a signed bundle |
+| `signBundle` | Sign a bundle directory with a `Signer` |
+
+### Override authority
+
+| Export | Description |
+|---|---|
+| `approveOverride` | Approve a pending override decision |
+
+### Invariant registry
+
+| Export | Description |
+|---|---|
+| `INVARIANT_REGISTRY` | Registry of all declared deterministic invariants |
+| `InvariantViolation` | Error subclass for invariant violations |
+| `violate` | Throw an `InvariantViolation` |
+| `hashInput` | SHA-256 hash of canonical input |
+
+### Key types
+
+| Export | Description |
+|---|---|
+| `ExecutionAttestation` | Signed record of a completed governed execution |
+| `ExecutionContext` | Full input context for `executeDecision` |
+| `ExecutionToken` | Signed artifact binding a decision to its execution identity |
+| `RuntimeManifest` | Runtime binary state snapshot |
+| `Signer` | Signing interface |
+| `Verifier` | Verification interface |
+| `ReplayStore` | Replay protection interface |
+| `DecisionResult` | Resolved policy decision |
+| `DecisionOutcome` | Action, override flag, and optional reason |
 
-  "version": "v1",
+---
 
-  "signalsSchema": {
+## Documentation
 
-    "risk_score": {
-      "type": "number"
-    }
-  },
+Full docs: [parmanasystems.mintlify.app](https://parmanasystems.mintlify.app)
+Package page: [parmanasystems.mintlify.app/packages/core](https://parmanasystems.mintlify.app/packages/core)
 
-  "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";
+## License
 
-Provides deterministic canonical serialization.
-
-Types
-import type {
-  ExecutionContext,
-  ExecutionAttestation,
-  ExecutionToken,
-  DecisionResult,
-  RuntimeManifest,
-  Signer,
-  AsyncSigner,
-  Verifier,
-  ReplayStore,
-  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:
-
-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parmanasystems/core",
-  "version": "1.69.0",
+  "version": "1.71.2",
   "private": false,
   "type": "module",
   "scripts": {
@@ -18,12 +18,12 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@parmanasystems/audit-db": "^1.69.0",
-    "@parmanasystems/bundle": "^1.69.0",
-    "@parmanasystems/crypto": "^1.69.0",
-    "@parmanasystems/execution": "^1.69.0",
-    "@parmanasystems/governance": "^1.69.0",
-    "@parmanasystems/verifier": "^1.69.0"
+    "@parmanasystems/audit-db": "^1.71.2",
+    "@parmanasystems/bundle": "^1.71.2",
+    "@parmanasystems/crypto": "^1.71.2",
+    "@parmanasystems/execution": "^1.71.2",
+    "@parmanasystems/governance": "^1.71.2",
+    "@parmanasystems/verifier": "^1.71.2"
   },
   "description": "Public orchestration and SDK surface for parmanasystems deterministic governance infrastructure.",
   "license": "Apache-2.0",
@@ -31,7 +31,7 @@
     "type": "git",
     "url": "https://github.com/pavancharak/parmanasystems-core.git"
   },
-  "homepage": "https://github.com/pavancharak/parmanasystems-core",
+  "homepage": "https://parmanasystems.mintlify.app",
   "bugs": {
     "url": "https://github.com/pavancharak/parmanasystems-core/issues"
   },