Session handoff — 2026-06-18 (74)

Large session. Continues from handoff-73 (Ctrl-G demo alias). This one ran the road to public availability end to end: a post-merge doc reconciliation, then versioning, installers, crates.io/binstall, the cargo fmt gate, and an actual v0.2.0 release that is now live on crates.io. Three new main-sequence ADRs (0054/0055/0056), one CI-ADR amendment, issue #35 closed.

§1. State

Branch main. 2509 pass / 0 fail / 1 ignored (the long-standing friendly doctest); clippy clean; cargo fmt --check clean (the tree is now stock-rustfmt formatted, and CI gates it). rdbms-playground --version → rdbms-playground 0.2.0.

Released: v0.2.0 — Gitea release with all six D1 targets (Linux/Windows via release.yaml on the tag; macOS via the dispatched release-macos.yaml, ad-hoc-signed). Published to crates.io (cargo install rdbms-playground and cargo binstall rdbms-playground both user-verified).

Push state: earlier commits were pushed (they triggered CI/releases). The most recent commits are unpushed and matter:

3c87dbb macOS nix-prune fix (takes effect next macOS dispatch).
d3af1c4 + 8ebe213 the manual publish.yaml workflow — ADR-0056 in the first, the workflow file itself in the second (git commit -am had skipped the new untracked file).
this handoff. Push main to land them. (Push is the user's step.)

§2. What shipped (commits `628b250`→`d3af1c4`)

628b250 doc reconciliation after the CI + website branch merges: rewrote CLAUDE.md's stale repo-layout tree; added a Website subproject note; fixed the CI note; gitignored .wrangler/ + .vscode/ and removed a tracked website/.vscode/; updated requirements (D1 macOS runtime-verified, DOC1 canonical-docs-on-website) + ADR-ci-003.
c30a611 ADR-0054 — version surfaces. --version/-V + an in-app version command, both reading CARGO_PKG_VERSION via one cli::version_text(). A release-CI guard fails the release unless the v* tag equals v<Cargo.toml version>.
ef99e6c ADR-0055 — scripts/install.sh (curl|sh, POSIX, shellcheck-clean, checksum-verified, ~/.local/bin). Verified end-to-end against the live release. install.ps1 (Windows irm|iex) added later (e9606b5) — written but untested here (no PowerShell on this box; validate on Windows).
e9606b5 ADR-0056 — crates.io + binstall prep. Publish-ready Cargo.toml (dropped publish=false; homepage/keywords/categories/ exclude); README.md; LICENSE-MIT/LICENSE-APACHE (dual, © Lazy Evaluation Ltd) + CONTRIBUTING.md (inbound=outbound); the [package.metadata.binstall] block with per-target overrides (linux-gnu→musl, windows-msvc→gnu/gnullvm; macOS direct).
41b7e9a + ec3c7c3 — #35 fmt gate. One mechanical cargo fmt (stock defaults, 102 files, behaviour-preserving) recorded in .git-blame-ignore-revs; ci.yaml now gates fmt --check (ADR-ci-002 Amendment 1). Closes #35.
88830ed+bd5be5e — v0.2.0 bump + the guard bug. The first release.yaml run failed at the version guard: it piped nix develop -c cargo metadata to node, but the flake devShell prints a banner to stdout, corrupting the JSON. Fixed to a toolchain-free grep -m1 '^version = ' Cargo.toml. The v0.2.0 tag was re-pointed (Option A) to the fix commit; re-run went green.
3c87dbb — macOS nix-prune fix. The prune step's profile dir (~/.cache/rdbms-ci) didn't exist, so nix develop --profile errored (swallowed by || true) → the gc-root was never created → the whole toolchain (~3.8 GiB) was deleted and re-downloaded every run. Added mkdir -p + dropped the || true. Diagnosed from the run-74 log via tea actions runs logs 74.
d3af1c4 — manual publish.yaml. workflow_dispatch + tag input (mirrors release-macos.yaml). Idempotent crates-io job (crates.io API pre-check + cargo publish backstop), independent jobs so Scoop/Homebrew/winget slot in later. ADR-0056 Amendment 1.

§3. Live vs manual vs parked

Automated on a v* tag: release.yaml builds + publishes the four Linux/Windows targets (+ fmt/clippy/test gate).
Manual workflow_dispatch: release-macos.yaml (mac binaries — intermittent runner) and publish.yaml (crates.io now; more registries later). Run them once the tag's build is up.
Parked (user decisions):
- macOS Developer-ID signing. The pipeline ad-hoc-signs (codesign --sign -). The user's Apple Development cert is the wrong type — distribution needs Developer ID Application + notarization (App Store Connect API key recommended). Fine for curl|sh (no quarantine); matters for browser downloads. Details in docs/plans/20260616-public-availability.md.
- Remaining D3: Scoop (lazyeval bucket), Homebrew (lazyeval tap), winget (komac on Linux CI, or manual PR) — each a sibling job in publish.yaml + a manifest repo.

§4. Immediate next steps

Push main (lands 3c87dbb + d3af1c4).
Add the CARGO_REGISTRY_TOKEN secret (crate-scoped, publish-update) so publish.yaml works: tea actions secrets create CARGO_REGISTRY_TOKEN (paste at prompt) or the Gitea UI.
Smoke-test publish.yaml: dispatch it for v0.2.0 — it should idempotently skip ("already on crates.io"), exercising the path risk-free.
The release ritual going forward (ADR-0054): bump Cargo.toml → commit → tag v<x.y.z> → push tag (Linux/Windows release builds) → dispatch release-macos → dispatch publish.

§5. Gotchas learned (don't relearn the hard way)

The flake devShell prints a banner to stdout — never pipe nix develop -c <cmd> into a parser. Read Cargo.toml directly, etc.
Workflow-file source differs by trigger: a tag-triggered run (release.yaml) uses the workflow at the tagged commit; a workflow_dispatch run (release-macos/publish) uses the default branch (main). So fixing a dispatched workflow only needs a main push; fixing a tag-triggered one needs the tag re-pointed.
Version vs tag: Cargo.toml is bare 0.2.0; the git tag is v0.2.0; the guard checks tag == "v" + version; binstall pkg-url spells v{ version }.
CI logs are reachable via tea actions runs logs <id> (and tea actions runs list --output tsv). Use it instead of guessing from a step name.
crates.io API needs a descriptive User-Agent (403 without one).

§6. How to take over

Read handoffs 72 → 73 → 74, CLAUDE.md, docs/requirements.md, and docs/plans/20260616-public-availability.md (the GA roadmap with all decisions + parked items).
Confirm green: cargo test (2509 / 1 ignored), cargo clippy --all-targets, cargo fmt --check.
ADRs for this arc: 0054 (versioning), 0055 (installer), 0056 (crates.io/binstall + the publish workflow); CI side ADR-ci-002 Amendment 1 (fmt gate), ADR-ci-003 (release matrix
- macOS).
Workflow unchanged: phased, test-first, /runda + DA before commits, ADR amendment + README index-upkeep for decided-area changes, confirm commit messages, never push.
Consider a cargo sweep at this milestone (target/ grows).

7.3 KiB Raw Blame History