@parmanasystems/execution-runtime

The operational enforcement layer. executeFromSignals is the top-level entry point that orchestrates the full governance pipeline: load and verify the policy bundle, normalize and validate input signals, evaluate the policy, compute the execution fingerprint, check replay protection, issue the token, sign it, call executeDecision, and confirm the replay store. A ReplayStore is mandatory — execution without one throws immediately.

Public API

Main entry point

/**
 * Full governance execution pipeline.
 *
 * Steps (in order):
 *   1. Load policy bundle from policiesRootPath/<policyId>/<policyVersion>/
 *   2. Verify bundle manifest signature with trustPublicKeyPath
 *   3. Normalize and validate input signals against policy schema
 *   4. Evaluate policy — produces DecisionResult
 *   5. Compute execution_fingerprint (SHA-256 of canonical {policyId, policyVersion, signals})
 *   6. Reserve fingerprint in replayStore (throws INV-013 on replay)
 *   7. Issue ExecutionToken and sign it
 *   8. Call executeDecision() to produce signed ExecutionAttestation
 *   9. Confirm fingerprint in replayStore
 *
 * @param input.signals  Raw signal map — governed signals (with provenance) or plain values.
 * @param signer         Ed25519 signing authority for token and attestation.
 * @param verifier       Paired verifier for signature checks.
 * @param runtimeEnvironment  Paths to policy bundles, trust root, and release manifest.
 *                            Defaults to env vars if omitted.
 * @param replayStore    REQUIRED. Throws [INV-REPLAY-001] if not provided.
 */
async function executeFromSignals(
  input: {
    policyId: string;
    policyVersion: string;
    signals: Record<string, unknown>;
  },
  signer: Signer,
  verifier: Verifier,
  runtimeEnvironment?: {
    policiesRootPath: string;
    trustPublicKeyPath: string;
    trustRootPath: string;
    releaseManifestPath: string;
  },
  replayStore?: ReplayStore
): Promise<ExecutionAttestation>

Redis-backed execution

/**
 * Execute with a Redis-backed replay store.
 * Convenience wrapper around executeFromSignals with RedisReplayStore.
 */
async function executeWithRedis(
  input: { policyId: string; policyVersion: string; signals: Record<string, unknown> },
  signer: Signer,
  verifier: Verifier,
  redisUrl: string,
  runtimeEnvironment?: RuntimeEnvironment
): Promise<ExecutionAttestation>

Batch execution

/**
 * Execute multiple governance decisions in sequence.
 * Each item uses the same signer/verifier/replayStore.
 * Fails fast on the first error.
 */
async function executeBatch(
  items: Array<{ policyId: string; policyVersion: string; signals: Record<string, unknown> }>,
  signer: Signer,
  verifier: Verifier,
  replayStore: ReplayStore,
  runtimeEnvironment?: RuntimeEnvironment
): Promise<ExecutionAttestation[]>

Dry run

/**
 * Evaluate the policy and preview the decision without replay protection,
 * signing, or side effects. Returns DryRunResult — not an attestation.
 */
async function evaluateDryRun(
  input: { policyId: string; policyVersion: string; signals: Record<string, unknown> },
  runtimeEnvironment?: RuntimeEnvironment
): Promise<DryRunResult>

interface DryRunResult {
  decision: DecisionOutcome;
  rule_id: string;
  signalsValidated: boolean;
}

Override resolution

/**
 * Transition a pending_override execution to a resolved state.
 * Requires the replay store to support the advanced lifecycle (reserve/confirm/fail).
 */
async function resolveOverride(
  executionId: string,
  replayStore: ReplayStore
): Promise<void>

Replay stores

/** Redis-backed replay store. Uses SET NX with TTL for distributed replay protection. */
class RedisReplayStore implements ReplayStore {
  constructor(redisUrl: string, options?: RedisReplayStoreOptions)
}

interface RedisReplayStoreOptions {
  ttlSeconds?: number;   // default: 86400 (24 h)
  keyPrefix?: string;
}

/** In-memory replay store for testing and single-process deployments. */
class MemoryReplayStore implements ReplayStore {
  constructor(options?: MemoryReplayStoreOptions)
}

interface MemoryReplayStoreOptions {
  maxSize?: number;
}

Review task store

/** Append a review task for a pending_override execution. */
async function addReviewTask(task: ReviewTask): Promise<void>

/** Retrieve all pending review tasks. */
async function getAllTasks(): Promise<ReviewTask[]>

interface ReviewTask {
  executionId: string;
  policyId: string;
  policyVersion: string;
  reason?: string;
  createdAt: string;
}

Environment variables

When runtimeEnvironment is not provided, executeFromSignals reads paths from the environment via getRuntimePaths() (imported from @parmanasystems/server's runtime module):

| Variable | Description | |---|---| | PARMANA_POLICIES_ROOT | Root directory of compiled policy bundles. | | PARMANA_TRUST_ROOT | Path to trust-root.json. | | PARMANA_TRUST_PUBLIC_KEY | Path to the trust root public key PEM. | | PARMANA_RELEASE_MANIFEST | Path to release-manifest.json. | | PARMANA_RELEASE_SIGNATURE | Path to release-manifest.sig. |

In normal server deployments these are injected by the container environment; direct library callers should pass the runtimeEnvironment argument explicitly.

Package wiring

@parmanasystems/execution-runtime depends on @parmanasystems/execution (core three-stage pipeline), @parmanasystems/governance (loadPolicyBundle), @parmanasystems/provenance (normalizeGovernedSignals), and @parmanasystems/canonical. The server injects a RedisReplayStore (from this package) and passes it along with a Signer/Verifier from @parmanasystems/signing. @parmanasystems/core re-exports executeFromSignals, MemoryReplayStore, and RedisReplayStore.