Documents key normalization and per-key ceiling

[johnnyt]

Docs only: two README sections and one section of the StatifierRouter.Binding module documentation. Nothing that any function answers changes.

Key programs (sr-91uk)

Binding.key/2 accepts only a non-empty string and normalizes nothing. Two hazards follow when a document's sources send one id in different shapes:

• an id sent as a number is refused, one key_refused ledger row per event;
• a padded id names a second address, so under create: :if_absent it opens a second execution, and under create: :never it is dropped as :no_execution.

The new README subsection, ### A key program that normalizes, sits under ## An example, where a reader first meets the key program, and before the scope resolver. Its new example is a parcel-delivery join with two bindings, and both use the key program trim(event.parcel_id::string). The existing join example is untouched. The moduledoc gets the same text under ## A key is used as it is answered, with a doctest. That doctest shows the raw program refusing a number and keeping the padding, the normalizing program giving "1042771" for both shapes, and an absent id still refused. The README's two bindings were also evaluated by hand against predicator 9.4.2, the version mix.lock resolves: both match and both give "1042771" for 1042771 and " 1042771 ".

The per-key ceiling (sr-aw0w)

The new ### One key's events, one at a time subsection under ## Broadway first states the ceiling as a property. One key's events step one at a time under the execution's lock, and each delivery that steps it is one transaction of several row writes. So more processors raise the rate across keys and never the rate for one key. It promises no figure. It names the three pressure valves: fold events into one (the host does the folding, because the pipeline has no batchers), a live Statifier.Session for a hot key, and the join done upstream.

Verification

• Full mix quality is green on the committed tree: 436 of 436 tests passed, Dialyzer clean, Docs and Doc links clean. README.md is a gated path here, so the gate applies.
• Sabotage on Binding.key/2, one row per check, each restored byte-equal before the next:
  1. Mutation: the guard accepts a non-string key. Killed: the new doctest failed on the numeric refusal, and so did key/2 refuses a key that is not a string.
  2. Mutation: the accepted key is trimmed. Killed: the new doctest failed on the raw padded key.
• Acceptance, checked against the branch:
  • sr-91uk: both hazards are named in the README and in the moduledoc, and both bindings of the new join carry the coercing and trimming key program.
  • sr-aw0w: the ceiling is stated as a property, the subsection contains no digit, and the three valves are named.
• No changelog fragment: docs only, per changelog.d/README.md.

Provenance

The file map held: README.md and the Binding moduledoc, nothing else. The doctest lives in the moduledoc, so the existing doctest Binding runs it and no test file changed.

Refs: sr-91uk, sr-aw0w