core/docs/adr/ADR-0226-residual-gated-practice-loop-v1.md

ADR-0226: Residual-Gated Practice Loop v1

Status: Proposed

Date: 2026-06-22

Scope: Kernel diagnostics, bounded contemplation, sealed practice, and read-only trace display

Depends on: ADR-0225 and PR #862

1. Summary

Residual-Gated Practice Loop v1 is the first proposed integrated, deterministic improvement loop over CORE's existing problem-frame and contract machinery:

failed/refused contract
→ typed residual
→ eligibility gate
→ bounded compute
→ deterministic candidate exploration
→ contract replay
→ sealed practice trace
→ reviewed promotion only

The loop turns a refusal into inspectable, bounded practice evidence. It does not turn a refusal into permission to guess. A candidate can produce an answer only after the existing contract authority is replayed and the applicable proof obligations close. If no candidate closes, the original refusal remains in force.

This ADR defines the whole capability tranche and the authority boundaries between its future components. It implements none of them.

2. Why this exists

CORE already has the machinery that this loop must connect:

• proposal-first construction hypotheses;
• exact ProblemFrame facts, bindings, and evidence spans;
• organ-specific ContractAssessment closure and refusal;
• the diagnostic-only ContractResidual projection implemented by PR #862;
• typed refusal and proof-gated answer disciplines;
• deterministic trace and replay conventions;
• sealed practice and reliability-ledger concepts;
• read-only contemplation miners that emit speculative, review-required findings;
• reviewed teaching and proposal mutation paths; and
• Workbench as an operator/auditor surface over persisted evidence.

None of those concepts is introduced by this ADR. The missing capability is a safe composition law between them.

Without an explicit composition law, a future search implementation could accidentally treat a residual as a repair command, let a budget grant become an admission decision, promote an explored candidate without replay, or give a UI execution authority. The purpose of v1 is to prevent those authority collapses before implementation begins.

The intrinsic state space is not a bag of retries. It is a typed obstruction space: ContractResidual identifies the exact axis on which a proposed construction failed to close. The corresponding action is a bounded, deterministic exploration over eligible candidate reconstructions. Its conjugate is contract and proof replay. Only that corrective replay may remove the obstruction.

3. Architectural directions considered

3.1 Monolithic practice controller

A single service could inspect residuals, choose a budget, search, validate, and emit a result. This is operationally compact but structurally unsafe: the same component would possess diagnostic, resource, exploration, and promotion authority. A local implementation shortcut could silently convert “worth examining” into “solved.” Rejected.

3.2 Practice-ledger-first orchestration

Exploration could begin in a sealed lane and be classified afterward. This would preserve evidence, but it would allocate compute and create candidates before residual eligibility was established. The gate would become retrospective telemetry rather than an authority boundary. Rejected.

3.3 Workbench-orchestrated exploration

Workbench could expose residuals and directly launch or tune exploration. This would make a display surface part of the execution and policy path, contrary to its operator/auditor posture. Rejected for v1.

3.4 Typed evidence pipeline

Each stage receives a narrow immutable input, emits a deterministic evidence record, and has no authority belonging to a later stage. Eligibility precedes budget; budget precedes exploration; exploration precedes replay; replay precedes any answer; sealing precedes review; review precedes durable promotion. Selected.

This direction makes illegal authority transitions visible in type and module boundaries. Downstream evidence may explain an upstream decision, but it may not rewrite that decision.

4. Capability target

The target milestone is an end-to-end diagnostic and sealed-practice proof over selected refused GSM8K-style/kernel problems.

For each case, CORE can show:

- exact problem frame
- exact bindings
- exact contract assessment
- exact residuals
- whether bounded contemplation is allowed
- what budget would be available
- what candidates were considered
- why each candidate failed or closed
- whether a proof-gated answer was produced
- deterministic replay trace
- wrong_ids == []

The milestone is not “search finds more answers.” It is “every answer or refusal is reconstructible from exact evidence, and no explored candidate can bypass the same contracts that govern the original assessment.” Increased closure is desirable only under the invariant that silent wrong answers remain zero.

5. Mastery mapping

