Requires Chronicle so its block-form macros can be used.

@spec actor(String.t() | atom(), term()) :: map()

Alias of ref/2, for readability at actor call sites.

@spec at(struct() | module(), audit_options() | term()) ::
  {:ok, struct()} | {:error, Chronicle.Error.t()}

Reconstructs an Ecto record at a version, event, timestamp, or its latest audited state.

Fails with :snapshot_incomplete rather than inventing values when the version omits protected fields, and with :record_deleted for a tombstone.

@spec checkpoint(
  atom(),
  keyword()
) :: {:ok, Chronicle.Integrity.Checkpoint.t()} | {:error, Chronicle.Error.t()}

Reads the current unverified ledger head. This does not establish integrity.

@spec delete(Ecto.Changeset.t() | struct(), audit_options()) ::
  {:ok, struct()} | {:error, Ecto.Changeset.t() | Chronicle.Error.t()}

Deletes an Ecto record and records a signed tombstone atomically.

@spec delete!(Ecto.Changeset.t() | struct(), audit_options()) :: struct()

Raising variant of delete/2.

Executes one grouped unit without establishing context.

Takes a do block or a zero-arity function.

@spec hash(term()) :: Chronicle.Sensitive.t()

Marks a value to be stored as a deterministic SHA-256 fingerprint.

A fingerprint answers correlation questions — did this field change, did it revert to an earlier value, does it match another record — without storing the value.

It is not secrecy. The digest is unsalted, so any value drawn from a small or guessable set (an email address, a phone number, a postcode, a status, a short numeric code) can be recovered by hashing candidates until one matches. Use secret/1 or omit/0 when the value itself must not be recoverable.

@spec health(
  atom(),
  keyword()
) :: {:ok, map()} | {:error, Chronicle.Error.t()}

Checks signing keys, background-verifier status, and external anchor lag without performing a complete verification.

@spec history(struct() | module(), audit_options() | term()) ::
  {:ok, [Chronicle.Version.t()]} | {:error, Chronicle.Error.t()}

Returns signed versions for an Ecto record, newest first.

Accepts a loaded struct, or a schema module plus a primary key. Composite primary keys take a map or keyword list. Defaults to 50 entries; :limit and :offset page through older versions.

@spec insert(Ecto.Changeset.t(), audit_options()) ::
  {:ok, struct()} | {:error, Ecto.Changeset.t() | Chronicle.Error.t()}

Inserts an Ecto changeset and its signed version in one transaction.

Returns {:error, changeset} for invalid domain changes and {:error, %Chronicle.Error{}} when the audit write fails, in which case the domain mutation is rolled back.

@spec insert!(Ecto.Changeset.t(), audit_options()) :: struct()

Raising variant of insert/2.

@spec keys(atom()) :: {:ok, map()} | {:error, Chronicle.Error.t()}

Returns signing-key inventory and availability for a named store.

@spec omit() :: Chronicle.Sensitive.t()

Marks a map field or list item to be dropped entirely.

@spec persist(Chronicle.Event.t(), audit_options()) ::
  {:ok, Chronicle.Event.t()} | {:error, Chronicle.Error.t()}

Persists or buffers a pre-built event.

Set immediate: true to bypass an active group. This is primarily intended for transactional adapters such as Chronicle.Multi.

@spec record(String.t(), map() | audit_options()) ::
  {:ok, Chronicle.Event.t()} | {:error, Chronicle.Error.t()}

Records one audit fact.

Data is a map; options are a keyword list. Unknown option keys raise, so a keyword list passed where data was intended is reported rather than silently dropped.

@spec record!(String.t(), map() | audit_options()) :: Chronicle.Event.t()

Raising variant of record/3.

@spec ref(term()) :: map() | nil

Creates a stable audit reference from a value implementing Chronicle.Identity.

@spec ref(String.t() | atom(), term()) :: map()

Creates a stable audit reference from an explicit type and identifier.

@spec revert(
  struct(),
  audit_options()
) :: {:ok, Ecto.Changeset.t()} | {:error, Chronicle.Error.t()}

Returns a changeset that transitions the current record to a historical version. It never persists the change.

Executes one durable grouped unit, establishing context from its options.

The lower-level primitive behind transaction/3, for non-Ecto providers. Takes a do block or a zero-arity function.

@spec secret(term()) :: Chronicle.Sensitive.t()

Marks a value to be stored as "[REDACTED]".

Records one timed operation and its outcome.

Takes a do block or a zero-arity function. The callback's value is returned unchanged; an exception is recorded as a failure and re-raised.

Chronicle.span "payment.authorize", subject: order do
  Payments.authorize(order)
end

Runs domain changes and all nested audit facts as one signed group in the configured repository transaction.

Takes a do block or a zero-arity function:

Chronicle.transaction "order.checkout", actor: user do
  Chronicle.update!(changeset)
end

The block's value is the transaction result. By default the outcome is a failure only when the block returns :error or {:error, reason}; pass :classify to change that.

@spec update(Ecto.Changeset.t(), audit_options()) ::
  {:ok, struct()} | {:error, Ecto.Changeset.t() | Chronicle.Error.t()}

Updates an Ecto changeset and records its signed version atomically.

@spec update!(Ecto.Changeset.t(), audit_options()) :: struct()

Raising variant of update/2.

@spec verify(
  atom(),
  keyword()
) :: {:ok, Chronicle.Integrity.Checkpoint.t()} | {:error, Chronicle.Error.t()}

Verifies the configured ledger of a named store.

@spec verify_all(
  atom(),
  keyword()
) :: {:ok, map()} | {:error, Chronicle.Error.t()}

Verifies every ledger in a named store, including unsigned-row coverage.