From 6f0d4c47a7c4f594ebccb925d0e1a14822659442 Mon Sep 17 00:00:00 2001 From: Andrew Hu Date: Sat, 7 Feb 2026 14:08:07 -0500 Subject: [PATCH 1/3] =?UTF-8?q?docs(v1-readiness):=20=F0=9F=93=9D=20add=20?= =?UTF-8?q?v1.0=20release=20criteria=20and=20dogfooding=20tracker?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Normative readiness document defining 30 verifiable criteria across 9 categories that must all pass before v1.0 can be tagged. Includes dogfooding registry with per-project evidence tracking and a quarry template pre-populated. - Gate rule: all criteria must pass, none waived - Criteria: API freeze, manifest freeze, Dataset dogfooding, Volume dogfooding, error paths, S3 verification, known limitations, documentation completeness, data correctness - Each criterion has an evidence block for date/observer/issue tracking - Out-of-scope section explicitly excludes CAS, Zarr, perf, new adapters - ARCH_INDEX.md updated with reference to new document Co-Authored-By: Claude Opus 4.6 --- docs/ARCH_INDEX.md | 1 + docs/V1_READINESS.md | 316 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 317 insertions(+) create mode 100644 docs/V1_READINESS.md diff --git a/docs/ARCH_INDEX.md b/docs/ARCH_INDEX.md index 4dee1e2..07cba7b 100644 --- a/docs/ARCH_INDEX.md +++ b/docs/ARCH_INDEX.md @@ -29,6 +29,7 @@ Do not update for internal refactors. Plans, contracts, and research notes. Contracts define **system behavior**. - `IMPLEMENTATION_PLAN.md` — contract-first, phased implementation plan +- `V1_READINESS.md` — v1.0 release criteria and dogfooding evidence - `VOLUME_DIRECTION.md` — product direction for the Dataset + Volume dual-paradigm model - `contracts/CONTRACT_CORE.md` — core model invariants and immutability - `contracts/CONTRACT_WRITE_API.md` — write API semantics and errors diff --git a/docs/V1_READINESS.md b/docs/V1_READINESS.md new file mode 100644 index 0000000..12cc18e --- /dev/null +++ b/docs/V1_READINESS.md @@ -0,0 +1,316 @@ +# V1_READINESS.md — v1.0 Release Criteria + +This document defines the **non-negotiable criteria** that must all pass +before Lode can be tagged v1.0. + +Stability is proven by **usage and time**, not design review. + +--- + +## Gate Rule + +- Every criterion below must be checked off with recorded evidence. +- Evidence must reference a real downstream project, real data, and a real observer. +- No criterion may be waived — if it cannot be met, it must be renegotiated and this document updated. +- The v1.0 tag is blocked until all criteria pass. + +--- + +## Dogfooding Registry + +Each downstream project that integrates Lode gets a subsection here. +Use the template to add new projects as they begin integration. + +### quarry + +- **Integration date:** TBD +- **Contact:** TBD +- **Usage profile:** Dataset / Volume / Both +- **Storage backend:** AWS S3 +- **Status:** Not started + +| Criterion | Validated | Date | Notes | +|-----------|:---------:|------|-------| +| Dataset write round-trip | | | | +| Volume write round-trip | | | | +| Error sentinels observed | | | | +| API friction (none = pass) | | | | + + + +--- + +## Criteria + +### 1. API Surface Freeze + +- [ ] No public type, function, or method signature has changed for 4+ weeks after first downstream integration + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] No new sentinel errors added for 4+ weeks after first downstream integration + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] `PUBLIC_API.md` matches exported symbols in `lode/api.go` with zero discrepancies + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] Option / VolumeOption surface has not expanded since dogfooding began + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +### 2. Manifest Format Freeze + +- [ ] `Manifest` struct fields unchanged for 4+ weeks + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] `VolumeManifest` struct fields unchanged for 4+ weeks + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] Owner sign-off on manifest JSON schema as v1.0 wire format + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +### 3. Dataset Dogfooding + +- [ ] At least one consumer writing Dataset snapshots to S3 for 2+ weeks + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] At least one consumer reading Dataset snapshots back (round-trip) for 2+ weeks + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] At least 100 Dataset snapshots committed and read with no corruption + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] No Dataset API changes required to support integration + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +### 4. Volume Dogfooding + +- [ ] At least one consumer using StageWriteAt + Commit with real data + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] At least one consumer using ReadAt on committed ranges + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] At least 3 Volume snapshots committed with cumulative manifests in a real workflow + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] No Volume API changes required to support integration + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +### 5. Error Path Validation + +- [ ] ErrNoSnapshots observed and handled correctly by a downstream consumer + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] ErrPathExists observed in real storage confirming immutability enforcement + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] ErrNotFound observed and handled correctly for a missing snapshot lookup + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +### 6. S3 Backend Verification + +- [ ] AWS S3 used for Dataset and Volume writes/reads during dogfooding with no adapter errors + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] Non-AWS backend caveat documented in README and PUBLIC_API.md as known v1.0 limitation + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +### 7. Known Limitations Accepted + +- [ ] Single-writer semantics documented as v1.0 limitation in README + PUBLIC_API.md + contracts + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] Context cancellation cleanup nondeterminism documented as best-effort, no correctness impact + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] Deferred test gaps (ITER-LIFECYCLE, COMP-WRAPPER-ORDER, ERR-RANGE-NOT-SUPPORTED) accepted as non-blocking + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +### 8. Documentation Completeness + +- [ ] README "Status" section updated to v1.0 language + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] All 13 contract files reviewed — no "planned"/"draft"/"future" language for shipped features + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] All examples pass (`task examples`) + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] CHANGELOG includes v1.0 entry summarizing stability commitment + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +### 9. Data Correctness + +- [ ] Zero silent data corruption during dogfooding (Dataset or Volume) + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] Zero manifest deserialization failures on same-version data + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +- [ ] Zero snapshot history inconsistencies (forked history, missing parent, duplicate ID) + +> **Evidence:** _not yet recorded_ +> Date: — | Observer: — | Project: — +> Summary: — +> Issue: #___ + +--- + +## Out of Scope for v1.0 + +The following are explicitly **not blockers** for the v1.0 release: + +- Content-addressable storage (CAS) +- Zarr codec support +- New codecs beyond Parquet +- Performance benchmarking or optimization +- New storage adapters beyond S3 +- Compaction or garbage collection +- Multi-writer / distributed coordination +- Query planning or execution + +These may become goals for v1.1+ but must not gate the initial stability release. + +--- + +## References + +- `PUBLIC_API.md` — public API shape and defaults +- `docs/contracts/CONTRACT_CORE.md` — core model invariants +- `docs/contracts/CONTRACT_WRITE_API.md` — write API semantics +- `docs/contracts/CONTRACT_READ_API.md` — read API contract +- `docs/contracts/CONTRACT_VOLUME.md` — Volume persistence model +- `docs/contracts/CONTRACT_ERRORS.md` — error taxonomy +- `docs/contracts/CONTRACT_TEST_MATRIX.md` — contract-to-test traceability +- `docs/contracts/CONTRACT_STORAGE.md` — storage adapter obligations From c84a689ae65d4690a72f6315cd2d0cce508751bc Mon Sep 17 00:00:00 2001 From: Andrew Hu Date: Sat, 7 Feb 2026 14:31:43 -0500 Subject: [PATCH 2/3] =?UTF-8?q?docs(v1-readiness):=20=F0=9F=94=92=20add=20?= =?UTF-8?q?privacy=20rule=20for=20private=20project=20dogfooding?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Private downstream projects use redacted aliases and backend-agnostic usage descriptions. Evidence blocks and issue references must not leak private context — private tracker issues referenced as (private). Co-Authored-By: Claude Opus 4.6 --- docs/V1_READINESS.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/V1_READINESS.md b/docs/V1_READINESS.md index 12cc18e..b2d2780 100644 --- a/docs/V1_READINESS.md +++ b/docs/V1_READINESS.md @@ -10,7 +10,7 @@ Stability is proven by **usage and time**, not design review. ## Gate Rule - Every criterion below must be checked off with recorded evidence. -- Evidence must reference a real downstream project, real data, and a real observer. +- Evidence must reference a real downstream project (or redacted alias), real data, and a real observer. - No criterion may be waived — if it cannot be met, it must be renegotiated and this document updated. - The v1.0 tag is blocked until all criteria pass. @@ -21,6 +21,13 @@ Stability is proven by **usage and time**, not design review. Each downstream project that integrates Lode gets a subsection here. Use the template to add new projects as they begin integration. +**Privacy rule:** Only public projects are listed by name. Private projects +use a redacted alias (e.g. `private-A`, `private-B`) and describe their +usage profile in backend-agnostic terms — no internal project names, +repo URLs, or domain-specific details. Evidence summaries and issue +references must not leak private context; if a linked issue lives in a +private tracker, reference it as `(private)` instead of by number. + ### quarry - **Integration date:** TBD @@ -37,13 +44,14 @@ Use the template to add new projects as they begin integration. | API friction (none = pass) | | | |