Governance Library

---

Version: v1.0

name: Specification — Governance Library Architecture (Option D)

description: Formal spec for TMMRuntime.authorize_trade() — single authorization entry point for all trade-executing scripts; Option D architecture; Phase 2 design; α.13 2026-04-16

type: project

---

SPEC — GOVERNANCE LIBRARY ARCHITECTURE (OPTION D)

Phase 2: Design (no code changes until α.13 approves)

Produced: 2026-04-16 | Authorized: α.13 | Designed: κ (C.L.O.D.)

Why: 43 of 45 trade-executing scripts bypass governance entirely. The root cause is architectural: each script was written independently with no shared authorization layer. The fix is not patching each script — it is building the layer that all scripts must pass through.

How to apply: This spec defines the single function every trade-executing script must call. Phase 3 wires all callers to this function. Phase 4 re-enables services only after all wires are confirmed.

---

INVARIANTS (must hold after Phase 3 completes)

| ID | Invariant |

|----|-----------|

| INV-01 | TMMRuntime.authorize_trade() is the ONLY path through which any on-chain transaction or exchange order may be executed |

| INV-02 | authorize_trade() calls TMMRuntime.evaluate_strike() internally — callers do not invoke evaluate_strike() directly |

| INV-03 | authorize_trade() calls AgencyWalls.check_all() internally — callers do not invoke check_all() directly |

| INV-04 | All authorization decisions are written to yield_log.md before the trade executes |

| INV-05 | A trade that fails authorize_trade() for any reason — TMM RED, AgencyWalls violation, NULL verdict, GAS_EXCEEDS_VOLUME, missing parameters — is BLOCKED and logged; the calling script receives (False, reason_str) and must abort |

| INV-06 | authorize_trade() is idempotent: calling it with identical parameters twice within the same second returns the same result without double-counting AgencyWalls exposure |

| INV-07 | The trade_intent dict must contain all fields defined in the schema below; missing fields return (False, "INCOMPLETE_INTENT") without calling TMM |

| INV-08 | No script may pass fabricated TMM scores to authorize_trade(); the function computes coherence internally — no external score injection |

---

PRODUCTION PATH

• File: /home/nous/tmm_runtime.py
• Service: No direct service; called as library by all trade-executing scripts
• Python environment: /home/nous/aether_env/bin/python3
• State file (AgencyWalls): /home/nous/.agency_walls_state.json
• Audit log: /home/nous/yield_log.md

---

FUNCTION SIGNATURE

@staticmethod
def authorize_trade(trade_intent: dict) -> tuple[bool, str]:
    """
    Single authorization entry point for ALL trade-executing scripts.

    Runs the full governance pipeline:
      1. Validates trade_intent schema
      2. Calls TMMRuntime.evaluate_strike() with portfolio state from intent
      3. Calls AgencyWalls.check_all() with v_total and trade amount
      4. Writes authorization decision to yield_log.md
      5. Returns (approved: bool, reason: str)

    The trade_intent dict MUST contain:
      v_total        (float) — total portfolio value in USD
      v_resonant     (float) — resonant component value in USD
      entropy        (float) — current entropy estimate [0.0, 1.0]
      strike_amount  (float) — trade amount in USD
      est_gas        (float) — estimated gas cost in USD
      is_resonant    (bool)  — whether trade involves resonant assets
      caller         (str)   — identifying string of calling script (for log)
      action         (str)   — 'DEPOSIT' | 'SWAP' | 'BUY' | 'SELL' | 'WITHDRAW'

    Returns:
      (True,  "AUTHORIZED: <verdict> coherence=<C:.5f>")    — trade may proceed
      (False, "REJECTED_TMM: <verdict> coherence=<C:.5f>")  — TMM gate failed
      (False, "REJECTED_WALLS: <wall_name>")                 — Agency Wall triggered
      (False, "REJECTED_GAS: GAS_EXCEEDS_VOLUME")            — gas > v_total
      (False, "REJECTED_NULL: glassy freeze")                — NULL verdict
      (False, "INCOMPLETE_INTENT: missing field <name>")     — schema error
      (False, "WALLS_ERROR: FAIL_SAFE triggered")            — state file corrupt/missing
    """

---

REQUIRED FIELDS IN trade_intent

| Field | Type | Validation | Source in calling script |

|-------|------|-----------|-------------------------|

| v_total | float | > 0 | On-chain balance query (get_portfolio_state or equivalent) |

| v_resonant | float | ≥ 0 | On-chain balance query |

| entropy | float | [0.0, 1.0] | get_entropy_from_log() or live oracle |

| strike_amount | float | > 0 | Trade size being authorized |

| est_gas | float | ≥ 0 | Gas estimate from node |

| is_resonant | bool | exact type | Whether trade is in resonant asset |

| caller | str | non-empty | Script name e.g. "aether-compounder.py" |

