@parmana/policy

Deterministic, first-match-wins rule evaluation, plus loading and validating policy documents.

[AVAILABLE]. packages/policy, 72 tests. CLAIMS.md 2.2/2.3.

Purpose

Evaluates a PolicySignals object against a Policy’s ordered rules and returns exactly one Decision. See Policies and the decision for the concept, this page is the export reference.

PolicyEngine.evaluate() alone does not check Policy.boundSignals — that binding is enforced one layer up, by SignalIntentBinder, which RuntimeEngine (@parmana/runtime) invokes immediately before calling PolicyEngine.evaluate(). Calling PolicyEngine.evaluate() directly, as the minimal example below does, bypasses signal/intent binding entirely — verified by actually running it. See Policies and the decision for why this split exists.

Install

npm install @parmana/policy

Key exports

Engine, [AVAILABLE]

Export	Signature
PolicyEngine	.evaluate(policy: Policy, input: PolicyInput): PolicyDecision, first-match-wins over policy.rules, unmatched input rejects

Routing and loading, [AVAILABLE]

Export	Purpose
PolicyRouter	Resolves a PolicyReference { name, version, schemaVersion } to a loaded Policy
PolicyRegistry	In-memory policy lookup by name/version
PolicyRepository (type)	The interface FilePolicyRepository and any custom repository implement
FilePolicyRepository	new FilePolicyRepository(directory: string), resolves <directory>/<name>/<version>/policy.json

Validation, [AVAILABLE]

Export	Purpose
PolicyValidator	Checks a loaded policy’s identity (policyId/policyVersion) matches what was requested before evaluation runs
SignalValidator	Validates submitted signals against a policy’s signalsSchema
SignalIntentBinder	.findViolations(policy, signals, intent), checks every Policy.boundSignals entry by strict equality against intent. Invoked by RuntimeEngine, not by PolicyEngine itself — see the note above

Types

Policy (including its optional boundSignals: Record<string, string> field, a signal-key → intent-dot-path map), PolicyRule, PolicyCondition, PolicyRuleOutcome, PolicyInput, PolicySignals, PolicyDecision, PolicyAction (enum: APPROVE, REJECT, REQUIRE_OVERRIDE), PolicyOutcome (enum: APPROVE, REJECT, REQUIRE_OVERRIDE), SignalIntentBindingViolation ({ signalKey, intentPath, signalValue, intentValue }).

Minimal example

import { FilePolicyRepository, PolicyEngine } from "@parmana/policy";

const repository = new FilePolicyRepository("policies");
const policy = await repository.load("vendor-payment", "2.0.0");

const engine = new PolicyEngine();
const decision = engine.evaluate(policy, {
  vendorVerified: true, invoiceVerified: true, paymentApproved: true,
  sufficientFunds: true, paymentAmount: 1000, riskScore: 5,
});
// decision.outcome === "APPROVE"

Full runnable version: Write your first policy.

Next

Write your first policy

Write a policy and confirm both the approve and reject paths.

@parmana/runtime

Where PolicyEngine is actually invoked as part of executing a transaction.