Canonical Reference

Master System Document

Canonical reference for all CO₂Router identity, claims, architecture principles, and distribution architecture. These definitions lock all downstream documents.

Identity Statement

Product Identity — Locked

CO₂Router

The Deterministic Environmental Execution Control Plane

"Authorise compute before it runs. Prove every decision."

Locked Technical Claims

These claims are used in all distribution materials. They are either measured facts or clearly-labeled design targets. No other values are permitted.

Claim	Value	Status
p95 total latency	77ms	MEASURED — 250 decision samples
p95 compute latency	59ms	MEASURED — 250 decision samples
p99 SLA ceiling	≤200ms cross-region	Contract target
Hot path budget	100ms	Internal quality gate
Carbon forecast variance	≤12% vs realized	DESIGN TARGET — not yet validated
Clean window detection	≥85%	DESIGN TARGET — not yet validated
Confidence calibration error	≤10%	DESIGN TARGET — not yet validated
Provider disagreement detection	≥95%	DESIGN TARGET — not yet validated
Database models	35+	Current schema — 11 migrations
Decision samples (proof record)	250	MEASURED

Locked Architecture Principles

Lowest Defensible Signal Doctrine

Route using the lowest carbon intensity value that can be defended with full provenance. The governing rule: use the lowest number whose source, freshness, and quality meet the minimum defensibility threshold.

No provider averaging. Averaging destroys provenance. The routing decision must be traceable to a single provider at a single timestamp.
No raw lowest. Using the lowest raw number without provenance is equally wrong. The signal must be defensible.
Provenance propagates. Source, timestamp, estimated flag, synthetic flag, and confidence score travel from provider through signal through decision into proof frame.

Evaluation Order

Policy → Water → SLA → Carbon → Cost

// Non-negotiable ordering. Cost is never a routing reason.
// Cost is a consequence of the carbon decision.
// Policy violations exit immediately — no carbon evaluation performed.

Fallback is Documented, Not Hidden

When a fallback is applied, the following are always captured and surfaced in the decision output:

Which fallback level was triggered
The reason for fallback (provider health state, cache miss)
The confidence penalty applied
fallbackUsed: true in CiResponseV2
syntheticFlag: true when data is synthetic (levels 4–5)
Quality tier downgraded to LOW with 30-minute lease

Workload Similarity Constraint

Workload similarity (embedding-based lookup) may influence confidence, explanation, and recommended delay windows only. It must never directly change the carbon score or routing decision.

// Hard constraints on adaptive intelligence layer:
maxEmbeddingsPerCommand: 1
maxSimilarityLookups:   10

// Similarity output may only modify:
// - signalConfidence (dampen, not amplify)
// - explanation.recommendedDelayWindows
// - explanation.historicalContext

// Similarity output must never modify:
// - carbonIntensity
// - decision (action)
// - selectedRegion
// - qualityTier

Locked Signal Doctrine

Provider	Permitted Uses	Prohibited Uses
WattTime MOER	Primary routing signal · MOER current + forecast · Causal scheduling truth · Avoided-emissions math	None — primary truth
EIA-930	demandRampPct · carbonSpikeProbability · curtailmentProbability · importCarbonLeakageScore · Predictive telemetry	Structural baseline (use Ember for that)
Ember	Structural validation · Confidence dampening · RegionStructuralProfile · Last data-backed fallback baseline	Fast-path routing · Any real-time decision
Electricity Maps	Flow-traced enrichment · Cross-border intelligence · EU region primary when configured	Replacing WattTime as US primary without explicit configuration

Live Proof Record

The canonical live decision used to verify system operation. This record is real — generated by the live engine.

{
  "job_id":           "32133b3a-77f5-4123-b5f6-024e8f954eba",
  "decision":         "run_now",
  "selectedRegion":   "us-west-2",
  "carbonIntensity":  2,              // gCO₂/kWh
  "signalConfidence": 0.88,
  "qualityTier":      "HIGH",
  "waterImpact":      1.13,           // liters
  "fallbackUsed":     false,
  "estimatedFlag":    false,
  "syntheticFlag":    false,
  "leaseExpiresAt":   "+4h"           // HIGH tier lease
}

Billing Model

Tier	Commands/Month	Model
Free	1,000	Per-command optimization
Pro	50,000	Per-command optimization
Enterprise	Unlimited	SLA-backed · custom contract
Overage	Unlimited beyond tier	$0.0015/command real · $0.00075/command simulation

Simulation commands count at 0.5× billing rate. Billing failure must never block routing — governance operates independently of billing state.

Segmented Pricing

Pricing is segmented by cloud spend. The product hierarchy is CI (entry) → Control (full governance) → Enterprise (unlimited + SLA).

Segment	Cloud Spend	CI (Entry)	Control (Full)	Enterprise	Pilot
Small	$25k–$75k/mo	$400/mo	$2,000/mo	$60k/yr	$250/30 days
Mid	$75k–$250k/mo	$800/mo	$4,000/mo	$120k/yr	$250/30 days
Large	$250k+/mo	$1,500/mo	$7,000/mo	$200k/yr	$250/30 days

Accuracy Targets — Disclosure Protocol

Required Disclosure

The four accuracy targets (≤12% forecast variance, ≥85% clean window detection, ≤10% confidence calibration error, ≥95% provider disagreement detection) are architectural design goals, not validated production metrics. They require sustained production volume to measure against realized outcomes. All distribution materials must label these targets as design targets or design goals — never as verified performance claims. The latency figures (77ms p95 total, 59ms p95 compute) are verified measurements and may be stated as such.