amikos-tech
diff --git a/‎.github/workflows/ci.yml‎
Lines changed: 35 additions & 0 deletions b/‎.github/workflows/ci.yml‎
Lines changed: 35 additions & 0 deletions
diff --git a/‎.golangci.yml‎
Lines changed: 1 addition & 1 deletion b/‎.golangci.yml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎.planning/PROJECT.md‎
Lines changed: 78 additions & 0 deletions b/‎.planning/PROJECT.md‎
Lines changed: 78 additions & 0 deletions
diff --git a/‎.planning/REQUIREMENTS.md‎
Lines changed: 103 additions & 0 deletions b/‎.planning/REQUIREMENTS.md‎
Lines changed: 103 additions & 0 deletions
diff --git a/‎.planning/ROADMAP.md‎
Lines changed: 107 additions & 0 deletions b/‎.planning/ROADMAP.md‎
Lines changed: 107 additions & 0 deletions
@@ -296,3 +296,38 @@ jobs:
             java/panama/build/test-results/test/**
             java/panama/build/reports/tests/test/**
           if-no-files-found: warn
+
+  api-compat:
+    name: API Compatibility Check
+    if: github.event_name == 'pull_request' && github.base_ref == 'main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417 # v6.3.0
+        with:
+          go-version: stable
+          cache: true
+      - name: Run API compatibility check
+        run: |
+          go install golang.org/x/exp/cmd/apidiff@latest
+          LATEST_TAG=$(git tag -l 'v*' --sort=-v:refname | head -1)
+          if [ -z "$LATEST_TAG" ]; then
+            echo "No release tags found -- skipping apidiff"
+            exit 0
+          fi
+          echo "Comparing against: $LATEST_TAG"
+          OLD_DIR=$(go mod download -json "github.com/amikos-tech/chroma-go-local@${LATEST_TAG}" | jq -r .Dir)
+          cd "$OLD_DIR" && apidiff -w /tmp/old.txt github.com/amikos-tech/chroma-go-local
+          cd "$GITHUB_WORKSPACE" && apidiff -w /tmp/new.txt github.com/amikos-tech/chroma-go-local
+          echo "## API Diff (vs $LATEST_TAG)" >> "$GITHUB_STEP_SUMMARY"
+          if apidiff -incompatible /tmp/old.txt /tmp/new.txt > /tmp/diff.txt 2>&1; then
+            echo "No incompatible changes detected." >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo '```' >> "$GITHUB_STEP_SUMMARY"
+            cat /tmp/diff.txt >> "$GITHUB_STEP_SUMMARY"
+            echo '```' >> "$GITHUB_STEP_SUMMARY"
+            echo "::warning::API changes detected vs $LATEST_TAG - review step summary"
+          fi
+          exit 0
@@ -52,7 +52,7 @@ formatters:
       sections:
         - standard
         - default
-        - prefix(github.com/chaoslabs-bg/tclr-v2/)
+        - prefix(github.com/amikos-tech/chroma-go-local/)
         - blank
         - dot
       custom-order: true
 
@@ -0,0 +1,78 @@
+# chroma-go-local v0.4.0: Go Subtree Reorganization
+
+## What This Is
+
+A structural refactor of the chroma-go-local repository that moves Go implementation code out of the repo root into a dedicated `go/` subtree. This preserves the current public import path (`github.com/amikos-tech/chroma-go-local`) and all API behavior while making Go/Java/Rust ownership boundaries explicit for long-term maintenance.
+
+## Core Value
+
+The public Go import path and API surface must remain 100% backward-compatible — existing users must not need to change any code.
+
+## Requirements
+
+### Validated
+
+- ✓ Pure Go FFI via purego (no cgo) — existing
+- ✓ Server mode (HTTP) and Embedded mode (in-process) — existing
+- ✓ Builder pattern configuration with YAML backing — existing
+- ✓ Explicit resource lifecycle with finalizer fallback — existing
+- ✓ Java scaffold bindings (JNA + Panama) — existing
+- ✓ Rust FFI shim with C-compatible exports — existing
+- ✓ Cross-platform support (Linux, macOS, Windows) — existing
+- ✓ WAL prune maintenance APIs — v0.4.0 (#26)
+- ✓ Collection rebuild maintenance API — v0.4.0 (#25)
+
+### Active
+
+- ✓ Add thin root facade to preserve import compatibility — Validated in Phase 3
+- ✓ Reorganize tests for subtree layout + API compatibility coverage — Validated in Phase 4
+- ✓ Update Make/CI for relocated Go package layout — Validated in Phase 4
+- ✓ Refresh docs/examples after Go subtree move — Validated in Phase 5
+- ✓ Add compatibility gate checklist for root cleanup refactor — Validated in Phase 5
+
+### Validated in Phase 2: File Migration
+
+- ✓ Move Go implementation into `internal/` subtree without breaking imports — all files in `internal/runtime/` and `internal/library/`
+
+### Out of Scope
+
+- New features or API additions — this is purely structural
+- Java binding changes — layout remains unchanged
+- Rust shim changes — shim stays in `shim/`
+- Go module path change — must remain `github.com/amikos-tech/chroma-go-local`
+
+## Context
+
+The current repo has Go implementation files (chroma.go, config.go, embedded.go, errors.go, library.go, backup.go, rebuild.go, compaction.go, wal_prune.go) mixed at the repo root alongside Rust and Java code. This makes long-term maintenance and Java binding expansion harder. The v0.4.0 milestone moves Go implementation into a clean subtree while the root package becomes a thin facade.
+
+GitHub milestone: v0.4.0 (amikos-tech/chroma-go-local milestone #4)
+Umbrella issue: #45
+Individual issues: #39, #40, #41, #42, #43, #44
+
+## Constraints
+
+- **Import compatibility**: Root module path `github.com/amikos-tech/chroma-go-local` must remain valid
+- **API stability**: No public API signature changes allowed
+- **Build system**: `make test`, `make lint`, `make test-all` must pass throughout
+- **CI**: GitHub Actions workflows must remain green across OS matrix
+- **No circular deps**: New package layout must not introduce circular dependencies
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Sequential phases (one issue per phase) | Refactoring has strict dependency chain; each step must be stable before next | — Pending |
+| Subtree under `go/` directory | Keeps Go/Java/Rust separation explicit at repo root level | — Pending |
+| Root becomes thin facade | Preserves import path without requiring Go module replace directives | — Pending |
+| Proposed layout: `go/internal/runtime/`, `go/internal/library/`, etc. | Internal packages prevent unintended external imports | — Pending |
+
+## Current State
+
+- Phase 1 (Layout Design) complete — skeleton packages created
+- Phase 2 (File Migration) complete — all Go implementation (8 files) and test files (11 files) moved to `internal/runtime/`, library FFI loading (4 files) moved to `internal/library/`. Zero .go files remain at repo root. Race-instrumented compilation and cross-compile pass.
+- Phase 3 (Root Facade) complete — 9 facade files at repo root (doc.go, chroma.go, config.go, errors.go, embedded.go, backup.go, rebuild.go, compaction.go, wal_prune.go) re-export 54 type aliases and ~37 wrapper functions from internal/runtime. Full public API surface restored. `go build ./...` passes including examples.
+- Phase 4 (Build and Test) complete — lint clean (gci prefix fixed, SA1019 suppressed), `compat_test.go` created with 110-symbol compile gate + 9 behavioral smoke tests, all make targets pass, cross-compile verified for 3 OS.
+- Phase 5 (Compatibility & Docs) complete — apidiff verified zero genuine breaking changes (90 false positives documented), CI api-compat job added, README/CLAUDE.md/GO_API_SURFACE.md updated for internal/ layout, CHANGELOG.md created with v0.4.0 entry.
+
+---
+*Last updated: 2026-03-21 after Phase 5 completion*
@@ -0,0 +1,103 @@
+# Requirements: chroma-go-local v0.4.0
+
+**Defined:** 2026-03-20
+**Core Value:** Public Go import path and API surface must remain 100% backward-compatible
+
+## v1 Requirements
+
+### Layout Migration
+
+- [x] **LAYOUT-01**: All Go implementation files moved from repo root into `internal/` subtree at module root
+- [x] **LAYOUT-02**: Implementation organized into `internal/runtime/` (server, embedded, config, errors) and `internal/library/` (FFI loading, platform shims)
+- [x] **LAYOUT-03**: All FFI globals and `sync.Once` initialization moved atomically to implementation package (no split state)
+- [x] **LAYOUT-04**: Platform-specific files (`library_unix.go`, `library_windows.go`) retain correct build tags after move
+
+### Import Facade
+
+- [x] **FACADE-01**: Root package exposes all current public types via type aliases (`type X = impl.X`)
+- [x] **FACADE-02**: Root package re-exports all public functions via variable assignments or wrapper calls
+- [x] **FACADE-03**: Root package re-exports all constants, variables, and error types
+- [x] **FACADE-04**: Root package contains zero implementation logic (pure forwarding only)
+- [x] **FACADE-05**: Import path `github.com/amikos-tech/chroma-go-local` remains valid and unchanged
+
+### Test Reorganization
+
+- [x] **TEST-01**: Implementation-focused tests moved alongside new internal packages
+- [x] **TEST-02**: Public API compatibility tests remain at root level
+- [x] **TEST-03**: `compat_test.go` added at root as compile-time API surface gate
+- [x] **TEST-04**: `make test` passes with reorganized test layout
+
+### Build & CI
+
+- [x] **BUILD-01**: Makefile targets updated for new package paths (`make test`, `make lint`, `make test-all`)
+- [x] **BUILD-02**: CI workflows (`.github/workflows/ci.yml`) updated for new structure
+- [x] **BUILD-03**: Stale `gci` prefix in `.golangci.yml` corrected to `github.com/amikos-tech/chroma-go-local/`
+- [x] **BUILD-04**: Cross-compile verification passes for `GOOS=windows`, `GOOS=linux`, `GOOS=darwin`
+
+### Docs & Verification
+
+- [x] **DOCS-01**: `go-apidiff` run against v0.3.4 tag confirms zero breaking changes
+- [x] **DOCS-02**: README.md updated with new directory layout and build instructions
+- [x] **DOCS-03**: CLAUDE.md updated to reflect new architecture
+- [x] **DOCS-04**: GO_API_SURFACE.md references updated for new file locations
+
+### Compatibility Gate
+
+- [x] **COMPAT-01**: Explicit compatibility checklist completed before merge
+- [x] **COMPAT-02**: No import-path break for current users verified
+- [x] **COMPAT-03**: Release notes include refactor summary and compatibility statement
+
+## v2 Requirements
+
+### Future Improvements
+
+- **FUTURE-01**: Verify `pkg.go.dev` rendering of type aliases to internal paths
+- **FUTURE-02**: Evaluate `go-apidiff` as permanent CI gate for future releases
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| New API features or methods | This is purely structural; new features belong to future milestones |
+| Java binding layout changes | Java layout stays in `java/`; not part of this refactor |
+| Rust shim changes | Shim stays in `shim/`; no code changes needed |
+| Go module path change | Must remain `github.com/amikos-tech/chroma-go-local` |
+| Second `go.mod` under `go/` | Creates separate module requiring `replace` directives; breaks published module |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| LAYOUT-01 | Phase 1 | Complete |
+| LAYOUT-02 | Phase 1 | Complete |
+| LAYOUT-03 | Phase 2 | Complete |
+| LAYOUT-04 | Phase 2 | Complete |
+| FACADE-01 | Phase 3 | Complete |
+| FACADE-02 | Phase 3 | Complete |
+| FACADE-03 | Phase 3 | Complete |
+| FACADE-04 | Phase 3 | Complete |
+| FACADE-05 | Phase 3 | Complete |
+| TEST-01 | Phase 4 | Complete |
+| TEST-02 | Phase 4 | Complete |
+| TEST-03 | Phase 4 | Complete |
+| TEST-04 | Phase 4 | Complete |
+| BUILD-01 | Phase 4 | Complete |
+| BUILD-02 | Phase 4 | Complete |
+| BUILD-03 | Phase 4 | Complete |
+| BUILD-04 | Phase 4 | Complete |
+| DOCS-01 | Phase 5 | Complete |
+| DOCS-02 | Phase 5 | Complete |
+| DOCS-03 | Phase 5 | Complete |
+| DOCS-04 | Phase 5 | Complete |
+| COMPAT-01 | Phase 5 | Complete |
+| COMPAT-02 | Phase 5 | Complete |
+| COMPAT-03 | Phase 5 | Complete |
+
+**Coverage:**
+- v1 requirements: 24 total
+- Mapped to phases: 24
+- Unmapped: 0
+
+---
+*Requirements defined: 2026-03-20*
+*Last updated: 2026-03-20 after roadmap creation*
@@ -0,0 +1,107 @@
+# Roadmap: chroma-go-local v0.4.0 — Go Subtree Reorganization
+
+## Overview
+
+A strictly sequential structural refactor: move all Go implementation files from the repo root into `internal/runtime/` and `internal/library/` subtrees, then restore the root package as a pure-forwarding facade. Each phase must be green before the next begins — the dependency chain is irreversible. The public import path `github.com/amikos-tech/chroma-go-local` and every exported symbol must be identical from a caller's perspective before and after.
+
+## Phases
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal phases appear between their surrounding integers in numeric order.
+
+- [x] **Phase 1: Layout Design** - Lock directory structure, create skeleton packages, confirm `internal/` is anchored at module root
+- [ ] **Phase 2: File Migration** - Move all Go implementation files into `internal/runtime/` and `internal/library/`, co-locate tests
+- [ ] **Phase 3: Root Facade** - Write thin facade at repo root that re-exports every public symbol via type aliases and function vars
+- [ ] **Phase 4: Build and Test** - Update Makefile, CI, lint config, and test layout; verify all `make` targets and cross-compile pass
+- [ ] **Phase 5: Compatibility and Docs** - Run `go-apidiff` against v0.3.4, add `compat_test.go`, update CLAUDE.md and docs
+
+## Phase Details
+
+### Phase 1: Layout Design
+**Goal**: The target directory structure exists as compilable skeleton packages; the `internal/` anchor is confirmed at module root; no files have moved yet
+**Depends on**: Nothing (first phase)
+**Requirements**: LAYOUT-01, LAYOUT-02
+**Success Criteria** (what must be TRUE):
+  1. `internal/runtime/` and `internal/library/` directories exist at the module root with valid `package` declarations
+  2. `go build ./...` succeeds with the skeleton in place alongside existing root files
+  3. The root facade import of `internal/runtime` compiles without "use of internal package not allowed" errors
+  4. No existing Go files have been relocated; the skeleton is additive only
+**Plans:** 1 plan
+Plans:
+- [x] 01-01-PLAN.md — Create skeleton packages and anchor validation test
+
+### Phase 2: File Migration
+**Goal**: All Go implementation files live in `internal/library/` and `internal/runtime/`; the repo root contains no implementation logic; `go test ./internal/...` passes with race detector on
+**Depends on**: Phase 1
+**Requirements**: LAYOUT-03, LAYOUT-04
+**Success Criteria** (what must be TRUE):
+  1. All FFI globals (`libHandle`, `libOnce`, `ffiMu`, and all function pointers) exist exclusively in `internal/runtime`; the module root has zero `var` state declarations
+  2. Platform-specific files (`library_unix.go`, `library_windows.go`) are present in `internal/library/` with correct build tags verified via `go list`
+  3. `go test -race ./internal/...` passes with no data-race reports
+  4. Per-package test count in `internal/...` accounts for all tests that previously ran at root; no tests are orphaned
+**Plans:** 2 plans
+Plans:
+- [x] 02-01-PLAN.md — Move library files to internal/library/, export LoadLibrary, bridge chroma.go Init()
+- [x] 02-02-PLAN.md — Move runtime files and tests to internal/runtime/, fix imports, remove anchor test
+
+### Phase 3: Root Facade
+**Goal**: The repo root package re-exports every previously public symbol so that existing callers compile and behave identically without changing a single import statement
+**Depends on**: Phase 2
+**Requirements**: FACADE-01, FACADE-02, FACADE-03, FACADE-04, FACADE-05
+**Success Criteria** (what must be TRUE):
+  1. Every exported type is re-exported via `type X = internal/runtime.X` (alias, not definition); `chroma.Server` and `runtime.Server` are the same type
+  2. Every exported function is delegated via `var F = runtime.F`; callers invoking `chroma.NewServer(...)` reach the implementation without wrapping overhead
+  3. Every exported constant, sentinel error, and package-level variable is forwarded at root; the root file contains zero logic, zero `var` state, and zero `init()` functions
+  4. `go test ./...` from the module root passes using the existing test suite with no changes to test files
+  5. The import path `github.com/amikos-tech/chroma-go-local` resolves to the facade package and the package name remains `chroma`
+**Plans:** 2 plans
+Plans:
+- [x] 03-01-PLAN.md — Create core facade files (doc.go, chroma.go, config.go, errors.go)
+- [x] 03-02-PLAN.md — Create feature facade files (embedded.go, backup.go, rebuild.go, compaction.go, wal_prune.go)
+
+### Phase 4: Build and Test
+**Goal**: All `make` targets pass, the CI matrix stays green, lint is clean, and the test layout reflects the new package structure including a root-level compatibility gate
+**Depends on**: Phase 3
+**Requirements**: TEST-01, TEST-02, TEST-03, TEST-04, BUILD-01, BUILD-02, BUILD-03, BUILD-04
+**Success Criteria** (what must be TRUE):
+  1. `make test`, `make test-release`, `make lint`, and `make test-all` all pass locally without modification by the caller
+  2. `golangci-lint run ./...` reports zero issues; the stale `gci` prefix in `.golangci.yml` is corrected to `github.com/amikos-tech/chroma-go-local/`
+  3. Cross-compile succeeds: `GOOS=linux go build ./...`, `GOOS=darwin go build ./...`, `GOOS=windows go build ./...` all complete without error
+  4. `compat_test.go` exists at repo root in `package chroma_test` and references every exported symbol; it compiles successfully as a compile-time API surface gate
+  5. CI workflows (`.github/workflows/ci.yml`) run without modification to the OS matrix or job structure
+**Plans:** 3 plans
+Plans:
+- [x] 04-01-PLAN.md — Fix lint config (gci prefix) and deprecated type nolint directives
+- [x] 04-02-PLAN.md — Create compat_test.go with compile-time API surface gate and behavioral smoke tests
+- [x] 04-03-PLAN.md — Full verification pass (make test, make lint, cross-compile, CI inspection)
+
+### Phase 5: Compatibility and Docs
+**Goal**: Machine-verified API compatibility against the v0.3.4 baseline is confirmed, documentation reflects the new layout, and the release is ready to merge
+**Depends on**: Phase 4
+**Requirements**: DOCS-01, DOCS-02, DOCS-03, DOCS-04, COMPAT-01, COMPAT-02, COMPAT-03
+**Success Criteria** (what must be TRUE):
+  1. `go-apidiff` run against the v0.3.4 tag reports zero incompatible changes
+  2. README.md and CLAUDE.md accurately describe the new `internal/runtime/` and `internal/library/` layout; no file paths point to the old root-level implementation files
+  3. GO_API_SURFACE.md references are updated to reflect new file locations
+  4. A compatibility checklist is completed and attached to the PR confirming: import path unchanged, no public API removals, no type definition breakages, race detector clean
+  5. Release notes include a refactor summary and an explicit compatibility statement for existing users
+**Plans:** 2 plans
+Plans:
+- [x] 05-01-PLAN.md — API compatibility verification (apidiff vs v0.3.4) and CI apidiff job
+- [x] 05-02-PLAN.md — Documentation refresh (README, CLAUDE.md, GO_API_SURFACE.md) and CHANGELOG.md
+
+## Progress
+
+**Execution Order:**
+Phases execute in strict sequential order: 1 -> 2 -> 3 -> 4 -> 5
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. Layout Design | 1/1 | Complete | 2026-03-20 |
+| 2. File Migration | 2/2 | Complete | 2026-03-20 |
+| 3. Root Facade | 0/2 | Not started | - |
+| 4. Build and Test | 0/3 | Not started | - |
+| 5. Compatibility and Docs | 0/2 | Not started | - |