alkblobs/tasks/changelog-and-readme.md

id, name, status, depends_on, scope, risk, impact, level

id	name	status	depends_on	scope	risk	impact	level
changelog-and-readme	CHANGELOG.md (v0.1.0) and the root README	completed	crate-docs docs-consistency-review feature-graph-verification	moderate	low	project	implementation

Description

The release-facing prose, written after the docs and matrix work so it describes verified reality.

CHANGELOG.md — the first entry, [0.1.0], in the family's Keep-a-Changelog form (precedent: alkcall/CHANGELOG.md, alkstore/CHANGELOG.md — the two-line header citing Keep a Changelog and Semantic Versioning, a dated prose-led entry, link references at the foot). Content: the initial release's full surface, written from the shipped crate — the Store facade (put/get/stat/range, pins and batches, sweep), the five engines (kv: sqlite default / postgres / mem; large: local / pg-lo), fleet GC (DB-backed pins, sweep lease, delete arbitration), the feature-gated ops module (alkcall-backed op family, ACL mapping, pin tokens), the git-family canonical hash and key encoding, and the fuzzing posture (the sidecar targets + the corpus-replay gate). The alkstore 0.1.0 entry is the closest shape precedent (an initial release's prose summary); the date is the release-prep date. Link refs point into docs/architecture/ ADRs where the entry names a decision.

README.md — written last, honestly (the plan's words). Precedent: alkcall/README.md, alktty/README.md, alksocks/README.md. Shape:

• Tagline (the manifest description's territory: content-addressed blob storage, multi-hash, pluggable backends, transport-agnostic).
• What it is / is not: the store layer only — no transport, no protocol in-core; ops rides alkcall behind a default-off feature (ADR-001's posture, stated plainly).
• Quick start: construct a store (the default dual-tier shape and one feature-gated variant), put/get round trip, a pin + sweep taste. Examples must compile against the real API — verify them (a doc-test or a manual compile against the built crate), not from memory.
• The feature table (ADR-013 §4's graph: default features, what each engine feature pulls).
• The engine table (tier / engine / feature / durability posture — one honest line each; pg-lo's named deltas included).
• Pointers: docs/architecture/ as the spec/ADR record, CHANGELOG, license (MIT OR Apache-2.0).

No overselling: no claims the crate doesn't make (no benchmarks beyond the recorded POC numbers' posture, no "production-ready" beyond what the gates prove).

Acceptance Criteria

• CHANGELOG.md exists with the [0.1.0] entry in the family format; the surface summary matches the shipped crate
• README.md exists with tagline / posture / quick start / feature + engine tables / pointers
• README examples verified against the real API (compile-checked)
• Feature and engine tables match ADR-013 §4 and the shipped constructor surface
• No claims beyond shipped reality (the honesty bar the wave-12 review audits)

References

• /workspace/@alkdev/alkcall/CHANGELOG.md and README.md (format and shape precedent)
• /workspace/@alkdev/alkstore/CHANGELOG.md (the 0.1.0 initial-release entry shape)
• docs/architecture/decisions/013-…-feature-graph.md §4 (the feature table's source)
• docs/architecture/backends-and-dispatch.md (the engine table's source)

Notes

• CHANGELOG.md — the [0.1.0] - 2026-10-16 entry in the alkcall / alkstore Keep-a-Changelog form (two-line header, prose-led entry, link references at the foot pointing into docs/architecture/decisions/). The prose covers the full shipped surface: the Store facade, pins and batches, the GC protocol, the five engines (durability postures stated per engine), fleet GC, the feature-gated ops module, and the fuzzing posture.
• README.md — tagline (the manifest description's territory), the is/is-not posture (store layer only; ops default-off, ADR-001), three quick-start examples (mem round trip + pin/sweep taste, the default dual-tier sqlite shape, the feature-gated kv_only_postgres variant), the ADR-013 §4 feature table, the engine table (tier/engine/feature/durability), and pointers (architecture docs, CHANGELOG, fuzz README, license). Every claim cross-checked against the shipped constructors, the facade docs, ADR-013 §4, and backends-and-dispatch.md — two honesty corrections found during that pass are worth recording: the sweep's refuse-to-run posture (zero registered liveness sources aborts with NoLivenessSources, so the quick start shows that rather than an invented reap), and read_range's slice digest is carried out-of-band by the caller, not an in-core read-gate (verification-on-get fires on the kv tier's materialized reads; ADR-006).
• tests/readme_examples.rs (kept) — the durable compile-check: each fence's call shape runs against the real API; the pg row is feature-gated and runs against the harness env, server-less it is absent like the conformance pg columns. Implementation lesson recorded there: a standalone tokio_postgres::connect client must have its Connection future spawned or every query hangs (the first draft hung exactly that; the engine's own harness does it right).
• Cargo manifest untouched — readme = "README.md" and the exclude list's fuzz/ belong to publish-prep, per the wave-12 decomposition.
• The interrupted first pg-column run left three schema debris mints (alkblobs_readme_pg_kv_*); dropped manually against the harness.

Summary

Both release-facing prose files landed as the wave-12 gate's final authoring step. CHANGELOG.md carries the family-format [0.1.0] entry summarizing the shipped crate with ADR link refs (ADR-001/002/ 003/005/006/007/008/009/012/013/014/015/016/017) and a Verified block recording the real numbers. README.md describes verified reality at the honesty bar: no capabilities beyond shipped constructors, no benchmark claims beyond the recorded POC posture, quick-start examples executable against the crate. Verified: the full block — cargo test 209 (default features) and 460 under --all-features, both against the live pg harness; both clippy configurations -D warnings clean; cargo fmt --check clean; cargo doc --no-deps warning-free; the fuzz corpus-replay gate 7/7.