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

# FAQ

> Answers to the questions this documentation's own discrepancies tend to raise

<AccordionGroup>
  <Accordion title="Why doesn't the API enforce authentication yet?">
    `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](/docs/api/authentication) and [TypeScript SDK → Installation](/docs/typescript-sdk/installation#credentials).
  </Accordion>

  <Accordion title="What's the difference between Override and human-in-the-loop approval?">
    They're opposites in timing. "Human-in-the-loop" usually means pausing an in-flight operation until a person approves it. [Override](/docs/concepts/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](/docs/guides/human-override) for how to use the underlying (unwired) `OverrideService` directly.
  </Accordion>

  <Accordion title="Is replay the same as verification?">
    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](/docs/guides/deterministic-replay).
  </Accordion>

  <Accordion title="Why does GET /verify/:id (or GET /receipt/:id) 404?">
    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](/docs/api/verify#get-the-latest-verification) and [REST API → Receipt](/docs/api/receipt#get-the-latest-receipt).
  </Accordion>

  <Accordion title="Why does the TypeScript SDK's verify() behave differently from the Python SDK's?">
    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](/docs/python-sdk/parmana-client#verify-does-not-mean-the-same-thing-in-both-sdks).
  </Accordion>

  <Accordion title="If a request fails, does the SDK throw?">
    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](/docs/typescript-sdk/errors).
  </Accordion>

  <Accordion title="Does POST /policies/validate check that a policy's rules make sense?">
    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](/docs/api/policies).
  </Accordion>

  <Accordion title="Can I run the bundled examples to see the platform working end to end?">
    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](/docs/getting-started/quickstart) or [Guides → Basic Execution](/docs/guides/basic-execution) instead. See [Examples Overview](/docs/examples/overview) for the full accounting.
  </Accordion>

  <Accordion title="Are the replay and verification packages actually used?">
    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](/docs/packages/overview) for the full picture of what's wired in versus what's shipped but dormant.
  </Accordion>

  <Accordion title="Where do I report a documentation error or an inaccuracy I've found?">
    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.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Error Model" href="/docs/api/error-model">The deepest spec-vs-implementation gap in this documentation.</Card>
  <Card title="Packages Overview" href="/docs/packages/overview">What's wired in vs. dormant, package by package.</Card>
  <Card title="Glossary" href="/docs/reference/glossary">Normative terminology, independent of implementation status.</Card>
  <Card title="Contributing" href="/docs/contributing/overview">How to help close these gaps.</Card>
</CardGroup>