> ## 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/runtime

> Orchestrates policy evaluation, authorization signing, execution, and trust record assembly. The composition root for everything else.

<Info>**\[AVAILABLE]**. `packages/runtime`. Wires together `@parmana/policy`, `@parmana/crypto`, `@parmana/storage`, and whichever `ExecutionSystem` you supply.</Info>

## Purpose

Given a `BusinessTransaction` and an `ExecutionSystem`, runs the full pipeline: validate,
evaluate policy, sign an authorization if approved, release execution, assemble and store
the resulting [Execution trust record](/concepts/execution-trust-records).

## Install

```bash theme={null}
npm install @parmana/runtime
```

## Key exports

### Entry points, \[AVAILABLE]

| Export                                                                                 | Signature                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RuntimeFactory.create(transactions, trustRecords, policyRepository, executionSystem)` | Returns an `ExecutionTrustApplication`. The default server's own bootstrap follows this exact call.                                                                                                           |
| `RuntimeBuilder`                                                                       | Fluent alternative: `.withPolicyRepository(repo).build(trustRecords)`, used throughout `examples/tutorials/`.                                                                                                 |
| `ExecutionTrustApplication`                                                            | `.execute(transaction)`, `.verify(id)`, `.replay(id)`, `.generateReceipt(id)`, `.getTrustRecord(id)`, `.getTransaction(id)`, `.listTransactions(page, pageSize)`. What `packages/api`'s routes call directly. |

### Advanced / lower-level, \[AVAILABLE]

| Export                                | Purpose                                                                                                                                                                                                                                                    |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RuntimeEngine`                       | The actual pipeline: validation, `ExecutionGate.enforce()` (throws on a `REJECTED` decision), authorization signing, execution, trust record assembly                                                                                                      |
| `RuntimePipeline`, `RuntimeComponent` | The composable stage interface, `ExecutionComponent`, `TrustChainValidationComponent`, etc. implement this                                                                                                                                                 |
| `RuntimeHook`, `RuntimeHookRunner`    | Lifecycle hooks around pipeline stages                                                                                                                                                                                                                     |
| `RuntimeContext`                      | Per-execution context threaded through the pipeline (`context.authorization` is where a [signed authorization](/concepts/execution-authorization) is visible before it's discarded, see [Authorize and execute end to end](/guides/authorize-and-execute)) |

### Services, \[AVAILABLE]

`business-transaction-service`, `execution-service`, `receipt-service` (uses
`@parmana/crypto`'s `ReceiptCrypto`, not `@parmana/receipt`, see that package's reference
page), `verification-service`.

### Errors, \[AVAILABLE]

`RuntimeError` (base, carries `status` and `code`), `BusinessTransactionValidationError`,
`DuplicateBusinessTransactionError`, `VerificationFailedError`, `ReceiptGenerationError`.
`packages/api/src/middleware/error-handler.ts` checks these by `instanceof` to pick an HTTP
status, verified per-route on [Endpoints](/api-reference/endpoints), including one gap where
a raw `TypeError` from validation bypasses this entirely.

## A rejected decision throws, it does not return

<Warning>
  `ExecutionTrustApplication.execute()` throws a `RuntimeError` when the policy decision is
  `REJECTED`, it does not return an object with `outcome: "REJECTED"`. Verified live in [Write
  your first policy](/guides/write-your-first-policy): the thrown message is the matched
  rule's rejection reason, `status: 500`, `code: "RUNTIME_ERROR"`. A caller that wants to
  handle rejection gracefully needs a `try`/`catch`.
</Warning>

## Minimal example

```typescript theme={null}
import { RuntimeFactory } from "@parmana/runtime";
import { DefaultExecutionSystem } from "@parmana/execution-system";

const application = RuntimeFactory.create(
  transactionRepository, trustRecordRepository, policyRepository,
  new DefaultExecutionSystem(),
);

const trustRecord = await application.execute(transaction); // throws if REJECTED
```

## Next

<CardGroup cols={2}>
  <Card title="Authorize and execute an action end to end" icon="play" href="/guides/authorize-and-execute">
    See `RuntimeContext.authorization` directly, something the REST API never exposes.
  </Card>

  <Card title="@parmana/execution-system" icon="plug" href="/reference/execution-system">
    The one interface the fourth `RuntimeFactory.create()` argument must implement.
  </Card>
</CardGroup>