Repository navigation
v0.1.4
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:
:skipand the cursor. The README andScriba.Target.Ectoboth said a
handler:skipstill advances its stream's cursor. It does not — the
pipeline rejects every:skipfromstream_advances, whether it came from
dedup or from the handler.- Commit failures and dead-lettering.
Scriba.Targetand
Scriba.DeadLettersaid commit failures are never dead-lettered.
Integrity-class ones are, in their own transaction, witherror_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_reasonis 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 docsnow 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_toinmix.exslists 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.Commandedre-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 withbuffer_size: 500.