--- id: release-readme name: Crate README (written last, honestly) + LICENSE + CHANGELOG status: completed depends_on: [release-crate-docs, release-deployment-matrix, release-contract-window-close, release-findings-2-3-disposition, release-n1-growth-posture] scope: narrow risk: low impact: component level: implementation tags: [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 - [x] Root `README.md` exists: family table, per-engine honest postures, compile-checked usage sketch, suite pointer, license note; no aspirational/unshipped claims - [x] `LICENSE-MIT` + `LICENSE-APACHE` at the root (MIT + Apache-2.0 canonical texts); ADR-018's in-tree substrate notice untouched - [x] `CHANGELOG.md` seeded with the 0.1.0 entry - [x] The per-crate readme wiring decided + landed - [x] Every README claim traceable to a spec (the trace list in Notes) - [x] 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 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 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.