<!-- mixed: the Specification, Tests, and Documentation sections are normative; the Provenance and Rationale sections are informative. -->

# Phase 4 option (e): evidence-typed obligation source and the declared-structure gate

Status: **implementation spec**, reached by review consensus. This supersedes the
four options previously weighed for the fixed-target `_ROOT_OBLIGATIONS`
constant. It amends the Phase 4 derivation contract in
`docs/research/phase4-decomposition-design.md` and the Phase 4 gate text in
`docs/self-host.md`.

## Provenance (informative)

The fixed target's base tree carries no observable cross-component imports: its
component files are import-free `NotImplementedError` stubs, and the only
cross-component importer is `tests/run_visible.py`, which is outside every
component. The declared `report -> (parse, render)` ordering is therefore
knowledge about the intended solution (expressed by the fixture's acceptance
script), not a fact about the base commit. The same is true of the nested
`report-format -> report-emit` chain and of the per-component criterion
allocation: even `_SOLUTION_FILES` imports nothing, so the ordering is not an
import edge anywhere.

Deriving the fixture would legitimately drop that ordering, changing the
scheduling and metrics every committed milestone report was measured against, and
would destroy the deliberate two-level nesting the recursive arms exercise.
Manufacturing imports in the stubs to make the scanner see the edge would be
fabricating evidence, which the derivation module explicitly refuses. The
resolution is to keep the fixed target's contract as declared input, make that
declaration first-class and mechanically justified, and scope the gate to what it
actually protects.

## Specification (normative)

### S1. Typed obligation source

Remove the module constant `_ROOT_OBLIGATIONS` from
`src/orchestrator/experiment_target.py` (currently lines 170-221).

`TargetSnapshot` gains three fields:

- `obligations_source: str` — one of `DERIVED` or `DECLARED`.
- `non_derivable_axes: Tuple[str, ...]` — empty iff `DERIVED`; non-empty and a
  subset of `{EDGES, NESTING, ALLOCATION}` iff `DECLARED`.
- `non_derivable_reason: str` — empty iff `DERIVED`; non-empty iff `DECLARED`.

The values are UPPER_SNAKE case per `AGENTS.md`, and the three axis identifiers
are catalogued exactly once in `docs/glossary.md`.

### S2. One builder

The fixture's obligations move out of scheduler code into fixture-owned,
versioned data (a manifest file loaded by the fixed-target fixture module), not a
Python constant in `experiment_target.py`.

`build_fixed_target` must construct its snapshot through the single validated
builder, `build_target`, passing the manifest and the typed source:

```text
build_target(
    repository, commit,
    snapshot_id=..., task_statement=TASK_STATEMENT,
    project_kernel=PROJECT_KERNEL, visible_commands=VISIBLE_COMMANDS,
    components=components, owned_scope=("src/**",),
    acceptance_criteria=ROOT_ACCEPTANCE_CRITERIA,
    obligations=<fixture manifest obligations>,
    non_derivable_axes=<fixture manifest axes>,
    non_derivable_reason=<fixture manifest reason>,
    budgets=<fixture budget input>,
    trial_scripts=TRIAL_SCRIPTS,
)
```

Requirements:

- `trial_scripts=TRIAL_SCRIPTS` is passed explicitly. Dropping it turns seeds
  `1003`/`1004` from their calibrated kinds into the default, destroying the
  calibration devices.
- The fixture's `contract_hash` stays byte-identical to its pre-change value;
  that value is captured before the change and asserted as a literal in a test.
- `target.repository` becomes absolute (it already does under `build_target`);
  this is visible in recorded state but is not hashed.

### S3. Budget channel

`build_target` gains `budgets: Optional[Mapping[str, float]] = None`.

- Keyed by component name; a component not named uses the default `30.0`.
- Threaded into `derive_obligations` (which must accept the per-component mapping
  rather than only its current scalar `budget`).
- Fail closed at the boundary: unknown keys are errors (a typo must not silently
  leave the default in place), and values must be finite and non-negative.

