---
id: 12102
title: 'Stage 0: extend initServerConfigs.mjs with overlay-preserving template advancement'
state: OPEN
labels:
  - enhancement
  - ai
  - architecture
assignees: []
createdAt: '2026-05-27T20:13:00Z'
updatedAt: '2026-05-27T20:13:00Z'
githubUrl: 'https://github.com/neomjs/neo/issues/12102'
author: neo-opus-ada
commentsCount: 0
parentIssue: 12101
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
---
# Stage 0: extend initServerConfigs.mjs with overlay-preserving template advancement

Authored by Claude Opus 4.7 (Claude Code 1M). Origin Session ID: `ba55de70-c601-448e-9eb4-9c214be1d9c6`. Sub of #12101 (parent Epic).

## Context

Post-pull-from-dev operator-overlay drift detected: 4-of-6 per-MCP-server overlays drift from templates. Specifically `ai/mcp/server/memory-core/config.mjs` still contains `graphProvider: AiConfig.graphProvider || 'openAiCompatible'` banned `||` fallback leftover from pre-merge state; missing `keep_alive` forwarding for ollama + openAiCompatible. Cross-family V-B-A: @neo-gpt confirmed runtime overlay drift broader than #11976 (test-overlay) scope.

Boundary per @neo-gpt 2026-05-27T20:03:56Z A2A: tests read canonical templates/fixtures (#11976 owns); runtime reads operator overlays (this Stage 0 owns extending `initServerConfigs.mjs`). Do NOT absorb #11976; reference as complementary.

## The Problem

`ai/scripts/setup/initServerConfigs.mjs` `detectDrift()` (lines 166-174) currently checks imports/exports only:

```js
const missingImports = templateShape.imports.filter(i => !configShape.imports.includes(i));
const missingExports = templateShape.exports.filter(e => !configShape.exports.includes(e));
```

This misses missing object leaves like `keep_alive` / `contextLimitTokens` / `safeProcessingLimitTokens` that templates add post-merge. `--migrate-config` flag overwrites the active gitignored config from template for broad drift, which does NOT preserve operator overrides.

## The Architectural Reality

`ai/scripts/setup/initServerConfigs.mjs` already owns:
- Top-level Tier-1 `ai/config.mjs` bootstrap + per-server `ai/mcp/server/*/config.mjs` bootstrap
- Clone-if-missing
- One-way template-shape drift detection (imports/exports only per `detectDrift()` lines 166-174)
- Warn-only default
- Tier-1 import materialization via `materializeServerConfigTemplate()` (line 134)
- `--migrate-config` overwrite behavior (lines 241-253)

**Per Epic Implementation Discipline Mandate (extended to Brain bootstrap scripts in Epic #12101)**: extend `initServerConfigs.mjs`; do NOT create parallel "smart-merge primitive."

## The Fix

Extend `detectDrift()` to project per-key paths in the data tree (object-leaf-level drift detection). Add `--merge-config` flag (distinct from `--migrate-config`) implementing conservative-merge mode: preserves existing active config values; adds template-new leaves; preserves Tier-1 import materialization (no regression on existing `from '../../../config.template.mjs'` → `from '../../../config.mjs'` rewrite). Preserve current `--migrate-config` overwrite behavior unchanged.

## Acceptance Criteria

- [ ] **AC-Stage0-1**: Extend `detectDrift()` to project per-key paths in the data tree. Test: post-pull-from-dev `ai/mcp/server/memory-core/config.mjs` missing `ollama.keep_alive` after template adds it triggers drift warning (currently misses per existing imports/exports-only detection).
- [ ] **AC-Stage0-2**: Add `--merge-config` flag (distinct from `--migrate-config`) that runs overlay-preserving template advancement: existing active config values preserved; template-new leaves added; Tier-1 import materialization preserved. Test: `--merge-config` on `memory-core/config.mjs` with operator override `graphProvider: 'custom'` preserves the override AND adds template-new `keep_alive: -1`.
- [ ] **AC-Stage0-3**: Preserve current `--migrate-config` overwrite behavior (no regression on existing CI/automation that uses overwrite mode). Test: invoking `--migrate-config` on a drifted config produces identical output to pre-Stage-0 behavior.

## Out of Scope

- Test-overlay drift (`#11976` owns; complementary, not absorbed)
- Smart-merge primitive as parallel script (extend existing `initServerConfigs.mjs`; PR-review rejects parallel)
- Bulk operator-overlay reset across all servers (consumer-driven; operator runs `--merge-config` per their decision)

## Related

- **Parent Epic**: #12101
- **Discussion**: #12100 §6 Stage 0 v14 + Stage 0 ACs
- **Complementary boundary**: #11976 (test-overlay scope distinct)

Handoff Retrieval Hints: `query_raw_memories("Stage 0 initServerConfigs overlay-preserving template advancement")` + grep `detectDrift` in `ai/scripts/setup/initServerConfigs.mjs`

## Timeline

- 2026-05-27T20:13:01Z @neo-opus-ada added the `enhancement` label
- 2026-05-27T20:13:02Z @neo-opus-ada added the `ai` label
- 2026-05-27T20:13:02Z @neo-opus-ada added the `architecture` label
- 2026-05-27T20:15:31Z @neo-opus-ada added parent issue #12101

