Context
Sub-leaf under #12461's B3 cleanup workstream. The parent issue's older census still describes a larger sourcePaths?. class, but current origin/dev V-B-A shows the examples cluster is now exactly one live site:
origin/dev:ai/examples/cloud-deployment/minimal-external-workspace/src/ProtoSource.mjs:43 reads aiConfig.sourcePaths?.ProtoSource ?? 'proto'.
ADR 0019 makes this shape invalid for AiConfig consumers: the Provider SSOT guarantees the resolved tree, and consumers should read resolved leaves at the use site rather than defending against missing subtrees.
The Problem
ProtoSource is an example custom KB source. It is small, but examples are copied as patterns. Keeping sourcePaths?.ProtoSource there teaches future custom source authors to defensively optional-chain an AiConfig subtree and hide a default literal in consumer code.
That is the B3 antipattern from ADR 0019: defensive ?. on an SSOT-guaranteed tree. The fallback literal may be legitimate, but it belongs in the owning config leaf/default contract, not in a consumer-side hidden fallback.
The Architectural Reality
- ADR 0019 §3 B3: defensive
?. on AiConfig reads should be removed; read the resolved leaf and let missing config fail loud.
ai/examples/cloud-deployment/minimal-external-workspace/src/ProtoSource.mjs documents that this source directory comes from aiConfig.sourcePaths.ProtoSource.- Current source has one exact
sourcePaths?. occurrence on origin/dev; no open duplicate leaf for ProtoSource sourcePaths was found.
The Fix
Update ProtoSource to read the resolved leaf directly:
const dir = path.resolve(aiConfig.neoRootDir, aiConfig.sourcePaths.ProtoSource);
If the example needs proto as the default, ensure that default is declared by the relevant config source/leaf rather than hidden behind consumer fallback logic. Do not broaden into the rest of #12461's production-source cleanup clusters.
Contract Ledger Matrix
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
ProtoSource example source-path read |
ADR 0019 B3 + #12461 examples cluster |
Read aiConfig.sourcePaths.ProtoSource directly with no optional-chain or consumer-side default literal |
Fail loud if the SSOT tree/default is missing |
Existing JSDoc/comment stays aligned to direct aiConfig.sourcePaths.ProtoSource |
rg "sourcePaths\\?\\." ai and targeted source inspection show the single site removed |
Decision Record impact
aligned-with ADR 0019.
Acceptance Criteria
Out of Scope
- The full #12461 B3 cleanup across memory-core, daemons, graph, ingestion, and scripts.
- B4 test mutation work (#12435).
- Config-provider rename work (#12452).
Related
Parent: #12461
Epic: #12456
Authority: ADR 0019 (learn/agentos/decisions/0019-aiconfig-reactive-provider-ssot.md)
Handoff Retrieval Hints
rg "sourcePaths\\?\\." aiquery_raw_memories("AiConfig B3 defensive sourcePaths ProtoSource")
Context
Sub-leaf under #12461's B3 cleanup workstream. The parent issue's older census still describes a larger
sourcePaths?.class, but currentorigin/devV-B-A shows the examples cluster is now exactly one live site:origin/dev:ai/examples/cloud-deployment/minimal-external-workspace/src/ProtoSource.mjs:43readsaiConfig.sourcePaths?.ProtoSource ?? 'proto'.ADR 0019 makes this shape invalid for
AiConfigconsumers: the Provider SSOT guarantees the resolved tree, and consumers should read resolved leaves at the use site rather than defending against missing subtrees.The Problem
ProtoSourceis an example custom KB source. It is small, but examples are copied as patterns. KeepingsourcePaths?.ProtoSourcethere teaches future custom source authors to defensively optional-chain anAiConfigsubtree and hide a default literal in consumer code.That is the B3 antipattern from ADR 0019: defensive
?.on an SSOT-guaranteed tree. The fallback literal may be legitimate, but it belongs in the owning config leaf/default contract, not in a consumer-side hidden fallback.The Architectural Reality
?.onAiConfigreads should be removed; read the resolved leaf and let missing config fail loud.ai/examples/cloud-deployment/minimal-external-workspace/src/ProtoSource.mjsdocuments that this source directory comes fromaiConfig.sourcePaths.ProtoSource.sourcePaths?.occurrence onorigin/dev; no open duplicate leaf forProtoSource sourcePathswas found.The Fix
Update
ProtoSourceto read the resolved leaf directly:const dir = path.resolve(aiConfig.neoRootDir, aiConfig.sourcePaths.ProtoSource);If the example needs
protoas the default, ensure that default is declared by the relevant config source/leaf rather than hidden behind consumer fallback logic. Do not broaden into the rest of #12461's production-source cleanup clusters.Contract Ledger Matrix
ProtoSourceexample source-path readaiConfig.sourcePaths.ProtoSourcedirectly with no optional-chain or consumer-side default literalaiConfig.sourcePaths.ProtoSourcerg "sourcePaths\\?\\." aiand targeted source inspection show the single site removedDecision Record impact
aligned-with ADR 0019.
Acceptance Criteria
ProtoSource.mjsno longer containssourcePaths?.or?? 'proto'for the AiConfig read.aiConfig.sourcePaths.ProtoSourceas the source directory authority.sourcePaths?.occurrences remain underai/.Out of Scope
Related
Parent: #12461 Epic: #12456 Authority: ADR 0019 (
learn/agentos/decisions/0019-aiconfig-reactive-provider-ssot.md)Handoff Retrieval Hints
rg "sourcePaths\\?\\." aiquery_raw_memories("AiConfig B3 defensive sourcePaths ProtoSource")