Skip to content
Chronicle
Search limited to 0.1. Switch to the latest version for up-to-date results.

Recorder

This content is for 0.1. Switch to the latest version for up-to-date documentation.

A recording lifecycle owns one capture scope, one WAL domain, and one finalization path. Public users normally start with command mode:

Terminal window
chronicle record --name checkout -- ./my-app

Command-mode lifecycle

Section titled “Command-mode lifecycle”
  1. Resolve and lock the public data directory.
  2. Prepare the recording identity and bounded WAL domain.
  3. Attach the capture source before starting a supervised command.
  4. Admit normalized events into a bounded queue.
  5. Group-commit evidence to WAL and make loss visible.
  6. Stop on process exit, signal, duration limit, or physical WAL limit.
  7. Recover the authoritative WAL prefix.
  8. Run ETL and publish the canonical session atomically.
  9. Update the advisory catalog only after canonical publication.

A finalization failure does not require recapturing when the recording is recoverable:

Terminal window
chronicle record --retry checkout

Continuous recorder

Section titled “Continuous recorder”

Command, PID, cgroup, and daemon modes share one continuous coordinator. It owns one filesystem domain, epoch rotation, incremental ETL resume, liveness/health metadata, and shutdown cleanup.

This is not an always-on distributed capture service. Recorder state, WAL, manifests, checkpoints, and catalog facts remain local and bounded. Consult the repository’s recorder runbook before operating that advanced path. The current local deployment co-locates the recorder runtime with incremental ETL; that is a topology choice, not logical ownership — ETL remains an independent boundary (see ETL). One .chronicle-domain.lock protects the local filesystem coordination domain; it is not the architectural ownership mechanism between Recorder and ETL.

Stop and recovery

Section titled “Stop and recovery”

The first termination signal drains and finalizes within the configured bounds. A forced termination or capacity limit remains visible in recording metadata and WAL-loss evidence. Recovery repairs only a verified incomplete final tail; it does not hide complete corruption or invent acknowledgement history.