7e4ba10c7a
Ratifies ADR-0227 and authorizes exactly one next implementation PR: diagnostic-only ComputeBudgetDecision. No ComputeBudgetDecision implementation, GeometricSearchRun, search execution, candidate generation, repair, Workbench, runtime/serving behavior, teaching/proposal/report/eval mutation, answer production, or unreviewed artifact mutation is authorized.
249 lines
10 KiB
Markdown
249 lines
10 KiB
Markdown
# ADR-0227: ComputeBudgetPolicy Envelope
|
|
|
|
**Status:** Accepted
|
|
|
|
**Date:** 2026-06-22
|
|
|
|
**Scope:** Kernel diagnostics, bounded contemplation, sealed practice
|
|
|
|
**Depends on:** ADR-0226 and PR #865
|
|
|
|
## Ratification note
|
|
|
|
Accepted for staged implementation.
|
|
|
|
This ADR authorizes exactly one next implementation PR: a diagnostic-only `ComputeBudgetDecision` read adapter over `SearchGateDecision`.
|
|
|
|
This authorization does not include `GeometricSearchRun`, search execution, candidate generation, repair, Workbench implementation, serving/runtime behavior, teaching/proposal/report/eval mutation, answer production, or any unreviewed artifact mutation. Those remain separately gated by future PRs.
|
|
|
|
---
|
|
|
|
## 1. Summary
|
|
|
|
This ADR defines the diagnostic `ComputeBudgetPolicy` and its corresponding output record `ComputeBudgetDecision`. This is the next envelope in the Residual-Gated Practice Loop v1:
|
|
|
|
```text
|
|
ContractAssessment
|
|
→ ContractResidual
|
|
→ SearchGateDecision
|
|
→ ComputeBudgetDecision
|
|
```
|
|
|
|
`ComputeBudgetPolicy` specifies a deterministic, diagnostic-only resource ceiling for future bounded contemplation and candidate exploration. It does not execute search, rank candidates, repair frames, or mutate any assets.
|
|
|
|
---
|
|
|
|
## 2. Why this exists
|
|
|
|
Once a residual context has been assessed by the `SearchGateDecision` and gated as `eligible`, the cognitive engine requires a deterministic resource boundary before any exploration or candidate reconstruction run can be initialized.
|
|
|
|
Without a distinct, deterministic budget envelope, downstream exploration could easily drift into:
|
|
* **Unbounded retries:** looping indefinitely without a terminal condition;
|
|
* **Stochastic exploration:** consuming varying amounts of compute based on transient execution time or non-replayable resource state;
|
|
* **Implicit repair / compute-as-truth:** using search budget as an epistemological validator (i.e. "if search completes, the candidate must be correct") rather than requiring independent contract and proof replay.
|
|
|
|
A structured, non-authoritative budget envelope protects the engine from executing unbounded search while ensuring that resource limits are themselves fully replay-stable and inspectable.
|
|
|
|
---
|
|
|
|
## 3. Non-Authority Doctrine
|
|
|
|
To prevent authority collapse and maintain the core safety invariants of the cognitive engine, the budget policy operates under a strict non-authority boundary:
|
|
|
|
> [!IMPORTANT]
|
|
> **Core Non-Authority Rules:**
|
|
> * `ComputeBudgetDecision` cannot authorize serving.
|
|
> * `ComputeBudgetDecision` cannot authorize mutation.
|
|
> * `ComputeBudgetDecision` cannot authorize answer production.
|
|
> * `ComputeBudgetDecision` cannot make a candidate true, valid, or closed.
|
|
> * `ComputeBudgetDecision` cannot repair a `ProblemFrame`.
|
|
> * `ComputeBudgetDecision` cannot call or execute search.
|
|
> * `ComputeBudgetDecision` cannot call external models.
|
|
> * `ComputeBudgetDecision` cannot override `SearchGateDecision`.
|
|
|
|
If the associated `SearchGateDecision` status is anything other than `ELIGIBLE` (e.g. `INELIGIBLE`, `BLOCKED`, `UNASSESSABLE`), the compute budget **must** be zero/blocked.
|
|
|
|
---
|
|
|
|
## 4. Inputs
|
|
|
|
A `ComputeBudgetDecision` is mapped directly from a single `SearchGateDecision`.
|
|
|
|
### Context Grouping
|
|
The default grouping constraint is **one-to-one**: exactly one `ComputeBudgetDecision` is produced for each `SearchGateDecision`. Budgets are never aggregated across independent gate decisions or distinct candidate organs.
|
|
|
|
### Required Input Properties
|
|
The budget policy requires the following fields from the input `SearchGateDecision`:
|
|
* `decision_id`: str (deterministic gate identifier)
|
|
* `policy_version`: str (gate policy version)
|
|
* `input_digest`: str (hash of the underlying residual context)
|
|
* `status`: SearchGateStatus (must be `ELIGIBLE` to grant non-zero budget)
|
|
* `reason_code`: str (e.g. `eligible_missing_role`, `eligible_missing_relation`)
|
|
* `residual_ids`: tuple[str, ...] (the exact projected residuals)
|
|
* `candidate_organ`: str | None (the diagnostic organ context)
|
|
* `evidence_spans`: tuple[SourceSpan, ...] (ordered provenance spans)
|
|
|
|
---
|
|
|
|
## 5. Output Shape
|
|
|
|
We define the conceptual schema for `ComputeBudgetDecision` with the following fields:
|
|
|
|
```python
|
|
@dataclass(frozen=True, slots=True)
|
|
class ComputeBudgetDecision:
|
|
budget_id: str
|
|
policy_version: str
|
|
gate_decision_id: str
|
|
gate_policy_version: str
|
|
gate_input_digest: str
|
|
status: ComputeBudgetStatus
|
|
reason_code: str
|
|
max_candidates: int
|
|
max_depth: int
|
|
max_steps: int
|
|
max_wallclock_ms: int | None
|
|
max_parallelism: int
|
|
evidence_spans: tuple[SourceSpan, ...]
|
|
explanation: str
|
|
```
|
|
*(Note: This is documentation only. No Python classes are implemented in this PR.)*
|
|
|
|
### ComputeBudgetStatus
|
|
We define the closed enum `ComputeBudgetStatus` with the following allowed values:
|
|
* `BUDGET_ALLOWED`: Bounded resource limits are granted for the eligible gate decision.
|
|
* `BUDGET_BLOCKED`: The gate decision is ineligible or blocked; budget limits are explicitly set to zero.
|
|
* `BUDGET_ZERO`: Budget is successfully assessed but explicitly configured as zero.
|
|
* `BUDGET_UNASSESSABLE`: The input gate decision contains malformed or unassessable structures.
|
|
|
|
### Wall-Clock Time Separation
|
|
The field `max_wallclock_ms` is strictly **diagnostic metadata**. It is excluded from the deterministic execution authority to prevent environment, hardware, or load-dependent divergence during replay. Budgets are enforced primarily using deterministic structural limits: `max_candidates`, `max_depth`, and `max_steps`.
|
|
|
|
---
|
|
|
|
## 6. Deterministic Policy Version
|
|
|
|
To ensure version consistency and avoid un-tracked changes to the budget tables:
|
|
|
|
```python
|
|
COMPUTE_BUDGET_POLICY_VERSION = "compute_budget.v1"
|
|
```
|
|
|
|
The implementation must use this exact string to identify the v1 policy.
|
|
|
|
---
|
|
|
|
## 7. Deterministic Budget ID
|
|
|
|
The `budget_id` is a full lowercase SHA-256 hash over a canonical JSON payload representing the deterministic fields of the decision.
|
|
|
|
### Payload Fields
|
|
The hash input must include exactly:
|
|
1. `policy_version`
|
|
2. `gate_decision_id`
|
|
3. `gate_policy_version`
|
|
4. `gate_input_digest`
|
|
5. `status` (as string value)
|
|
6. `reason_code`
|
|
7. `max_candidates`
|
|
8. `max_depth`
|
|
9. `max_steps`
|
|
10. `max_parallelism`
|
|
11. `evidence_spans`: An ordered list of spans containing:
|
|
* `text`
|
|
* `start`
|
|
* `end`
|
|
* `sentence_index`
|
|
|
|
### Excluded Fields
|
|
To guarantee that the `budget_id` remains completely replay-stable across different processes, machines, and execution runs, the following fields **must not** be included in the hashed payload:
|
|
* `explanation` (localized or formatting-sensitive text)
|
|
* `max_wallclock_ms` (hardware-dependent value)
|
|
* Current system time, timestamps, or clocks
|
|
* Random numbers or UUIDs
|
|
* Environment variables, hostname, OS details, or CI run metadata
|
|
* File system paths
|
|
|
|
---
|
|
|
|
## 8. Budget Policy Table (v1)
|
|
|
|
We define a closed, static budget allocation table for version `compute_budget.v1`. Budgets must remain small and deterministic.
|
|
|
|
| SearchGateStatus | SearchGate reason_code | Budget Status | max_candidates | max_depth | max_steps | max_parallelism |
|
|
|---|---|---|---|---|---|---|
|
|
| **Any non-ELIGIBLE status**<br>(`BLOCKED`, `INELIGIBLE`, `UNASSESSABLE`) | *Any* | `BUDGET_BLOCKED` | 0 | 0 | 0 | 0 |
|
|
| `ELIGIBLE` | `eligible_missing_role` | `BUDGET_ALLOWED` | 5 | 2 | 10 | 1 |
|
|
| `ELIGIBLE` | `eligible_missing_relation` | `BUDGET_ALLOWED` | 5 | 2 | 10 | 1 |
|
|
| `ELIGIBLE` | `eligible_missing_proposal` | `BUDGET_ALLOWED` | 3 | 1 | 5 | 1 |
|
|
| `ELIGIBLE` | `eligible_target_unbound` | `BUDGET_ALLOWED` | 5 | 2 | 10 | 1 |
|
|
| `ELIGIBLE` | *Any unknown code* | `BUDGET_UNASSESSABLE`| 0 | 0 | 0 | 0 |
|
|
|
|
### Constraints:
|
|
* **No adaptive scaling:** The budget cannot self-increase, adapt dynamically to progress, or scale based on previous failures.
|
|
* **No "try until solved":** The limits are hard ceilings; exhaustion must immediately terminate the run as a refusal.
|
|
* **No concurrency bounds expansion:** `max_parallelism` is pinned to `1` in v1 to ensure deterministic candidate traversal.
|
|
|
|
---
|
|
|
|
## 9. Interaction with Future GeometricSearchRun
|
|
|
|
A future `GeometricSearchRun` component must consume `ComputeBudgetDecision` as a load-bearing constraint. The run must refuse to initialize or execute if:
|
|
* The budget status is `BUDGET_BLOCKED`, `BUDGET_ZERO`, or `BUDGET_UNASSESSABLE`.
|
|
* The budget limits are invalid or exhausted (`max_candidates == 0` or `max_steps == 0`).
|
|
* The `budget_id` does not match the canonical hash reconstructed from the inputs during replay.
|
|
* The `policy_version` is unsupported by the runner.
|
|
|
|
This ADR does not implement the `GeometricSearchRun`.
|
|
|
|
---
|
|
|
|
## 10. Practice and Workbench Implications
|
|
|
|
### Practice Loop
|
|
The Practice Loop may persist the `ComputeBudgetDecision` within the sealed trace for diagnostic and auditing purposes. The loop must treat the budget as a resource ceiling only; recording a budget decision does not change the epistemic status of any candidate or mutate any ratified packs.
|
|
|
|
### Workbench
|
|
Workbench may expose these budget decisions in a read-only viewer, allowing operators to audit:
|
|
* Why a particular budget was allowed or blocked;
|
|
* The specific limits applied (`max_candidates`, `max_depth`, `max_steps`).
|
|
|
|
There are no interactive tuning controls, edit forms, or operator override actions permitted in Workbench for this PR.
|
|
|
|
---
|
|
|
|
## 11. Non-Goals
|
|
|
|
This ADR explicitly does not cover:
|
|
* Implementing python code for `ComputeBudgetPolicy` or `ComputeBudgetDecision`.
|
|
* Implementing the `GeometricSearchRun` candidate search.
|
|
* Mutating or displaying in Workbench.
|
|
* Serving path alterations or runtime dispatch.
|
|
* Adding new contract labels or modifying the existing assessment logic.
|
|
* Mutating teaching proposals, training packs, or reliability-ledger counts.
|
|
|
|
---
|
|
|
|
## 12. Follow-on PRs
|
|
|
|
The proposed sequence of PRs after this ADR is:
|
|
|
|
```text
|
|
#867 — ratify ComputeBudgetPolicy envelope
|
|
#868 — implement diagnostic-only ComputeBudgetDecision
|
|
#869 — define inert GeometricSearchRun envelope
|
|
```
|
|
|
|
These numbers are provisional and subject to adjustment during code reviews.
|
|
|
|
---
|
|
|
|
## 13. Acceptance Criteria
|
|
|
|
This proposal is complete when:
|
|
1. The PR is docs-only and contains exactly this ADR file.
|
|
2. The role of the budget decision as a non-authoritative ceiling is stated explicitly.
|
|
3. The deterministic hashing scheme for `budget_id` is defined and excludes wall-clock/environment parameters.
|
|
4. The closed policy table for `compute_budget.v1` is defined.
|
|
5. Fail-closed semantics for invalid/denied gates are enforced.
|
|
6. `git diff --check` passes cleanly with no trailing whitespace or check errors.
|