Merge pull request #140 from amikos-tech/feature/phase-05-cloud-integration-testing

Phase 5: Cloud Integration Testing (#139 follow-up)

Author: oss-amikos

.planning/REQUIREMENTS.md

@@ -35,7 +35,7 @@ Requirements for the current milestone. Each maps to roadmap phases.
 
 ### Cloud Integration Testing
 
-- [ ] **CLOUD-01**: Cloud search parity tests cover pagination, IDIn/IDNotIn, document filters, metadata projection, and combined filter scenarios.
+- [x] **CLOUD-01**: Cloud search parity tests cover pagination, IDIn/IDNotIn, document filters, metadata projection, and combined filter scenarios.
 - [x] **CLOUD-02**: Cloud schema/index tests cover distance space variants, HNSW/SPANN config paths, invalid transitions, and schema round-trip assertions.
 - [x] **CLOUD-03**: Cloud array metadata tests cover string/number/bool arrays, round-trip retrieval, and contains/not_contains filter behavior.
 
@@ -71,7 +71,7 @@ Deferred to future milestones.
 | EMB-07 | Phase 4 | Pending |
 | EMB-08 | Phase 4 | Pending |
 | RERANK-01 | Phase 4 | Pending |
-| CLOUD-01 | Phase 5 | Pending |
+| CLOUD-01 | Phase 5 | Complete |
 | CLOUD-02 | Phase 5 | Complete |
 | CLOUD-03 | Phase 5 | Complete |
 

.planning/ROADMAP.md

@@ -16,7 +16,9 @@ Decimal phases appear between their surrounding integers in numeric order.
 - [x] **Phase 2: Collection API Extensions** — Add Collection.fork, Collection.indexingStatus, and cloud feature parity audit.
 - [x] **Phase 3: Search API** — Implement the Search endpoint with ranking expressions, field projection, groupBy, and read levels. (completed 2026-03-22)
 - [ ] **Phase 4: Embedding Ecosystem** — Add sparse/multimodal interfaces, reranking, new providers, and embedding registry.
-- [ ] **Phase 5: Cloud Integration Testing** — Build cloud parity test suites for search, schema/index, and array metadata.
+- [ ] **Phase 5: Cloud Integration Testing** — Build cloud parity test suites for search, schema/index, and array metadata. (gap closure in progress)
+- [ ] **Phase 6: Documentation Site** — Build a rich documentation site with API surfaces, examples, and feature guides (similar to chroma-go docs).
+- [ ] **Phase 7: Working Examples** — Add full working examples for all major features (similar to chroma-go examples/).
 
 ## Phase Details
 
@@ -93,11 +95,12 @@ Plans:
   2. Cloud schema/index tests cover distance space variants, HNSW/SPANN config, invalid transitions, round-trip assertions.
   3. Cloud array metadata tests cover string/number/bool arrays, round-trip retrieval, contains/not_contains filters.
   4. Test suite can run in CI with cloud credentials or be skipped gracefully without them.
-**Plans:** 1/2 plans executed
+**Plans:** 3/3 plans complete
 
 Plans:
 - [x] 05-01-PLAN.md — Schema/index + array metadata cloud tests, mixed-type array client validation
-- [ ] 05-02-PLAN.md — Search parity cloud tests (KNN, RRF, GroupBy, batch, pagination, filters, projection, read levels)
+- [x] 05-02-PLAN.md — Search parity cloud tests (KNN, RRF, GroupBy, batch, pagination, filters, projection, read levels)
+- [x] 05-03-PLAN.md — Gap closure: fix embedding projection assertion and WAL read-level test target
 
 ## Progress
 
@@ -111,4 +114,24 @@ Phase 4 can execute in parallel with Phases 1-3 (independent).
 | 2. Collection API Extensions | 2/2 | Complete | 2026-03-21 |
 | 3. Search API | 3/3 | Complete   | 2026-03-22 |
 | 4. Embedding Ecosystem | 0/TBD | Pending | — |
-| 5. Cloud Integration Testing | 1/2 | In Progress|  |
+| 5. Cloud Integration Testing | 2/3 | In Progress|  |
+
+### Phase 6: Documentation Site
+
+**Goal:** Build a rich documentation site (similar to amikos-tech/chroma-go) covering all library features, API surfaces, and usage examples.
+**Requirements**: TBD
+**Depends on:** Phases 1-5 (documents features built in earlier phases)
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /gsd:plan-phase 6 to break down)
+
+### Phase 7: Working Examples
+
+**Goal:** Add full working examples for all major features, organized by topic, runnable standalone — similar to amikos-tech/chroma-go examples/.
+**Requirements**: TBD
+**Depends on:** Phases 1-5 (examples demonstrate features built in earlier phases)
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /gsd:plan-phase 7 to break down)

