@spec as_of(module(), row_id(), DateTime.t(), [as_of_opt()]) ::
  {:ok, json_map() | struct()}
  | {:error, :deleted_record | :before_audit_horizon}
  | {:error, {:cast_error, String.t()}}

Returns the row snapshot at a timestamp as a string-keyed map or loaded schema struct.

Use row_history/3 to inspect the captured changes that produced the snapshot. id uses the row_id() scalar or composite-key shapes; invalid key shapes raise ArgumentError.

Returns {:ok, snapshot}, {:error, :deleted_record} when the latest snapshot at or before timestamp was a delete, or {:error, :before_audit_horizon} when the row has no snapshot at or before the requested timestamp. These are outcomes callers branch on, not a lookup miss — a deleted or pre-horizon row is not "absence is a bug" — so There is no ! sibling because deletion and the audit horizon are expected results.

Options

• :repo — Ecto.Repo module. Required.
• :storage_schema — storage schema override. Optional.
• :scope — caller-owned scope value. Optional and opaque to Threadline.
• :scope_query_fn — callback that adds caller scope predicates. Optional.
• :cast — load the captured map into the schema struct. Optional; defaults to false.

Returns

• {:ok, snapshot} — the latest captured row state at or before timestamp.
• {:error, :deleted_record} — the latest change at that time is a delete.
• {:error, :before_audit_horizon} — no captured state exists at or before the timestamp.
• {:error, {:cast_error, message}} — schema loading failed with cast: true.
• Raises ArgumentError for an invalid row key and KeyError when :repo is missing.

Examples

Threadline.as_of(MyApp.User, 42, ~U[2026-01-01 00:00:00Z], repo: MyApp.Repo)
Threadline.as_of(MyApp.LineItem, [tenant_id: 1, id: 5], timestamp, repo: MyApp.Repo)

Results contain column values as captured; redaction is applied when triggers are generated, not on read. Authorize reads with :scope_query_fn.

@spec change_diff(Threadline.Capture.AuditChange.t(), [change_diff_opt()]) ::
  json_map()

Projects a captured %Threadline.Capture.AuditChange{} into a deterministic string-keyed map.

Use Threadline.row_history/3 to obtain linked changes before projecting them. This function delegates to Threadline.ChangeDiff.from_audit_change/2; its default output includes schema and before-value metadata, while format: :export_compat returns the export-compatible field set.

Options

• :format — :primary or :export_compat. Optional; defaults to :primary.
• :expand_insert_fields — boolean. Optional; defaults to false and derives field rows for INSERT changes from data_after.

Returns

• A string-keyed map describing the captured change, with field-level changes and captured values.

Examples

Threadline.change_diff(audit_change)
Threadline.change_diff(audit_change, format: :export_compat)

Results contain column values as captured; redaction is applied when triggers are generated, not on read. Authorize reads with :scope_query_fn.

@spec history(module(), row_id(), [history_opt()]) :: [
  Threadline.Capture.AuditChange.t()
]

Returns a list of %Threadline.Capture.AuditChange{} rows for one schema record, newest first.

Use row_history/3 for linked change records and cursor paging. This deprecated function keeps its unbounded default and returns plain %AuditChange{} structs; map .audit_change over a row_history/3 result to obtain the same row type.

Structs include :changed_from when present in the row (sparse prior values on UPDATE under an opt-in per-table capture function; nil when disabled or on INSERT/DELETE rows).

id is a bare scalar for a single-column key, or a map or keyword list naming every key field for a composite key (atom- or string-keyed, any order):

Threadline.history(MyApp.User, 42, repo: MyApp.Repo)
Threadline.history(MyApp.LineItem, [tenant_id: 1, id: 5], repo: MyApp.Repo)

Key names are the schema's field names, not database column names — unless a primary_key: override is configured for the table, in which case the override's declared columns are the accepted keys instead. A missing, extra, or misnamed key, a nil value, a scalar for a composite table, or a loaded struct all raise ArgumentError.

History for a table that has since been dropped or renamed, or a key column whose type changed, stays readable: the key's comparison type falls back to the schema field's Ecto type. The one inexact case is a fixed-width char(n) key — the fallback cannot reproduce the database's stored blank-padding, so pass the value already padded to the original column width.

If :scope_query_fn is configured, it should only add predicates: any limit it sets on the query is overridden by :limit's final LIMIT, and the cap counts only rows the scope predicate left in scope.

Options

• :repo — Ecto.Repo module. Required.
• :storage_schema — storage schema override. Optional.
• :scope — caller-owned scope value. Optional and opaque to Threadline.
• :scope_query_fn — callback that adds caller scope predicates. Optional.
• :from — inclusive lower bound on captured_at. Optional.
• :to — inclusive upper bound on captured_at. Optional.
• :limit — positive integer or :infinity. Optional; absent or nil keeps the unbounded legacy default. This caps rows and does not page.

