Skip to content

chore: re-measure every resource-cost claim, and regenerate the examples that produce them #767

Description

@DavidCozens

Every claim the project makes about flash, RAM and stack cost is measured from the
two example stacks. Those stacks are stale, and #750 has moved the default they
were measured against, so the figures the release would ship are wrong. This is the
last story before #650 cuts 0.1.0, so that the release carries measured sizes.

The examples are the instrument

solid-syslog-example (CMake, 15 commits) and solid-syslog-example-make (Make,
22 commits) teach integration one commit at a time, each stage measured. The
history is the artefact, so an early commit cannot be patched without rewriting
every SHA after it. Both are regenerated as a stack rather than fixed piecemeal.

Neither is broken today: each pins the library (e4bc54d via FetchContent,
0d212aa via submodule), so both still build. They demonstrate an old API against
an old pin - stale, not failing. Nothing in docs/, the README or the website
cites an example commit SHA, so the rewrite breaks no inbound link.

Sequencing

  1. Regenerate both stacks on current main, measuring each stage.
  2. Correct every cost claim below from those measurements, and re-derive the
    sizing narrative described under Not just the figures.
  3. Cut 0.1.0 release #650 cuts 0.1.0, shipping the corrected docs.
  4. Re-pin both stacks to the release tag if the cut moved the SHA. The release
    commit changes no library source, so the figures should stand - confirm rather
    than re-measure.

Carry into the regeneration

Three breaking refactors land between the pins and main. Each fails to compile,
deliberately - no compatibility aliases were left:

Also:

Resource-cost claims

Nothing here is adjusted on paper. The known inventory:

  • README.md:14-16 - the headline figures: +5 KB flash / 0.4 KB RAM for a
    record on the wire, +13.5 KB flash / 37 KB RAM for the whole path.
  • docs/hardening-path.md - a **Cost.** line on each of the twenty stages,
    plus the reconciliation paragraph quoting 13.5 KB against the ~13.9 KB the
    column sums to.
  • The example repositories themselves, which carry the exact figures, the diff
    that produced each, and the reasoning behind it.
  • The website, which is outside this repository and needs checking against the
    same measurements rather than assumed consistent.

Not just the figures

Stages 7, 13 and 14 of docs/hardening-path.md are a sizing narrative - take
the default, hit truncation at a 256-byte cap, double it to 512, then shrink the
ring - and it is written against a 2048-byte default. At 480 the premise of each
stage changes: stage 7 is no longer mainly a reduction, and stage 13's "double the
cap to 512" is a slight raise above the default rather than a doubling. Re-derive
the narrative, then measure it.

Done when

  • Both stacks rebuild on main, commit by commit.
  • Every figure above is measured at the new default, and the sizing narrative
    follows from the default the library now ships.
  • The website carries no cost claim that disagrees with the measurements.
  • The licence prose in both repos states the library's licence correctly.
  • After the cut, both stacks pin the release and their figures are confirmed.

Metadata

Metadata

Assignees

No one assigned

    Labels

    choreMaintenance, tooling, and infrastructure

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions