How factos_sqlight Works

Storage

factos_events is an append-only event log ordered by an integer position. Rows store the event id, descriptor data, tags, metadata, and JSON payload.

Dispatch transaction

A dispatch runs inside BEGIN IMMEDIATE:

1. acquire SQLite’s writer lock;
2. read and decode the decision context;
3. fold events and decide the command;
4. verify the append condition;
5. append accepted events in order;
6. run subscriptions on the same connection;
7. commit.

A subscription or storage error rolls back the complete transaction.

Retries

Busy and lock errors retry the complete transaction up to the configured attempt count. Decision functions, codecs, event-id allocation, and subscriptions must therefore be retry-safe.

Domain, subscription, schema, and payload errors are returned without retrying.

Decision contexts

NoContext skips history, AllEvents protects the complete log, and Matching(items:) produces selective type-and-tag predicates.

BEGIN IMMEDIATE prevents another writer from changing the selected context before commit. The explicit FailIfEventsMatch condition remains the shared backend contract.

Recovery

read_after returns globally ordered pages. Checkpoints, replay policy, and projection rebuild state remain application-owned.