> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parmanasystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# @parmana/policy

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

<Info>**\[AVAILABLE]**. `packages/policy`, 72 tests. CLAIMS.md 2.2/2.3.</Info>

## Purpose

Evaluates a `PolicySignals` object against a `Policy`'s ordered rules and returns exactly
one `Decision`. See [Policies and the decision](/concepts/policies-and-the-decision) for the
concept, this page is the export reference.

<Note>
  `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](/concepts/policies-and-the-decision)
  for why this split exists.
</Note>

## Install

```bash theme={null}
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

```typescript theme={null}
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](/guides/write-your-first-policy).

## Next

<CardGroup cols={2}>
  <Card title="Write your first policy" icon="scale-balanced" href="/guides/write-your-first-policy">
    Write a policy and confirm both the approve and reject paths.
  </Card>

  <Card title="@parmana/runtime" icon="cog" href="/reference/runtime">
    Where `PolicyEngine` is actually invoked as part of executing a transaction.
  </Card>
</CardGroup>