# ADR-112: Mandatory Wiring Verification for New Config Fields and Factory Functions

**Date:** 2026-03-17 | **Status:** ACCEPTED
**Severity:** P0 — Production regression in v0.29.3

## Context

v0.29.3 introduced `EmbeddingsConfig` and `create_embedding_engine()` factory to fix BUG-2 (rebuild ignores configured embedding backend). However, TWO critical regressions shipped:

1. **GraphConfig.path missing**: `_load_graph()` in `main.py:1871` references `cfg.graph.path`, but the `path` field was never added to the `GraphConfig` Pydantic model. Every command that loads the graph (`inspect`, `context`, `run`) crashes with `AttributeError`.

2. **ChunkScorer query-time path not updated**: The new `create_embedding_engine()` factory was correctly wired into `rebuild_command()` but NOT into `graph.py:1510` where `ChunkScorer` is created at query time. Users with `embeddings.backend: bedrock` get a `HFValidationError` because `EmbeddingEngine()` tries to load `amazon.titan-embed-text-v2:0` as a HuggingFace model.

3. **Init duplicate embedding pass**: `init_command()` calls `rebuild_command()` (which now correctly builds Bedrock embeddings) AND then runs a separate `ChunkScorer().build_cache()` which fails because the raw `EmbeddingEngine()` doesn't know about Bedrock.

## Root Cause

**All three bugs share one root cause: incomplete wiring of new abstractions.**

When a new config field or factory function is introduced, ALL consumers must be updated. The v0.29.3 changes updated the `rebuild_command` consumer but missed:
- The Pydantic model definition (`GraphConfig.path`)
- The query-time activation path (`graph.py`)
- The init embedding pass (`init.py`)

## Decision

**Every PR that adds a config field or factory function MUST include a wiring checklist:**

1. **Config field added?** → Grep for ALL references to that field. Verify the Pydantic model defines it.
2. **Factory function added?** → Grep for ALL direct constructor calls of the class it replaces. Update every one.
3. **New code path?** → Verify it's actually reached by running `graq inspect --stats` + `graq run "test"` after the change.

**Minimum verification before release:**
```bash
graq inspect --stats      # Tests graph loading (catches GraphConfig.path)
graq run "test query"     # Tests query-time activation (catches ChunkScorer routing)
graq init --help          # Tests init imports (catches init crashes)
```

## Consequences

**Positive:**
- Prevents model/code field mismatches
- Prevents factory functions that are defined but never called
- Simple 3-command smoke test catches all P0 regressions

**Negative:**
- Adds ~30 seconds to pre-release process
- Requires discipline (not automated yet — consider adding to CI)

## Related

- BUG-4: `GraphConfig` missing `path` — fixed in v0.29.4
- BUG-5: `ChunkScorer` query-time routing — fixed in v0.29.4
- BUG-6: Bedrock cross-region inference profile — fixed in v0.29.4
- GCC MANDATORY: WIRING VERIFICATION (applies globally)