Budgets are **excluded from the projection** (S4). They are declared input on
both paths: derivation receives them, never invents them. Budget-only
declarations are therefore unnecessary and are refused by the predicate.

### S4. Projection

A `DECLARED` obligation set is normalized into a component projection before
comparison. Define the three axes:

- `EDGES` — after projection, the declared dependency edge set differs from the
  derived edge set.
- `NESTING` — at least one declared top-level obligation carries nested
  obligations; derivation never produces nesting.
- `ALLOCATION` — at least one component's declared criterion set differs from the
  derived full declared criteria set.

Projection rules:

1. Expand each top-level declared obligation's `scope` glob against the tracked
   Python files at the base commit, using the same `_component_of` matcher the
   derivation and the write-scope gate already share. Every matched file must be
   owned by exactly one component. Zero matched files, or files owned by more
   than one component, fails closed.
2. Each component must be claimed by exactly one top-level declared obligation; a
   component claimed zero or multiple times fails closed.
3. Nesting is compared as presence/shape, not edge-projected.
4. Budgets, descriptions, and child-id spelling are excluded from the
   comparison.

Recorded asymmetry: file-backed resolution means a `DECLARED` set cannot
reference a file-less (greenfield) component, because its scope expands to zero
files, while the derived path emits an obligation per component regardless of
matched files. Accept fail-closed now; pattern-containment resolution is the
named extension if greenfield declarations are ever needed (S12).

### S5. Predicate

Derivation is **always recomputed**, regardless of source. A raising derivation
is fatal with `ExperimentError`. The only failure modes are overlap, duplicate
component names, and an unreadable commit; unparseable files and unclaimed files
are non-failures by design.

```text
derived = derive_obligations(repository, commit, components, criteria, budgets)
axes_present = set()
if projected_declared_edges != derived_edges:
    axes_present.add("EDGES")
if declared_nesting_shape != derived_nesting_shape:      # keyed by component
    axes_present.add("NESTING")
if declared_allocation_shape != derived_allocation_shape: # keyed by component
    axes_present.add("ALLOCATION")

admissible = (
    axes_present                                       # non-empty
    and set(non_derivable_axes) == axes_present         # names ALL divergence
    and non_derivable_reason.strip()                    # rationale present
)
```

A `DECLARED` target is admitted iff `admissible`; otherwise `build_target` raises
`ExperimentError`. `DERIVED` targets carry empty axes and an empty reason, and
skip the comparison. There is no hard-coded axis checklist: every axis is a diff
against `derive_obligations`'s live output, so a declaration resting on an axis
that later becomes derivable starts failing on its own. The `NESTING` and
`ALLOCATION` shapes are keyed by **projected component**, not by raw child id,
because a derived child id is always the component name and keying by child id let
a pure rename register as structural divergence.

**Amendment (re-review).** This section originally specified
`set(non_derivable_axes) <= axes_present` and permitted unnamed-but-divergent
axes, "requiring exact match would force spurious claims." The adversarial
[review](phase4-option-e-review-report.md) falsified that rule: subset admission
let a declaration rest almost entirely on undeclared divergence and stay alive on
a single token axis, which is the opposite of mechanically justified. The shipped
rule is **exact equality**, so the named set is a complete account of the
divergence. The cost is real but bounded: a declaration that incidentally
diverges on an axis must say so in its rationale — one clause of prose against an
unbounded smuggling channel.

### S6. Validation order

The order is normative:

1. **Shape** — required keys including `scope` (top-level and nested), non-empty
   string `child_id`, `criterion_ids` a sequence of non-empty strings, finite
   non-negative budgets, acceptance shape.
2. **Coverage** — the existing bidirectional rule, unchanged.
3. **Projection** — bijection, scope resolution, and component-claim (S4).
4. **Predicate** — axes subset and reason (S5).

Coverage must precede the projection because the allocation comparison consumes
coverage-validated criterion sets. Shape must precede coverage so a scopeless
obligation fails at the boundary rather than with a `KeyError` at
`plan_decomposition`. Reorder the current single loop accordingly.

