alkstore/tasks/release-publish-prep.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
release-publish-prep	Publish prep — package verification, exclusion check, publish records	completed	release-readme release-flake-investigation	moderate	medium	project	implementation	wave-8 publish

Description

The plan's wave-8 "publish prep": everything short of the manual cargo publish itself (CI and publishing are manual per the plan's decided points — self-hosted Gitea, supply-chain posture; the actual publish is the user's action, post-gate).

1. Package metadata audit: the four published crates currently carry only version/edition/license/repository — description is missing on all four (crates.io requires it). Land honest descriptions per crate; decide the remaining optional fields (keywords, categories, homepage/docs — the family's published crates are the precedent to check) and record the decisions.
2. cargo package verification per published crate (alkstore, alkstore-sqlite, alkstore-postgres, alkstore-mem): each packages clean (no warnings that block, .crate contents inspected), builds + tests from the packaged source (cargo package --no-verify off — let it verify, or verify manually per crate and record which).
3. The publish-exclusion verification (parked from wave 7 — tasks/review-wave-7.md item 4(iii)): the mechanism (exclude = ["fuzz"] on the root workspace) landed; this is the verification that no published package leaks the sidecar — inspect each .crate's file list: no fuzz/ paths, no alkstore-fuzz-shared references, no grown corpora/artifacts. Also verify alkstore-contract-suite (publish = false) and the fuzz sidecar are absent from any package.
4. Path-dep + version records: the engines' alkstore = { version = "0.1", path = … } shape is publish-legal (version bound present) — verify each path dep carries its version bound; record the publish order (core first, then engines — ADR-017 §4.1's pairing) and the version decision (0.1.0 as contract v1's initial release, per ADR-017's semver-is-the-contract discipline) in the task Notes as the publish checklist of record.
5. Substrate packaging check (ADR-013/018): alkstore-sqlite's package includes the in-tree substrate — verify PROVENANCE.md and the dual-license notice ride in the .crate, and the package is honest about carrying them.
6. The publish checklist of record: a Notes section listing the exact manual commands in order (per crate: package → publish), including the dry-run evidence, so the user's publish session is mechanical.

Acceptance Criteria

• description landed on all four published crates; optional metadata decisions recorded
• cargo package clean per published crate (verification posture recorded); .crate contents inspected
• Publish-exclusion verification recorded: no fuzz/sidecar/ contract-suite paths in any package's file list
• Path-dep version bounds verified; publish order + version decision recorded
• Substrate PROVENANCE + license notice confirmed in the alkstore-sqlite package
• The manual publish checklist of record written (commands in order, evidence attached)
• Workspace gates + the fuzz corpus-replay gate green at session end

References

