> ## 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.
# Tutorials
> All 94 numbered examples in examples/tutorials/, grouped by what they demonstrate. This page links to them, it does not duplicate their content.
**\[AVAILABLE]**, 93 run unattended in CI via `npm run examples` (`scripts/run-examples.ts`), confirmed passing this pass; one (09, noted below) needs a live server and runs individually. Numbering has a gap at 61 — retired during a connector refactor, never reused. See [Detect tampering](/guides/detect-tampering) and [Choose a signature provider](/guides/choose-a-signature-provider) for guides built directly on several of these.
Run any of them directly: `node_modules/.bin/tsx examples/tutorials//run.ts`.
## Fundamentals (01-24)
| # | Name | Demonstrates |
| -- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| 01 | Hello World | Constructing a `BusinessTransaction`, no execution yet |
| 02 | Policy Evaluation | `PolicyEngine.evaluate()` in isolation |
| 03 | Runtime Execution | First full `RuntimeFactory` execution, using the `DefaultExecutionSystem` placeholder |
| 04 | Policy Router | Resolving a `PolicyReference` to a loaded policy |
| 05 | Verification | Fresh verification appended to a trust record's history |
| 06 | Replay | `@parmana/replay`'s real, scoped policy re-evaluation, see [Replay](/replay/overview) |
| 07 | Receipt Generation | The real, wired `Receipt` (via `@parmana/crypto`'s `ReceiptCrypto`), not `@parmana/receipt`'s separate model |
| 08 | Human Approval | An `Authority` / `Authorization` / `Intent` chain without executing |
| 09 | REST API | `POST /transactions` over HTTP, excluded from the unattended batch, needs a live server, see [REST API Introduction](/api-reference/introduction) |
| 10 | End-to-End | Execute, verify, and receipt in one run, still via `DefaultExecutionSystem` |
| 11 | Execution Authorization | The `SignedExecutionAuthorization` envelope itself, printed directly, see [Authorize and execute end to end](/guides/authorize-and-execute) |
| 12 | Envelope Verification | `EnvelopeVerifier`'s per-check breakdown on a valid envelope |
| 13 | Post-Quantum Signatures | `config.crypto.primarySignatureProvider` read and printed |
| 14 | Custom Policy | Writing and evaluating a policy outside the shipped `vendor-payment` one, see [Write your first policy](/guides/write-your-first-policy) |
| 15 | Custom Runtime Component | Extending `RuntimePipeline` with a custom `RuntimeComponent` |
| 16 | Runtime Pipeline | The pipeline's stage composition, inspected directly |
| 17 | Multi-Policy Routing | Routing different transactions to different policies |
| 18 | Runtime Hooks | `RuntimeHook` / `RuntimeHookRunner` lifecycle callbacks |
| 19 | Runtime Composition | Assembling a `Runtime` from individual components |
| 20 | Batch Execution | Multiple transactions through one runtime instance |
| 21 | Partial Failure Handling | One transaction in a batch failing without stopping the rest |
| 22 | Idempotent Execution | Resubmitting the same `businessTransactionId` |
| 23 | Production Deployment | Configuration shape for a non-local deployment |
| 24 | SDK Integration Patterns | Common client-side call patterns |
## Execution authorization and envelope (25-34)
| # | Name | Demonstrates |
| -- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| 25 | Execution Permit Generation | The `@parmana/execution-control` `ExecutionPermit` model, see [@parmana/receipt](/reference/receipt) for its real, separate scope |
| 26 | Execution Authorization Verification | `AuthorizationVerifier` checking a signature independent of the fuller envelope flow |
| 27 | Authorization Expiration | An expired `expiresAt` rejected by `EnvelopeVerifier` |
| 28 | Envelope Replay Detection | A reused nonce rejected on the second check |
| 29 | Authorization Tampering | A mutated payload failing signature verification, per-check breakdown, see [Detect tampering](/guides/detect-tampering) |
| 30 | Policy Version Pinning | An authorization bound to one exact `policyVersion` |
| 31 | Authorization Binding | `authorizationId` binding an authorization to one decision |
| 32 | Execution Pipeline | The stages between decision and release, inspected directly |
| 33 | Execution Boundary | Where policy evaluation ends and release begins |
| 34 | Execution Gateway | `ExecutionGateway` constructed and exercised directly, see [The gateway](/concepts/the-gateway) |
## Gateway hardening: mutate, verify, watch it fail (35-46)
The same pattern each time: generate something valid, mutate exactly one thing, re-verify,
confirm rejection. See [Detect tampering](/guides/detect-tampering) for three of these run
live with real output.
| # | Name | What's mutated |
| -- | --------------------- | ------------------------------------------------------- |
| 35 | Replay Attack | The same authorization submitted twice |
| 36 | Parameter Tampering | A parameter inside the executable content |
| 37 | Action Substitution | The `action` field |
| 38 | Target Substitution | The `target` field |
| 39 | Policy Substitution | The referenced policy |
| 40 | Signature Forgery | The signature itself, signed by a different key |
| 41 | Expired Authorization | The clock, past `expiresAt` |
| 42 | Nonce Reuse | The nonce, submitted a second time |
| 43 | Stolen Authorization | A valid envelope replayed by a different party |
| 44 | Direct API Bypass | Attempting to skip the gateway entirely |
| 45 | Connector Bypass | Attempting to reach a connector without a valid session |
| 46 | TOCTOU Protection | The full check-vs-use gap, end to end |
## Cryptography (47-52)
| # | Name | Demonstrates |
| -- | --------------------- | ------------------------------------------------------------------------------------------------------------------- |
| 47 | Canonical JSON | `CanonicalSerializer`'s key-sorted, deterministic output |
| 48 | Deterministic Hashing | The same content hashing identically every time |
| 49 | Detached Signatures | Signing content without embedding it in the signature artifact |
| 50 | Ed25519 | Default signature provider, sign and verify, see [Choose a signature provider](/guides/choose-a-signature-provider) |
| 51 | Dilithium3 | ML-DSA-65 (post-quantum), signing with the `pq` key, same guide |
| 52 | Hybrid Signatures | Both algorithms signing the same artifact at once, same guide |
## Execution Permit and Receipt: a separate, unwired path (53-56)
None of these four reach `packages/api` or `packages/runtime`. They exercise
`@parmana/execution-control`'s `ExecutionPermit` and `@parmana/receipt`'s
`ExecutionReceipt`, real and tested, disconnected from the default server. See
[@parmana/receipt](/reference/receipt) for the precise scope note.
| # | Name | Demonstrates |
| -- | ------------------------------ | -------------------------------------------------------------------------- |
| 53 | Execution Permit | Building an `ExecutionPermit` with `ExecutionPermitBuilder` |
| 54 | Execution Receipt | `ExecutionReceiptBuilder.build(permit, trustRecord)` |
| 55 | Execution Receipt Verification | `ExecutionReceiptVerifier.verify()`, a structural check, not cryptographic |
| 56 | Complete Execution Flow | Permit through receipt through verification, one run |
## Credential isolation (57-60)
| # | Name | Demonstrates |
| -- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| 57 | Credential Isolation | The concept end to end, at the library level |
| 58 | Session Credentials | Issue, consume, expire, reuse-reject, revoke, see [Issue and verify session credentials](/guides/session-credentials) |
| 59 | Secure Connectors | Gateway attestation plus a `SessionCredentialSecureConnector`, including a spoofed-attestation rejection |
| 60 | End-to-End Enterprise Execution | The full credential-isolated path, one run |
## Signal/Intent binding (62)
Tutorial 61 does not exist — the number was retired during a connector refactor (an
earlier, single Razorpay tutorial split into the Razorpay group below) and was never
reused.
| # | Name | Demonstrates |
| -- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 62 | Signal/Intent Binding | `SignalIntentBinder` rejecting a caller-declared signal that doesn't match `intent`, and the same transaction approved once correctly bound — see [Trust and Claims](/trust-and-claims/claims-discipline) for the live bypass this closed |
## Razorpay: connector, fetch-verification, caps, webhooks, settlement (63-68)
See [Razorpay](/integrations/razorpay) for the connector these exercise and its exact proven
scope.
| # | Name | Demonstrates |
| -- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 63 | Razorpay Refund Connector | The full path from a `BusinessTransaction` through policy to a real (mocked) refund call, via the same production composition (`createExecutionSystem` + `createApplication`) `server.ts` itself calls |
| 64 | Razorpay Policy Denial | A refund exceeding the payment's real refundable remainder rejected, zero refund calls ever reaching the connector |
| 65 | Razorpay Signal-State Verification | `RazorpaySignalStateVerifier` independently fetching the real payment and rejecting a caller-declared signal that disagrees with it, naming the exact mismatch |
| 66 | Razorpay Daily Cumulative Cap | Two concurrent refunds racing the daily cap; the atomic `RazorpayDailyRefundLedger` lets exactly one through, never both |
| 67 | Razorpay Webhook Receipt | HMAC-SHA256 signature verification over the raw body plus atomic `eventId` dedupe, exercised directly against the real functions |
| 68 | Razorpay Settlement Confirmation | `RazorpaySettlementProcessor` always re-fetching the refund from Razorpay rather than trusting the webhook's own claimed event type |
## HubSpot: connector, denial, verification, approval artifacts (69-72)
See [HubSpot](/integrations/hubspot) for the connector these exercise and its exact proven
scope.
| # | Name | Demonstrates |
| -- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 69 | HubSpot Deal Update Connector | The full path from a `BusinessTransaction` through policy to a real (mocked) `PATCH` call, via the same production composition `server.ts` itself calls |
| 70 | HubSpot Policy Denial | A move out of a terminal pipeline stage rejected, the deal left completely untouched on HubSpot |
| 71 | HubSpot Signal-State Verification | `HubSpotSignalStateVerifier` independently fetching the real deal and rejecting a caller-declared `currentDealStage` that disagrees with it |
| 72 | HubSpot Approval Artifact | An over-threshold amount change requiring a real, independently-issued, signed Approval Artifact scoped to the right deal and amount, not a bare `preAuthorizedForAmountChange: true` claim |
## Refusal records and signed audit events (73-75)
| # | Name | Demonstrates |
| -- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| 73 | Refusal Records | A policy `REJECT` producing a durable, signed Refusal Record, retrievable and independently verifiable afterward |
| 74 | Refusal Record Fail-Open | A Refusal Record write failure never blocking, delaying, or changing the actual rejection a caller receives — the record is evidence, not a gate |
| 75 | Signed Audit Events | Caller-authentication audit events signed with the same root of trust as every other Parmana artifact, tampering detectable |
## Caller scoping and concurrency (76-78)
| # | Name | Demonstrates |
| -- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| 76 | Caller Principal Scoping | `isPrincipalAllowed()`: fail-closed by default, an authenticated caller may only assert its own identity absent an explicit operator grant |
| 77 | Caller Ownership Scoping | `isOwnedByCaller()`: one authenticated caller can't read another caller's transaction, trust record, or receipt history |
| 78 | Duplicate Transaction Race | Two concurrent `create()` calls for the identical `businessTransactionId`, exactly one winning, the stored record never silently overwritten |
## Storage and config validation (79-80)
| # | Name | Demonstrates |
| -- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 79 | Storage Backend Selection | `StorageFactory.createFromEnvironment()`, and why `NODE_ENV=test` always resolves to in-memory regardless of other config |
| 80 | Fail-Closed Config Validation | Invalid `CRYPTO_MODE`/`PARMANA_STORAGE`/`PARMANA_API_KEYS` values rejected at load time with a named, specific error, never a silent fallback |
## Multi-connector composition (81-83)
| # | Name | Demonstrates |
| -- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 81 | Connector Execution Gateway | `GatewayConnectorRegistry` resolving a capability string to its registered connector, each connector failing closed independently when its own credentials are absent |
| 82 | Composite Signal-State Verification | `CompositeSignalStateVerifier` composing the Razorpay and HubSpot verifiers into the one verifier `RuntimeEngine` accepts, with no cross-contamination between them |
| 83 | Capability/Policy Binding (TD-22) | `CapabilityPolicyBinder` closing the gap where a real, fund-moving capability could be paired with the wrong, unprotected policy |
## HTTP surface hardening (84, 88-91)
| # | Name | Demonstrates |
| -- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 84 | Caller Authentication | The real Express caller-authentication middleware over a real listening server: valid/missing/invalid credentials, per-caller scoping, key rotation and revocation |
| 88 | Malformed Request Handling | Malformed JSON and oversized request bodies returning specific `400`/`413` errors, not a generic `500` |
| 89 | Readiness Probe | `GET /ready`, distinct from `GET /health`, across memory-backed and (genuinely unreachable) Supabase-backed storage |
| 90 | OpenAPI Self-Description | `GET /openapi.yaml` serving a valid, unauthenticated, fully-dereferenced OpenAPI 3.1 document, no unresolved `$ref`s |
| 91 | Graceful Shutdown | The `SIGTERM`/`SIGINT` handler draining in-flight requests before exit, force-exiting on a hung close after a bounded timeout |
## Real-world fixtures and gateway internals (85-87, 92-93)
| # | Name | Demonstrates |
| -- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 85 | Razorpay Real Webhook Fixture | The actual `POST /webhooks/razorpay` route replaying a real, PII-redacted Razorpay-delivered payload, not a synthetic one this codebase constructed |
| 86 | Gateway Attestation | `SignedTokenConnectorAuthenticator`'s full surface: payload tampering, the missing-attestation default, request-bound vs. signature-only checks, the trusted-connector allow-list |
| 87 | Key Provider Path Traversal | `FileKeyProvider` rejecting a path-traversal `keyId` on every one of its four methods, before ever touching the filesystem |
| 92 | Public API Boundary | `@parmana/execution-gateway`'s internal implementation classes checked directly against the real compiled export surface, none reachable from outside |
| 93 | Trust Record Ordering | A Trust Record's collections preserving insertion order through a full round trip, hash and signature both still valid on reload |
## SDK and generic verification (94-95)
| # | Name | Demonstrates |
| -- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 94 | SDK HTTP Transport | The published TypeScript SDK's `HttpTransport`: bearer-key attachment and its full status-code-to-typed-error-class mapping, including `403`/`POLICY_DENIED` |
| 95 | Generic Approval Verifier | `ApprovalVerifier` exercised directly, connector-agnostic, with its full nine-check breakdown and durable, cross-process replay protection |
## Scenarios
Two production-shaped scenarios also live in `examples/scenarios/`, run manually via `npm
run examples` (`scripts/run-examples.ts`), not currently part of CI: `expense-approval`,
`purchase-order`. (A third, `vendor-payment`, existed here until `payments:execute` was
removed from the repository entirely — see `docs/VERIFICATION-GAPS.md` G-27.)
## Next
Three of the tutorials above, run live with real output.
How every claim on this site, including every line above, maps back to code and tests.