alkstore/tasks/release-readme.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
release-readme	Crate README (written last, honestly) + LICENSE + CHANGELOG	completed	release-crate-docs release-deployment-matrix release-contract-window-close release-findings-2-3-disposition release-n1-growth-posture	narrow	low	component	implementation	wave-8 docs readme

Description

The plan's wave-8 "crate README (written last, honestly)" — the root README.md does not exist yet, and it is written last so it describes the shipped thing, not the intended one. Its dependencies are the wave's other doc-shaped tasks for exactly that reason.

1. README.md (root, the crates.io-facing front page): what alkstore is (one reactive store interface — notify, streams, queues, locks, scheduler, outbox — over SQLite, Postgres, and the in-process mem engine), the crate family table (which crate to pick, per ADR-016's compile-time engine identity), the honest posture lines per engine (single-host file-backed / multi-host / honest-ephemeral, never fleet-valid), a minimal usage sketch (compile-checked against the real API — the mem engine is the zero-config example carrier), the contract-suite pointer (three engines, one pinned contract), and the license note. No aspirational claims: only what waves 1–7 shipped.
2. LICENSE files: LICENSE-MIT + LICENSE-APACHE at the root per the family pattern (alkcall/alksocks ship both; the workspace license = "MIT OR Apache-2.0" field is set but no license files exist). The substrate's in-tree dual-license notice (ADR-018) stays as landed — the root files do not replace it.
3. CHANGELOG.md: seeded per the family pattern — the 0.1.0 initial-release entry summarizing the contract v1 surface and the three engines (honest, brief; the family's changelogs are release-note-shaped, not commit logs).
4. Per-crate readme wiring: decide whether each published crate's [package] readme points at the root README or gets its own short crate-specific readme (the engines' lib docs already carry their posture — a pointer-style per-crate readme is the likely honest shape); land the decision.
5. Honesty cross-check: every README claim traceable to a spec (core-contract.md, deployment.md, the engine specs) — this is the "written last, honestly" discipline, and the review gate will audit it.

Acceptance Criteria

• Root README.md exists: family table, per-engine honest postures, compile-checked usage sketch, suite pointer, license note; no aspirational/unshipped claims
• LICENSE-MIT + LICENSE-APACHE at the root (MIT + Apache-2.0 canonical texts); ADR-018's in-tree substrate notice untouched
• CHANGELOG.md seeded with the 0.1.0 entry
• The per-crate readme wiring decided + landed
• Every README claim traceable to a spec (the trace list in Notes)
• Workspace gates green (docs-only expected)

References

• docs/plans/implementation.md §Wave 8 (written last, honestly)
• docs/architecture/overview.md (the family/feature source)
• docs/architecture/deployment.md (the posture lines)
• docs/architecture/decisions/016-deployment-honesty.md, docs/architecture/decisions/018-provenance-register-and-cherry-picks.md
• /workspace/@alkdev/alkcall/README.md + CHANGELOG.md (the family pattern)

Notes

To be filled by implementation agent

Per-crate readme wiring — decision: pointer-style per-crate readmes. Each of the four published crates gets its own short README.md (role + one honest posture paragraph + the constructor line) and [package] readme = "README.md" is wired in its Cargo.toml. Rationale: a [package] readme = "../README.md" puts workspace-relative links into crates.io-rendered markdown, where they break, and the engines' lib docs already carry their posture in depth — so the per-crate readme summarizes honestly and links back to the root README via absolute repository URLs (git.alk.dev). The contract-suite crate is publish = false — no readme. The root README's docs links are workspace-relative (they render on the git forge, which is where the root README lives).

Usage-sketch compile check: the root README's snippets were extracted into a scratch crate (/tmp/opencode/readme-check/) with path deps on all four published crates — compiled clean and ran (the mem queue round-trip passes its assertions; alkstore_sqlite::open / alkstore_postgres::open / MemStore::new() constructor forms compile, the sqlite open actually opens). Harness artifact noted: the postgres constructor attempt needs enable_all() in the harness runtime for the IO driver (tokio-postgres TCP); the README's constructor-forms block is the constructor sketch, and the engine docs carry the real construction details. The mem round-trip mirrors the crate's lib-doc doctest (which cargo test re-verifies).

Substrate notice untouched: no file under alkstore-sqlite/src/ changed; the bundled LICENSE and register stay as landed (ADR-018).

LICENSE-MIT / LICENSE-APACHE copied from the alkcall family pattern (canonical texts, "Copyright (c) 2025-2026 Alk Development"); the workspace license = "MIT OR Apache-2.0" field matches. CHANGELOG follows the alkcall changelog shape (Keep a Changelog, release-note- shaped, tag-link refs at the bottom — v0.1.0 tag URL per the repo).

Honesty trace list (README claim → spec source)

Root README.md:

• Intro mechanism list + "substrate, made once" framing — docs/architecture/overview.md (intro + §Why this crate exists); feature scope per ADR-002; "durable queues with the transactional enqueue property" verbatim from overview.
• Engine native machinery (watcher / pg_notify+LISTEN / guarded in-process state) — overview intro.
• Store seven-mechanism bullet list — core-contract.md §Mechanism contracts; notify wake discipline — ADR-006 (opaque wake + re-read, commit-boundary delivery); streams offsets + consumer-invoked trim_to — ADR-015; queue claim/backoff/dead-letter/sweep — ADR-010; outbox outbox_enqueue_tx — ADR-014; scheduler @every + leadership + catch-up — ADR-009 / core-contract §scheduler (suite rows scheduler_leadership_discipline, scheduler_bounded_catchup); TTL locks renewal/expiry reclaim — core-contract §named locks (suite row lock_ttl_expiry_and_reacquisition); tx seam drop = rollback — ADR-007/ADR-021.
• Family table roles — overview §Crate family (ADR-001, ADR-016); core "no driver dependencies" — ADR-020 §4.
• SQLite "single-host, file-backed / cross-process on one host verified / NFS two-writers unsupported" — deployment.md §Host semantics (ADR-016, ADR-003).
• Postgres "multi-host native / NoTls every path, v1 TLS effectively unavailable" — deployment.md §Host semantics + §TLS posture (v1) (ADR-004).
• Mem "honest-ephemeral / never fleet-valid / loss on process exit / wasm32-compile-clean" — deployment.md §Host semantics + ADR-024 §2/§5.
• "No runtime capability surface; compile-time identity is the deployment statement" — ADR-016 + deployment.md.
• Usage sketch — compile-checked (above); constructors match alkstore-sqlite/src/store.rs open(path, SqliteOpts) (sync), alkstore-postgres/src/store.rs open(config, PgOpts) (async), MemStore::new() (sync).
• "Three engines, one pinned contract" — the contract-suite crate's lib docs (each engine consumes the suite as a dev-dependency and runs the rows in its test target); ADR-022.
• License note — workspace license field; substrate bundled-notice carrier — ADR-018 + alkstore-sqlite/src/substrate/mod.rs.

Per-crate readmes:

• alkstore/: family/ADR-016 compile-time identity; "no driver dependencies, ever (serde/serde_json sole deps)" — ADR-001/ADR-020 §4.
• alkstore-sqlite/: single-host posture + NFS — deployment.md; "no consumer surface to raise the sync level, NORMAL hardwired" — deployment.md §Durability knobs (the release-matrix correction); bundled-notice note — ADR-018.
• alkstore-postgres/: natively async — ADR-004/ADR-007 (POC-verified); budget max_size + 1 per LISTEN-ing process + deadpool#360 — deployment.md §Connection budgets; NoTls v1 — deployment.md §TLS posture; engine-owned schema (default alkstore) — deployment.md + ADR-010 §8.
• alkstore-mem/: honest-ephemeral / dependency-is-the-declaration / never fleet-valid / per-instance isolation (drop closes receivers) — ADR-024 §2/§4 + crate lib docs; wasm32 sync+time subset — ADR-024 §5
  • deployment.md §Toolchain notes.

CHANGELOG: every statement re-checked against the shipped crates — contract v1 surface listing mirrors core-contract.md and alkstore/src/lib.rs re-exports; engine postures mirror deployment.md; "dependency is the ephemerality declaration" — ADR-024; "closes the pre-release contract-change window" — ADR-017 §2 (class-1 terminates at first release; this is the release the window was written against).

No claims found without a spec source; no aspirational/unshipped features named (no latency numbers — deployment.md's POC profile is pointed to, not copied).

Summary

To be filled on completion

Landed (2026-10-11): root README.md (intro, seven-mechanism interface list, family table with per-engine honest postures, compile-checked + executed usage sketch on the mem crate as the zero-config carrier, contract-suite pointer — three engines, one pinned contract, docs index, license note); LICENSE-MIT + LICENSE-APACHE (family canonical texts); CHANGELOG.md seeded with the 0.1.0 entry (contract v1 surface, three engines and their postures, the ADR-017 window-closing note); per-crate readme wiring decided and landed — pointer-style per-crate readmes for the four published crates with readme = "README.md" wired in each Cargo.toml (contract-suite unpublished, excluded). Substrate notice untouched. Gates: workspace build, full cargo test (15 result blocks green, incl. the mem round-trip doctest), clippy --all-targets -- -D warnings, fmt --check, doc gate (RUSTDOCFLAGS="-D warnings" cargo doc --no-deps), and the fuzz corpus replay (cargo test --manifest-path fuzz/shared/Cargo.toml) all pass. README snippets additionally compile-checked and executed via a scratch crate with path deps on the real published crates.