• docs/plans/implementation.md §Wave 8, §Decided points (CI/publishing manual)
• tasks/review-wave-7.md (the parked exclusion verification, item 4)
• docs/architecture/decisions/017-contract-versioning.md §4.1 (the version pin + pairing)
• docs/architecture/decisions/013-fold-substrate-into-sqlite.md + docs/architecture/decisions/018-provenance-register-and-cherry-picks.md (the in-tree substrate's packaging posture)
• docs/architecture/decisions/022-contract-suite-layout.md (the suite is not published)

Notes

Decisions of record

1. Release version — 0.1.0, by user decision at this task (2026-10-11). This contradicted ADR-017 §1's "the initial release is 1.0.0" pin, so a pre-release class-1 amendment was recorded inline in ADR-017 §1 (the window this release closes): contract v1's content ships whole in 0.1.0; the §4.1 manifest pins take the ADR's own pre-1.0 0.y form (alkstore = { version = "0.1", path = … }); breaking changes bump 0.y, additions 0.y.z; the full coupling binds at the future 1.0. Motive recorded: the family's 0.x-initial precedent (alkcall 0.8.1, alktunnels 0.2.1, alksocks 0.1.0, alkblobs 0.1.0). This task's description itself assumed "0.1.0" — the CHANGELOG (release-readme) had seeded it, but the ADR pin was never dispositioned; the discrepancy was raised with the user rather than landing silently in either direction.
2. Optional metadata — homepage / documentation omitted. The family precedent (alkcall/alktunnels/alksocks/alktty/alkblobs) carries neither field on any published crate; docs.rs links are automatic on crates.io and repository is the de-facto homepage. keywords + categories landed per crate (≤5 keywords, lowercase; valid crates.io category slugs). Descriptions follow the family's colon-form one-liners.
3. License texts ride the packages — per-crate LICENSE-MIT / LICENSE-APACHE copies. The texts live at the workspace root, and cargo (1.99) does not package workspace-root license files into member .crates: workspace-inherited license-files was tried first and proved a packaging no-op (verified in a sandbox — the field is accepted and inherited, but cargo's rewrite drops it and the tarball carries no texts), so the field was reverted and the canonical texts copied into the four published crate dirs, where cargo's auto-detect (LICENSE* in the package dir) packages them. The sqlite substrate's separate in-src bundled notice (src/substrate/LICENSE) is unaffected — ADR-018's carrier.
4. Verification posture. cargo package verification (registry resolution + verify build) is core-first by construction: for the engines, the packaged manifest drops the path dep, so packaging/verification must resolve alkstore = "0.1" from the index — which fails pre-core-publish with no matching package named 'alkstore' found … searched: crates.io index (captured twice: cargo package -p alkstore-postgres and cargo publish --dry-run -p alkstore-mem). Posture: core got the full cargo-native path (cargo package clean, verification build green, cargo publish --dry-run green to the "aborting upload due to dry run" line); engines got reconstructed-tree verification: per engine, the exact cargo package --list file set + a hand-normalized publish-shaped manifest (the only semantic deltas from the workspace manifest: the workspace-inheritance concretization and the core dep's registry edge restored as its publish-legal version = "0.1", path = "../alkstore" form — the substitution; the suite stays a path-only dev-dep in the published shape, which consumers never fetch) → cargo build + cargo test green in each. The engines' registry-side verification happens live, in order, at the publish session (checklist below).

Field audit (the evidence)

• cargo package --list per crate saved at the time of the run; the core .crate (the real cargo artifact, target/package/alkstore-0.1.0.crate, 30 files) inspected: license texts at the tarball root, README, the normalized Cargo.toml (concrete fields, path dep dropped), no stray paths.
• Exclusion verification (review-wave-7 item 4(iii)) — clean. Each package's file list diffed against its directory contents (identical mod sort order): no fuzz/ paths, no alkstore-fuzz-shared references, no grown corpora/artifacts in any package; the suite (publish = false) appears in no [dependencies] — engines carry it only as a path-only dev-dep, and it is not a package itself. The workspace exclude = ["fuzz"] holds (fuzz is a separate, excluded workspace). The engines' src/fuzz_surface_tests.rs files DO ride their packages — expected: they are the documented doc-hidden re-export probe tests inside the crate (release-crate-docs), not sidecar leakage.
• alkstore-sqlite substrate — both carriers confirmed in the package: src/substrate/PROVENANCE.md (the full register with fork-point statement and delta entries) and src/substrate/LICENSE (the dual MIT+Apache text + fork-point + modification statements); substrate/mod.rs's module doc names both, and the crate README + root README point at the notice — the package is honest about carrying them (ADR-013 §3 / ADR-018 §1).
• Path-dep version bounds verified: alkstore = { version = "0.1", path = "../alkstore" } on all three engines (the §4.1 carrier 1 manifest pin, pre-1.0 0.y form) and on the suite's dep; no versioned path dep missing its bound.
• Packaged-source test evidence (all green, 2026-10-11): core .crate extracted → 25 + 0 doc-tests; sqlite tree 193 + 25 suite rows + 0; mem tree 102 + 25 + 1 doctest; postgres tree 127 + 25 + 9
  • 0 (postgres rows skip-green without a server env, the same posture as the workspace test run).

The manual publish checklist of record (the user's publish session)

Run from the workspace root; gates are assumed green (this task's evidence; re-run if any later commit touched code):

cargo build
cargo test
cargo test --manifest-path fuzz/shared/Cargo.toml
cargo clippy --all-targets -- -D warnings
cargo fmt --check
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps

# 1. Core first — the engines' packaged manifests resolve `alkstore
#    = "0.1"` from the index; until this lands, cargo package/publish
#    for the engines is impossible (the error this task captured).
cargo package -p alkstore && tar tf target/package/alkstore-0.1.0.crate
#    eyeball: LICENSE-MIT/LICENSE-APACHE at the tarball root, README,
#    no stray paths (this task's evidence: 30 files, all clean).
cargo publish -p alkstore
#    wait for index availability (a minute or two;
#    `cargo search alkstore` resolving is the readiness probe).

# 2. Engines — any order among them (mutually independent); each now
#    packages + verifies fully against the live core:
cargo package -p alkstore-sqlite
tar tf target/package/alkstore-sqlite-0.1.0.crate | grep -E 'LICENSE|substrate'
#    eyeball: LICENSE-MIT/LICENSE-APACHE at the tarball root AND
#    src/substrate/{PROVENANCE.md,LICENSE} riding in-tree.
cargo publish -p alkstore-sqlite

cargo package -p alkstore-postgres && cargo publish -p alkstore-postgres
cargo package -p alkstore-mem       && cargo publish -p alkstore-mem

# 3. Tag + forge release: v0.1.0 (the CHANGELOG's tag link points here).

Summary

Landed (2026-10-11): ADR-017 §1's pre-release class-1 amendment (initial release 0.1.0, user decision — family 0.x-initial precedent, §4.1 pins stay the pre-1.0 0.y form); package metadata on the four published crates (colon-form descriptions, keywords ≤5, categories; homepage/ documentation omitted per family precedent); per-crate LICENSE-MIT + LICENSE-APACHE copies (workspace-inherited license-files proved a cargo-1.99 packaging no-op in a sandbox, reverted — the copies are what cargo's auto-detect packages). Package verification: core full cargo-native (package + verify build + publish --dry-run clean, 30 files); engines blocked pre-core-publish by construction (captured error) — verified from reconstructed exact---list trees with the publish-shaped manifests (core dep as its publish-legal version+path form), all green (sqlite 193+25, mem 102+25+1, postgres 127+25+9). Publish-exclusion verification clean: no fuzz/sidecar/corpora/ suite paths in any package's file list (engines' in-src fuzz_surface_tests.rs are the documented crate-internal probe tests, not leakage); sqlite's package carries src/substrate/PROVENANCE.md + the dual-license src/substrate/LICENSE, documented in mod.rs and the readmes. Path-dep bounds verified on all engines + suite; the manual publish checklist of record (core → engines, per-crate package → eyeball → publish, plus the gates) written into Notes. Gates at session end: build, full cargo test (15 result blocks green), clippy --all-targets -- -D warnings, fmt --check, doc gate (RUSTDOCFLAGS="-D warnings"), fuzz corpus replay — all green.