Mastery dimension	Residual-Gated Practice Loop responsibility
Articulation	Present the frame, bindings, claims, residuals, disclosures, candidate dispositions, and trace explanation without collapsing raw evidence into the user-facing answer.
Reasoning	Preserve ContractAssessment, proof gates, entailment, and explicit refusal. Unknown remains unknown and is never coerced to False.
Contemplation	Admit only gated residual classes to bounded, deterministic candidate exploration. Contemplation proposes reconstructions; it does not assert conclusions.
Practice	Run in sealed, replayable lanes. Candidate and outcome artifacts remain provisional; ratified packs, policy, identity, and serving do not mutate without review.
Problem solving	Produce an answer only when a candidate reconstructs the required evidence, replays to contract closure, and satisfies the applicable proof obligations. Otherwise refuse.

These dimensions are views of one evidence flow, not independent subsystems. The same trace must explain both the forward exploration and its corrective replay.

6. End-to-end flow

ProblemFrame
  ↓
ContractAssessment ── runnable ───────────────────────────────→ existing path
  │ refused
  ↓
ContractResidual[]
  ↓
SearchGateDecision ── denied ────────────────────────────────→ refusal + trace
  │ allowed
  ↓
ComputeBudgetPolicy
  ↓
GeometricSearchRun
  ↓ candidates in deterministic order
ContractAssessment replay + applicable proof replay
  ├─ no closed candidate ────────────────────────────────────→ refusal + trace
  └─ exactly proven candidate ───────────────────────────────→ proof-gated result
  ↓
sealed practice trace
  ↓
review-required artifact, if any
  ↓
existing reviewed promotion path only

Workbench ← read-only projection of the sealed trace

The arrow into Workbench is deliberately lateral. Workbench observes the loop; it is not a stage that advances it.

7. Components and boundaries

A. ContractResidual — existing

PR #862 implemented ContractResidual as a deterministic, read-only projection over refused ContractAssessment records.

It preserves existing blocker codes and exact evidence spans. It does not assess contracts, declare truth, decide search eligibility, allocate compute, repair a frame, derive an answer, mutate artifacts, or affect serving.

This ADR consumes that boundary unchanged.

B. SearchGateDecision — future

SearchGateDecision is a read-only eligibility decision over one complete residual context. It answers only whether a future bounded exploration run may be considered.

Its minimum conceptual output is:

decision_id
residual_ids
disposition: allowed | denied
reason_codes
policy_version
input_digest

The exact schema belongs to its implementation ADR/PR. Whatever schema is chosen must be frozen, deterministic, and explicit about denial.

SearchGateDecision:

• does not search;
• does not allocate a budget;
• does not repair bindings, spans, relations, or targets;
• does not mutate a ProblemFrame or ContractAssessment;
• does not make a residual true, false, solved, or runnable;
• does not produce an answer;
• does not mutate teaching, policy, packs, identity, reports, or evals; and
• does not affect serving.

Eligibility is intentionally narrower than residual existence. In particular, an unclassified fallback residual is not implicitly searchable.

C. ComputeBudgetPolicy — future

ComputeBudgetPolicy produces a deterministic budget envelope only for an allowed gate decision. It cannot be invoked as an alternate gate.

A future envelope must use structural units, such as maximum candidate count, maximum expansion depth, maximum deterministic operator applications, or maximum proof replays. Wall-clock duration alone is not a replay-stable budget.

The policy must provide:

• a stable policy/version identity;
• the allowed gate decision digest;
• explicit non-negative limits;
• a canonical budget digest; and
• a fail-closed disposition for unsupported or malformed input.

It must not contain hidden expansion, stochastic allocation, adaptive unbounded loops, environment-dependent limits, or an override that permits a denied residual to proceed.

Budget is a resource ceiling, not evidence, proof, or authority.

D. GeometricSearchRun — future

GeometricSearchRun is the deterministic candidate-exploration envelope. It is functional, bounded, and replayable:

(exact input state, allowed gate, budget, operator set, versions)
  → ordered candidate attempts + run outcome

The word “geometric” denotes exploration in CORE's structured relational and operator space. It does not authorize approximate nearest-neighbor retrieval, cosine ranking, stochastic sampling, opaque model fallback, or unbounded graph growth.

The run must:

• consume immutable input evidence;
• use an explicitly versioned, closed operator set;
• order candidates with stable deterministic tie-breaks;
• charge every expansion and replay against the budget envelope;
• preserve failed candidates and their blocker/proof dispositions;
• perform no pack, policy, identity, Vault, report, eval, or serving mutation;
• avoid mutation of shared input state during exploration; and
• return exhaustion as a typed refused outcome.

