Operate the V3 event ledger

Harnery records every supported adapter through one canonical V3 ledger at .harnery/ledgers/v3/. Producers and consumers fail closed when its control pair is missing or invalid. There is no alternate recording path.

For the command-purpose evidence attached to tool activity, see Declare tool intent. That guide explains capture precedence and why the durable ledger keeps fingerprints rather than literal intent prose.

Initialization

harn init initializes the ledger automatically. For an existing project, or to repair installation state explicitly, run:

harn ledger-v3 initialize \
  --root <project-root> \
  --approval-record-id <durable-approval-id>

The initializer writes an immutable genesis manifest with the exact schema, build, configuration, capability, and privacy-key digests. It then activates that candidate. Repeating the command is idempotent while the active epoch is compatible.

Use harn init --check in automation. It exits nonzero unless the V3 control pair is active and internally consistent.

Inspect the active epoch

harn ledger-v3 status

The result identifies the control state, genesis and activation events, schema digest, approved producer builds, privacy epoch, and active ledger location. Writers accept only a build named by that control packet.

The validating reader covers every sealed segment in catalog.json plus the active tail. Before the first rotation, an absent catalog is normal and the reader validates active.ndjson directly.

Advance to a new epoch

A contract digest or approved-build change requires a new epoch:

harn ledger-v3 initialize \
  --root <project-root> \
  --approval-record-id <durable-approval-id> \
  --force-new-epoch

The complete current V3 directory moves intact to .harnery/ledgers/v3-archives/. Harnery then creates and activates a fresh epoch. It never edits archived event bytes in place.

Advance only after the new build passes producer conformance, consumer replay, privacy, terminal-race, rotation, and run-quality boundary tests. Sessions that started under the archived epoch remain audit evidence and do not become part of the new epoch retroactively.

At a live hook or command boundary, Harnery automatically performs this archive and replacement only when the current runtime can prove that the stored schema or active adapter capability profiles are incompatible. The bootstrap lease serializes concurrent boundaries. A supported adapter bridge then opens one new session generation and restores the session’s private task, lifecycle, and file-claim projection through canonical coordination events. Private task text and lifecycle reasons stay out of the ledger.

This automatic path does not cover a missing ledger, damaged control packet, or any state whose cause is ambiguous. Those states keep the writer gate closed and require the explicit recovery process below.

Backup and recovery

harn backup snapshot includes ledgers/ by default along with durable coordination state. Disposable caches in active/ and process attribution in pid-map/ are rebuilt from live V3 observations and are not backup authority.

If an active control pair is damaged, producers and authority-bearing commands stop rather than inventing state. The command error names the unavailable V3 control or session generation instead of reporting only a missing process-map entry. Restore the complete V3 epoch from a verified backup or initialize a new epoch with an explicit approval record. Do not copy individual rows or synthesize missing lifecycle events.

Evidence boundary

Run-quality evidence begins at the activation event of the current approved epoch. A generation qualifies only when it starts after that boundary, reaches an authoritative terminal, passes the validating reader, and carries the exact schema, build, configuration, capability, and privacy attestations required by the collector.