### S7. Nested validation

Nested obligations are validated recursively with the same shape rules as
top-level, plus:

- `criterion_ids` must be a non-empty subset of the parent's `criterion_ids` and
  of the declared criteria (non-vacuity).
- Budgets must be finite and non-negative.

Uniqueness/partition of nested criteria is left to the recursive-planning pilot's
validator review, not this gate.

**Recorded asymmetry (re-review condition).** `EDGES` is measured only over
*top-level* obligations, and only for dependency names the projection can
express. A nested obligation's own `depends_on` is validated for shape and for
naming a real sibling, but its **honesty is not gate-enforced**: a declared edge
to a nested child id projects to nothing and reads as *no edge* rather than as
divergence, so a nested edge cannot be justified by measurement and cannot be
falsified by it either. The top-level edge non-claim in S9 covers the scanner
accuracy limits; this is a different limit, and it is named here so the pilot
inherits it deliberately.

**Re-open trigger.** If pilot declarations come to depend on *nested* edge
ordering, this asymmetry stops being acceptable inherited surface and concern 2
must be re-opened: `derive_dependencies` would need to project nested structure,
or nested edges would need their own axis.

### S8. Admissibility and absorption principle

- **Admissibility** — `DECLARED` is admissible exactly for divergence derivation
  cannot express today: because the signal is unobservable in the tree (`EDGES`),
  or because design defers the structure to the bounded recursive-planning pilot
  (`NESTING`, `ALLOCATION`). Deferred is not permanent; the measured diff
  self-tracks when those become expressible.
- **Absorption** — the derivation parameter surface grows to absorb legitimate
  needs that design does not defer to the pilot (budgets now). Parameters never
  pre-empt the pilot's design space.

### S9. Gate text and documentation

Rewrite the Phase 4 gate outcome clause, scoped to **decomposition structure**
(obligations, dependencies, scopes, criterion allocation):

- Reproducibility of the declared structure is mechanically refuted by the
  predicate.
- Necessity of a declared edge is not statically provable and is **not claimed**.
- `_commands_for` and `_SOLUTION_FILES` are named out of scope on two grounds:
  they are candidate production rather than decomposition, and they are
  transitional machinery retired when the patch path replaces the scripted path
  (`verify_commands_for` is the already target-general surface).

Update `docs/self-host.md` (Phase 4 gate status, currently around line 120) and
`docs/research/phase4-decomposition-design.md` (points 2-5 of the derivation
contract, and the fixed-target status notes). Update `build_target`'s docstring,
which currently describes `obligations=` as an unconditional override
"validated identically". Record the gate-text change as breaking, with this
document as rationale.

### S10. Identity and hashing

The typed fields determine contract shape, so they belong in
`TargetSnapshot.snapshot_hash()`. They must stay **out of** `contract_hash`, both
because they are provenance rather than what the candidate must satisfy and
because adding them would break the fixture's contract byte-identity.

Audit committed evidence before landing: if it keys on `contract_hash` the change
is free; if it keys on `snapshot_hash`, the formula change is an evidence-visible
break needing the same documented rationale. Default is include in
`snapshot_hash`, with the F10 rule (post-build mutation must change identity) as
the tie-breaker. The fixture's `snapshot_hash` is already rebuild-unstable (a
fresh commit per `build_fixed_target` call, and the commit is hashed), so the
stability regression bites real targets with fixed base commits only.

### S11. Migration (complete call-site list)

Delete or migrate every `obligations=` call site. Supplying `obligations=` implies
`DECLARED`, and `DECLARED` requires axes and a reason, so every caller is a
migration item.