| action | str | one of DEPOSIT/SWAP/BUY/SELL/WITHDRAW | Trade action type |

---

INTERNAL PIPELINE

authorize_trade(intent)
  │
  ├─ Step 1: Schema validation
  │    Missing field → return (False, "INCOMPLETE_INTENT: missing <field>")
  │
  ├─ Step 2: TMMRuntime.evaluate_strike(
  │            v_total, v_resonant, entropy,
  │            strike_amount, est_gas, is_resonant
  │          )
  │    GAS_EXCEEDS_VOLUME → log + return (False, "REJECTED_GAS: GAS_EXCEEDS_VOLUME")
  │    NULL               → log + return (False, "REJECTED_NULL: glassy freeze")
  │    RED                → log + return (False, "REJECTED_TMM: RED coherence=<C>")
  │    AMBER              → approved if coherence >= Ω; else → (False, "REJECTED_TMM: AMBER")
  │    GREEN              → continue to Step 3
  │
  ├─ Step 3: AgencyWalls.update_treasury_snapshots(v_total)
  │          AgencyWalls.check_all(v_total, strike_amount)
  │    walls_ok=False → log + return (False, "REJECTED_WALLS: <wall_name>")
  │    state error    → log + return (False, "WALLS_ERROR: FAIL_SAFE triggered")
  │
  ├─ Step 4: Write to yield_log.md
  │    Format: [ISO8601] | AUTHORIZE | caller=<> action=<> amount=<> verdict=<> C=<> approved=<>
  │
  └─ Step 5: return (True, "AUTHORIZED: <verdict> coherence=<C:.5f>")

---

yield_log.md AUDIT TRAIL FORMAT

Every authorize_trade() call — whether approved or rejected — writes one line to yield_log.md:

[2026-04-16T14:23:01Z] | AUTHORIZE | caller=aether-compounder.py | action=DEPOSIT | amount=45.20 | verdict=GREEN | coherence=0.97512 | walls=PASS | approved=True
[2026-04-16T14:23:05Z] | AUTHORIZE | caller=aether-compounder.py | action=DEPOSIT | amount=45.20 | verdict=RED | coherence=0.94110 | walls=SKIP | approved=False | reason=REJECTED_TMM: RED coherence=0.94110
[2026-04-16T14:23:08Z] | AUTHORIZE | caller=aether-simons.py | action=BUY | amount=10.00 | verdict=GREEN | coherence=0.97601 | walls=REJECTED: DAILY_HALT | approved=False | reason=REJECTED_WALLS: DAILY_HALT

Fields: timestamp (ISO8601 UTC), caller, action, amount, TMM verdict, coherence score, walls result, approved, optional reason on rejection.

---

CALLER PATTERN (what every trade-executing script looks like after Phase 3)

# BEFORE (ungoverned)
def supply_to_morpho(amount_raw):
    # ... build tx ...
    tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction)

# AFTER (governed)
def supply_to_morpho(amount_raw):
    v_total, v_resonant, entropy = get_portfolio_state()
    est_gas = estimate_gas_usd()  # real estimate

    approved, reason = TMMRuntime.authorize_trade({
        "v_total":       v_total,
        "v_resonant":    v_resonant,
        "entropy":       entropy,
        "strike_amount": amount_raw / 10**6,
        "est_gas":       est_gas,
        "is_resonant":   False,
        "caller":        "aether-compounder.py",
        "action":        "DEPOSIT",
    })

    if not approved:
        log(f"BLOCKED: {reason}")
        return None

    # ... build tx ...
    tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction)

---

RELATIONSHIP TO EXISTING CODE

| Existing function | Status after Phase 3 | Notes |

|-------------------|---------------------|-------|

| TMMRuntime.evaluate_strike() | Remains; called internally by authorize_trade() | Callers stop calling it directly |

| AgencyWalls.check_all() | Remains; called internally by authorize_trade() | Callers stop calling it directly |

| AgencyWalls.update_treasury_snapshots() | Remains; called internally by authorize_trade() | Callers stop calling it directly |

| _log_to_yield() in AgencyWalls | Merged into single yield_log write in authorize_trade() | Consolidates duplicate log calls |

| pure_compounder.py supply_to_morpho() | Updated to use authorize_trade() | Current FIX-001+FIX-002 replaced by single call |

| aether-compounder.py supply_to_morpho() | Updated to use authorize_trade() | Primary Phase 3 target |

---

PENDING FIX INTEGRATION

All pending TMM fixes are absorbed into authorize_trade() pipeline. The fixes do NOT change the public function signature — they improve the internal governance quality.

| Fix | Gap | Where it lands in authorize_trade() |

|-----|-----|-------------------------------------|

| FIX-003 (GAP-02) | p_v_total underflow | Step 2: evaluate_strike() — GAS_EXCEEDS_VOLUME path |

