HEDDLE

Concepts

The oplog

The append-only record of every action taken in a Heddle repo. Captures, retries, aborts, conflicts, contexts, signatures, redactions — they all land in the oplog. The oplog is the source of truth: the working state can be reconstructed entirely from oplog replay, and any corruption can be repaired from it.

What's in the oplog

Every action that changes the repository's state writes one or more entries. An entry carries: timestamp, actor, action kind, before-state pointer (if applicable), after-state pointer (if applicable), payload, and a checksum chained to the previous entry.

User-facing action kinds — the operations a contributor explicitly performs and might want to inspect:

  • Snapshot — a new state was written to a thread.
  • Checkpoint — a cheap addressable save intended for agent-style frequent saves; filtered out of the human-default heddle log, still goto-able.
  • Goto — HEAD moved to a different state.
  • Fork — a thread was forked from a state.
  • Collapse — multiple states were squashed into one.
  • ThreadCreateV2 / ThreadDelete / ThreadUpdate — thread lifecycle. ThreadCreate (V1) is retained as a read-only legacy variant; new recordings use ThreadCreateV2.
  • MarkerCreate / MarkerDelete — marker lifecycle.
  • FastForwardV2 — fast-forward merge into a thread. FastForward (V1) is retained as a read-only legacy variant.
  • Redact — a redaction was declared on a blob in a specific state. Reversible via heddle undo --allow-redact-undo; refused once the underlying bytes have been purged.
  • Purge — the bytes referenced by an earlier Redact were physically removed. Irreversible by design.

Internal machinery — transaction envelopes and lifecycle events recorded for forensics and replay determinism:

  • TransactionCommit / TransactionAbort — transaction envelopes recorded so the audit trail shows what was folded in or what would have applied.
  • EphemeralThreadCollapse — an ephemeral thread's TTL elapsed and its pointer was retired; the states behind it remain addressable.
  • ConflictResolved — a structured conflict was resolved through ConflictService::Resolve or its CLI front-end.

Replay vs the working state

The working state of a repo (the threads, the states the threads point to, the contexts active at any location) is a derived view of the oplog. Anything you can see from a regular command can be recomputed by replaying the oplog from scratch.

This makes the oplog the trust root. If the materialized views ever disagree with the oplog, heddle fsck --repair rebuilds the views from the oplog. The reverse is never true — the oplog is never derived from anything else.

Rebuild materialized views from the oplog

bash$ heddle fsck --full --thorough --repairok · 14,302 objects rebuilt · 1 stale ref repaired

Query patterns

Because the oplog is structured (not freeform text), heddle query can ask precise questions:

  • "Show every signature by anan@heddle.sh in the last 30 days."
  • "Show every capture from claude-opus-4.7 on task/biscuit-*."
  • "Show every retry preceded by an abort in the same thread."

A structured oplog query

bash$ heddle query --actor anan@heddle.sh --kind review_sign --since 30d14 signatures over 14 days  task/biscuit-authz · ed25519:a8f3c1d7 · 2026-05-09  task/payments-retry · ed25519:8b7c2d… · 2026-05-08  ...

Recovery

The oplog is the canonical record. If the local store is corrupted (disk failure, bad sectors, a botched manual edit), recovery works from the oplog:

  1. heddle fsck walks the oplog from the last verified checkpoint, replays each entry, and rebuilds the materialized state.
  2. Any entry whose checksum doesn't chain correctly is surfaced; the operator decides whether to drop it or recover from an upstream replica.
  3. The repaired state is written back. The original corrupted bytes are quarantined for forensics.

Performance

The oplog is append-only and per-repo, so the only write-time cost is one local fsync. The cost of replay grows with oplog size, but in practice replays are rare — they happen on fsck/repair, on remote sync, and on first clone. Routine reads use the materialized views, which are already up to date.

For very large repos (millions of captures), the oplog supports checkpointing — periodic compacted snapshots that let replay start from a known good state instead of walking from the beginning. heddle maintenance index manages checkpoints automatically.

Compared to Git

GitHeddle
git reflog heddle oplog (via heddle query)

Reflog records ref movements per-clone. Heddle's oplog records every action, ever, and replicates across clones. Reflog forgets; oplog remembers.

git fsck heddle fsck --repair (oplog-driven)

Git's fsck checks integrity; Heddle's fsck additionally rebuilds materialized views from the oplog when they drift.

audit log (external) heddle query

Git teams build their own audit tooling on top of webhooks. Heddle ships the structured query primitive in the binary.

The commands

  • heddle query — structured oplog queries (reference page lands in the next docs pass).
  • heddle fsck — verifies oplog integrity and rebuilds views from it.
  • heddle doctor — surfaces slow-growing oplog problems (bloat, undersized checkpoints).

Related: attribution and signing for how oplog entries are authenticated, and redaction and purge for what happens when an oplog entry needs to be retracted.