Phase 3: runtime-config seam cleanup to Phase 4 boundary

docs/design/phase-1b-config-import-audit.md

@@ -0,0 +1,58 @@
+# Phase 1B config import audit
+
+
+Total `import { config } from` sites under `src/`: **51**
+
+| File | Initial class |
+| --- | --- |
+| `src/services/memory-audn.ts` | mixed or construction-time |
+| `src/services/memory-ingest.ts` | mixed or construction-time |
+| `src/services/retrieval-format.ts` | mixed or construction-time |
+| `src/services/memory-crud.ts` | mixed or construction-time |
+| `src/services/retrieval-policy.ts` | mixed or construction-time |
+| `src/services/reranker.ts` | mixed or construction-time |
+| `src/services/write-security.ts` | request-time/module-read |
+| `src/services/consensus-validation.ts` | request-time/module-read |
+| `src/services/embedding.ts` | mixed or construction-time |
+| `src/services/agentic-retrieval.ts` | request-time/module-read |
+| `src/services/chunked-extraction.ts` | mixed or construction-time |
+| `src/services/consensus-extraction.ts` | constant-or-env bootstrap |
+| `src/services/conflict-policy.ts` | mixed or construction-time |
+| `src/services/__tests__/retrieval-trace.test.ts` | mixed or construction-time |
+| `src/services/extraction-cache.ts` | request-time/module-read |
+| `src/services/__tests__/current-state-retrieval-regression.test.ts` | constant-or-env bootstrap |
+| `src/services/cost-telemetry.ts` | mixed or construction-time |
+| `src/services/lesson-service.ts` | request-time/module-read |
+| `src/services/deferred-audn.ts` | request-time/module-read |
+| `src/services/__tests__/staged-loading.test.ts` | mixed or construction-time |
+| `src/__tests__/route-validation.test.ts` | mixed or construction-time |
+| `src/services/consolidation-service.ts` | request-time/module-read |
+| `src/__tests__/smoke.test.ts` | request-time/module-read |
+| `src/services/composite-grouping.ts` | mixed or construction-time |
+| `src/services/query-expansion.ts` | mixed or construction-time |
+| `src/services/retrieval-trace.ts` | constant-or-env bootstrap |
+| `src/services/__tests__/deferred-audn.test.ts` | request-time/module-read |
+| `src/services/search-pipeline.ts` | mixed or construction-time |
+| `src/services/memory-search.ts` | mixed or construction-time |
+| `src/services/__tests__/write-security.test.ts` | request-time/module-read |
+| `src/services/llm.ts` | mixed or construction-time |
+| `src/services/memory-storage.ts` | mixed or construction-time |
+| `src/app/__tests__/composed-boot-parity.test.ts` | mixed or construction-time |
+| `src/app/__tests__/runtime-container.test.ts` | request-time/module-read |
+| `src/db/repository-lessons.ts` | mixed or construction-time |
+| `src/db/migrate.ts` | constant-or-env bootstrap |
+| `src/db/repository-entities.ts` | mixed or construction-time |
+| `src/db/repository-read.ts` | mixed or construction-time |
+| `src/db/repository-links.ts` | mixed or construction-time |
+| `src/db/query-helpers.ts` | mixed or construction-time |
+| `src/db/repository-vector-search.ts` | mixed or construction-time |
+| `src/db/agent-trust-repository.ts` | mixed or construction-time |
+| `src/db/__tests__/test-fixtures.ts` | mixed or construction-time |
+| `src/db/__tests__/claim-slot-backfill.test.ts` | mixed or construction-time |
+| `src/db/__tests__/links.test.ts` | mixed or construction-time |
+| `src/db/repository-representations.ts` | mixed or construction-time |
+| `src/db/__tests__/dual-write-representations.test.ts` | request-time/module-read |
+| `src/db/__tests__/mutation-audit.test.ts` | mixed or construction-time |
+| `src/db/__tests__/temporal-invalidation.test.ts` | mixed or construction-time |
+| `src/db/__tests__/temporal-neighbors.test.ts` | mixed or construction-time |
+| `src/db/__tests__/canonical-memory-objects.test.ts` | mixed or construction-time |

