Skip to main content
openapi/openapi.yaml declares a global BearerAuth (JWT) security scheme, and both SDKs model Credentials/AuthenticationScheme, but packages/api/src/middleware/ contains no auth-checking middleware — no route currently validates a bearer token or API key. Worse, even if the server did check one, the TypeScript SDK’s HttpTransport never reads configuration.credentials to attach an Authorization header in the first place. Treat any locally-run or deployed instance of this server as unauthenticated until both halves of this gap close. See REST API → Authentication and TypeScript SDK → Installation.
They’re opposites in timing. “Human-in-the-loop” usually means pausing an in-flight operation until a person approves it. Override is a post-hoc correction: the Decision and Execution already happened, and a human appends an immutable Override artifact to the record afterward, without altering what was already recorded. Parmana’s runtime has no notion of a paused, awaiting-approval transaction state. As of this snapshot, Override is also not reachable through any REST endpoint or SDK method — see Guides → Human Override for how to use the underlying (unwired) OverrideService directly.
Today, yes, functionally — both POST /verify and POST /replay call the exact same method, VerificationCrypto.verify(), which re-hashes the trust record and compares it to the stored trustRecordHash. Conceptually they’re meant to be different: Verification asks “has this record been altered?” while Replay is meant to ask “would evaluating this Policy against these recorded signals produce the same Decision again?” The monorepo does ship a real engine for that second question — @parmana/replay’s ReplayEngine, which re-runs PolicyEngine.evaluate() and compares outcomes — but it isn’t wired into POST /replay in this snapshot. See Guides → Deterministic Replay.
Those paths don’t exist. packages/api/src/app.ts mounts the “get latest” handlers at /verification/:id and /receipt/latest/:id instead — a naming trap where the route file names (verify-get.ts, receipt-get.ts) don’t match their own mount paths. Both SDKs’ verify()/receipt()-style read paths already target the correct URLs internally; only hand-written HTTP calls following the “obvious” naming get this wrong. See REST API → Verify and REST API → Receipt.
TypeScript’s client.verify(id) calls GET /verification/:id — a read of the latest already-computed Verification. Python’s client.verification.verify(id) calls POST /verify — it triggers a brand-new Verification and appends it to the trust record. Same method name, genuinely different effect (one is side-effect-free, the other writes). This is the most significant behavioral divergence between the two official SDKs found while writing this documentation. See Python SDK → ParmanaClient.
Depends which SDK. The Python SDK’s HttpTransport checks response.ok and raises RuntimeError for any non-2xx response. The TypeScript SDK’s HttpTransport does not check status at all — a 404 or 500 resolves successfully, with the error JSON body returned as if it were the expected success type. If you’re writing error-handling logic against the TypeScript SDK, don’t rely on a catch block for anything other than ConfigurationError, TimeoutError, or NetworkError — see TypeScript SDK → Errors.
No — it only confirms policies/<policyId>/<policyVersion>/policy.json exists on disk and parses as JSON. It doesn’t run schema validation or check that referenced signals, conditions, or actions are well-formed. A syntactically valid but semantically broken policy file reports { "valid": true }. See REST API → Policies.
Only three of the ten numbered examples (01-hello-world, 02-policy-evaluation, 03-runtime-execution) currently have implemented run.ts files — the rest are single-line console.log stubs with empty fixture files. None of the ten call the REST API or either SDK directly; they exercise package internals (PolicyEngine, RuntimeEngine) in isolation. For an actual end-to-end walkthrough, follow Getting Started → Quickstart or Guides → Basic Execution instead. See Examples Overview for the full accounting.
Not by the running server. @parmana/replay’s ReplayEngine and @parmana/verification’s six-stage VerificationPipeline are both real, complete implementations, but neither is imported anywhere under packages/runtime or packages/api. What actually runs when you call POST /verify or POST /replay is a single hash comparison via @parmana/crypto. See Packages Overview for the full picture of what’s wired in versus what’s shipped but dormant.
This documentation is generated against a specific snapshot of the parmana monorepo and calls out every implementation/specification mismatch it found at that point in time explicitly, rather than silently picking one side. If the underlying code has since changed, treat the source files referenced on each page — not this documentation — as the final authority, and open an issue or PR against parmana-docs to update the affected page.

Error Model

The deepest spec-vs-implementation gap in this documentation.

Packages Overview

What’s wired in vs. dormant, package by package.

Glossary

Normative terminology, independent of implementation status.

Contributing

How to help close these gaps.