aios/docs/superpowers/specs/2026-08-18-model-governance-runtime.md

AIOS Model Governance Runtime

Status and purpose

This component turns the previously PARTIAL Model Governance interface map into an enforceable runtime policy for the already verified Hermes/OpenClaw Online Agent path.

It is intentionally a single SQLite library, not a new network service. The existing external Agent executor calls the library immediately before launching a model-backed runtime and settles the same reservation immediately after the result.

The authoritative execution chain remains:

Online Task scope / trace
→ dedicated worker claim + heartbeat
→ external Agent executor
→ ModelGovernanceStore.route()
→ root-owned runtime profile binds provider/model/version
→ Hermes / OpenClaw process
→ ModelGovernanceStore.record_success() / record_failure()
→ durable Online Agent checkpoint/result

P0 scope/trace/credential, P1 checkpoint/retry, P2 fleet scheduling and the existing external Agent credential boundary remain authoritative.

Ten Model Governance contracts

MODEL_PROVIDER_REGISTRY

model_governance_providers stores provider identity, failure domain, circuit policy and an opaque credential reference. Raw credentials are rejected.

Allowed reference prefixes:

• systemd-credential:
• runtime-profile:
• credential-broker:

MODEL_SELECTION_POLICY

model_governance_scope_policies constrains eligible models/providers/capabilities. Routing is deterministic: explicit preferred models, then configured priority, then stable provider/model IDs.

MODEL_VERSION_PINNING

A registry row always includes a model version. A scope can additionally pin a model ID + exact version. Every route decision persists both model ID and version plus model/policy revisions.

MODEL_BUDGET_ACCOUNTING

A route first reserves estimated input/output tokens and estimated cost inside BEGIN IMMEDIATE. Settled usage and outstanding reservations both count against the daily scope budget, preventing two concurrent requests from oversubscribing the same budget.

Runtime-reported usage is preferred. When telemetry is absent, the reserved upper bound is charged rather than silently under-counting.

OpenClaw's verified result shape is supported directly:

meta.agentMeta.usage.input
meta.agentMeta.usage.output
meta.agentMeta.costUsd

Hermes currently has no structured usage in the verified output, so it uses conservative reservation settlement.

MODEL_FALLBACK_POLICY

Provider failures are durable. Repeated failures open a circuit for the configured cooldown. A fallback request excludes the failed provider and increments fallback_index; the scope policy bounds the number of fallback attempts.

MODEL_SCOPE_ISOLATION

The signed agent_runtime execution envelope now carries authoritative Task scope + trace identity.

The projection layer always overwrites runtime_input.scope and runtime_input.trace_id from the Online Task, even if an execution request attempts to supply different values.

Tenant/project lookup may fall back only to the same tenant's policy. It never falls back to a system or legacy policy. system and legacy require their own explicit policies, avoiding fake tenant identities.

MODEL_CREDENTIAL_BOUNDARY

Model governance stores credential references only. The root-owned external-runtime profile still owns the actual provider credential projection. Task payloads cannot select executable, argv, environment, provider credential, or credential path.

The external child process remains unable to reach the AIOS control plane.

MODEL_TRACE_AUDIT

Every route, failure, provider/model/policy update and settlement appends to a SHA-256 hash-chained audit table with task ID, trace ID and scope key. verify_audit_chain() detects tampering.

MODEL_EVALUATION_GATE

A model cannot enter the registry unless its state is APPROVED and it has a 64-hex evaluation evidence digest.

The staging bootstrap uses the already verified Hermes/OpenClaw E2E external-result SHA256 values as evaluation evidence, rather than a configuration-file hash.

MODEL_ROUTING_RESILIENCE

Route request IDs are idempotent and bound to a canonical request hash. Conflicting replay is rejected. Provider health, reservations, usage settlement and policy/provider/model updates use transaction/CAS semantics.

Runtime profile contract

A root-owned Hermes/OpenClaw profile may declare:

{
  "model_governance": {
    "required": true,
    "provider_ids": ["provider-a"],
    "model_capabilities": ["text"],
    "max_output_tokens": 512
  }
}

When required=true:

• provider_ids must be non-empty;
• max_output_tokens must be positive;
• argv/environment must contain at least one governance-controlled marker: {provider_id}, {model_id}, or {model_version};
• AIOS_MODEL_GOVERNANCE_ENABLED must be enabled;
• a matching scope policy/model/provider must exist;
• budget reservation must succeed before the child process is launched.

The task cannot provide these markers or their values.

SQLite authority

Default database:

/var/lib/aios-model-governance/state.sqlite3

The executor process already owns the only runtime mutation path. The directory is created by tmpfiles and is the only new writable path added to that executor.

No direct Task/Job/Git database writes are introduced.

Bootstrap/reconciliation

aios_model_governance_admin.py applies a root-owned JSON bootstrap idempotently. It compares desired state to current rows and uses the current revision as the CAS input only when a change is actually required.

The repository staging bootstrap is not a Production policy. It exists only to reproduce and govern the already verified non-production Hermes/OpenClaw runtimes.

Cost caveat

The current verified OneAPI-backed runtime evidence reports zero authoritative provider cost for OpenClaw and no structured cost for Hermes. The staging bootstrap therefore does not invent pricing and sets cost rates/budget to zero/unbounded.

Token budgets remain enforced. Real monetary budget enforcement becomes effective as soon as authoritative per-model pricing is entered into the root-owned registry.

OpenClaw JIT/WASM compatibility

The previous live acceptance proved that OpenClaw Node/WASM requires MemoryDenyWriteExecute=no. Model Governance must preserve that already-evidenced runtime exception; it must not further weaken NoNewPrivileges, ProtectSystem=strict, ProtectHome, loopback deny, credential isolation or repository isolation.

Failure/recovery invariants

• Budget denial occurs before provider execution.
• Missing scope policy fails closed.
• Missing/disabled governance fails closed when a profile requires it.
• Actual usage cannot exceed the reservation.
• Provider failure releases that reservation into FAILED state before fallback.
• Settlement is idempotent.
• Route replay is idempotent only for the exact canonical request.
• Audit corruption is detectable.
• Online Agent checkpoint/result retry remains unchanged and remains the outer recovery authority.

Verification

Required unit/integration coverage includes:

• registry/evaluation/CAS;
• scope isolation and no system→tenant fallback;
• model/version pinning;
• atomic budget reservation;
• settlement/replay;
• missing telemetry conservative settlement;
• provider circuit/fallback;
• trace/audit tamper detection;
• authoritative scope/trace projection;
• task runtime-input scope override attack;
• root-owned provider/model binding;
• OpenClaw nested usage extraction;
• real Hermes/OpenClaw staging live tasks with Model Governance evidence.

The governed implementation is not complete without the unified all-modified-files bundle for the candidate delta and the cumulative lineage bundle.