feat: Phase 8 — Embedded maintenance operations (rebuild, compact, WAL prune) (#80)

* docs(08): capture phase context

* docs(state): record phase 8 context session

* docs(08): research embedded maintenance phase domain

* docs(08-embedded-maintenance): create phase plan

Two plans in 2 waves:
- Plan 01: Expand EmbeddedSession with callback slots, wire JNA + Panama backends
- Plan 02: Integration tests for embedded maintenance in both backends

* fix(08): revise plans based on checker feedback

Add Java lint step (gradle :core:check :jna:check 🇵🇦check) to
08-01 verification and Task 2 verify block per CLAUDE.md compliance.

Document D-09 data-seeded test deferral in 08-02 objective and task
actions — collection CRUD unavailable until FUTURE-03.

* docs(08): add validation strategy

* feat(08-01): expand EmbeddedSession with callback slots and maintenance methods

- Add 5 BiFunction callback slots for maintenance operations
- Add 7 public maintenance methods (5 primary + 2 convenience overloads)
- Add ensureOpen() guard pattern matching ServerSession
- Constructor expands from 2 to 7 parameters with null checks

* feat(08-01): wire JNA and Panama backends with maintenance symbol bindings

- Add 5 chroma_embedded_* symbol declarations to JNA JnaBindings interface
- Add 5 MethodHandle fields to Panama Ffi record with eager binding
- Both doStartEmbedded methods pass callFfiJson lambdas to expanded constructor
- Fix EmbeddedSessionTest to use 7-parameter constructor

* docs(08-01): complete embedded maintenance wiring plan

- Create 08-01-SUMMARY.md with execution results
- Update STATE.md with phase 8 position and decisions
- Update ROADMAP.md progress (1/2 plans complete)
- Mark EMNT-01 through EMNT-04 complete in REQUIREMENTS.md

* test(08-02): add JNA embedded maintenance integration tests

- 7 tests covering smoke, error paths, input validation, closed-session guards
- Verifies rebuildCollection, compactAll, compactCollection, pruneAllWAL, pruneCollectionWAL

* test(08-02): add Panama embedded maintenance integration tests

- 7 tests mirroring JNA coverage for smoke, error paths, validation, closed-session guards
- Verifies rebuildCollection, compactAll, compactCollection, pruneAllWAL, pruneCollectionWAL

* docs(08-02): complete embedded maintenance integration tests plan

- SUMMARY.md with 14 tests (7 JNA + 7 Panama) coverage
- STATE.md updated with phase 08 completion
- ROADMAP.md marks phase 08 complete (2/2 plans)
- REQUIREMENTS.md marks EMNT-05 complete

* docs(phase-08): complete phase execution

* docs(phase-08): evolve PROJECT.md after phase completion

* test(08): complete UAT - 5 passed, 0 issues

* docs(08): ship phase 08 — PR #80

* fix(08): address PR review findings — dead name param, error handling, tests

- Remove dead `name` parameter from rebuildCollection and pruneCollectionWAL
  (options object already carries the name; old API silently discarded it)
- Add pruneCollectionWAL(String) convenience overload for API parity
- Log readLastError failures in PanamaChromaRuntime instead of silent null
- Use addSuppressed for callFfiVoid drain catch in AbstractChromaRuntime
- Replace null-returning test stubs with UnsupportedOperationException
- Add 13 unit tests: constructor null-rejection (5), input validation (5),
  convenience overload delegation (2), existing lifecycle (6 unchanged)
- Update integration tests and ServerSession stubs for new signatures

* fix(08): address PR review — stale stubs, type consistency, API symmetry

- Update 3 stale "Phase 8" stub messages to "Phase 10" in ServerSession
- Add compactCollection(String) convenience overload to match rebuild/prune
- Add Javadoc on pruneAllWAL noting name field is ignored
- Change collectionCount from u32/int to u64/long across Rust, Go, Java
- Change WAL prune warning from Option<String>/String to Vec<String>/List

* test(08): add compactCollection delegation test and convenience overload smoke tests

Complete the symmetric delegation test set in EmbeddedSessionTest and
exercise the convenience overload FFI path in JNA/Panama integration tests.

Author: tazarov

.planning/PROJECT.md

@@ -41,9 +41,9 @@ Java and Go APIs must provide equivalent access to all Chroma runtime capabiliti
 - [x] Java server lifecycle API (start/stop/port/address/URL) — Validated in Phase 7
 - [x] Java builder pattern for server configuration — Validated in Phase 6
 - [ ] Java backup API with option builder
-- [ ] Java rebuild API with option builder
-- [ ] Java compaction API (per-collection and all)
-- [ ] Java WAL prune API with option builder
+- [x] Java rebuild API with option builder — Validated in Phase 8
+- [x] Java compaction API (per-collection and all) — Validated in Phase 8
+- [x] Java WAL prune API with option builder — Validated in Phase 8
 - [ ] JNA and Panama implementations kept in sync
 - [ ] Java integration tests for all new APIs
 

.planning/REQUIREMENTS.md

@@ -23,11 +23,11 @@
 
 ### Embedded Maintenance
 
-- [ ] **EMNT-01**: `EmbeddedSession.rebuildCollection(name, options)` returns RebuildCollectionResult in both backends
-- [ ] **EMNT-02**: `EmbeddedSession.compactCollection(request)` and `compactAll(request)` return CompactionResult in both backends
-- [ ] **EMNT-03**: `EmbeddedSession.pruneCollectionWAL(name, options)` and `pruneAllWAL(options)` return WALPruneResult in both backends
-- [ ] **EMNT-04**: Option builders (RebuildOptions, WALPruneOptions) validate inputs at build time
-- [ ] **EMNT-05**: Integration tests verify each embedded maintenance operation in both backends
+- [x] **EMNT-01**: `EmbeddedSession.rebuildCollection(name, options)` returns RebuildCollectionResult in both backends
+- [x] **EMNT-02**: `EmbeddedSession.compactCollection(request)` and `compactAll(request)` return CompactionResult in both backends
+- [x] **EMNT-03**: `EmbeddedSession.pruneCollectionWAL(name, options)` and `pruneAllWAL(options)` return WALPruneResult in both backends
+- [x] **EMNT-04**: Option builders (RebuildOptions, WALPruneOptions) validate inputs at build time
+- [x] **EMNT-05**: Integration tests verify each embedded maintenance operation in both backends
 
 ### Backup
 
@@ -78,11 +78,11 @@
 | SRVR-02 | Phase 7 | Pending |
 | SRVR-03 | Phase 7 | Pending |
 | SRVR-04 | Phase 7 | Pending |
-| EMNT-01 | Phase 8 | Pending |
-| EMNT-02 | Phase 8 | Pending |
-| EMNT-03 | Phase 8 | Pending |
-| EMNT-04 | Phase 8 | Pending |
-| EMNT-05 | Phase 8 | Pending |
+| EMNT-01 | Phase 8 | Complete |
+| EMNT-02 | Phase 8 | Complete |
+| EMNT-03 | Phase 8 | Complete |
+| EMNT-04 | Phase 8 | Complete |
+| EMNT-05 | Phase 8 | Complete |
 | BKUP-01 | Phase 9 | Pending |
 | BKUP-02 | Phase 9 | Pending |
 | BKUP-03 | Phase 9 | Pending |

.planning/ROADMAP.md

@@ -76,10 +76,11 @@ Plans:
   3. `EmbeddedSession.pruneCollectionWAL(name, options)` and `pruneAllWAL(options)` return WALPruneResult in both backends
   4. Option builders (RebuildOptions, WALPruneOptions) reject invalid inputs at build time with clear error messages
   5. Integration tests verify each maintenance operation produces valid results against a real embedded instance in both backends
-**Plans**: TBD
+**Plans**: 2 plans
 
 Plans:
-- [ ] 08-01: TBD
+- [x] 08-01-PLAN.md -- Expand EmbeddedSession with callback slots, wire JNA and Panama backends
+- [x] 08-02-PLAN.md -- Integration tests for embedded maintenance in both JNA and Panama backends
 
 ### Phase 9: Backup API
 **Goal**: Users can back up Chroma data from both embedded and server modes, producing a directory with a manifest file that records backup metadata
@@ -124,6 +125,6 @@ Phases execute in numeric order: 6 -> 7 -> 8 -> 9 -> 10
 | 5. Compatibility and Docs | v0.4.0 | 2/2 | Complete | - |
 | 6. Core Foundation Types | v0.5.0 | 0/3 | Not started | - |
 | 7. Server Lifecycle | v0.5.0 | 2/2 | Complete | 2026-03-26 |
-| 8. Embedded Maintenance | v0.5.0 | 0/? | Not started | - |
+| 8. Embedded Maintenance | v0.5.0 | 2/2 | Complete | 2026-03-26 |
 | 9. Backup API | v0.5.0 | 0/? | Not started | - |
 | 10. Server Maintenance | v0.5.0 | 0/? | Not started | - |

.planning/STATE.md

@@ -2,14 +2,14 @@
 gsd_state_version: 1.0
 milestone: v0.5.0
 milestone_name: Java API Surface
-status: Ready to plan
-stopped_at: Completed 07-02-PLAN.md
-last_updated: "2026-03-26T08:46:03.795Z"
+status: "Phase 08 shipped — PR #80"
+stopped_at: Completed 08-02-PLAN.md
+last_updated: "2026-03-26T14:17:06.008Z"
 progress:
   total_phases: 5
-  completed_phases: 2
-  total_plans: 5
-  completed_plans: 5
+  completed_phases: 3
+  total_plans: 7
+  completed_plans: 7
 ---
 
 # Project State
@@ -19,11 +19,11 @@ progress:
 See: .planning/PROJECT.md (updated 2026-03-21)
 
 **Core value:** Java and Go APIs must provide equivalent access to all Chroma runtime capabilities
-**Current focus:** Phase 07 — server-lifecycle
+**Current focus:** Phase 08 — embedded-maintenance
 
 ## Current Position
 
-Phase: 8
+Phase: 9
 Plan: Not started
 
 ## Performance Metrics
@@ -35,6 +35,8 @@ Plan: Not started
 | Phase 06 P02 | 5min | 2 tasks | 13 files |
 | 07 | 01 | 3min | 2 | 3 |
 | 07 | 02 | 2min | 1 | 2 |
+| 08 | 01 | 3min | 2 | 4 |
+| 08 | 02 | 9min | 2 | 2 |
 
 ## Accumulated Context
 
@@ -52,6 +54,10 @@ Plan: Not started
 - [Phase 07]: serverFree and embeddedFree bypass callFfiVoid to avoid FFI lock in finally blocks
 - [Phase 07]: Skipped port-already-bound and concurrent start tests -- flaky across OSes
 - [Phase 07]: Used ServerConfigBuilder in integration tests to validate builder output against real FFI
+- [Phase 08]: BiFunction<Long, String, T> callback slots for all 5 maintenance operations
+- [Phase 08]: EmbeddedSession constructor expanded from 2 to 7 parameters
+- [Phase 08]: Smoke tier tests only -- D-09 data-seeded tests deferred pending FUTURE-03 collection CRUD
+- [Phase 08]: EmbeddedConfigBuilder used for test YAML instead of hand-written strings
 
 ### Pending Todos
 
@@ -63,6 +69,6 @@ None yet.
 
 ## Session Continuity
 
-Last session: 2026-03-26T08:31:48Z
-Stopped at: Completed 07-02-PLAN.md
+Last session: 2026-03-26T13:10:41Z
+Stopped at: Completed 08-02-PLAN.md
 Resume file: None