| FIX-004 (GAP-03) | Entropy hardcoded | Step 1: caller supplies real entropy; entropy oracle built separately |

| FIX-005 (GAP-04) | ETH price hardcoded | Intent field: caller must supply real v_total from live price feed |

| FIX-006 (GAP-08) | yield_log writes | Step 4: authorize_trade() centrally writes all decisions |

| FIX-007 (GAP-09) | Dual-TMM not enforced | New: authorize_trade() for Wealthsimple trades requires two separate intent evaluations (AION-context + ASTRA-context) before returning approved=True |

| FIX-008 (GAP-05) | NULL verdict unhandled | Step 2: NULL → REJECTED_NULL with explicit log |

| FIX-009 (GAP-07) | Sovereignty target | Post-authorize_trade() hook: log cumulative_yield toward $27,042.50 target |

---

OPEN DESIGN QUESTIONS (for α.13 review before Phase 3)

1. Dual-TMM for Wealthsimple trades: Aether/simons_actuator.py currently accepts aion_tmm_score and astra_tmm_score as parameters (Sisters compute externally). Under Option D, should authorize_trade() accept a dual_tmm_mode=True flag that requires two sequential calls (one with AION portfolio state, one with ASTRA portfolio state), both returning approved=True? Or should the dual-TMM check remain at the actuator layer?

1. Entropy source: get_entropy_from_log() currently returns 0.50 hardcoded (GAP-03). What is the live entropy oracle? Does it read from a log file written by MNEMOS/the Sisters, or is there an on-chain data source?

1. ETH price feed: GAP-04 — v_total computation in aether-compounder.py uses eth_bal * 2500 (hardcoded). Should authorize_trade() receive v_total pre-computed by the caller (shifting responsibility to callers) or should it fetch a live price internally?

1. Idempotency window: INV-06 requires that identical calls within the same second don't double-count AgencyWalls exposure. The AgencyWalls state file updates entry_snapshot on every check_all() call. Should authorize_trade() add a call timestamp check, or is this handled by AgencyWalls existing logic?

---

VERIFICATION CRITERIA

Phase 3 is complete when ALL of the following pass:

• [ ] grep -rn "send_raw_transaction\|send_transaction\|execute_pairs_trade\|execute_liquidation" /home/nous/*.py — every match has authorize_trade() call in same function scope (or is in archive/)
• [ ] pytest tests/test_tmm_runtime.py tests/test_agency_walls.py -v — all tests pass
• [ ] New test: tests/test_authorize_trade.py — covers all 8 return paths (AUTHORIZED, REJECTED_TMM, REJECTED_WALLS, REJECTED_GAS, REJECTED_NULL, INCOMPLETE_INTENT, WALLS_ERROR, dual-TMM mode)
• [ ] yield_log.md receives one entry per authorize_trade() call in integration test
• [ ] aether-compounder.py integration test: mock portfolio state + call supply_to_morpho() + verify authorize_trade() called + verify log entry written

---

FAILURE MODES

| Failure | Behavior |

|---------|---------|

| trade_intent missing required field | (False, "INCOMPLETE_INTENT: missing <field>") — no TMM or walls called |

| evaluate_strike() raises exception | (False, "TMM_ERROR: <exception>") — FAIL SAFE, trade blocked |

| AgencyWalls state file corrupt | (False, "WALLS_ERROR: FAIL_SAFE triggered") — inherited from AgencyWalls._load_state() |

| yield_log.md write fails | Log failure is swallowed (best-effort); authorization decision is NOT reversed. Warning printed to stdout. |

| Caller ignores return value | Cannot be prevented by library. Enforced by code review + weekly grep audit. |

---

PHASE 3 EXECUTION ORDER

1. Add authorize_trade() to tmm_runtime.py (FIX-010 in fix queue)
2. Write tests/test_authorize_trade.py (all 8 paths + integration test)
3. Confirm all tests pass
4. Apply FIX-003 (gas underflow) — already designed + 22 tests written
5. Update aether-compounder.py — replace FIX-001+FIX-002 pattern with authorize_trade()
6. Update aether-simons.py — add authorize_trade() call replacing if False: stub
7. Update pure_compounder.py — replace FIX-001+FIX-002 with authorize_trade() (or archive)
8. Archive Tier 3 historical scripts to /home/nous/archive/historical_strikes/
9. Govern or archive Tier 2 recent scripts (sisters_compounder.py is highest priority)
10. Run full governance audit: grep verify + all tests pass
11. Report to α.13 for Phase 4 restart authorization

---

κ ⊜ Σ.◇ Phase 2 design sealed. Awaiting α.13 review of open design questions + Phase 3 authorization.

Φζ.⊤.

---

Jeremy Zlabis

Chronogeometer · Visionary · Disruptor · Chief

42 Sisters AI · East York, Toronto

🍁 Φ 0.042