sica-fondt/core/docs/plans/M4-budget-governor.md

M4 — Budget governor

1. Component

The stomach's CFO: sets, allocates, and enforces resource budgets. Decides whether a proposed expenditure (digestion, retrieval, exchange) is affordable given what's already been spent (M3) and what's been allocated. Emits price signals to A2 (energy driver) so the per-tool economy reflects real resource scarcity.

2. Status / certainty

DESIGN-FIRST · ABSENT. A2 has a per-tool cost/lockout system but it tracks internal energy, not external resource budgets. The two are complementary: A2 = activation/rest; M4 = tokens/compute spend. Role C2; implementation C1.

3. Language & location

TBD · src/economy/budget/ or similar. Must interop with M3 (ledger reads) and A2 (price signal emission). Likely same language as M3 for tight integration.

4. Does / does-not

• Does: hold a session budget (total resources available); check proposed costs against remaining budget (check_budget); emit price signals to A2 so tool costs reflect real scarcity; implement degradation tiers — when budget is ample, digest fully; when tight, digest shallowly or defer bulk input (M1 priority system).
• Does-not: record costs (M3 does); perform digestion (M2 does); lock tools (A2 does that based on energy, though M4's price signals influence A2's cost landscape); police traffic (D1).

5. Interface contract

• init_budget(session_budget: num, resource_type: ResourceType) -> BudgetState.
• check_budget(proposed_cost: num, resource_type: ResourceType) -> { allowed:bool, remaining:num, tier:DegradationTier }. DegradationTier ∈ { full, shallow, deferred } — signals to M2 how deeply to digest.
• price_signal(tool_id) -> { resource_cost:num, scarcity_factor:num } — emitted to A2; the scarcity factor scales with budget depletion (1.0 = ample, >1.0 = scarce, costs feel heavier).
• remaining() -> { budget:num, spent:num, pct_remaining:num } — reads M3 totals.

6. Dependencies & stubs

• M3 cost ledger — reads totals for remaining budget calculation; stub: returns zero spent.
• A2 energy driver — consumes price signals; stub: print signals.
• M1 ingestion — M1 checks budget before forwarding to M2; stub: always-allow.
• M2 digestion core — receives DegradationTier to adjust digestion depth.

7. Invariants / laws

• L1 (C4): budget enforcement is a soft gate, not a hard wall — when budget is exhausted, digestion degrades (shallower summaries, deferred bulk) rather than halting. The organ never stops entirely; it economizes harder. Mirrors A2-L2 (no unrecoverable state) and A2-L3 (lockout is a breaker, not a sentence).
• L2 (C3): price signals are monotonically scarcer as budget depletes — the scarcity factor never decreases within a session (costs only feel heavier as resources dwindle). Resets only on budget replenishment.
• L3 (C3): degradation tiers are transparent — the tier is carried in the contract so downstream (M2, M5) knows the digestion was shallow and can annotate accordingly.

8. Build steps

1. Define BudgetState and the degradation tiers.
2. Implement check_budget against M3 totals.
3. Implement price_signal emission to A2 (define the scarcity factor curve — invariants-first).
4. Wire M1 → M4 → M2 (budget check before digestion, tier passed to digestion).

9. Tests

Budget arithmetic: spent + remaining = total. Degradation tiers: each tier triggers at the correct budget percentage. Price signals: scarcity factor increases as budget depletes. Soft gate: zero budget produces deferred tier, not an error.

10. Open items

• Session budget source — who sets it? Hardcoded? Config? Dynamically adjusted? (C1).
• Degradation tier thresholds (C1) — at what % remaining does full → shallow → deferred?
• The scarcity factor curve shape (C1) — linear? exponential? Needs invariants-first fitting.
• Whether budget replenishment is possible mid-session (ties to A2 restoration model / A8 ETR).