202 lines
10 KiB
Markdown
202 lines
10 KiB
Markdown
---
|
||
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
|
||
|
||
- [ ] 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. |