Module jsonl 

Append-only JSONL event log: JsonlLog.

Per BUILD_SPEC §7, the JSONL mirror is a peer to the SQLite store: it provides inspectability (one event per line, grep-able) and disaster recovery (the full ledger can be rebuilt from this file alone). Append-only, fsync-per-write, and hash-chained.

Append protocol

1. The caller hands JsonlLog::append an Event.
2. The log sets prev_event_hash to its current head (or None for the first event).
3. The log re-seals the event via crate::hash::seal, which recomputes both payload_hash and event_hash under the canonical framing.
4. The log writes one JSON line + \n, then fsyncs the file.
5. The new event_hash becomes the head.

Re-sealing on append means callers don’t need to pre-populate the hashes (they’re an artifact of the chain, not the event’s identity).

Why fsync per write

The JSONL log is the disaster-recovery source of truth. An event that is “appended” but lost on power loss leaves the SQL store ahead of the mirror — defeating the mirror’s purpose. We pay the latency cost (~1ms-10ms per write on commodity SSDs) in exchange for crash safety. Higher-throughput modes (group commit, periodic fsync) are a future optimization gated on a config flag and an ADR.

What this module does NOT do

• Replicate the chain to remote storage (out of scope; future ADR).
• Compact or rotate the log (out of scope for v0; planned for Phase 4).
• Index the log (the SQL store is the queryable surface).

Structs

JsonlIter

Owning iterator over a JsonlLog.

JsonlLog

Append-only JSONL log handle.

SignedJsonlIter

Owning iterator over a JsonlLog yielding full SignedRow envelopes (event + optional signature). Used by the Ed25519-aware audit verifier in crate::audit::verify_signed_chain.

Enums

JsonlError

Errors raised by JsonlLog.

Constants

APPEND_ATTESTATION_REQUIRED_RULE_ID

Required contributor rule id documenting that attestation requirements (ADR 0010 §1, ADR 0014 §3, ADR 0026 §4) composed into the policy decision for an unsigned JSONL append. The contributor MUST vote Allow for EventSource::User; the ledger refuses authority-bearing rows that lack attestation.

APPEND_EVENT_SOURCE_TIER_GATE_RULE_ID

Required contributor rule id documenting that the event source tier gate composed into the policy decision for an unsigned JSONL append (ADR 0019 §3, ADR 0026 §2). The ledger refuses EventSource::User rows when the final outcome is PolicyOutcome::Reject or PolicyOutcome::Quarantine.

APPEND_RUNTIME_MODE_RULE_ID

Required contributor rule id documenting that the runtime mode gate (ADR 0037 §2) composed into the policy decision for an unsigned JSONL append. Local-development unsigned ledgers register a Warn; trusted modes register Reject to prevent unsigned rows from being passed off as authority grade.

APPEND_SIGNED_KEY_STATE_CURRENT_USE_RULE_ID

Required contributor rule id documenting that the signing key state at event time satisfies ADR 0023 current-use revalidation for a signed JSONL append. Historical-only or revoked keys vote Reject here.

APPEND_SIGNED_TRUST_TIER_MINIMUM_RULE_ID

Required contributor rule id documenting that the signing principal’s trust tier satisfies the ADR 0019 minimum for a signed JSONL append. Principals below Verified vote Reject here.

SCHEMA_MIGRATION_ATTESTATION_REQUIRED_RULE_ID

Required contributor rule id documenting that a fresh operator attestation (ADR 0010 §1-§2) was supplied over the proposed v1 -> v2 boundary payload. Absent or invalid attestation votes Reject. ADR 0026 §4 forbids BreakGlass substituting for this contributor at the migration authority root.

SCHEMA_MIGRATION_AUTHORITY_CLASS_RULE_ID

Required contributor rule id documenting that the proposing principal sits in the Operator authority class (ADR 0019 §3) for a v1 -> v2 schema migration boundary append. Non-operator principals vote Reject here; the rule is documented as authority-class so a future ADR 0019 §7 scoped tier_admin capability can satisfy the same contributor.

SCHEMA_MIGRATION_CURRENT_USE_TEMPORAL_AUTHORITY_RULE_ID

Required contributor rule id documenting that the signing key supplied for the operator attestation is in current use (ADR 0023 §2 / §5): the key state at attestation time is Active, not Retired or Revoked. A historical-only signing key votes Reject here; ADR 0026 §4 forbids BreakGlass substituting for this contributor.

Functions

append_policy_decision_test_allow

Build a PolicyDecision that satisfies JsonlLog::append inputs for the happy path. Intended for tests and fixtures only.

append_signed_policy_decision_test_allow

Build a PolicyDecision that satisfies JsonlLog::append_signed inputs for the happy path. Intended for tests and fixtures only; see append_policy_decision_test_allow for the production-caller contract.

schema_migration_v1_to_v2_policy_decision_test_allow

Build a PolicyDecision that satisfies JsonlLog::append_schema_migration_v1_to_v2 inputs for the happy path. Intended for tests and fixtures only.