harn ledger-v3

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.

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.

Closed-epoch retention

Closed epochs are local audit and recovery evidence, not an unlimited second copy of all coordination history. Harnery keeps at least the newest two complete epochs. Outside that floor, it selects epochs older than seven days and then the oldest epochs needed to fit a 1 GiB byte budget.

Preview the exact policy and candidates before changing the filesystem:

harn ledger-v3 archives list
harn ledger-v3 archives clean
harn ledger-v3 archives clean --yes

The mutating command recalculates the complete plan before every removal. It deletes only a still-complete epoch-<timestamp> directory whose size and last modification match the preview. Unknown directories, symlinks, unreadable trees, and the newest minimum remain untouched.

Set repository-specific limits in .harnery/config.jsonc:

{
  "events": {
    "archive_max_bytes": 1073741824,
    "archive_max_age_days": 7,
    "archive_keep_min": 2,
    "archive_auto_clean": true
  }
}

The daily session-start janitor runs the same guarded cleanup. Set archive_auto_clean to false when a project must keep every closed epoch locally, but provide another bounded retention mechanism in that case.

Sealed V1 shards

A hard-fenced project no longer appends to V1, so those shards are finite but can still occupy substantial disk. legacy-compress replaces non-terminal loose shards with gzip files only after the hard fence passes, the source digest remains unchanged, and every logical row matches the compressed copy.

harn ledger-v3 legacy-compress
harn ledger-v3 legacy-compress --yes

The terminal shard named by V1-SEALED.json remains loose because its exact digest is part of the fence. Existing .gz files also remain unchanged.

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 a durable frame makes the active authority invalid, producers and authority-bearing commands stop rather than inventing state. Recover it explicitly:

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

Recovery moves the complete failed directory into v3-archives/ without editing it. A fresh epoch receives only a new genesis and activation. Events after the rejected frame are preserved in the archive but never copied into the new authority.

The command writes a hash-only receipt under v3-recoveries/. It records the failed authority digest, the validated-prefix digest, the first diagnostic and event witness, the archive directory, and the new genesis and activation IDs. It does not retain event bodies. Canonical reads expose these failed-epoch receipts beside the readable current epoch. Repeating the command against the same new authority returns the existing receipt instead of creating another epoch.

Use this operation only when ledger-v3 status reports ledger_integrity_failure. For other control damage, restore the complete V3 epoch from a verified backup. Do not copy individual rows, edit timestamps, 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.