Locate ownership and preserve model contracts

Use this map to place a change and select its verification. It describes source commit 7cb7f20b357f23ee1683670953c7dd0092fa2084, reviewed on 1 October 2026. The public Python model, YAML builder and retained runner have distinct lifecycle and evidence responsibilities.

Construction and execution path

Layer	Responsibility	Source and relevant tests
Public exports and model facade	Stable import names, validated constructors, model lifecycle and analysis properties	`src/ammm/mmm/__init__.py:10`, `src/ammm/mmm/mmm.py:377`; `tests/mmm/test_persistence_contract.py`
Data and graph	Canonical labelled inputs, scaling, parameter graph, contributions and likelihood	`src/ammm/mmm/data_conversion.py:189`, `src/ammm/mmm/_mmm_graph.py:182`; `tests/mmm/test_fixed_effects.py`, `tests/mmm/test_correlated_random_effects.py`
Calibration and persistence	Copied measurement inputs, graph attachment, saved-state validation and replay	`src/ammm/mmm/_mmm_calibration.py:102`, `src/ammm/mmm/persistence.py:62`; `tests/mmm/test_persistence_sampling.py`
Summary, incrementality and optimisation	Tables/intervals, defined spend contrasts and constrained posterior utility	`src/ammm/mmm/summary/factory.py:240`, `src/ammm/mmm/incrementality.py:271`, `src/ammm/mmm/budget_optimizer.py:704`; `tests/mmm/test_counterfactual.py`
Trusted YAML construction	Typed blocks, recursive object resolution, effects, graph, original-scale variables, calibration and optional idata attachment	`src/ammm/mmm/builders/yaml.py:73`; `tests/mmm/builders/test_yaml.py`, `tests/mmm/builders/test_schema.py`
CLI	Input selection, override precedence, verbosity and exit codes	`runme.py:193`, `runme.py:313`, `runme.py:387`; `tests/test_pipeline_reporting.py`
Retained runner	Invocation context, stage order, immutable directory reservation, manifests and failure retention	`src/ammm/pipeline/runner.py:68`, `src/ammm/pipeline/runner.py:156`; `tests/test_pipeline_stage_edges.py`
Evidence and advisory work	Diagnostic policy, prior alternatives, anonymised evidence, deterministic floor and explicit proposal adoption	`src/ammm/mmm/diagnostic_gates.py:507`, `src/ammm/pipeline/stages/ai_advisor.py:88`; `tests/test_prior_sensitivity.py`, `tests/test_pipeline_ai_advisor.py`

The builder constructs a graph; the runner orchestrates fitting and retained outputs. Direct-builder data paths are process-relative whereas runner input paths are YAML-relative. A dry run builds the main graph without exercising every stage (src/ammm/mmm/builders/yaml.py:137, src/ammm/pipeline/runner.py:356, runme.py:163). Keep those boundaries visible when adding a new entry point.

Stage and artefact contract

PipelineStageSpec identifies the stage name, label and handler; PipelineContext carries resolved invocation state. A handler returns an artefact mapping or None for a skipped optional stage. The runner owns stage transitions, records exceptions, marks remaining pending stages not_reached and writes the manifest; handlers should not invent independent success semantics (src/ammm/pipeline/runner.py:68, src/ammm/pipeline/runner.py:295).

When adding or changing a stage, update its directory mapping, stage order, configuration validation, declared outputs and user-facing schemas together. Exercise enabled, disabled, failed and not-reached cases, and verify paths from the retained run root. Existing output directories are reserved exclusively; a repair must not merge a new invocation into an old run (src/ammm/pipeline/artifacts.py:103, src/ammm/pipeline/manifest.py:27). See retained output contracts.

A diagnostic failure is an evidence result and currently does not raise merely to stop orchestration. A provider recommendation cannot weaken the deterministic floor or silently apply a new configuration. Keep process completion, model-risk acceptance and configuration approval as separate records (src/ammm/pipeline/stages/core.py:684, src/ammm/pipeline/stages/ai_advisor.py:181, src/ammm/ai/approval.py:107).

Choose verification from the changed contract

Change	Minimum relevant verification
Public argument, data shape or YAML block	Valid/invalid inputs, default/override behaviour and matching example
Graph, transformation or likelihood	Fixed-input numerical/gradient or distribution checks appropriate to the claim, plus estimator operation boundaries
Calibration or saved state	Build/calibrate/fit lifecycle, copied inputs, save/load replay and prediction identity on labelled data
Counterfactual or optimisation	Units, coordinate order, history/carryover, explicit objective and independent feasibility checks
Runner output or advisory stage	Manifest transitions, optional outputs, failure retention, privacy and local-only execution
Documentation only	Source agreement, local links, examples affected by the change and navigation

Use local checks and typing/performance guidance. A passing software test or synthetic example does not replace an estimator recovery study, causal design review or resource qualification. State the executed scope and retain the source/configuration identity with results.

Raw documentation ownership

docs/source/ is the maintained raw-Markdown documentation. The empty docs-site/ directory has no documentation build, publishing role or runtime contract in this checkout; do not place maintained content there. It can be removed independently without introducing a site generator. Keep the main entry point within two links of each page, and link shared contracts instead of copying defaults into multiple workflows.