Technical Whitepaper

1. Introduction: Execution vs Advisory Systems

1.1 The Advisory Gap

The cloud infrastructure stack has reached a level of observational sophistication without a corresponding level of governance authority. Organizations operating at scale have access to detailed real-time telemetry — per-region carbon intensity from multiple providers, grid demand forecasts, water stress indices for data center basins, cost optimization signals, and latency profiles. They have dashboards, alerts, and weekly sustainability reports. What they do not have is a system that acts on those signals at the moment of execution.

This gap — between environmental awareness and environmental enforcement — defines the current state of the market. Every tool in the ecosystem operates in an advisory posture. Observability platforms (Datadog, Grafana, New Relic) record what happened after workloads ran. Schedulers (AWS EventBridge, GCP Cloud Scheduler, Kubernetes CronJobs) execute on time or on trigger, blind to environmental state. Carbon accounting tools (Climatiq, Google Carbon Footprint, Microsoft Sustainability Manager) produce post-hoc emissions inventories. None of these systems can authorize or deny execution.

Advisory systems suggest. CO₂Router authorizes. Without hard enforcement, environmental computing is toothless.

1.2 Why Advisory Is Not Sufficient

Three failure modes characterize advisory governance:

• Post-hoc measurement: Carbon is counted after it is emitted. A workload that ran in us-east-1 at 420 gCO₂/kWh when eu-west-1 was at 180 gCO₂/kWh is not recoverable. The carbon is already in the atmosphere.
• No enforcement binding: A recommendation to reroute has zero enforcement weight. The CI/CD pipeline, the Kubernetes scheduler, and the cloud provider API do not know or respect environmental thresholds unless something authoritative communicates them at decision time.
• No proof of governance: Saying a governance policy was applied is not the same as proving it. Without cryptographic provenance, an audit cannot distinguish between a workload that was genuinely authorized under policy and one that ran with no governance applied.

1.3 The CO₂Router Category

CO₂Router defines a new category: deterministic pre-execution governance. The category is characterized by three properties:

• Execution authority: the system can authorize, reroute, delay, throttle, or deny a workload before it runs.
• Determinism: given the same inputs, the system produces the same output. Decisions are reproducible and replayable.
• Cryptographic provenance: every decision is sealed with a tamper-evident proof record that can be inspected and verified after the fact.

2. Deterministic Decision Model

2.1 The Authorization Request

A workload authorization begins with a pre-execution request submitted to CO₂Router before any compute resources are provisioned. The request carries the workload identity, the target region set, scheduling constraints, and policy context. CO₂Router evaluates this request against the current state of the signal layer and returns a binding decision. The authorization model is synchronous in the hot path.

2.2 The Five-Action Schema

CO₂Router returns exactly one of five binding actions per authorization request:

The deny action is the governance primitive that most clearly distinguishes CO₂Router from advisory systems. A system that cannot deny does not govern.

2.3 Quality-Tiered Governance Leases

Every decision carries a governance lease — a time-bounded validity window tied to signal confidence:

3. Signal Abstraction Layer

3.1 Design Principles

• Lowest Defensible Signal doctrine: Route using the lowest carbon intensity value that can be defended with full provenance. Do not average. Use the lowest number whose source, freshness, and quality meet the minimum defensibility threshold.
• No provider averaging: Averaging signals from multiple providers destroys provenance. CO₂Router must be able to answer "why did you choose eu-west-1?" with a specific answer rooted in a specific signal from a specific provider at a specific time.
• Preserve provenance and trust flags: Every signal carries its source, timestamp, estimated flag, synthetic flag, and confidence score. These are propagated through the decision into the proof frame.
• Fallback is documented, not hidden: When a fallback is applied, the fallback step, confidence penalty, and reason are captured and surfaced in the decision output.

3.2 Provider Hierarchy

3.3 Provider Disagreement Detection

When multiple providers return signals for the same region at the same time, CO₂Router computes a disagreement score:

disagreementPct = abs(primary − secondary) / avg(primary, secondary) × 100

// Classification
none:    < 5%     (normal variance)
low:     5–15%    (log and continue)
medium:  15–30%   (flag, use lower signal)
high:    30–50%   (flag, confidence penalty)
severe:  > 50%    (flag, use lower, attach note to reasoning chain)

Design target: ≥95% provider disagreement detection accuracy. Empirical disagreement rates: 8–15% for US regions, 15–25% for international regions (marginal vs flow-traced methodology difference).

4. Governance Framework (SAIQ)

4.1 Framework Overview

The SAIQ framework is the four-layer evaluation model applied to every authorization request:

4.2 Evaluation Order

