v1.0.0-Release

V1.0.0 — The Freeze

Aspirational milestone. Pour is a personal passion project; this doc defines what would let me stop calling it "in development" and start calling it "the tool I use."

What V1.0.0 Means

A worthy v1.0.0 is not feature-completeness. It is the moment Pour graduates from project-being-built to tool-being-used, anchored on a single promise:

"I can rely on this for myself, indefinitely, without it being the thing I'm working on."

The bar is "freeze the foundation." v2.0.0 is when I decide I was wrong about the foundation.

The Three Gates

1. Stability Commitment

The config schema is frozen, or has a real migration story (not the aspirational config_version claim noted in the pre-release assessment). A version bump never breaks my own vault.

The correctness floor from [[v1.0.0-pre-release-assessment]] is closed:

  • util::atomic_replace is genuinely atomic on Windows (MoveFileExW + MOVEFILE_REPLACE_EXISTING, or atomicwrites/fs_err).
  • transport/fs.rs::resolve_path rejects .. traversal on the write path, not just the read path.
  • CHANGELOG.md exists with at least v0.1.0 → v0.2.0 → v0.2.1 → v0.2.2 → v0.3.0 → v1.0.0.
  • config_version migration claim in README is either implemented or softened to match reality.

2. Shape Lock-in

Pour has decided what it is and what it isn't. After v1.0.0, breaking changes have a cost.

  • Capture surfaces are settled — terminal at desk, PWA in the wild. No third surface in flight.
  • Field-type model decision made: either FieldType trait or enum frozen with documented lock-in (assessment §C).
  • pub surface is intentional, not accidental. lib.rs re-exports demoted to pub(crate) by default; promotions are deliberate (assessment §E).
  • Public TUI / config types audited for things that exist only for tests (e.g. ApiClient::base_url) — gated behind cfg(test) or removed.

3. Self-sufficient

I could hand it to past-me and they get the value without me on call.

  • README reflects actual schema and tech stack (carry-over from pre-release assessment).
  • field-types, System-Architecture-Overview, pour-design-spec describe the v1.0.0 reality, not an aspirational vision (deviation annotations resolved or accepted).
  • Consolidated keyboard-shortcut reference exists.
  • Project-standards doc exists: error-handling policy, pub discipline, file-size budget, atomic-write helper as the single sanctioned pattern (assessment §Open Docs).

What V1.0.0 Is Not Gated On

Things that look like v1.0.0 work but aren't, for a personal tool:

  • A user count or marketing site. No external users; no acquisition target.
  • Semver-grade backwards compatibility for hypothetical consumers. I am the only consumer. The schema stability commitment in Gate 1 is for me, not them.
  • Every nice-to-have feature — async dynamic-select refresh (ADR-003-Synchronous-TUI-Async-Operations), history pruning, undo before write, plugin/extension system, theme configurability. All deferred or accepted as deviations.
  • Decomposition / dedup work from the pre-release assessment (god-modules, 17× atomic-write block, three JSON stores, Action enum sprawl). Real improvements, but they are quality of life for future-me-the-maintainer, not v1.0.0 gates for me-the-user. (Reframed 2026-04-29: shipped on the decomp branch as Phases 0–6 of pour-v1-decomposition. Closed all four items + 102 net new tests.)
  • Test coverage for tui/configure.rs rendering / key handlers. Worth doing, not a v1.0.0 gate (Closed 2026-04-29 by tests/tui_configure.rs — 52 cases, the assessment's "single biggest test hole heading into v1.0.0".)
  • Automated PWA test infrastructure — every PWA subsystem (offline queue, service worker, sub-form state machine, heatmap aggregation) ships untested by an automated harness. Manual real-device verification is the verification (checklist in v1.0.0-phase2-closeout). Pour is a personal tool with one user; explicit accept-the-gap is the right call. Phase 2 closeout Open Q9 is closed. Revisit at v1.1+ if the test surface ever needs to extend to collaborators.

What Shipped in the Web Branch

The mobile/PWA initiative (Steps A–F, web branch) landed all planned Phase 1 scope:

  • pour serve subcommand — HTTP server on port 8421 (default), 0.0.0.0 binding, QR code + URL printed at startup.
  • Auth — Bearer token (mobile_token in ~/.pour/secrets.toml), constant-time compare, ?token= bootstrap-only.
  • Nine /api/v1/* endpoints — health, config, options, submit, captures, history, presets CRUD + reorder. Shapes locked in pour-api-contract. OpenAPI at pour-openapi.yaml.
  • Embedded PWA — vanilla HTML/CSS/JS (~600 LOC) via rust-embed. Module list, form rendering, submit, history list. "Add to Home Screen" on iOS/Android.
  • Idempotency — in-memory LRU (1024 cap), in-flight TTL 60 s, done TTL 5 min. Idempotency-Key header per contract §9.
  • captured_at — client-supplied ISO 8601 timestamp on submit preserves moment of capture.
  • mobile_visible = false — per-module opt-out from phone interface. config_version bumped to 0.3.0.
  • Test suite extends through unit, engine-layer, and full-stack TCP integration scenarios. As of 2026-04-26: 762 tests passing across 30 test binaries; see cargo test for the current count.

Phase 2 deferred (not shipped on initial web-branch merge): offline queue (IndexedDB) (closed 2026-04-27 — Stream A TASK-2.1.1–2.1.5 landed), service worker app-shell cache (closed 2026-04-27 — Stream A TASK-2.2.1–2.2.3 landed), sub-form overlay for create_template fields (closed 2026-04-27 — Stream B TASK-2.3.1–2.3.5 landed), preset mutation UI (save/edit/delete/reorder from PWA) (closed 2026-04-27 — Stream C TASK-2.4.1–2.4.5 landed), history heatmap on mobile dashboard (closed 2026-04-27 — Stream D TASK-2.5.1–2.5.6 landed: bottom-tab nav, cursor-paginated history list, tap-to-read panel, 90-day heatmap with client-side rollup), TLS, mDNS/pour.local.

Architecture: ADR-005-PWA-Companion, Rust-WASM-Frontend-Tradeoffs, System-Architecture-Overview.

Path from Today

Current state (2026-04-25):

  • Cargo.toml: 0.2.2 (in-flight; only v0.2.0 is git-tagged).
  • Branch web — all Steps A–F complete. The PWA is the last personal capture need; once merged, my own daily-driver requirements are met.
  • Foundation already shipped in v0.2.x — see v0.2.0-Foundation.
  • Next planned tag: v0.3.0 — web/PWA capture surface, when web merges to main.

Likely sequence:

  1. Merge web → main, tag v0.3.0.
  2. Address pre-release assessment Foundations (atomic write, path traversal) and pick decomposition appetite → tag v0.4.0 (or fold into v1).
  3. Lock the three gates → tag v1.0.0.

The PWA has landed. The shortest honest path to v1.0.0 is Foundations + CHANGELOG + schema-stability commitment — everything else is optional polish.

Why This Definition

Calling something v1.0.0 is a promise. For a public library it is a promise to users about API stability. For a personal passion project it is a promise to future-me that I have stopped tinkering with the floor and started building on it. The criteria above are the smallest set that would let me trust that promise — narrower than "feature complete," wider than "it works on my machine."