Summary
Captures the aiConfig configuration model as intent-driven documentation, so the next session inherits the conclusion instead of re-deriving it. It surfaced while picking up Stage 0 (#12102): re-reading state.Provider + the BaseConfig proxy showed the source-level drift/merge approach is the wrong layer — aiConfig is hierarchical nested data, and the Provider already deep-merges it.
The model: a tree of state.Providers (the Tier-1 realm root Neo.ai.Config + per-server children via getParent), each owning only its slice; reads walk up to the owner, writes bubble to the owner. So an operator overlay is a thin child of its template, never a clone — advancing it is inheritance, not a source merge.
Deltas
learn/agentos/AiConfigModel.md (new) — the model + the source-merge anti-pattern it rules out, closing on the test "if you're parsing or rewriting config source to reconcile a template and an overlay, stop."ai/BaseConfig.mjs — the class JSDoc gains the hierarchical-realm intent + a @see link to the guide.
Test Evidence
Documentation-only; no runtime logic changed.
node --check ai/BaseConfig.mjs passes (JSDoc-only edit).- The guide's four relative links resolve to real files:
examples/stateProvider/advanced/MainContainer.mjs, src/state/Provider.mjs, ai/BaseConfig.mjs, learn/agentos/cloud-deployment/Configuration.md.
Post-Merge Validation
None required — no behavior change. Discoverability: the guide is reachable via the @see on Neo.ai.BaseConfig + grep/KB; it intentionally stays out of learn/tree.json (agent-facing architecture intent, like its ConfigSubstrate* / v13-path neighbours).
Evidence: the model is grounded in src/state/Provider.mjs (data_ merge: 'deep' lines 47/61, owner-routed internalSetData, getOwnerOfDataProperty) and ai/BaseConfig.mjs (the getParent override + compileMetaLeaves).
FAIR-band: n/a — operator-directed documentation.
Refs #12102 — its source-merge prescription is retired; the thin-child overlay implementation (a config.mjs that is a thin child rather than a materialized clone) is high-blast follow-on to scope with the epic.
Authored by Claude Opus 4.8 (Claude Code, 1M context).
Summary
Captures the aiConfig configuration model as intent-driven documentation, so the next session inherits the conclusion instead of re-deriving it. It surfaced while picking up Stage 0 (#12102): re-reading
state.Provider+ theBaseConfigproxy showed the source-level drift/merge approach is the wrong layer — aiConfig is hierarchical nested data, and the Provider already deep-merges it.The model: a tree of
state.Providers (the Tier-1 realm rootNeo.ai.Config+ per-server children viagetParent), each owning only its slice; reads walk up to the owner, writes bubble to the owner. So an operator overlay is a thin child of its template, never a clone — advancing it is inheritance, not a source merge.Deltas
learn/agentos/AiConfigModel.md(new) — the model + the source-merge anti-pattern it rules out, closing on the test "if you're parsing or rewriting config source to reconcile a template and an overlay, stop."ai/BaseConfig.mjs— the class JSDoc gains the hierarchical-realm intent + a@seelink to the guide.Test Evidence
Documentation-only; no runtime logic changed.
node --check ai/BaseConfig.mjspasses (JSDoc-only edit).examples/stateProvider/advanced/MainContainer.mjs,src/state/Provider.mjs,ai/BaseConfig.mjs,learn/agentos/cloud-deployment/Configuration.md.Post-Merge Validation
None required — no behavior change. Discoverability: the guide is reachable via the
@seeonNeo.ai.BaseConfig+ grep/KB; it intentionally stays out oflearn/tree.json(agent-facing architecture intent, like itsConfigSubstrate*/v13-pathneighbours).Evidence: the model is grounded in
src/state/Provider.mjs(data_merge: 'deep'lines 47/61, owner-routedinternalSetData,getOwnerOfDataProperty) andai/BaseConfig.mjs(thegetParentoverride +compileMetaLeaves).FAIR-band: n/a — operator-directed documentation.
Refs #12102 — its source-merge prescription is retired; the thin-child overlay implementation (a
config.mjsthat is a thin child rather than a materialized clone) is high-blast follow-on to scope with the epic.Authored by Claude Opus 4.8 (Claude Code, 1M context).