src/__tests__/config-singleton-audit.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Config singleton import regression gate.
+ *
+ * Counts the non-test source files that bind the module-level config
+ * singleton value from config.js (any import/export pattern). The threshold
+ * should only move DOWN as config-threading PRs land. Any PR that adds
+ * a new singleton import must raise the threshold explicitly — that
+ * friction is the point.
+ *
+ * This test does not depend on a live database or runtime — it reads
+ * source files statically, matching the pattern in
+ * deployment-config.test.ts.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, dirname, extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SRC = resolve(__dirname, '..');
+
+/**
+ * Maximum allowed non-test source files that bind the runtime config
+ * singleton value from config.js. Ratchet this DOWN after each
+ * config-threading PR lands.
+ * Current baseline: 34 files after the ingest/lineage config-threading
+ * cleanup removed those last singleton reads from `memory-lineage.ts`
+ * and `memory-ingest.ts`.
+ * Includes multi-import forms (e.g. `import { config, updateRuntimeConfig }`)
+ * and re-exports (e.g. `export { config } from`).
+ */
+const MAX_SINGLETON_IMPORTS = 34;
+
+/**
+ * Matches any import or re-export that binds the `config` value (not
+ * just a type) from a path ending in `config.js` or `config`. Covers
+ * single-line and multiline import blocks:
+ *   import { config } from '../config.js'
+ *   import { config, updateRuntimeConfig } from '../config.js'
+ *   import {\n  config,\n  updateRuntimeConfig,\n} from '../config.js'
+ *   export { config, ... } from './config.js'
+ * Excludes `import type`-only statements.
+ */
+const CONFIG_BINDING_RE = /(?:import|export)\s*\{[^}]*\bconfig\b[^}]*\}\s*from\s*['"][^'"]*config/s;
+const IMPORT_TYPE_ONLY_RE = /import\s+type\s*\{/;
+
+function collectTsFiles(dir: string): string[] {
+  const results: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = resolve(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === '__tests__' || entry.name === 'node_modules') continue;
+      results.push(...collectTsFiles(full));
+    } else if (entry.isFile() && extname(entry.name) === '.ts') {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+function findSingletonImporters(): string[] {
+  const files = collectTsFiles(SRC);
+  const matches: string[] = [];
+  for (const filePath of files) {
+    const content = readFileSync(filePath, 'utf-8');
+    // Find all import/export blocks from a config path that bind `config`
+    const hits = content.match(new RegExp(CONFIG_BINDING_RE.source, 'gs')) ?? [];
+    const hasRuntimeBinding = hits.some((hit) => !IMPORT_TYPE_ONLY_RE.test(hit));
+    if (hasRuntimeBinding) matches.push(filePath);
+  }
+  return matches.sort();
+}
+
+describe('config singleton regression gate', () => {
+  it(`non-test source files importing config singleton must not exceed ${MAX_SINGLETON_IMPORTS}`, () => {
+    const files = findSingletonImporters();
+
+    expect(files.length).toBeLessThanOrEqual(MAX_SINGLETON_IMPORTS);
+
+    // Print the list on failure so the developer knows exactly which
+    // files to inspect or thread.
+    if (files.length > MAX_SINGLETON_IMPORTS) {
+      console.error(
+        `Config singleton imports (${files.length}) exceed threshold (${MAX_SINGLETON_IMPORTS}):\n` +
+          files.map((f) => `  ${f}`).join('\n'),
+      );
+    }
+  });
+
+  it('threshold is not stale (count should be close to threshold)', () => {
+    const files = findSingletonImporters();
+    const slack = MAX_SINGLETON_IMPORTS - files.length;
+
+    // If the threshold has more than 5 files of slack, a threading PR
+    // landed without ratcheting the threshold down. Warn but don't fail
+    // — the primary gate is the upper-bound test above.
+    if (slack > 5) {
+      console.warn(
+        `Config singleton threshold has ${slack} files of slack ` +
+          `(threshold=${MAX_SINGLETON_IMPORTS}, actual=${files.length}). ` +
+          `Consider ratcheting MAX_SINGLETON_IMPORTS down to ${files.length + 2}.`,
+      );
+    }
+  });
+});

src/__tests__/memory-route-config-seam.test.ts

@@ -0,0 +1,178 @@
+/**
+ * Route-level config seam tests for createMemoryRouter.
+ *
+ * Verifies that read-side route config now comes from the injected adapter
+ * rather than the module-level singleton for health/config responses and
+ * search-limit clamping.
+ */
+
+import express from 'express';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createMemoryRouter } from '../routes/memories.js';
+import type { MemoryService } from '../services/memory-service.js';
+
+interface BootedApp {
+  baseUrl: string;
+  close: () => Promise<void>;
+}
+
+interface MutableRouteConfig {
+  retrievalProfile: string;
+  embeddingProvider: 'openai';
+  embeddingModel: string;
+  llmProvider: 'openai';
+  llmModel: string;
+  clarificationConflictThreshold: number;
+  maxSearchResults: number;
+  hybridSearchEnabled: boolean;
+  iterativeRetrievalEnabled: boolean;
+  entityGraphEnabled: boolean;
+  crossEncoderEnabled: boolean;
+  agenticRetrievalEnabled: boolean;
+  repairLoopEnabled: boolean;
+}
+
+async function bindEphemeral(app: ReturnType<typeof express>): Promise<BootedApp> {
+  const server = app.listen(0);
+  await new Promise<void>((resolve) => server.once('listening', () => resolve()));
+  const addr = server.address();
+  const port = typeof addr === 'object' && addr ? addr.port : 0;
+  return {
+    baseUrl: `http://localhost:${port}`,
+    close: () => new Promise<void>((resolve) => server.close(() => resolve())),
+  };
+}
+
+describe('memory route config seam', () => {
+  let booted: BootedApp;
+  let routeConfig: MutableRouteConfig;
+  const search = vi.fn();
+
+  beforeAll(async () => {
+    routeConfig = {
+      retrievalProfile: 'route-adapter-profile',
+      embeddingProvider: 'openai',
+      embeddingModel: 'adapter-embedding-model',
+      llmProvider: 'openai',
+      llmModel: 'adapter-llm-model',
+      clarificationConflictThreshold: 0.91,
+      maxSearchResults: 3,
+      hybridSearchEnabled: true,
+      iterativeRetrievalEnabled: false,
+      entityGraphEnabled: true,
+      crossEncoderEnabled: true,
+      agenticRetrievalEnabled: false,
+      repairLoopEnabled: true,
+    };
+
+    search.mockResolvedValue({
+      memories: [],
+      injectionText: '',
+      citations: [],
+      retrievalMode: 'flat',
+    });
+
+    const service = {
+      search,
+      fastSearch: vi.fn(),
+      workspaceSearch: vi.fn(),
+      ingest: vi.fn(),
+      quickIngest: vi.fn(),
+      storeVerbatim: vi.fn(),
+      workspaceIngest: vi.fn(),
+      expand: vi.fn(),
+      expandInWorkspace: vi.fn(),
+      list: vi.fn(),
+      listInWorkspace: vi.fn(),
+      getStats: vi.fn(),
+      consolidate: vi.fn(),
+      executeConsolidation: vi.fn(),
+      evaluateDecay: vi.fn(),
+      archiveDecayed: vi.fn(),
+      checkCap: vi.fn(),
+      getMutationSummary: vi.fn(),
+      getRecentMutations: vi.fn(),
+      getAuditTrail: vi.fn(),
+      getLessons: vi.fn(),
+      getLessonStats: vi.fn(),
+      reportLesson: vi.fn(),
+      deactivateLesson: vi.fn(),
+      reconcileDeferred: vi.fn(),
+      resetBySource: vi.fn(),
+      get: vi.fn(),
+      delete: vi.fn(),
+    } as unknown as MemoryService;
+
+    const configRouteAdapter = {
+      current: () => ({ ...routeConfig }),
+      update: (updates: { maxSearchResults?: number }) => {
+        if (updates.maxSearchResults !== undefined) {
+          routeConfig.maxSearchResults = updates.maxSearchResults;
+        }
+        return Object.keys(updates);
+      },
+    };
+
+    const app = express();
+    app.use(express.json());
+    app.use('/memories', createMemoryRouter(service, configRouteAdapter));
+    booted = await bindEphemeral(app);
+  });
+
+  beforeEach(() => {
+    search.mockClear();
+    routeConfig.maxSearchResults = 3;
+  });
+
+  afterAll(async () => {
+    await booted.close();
+  });
+
+  it('serves health/config payloads from the injected adapter snapshot', async () => {
+    const healthRes = await fetch(`${booted.baseUrl}/memories/health`);
+    expect(healthRes.status).toBe(200);
+    const healthBody = await healthRes.json();
+    expect(healthBody.config.retrieval_profile).toBe('route-adapter-profile');
+    expect(healthBody.config.max_search_results).toBe(3);
+
+    const putRes = await fetch(`${booted.baseUrl}/memories/config`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ max_search_results: 7 }),
+    });
+    expect(putRes.status).toBe(200);
+    const putBody = await putRes.json();
+    expect(putBody.applied).toContain('maxSearchResults');
+    expect(putBody.config.max_search_results).toBe(7);
+
+    const updatedHealthRes = await fetch(`${booted.baseUrl}/memories/health`);
+    const updatedHealthBody = await updatedHealthRes.json();
+    expect(updatedHealthBody.config.max_search_results).toBe(7);
+  });
+
+  it('clamps search limits using the injected adapter snapshot', async () => {
+    await fetch(`${booted.baseUrl}/memories/search`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        user_id: 'user-1',
+        query: 'route seam query',
+        limit: 50,
+      }),
+    });
+
+    expect(search).toHaveBeenCalledWith(
+      'user-1',
+      'route seam query',
+      undefined,
+      3,
+      undefined,
+      undefined,
+      undefined,
+      {
+        retrievalMode: undefined,
+        tokenBudget: undefined,
+      },
+    );
+  });
+});