Returns

• A list of %Threadline.Capture.AuditChange{} rows ordered by captured_at and id descending.
• Raises ArgumentError for an invalid row key or limit, and KeyError when :repo is missing.

Examples

Threadline.history(MyApp.User, 42, repo: MyApp.Repo)
Threadline.history(MyApp.LineItem, [tenant_id: 1, id: 5], repo: MyApp.Repo)

Results contain column values as captured; redaction is applied when triggers are generated, not on read. Authorize reads with :scope_query_fn.

@spec row_history(module(), row_id(), [row_history_opt()]) ::
  [Threadline.Investigation.LinkedChange.t()]
  | Threadline.Page.t(Threadline.Investigation.LinkedChange.t())

Returns a list of %Threadline.Investigation.LinkedChange{} or a %Threadline.Page{} for one schema row, ordered newest first.

Use timeline/2 to inspect changes across rows. A list is capped at 200 entries by default; use cursor: to walk the full history page by page. limit: caps a list and cannot be combined with cursor:.

Options

• :repo — Ecto.Repo module. Required.
• :storage_schema — string. Optional. Selects a Threadline storage schema override.
• :scope — caller-owned value. Optional. Opaque to Threadline and passed to :scope_query_fn.
• :scope_query_fn — function. Optional. Adds the caller's scope predicates to the read.
• :from — DateTime. Optional. Inclusive lower bound on captured_at.
• :to — DateTime. Optional. Inclusive upper bound on captured_at.
• :limit — positive integer or :infinity. Defaults to 200 most recent changes; cannot be combined with :cursor.
• :cursor — :start or a prior page cursor. Optional. Returns a page instead of a list; nil raises ArgumentError.
• :page_size — positive integer. Defaults to 1000; only applies with :cursor.

Unknown keys raise ArgumentError naming the allowed keys.

Returns

• A list of linked changes, capped at 200 by default, or a %Threadline.Page{} when :cursor is set.
• Raises ArgumentError for an unknown option, an invalid key shape, or incompatible paging options.

Examples

Threadline.row_history(MyApp.LineItem, [tenant_id: 7, id: 42], repo: MyApp.Repo)

first = Threadline.row_history(MyApp.LineItem, 42, repo: MyApp.Repo, cursor: :start)
Threadline.row_history(MyApp.LineItem, 42, repo: MyApp.Repo, cursor: first.cursor)

Results contain column values as captured; redaction is applied when triggers are generated, not on read. Authorize reads with :scope_query_fn.

@spec row_history(module(), row_id(), [row_history_filter()], [
  row_history_legacy_opt()
]) ::
  [Threadline.Investigation.LinkedChange.t()]
  | Threadline.Page.t(Threadline.Investigation.LinkedChange.t())

Returns a list of linked changes for one schema row using the retired (filters, opts) shape and its unbounded default.

Use row_history/3 and pass limit: :infinity to keep the unbounded behavior. The filters argument accepts only row-history filters. For duplicate :repo, :from, or :to keys, the value in filters takes precedence over the value in opts, preserving the legacy call's ordering.

Filters

• :repo — Ecto.Repo module. Optional when supplied in opts.
• :from — inclusive lower bound on captured_at. Optional.
• :to — inclusive upper bound on captured_at. Optional.

Options

• :repo — Ecto.Repo module. Required.
• :storage_schema — storage schema override. Optional.
• :scope — caller-owned scope value. Optional and opaque to Threadline.
• :scope_query_fn — callback that adds caller scope predicates. Optional.
• :from — inclusive lower bound on captured_at. Optional.
• :to — inclusive upper bound on captured_at. Optional.
• :limit — positive integer or :infinity. Optional; defaults to :infinity for this deprecated shape.
• :cursor — :start or a prior row-history cursor. Optional; returns a page.
• :page_size — positive integer. Optional; applies with :cursor.

Unknown keys raise ArgumentError naming the allowed keys.

Returns

• A list of %Threadline.Investigation.LinkedChange{} rows.
• Raises ArgumentError for invalid filters, options, or row keys, and KeyError when :repo is missing.

Examples

Threadline.row_history(MyApp.User, 42, [from: start_time], repo: MyApp.Repo)

Results contain column values as captured; redaction is applied when triggers are generated, not on read. Authorize reads with :scope_query_fn.

@spec row_history_page(module(), row_id(), [row_history_filter()], [
  row_history_page_opt()
]) ::
  Threadline.Page.t(Threadline.Investigation.LinkedChange.t())

Returns a %Threadline.Page{} of linked changes for one schema row using the retired first-page convention.