| Call site | Disposition |
| --- | --- |
| `experiment_target.py:170-221` `_ROOT_OBLIGATIONS`, used at `:307`, `:484` | Replace with the fixture manifest; route `build_fixed_target` through `build_target`. |
| `trial_driver.py:65`, `experiment.py:72` | Dead imports of `_ROOT_OBLIGATIONS`; delete. Re-export the manifest loader deliberately if the facade needs it. |
| `test_phase2_general_target.py:116-127` (`_build_calc_target`) | `obligations=None` (derive). Declared is identical to derived and is refused; the derived child id is `calc`, preserving `:320`. |
| `test_phase2_general_target.py:566-613` (greet) | Stays `DECLARED` with `non_derivable_axes=("ALLOCATION",)` and a reason. Behavioral necessity witness: derivation stamps both mandatory criteria on each child, so the `core` leaf, patching only `greet/core.py`, could not satisfy the mandatory `AC-UTIL`. |
| `test_phase2_general_target.py:268-311` (builder negatives) | Give real globs, scopes, and axes so each case tests the rule in its name. `:265` (unresolvable commit) is unchanged: commit resolution fails first. |
| `test_phase3_project_oracle.py:186-212` (self target) | `obligations=None` (derive). Manifest path confirmed independent of `target.obligations`. |
| `test_derive_obligations.py:222-249` (override pin) | Replace with an admitted/refused pair: a divergent override admitted with its axis named, and a derived-equivalent override refused. |
| `test_derive_obligations.py:268-276` (fixed-target declaration) | Update to assert the manifest path, the axes, and the preserved `report -> (parse, render)` dependency. |

### S12. Revisit triggers

- The bounded recursive-planning pilot lands: `NESTING` and `ALLOCATION`
  declarations should shrink and eventually fail closed unaided.
- An independent re-baseline of the fixed target.
- The patch path retires the scripted command map.
- Derivation learns to nest (the F2 scenario): nested child ids must be excluded
  from the `NESTING` shape the way top-level spelling now is, or a nested rename
  will manufacture `NESTING` divergence. Recorded by the option (e) re-review as
  a forward obligation on the pilot.
- Concern 6 (git-call amplification) worsens further: axis measurement now also
  invokes `derive_obligations`, so a declared build runs the `ls-tree` scan
  additional times. Not a correctness defect; revisit if per-target build cost
  matters.
- Greenfield declared scopes are needed: add pattern-containment resolution for
  file-less components.

## Tests (normative)

1. **Fixture routing identity** — `build_fixed_target` produces a `contract_hash`
   equal to the captured pre-change literal, `trial_scripts == TRIAL_SCRIPTS`,
   and an absolute `repository`.
2. **Fixture admitted** — the fixed target is `DECLARED`, its axes are a subset of
   the measured `axes_present`, and it is admitted.
3. **Refused no-divergence declaration** — a declaration identical to the derived
   set (the calc shape) raises `ExperimentError`.
4. **Raising derivation fatal** — a target with overlapping component globs and a
   supplied declaration raises `ExperimentError`.
5. **Greet positive pin** — the two-component per-leaf declaration is admitted on
   `ALLOCATION` alone.
6. **Nested validation** — a nested obligation with an empty `child_id`, an
   undeclared criterion, a non-finite budget, or no criteria raises
   `ExperimentError`.
7. **Typed-field discipline** — `DERIVED` with non-empty axes or reason raises;
   `DECLARED` with empty axes or empty reason raises.
8. **Command-key drift pin** — a conformance test asserts `_commands_for`'s node
   keys equal the fixture manifest's child ids, top-level and nested.
9. **Negative builder cases** — each of `test_phase2_general_target.py:268-311`
   reaches and exercises its named rule.
10. **Docs gates** — `scripts/check-docs`, `scripts/check-static`, and
    `scripts/check-tests` pass.

## Rationale (informative)

The earlier options were rejected on their own merits. Keeping the declaration
without a gate leaves the exception unenforced. Re-baselining the fixed target
trades a scarce committed evidence base for gate literalism, and deriving from a
stub tree with no import edges would model a task the fixture does not actually
pose. Manufacturing imports in the stubs fabricates observable evidence — the
exact move `derive_obligations` refuses on the principle that a dependency is an
import, not an assertion. Option (e) keeps the fixture's declared contract, makes
the declaration first-class and mechanically justified, and rewrites the gate as
an accurate outcome clause rather than a mechanism clause whose prose overclaims.
