# Journal Cryptography

ZERO journal cryptography makes live decisions, safety refusals, deployment
events, and public proof artifacts verifiable as append-only evidence.

The goal is not to prove that an autonomous decision was correct. The goal is to
prove what the system claimed at the time, what payload was bound into the
journal, what sequence it followed, and which signed root later committed to it.

## Canonical Entry Envelope

Every journal stream uses the `zero.journal.v1` envelope:

```json
{
  "version": "zero.journal.v1",
  "seq": 1024,
  "ts": "2026-05-04T07:00:00Z",
  "stream": "trades",
  "deployment_id": "dep_...",
  "event_type": "trade_closed",
  "payload_hash": "sha256:...",
  "prev_hash": "sha256:...",
  "entry_hash": "sha256:...",
  "signing_key_id": "deployment-ed25519-v1",
  "signature": "base64..."
}
```

`entry_hash` commits to the canonicalized envelope and payload hash. `prev_hash`
links the entry to the prior entry in the same stream. `signature` binds the
entry to the configured Ed25519 journal key.

## Streams

The first public streams are:

- `trades`
- `positions`
- `deployment_events`
- `safety_refusals`
- `config_promotions`
- `decisions`
- `rejections`
- `near_misses`

Every replay or incident postmortem that references a live decision should cite
the stream, sequence, entry hash, daily root hash, and anchor URL when available.

## Daily Root

Each day produces a signed root file:

```text
journal-root-YYYY-MM-DD.json
```

The daily root commits to the final hash for every stream seen that day. A root
is not a substitute for the entries; it is the compact public commitment agents
can use to verify that a replay, postmortem, or proof pack is bound to the same
append-only history.

## Anchoring

ZERO uses staged anchoring:

1. Local verifier and daily signed roots.
2. Trusted timestamp anchoring through OpenTimestamps or Sigstore-style logs.
3. Optional public-chain anchoring when the operational process is stable.

External anchoring is defense in depth. A missing external anchor is a degraded
state, not proof that the journal is false.

## Failure Behavior

| Condition | Behavior |
| --- | --- |
| Hash mismatch | Freeze learning and public proof for the affected stream. |
| Missing sequence | Mark the stream degraded until reconciliation is appended. |
| Invalid signature | Escalate as S1 or S0 depending on live-capital exposure. |
| Anchor publish failure | Keep local signed root, mark the root unanchored. |
| Concurrent append conflict | Freeze the stream and require a reconciliation entry. |

## What The Hash Proves

- The public payload hash was present in the append-only stream.
- The entry followed a specific previous hash in that stream.
- The entry was signed by the configured journal signing key.
- A daily root later committed to the stream tip.
- A replay or postmortem can be checked against the same evidence chain.

## What The Hash Does Not Prove

- It does not prove that the model was right.
- It does not prove that a market signal was profitable.
- It does not reveal private keys, bearer tokens, or proprietary thresholds.
- It does not replace Hyperliquid settlement evidence for executed orders.
- It does not make missing or partial evidence acceptable; those states remain
  public degradations.

## Verifier Commands

The verifier is offline and non-mutating except where an output file is
explicitly requested.

```bash
cd engine
PYTHONPATH=. python3 -m zero.journal.chain wrap --input sample.jsonl --output sample.chain.jsonl --stream trades
PYTHONPATH=. python3 -m zero.journal.chain verify --input sample.chain.jsonl --stream trades
PYTHONPATH=. python3 -m zero.journal.chain root --input sample.chain.jsonl --stream trades --output journal-root.json
PYTHONPATH=. python3 -m zero.journal.root --day 2026-05-04 --output-dir zero/data/journal-roots
PYTHONPATH=. python3 -m zero.journal.anchor --root zero/data/journal-roots/journal-root-2026-05-04.json --provider local
PYTHONPATH=. python3 -m zero.journal.proof_pack --root zero/data/journal-roots/journal-root-2026-05-04.json --output-dir zero/data/proof-packs
```

## Release Gate

A live public account is not launch-grade until:

- live trade entries verify against sidecar payload binding,
- at least one daily root is signed,
- at least one external timestamp anchor is published,
- verifier failure cases are covered by tests,
- replays and postmortems can cite journal root evidence without exposing
  secrets.