Skip to content

v0.1.4

Choose a tag to compare

@thatsme thatsme released this 16 Sep 10:13
· 25 commits to main since this release

Documentation only — no code change from 0.1.3.

Every document audited against the code

All shipped documents were checked claim by claim against the implementation:
README.md, SCRIBA_ARCHITECTURE.md, MIGRATION.md, every @moduledoc and public
@doc in lib/, examples/bank/README.md and bench/README.md. 39 claims
the code contradicts were corrected. No document was treated as evidence for
another.

The ones that would have misled someone building on this:

  • :skip and the cursor. The README and Scriba.Target.Ecto both said a
    handler :skip still advances its stream's cursor. It does not — the
    pipeline rejects every :skip from stream_advances, whether it came from
    dedup or from the handler.
  • Commit failures and dead-lettering. Scriba.Target and
    Scriba.DeadLetter said commit failures are never dead-lettered.
    Integrity-class ones are, in their own transaction, with error_kind
    "commit:<SQLSTATE>".
  • What halts a projection. Documented as structural errors only. A batch
    in which every attempted write fails on integrity grounds also halts, and
    :halt_reason is then {:integrity_wipeout, n} rather than a
    Postgrex.Error.
  • Replay verification. Three places still claimed the test double discards
    failed messages "so the suite cannot replay anything". It requeues them in
    position order, and the suite exercises that path.
  • Dead-letter arrival paths: five, not two — multi-key collisions and
    unapplicable handler returns bypass the retry layer entirely.

Also corrected: the Coordinator state struct (11 fields, not 7), the halt
transition (accepted from every state, not just :running), Scriba.Info's
:halt_reason field, the DDL in §8 and §9 (:utc_datetime_usec is
timestamp, not timestamptz), P1's assertion (it reads the target's commit
log, not handle/2), two dual-emit telemetry sites, the §12 file layout, the
Scriba.Source behaviour (a GenStage producer plus Broadway.Acknowledger,
not Broadway.Producer), :commanded's dependency grouping, the missing
:halted case in pause/1 and resume/1, MIGRATION.md's claim that
multi-key collisions raise ArgumentError (they dead-letter), and
bench/README.md's pre-watermark throughput figures.

A full documentation audit is now a release gate (architecture §14), because
auditing only the documents a change touches is what let these survive:
documents drift against code they never mention.

Changed

  • mix docs now generates without warnings. Internal modules carry
    @moduledoc false, so every deliberate mention of one — the telemetry
    catalog naming its emitters, the architecture guide naming processes, this
    file naming what changed — produced a "references … but it is hidden"
    warning. :skip_code_autolink_to in mix.exs lists those names, so they
    render as plain code instead of failing to link. A warning now means a
    genuinely broken reference.

  • Throughput figures in the README and Scriba.Source.Commanded re-measured
    after the 0.1.3 acknowledgement change, on 5,000 events over 100 streams:
    9.1 events/sec at the adapter default, 6,002 with buffer_size: 500.