Context
After PR #12164 (Epic #12101 Stage 1) merged and the orchestrator was rebooted (2026-05-29), operator review surfaced that the ChromaDB "dummy embedding function" — used to bypass server-side embedding generation when Neo provides embeddings directly — is defined in multiple divergent places instead of a single Tier-1 source. The unified Chroma topology (Memory Core + Knowledge Base share one instance) makes the EF realm-wide: it belongs once at Tier-1.
The Problem
Four divergent / misplaced definitions of the same dummy EF:
- Tier-1
ai/config.template.mjs:612 — dummyEmbeddingFunction (name: 'dummy_embedding_function', verbose anti-legacy structure: name / getConfig / constructor.buildFromConfig).
- Knowledge Base
ai/mcp/server/knowledge-base/config.template.mjs:114 — re-declares its own copy.
- defrag
ai/scripts/maintenance/defragChromaDB.mjs:378-383 — hardcodes a third variant with name: 'dummy'. That literal 'dummy' is what chromadb 3.x maps to the (non-existent) @chroma-core/dummy package, producing the Collection schema deserialization … @chroma-core/dummy is not installed warning seen during chroma defrag (knowledge-base).
- GitHub Workflow
ai/mcp/server/github-workflow/config.template.mjs:84 — includes dummyEmbeddingFunction but never imports chromadb (V-B-A 2026-05-29: grep -c chromadb = 0). Dead config.
The Architectural Reality
- Unified Chroma (#11111 chroma-client primitives) — MC + KB share one Chroma instance; the dummy EF is a realm-wide constant, not a per-server concern.
- The canonical Tier-1 EF round-trips intact through the new reactive config (verified 2026-05-29:
name, generate, getConfig, and the special own constructor.buildFromConfig all survive as callable functions).
- KB's
ChromaManager reads aiConfig.dummyEmbeddingFunction; the defrag ignores config and hardcodes its own.
The Fix
- Keep the single canonical
dummyEmbeddingFunction leaf in Tier-1 ai/config.template.mjs (+ regenerated config.mjs).
- KB: remove the duplicate definition; reference Tier-1's (
default: AiConfig.dummyEmbeddingFunction snapshot now; becomes chain-inherited once the parent-chain realm-inheritance sub lands).
- defrag
defragChromaDB.mjs: import + use AiConfig.dummyEmbeddingFunction instead of the hardcoded name: 'dummy' object. The verbose canonical EF is expected to also clear the chromadb-3.x deserialization warning.
- GH-workflow: delete
dummyEmbeddingFunction (no chroma usage).
Contract Ledger
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
AiConfig.dummyEmbeddingFunction (Tier-1 config key) |
ai/config.template.mjs:612 |
Single canonical definition; realm-wide |
n/a (concrete default) |
leaf JSDoc |
Round-trip verified 2026-05-29 |
KB dummyEmbeddingFunction |
knowledge-base/config.template.mjs:114 |
Removed; references Tier-1 |
inherits Tier-1 |
— |
Duplicate confirmed |
defrag dummyEf |
defragChromaDB.mjs:378 |
Removed; uses AiConfig.dummyEmbeddingFunction |
— |
— |
Hardcoded name:'dummy' confirmed |
GH-workflow dummyEmbeddingFunction |
github-workflow/config.template.mjs:84 |
Removed (no chroma) |
n/a |
— |
grep -c chromadb = 0 |
Acceptance Criteria
Out of Scope
- The Provider parent-chain wiring itself (the parent-chain realm-inheritance sub) — this ticket consolidates the definition; the chain makes KB inherit it rather than snapshot.
- chromadb-3.x warning suppression via
createSilentExecutor in the defrag (tracked on #12102) — only relevant if the canonical EF doesn't already clear it.
Related
- Epic #12101; PR #12164 (merged Stage 1); #11111 (Chroma-client primitives — adjacent; #11111 deliberately did NOT share
ensureDummyEmbedding at the wrapper layer, so this config-level SSOT is a distinct concern).
Origin Session ID: b124b83a-2cca-4a2b-a711-64868439ba1e
Retrieval Hint: "dummyEmbeddingFunction single source of truth Tier-1 defrag chromadb"
Context
After PR #12164 (Epic #12101 Stage 1) merged and the orchestrator was rebooted (2026-05-29), operator review surfaced that the ChromaDB "dummy embedding function" — used to bypass server-side embedding generation when Neo provides embeddings directly — is defined in multiple divergent places instead of a single Tier-1 source. The unified Chroma topology (Memory Core + Knowledge Base share one instance) makes the EF realm-wide: it belongs once at Tier-1.
The Problem
Four divergent / misplaced definitions of the same dummy EF:
ai/config.template.mjs:612—dummyEmbeddingFunction(name: 'dummy_embedding_function', verbose anti-legacy structure:name/getConfig/constructor.buildFromConfig).ai/mcp/server/knowledge-base/config.template.mjs:114— re-declares its own copy.ai/scripts/maintenance/defragChromaDB.mjs:378-383— hardcodes a third variant withname: 'dummy'. That literal'dummy'is what chromadb 3.x maps to the (non-existent)@chroma-core/dummypackage, producing theCollection schema deserialization … @chroma-core/dummy is not installedwarning seen duringchroma defrag (knowledge-base).ai/mcp/server/github-workflow/config.template.mjs:84— includesdummyEmbeddingFunctionbut never imports chromadb (V-B-A 2026-05-29:grep -c chromadb= 0). Dead config.The Architectural Reality
name,generate,getConfig, and the special ownconstructor.buildFromConfigall survive as callable functions).ChromaManagerreadsaiConfig.dummyEmbeddingFunction; the defrag ignores config and hardcodes its own.The Fix
dummyEmbeddingFunctionleaf in Tier-1ai/config.template.mjs(+ regeneratedconfig.mjs).default: AiConfig.dummyEmbeddingFunctionsnapshot now; becomes chain-inherited once the parent-chain realm-inheritance sub lands).defragChromaDB.mjs: import + useAiConfig.dummyEmbeddingFunctioninstead of the hardcodedname: 'dummy'object. The verbose canonical EF is expected to also clear the chromadb-3.x deserialization warning.dummyEmbeddingFunction(no chroma usage).Contract Ledger
AiConfig.dummyEmbeddingFunction(Tier-1 config key)ai/config.template.mjs:612dummyEmbeddingFunctionknowledge-base/config.template.mjs:114dummyEfdefragChromaDB.mjs:378AiConfig.dummyEmbeddingFunctionname:'dummy'confirmeddummyEmbeddingFunctiongithub-workflow/config.template.mjs:84grep -c chromadb= 0Acceptance Criteria
dummyEmbeddingFunctiondefined exactly once (Tier-1); no independent object-literal definitions in server configs.defragChromaDB.mjsusesAiConfig.dummyEmbeddingFunction; no hardcodedname: 'dummy'.dummyEmbeddingFunction.Out of Scope
createSilentExecutorin the defrag (tracked on #12102) — only relevant if the canonical EF doesn't already clear it.Related
ensureDummyEmbeddingat the wrapper layer, so this config-level SSOT is a distinct concern).Origin Session ID: b124b83a-2cca-4a2b-a711-64868439ba1e Retrieval Hint: "dummyEmbeddingFunction single source of truth Tier-1 defrag chromadb"