src/__tests__/route-validation.test.ts

@@ -21,17 +21,13 @@ vi.mock('../services/embedding.js', async (importOriginal) => {
 });
 
 import { pool } from '../db/pool.js';
-import { config } from '../config.js';
 import { MemoryRepository } from '../db/memory-repository.js';
 import { ClaimRepository } from '../db/claim-repository.js';
 import { MemoryService } from '../services/memory-service.js';
 import { createMemoryRouter } from '../routes/memories.js';
+import { setupTestSchema } from '../db/__tests__/test-fixtures.js';
 import express from 'express';
-import { readFileSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEST_USER = 'route-validation-test-user';
 const VALID_UUID = '00000000-0000-0000-0000-000000000001';
 const INVALID_UUID = 'not-a-uuid';
@@ -42,9 +38,7 @@ const app = express();
 app.use(express.json());
 
 beforeAll(async () => {
-  const raw = readFileSync(resolve(__dirname, '../db/schema.sql'), 'utf-8');
-  const sql = raw.replace(/\{\{EMBEDDING_DIMENSIONS\}\}/g, String(config.embeddingDimensions));
-  await pool.query(sql);
+  await setupTestSchema(pool);
 
   const repo = new MemoryRepository(pool);
   const claimRepo = new ClaimRepository(pool);
@@ -124,7 +118,7 @@ describe('GET /memories/list — source_site filter', () => {
 });
 
 describe('POST /memories/search — scope and observability contract', () => {
-  it('returns canonical user scope and only includes observability fields that are actually emitted', async () => {
+  it('returns canonical user scope and only includes observability sections that the retrieval path actually emitted', async () => {
     const res = await fetch(`${baseUrl}/memories/search`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -138,10 +132,9 @@ describe('POST /memories/search — scope and observability contract', () => {
     expect(res.status).toBe(200);
     const body = await res.json();
     expect(body.scope).toEqual({ kind: 'user', userId: TEST_USER });
-    expect(body.observability).toBeDefined();
-    expect(body.observability.retrieval ?? null).toBe(null);
-    expect(body.observability.packaging).toBeDefined();
-    expect(body.observability.assembly).toBeDefined();
+    expect(body.observability?.retrieval).toBeUndefined();
+    expect(body.observability?.packaging?.packageType).toBe('subject-pack');
+    expect(body.observability?.assembly?.blocks).toEqual(['subject']);
   });
 
   it('returns canonical workspace scope for workspace searches', async () => {