Exploration may reconstruct candidate frames or bindings in an isolated value space. It may not promote any candidate. A candidate is merely an object for the existing assessment and proof authorities to judge.

E. Contract and proof replay — existing authorities, future adapter

Every candidate considered potentially closing must be replayed through the same organ-specific ContractAssessment authority that judged the original frame. Applicable proof/verifier obligations must then run over the candidate's exact evidence.

Replay has three permitted dispositions:

contract_refused
contract_closed_but_proof_refused
contract_and_proof_closed

Only contract_and_proof_closed may support answer production. A boolean, score, heuristic rank, absence of a blocker, or exhausted budget is not a proof. If candidates disagree, uniqueness or the relevant organ's existing disagreement rule must close before an answer can be produced; otherwise the result remains refused.

Replay must not patch the original assessment. It produces a new assessment over an explicitly identified candidate reconstruction while retaining the original assessment as immutable evidence.

F. Sealed Practice Integration — future

Sealed practice captures the complete input, decisions, attempts, replays, and outcome of the loop. The seal is tamper evidence and replay identity; it is not proof that a candidate is correct and is not promotion authority.

A v1 trace must be sufficient to reconstruct:

• source/case identity without weakening existing sealed-data rules;
• exact ProblemFrame, binding, and proposal references;
• original ContractAssessment and projected residuals;
• gate decision and policy version;
• budget envelope and consumption;
• ordered candidate attempts and operator provenance;
• per-candidate contract and proof replay dispositions;
• selected proof-gated result or final refusal;
• canonical input, stage, and trace hashes; and
• schema and implementation versions required for deterministic replay.

Candidate failures are evidence and must not be discarded. Hashing must use a canonical representation with stable ordering and no timestamp, random ID, wall-clock result, memory address, or environment-dependent field in the load-bearing payload.

The integration may emit a review-required artifact through an existing proposal/review path. It must not mutate ratified packs, policy, identity, serving, or durable epistemic standing. Practice evidence remains provisional until an existing reviewed or certificate-bearing promotion authority accepts it.

G. Workbench Trace Display — future

Workbench v1 is a read-only projection of the sealed practice trace. It shows:

• frame and exact source spans;
• proposals and bindings;
• original assessment and residuals;
• gate disposition and reasons;
• budget grant and consumption;
• candidate ordering and per-candidate failures/closure;
• contract/proof replay hashes;
• final proof-gated answer or refusal; and
• missing-evidence or replay-divergence states.

Workbench must read a backend-owned persisted projection. It must not infer missing stage evidence in the browser, rerun search to fill gaps, edit an operator, tune a budget, repair a candidate, ratify an artifact, or mutate runtime state in v1. Missing evidence is displayed as missing evidence, not as a synthesized successful stage.

8. Authority boundaries

The following rules are normative:

1. ContractAssessment is the sole runnable/refused authority.
2. ContractResidual is explanation and projection only.
3. SearchGateDecision cannot make a residual true, false, solved, or runnable.
4. ComputeBudgetPolicy cannot authorize exploration unless SearchGate allowed it.
5. GeometricSearchRun cannot promote results or change durable standing.
6. Only contract replay plus the applicable proof replay can close a candidate for answer production.
7. Unknown remains unknown, never False by absence or exhaustion.
8. A denied or failed search preserves refusal unless proof closes a candidate.
9. A sealed trace proves trace integrity, not semantic truth.
10. Review may promote only through existing reviewed/certified paths; source kind (search, practice, or miner) grants no epistemic authority.
11. Workbench is a read surface, not an execution or mutation authority in v1.
12. No serving behavior changes in v1.

Component	May decide	Must not decide
ContractAssessment	runnable/refused for its organ	search budget, promotion, review
ContractResidual	nothing; projection only	truth, eligibility, repair, serving
SearchGateDecision	eligibility for bounded exploration	runnable, solved, budget size, truth
ComputeBudgetPolicy	deterministic resource ceiling	eligibility, closure, promotion
GeometricSearchRun	ordered attempts within the envelope	truth, promotion, serving
Contract/proof replay	candidate closure under existing obligations	durable promotion
Sealed practice	trace integrity and replay identity	truth, ratification
Review path	disposition under existing review authority	retroactive fabrication of evidence
Workbench	display of persisted evidence	execution, repair, operator mutation

