feat(planning): add phases 10-17 to v0.4.1 roadmap (#467)

* feat(planning): add phases 10-15 to v0.4.1 roadmap

Map remaining v0.4.1 milestone issues to new phases:
- Phase 10: Code cleanups (#461, #466)
- Phase 11: Collection.ForkCount (#460)
- Phase 12: Delete with limit (#439)
- Phase 13: OpenRouter embeddings compatibility (#438)
- Phase 14: Twelve Labs EF (#190)
- Phase 15: Cloud RRF/GroupBy test coverage (#462)

* feat(planning): add phases 11-12, renumber 11-15 to 13-17, add #456 to phase 10

New phases:
- Phase 11: Fork double-close bug (#454)
- Phase 12: SDK auto-wiring research (#455)

Updated:
- Phase 10 now includes registry test cleanup (#456)
- Old phases 11-15 renumbered to 13-17
- Phase 13 (ForkCount) depends on phases 11+12

Author: tazarov

.planning/PROJECT.md

@@ -22,7 +22,15 @@ Go applications can use Chroma and embedding providers through a stable, portabl
 
 ### Active
 
-None — all v0.4.1 milestone requirements validated.
+- Convenience constructors reduce Content API verbosity for common modality+source combinations — Phase 9
+- Duplicated path safety utilities consolidated, *context.Context anti-pattern fixed, registry test cleanup added — Phase 10 (issues #456, #461, #466)
+- Fork() double-close bug fixed for shared EF pointers — Phase 11 (issue #454)
+- SDK auto-wiring behavior traced and documented against official Chroma SDKs — Phase 12 (issue #455)
+- Collection.ForkCount provides Go parity with upstream /fork_count endpoint — Phase 13 (issue #460)
+- Delete operations support optional limit parameter matching upstream — Phase 14 (issue #439)
+- OpenAI embedding function supports OpenRouter provider preferences and encoding_format — Phase 15 (issue #438)
+- Twelve Labs multimodal embedding provider added — Phase 16 (issue #190)
+- Cloud integration tests cover Search API RRF and GroupBy primitives end-to-end — Phase 17 (issue #462)
 
 ### Recently Validated
 
@@ -32,7 +40,7 @@ None — all v0.4.1 milestone requirements validated.
 
 ### Out of Scope
 
-- Shipping every provider on the new multimodal contract in this milestone — Gemini and VoyageAI validate the foundation, remaining providers adopt later
+- Shipping every provider on the new multimodal contract in this milestone — Gemini, VoyageAI, and Twelve Labs are in scope; remaining providers adopt later
 - Replacing or removing existing `EmbeddingFunction` and image-only multimodal APIs — backwards compatibility is an explicit acceptance criterion
 - Changing collection/query semantics outside the embedding abstraction boundary — keep the milestone scoped to shared embedding foundations
 
@@ -64,4 +72,4 @@ None — all v0.4.1 milestone requirements validated.
 | Pivot Phase 7 from vLLM/Nemotron to VoyageAI | vLLM lacks NVOmniEmbedModel support; VoyageAI multimodal validates portability with text/image/video | ✓ Good |
 
 ---
-*Last updated: 2026-03-23 — v0.4.1 milestone complete. All 8 phases executed: shared contract, capabilities, registry, intent mapping, docs, Gemini multimodal, VoyageAI multimodal, provider documentation and changelog.*
+*Last updated: 2026-03-25 — v0.4.1 milestone expanded to 17 phases: added fork double-close bug (#454), SDK auto-wiring research (#455), registry test cleanup (#456) alongside prior additions.*

.planning/ROADMAP.md

@@ -6,7 +6,7 @@ This roadmap initializes GSD planning for the current brownfield milestone focus
 
 ## Milestones
 
-- 🚧 **v0.4.1 Provider-Neutral Multimodal Foundations** - Phases 1-9 (current planning milestone)
+- 🚧 **v0.4.1 Provider-Neutral Multimodal Foundations** - Phases 1-17 (current planning milestone)
 
 ## v0.4.1 Provider-Neutral Multimodal Foundations
 
@@ -23,6 +23,14 @@ This roadmap initializes GSD planning for the current brownfield milestone focus
 - [x] **Phase 7: Voyage Multimodal Adoption** - Wire VoyageAI into the shared multimodal contract with text, image, and video support to validate the foundation end-to-end.
 - [x] **Phase 8: Document Gemini and VoyageAI multimodal embedding functions** - Update provider docs, add runnable examples, update README, create changelog. (completed 2026-03-23)
 - [ ] **Phase 9: Convenience Constructors and Documentation Polish** - Add shorthand constructors to reduce Content API verbosity and update docs.
+- [ ] **Phase 10: Code Cleanups** - Extract shared path safety utilities, fix *context.Context anti-pattern, add registry test cleanup. (issues #456, #461, #466)
+- [ ] **Phase 11: Fork Double-Close Bug** - Fix EF pointer sharing in Fork() that causes double-close on client.Close(). (issue #454)
+- [ ] **Phase 12: SDK Auto-Wiring Research** - Trace contentEmbeddingFunction auto-wiring behavior in official Chroma SDKs. (issue #455)
+- [ ] **Phase 13: Collection.ForkCount** - Add ForkCount endpoint support for upstream /fork_count API. (issue #460)
+- [ ] **Phase 14: Delete with Limit** - Add delete-with-limit support for upstream limit parameter. (issue #439)
+- [ ] **Phase 15: OpenRouter Embeddings Compatibility** - Add first-class OpenRouter support via provider preferences and encoding_format. (issue #438)
+- [ ] **Phase 16: Twelve Labs Embedding Function** - Add Twelve Labs multimodal embedding provider. (issue #190)
+- [ ] **Phase 17: Cloud RRF and GroupBy Test Coverage** - Add cloud integration tests for Search API RRF and GroupBy primitives. (issue #462)
 
 ## Phase Details
 
@@ -162,8 +170,17 @@ Plans:
 | 4. Provider Mapping and Explicit Failures | 2/2 | Complete   | 2026-03-20 |
 | 5. Documentation and Verification | 2/2 | Complete   | 2026-03-20 |
 | 6. Gemini Multimodal Adoption | 2/2 | Complete   | 2026-03-20 |
-| 7. Voyage Multimodal Adoption | 0/2 | Planning complete | - |
-| 8. Document Gemini and VoyageAI | 0/2 | Planning complete | - |
+| 7. Voyage Multimodal Adoption | 2/2 | Complete | 2026-03-22 |
+| 8. Document Gemini and VoyageAI | 2/2 | Complete | 2026-03-23 |
+| 9. Convenience Constructors | 0/0 | Not started | - |
+| 10. Code Cleanups | 0/0 | Not started | - |
+| 11. Fork Double-Close Bug | 0/0 | Not started | - |
+| 12. SDK Auto-Wiring Research | 0/0 | Not started | - |
+| 13. Collection.ForkCount | 0/0 | Not started | - |
+| 14. Delete with Limit | 0/0 | Not started | - |
+| 15. OpenRouter Embeddings | 0/0 | Not started | - |
+| 16. Twelve Labs EF | 0/0 | Not started | - |
+| 17. Cloud RRF/GroupBy Tests | 0/0 | Not started | - |
 
 ### Phase 9: Convenience Constructors and Documentation Polish
 
@@ -179,3 +196,117 @@ Plans:
 
 Plans:
 - [ ] TBD (run /gsd:plan-phase 9 to break down)
+
+### Phase 10: Code Cleanups
+**Goal:** Consolidate duplicated path safety utilities into a shared internal package, fix the *context.Context pointer-to-interface anti-pattern across embedding providers, and add registry test cleanup to prevent global state leaks.
+**Depends on:** Phase 9
+**Issues**: #456, #461, #466
+**Success Criteria** (what must be TRUE):
+  1. A shared `pkg/internal/pathutil` package provides `ContainsDotDot`, `ValidateFilePath`, and `SafePath` utilities.
+  2. Gemini, Voyage, and default_ef use the shared path utilities instead of local duplicates.
+  3. Gemini, Nomic, and Mistral use `context.Context` (not `*context.Context`) for DefaultContext.
+  4. Registry tests use `t.Cleanup` with unregister helpers to prevent global state leaks.
+  5. All existing tests pass without modification.
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /gsd:plan-phase 10 to break down)
+
+### Phase 11: Fork Double-Close Bug
+**Goal:** Fix EF pointer sharing in Fork() that causes the same underlying embedding function resource to be closed twice when client.Close() iterates cached collections.
+**Depends on:** None (independent, but should precede ForkCount work)
+**Issues**: #454
+**Success Criteria** (what must be TRUE):
+  1. Forked collections do not double-close shared EF resources when client.Close() is called.
+  2. Both `embeddingFunction` and `contentEmbeddingFunction` ownership is handled correctly.
+  3. Tests cover Fork + Close lifecycle without panics or use-after-close errors.
+  4. Existing fork tests continue to pass.
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /gsd:plan-phase 11 to break down)
+
+### Phase 12: SDK Auto-Wiring Research
+**Goal:** Trace contentEmbeddingFunction auto-wiring behavior in official Chroma SDKs (Python, JavaScript) to verify chroma-go's approach is consistent or document deliberate differences.
+**Depends on:** None (research task, informs Phase 13)
+**Issues**: #455
+**Success Criteria** (what must be TRUE):
+  1. Python SDK auto-wiring behavior documented for get_collection, list_collections, and create_collection.
+  2. JavaScript SDK auto-wiring behavior documented for equivalent operations.
+  3. Comparison with chroma-go behavior written up with any recommended changes or documented differences.
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /gsd:plan-phase 12 to break down)
+
+### Phase 13: Collection.ForkCount
+**Goal:** Add `ForkCount(ctx) (int, error)` to the V2 Collection interface with HTTP transport support, matching upstream Chroma's /fork_count endpoint.
+**Depends on:** Phase 11, Phase 12 (benefits from fork bug fix and SDK research)
+**Issues**: #460
+**Success Criteria** (what must be TRUE):
+  1. `pkg/api/v2.Collection` includes `ForkCount(ctx context.Context) (int, error)`.
+  2. HTTP implementation issues `GET .../fork_count` and decodes `{"count": n}`.
+  3. Embedded/local behavior returns an explicit unsupported error.
+  4. Tests cover HTTP happy path, failure path, and embedded unsupported path.
+  5. Forking docs mention the new method.
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /gsd:plan-phase 13 to break down)
+
+### Phase 14: Delete with Limit
+**Goal:** Add limit parameter support to collection delete operations, matching upstream Chroma PRs #6573/#6582.
+**Depends on:** None (independent)
+**Issues**: #439
+**Success Criteria** (what must be TRUE):
+  1. Delete operations accept an optional limit parameter.
+  2. HTTP transport sends the limit when specified.
+  3. Tests cover delete-with-limit happy path and edge cases.
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /gsd:plan-phase 14 to break down)
+
+### Phase 15: OpenRouter Embeddings Compatibility
+**Goal:** Extend the OpenAI embedding function to support OpenRouter-specific fields (encoding_format, input_type, provider preferences) and relax model validation for provider-prefixed IDs.
+**Depends on:** None (independent)
+**Issues**: #438
+**Success Criteria** (what must be TRUE):
+  1. `CreateEmbeddingRequest` supports `encoding_format`, `input_type`, and `provider` fields.
+  2. `WithModel` accepts provider-prefixed model IDs (e.g. `openai/text-embedding-3-small`).
+  3. Provider preferences struct covers documented OpenRouter fields with extensibility.
+  4. Existing OpenAI behavior and tests remain unchanged.
+  5. Docs include OpenRouter usage example with `WithBaseURL`.
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /gsd:plan-phase 15 to break down)
+
+### Phase 16: Twelve Labs Embedding Function
+**Goal:** Add a new Twelve Labs multimodal embedding provider supporting text, image, and audio embeddings via the Twelve Labs API.
+**Depends on:** Phase 9 (benefits from Content API foundations)
+**Issues**: #190
+**Success Criteria** (what must be TRUE):
+  1. `pkg/embeddings/twelvelabs` implements dense embedding and Content API interfaces.
+  2. Supports text, image, and audio modalities per Twelve Labs API docs.
+  3. Registered in factory/registry with config round-trip support.
+  4. Tests cover request construction, modality validation, and config persistence.
+  5. Docs and examples added for Twelve Labs provider.
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /gsd:plan-phase 16 to break down)
+
+### Phase 17: Cloud RRF and GroupBy Test Coverage
+**Goal:** Add end-to-end cloud integration tests that exercise Search API RRF and GroupBy primitives against live Chroma Cloud.
+**Depends on:** None (independent, but best run last as test hardening)
+**Issues**: #462
+**Success Criteria** (what must be TRUE):
+  1. RRF smoke test using dense + sparse KNN ranks with `WithKnnReturnRank`.
+  2. RRF weighted/custom-k test proves request acceptance and ordering changes.
+  3. GroupBy MinK/MaxK tests assert per-group caps and flattened limits.
+  4. All tests tagged `cloud` and use existing cloud test infrastructure.
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /gsd:plan-phase 17 to break down)