Context
PR #14022 was approved as Approve+Follow-Up after review at head b54fb2d45:
The review approved #14022 because the physical daemon + data-dir isolation is the right primary containment for unit-test Chroma writes. The follow-up is the remaining config-independent safety net: Chroma still needs a caller-keyed write guard equivalent to the existing SQLite/file-store guard pattern.
Pre-creation V-B-A:
- GitHub identity verified before public issue creation:
neo-gpt.
- Label list verified:
bug, ai, testing, regression, and model-experience exist.
- KB semantic sweep for
caller-keyed Chroma write guard assertTestWriteIsolated unit test isolation surfaced #11652, #12335, #13639, #13665, #13683, and #12180 as precedent, but no existing narrow Chroma caller-keyed guard ticket.
- Exact local sweep over
resources/content/issues, resources/content/discussions, .agents/skills/unit-test, and learn found the shared assertTestWriteIsolated precedent but no dedicated Chroma write-path ticket.
- Live latest-open sweep: checked latest 20 open issues at 2026-06-25T23:08:48Z. Closest active tickets were #14010 (broad Chroma test-collection isolation parent), #14023 (Memory Core defrag unrecoverable reasons), and #14024 (backup-corruption timeline diagnostic). No equivalent #14022 follow-up leaf was present.
- A2A in-flight sweep: checked latest 30 all-status messages at 2026-06-25T23:08:48Z. Vega already claimed the guard fast-follow in the #14022 review coordination; #14024 is a separate detection/timeline lane. This ticket records Vega's claimed leaf instead of creating a competing lane.
The Problem
#14022 physically isolates unit-test Chroma through config resolution: unit tests run a separate Chroma daemon on the test endpoint and data directory. That closes the normal path, but the review reproduced the failure mode that motivated the fast-follow: if a stale generated overlay, missed migration, or non-standard runner resolves the active Chroma config back to production coordinates, the isolation can silently fall back to the live store.
The existing Agent OS guard pattern avoids this class for other stores by keying on the caller context, not only on config state. assertTestWriteIsolated throws when a test runner context is writing to a production-like store. Chroma has no equivalent write-path guard yet.
The rule we need is simple: unit tests must not touch the live Chroma store at any moment, even when config resolution is wrong.
The Architectural Reality
Relevant precedent:
- #11652 guards destructive canonical Chroma collection deletes.
- #12335 moved unit-test Chroma usage into isolated test routing under
UNIT_TEST_MODE.
- #13639 / #13665 introduced the shared
assertTestWriteIsolated guard pattern for SQLite graph writes.
- #13683 applied the same shared guard to concept-ontology file writes.
- #14022 adds the primary physical Chroma daemon/data-dir isolation for unit tests.
The missing surface is the Chroma write funnel itself. The fix should guard Chroma writes based on caller/test-runner context and the resolved Chroma target, so a config or overlay mistake fails closed before any live collection, document, metadata, or embedding write occurs.
The Fix
- Identify the central Chroma write path(s) used by Memory Core / KB tests and production code.
- Apply the existing shared
assertTestWriteIsolated pattern, or a Chroma-specific adapter around it, before mutating Chroma when a test-runner context is present.
- Treat production-like Chroma targets as forbidden under test caller context, even if
UNIT_TEST_MODE or the generated config overlay is missing or stale.
- Keep production runtime behavior a no-op when no test-runner signal is present.
- Add focused unit coverage proving that Chroma writes fail closed when
TEST_WORKER_INDEX is set and the target resolves to the production Chroma store.
- Document the
chroma CLI and migrated config.mjs prerequisites for npm run test-unit, and either pid-scope portTest / 18180 or explicitly document the single-concurrent-run constraint if that is the intended behavior.
Contract Ledger Matrix
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
| Chroma write path |
#14022 review follow-up + #14010 test-isolation contract |
Test-runner context cannot write to a production-like Chroma target |
Throw before the Chroma mutation |
JSDoc on the guard call / helper |
Unit test with TEST_WORKER_INDEX and prod-like target |
| Unit-test Chroma prerequisites |
#14022 review follow-up |
Contributor entry points state that chroma CLI and migrated config overlay are required for npm run test-unit |
Failure message or docs point to bootstrap/migration path |
.agents/skills/unit-test or nearby contributing docs |
Documentation assertion / focused test if there is a helper |
| Unit-test Chroma port policy |
#14022 review follow-up |
portTest concurrency behavior is either pid-scoped or explicitly constrained |
Clear single-run constraint if fixed port stays |
Config/template comment or docs |
Unit/static assertion where practical |
Decision Record impact
Aligned with ADR 0019. The fix should keep AiConfig as the reactive Provider SSOT and add a fail-closed write guard at the Chroma mutation boundary; it does not amend the ADR.
Acceptance Criteria
Out of Scope
- Reopening #14022.
- Rewriting the physical Chroma isolation delivered by #14022.
- Changing the Memory Core repair-defrag path (#14020 / #14023).
- Adding live data-integrity drift detection (#14024 / #13860 sibling lane).
- Attributing #13999's missing vectors to test bleed without new evidence.
Avoided Traps
- Do not rely on
test-* collection names as the guard. Naming is diagnostic smell, not isolation.
- Do not add a second config decision tree that bypasses ADR 0019.
- Do not weaken the primary physical isolation from #14022; the guard is the config-independent complement.
- Do not combine this with the backup-corruption timeline or defrag unrecoverable-reason tickets.
Related
Related: #14010
Related: #14022
Related: #13639
Related: #13665
Related: #13683
Related: #12335
Related: #11652
Origin Session ID: 35f83031-f1a6-41a7-9c3b-089b87307db9
Handoff Retrieval Hints
query_raw_memories("#14022 caller-keyed Chroma write guard assertTestWriteIsolated")query_raw_memories("Chroma unit-test physical isolation config-independent guard TEST_WORKER_INDEX")- Exact anchors:
assertTestWriteIsolated, storeWriteGuard, ChromaManager, playwright.config.unit.mjs, config.template.mjs.
Context
PR #14022 was approved as
Approve+Follow-Upafter review at headb54fb2d45:The review approved #14022 because the physical daemon + data-dir isolation is the right primary containment for unit-test Chroma writes. The follow-up is the remaining config-independent safety net: Chroma still needs a caller-keyed write guard equivalent to the existing SQLite/file-store guard pattern.
Pre-creation V-B-A:
neo-gpt.bug,ai,testing,regression, andmodel-experienceexist.caller-keyed Chroma write guard assertTestWriteIsolated unit test isolationsurfaced #11652, #12335, #13639, #13665, #13683, and #12180 as precedent, but no existing narrow Chroma caller-keyed guard ticket.resources/content/issues,resources/content/discussions,.agents/skills/unit-test, andlearnfound the sharedassertTestWriteIsolatedprecedent but no dedicated Chroma write-path ticket.The Problem
#14022 physically isolates unit-test Chroma through config resolution: unit tests run a separate Chroma daemon on the test endpoint and data directory. That closes the normal path, but the review reproduced the failure mode that motivated the fast-follow: if a stale generated overlay, missed migration, or non-standard runner resolves the active Chroma config back to production coordinates, the isolation can silently fall back to the live store.
The existing Agent OS guard pattern avoids this class for other stores by keying on the caller context, not only on config state.
assertTestWriteIsolatedthrows when a test runner context is writing to a production-like store. Chroma has no equivalent write-path guard yet.The rule we need is simple: unit tests must not touch the live Chroma store at any moment, even when config resolution is wrong.
The Architectural Reality
Relevant precedent:
UNIT_TEST_MODE.assertTestWriteIsolatedguard pattern for SQLite graph writes.The missing surface is the Chroma write funnel itself. The fix should guard Chroma writes based on caller/test-runner context and the resolved Chroma target, so a config or overlay mistake fails closed before any live collection, document, metadata, or embedding write occurs.
The Fix
assertTestWriteIsolatedpattern, or a Chroma-specific adapter around it, before mutating Chroma when a test-runner context is present.UNIT_TEST_MODEor the generated config overlay is missing or stale.TEST_WORKER_INDEXis set and the target resolves to the production Chroma store.chromaCLI and migratedconfig.mjsprerequisites fornpm run test-unit, and either pid-scopeportTest/ 18180 or explicitly document the single-concurrent-run constraint if that is the intended behavior.Contract Ledger Matrix
TEST_WORKER_INDEXand prod-like targetchromaCLI and migrated config overlay are required fornpm run test-unit.agents/skills/unit-testor nearby contributing docsportTestconcurrency behavior is either pid-scoped or explicitly constrainedDecision Record impact
Aligned with ADR 0019. The fix should keep AiConfig as the reactive Provider SSOT and add a fail-closed write guard at the Chroma mutation boundary; it does not amend the ADR.
Acceptance Criteria
UNIT_TEST_MODEor collection-name prefixes.TEST_WORKER_INDEXis set and the target is production-like.npm run test-unitChroma prerequisites are documented:chromaCLI availability and migratedconfig.mjs/ bootstrap requirement.portTest/ 18180 concurrency behavior is either made pid-scoped or explicitly documented as a single-concurrent-run constraint.Out of Scope
Avoided Traps
test-*collection names as the guard. Naming is diagnostic smell, not isolation.Related
Related: #14010 Related: #14022 Related: #13639 Related: #13665 Related: #13683 Related: #12335 Related: #11652
Origin Session ID: 35f83031-f1a6-41a7-9c3b-089b87307db9
Handoff Retrieval Hints
query_raw_memories("#14022 caller-keyed Chroma write guard assertTestWriteIsolated")query_raw_memories("Chroma unit-test physical isolation config-independent guard TEST_WORKER_INDEX")assertTestWriteIsolated,storeWriteGuard,ChromaManager,playwright.config.unit.mjs,config.template.mjs.