@parmanasystems/execution

The deterministic execution core. Given a signed ExecutionToken and a configured ExecutionContext, executeDecision runs three stages synchronously: verify the token signature against the runtime manifest, enforce the decision (approve/reject/pending-override), and sign the result into an ExecutionAttestation. The function is stateless and time-independent — the same inputs always produce a structurally identical attestation.

This package also owns policy evaluation (evaluatePolicy), token issuance (issueToken), signal validation, the replay store interface, and the full error code registry.

Public API

Execution

/**
 * Three-stage deterministic execution:
 *   Stage 1 — verify token signature and runtime compatibility
 *   Stage 2 — enforce decision (approve / reject / pending_override)
 *   Stage 3 — sign the ExecutionAttestation with context.signer
 *
 * Does NOT do replay protection — callers (executeFromSignals) must guard.
 */
async function executeDecision(context: ExecutionContext): Promise<ExecutionAttestation>

/**
 * Confirm that a real-world executed action matches its governance authorization.
 * Returns an ExecutionIntegrityProof signed by context.signer.
 */
async function confirmExecution(options: {
  attestation: ExecutionAttestation;
  executedAction: ExecutedAction;
  signer: Signer;
  verifier: Verifier;
  publicKey: string;
  timeWindowSeconds?: number;
}): Promise<ExecutionIntegrityProof>

Policy evaluation

/**
 * Evaluate a compiled policy against a signal map.
 * Returns DecisionResult with status "decided" and the matching rule's outcome.
 * Throws [SYS-006] if no rule matches (fail-closed — no silent pass).
 */
function evaluatePolicy(
  policy: CompiledPolicy,
  signals: Record<string, unknown>
): DecisionResult

Token lifecycle

/**
 * Issue a deterministic ExecutionToken from a decision payload.
 * The token is the governance event — it is signed and embedded in the attestation.
 */
function issueToken(input: {
  executionId: string;
  policyId: string;
  policyVersion: string;
  schemaVersion: string;
  runtimeVersion: string;
  decision_payload: DecisionOutcome;
  signalsHash: string;
}): ExecutionToken

/** Verify a base64-encoded token signature. Returns true if valid. */
async function verifyExecutionToken(
  token: ExecutionToken,
  signature: string,
  verifier: Verifier
): Promise<boolean>

Runtime manifest

/** Return the static runtime manifest embedded in this package at build time. */
function getRuntimeManifest(): RuntimeManifest

/** Sign a runtime manifest with a Signer. Returns the signature string. */
async function signRuntimeManifest(manifest: RuntimeManifest, signer: Signer): Promise<string>

/** Verify a runtime manifest against its signature. */
async function verifyRuntimeManifest(
  manifest: RuntimeManifest,
  signature: string,
  verifier: Verifier
): Promise<boolean>

Signers / Verifiers

/** Local Ed25519 signer backed by a PEM private key string. */
class LocalSigner implements Signer {
  constructor(privateKeyPem: string)
  async sign(payload: string): Promise<string>
}

/** Local Ed25519 verifier backed by a PEM public key string. */
class LocalVerifier implements Verifier {
  constructor(publicKeyPem: string)
  async verify(payload: string, signature: string): Promise<boolean>
}

interface Signer   { sign(payload: string): Promise<string> }
interface Verifier { verify(payload: string, signature: string): Promise<boolean> }

Replay store interface

interface ReplayStore {
  hasExecuted?(id: string): Promise<boolean>;
  markExecuted?(id: string): Promise<void>;
  consume?(id: string): Promise<boolean>;
  reserve?(id: string): Promise<void>;
  startExecution?(id: string): Promise<void>;
  confirm?(id: string): Promise<void>;
  fail?(id: string): Promise<void>;
}

Error codes

import { ErrorCodes } from "@parmanasystems/execution";
// ErrorCodes.INV_013  — "INV-013" replay detected
// ErrorCodes.VAL_003  — unknown signal
// ErrorCodes.VAL_004  — required signal missing
// ErrorCodes.SIG_001  — invalid token signature
// ErrorCodes.POL_001  — policy.json not found
// ... (full registry in packages/execution/src/error-codes.ts)

Core types

interface ExecutionAttestation {
  executionId: string;
  execution_fingerprint: string;
  policyId: string;
  policyVersion: string;
  schemaVersion: string;
  runtimeVersion: string;
  signalsHash: string;
  decision: { action: "approve" | "reject"; requires_override: boolean; reason?: string };
  execution_state: "completed" | "blocked" | "pending_override";
  runtimeHash: string;
  provenance: {
    provenanceVersion: string;
    bundleHash: string;
    manifestHash: string;
    manifestSignature: string;
    trustRootVersion: string;
    signerKeyId: string;
    evaluatorSemanticHash: string;
    evaluatorArtifactHash?: string;
    evaluatorHash: string;  // deprecated alias for evaluatorSemanticHash
    releaseManifestHash: string;
  };
  signature: string;
}

interface ExecutionContext {
  token: ExecutionToken;
  execution_fingerprint: string;
  token_signature: string;
  signer: Signer;
  verifier: Verifier;
  runtime_manifest: RuntimeManifest;
  runtimeRequirements: RuntimeRequirements;
  provenance: ExecutionAttestation["provenance"];
  auditMode?: boolean;
}

interface RuntimeManifest {
  runtimeVersion: string;
  runtimeHash: string;
  capabilities: readonly string[];
  supportedSchemaVersions: readonly string[];
}

Environment variables

None. Signing keys are injected via Signer/Verifier interfaces.

Package wiring

@parmanasystems/execution depends on @parmanasystems/canonical and @parmanasystems/contracts. It is the core engine consumed by @parmanasystems/execution-runtime (which adds policy loading, signal normalization, and replay protection around executeDecision). @parmanasystems/verifier uses the ExecutionAttestation type and canonicalizeAttestation to independently verify attestations. @parmanasystems/core re-exports the full public surface.