.planning/STATE.md

@@ -2,14 +2,14 @@
 gsd_state_version: 1.0
 milestone: v1.5
 milestone_name: milestone
-status: "Phase 03 shipped — PR #139"
-stopped_at: Completed 03-search-api-03-03-PLAN.md
-last_updated: "2026-03-23T08:38:51.785Z"
+status: "Phase 05 shipped — PR #140"
+stopped_at: Completed 05-cloud-integration-testing-05-03-PLAN.md
+last_updated: "2026-03-23T13:51:04.103Z"
 progress:
   total_phases: 10
-  completed_phases: 8
-  total_plans: 23
-  completed_plans: 22
+  completed_phases: 9
+  total_plans: 24
+  completed_plans: 24
 ---
 
 # Project State
@@ -23,8 +23,8 @@ See: .planning/PROJECT.md (updated 2026-03-17)
 
 ## Current Position
 
-Phase: 05 (cloud-integration-testing) — EXECUTING
-Plan: 2 of 2
+Phase: 05
+Plan: Not started
 
 ## Performance Metrics
 
@@ -68,6 +68,8 @@ Plan: 2 of 2
 | Phase 03-search-api P01 | 4 | 2 tasks | 12 files |
 | Phase 03-search-api P02 | 3min | 2 tasks | 6 files |
 | Phase 03-search-api P03 | 90 | 2 tasks | 7 files |
+| Phase 05-cloud-integration-testing P02 | 4 | 2 tasks | 1 files |
+| Phase 05 P03 | 5 | 1 tasks | 1 files |
 
 ## Accumulated Context
 
@@ -137,10 +139,15 @@ Recent decisions affecting current work:
 - [Phase 03-search-api]: SearchResultImpl stores Double scores internally, downcasts to Float on row access per SearchResultRow contract
 - [Phase 03-search-api]: RRF and text queryText skipped via Assume in integration tests — server returns 'unknown variant' for $rrf and rejects string values in $knn.query; tests document intended contract
 - [Phase 03-search-api]: Wire format keys corrected to '$knn'/'$rrf' (dollar-prefixed) — bare 'knn'/'rrf' keys rejected by Chroma server
+- [Phase 05-cloud-integration-testing]: CLOUD-01 search parity tests: GroupBy results via rows() only; ReadLevel WAL uses isolated collection without polling; RRF auto-skipped with Assume.assumeTrue false documenting server limitation; filter matrix 8 sub-scenarios inline; pagination client validation throws IllegalArgumentException before HTTP
+- [Phase 05-cloud-integration-testing]: Embedding projection assertion loosened to accept null or [[null]]: server returns [[null]] for unselected embeddings
+- [Phase 05-cloud-integration-testing]: WAL read-level test uses isolated 3D collection (col) instead of 4D seedCollection to avoid dimension mismatch
 
 ### Roadmap Evolution
 
 - Phase 6 added: Tech Debt Cleanup (DOC-BUG-1, DOC-BUG-2, INFRA-1, INFRA-2, inert assumeMinVersion removal)
+- Phase 6 added: Documentation Site — rich docs with API surfaces, examples, and feature guides (similar to chroma-go)
+- Phase 7 added: Working Examples — full runnable examples for all major features (similar to chroma-go examples/)
 
 ### Pending Todos
 
@@ -152,6 +159,6 @@ None.
 
 ## Session Continuity
 
-Last session: 2026-03-22T18:35:36.178Z
-Stopped at: Completed 03-search-api-03-03-PLAN.md
+Last session: 2026-03-23T13:27:48.062Z
+Stopped at: Completed 05-cloud-integration-testing-05-03-PLAN.md
 Resume file: None