9. Determinism, replay, and failure semantics

Given byte-equivalent input evidence, component versions, policy, operator set, and budget, the loop must reproduce:

• the same residual ordering;
• the same gate decision and reasons;
• the same budget envelope;
• the same candidate sequence;
• the same per-candidate assessment and proof dispositions;
• the same selected result or refusal; and
• the same canonical trace hash.

Replay divergence is a failed equivalence check, not ignorable telemetry. Malformed input, unknown policy versions, digest mismatch, unsupported residual kinds, budget overrun, candidate disagreement, missing proof, or trace-seal failure must fail closed with a typed reason.

The loop contains no retry-until-success behavior. Re-execution under identical inputs is replay and must be identical. A new policy, operator set, or budget is a new explicitly versioned run with a new trace identity.

10. Preservation of CORE invariants

This tranche is constrained by the existing invariants:

• Field closure: no component may weaken versor_condition(F) < 1e-6 or introduce repair/normalization outside approved construction/algebra boundaries.
• Exact geometry: no cosine, ANN, HNSW, approximate recall, or stochastic candidate selection.
• Wrong-zero: proof/refusal gates remain load-bearing and evaluated lanes must retain wrong_ids == [].
• Open-world truthfulness: Unknown is not False; search exhaustion is not refutation.
• Reviewed mutation: candidate discovery, practice traces, and miner output remain provisional and cannot mutate durable packs, policy, identity, or epistemic standing without the existing review/certificate authority.
• Serving isolation: the diagnostic/practice tranche is off-serving until a separate ratified serving decision proves the required parity and safety obligations.
• Evidence fidelity: exact source spans and original assessments survive unchanged through the trace.
• Replay: load-bearing hashes use canonical, deterministic payloads.

11. PR ladder

The intended follow-on sequence is:

#864 — ratify this ADR
#865 — implement diagnostic-only SearchGateDecision
#866 — implement deterministic ComputeBudgetPolicy envelope
#867 — implement inert GeometricSearchRun envelope
#868 — wire sealed practice trace capture
#869 — Workbench read-only trace display
#870 — evaluate on selected refused GSM8K/kernel examples

These numbers are provisional. Review may split, combine, reorder, or renumber them if evidence reveals a safer boundary. Each PR remains independently reviewed and must not borrow authority from a later rung.

In particular, #865 must not begin before this ADR is ratified, and no rung may silently include serving integration or durable promotion.

12. Non-goals

This ADR:

• does not implement code;
• does not implement SearchGateDecision;
• does not implement ComputeBudgetPolicy;
• does not implement GeometricSearchRun;
• does not implement or modify Workbench;
• does not touch serving or runtime behavior;
• does not mutate teaching, proposal, report, eval, or sealed-practice artifacts;
• does not broaden state_change.transition;
• does not add a new construction family or derivation organ;
• does not permit stochastic fallback, opaque model calls, approximate recall, or unbounded exploration;
• does not authorize unreviewed learning or promotion;
• does not redefine ContractAssessment or ContractResidual; and
• does not claim a capability gain from documentation alone.

13. Acceptance criteria

This proposal is complete when:

1. The PR is docs-only and changes only this ADR.

2. Existing CORE machinery is distinguished explicitly from future adapters.

3. The complete tranche is defined, not only the next implementation PR.

4. ContractAssessment remains the sole runnable/refused authority.

5. Eligibility, budget, exploration, replay, sealing, review, and display have separate non-overlapping authority boundaries.

6. Failed exploration remains refusal unless contract and proof replay close a candidate.

7. Unknown is never coerced to False.

8. The wrong=0 doctrine and wrong_ids == [] target are explicit.

9. Durable mutation remains reviewed or certificate-bearing through existing paths.

10. Replay inputs, ordering, failure semantics, and trace identity are deterministic.

11. No hidden normalization, stochastic fallback, approximate recall, unreviewed mutation, or serving change is authorized.

12. git diff --check passes and the changed-file surface is exactly:

    docs/adr/ADR-0226-residual-gated-practice-loop-v1.md
    

No code tests are required for this documentation-only proposal beyond the repository bootstrap smoke baseline and diff validation.