Write and audit the compressed-index card

The final report explains one binary representation and the evidence behind it. It must not turn a small measured ratio into a universal compression claim.

Goal

Write and audit project-root report.md as a concise compressed-index card whose claims identify the format, prove the equivalence boundaries, and stay within the measured evidence.

Inputs

Use the manifest, ordinal and gap traces, varint trace, payload layout, index.bin and digest, rebuilt index, structural and search comparisons, malformed-stream results, size accounting and plot data, read-back checks, and replay agreement or mismatch.

Deliverables

The card must explain in plain language:

• corpus, tokenizer, index, query, configuration, and format identity;
• document ordinals, first-gap-zero cases, position gaps, and exact round trips;
• the canonical integer groups, continuation rule, zero encoding, shortest encoding, and decoder rejection cases;
• strict length-prefixed UTF-8 dictionary fields and the exact payload stream;
• all positive bounds and defensive checks before allocation or reading;
• the LMP container, version, big-endian payload length, and failure order;
• structural versus search equivalence and their separate evidence;
• complete file sizes versus controlled numeric-stream denominators;
• malformed coverage, artifact names, read-back, replay result, and first mismatch behavior; and
• what the fixture cannot establish about optimality, production readiness, universal size reduction, or speed.

Include one small worked path from a source posting through ordinal and position gaps, integer bytes and offsets, decoded posting, and an equivalence record. Distinguish observations from interpretation and name any first mismatch honestly.

Checks

Audit every sentence against a saved record or explicit format rule. Reject wording that calls the format optimal, production-ready, universally smaller, or faster, or that treats a complete decode as proof of search equivalence. Check that ratios name their value sequence and denominator, complete file sizes are not called controlled compression ratios, and malformed input is not described as recovered.

Check the card names strict UTF-8, canonical integer and gap rules, bounds, container failure order, structural and behavioral comparison, all important zero and first-gap cases, artifacts, read-back, and replay outcome. Readers should be able to locate the evidence behind every numerical claim.

Workspace

Keep the card at the project root as report.md. Do not replace it with a compression gauge or decorative binary illustration. Preserve machine-readable artifacts, bytes, digests, and figures beside it.

Hints

Review

Give the card to someone who has not opened the source code. Can they explain one gap and integer, identify why one malformed stream is rejected, distinguish the two size denominators, and tell whether replay agreed? Mark every sentence that outruns the artifacts.

How to check your work

Checks compare report.md with the evidence-limited reference card after your own audit. The supplied fixture names the byte contract and measurements without claiming optimality, production readiness, or unmeasured speed.