Multi-objective arbitration evaluates constraints in this fixed sequence. Earlier constraints can exit the evaluation without evaluating later ones:

Policy → Water → SLA → Carbon → Cost

// Policy violation = immediate deny (no further evaluation)
// Water scarcity violation = deny or delay (no carbon evaluation needed)
// SLA constraint = may override carbon routing preference
// Carbon = primary optimization target
// Cost = consequence of carbon decision, never the reason

4.3 Operating Modes

5. Replay + Proof Architecture

5.1 The Proof Hash

The proofHash is a SHA-256 hash of the canonical decision envelope at decision time. The canonical envelope includes: arbitrated signal values, policy evaluation result, decision action, selected region, reference timestamp, and operating mode. The hash is deterministic — given the same canonical envelope, the same hash is always produced.

// proofHash serves two purposes:
// 1. Tamper-evidence: any modification to the record invalidates the hash
// 2. Replay verification: replayed envelope must match original hash

// Decision record is append-only. Never updated or deleted.
// This is the basis for the replay guarantee.

5.2 Multi-Signal Snapshot (MSS)

The MSS is captured at decision time and stored in the proof record. Key fields:

{
  snapshotId:              string,        // unique MSS identifier
  carbonProvider:          string,        // primary provider used
  carbonProviderHealth:    "HEALTHY" | "DEGRADED" | "FAILED",
  waterAuthorityHealth:    "HEALTHY" | "DEGRADED" | "FAILED",
  carbonFreshnessSec:      number,        // age of carbon signal (seconds)
  waterFreshnessSec:       number,        // age of water signal (seconds)
  cacheStatus:             "live" | "warm" | "fallback",
  lastKnownGoodApplied:    boolean,
  carbonLineage:           string[],      // provenance chain
  waterLineage:            string[]       // provenance chain
}

6. Data Model

CO₂Router uses Prisma ORM over PostgreSQL (Neon, with pgbouncer connection pooling) with 35+ models across 11 migrations. The schema is the single source of truth for all persisted state.

Five primary data domains:

• Decision Data: DecisionLog, CarbonCommand, CarbonLedgerEntry, DecisionTraceEnvelope — append-only, never modified
• Grid Signal Data: GridSignalSnapshot, ProviderSnapshot, EIA930RawRecord — time-series, 15-min ingestion
• Water Impact Data: WaterBundle — basin + facility level, multi-scenario (current/2030/2050/2080)
• Organizational + Billing: Organization, BillingRecord, UsageRecord
• Intelligence + Learning: AdaptiveProfile, WorkloadEmbedding, ForecastRefresh

7. Latency Constraints

The 100ms hot path quality gate is non-negotiable. The p99 SLA contract is 200ms cross-region. Measured live system performance: 77ms p95 total, 59ms p95 compute (250 decision samples). See ADR-001 for the full five-layer latency control architecture.

8. Failure Handling and Fallback Discipline

Fallback is documented, not hidden. Every fallback step is captured in the decision output with reason, confidence penalty, and provider health state. The five-level fallback chain degrades gracefully from live data to a conservative static estimate while preserving governance. See the Latency ADR for fallback TTL architecture.

11. Accuracy Targets and Production SLAs

Appendix A: CiResponseV2 Schema Reference

// Zod-validated TypeScript contract — single source of truth for decision output
interface CiResponseV2 {
  // Core decision
  decision:               "run_now" | "reroute" | "delay" | "throttle" | "deny"
  decisionMode:           "runtime_authorization" | "scenario_planning"
  operatingMode:          "NORMAL" | "STRESS" | "CRISIS"
  decisionFrameId:        string            // UUID — used for replay and audit
  proofHash:              string            // SHA-256 of canonical decision envelope

  // Region + carbon
  selectedRegion:         string
  carbonIntensity:        number            // gCO₂/kWh
  carbon_delta_g_per_kwh: number | null
  forecast_stability:     string | null

  // Signal quality
  qualityTier:            "HIGH" | "MEDIUM" | "LOW"
  signalConfidence:       number            // 0–1
  source_used:            string | null
  validation_source:      string | null
  fallback_used:          boolean | null
  estimatedFlag:          boolean | null
  syntheticFlag:          boolean | null

  // Grid intelligence (nullable — EIA-930 dependent)
  balancingAuthority:           string | null
  demandRampPct:                number | null
  carbonSpikeProbability:       number | null
  curtailmentProbability:       number | null
  importCarbonLeakageScore:     number | null

  // Disagreement
  provider_disagreement: { flag: boolean; pct: number | null }

  // Lease
  leaseExpiresAt:         string            // ISO 8601
  decisionEnvelope:       object            // full signal state at decision time
  policyTrace:            object            // governance evaluation record
}