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.
What are invariants?
An invariant is a property that must always be true — before, during, and after every governed execution.
Parmana enforces invariants at runtime. If an invariant is violated the execution fails closed immediately. No partial results. No silent errors. The system throws an InvariantViolation and stops.
// What a violation looks like
throw new InvariantViolation({
invariant_id: "INV-013",
boundary: "replay",
reason: "Replay detected: execution_fingerprint abc123 has already been consumed",
input_hash: "sha256 of the input that triggered the violation",
timestamp_seq: 7, // monotonically increasing within this process
});
Why invariants matter
Most systems have implicit assumptions about how they should behave. Parmana makes these assumptions explicit and enforces them at every boundary.
| Without invariants | With invariants |
|---|
| The system might work correctly most of the time | The system either behaves correctly or throws |
| Failures are silent or discovered after the fact | Violations are recorded with full structured context |
| Nobody can prove the system behaved correctly | Every governed execution is provably correct or rejected |
| Auditors must trust logs | Auditors can verify cryptographic proofs |
Invariant boundaries
Every invariant is assigned to one or more pipeline boundaries. A violation at a boundary throws before anything downstream can observe a partial result.
| Boundary | Stage | What it protects |
|---|
canonicalize | Before signing | Identical inputs produce identical bytes |
validate | Input gate | Signals and policy structure are correct |
verify | Pre-execution | Token, runtime, and schema are valid |
replay | Pre-execution | Same fingerprint cannot be consumed twice |
execute | Core pipeline | Decision derivation and audit integrity |
sign | Post-execution | Attestation is independently verifiable |
All invariants
Canonicalization invariants
These enforce that the canonical JSON serialization is deterministic, stable, and lossless across all environments.
| Code | Invariant |
|---|
INV-001 | Canonical serialization produces identical bytes for identical inputs |
INV-047 | Canonical serialization uses explicit UTF-8 encoding |
INV-048 | Unicode normalization is stable across canonicalization calls |
INV-049 | Canonical JSON sorts object keys recursively and preserves array order |
INV-050 | Duplicate JSON keys must not appear in governance payloads |
INV-051 | Numeric values canonicalize identically regardless of trailing zeros |
INV-052 | Object insertion order does not affect canonical form or content-address hash |
INV-053 | Array element order is preserved through canonicalization |
INV-054 | JSON type closure: NaN and Infinity serialize to null; undefined fields are omitted |
INV-057 | Content-address (SHA-256) is stable for identical content across calls |
Validation invariants
These enforce that signals and policy structure are structurally correct before evaluation begins.
| Code | Invariant |
|---|
INV-002 | Input payload must be structurally valid |
INV-009 | Signals hash must be a non-empty string binding execution to specific inputs |
INV-010 | Policy ID and policy version must be non-empty strings |
INV-040 | AI output and governance enforcement are strictly separated — no AI field in execution scope |
INV-078 | Operational metadata fields must not contaminate deterministic signing scope |
Verification invariants
These enforce that the runtime environment, token signature, and schema version are valid before execution proceeds.
| Code | Invariant |
|---|
INV-003 | Execution token signature must be cryptographically valid |
INV-005 | Runtime version must be in the set of supported runtime versions |
INV-006 | Schema version 1.0.0 must be supported by both runtime manifest and requirements |
INV-007 | Execution token must not be expired at governed_time |
INV-011 | All required runtime capabilities must be present in the runtime manifest |
INV-017 | Any verification failure causes fail-closed execution — no partial results |
INV-020 | Runtime capability declarations are truthful and non-negotiable |
INV-031 | Runtime manifest declares explicit supported_schemaVersions and runtimeVersion |
INV-041 | Governance boundary is explicit: runtime manifest must declare runtimeVersion |
INV-061 | Runtime capability declarations are immutable after build |
INV-077 | All failure modes are deterministic: same invalid input always produces the same error |
INV-080 | Unsupported schema and runtime versions fail explicitly with a descriptive error |
Replay invariants
These enforce that every execution_fingerprint is consumed exactly once.
| Code | Invariant |
|---|
INV-013 | Replay protection is always enforced — execution_fingerprint is single-use and non-configurable |
INV-059 | Replay domain is explicit: every fingerprint in the store was consumed by a real execution |
Execution invariants
These enforce the correctness and side-effect discipline of the core pipeline.
| Code | Invariant |
|---|
INV-004 | Execution time is injected deterministically — no wall-clock reads inside the execution scope |
INV-014 | governed: true structurally distinguishes ExecutionResult from DryRunResult |
INV-015 | Audit record must be written before attestation is issued |
INV-016 | Audit records are linearizable via SHA-256 hash chain |
INV-022 | Every policy decision is derivable from the policy document and input signals |
INV-024 | Decision values are semantically unambiguous strings |
INV-025 | Schema version and runtime version are present in every ExecutionResult |
INV-030 | Every attestation contains a runtimeHash binding it to a specific runtime version |
INV-033 | Governance properties (replay, audit, attestation) are structurally enforced — not configurable |
INV-072 | Dry-run path produces no side effects: no replay store write, no audit record, no signature |
INV-073 | Canonical evaluation source files contain no network calls |
INV-074 | Every governed executeDecision call produces exactly one audit record |
INV-075 | Execution IDs (UUIDv4) are unique per issuance — governance identity is non-reusable |
Signing invariants
These enforce that attestations are independently verifiable and tamper-evident.
| Code | Invariant |
|---|
INV-008 | The governed field is always in signature scope and equals literal true |
INV-034 | Any verifier holding the correct public key can independently verify an attestation |
INV-035 | Verification is reproducible: same attestation + key produces identical outcome |
INV-037 | Signatures from different authority keys do not cross-verify — signing domains are isolated |
INV-038 | Cross-key verification failures are consistent: wrong-key always returns false |
INV-060 | Attestation verification is idempotent: same inputs always produce identical results |
| Code | Invariant |
|---|
META-001 | Every governed execution produces a signed, independently verifiable attestation |
META-004 | Invariant violations always fail closed — no partial results are emitted on violation |
Fail-closed semantics
Every invariant violation:
- Throws
InvariantViolation immediately — execution stops
- Records a structured
ViolationReport with invariant ID, boundary, reason, input hash, and sequence number
- Never returns a partial result
- Never logs-and-continues
This is stronger than observability. A logged violation means something went wrong but execution continued. A thrown violation means execution stopped before any side effect could occur.
import { InvariantViolation } from "@parmanasystems/execution";
try {
const attestation = await executeFromSignals(input, signer, verifier, store);
} catch (err) {
if (err instanceof InvariantViolation) {
console.log(err.report.invariant_id); // "INV-013"
console.log(err.report.boundary); // "replay"
console.log(err.report.reason); // human-readable description
console.log(err.report.input_hash); // SHA-256 of the input that triggered it
console.log(err.report.timestamp_seq); // monotonic sequence number
}
}
Use Cases
Detecting tampered attestations in an IRDAI audit
An IRDAI auditor receives a set of insurance claim attestations from a regulated insurer. The auditor runs verifyAttestation on each record. Any record where result.checks.signature_verified is false indicates that the attestation body was modified after signing — a violation of INV-034. The invariant guarantees this is detectable by any party with the public key, without access to the insurer’s infrastructure.
Catching a replay attack during loan disbursement
A disbursement system accidentally submits the same loan application twice due to a retry bug. The second submission hits INV-013 — the replay protection invariant fires before evaluation runs and before any attestation is produced. The calling system catches the InvariantViolation, reads err.report.invariant_id === "INV-013", increments a metric, and returns the original attestation to the caller. No double disbursement occurs.
Verifying a governance pipeline in CI
A fintech runs verifyBundle in its CI/CD pipeline before deploying a new policy version. If the bundle content no longer matches the signed manifest — because a developer edited policy.json without rebuilding the bundle — INV-034 and INV-035 fire. The deployment is blocked and the team is alerted. This prevents a deployed policy from diverging from its signed governance artifact.
See also
