Phase 10: Code Cleanups (#470)

* docs(10): capture phase context

* docs(state): record phase 10 context session

* docs(10): research phase domain

* docs(phase-10): add validation strategy

* docs(10): create phase plan

* refactor(10-01): extract shared pathutil package from duplicated provider code

- Create pkg/internal/pathutil with ContainsDotDot, ValidateFilePath, SafePath
- Replace local containsDotDot in gemini/content.go and voyage/content.go
- Replace local safePath in default_ef/download_utils.go
- Add comprehensive unit tests for all three functions

* fix(10-01): replace *context.Context pointer-to-interface with context.Context value

- Fix Gemini DefaultContext from *context.Context to context.Context
- Fix Nomic DefaultContext from *context.Context to context.Context
- Fix Mistral DefaultContext from *context.Context to context.Context
- Remove unnecessary pointer indirection and address-of operations

* docs(10-01): complete path safety and context anti-pattern plan

- Add 10-01-SUMMARY.md with execution results
- Update STATE.md with phase 10 progress
- Update ROADMAP.md plan progress
- Mark CLN-01, CLN-02, CLN-03, CLN-06 requirements complete

* feat(10-02): add URL path extension fallback to resolveMIME in Gemini and Voyage

- Add net/url import and URL path parsing as 3rd fallback in resolveMIME
- URL query strings and fragments are stripped by url.Parse before extension check
- Update error message to mention file/URL with known extension
- Add 4 new test cases per provider (URL fallback, query string, fragment, no-ext)
- Remove dead TestVoyageContainsDotDot test referencing removed containsDotDot function

* refactor(10-02): add registry unregister helpers and t.Cleanup to all tests

- Add 4 unexported unregister helpers (dense, sparse, multimodal, content)
- Add t.Cleanup with unregister calls to all 22 registration test sites
- Replace inline mu.Lock/delete/mu.Unlock with unregister helper calls
- Tests pass with -count=2 proving no global state leaks

* docs(10-02): complete URL MIME inference and registry test cleanup plan

- SUMMARY.md documents URL path fallback and registry cleanup changes
- STATE.md updated with position, metrics, and decisions
- ROADMAP.md reflects Phase 10 complete (2/2 plans)
- REQUIREMENTS.md marks CLN-04, CLN-05, CLN-06 complete

* docs(phase-10): complete phase execution and verification

* fix(10): harden input validation, error handling, and test coverage

- Add empty-string guards to ValidateFilePath and SafePath
- Surface URL parse errors in resolveMIME instead of silently discarding
- Wrap ValidateFilePath/SafePath errors with caller context
- Make containsDotDot unexported, remove dead SafePath branch
- Remove stale TODO(#469), use defer for unregister mutex consistency
- Add tests for malformed URLs, multi-level traversal, edge cases

* fix(10): handle root destPath in SafePath, strip URL from error messages

- Special-case root "/" in SafePath prefix check to avoid false rejection
- Remove raw URL from resolveMIME parse error to prevent credential leaks
- Add test for SafePath with root destPath

* fix(10): add MIME format validation, Gemini modality default case, clarify ValidateFilePath scope

- Clarify ValidateFilePath doc: only rejects relative ".." traversal, not
  absolute path manipulation; point callers to SafePath for confinement
- Add default case to Gemini validateMIMEModality matching Voyage's pattern,
  rejecting unknown modalities instead of silently passing
- Add MIME type format validation in BinarySource.Validate() using RFC 2045
  type/subtype regex to block injection via malformed MIME strings
- Add tests for all three changes

* refactor(10): simplify MIME regex init to regexp.Compile with nolint

* fix(10): remove weak MIME validation fallback, reject all if regex unavailable

Author: tazarov

.planning/REQUIREMENTS.md

@@ -51,6 +51,15 @@
 - [x] **CONV-03**: All convenience constructors have unit tests and existing tests/examples remain green
 - [x] **CONV-04**: Multimodal docs and provider examples show shorthand constructors as the primary examples with verbose forms linked from the generic Content API page
 
+### Code Cleanups
+
+- [x] **CLN-01**: Duplicated path safety functions (`containsDotDot`, `safePath`) are extracted into a shared `pkg/internal/pathutil` package with unit tests
+- [x] **CLN-02**: Gemini, Voyage, and default_ef providers import path safety utilities from the shared package instead of maintaining local copies
+- [x] **CLN-03**: Gemini, Nomic, and Mistral providers use `context.Context` (value type) for `DefaultContext` instead of `*context.Context` (pointer-to-interface anti-pattern)
+- [x] **CLN-04**: Registry tests use `t.Cleanup` with unexported unregister helpers to prevent global state leaks between test runs
+- [x] **CLN-05**: Gemini and VoyageAI `resolveMIME` functions infer MIME type from URL path extensions as a fallback, making URL constructors work end-to-end
+- [x] **CLN-06**: All existing tests pass without modification after cleanup changes
+
 ## v2 Requirements
 
 ### Provider Adoption
@@ -101,12 +110,18 @@
 | CONV-02 | Phase 9 | Planned |
 | CONV-03 | Phase 9 | Planned |
 | CONV-04 | Phase 9 | Planned |
+| CLN-01 | Phase 10 | Planned |
+| CLN-02 | Phase 10 | Planned |
+| CLN-03 | Phase 10 | Planned |
+| CLN-04 | Phase 10 | Planned |
+| CLN-05 | Phase 10 | Planned |
+| CLN-06 | Phase 10 | Planned |
 
 **Coverage:**
-- v1 requirements: 25 total
-- Mapped to phases: 25
+- v1 requirements: 31 total
+- Mapped to phases: 31
 - Unmapped: 0
 
 ---
 *Requirements defined: 2026-03-18*
-*Last updated: 2026-03-25 — added CONV-01/02/03/04 for phase 9*
+*Last updated: 2026-03-26 -- added CLN-01/02/03/04/05/06 for phase 10*

.planning/ROADMAP.md

@@ -23,7 +23,7 @@ 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, fix resolveMIME for URL-backed sources. (issues #456, #461, #466, #469)
+- [x] **Phase 10: Code Cleanups** - Extract shared path safety utilities, fix *context.Context anti-pattern, add registry test cleanup, fix resolveMIME for URL-backed sources. (issues #456, #461, #466, #469) (completed 2026-03-26)
 - [ ] **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)
@@ -172,8 +172,8 @@ Plans:
 | 6. Gemini Multimodal Adoption | 2/2 | Complete   | 2026-03-20 |
 | 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/2 | Not started | - |
-| 10. Code Cleanups | 0/0 | Not started | - |
+| 9. Convenience Constructors | 2/2 | Complete | - |
+| 10. Code Cleanups | 2/2 | Complete    | 2026-03-26 |
 | 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 | - |
@@ -202,17 +202,19 @@ Plans:
 **Goal:** Consolidate duplicated path safety utilities into a shared internal package, fix the *context.Context pointer-to-interface anti-pattern across embedding providers, add registry test cleanup to prevent global state leaks, and fix resolveMIME for URL-backed sources.
 **Depends on:** Phase 9
 **Issues**: #456, #461, #466, #469
+**Requirements**: [CLN-01, CLN-02, CLN-03, CLN-04, CLN-05, CLN-06]
 **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.
   6. Gemini and VoyageAI `resolveMIME` infer MIME type from URL path extensions, making URL constructors work end-to-end.
-**Plans:** 0 plans
+**Plans:** 2/2 plans complete
 
 Plans:
-- [ ] TBD (run /gsd:plan-phase 10 to break down)
+- [x] 10-01-PLAN.md — Create shared pathutil package, replace local implementations, fix *context.Context anti-pattern
+- [x] 10-02-PLAN.md — Add resolveMIME URL fallback, registry unregister helpers, and t.Cleanup to all tests
 
 ### 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.

.planning/STATE.md

@@ -2,14 +2,14 @@
 gsd_state_version: 1.0
 milestone: v0.4.1
 milestone_name: Provider-Neutral Multimodal Foundations
-status: "Phase 9 shipped — PR #468"
-stopped_at: Completed 09-02-PLAN.md
-last_updated: "2026-03-26T08:17:06.350Z"
+status: Ready to plan
+stopped_at: Completed 10-02-PLAN.md
+last_updated: "2026-03-26T10:37:37.709Z"
 progress:
   total_phases: 17
-  completed_phases: 9
-  total_plans: 22
-  completed_plans: 22
+  completed_phases: 10
+  total_plans: 24
+  completed_plans: 24
 ---
 
 # Project State
@@ -19,11 +19,11 @@ progress:
 See: .planning/PROJECT.md (updated 2026-03-18)
 
 **Core value:** Go applications can use Chroma and embedding providers through a stable, portable API that minimizes provider-specific friction.
-**Current focus:** Phase 09 — convenience-constructors-and-documentation-polish
+**Current focus:** Phase 10 — code-cleanups
 
 ## Current Position
 
-Phase: 10
+Phase: 11
 Plan: Not started
 
 ## Performance Metrics
@@ -66,6 +66,8 @@ Plan: Not started
 | Phase 08 P02 | 4min | 2 tasks | 3 files |
 | Phase 09 P01 | 1min | 2 tasks | 2 files |
 | Phase 09 P02 | 5min | 2 tasks | 4 files |
+| Phase 10 P01 | 4min | 2 tasks | 8 files |
+| Phase 10 P02 | 7min | 2 tasks | 6 files |
 
 ## Accumulated Context
 
@@ -111,6 +113,8 @@ Recent decisions affecting current work:
 - [Phase 08]: Reworded ROADMAP Phase 8 success criteria to eliminate last Nemotron text reference
 - [Phase 09]: Return Content by value and use ContentOption func(*Content) with no error return for convenience constructors
 - [Phase 09]: Shorthand-first doc pattern: provider multimodal sections show NewTextContent/NewImageFile, link to multimodal.md for verbose
+- [Phase 10]: Follow plan as specified - no deviations required for path safety consolidation and context anti-pattern fix
+- [Phase 10]: Remove dead TestVoyageContainsDotDot referencing function eliminated in Plan 01
 
 ### Roadmap Evolution
 
@@ -143,6 +147,6 @@ None.
 
 ## Session
 
-**Last Date:** 2026-03-25T16:12:32.516Z
-**Stopped At:** Completed 09-02-PLAN.md
+**Last Date:** 2026-03-26T10:32:36.242Z
+**Stopped At:** Completed 10-02-PLAN.md
 **Resume File:** None