> ## 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.

# Canonical

> Deterministic canonicalization and serialization for reproducible hashing and verification.

# @parmanasystems/canonical

The Canonical package provides deterministic serialization and canonicalization used throughout Parmana.

It ensures that identical data always produces identical hashes, signatures, execution fingerprints, and verification results regardless of platform, runtime, or language implementation.

## Installation

```bash theme={null}
npm install @parmanasystems/canonical
```

## Responsibilities

The canonical layer provides:

* Deterministic serialization
* Canonical JSON generation
* Stable hashing inputs
* Signature consistency
* Cross-platform reproducibility
* Verification compatibility

## Why it exists

Cryptographic systems depend on exact byte-for-byte consistency.

Without canonicalization:

```json theme={null}
{"a":1,"b":2}
```

and

```json theme={null}
{"b":2,"a":1}
```

could produce different hashes even though they represent the same data.

Canonicalization eliminates this ambiguity.

## Core concepts

### Canonical Form

Before hashing or signing, data is transformed into a deterministic representation.

```text theme={null}
Input
   ↓
Canonicalization
   ↓
Canonical Form
   ↓
Hashing / Signing
```

This guarantees reproducibility.

### Execution Fingerprints

Execution fingerprints are derived from canonicalized inputs.

```text theme={null}
sha256(
  canonical(
    policyId,
    policyVersion,
    signals
  )
)
```

Because canonicalization is deterministic:

* identical inputs produce identical fingerprints
* replay protection remains stable
* verification is reproducible

### Signature Consistency

Attestation signatures operate on canonical payloads.

This ensures:

* deterministic signing inputs
* reproducible verification
* language-independent validation

## Relationship to other packages

| Package                     | Responsibility              |
| --------------------------- | --------------------------- |
| `@parmanasystems/canonical` | Deterministic serialization |
| `@parmanasystems/signing`   | Signature generation        |
| `@parmanasystems/execution` | Fingerprint generation      |
| `@parmanasystems/verifier`  | Verification                |
| `@parmanasystems/core`      | End-to-end SDK              |

## Why canonicalization matters

Without canonicalization:

```text theme={null}
Same data
     ↓
Different serialization
     ↓
Different hashes
     ↓
Broken verification
```

With canonicalization:

```text theme={null}
Same data
     ↓
Same canonical form
     ↓
Same hash
     ↓
Same verification result
```

## Design principles

### Deterministic

The same input always produces the same canonical form.

### Portable

Different runtimes produce identical results.

### Verifiable

Hashes and signatures remain reproducible.

### Long-term stable

Historical attestations remain verifiable years later.

## Typical usage

Most developers use canonicalization indirectly through:

* `@parmanasystems/core`
* `@parmanasystems/execution`
* `@parmanasystems/signing`

Advanced integrations may use canonicalization directly when generating hashes or custom trust artifacts.

## Security benefits

### Stable Hashes

Hashes are independent of serialization order.

### Stable Signatures

Signatures are generated from reproducible payloads.

### Independent Verification

Third parties can reproduce hashes exactly.

### Audit Reproducibility

Historical authority verification outcomes remain verifiable.

## See also

* `/packages/signing`
* `/packages/execution`
* `/packages/verifier`
* `/verification/attestations`
* `/architecture/trust-portability`