Module annotations 

Annotation sidecar for testbench tapes.

An annotation file (<tape>.annotations.jsonl) is the durable form of human judgment over a recorded run. Each annotation references a tape event by its immutable TapeRecord::seq number and carries a structured kind + evidence + author so downstream pipelines (eval rubrics, friction roll-ups, crystallization candidate detection, replay-for-teaching) can read the same artifact.

File layout

run.tape                    # the unified event tape
run.tape.annotations.jsonl  # annotations sidecar (this format)

Like the tape itself, the annotations file is line-delimited JSON. The first line is a header; every subsequent line is one annotation. Empty lines and lines starting with # are tolerated so external tools can emit comments without breaking interop.

Schema

• Header (one line, always first):

  {
    "type": "header",
    "schema_version": 1,
    "tape_path": "run.tape",
    "tape_content_hash": "<blake3>",
    "harn_version": "0.8.6"
  }

• Annotation (zero or more, after the header):

  {
    "type": "annotation",
    "id": "ann_001",
    "event_id": 42,
    "kind": "hypothesis",
    "evidence": "checkout incident — see runbook",
    "author": {"id": "alice", "kind": "human", "surface": "burin-code"},
    "timestamp": "2026-05-10T17:00:00Z",
    "hypothesis_status": "active"
  }

Optional fields default to their None / empty form so older readers roll forward when newer fields appear. Unknown AnnotationKind values surface as AnnotationKind::Unknown so a validator can still report on the rest.

Structs

Annotation

One annotation record on a tape event. Every field except event_id and kind is optional so authoring tools can emit minimal records.

AnnotationAuthor

Provenance for an annotation. Surfaces the difference between a human who clicked through Burin Code and an agent that auto-flagged a turn during a self-eval.

AnnotationHeader

Header record at the top of every annotations file. Captures the schema version and a back-reference to the tape so a validator can detect mismatched bundles.

AnnotationLink

AnnotationSpan

Span over a contiguous range of events. start_event_id must equal the wrapping annotation’s event_id; end_event_id must be greater than or equal to the start. The validator enforces both invariants.

AnnotationTape

Fully-loaded annotation tape — header plus every record. Built by AnnotationTape::load and consumed by the validator, the replay surface, and the export pipeline.

AnnotationValidationReport

Result of validating annotations against a tape.

CrystallizeAnchor

One event the human-judgment loop has flagged as worth crystallizing. The candidate detector consumes a Vec<CrystallizeAnchor> alongside inferred candidates so the two paths converge into one ranked list.

Enums

AnnotationKind

Closed taxonomy of annotation kinds. New kinds must be added here so the validator can reason about them; older readers receive AnnotationKind::Unknown for kinds they don’t recognize.

AnnotationProblem

Validation problem detected by validate_against_tape. Each variant carries enough context for a CLI report or a CI annotation comment.

AuthorKind

HypothesisStatus

Lifecycle of a hypothesis-kind annotation. Mirrors the human-hypothesis loop in harn-cloud#54 / burin-code#277.

Constants

ANNOTATIONS_SIDECAR_SUFFIX

Conventional sidecar suffix appended to a tape path. run.tape pairs with run.tape.annotations.jsonl.

ANNOTATION_SCHEMA_VERSION

Format version of the annotations sidecar. Bump on any breaking change. Loaders refuse files with a higher version.

Functions

annotation_to_friction_event

Adapt a friction-kind annotation into a FrictionEvent. Returns None when the annotation is not a friction record or is missing the required friction_kind.

annotations_for_record

Convenience: pair a tape record with all annotations that reference its seq. Used by the replay surface and the export pipeline.

compute_tape_content_hash

BLAKE3 hex digest of a tape’s logical content. Implemented by hashing the deterministically-serialized record stream so the digest is stable across runs that produce the same tape — and changes when any record content does.

validate_against_tape

Validate an annotations file against its target tape. Returns a structured report so the CLI can emit either pretty-printed problems or a machine-readable JSON payload.