@spec append(String.t(), struct(), keyword()) :: :ok | {:error, term()}

Appends a single event to the event log for the given event source.

Options

• :client — the client name (default: Chronicle.Client)
• :namespace — overrides the client's default namespace
• :event_sequence_id — event sequence id (default: "event-log")
• :event_source_type — the event source type (default: "Default")
• :event_stream_type — the event stream type (default: "All")
• :event_stream_id — the event stream ID (default: "Default")
• :tags — list of tag strings
• :subject — the identity subject string
• :correlation_id — correlation id override (Chronicle.Correlation.CorrelationId or string)
• :identity — identity override (Chronicle.Identity)
• :causation — causation chain override (list of Chronicle.Auditing.CausationEntry)
• :concurrency_scope — Chronicle.Events.ConcurrencyScope or keyword options with :sequence_number, :event_source_id, :event_stream_type, :event_stream_id, :event_source_type, and :event_types

Returns :ok on success or {:error, reason} on failure.

@spec append_and_wait_for_completion(String.t(), struct(), keyword()) ::
  {:ok, %{success: boolean(), failed_partitions: list()}} | {:error, term()}

Appends a single event, then waits for every observer (reactor, reducer, ++) affected by the append to either reach the appended sequence number or fail.

This is additive rather than a change to append/3's return shape: append/3 and append_many/3 return only :ok | {:error, term()} today (no AppendResult-equivalent carrying a sequence number), so building WaitForCompletion on top of them would either be a breaking change to their return contract or require a second round-trip to re-discover the sequence number. This function does the append and the wait as one call instead.

Mirrors the C# client's AppendResult.WaitForCompletion() extension.

Returns {:ok, %{success: boolean(), failed_partitions: [Chronicle.FailedPartitions.FailedPartition.t()]}} on success (whether or not every observer completed — check :success), or {:error, reason} if the append itself failed.

Options

Same as append/3, plus:

• :timeout — how long to wait for observer completion, in milliseconds (default: 5_000, matching the C# client's default).

@spec append_many(String.t(), [struct()], keyword()) :: :ok | {:error, term()}

Appends multiple events to the event log for the given event source.

All events are appended atomically. Each event must be a struct that use Chronicle.Events.EventType.

Options

Same as append/3, including :event_sequence_id and :concurrency_scope.

@spec append_many_for_event_sources(
  [Chronicle.EventSequences.EventForEventSourceId.t()],
  keyword()
) :: :ok | {:error, term()}

Appends a list of Chronicle.EventSequences.EventForEventSourceId entries as a single atomic append-many, each carrying its own target event source id (and other per-event metadata such as stream type/id, subject, and causation).

Use this when a batch of events needs to target several, possibly different, event source ids in one transaction — e.g. reactor side-effect dispatch (see Chronicle.Reactors.Handler).

Options

• :client — the client name (default: Chronicle.Client)
• :namespace — overrides the client's default namespace
• :event_sequence_id — event sequence id (default: "event-log")

@spec complete_stream(String.t(), String.t(), keyword()) ::
  {:ok, non_neg_integer()}
  | {:error, :default_stream_cannot_be_completed | :already_completed | term()}

Completes a named, non-default stream so that no further events can be appended to it.

The default stream (event stream type "All" paired with the default event stream id) can never be completed. Completing an already-completed stream leaves it in its completed state.

Options

• :client — the client name (default: Chronicle.Client)
• :namespace — overrides the client's default namespace
• :event_sequence_id — event sequence id (default: "event-log")

Returns {:ok, tail_sequence_number} on success, or {:error, :default_stream_cannot_be_completed | :already_completed}.

@spec get_for_event_source(
  String.t(),
  keyword()
) :: {:ok, list()} | {:error, term()}

Returns events for the given event source ID from the event log.

Options

• :client — the client name (default: Chronicle.Client)
• :namespace — overrides the client's default namespace
• :event_sequence_id — event sequence id (default: "event-log")
• :event_types — list of event type modules to filter by (default: all)
• :event_source_type — the event source type to filter by (default: all)
• :event_stream_type — the event stream type to filter by (default: all)
• :event_stream_id — the event stream id to filter by (default: all)

Returns {:ok, [appended_event]} or {:error, reason}.

@spec get_from_sequence_number(
  non_neg_integer(),
  keyword()
) :: {:ok, list()} | {:error, term()}

Returns events from (and including) the given sequence number onward.

Mirrors the Chronicle C# and TypeScript clients' GetFromSequenceNumber().

Options

• :client — the client name (default: Chronicle.Client)
• :namespace — overrides the client's default namespace
• :event_sequence_id — event sequence id (default: "event-log")
• :event_source_id — optional event source id to filter by (default: all)
• :event_types — list of event type modules to filter by (default: all)

Returns {:ok, [appended_event]} or {:error, reason}.

@spec get_next_sequence_number(
  String.t() | nil,
  keyword()
) :: {:ok, non_neg_integer()} | {:error, term()}

Returns the sequence number that will be assigned to the next appended event.

Mirrors the Chronicle C# and TypeScript clients' GetNextSequenceNumber().

Options

Same as get_tail_sequence_number/2.

@spec get_tail_sequence_number(
  String.t() | nil,
  keyword()
) :: {:ok, non_neg_integer()} | {:error, term()}

Returns the tail sequence number for an event sequence.

Options

• :client — the client name (default: Chronicle.Client)
• :namespace — overrides the client's default namespace
• :event_sequence_id — event sequence id (default: "event-log")
• :event_source_type — the event source type to filter by (default: "Default")
• :event_stream_type — the event stream type to filter by (default: "Default")
• :event_stream_id — the event stream id to filter by (default: all)
• :event_types — list of event type modules to filter by (default: all)

@spec get_tail_sequence_number_for_observer(
  module(),
  keyword()
) :: {:ok, non_neg_integer()} | {:error, term()}

Returns the tail sequence number scoped to only the event types that the given reactor or reducer module subscribes to (its @handles declarations).

Mirrors the Chronicle C# client's GetTailSequenceNumberForObserver().

Options

Same as get_tail_sequence_number/2, minus :event_types (derived from observer_module).

@spec has_events_for?(
  String.t(),
  keyword()
) :: {:ok, boolean()} | {:error, term()}

Checks whether an event sequence has events for an event source id.

Options

• :client — the client name (default: Chronicle.Client)
• :namespace — overrides the client's default namespace
• :event_sequence_id — event sequence id (default: "event-log")

@spec redact(non_neg_integer(), String.t(), keyword()) :: :ok | {:error, term()}

Redacts a single event at a specific sequence number, permanently replacing its content for compliance/GDPR erasure. This is destructive and irreversible.

Options

• :client — the client name (default: Chronicle.Client)
• :namespace — overrides the client's default namespace
• :event_sequence_id — event sequence id (default: "event-log")

@spec redact_for_event_source(String.t(), String.t(), [module()], keyword()) ::
  :ok | {:error, term()}

Redacts all events for a given event source, optionally filtered to specific event types. Permanently replaces content for compliance/GDPR erasure. This is destructive and irreversible.

Options

Same as redact/3.