Use row_history/3 with cursor: :start and optional page_size:. An absent or nil cursor here still begins the first page.

Filters

• :repo — Ecto.Repo module. Optional when supplied in opts.
• :from — inclusive lower bound on captured_at. Optional.
• :to — inclusive upper bound on captured_at. Optional.

Options

• :repo — Ecto.Repo module. Required.
• :storage_schema — storage schema override. Optional.
• :scope — caller-owned scope value. Optional and opaque to Threadline.
• :scope_query_fn — callback that adds caller scope predicates. Optional.
• :from — inclusive lower bound on captured_at. Optional.
• :to — inclusive upper bound on captured_at. Optional.
• :limit — positive integer or :infinity. Optional.
• :cursor — :start or a prior row-history cursor. Optional; an absent or nil value begins the first page.
• :page_size — positive integer. Optional; defaults to 1000.

Unknown keys raise ArgumentError naming the allowed keys.

Returns

• A %Threadline.Page{} of matching linked changes.
• Raises ArgumentError for invalid filters, options, cursor, or row keys, and KeyError when :repo is missing.

Examples

Threadline.row_history_page(MyApp.User, 42, [from: start_time], repo: MyApp.Repo)

Results contain column values as captured; redaction is applied when triggers are generated, not on read. Authorize reads with :scope_query_fn.

@spec timeline([timeline_filter()], [timeline_opt()]) :: [
  Threadline.Capture.AuditChange.t()
]

Returns captured AuditChange rows across tables in descending capture order.

Use timeline_page/2 when a large investigation window needs stable keyset traversal. timeline/2 reads the matching rows as one list.

Filters

• :repo — Ecto.Repo module. Optional when supplied in opts.
• :table — string or atom. Optional. Matches table_name.
• :table_schema — string or atom. Optional. Matches the captured host schema.
• :actor_ref — %ActorRef{}. Optional. Matches the transaction actor.
• :from — DateTime. Optional. Inclusive lower bound on captured_at.
• :to — DateTime. Optional. Inclusive upper bound on captured_at.
• :correlation_id — non-empty string. Optional. Matches linked action correlation with strict inner-join semantics.

Options

• :repo — Ecto.Repo module. Required.
• :storage_schema — string. Optional. Selects a Threadline storage schema override.
• :scope — caller-owned value. Optional. Opaque to Threadline and passed to :scope_query_fn.
• :scope_query_fn — function. Optional. Adds the caller's scope predicates to the read.

Unknown keys raise ArgumentError naming the allowed keys.

Returns

• A list of matching %Threadline.Capture.AuditChange{} rows.
• Raises ArgumentError for invalid filters or repository options.

Examples

Threadline.timeline([table: "users"], repo: MyApp.Repo)

Results contain column values as captured; redaction is applied when triggers are generated, not on read. Authorize reads with :scope_query_fn.

@spec timeline_page([timeline_filter()], [timeline_page_opt()]) ::
  Threadline.Page.t(Threadline.Capture.AuditChange.t())

Returns a %Threadline.Page{} of captured AuditChange rows in timeline order, using the same filters as timeline/2.

Use timeline/2 when one eager list is the simpler read. A cursor walk gives large investigation windows stable keyset traversal; stop when has_more is false.

Filters

• :repo — Ecto.Repo module. Optional when supplied in opts.
• :table — string or atom. Optional. Matches table_name.
• :table_schema — string or atom. Optional. Matches the captured host schema.
• :actor_ref — %ActorRef{}. Optional. Matches the transaction actor.
• :from — DateTime. Optional. Inclusive lower bound on captured_at.
• :to — DateTime. Optional. Inclusive upper bound on captured_at.
• :correlation_id — non-empty string. Optional. Matches linked action correlation with strict inner-join semantics.

Options

• :repo — Ecto.Repo module. Required.
• :storage_schema — string. Optional. Selects a Threadline storage schema override.
• :scope — caller-owned value. Optional. Opaque to Threadline and passed to :scope_query_fn.
• :scope_query_fn — function. Optional. Adds the caller's scope predicates to the read.
• :page_size — positive integer. Defaults to 1000.
• :cursor — :start or a prior page cursor. Optional. nil raises ArgumentError.

Unknown keys raise ArgumentError naming the allowed keys.

Returns

• A %Threadline.Page{} of matching changes.
• Raises ArgumentError for invalid filters, repository options, or cursor, and KeyError when :repo is missing.

Results contain column values as captured; redaction is applied when triggers are generated, not on read. Authorize reads with :scope_query_fn.

Examples

first = Threadline.timeline_page([table: "users"], repo: MyApp.Repo)
Threadline.timeline_page([table: "users"], repo: MyApp.Repo, cursor: first.cursor)