Appendix A: Code Examples: The Record Formats of the Five Functions
This appendix holds the record formats of AI Environment in full: the footprint record, the benefit record, the environmental budget, the placement policy, the supplier disclosure record, the environmental claim record, the hardware lifecycle record, the mandate manifest and the runbook manifest of an environmental agent, the environmental register and the AI Decision Record at the scale-up gate. For each format it gives the fields and the rule behind them, a JSON Schema that the structure must satisfy, one validated example (two or more where the chapters give several forms) taken from the two organisations of the book, and a short Python check for what a schema cannot say: that a range is ordered, that a carbon figure follows from the energy and the grid, that an evidence date has not run out, that a stop path is outside the system it stops.
Every record is the record that the owning chapter prints, completed where the chapter prints only an extract. A record that a chapter prints in full is reproduced without change. Where a chapter shows only the part that it needs, the missing fields are filled from the identifier ledger and the text of the chapters, and the first lines of the file say composed. Where two chapters give different values for the same field, the record follows the ledger of identifiers; the two cases that matter for reading the figures (FPR-NR-0001 in two revisions and FPR-HM-0002 from two directions) are explained in the sections that hold them. Every organisational figure in this appendix is illustrative. The names, dates, volumes and energy figures are those of the fictional Nordvik Region and Hansa Mutual and show the shape of a record; none is data, and none should be copied into a record of your own. One record is the exception: FPR-BK-0001 (A.4) is the footprint of the production of this book, a real measurement of token counts with an estimated energy, measured on 16 November 2026. It belongs to neither organisation, carries no illustrative label and is checked on its own date (A.15). The field names are those of the chapters. Appendix B holds blank skeletons in a general form for copying; the records here are the forms that the checks of this appendix read.
How to use this appendix
- Start with the footprint record (A.4). Every other record points to one: the benefit record to the footprint it is set against, the budget to the use it limits, the claim to the figures that support it.
- Copy the shape, not the values. Replace every name, date, volume and limit, and keep a field only if you can fill it with something that is true of your use. A field that is empty is written
nulland a person is named for it; it is never deleted. - Date every piece of evidence. Each claim carries the day it was measured and the number of days it stays valid (A.3). A record whose evidence has expired is marked, not deleted.
- Keep the meter and the stop path outside the system they limit. The budget, the placement policy, the mandate manifest and the runbook each say who holds the stop and that the path does not run through the thing it stops. A budget with no recorded stop drill is not counted as a cap.
- Run the checks. Save the schemas, the records and the code of A.14 into three folders and run
validate_records.py. A record that fails a schema is not read further; a record that passes the schema is then checked for what the schema cannot see. A check never replaces the person who reads the record and who is named in it.
Identifier families
Table A.2.1: Identifier families, the record each names and where it is specified.
| Family | Record | Owning chapters | Section |
|---|---|---|---|
FPR-NR-*, FPR-HM-*, FPR-BK-* |
Footprint record (BK: the production of this book) |
5 to 8 | A.4 |
BEN-NR-*, BEN-HM-* |
Benefit record | 9 | A.5 |
EBG-NR-*, EBG-HM-* |
Environmental budget | 4, 12, 20 | A.6 |
PLC-NR-*, PLC-HM-* |
Placement policy | 17 | A.7 |
SDR-NR-*, SDR-HM-* |
Supplier disclosure record | 8, 23 | A.8 |
CLM-NR-*, CLM-HM-* |
Environmental claim record | 22 | A.9 |
HWL-NR-*, HWL-HM-* |
Hardware lifecycle record | 16 | A.10 |
MND-NR-ENV-*, MND-HM-ENV-* |
Mandate manifest | 15 | A.11 |
RBK-NR-ENV-* |
Runbook manifest | 20 | A.12 |
environment-nr, environment-hm |
Environmental register | 4, 24 | A.13 |
AIDR-1300 to AIDR-1399 |
AI Decision Record at the scale-up gate | 24 | A.13 |
Other identifiers that the records mention are defined in their chapters: model-choice records MCR-* (Chapter 12), measurement plans MPL-* (Chapter 8), watch lists WCH-* (Chapter 11), tender annexes TA-* (Chapter 23), delegation profiles DLG-* (Chapters 15 and 20), role charters ROLE-* and competence records CMP-* (Chapter 24). The two numbers that the ledger keeps at two labelled values are FPR-NR-0001 (revision 1, 16.3 Wh and 0.52 g per resolved enquiry; revision 2, 30.5 Wh and 0.98 g, for the same boundary and the same month, differing in three inputs) and FPR-HM-0002 (bottom-up, 2.3 Wh and 0.81 g per claim triaged; top-down, 21 Wh at the IT boundary and 10.3 g, about thirteen times apart at one boundary). Both values and their direction are kept, each labelled wherever it appears, and neither is ever compared with the other.
A.3 Conventions
Dates and evidence age. Dates are ISO 8601 (2032-10-04). A period is a month (2032-09). The validity of evidence follows the convention of Chapter 4 and is set in the register, not in each record.
Table A.3.1: How long each kind of evidence stays valid, and why.
| Evidence | Valid for | Reason |
|---|---|---|
| Footprint of a running use | 90 days, or a change of model, region or volume | Volume, model version and grid change |
| Benefit record | 180 days, or a change of conditions | The alternative and the rebound change |
| Stop drill | 90 days | The stop path must work when it is needed |
| Supplier disclosure | 12 months, or the reporting year of the supplier | Suppliers report annually and change method |
| Hardware record | 90 days (measured utilisation) | Utilisation changes |
| Claim | The reporting year at most | A claim is true of a period |
Ranges. A figure with an uncertainty is a range {low, central, high} with low <= central <= high. A footprint record that gives only a central value says in dominating_assumptions why.
Illustrative. Every record of the two organisations carries labels: [illustrative] or a comment to that effect. The one exception is FPR-BK-0001, which carries labels: [measured-tokens, estimated-energy] and says in its comment that it is not illustrative.
What a check returns. Each check in this appendix returns two lists. A problem fails the record: it is a rule that the record breaks. A note is something the reader should see and that the record may legitimately carry: an open test, a value that is null with an owner, a budget that is not yet a cap. The first block below is the part of record_checks.py that every check shares; the checks that follow are its later parts and are saved to the same file in order.
# record_checks.py, part 0: helpers shared by every check (Python 3.12, PyYAML)
from __future__ import annotations
import math
import re
from datetime import date, timedelta
from typing import Any
def d(value: Any) -> date | None:
"""A date from a date object, an ISO string or None."""
if value is None or isinstance(value, date):
return value
return date.fromisoformat(str(value))
def expires(measured: Any, valid_days: int) -> date:
return d(measured) + timedelta(days=valid_days)
def ordered(r: dict) -> bool:
"""A range is ordered when low <= central <= high, where the ends are given."""
lo, mid, hi = r.get("low", r["central"]), r["central"], r.get("high", r["central"])
return lo <= mid <= hi
def close(a: float, b: float, rel: float) -> bool:
return math.isclose(a, b, rel_tol=rel, abs_tol=1e-9)
# Every check returns (problems, notes). A problem fails the record; a note is something
# the reader should see but that the record may legitimately carry (an open test, a null).
Result = tuple[list[str], list[str]]
A.4 The footprint record FPR-*
Owner and question. The use's owner, with the platform team and a reviewer who did not produce the figure, answers: what does this use cost the environment, at what boundary, in which year and with what check (Chapters 5 to 8)?
Table A.4.1: Fields of the footprint record FPR-*.
| Field | Meaning and rule |
|---|---|
id, revision |
FPR-NR-nnnn, FPR-HM-nnnn or, for the production of this book, FPR-BK-nnnn; the revision rises when the method or an input changes, and a superseded revision stays in version control |
use, service, mode, owner, accountable |
The use as the register names it, its service record SVC-*, its usage mode, the owner of the figure and the person who answers for the method |
functional_unit, period, volume |
The unit of work, the month measured and the number of units in it; all attempts are counted, failures included |
boundary |
Operational or lifecycle; what is included; what is excluded; location-based or market-based; the grid factor with its year and source |
method, multipliers |
How the figure was made (estimate, measurement, bottom-up or top-down) and the factors that turn work into energy: calls per unit, seconds per call, retries, draw |
result or energy_kwh and carbon_g_per_unit |
The energy and carbon per unit as ranges (revision 1 form), or the chain IT energy, facility energy and energy allocated to the use (revision 2 form) |
dominating_assumptions |
The inputs that move the result most |
independence or independent_check |
Who produced the figure and who checked it, and that the checker is not the producer; or the status of the check (none, partial, done) and what is open |
evidence |
The date measured and the days valid, or a list of items each with its own date, source and kind |
lca_frame |
Optional block that states the standing of the record as a life cycle assessment (Chapter 5, Table 5.3). It is required for any record that is called an LCA or that is published: lca_status (inventory, screening LCA or LCA, in words), review (none, expert or panel), guideline_mapping, functional_unit, boundary, stage_mapping, categories (climate change always, other categories named), cut_off (what was left out and the effect assessed), allocation (with the sensitivity under at least two rules), electricity_basis (both bases and which drives the figure), hardware_life_years with embodied_life_sensitivity_kgco2e, data_quality and compliance_statement (full or partial, against which text). A footprint record without it is an inventory |
Schema.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://aienvironment.example/schemas/fpr.schema.json",
"title": "Footprint record (FPR)",
"type": "object",
"required": ["id", "use", "functional_unit", "period", "volume", "boundary"],
"allOf": [
{"anyOf": [{"required": ["result"]}, {"required": ["carbon_g_per_unit"]}]},
{"anyOf": [{"required": ["independence"]}, {"required": ["independent_check"]}]}
],
"additionalProperties": false,
"properties": {
"id": {"type": "string", "pattern": "^FPR-(NR|HM|BK)-[0-9]{4}$"},
"revision": {"type": "integer", "minimum": 1},
"use": {"type": "string", "minLength": 1},
"service": {"type": "string", "pattern": "^SVC-(NR|HM)-[0-9]{3}$"},
"mode": {"type": "integer", "minimum": 0, "maximum": 5},
"owner": {"type": "string"},
"accountable": {"type": "string"},
"functional_unit": {"type": "string", "minLength": 1},
"period": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}$"},
"volume": {"type": "number", "exclusiveMinimum": 0},
"boundary": {
"oneOf": [
{"type": "string", "minLength": 1},
{
"type": "object",
"required": ["scope", "carbon_basis"],
"properties": {
"scope": {"enum": ["operational", "lifecycle"]},
"included": {"type": "array", "items": {"type": "string"}},
"excluded": {"type": "array", "items": {"type": "string"}},
"carbon_basis": {"enum": ["location-based", "market-based"]},
"grid_g_per_kwh": {"type": "object", "required": ["value", "year"],
"properties": {"value": {"type": "number", "minimum": 0}, "year": {"type": "integer"}, "source": {"type": "string"}}},
"pue": {"type": "number", "minimum": 1}
}
}
]
},
"method": {"type": "object"},
"multipliers": {"type": "object"},
"result": {
"type": "object",
"required": ["energy_wh_per_unit", "carbon_g_per_unit"],
"properties": {
"statistic": {"enum": ["mean", "median", "p95"]},
"energy_wh_per_unit": {"$ref": "#/$defs/range"},
"carbon_g_per_unit": {"$ref": "#/$defs/range"},
"month_kwh": {"$ref": "#/$defs/range"}
}
},
"energy_kwh": {"type": "object"},
"carbon_g_per_unit": {"$ref": "#/$defs/range"},
"embodied": {"type": "object"},
"dominating_assumptions": {"type": "array", "items": {"type": "string"}, "minItems": 1},
"independence": {
"type": "object",
"required": ["produced_by", "checked_by", "independent_of_producer"],
"properties": {"produced_by": {"type": "string"}, "checked_by": {"type": "string"}, "independent_of_producer": {"type": "boolean"}}
},
"independent_check": {"type": "object", "required": ["status"], "properties": {"status": {"enum": ["none", "partial", "done"]}}},
"evidence": {
"oneOf": [
{"type": "object", "required": ["measured_on", "valid_days"],
"properties": {"measured_on": {"type": "string", "format": "date"}, "valid_days": {"type": "integer", "minimum": 1}, "result_of_check": {"type": "string"}}},
{"type": "array", "minItems": 1, "items": {"type": "object", "required": ["item"]}}
]
},
"reviewed_by": {"type": "string"},
"supersedes": {"type": "object"},
"lca_frame": {
"type": "object",
"required": ["lca_status", "functional_unit", "boundary", "categories"],
"additionalProperties": false,
"properties": {
"lca_status": {"type": "string", "minLength": 1},
"review": {"enum": ["none", "expert", "panel"]},
"guideline_mapping": {"type": "string"},
"functional_unit": {"type": "string", "minLength": 1},
"boundary": {"type": "string", "minLength": 1},
"stage_mapping": {"type": "string"},
"categories": {"type": "array", "items": {"type": "string"}, "minItems": 1},
"cut_off": {"type": "array", "items": {"type": "string"}},
"allocation": {"type": "object"},
"electricity_basis": {"type": "object"},
"hardware_life_years": {"type": "number", "exclusiveMinimum": 0},
"embodied_life_sensitivity_kgco2e": {"type": "object", "minProperties": 2, "additionalProperties": {"type": "number", "minimum": 0}},
"data_quality": {"type": "object"},
"compliance_statement": {"type": "string"}
}
},
"labels": {"type": "array", "items": {"type": "string"}}
},
"$defs": {
"range": {
"type": "object",
"required": ["central"],
"properties": {"low": {"type": "number", "minimum": 0}, "central": {"type": "number", "minimum": 0}, "high": {"type": "number", "minimum": 0}},
"additionalProperties": false
}
}
}
Example: revision 1 of the citizen-service assistant at Nordvik Region. The range is a factor of seven, and the record names the three assumptions that dominate it. It is the record the benefit record of A.5 is set against.
# register/fpr/FPR-NR-0001.yaml, revision 1 (illustrative, Nordvik Region)
id: FPR-NR-0001
revision: 1 # first estimate; revision 2 (below) is written from the provider's specification
use: citizen-service assistant, open-weight generation route
service: SVC-NR-005
owner: ida.pettersson # procurement manager; supplier figures
accountable: henrik.dahl # owner of the environmental register
functional_unit: resolved enquiry
period: 2032-09
volume: 146000
boundary:
scope: operational
included: [accelerators, host cpu and memory, facility overhead]
excluded: [embodied impact, end-user devices, network outside the data centre, water]
carbon_basis: location-based
grid_g_per_kwh: {value: 32, year: 2032, source: profile}
method:
type: estimate
inputs: [pool size 24, draw per accelerator range, provider pue, gateway token share]
allocation: share of pool by tokens through the gateway
multipliers:
queries_per_unit: gateway
reasoning: off
result:
statistic: mean
energy_wh_per_unit: {low: 7.7, central: 16.3, high: 30.0}
carbon_g_per_unit: {low: 0.19, central: 0.52, high: 1.35}
dominating_assumptions: [draw per accelerator, grid factor, pool share]
independence:
produced_by: platform-team
checked_by: sustainability-lead # Astrid Nyberg; reviewer, not producer
independent_of_producer: true
evidence:
measured_on: 2032-10-04
valid_days: 90
result_of_check: range accepted; draw per accelerator not metered
labels: [illustrative]
Example: revision 2 (draft) of the same use. The boundary and the month are the same. The draw per accelerator, the PUE and the pool share are corrected from the provider's specification, so that the energy per resolved enquiry is 30.5 Wh at the facility boundary and 25.2 Wh at the IT boundary, against 16.3 Wh in revision 1. The two are kept and labelled, and the register carries revision 1 while revision 2 is a draft with its independent check still partial.
# footprint/FPR-NR-0001.yaml, revision 2 (illustrative figures; draft of September 2032)
id: FPR-NR-0001
revision: 2 # draft; revision 1 is the estimate above (0.52 g)
use: citizen-service assistant, open-weight route
period: 2032-09
functional_unit: resolved enquiry
volume: 146000
boundary: operational, facility level, location-based, reserved pool only
energy_kwh:
it: {central: 8986, low: 7776, high: 10714, kind: estimate}
facility: {central: 10873, pue: 1.21, pue_kind: vendor-reported}
allocated_to_use: {central: 4458, share: 0.41, share_basis: gateway tokens}
carbon_g_per_unit: {central: 0.98, low: 0.85, high: 1.17}
embodied: {status: unsourced, included: false}
evidence:
- {item: accelerator_hours, measured_on: 2032-09-30, source: gateway, valid_days: 90}
- {item: pue, measured_on: 2032-05-15, source: SDR-NR-0001, valid_days: 365}
- {item: power_per_accelerator, kind: assumption, source: provider specification}
independent_check:
status: partial
done: accelerator-hours gateway vs invoice, within 0.05
open: metered kWh for the reserved pool requested from the provider
reviewed_by: sustainability-lead
supersedes: {id: SCI-2026-10, g_per_unit: 1.90, period: 2026-10, status: expired}
Example: the claims-triage agent at Hansa Mutual, bottom-up. The 2.3 Wh per claim count the active accelerator-seconds. The top-down figure of Chapter 8, 21 Wh per claim at the IT boundary from a 6 per cent share of the rack energy with idle capacity included, is a separate, labelled record; the two are about thirteen times apart at one boundary, the likely cause is the idle capacity held for the agent, and the cause is not measured.
# composed: dominating_assumptions is taken from the text of Chapter 6; the other fields are the record of that chapter
# register/fpr/FPR-HM-0002.yaml (illustrative, Hansa Mutual; bottom-up)
id: FPR-HM-0002
use: claims-triage agent
service: SVC-HM-002
mode: 5
owner: anja.weiss # head of the group AI platform
accountable: verena.lindner # method for Scope 2 and Scope 3
functional_unit: claim triaged # all attempts counted, failures included
period: 2032-09
volume: 140000
boundary:
scope: operational
included: [accelerators, host share, facility overhead]
excluded: [embodied impact, burst capacity in cloud a, water, network]
carbon_basis: location-based
grid_g_per_kwh: {value: 350, year: 2032, source: profile}
pue: 1.38
method:
type: estimate from rack meters and gateway traces
direction: bottom-up # active accelerator-seconds; the top-down figure of Chapter 8 is a separate, labelled record
multipliers:
calls_per_unit: {mean: 9, p95: gateway}
seconds_per_call: {low: 0.7, central: 0.9, high: 1.2}
retry_factor: {low: 1.05, central: 1.15, high: 1.30}
draw_w_per_accelerator: {low: 450, central: 650, high: 850}
result:
statistic: mean
energy_wh_per_unit: {low: 1.1, central: 2.3, high: 4.8}
carbon_g_per_unit: {low: 0.38, central: 0.81, high: 1.68}
month_kwh: {low: 150, central: 325, high: 673}
dominating_assumptions: [draw per accelerator, seconds per call, retry factor]
independence:
produced_by: group-ai-platform
checked_by: finops-lead # Jan Berger; reads the meter and the invoice
independent_of_producer: true
evidence:
measured_on: 2032-10-06
valid_days: 90
result_of_check: central value within meter range; burst energy not metered
labels: [illustrative]
Example: the model scope at Hansa Mutual, with the lca_frame. Chapter 5 prints the training of the claims-route classifier in the model-scope form (training runs, embodied term, allocation); the record below carries its figures in the form that the check reads. All 11 runs are counted, the base model's pre-training is cut off because the provider gives accelerator hours only, and the lca_frame says that the record is an inventory with one category and no review, so it supports internal decisions and no public comparison. The carbon figure is the 425,250 g of the metered energy at 350 g per kWh plus the 12,500 g of allocated embodied impact. The sensitivity shows the embodied term at lives of three, five and six years, holding the reserved hours fixed.
# composed: Chapter 5 prints this record in the model-scope form; the fields of the use-record form are filled from it
# register/fpr/FPR-HM-0007.yaml (illustrative, Hansa Mutual; model scope, training of version 2032.2)
id: FPR-HM-0007
use: claims-route classifier version 2032.2, training of 11 runs (model scope; used by FPR-HM-0003)
owner: katja.neumann # metering of the Frankfurt racks
accountable: verena.lindner # method owner
functional_unit: one training of version 2032.2, all 11 runs
period: 2032-09
volume: 1
boundary:
scope: lifecycle
included: [rack-metered IT energy of all 11 runs with the host, facility overhead through PUE, allocated embodied impact of the accelerators]
excluded: [data preparation, evaluation outside the platform, "pre-training of the base model (cut-off rule, the provider gives accelerator hours only)"]
carbon_basis: location-based
grid_g_per_kwh: {value: 350, year: 2032, source: profile}
pue: 1.38
method:
type: metered at rack level
runs_counted: 11 # 1 final run and 10 earlier runs (search and one failed run)
accelerator_hours: {final_run: 240, all_runs: 1420}
it_energy_kwh: 880
facility_energy_kwh: 1215
embodied:
accelerator_kgco2e_each: 200 # assumption in the order of published per-card figures
lifespan_years: 5
utilisation: 0.52
allocated_kgco2e: 12.5
rule: reserved hours divided by life and by measured utilisation
result:
statistic: mean
energy_wh_per_unit: {central: 1215000}
carbon_g_per_unit: {central: 437500} # 425,250 operational at 350 g/kWh + 12,500 embodied
dominating_assumptions: [accelerator life, embodied impact per card, PUE of the Frankfurt halls] # a single central value: the metered energy has no range, the embodied term has the sensitivity below
lca_frame:
lca_status: inventory with one category (climate change)
review: none
guideline_mapping: ITU-T L.1801 (02/2026), mapping only
functional_unit: one training of version 2032.2, all 11 runs
boundary: rack-metered IT energy times PUE, plus allocated embodied; no data preparation
stage_mapping: training and embodied to production stage; inference to use stage (FPR-HM-0003)
categories: [climate change]
cut_off: [pre-training of the base model]
hardware_life_years: 5
embodied_life_sensitivity_kgco2e: {years_3: 20.8, years_5: 12.5, years_6: 10.4}
independent_check:
status: none
open: own metering, not independently verified
evidence:
- {item: rack energy of all runs, measured_on: 2032-09-30, source: rack counters, valid_days: 90}
- {item: embodied impact per accelerator, kind: assumption, source: order of published per-card figures}
labels: [illustrative]
Example: the production of this book. FPR-BK-0001 is the one record of the appendix that is real. It counts the operational inference energy of the 101 recorded agent transcripts that drafted, checked and revised this manuscript, from their token counts; the energy per token is a proxy from a published model of other systems, and the grid is assumed. Chapter 8 explains the method and the three scenarios; the floor counts output tokens only at the median rate of the 5,000-token response of that model (it is not a lower bound), the central value adds new input and cache writes at 1 per cent and cache reads at 0.1 per cent of that rate, and the ceiling charges every token at the rate times the idle and redundancy factor of 1.31. The owner is unassigned, because the record is written after the work and no one was named for it; the check reports that as a note. The record fails the Cap test of Chapter 8 for the reason it gives in its comment, and it is not a row of either organisation's register: if it were, the rule of A.13 that a row without a footprint, benefit and stop drill record is missing them, not exempt, would report it incomplete. Its evidence runs for 90 days from 16 November 2026, so it is checked on that date and not on the date of the illustrative records (A.15).
# footprint/FPR-BK-0001.yaml (the book's own production; measured token counts, estimated energy; NOT illustrative)
# cap: no budget was set before the work and no stop path was defined (Chapter 4); the Cap test is failed
id: FPR-BK-0001
revision: 1
use: production of this book, 33 files drafted, checked and revised by delegated agents
owner: unassigned # no owner named yet; the author names one before release
functional_unit: one edition of the manuscript (231,220 words)
period: 2026-11
volume: 1
boundary:
scope: operational
included: [inference energy of the 101 recorded agent transcripts, through proxy energy per token]
excluded: [orchestrating session, unrecorded agents, model training, hardware manufacture, network, sandbox compute (about 11 h), CI runners, hosting and reading, text-to-speech and rendering for the short, author and reviewer time and devices]
carbon_basis: location-based
grid_g_per_kwh: {value: 20, year: 2026, source: assumption, continental_alternative: 350}
method:
type: estimate from recorded token counts
carbon_check_tolerance: 0.005 # carbon is energy times grid to within 0.5 per cent for this record
tokens: {output: 8063025, cache_creation: 40048021, cache_read: 1835637219, input: 13786}
proxy: {reasoning_response_wh: 3.91, reasoning_tokens: 5000, spread_in_paper_mwh_per_output_token: [0.78, 1.05], ceiling_factor: 1.31, source: "Oviedo et al. 2026, node times PUE, not these models"}
share_of_output_rate: {floor: [0, 0], central: [0.01, 0.001], ceiling: [1, 1]} # [new input tokens, cached tokens]
result:
energy_wh_per_unit: {low: 6305, central: 8054, high: 1929764}
carbon_g_per_unit: {low: 126, central: 161, high: 38595} # at 20 g/kWh; at 350 g/kWh: 2207, 2819, 675417
dominating_assumptions: [energy charged per cached token, energy per output token, grid factor, orchestrating session not counted]
independent_check:
status: none
open: counted by the producer from its own transcripts; no second source and no provider figure for these models
evidence:
- {item: token counts, measured_on: 2026-11-16, source: usage fields of recorded transcripts, valid_days: 90}
- {item: energy per token, kind: assumption, source: proxy from a published model}
- {item: cached-token share, kind: assumption, source: author of the calculation}
labels: [measured-tokens, estimated-energy]
Check. The check refuses a range out of order, a boundary that does not say what it leaves out, a carbon figure that is not energy times grid (within 5 per cent, or within the tolerance that the record sets for itself), a facility figure that is not IT energy times PUE, expired evidence and a check that is not independent. When an lca_frame is present it also refuses a frame without climate change among its categories, one that lacks a functional unit or boundary, and an embodied sensitivity that rises with the life of the hardware. It reports as notes what the record honestly carries open, including an owner who is unassigned and an lca_frame without a review.
# record_checks.py, part 1: footprint record
def check_fpr(rec: dict, today: date, index: dict | None = None) -> Result:
p: list[str] = []
n: list[str] = []
res = rec.get("result", {})
for name, rng in (("energy_wh_per_unit", res.get("energy_wh_per_unit")),
("carbon_g_per_unit", res.get("carbon_g_per_unit") or rec.get("carbon_g_per_unit"))):
if rng and not ordered(rng):
p.append(f"{name}: low, central and high are not in order")
b = rec["boundary"]
if isinstance(b, dict):
if not b.get("excluded"):
p.append("boundary: says what is counted but not what is left out")
grid = b.get("grid_g_per_kwh", {}).get("value")
if grid and res.get("energy_wh_per_unit") and res.get("carbon_g_per_unit"):
implied = res["energy_wh_per_unit"]["central"] * grid / 1000
tol = rec.get("method", {}).get("carbon_check_tolerance", 0.05) # a record may tighten the 5 per cent
if not close(implied, res["carbon_g_per_unit"]["central"], tol):
p.append(f"carbon {res['carbon_g_per_unit']['central']} g is not energy x grid ({implied:.3f} g)")
ek = rec.get("energy_kwh")
if ek: # revision 2 form: chain IT -> facility -> allocated to the use
if not close(ek["it"]["central"] * ek["facility"]["pue"], ek["facility"]["central"], 0.005):
p.append("facility energy is not IT energy x PUE")
if not close(ek["facility"]["central"] * ek["allocated_to_use"]["share"], ek["allocated_to_use"]["central"], 0.005):
p.append("allocated energy is not facility energy x share")
wh = ek["allocated_to_use"]["central"] * 1000 / rec["volume"]
n.append(f"allocated energy per unit {wh:.1f} Wh; implied grid "
f"{rec['carbon_g_per_unit']['central'] / wh * 1000:.0f} g/kWh")
ev = rec.get("evidence")
items = ev if isinstance(ev, list) else [ev]
for e in items:
if "valid_days" not in e:
n.append(f"evidence '{e.get('item', 'record')}' is an assumption, not a measurement")
elif expires(e["measured_on"], e["valid_days"]) < today:
p.append(f"evidence '{e.get('item', 'record')}' expired on {expires(e['measured_on'], e['valid_days'])}")
ind = rec.get("independence")
if ind:
if not ind["independent_of_producer"] or ind["produced_by"] == ind["checked_by"]:
p.append("the check is not independent of the producer")
elif rec["independent_check"]["status"] != "done":
n.append(f"independent check is {rec['independent_check']['status']}")
if not rec.get("dominating_assumptions") and "result" in rec:
p.append("a result without its dominating assumptions")
if rec.get("owner") == "unassigned":
n.append("no owner is named for the figure")
lf = rec.get("lca_frame")
if lf:
if "climate change" not in lf["categories"]:
p.append("lca_frame: climate change is the one mandatory category")
sens = lf.get("embodied_life_sensitivity_kgco2e", {})
pairs = []
for k, v in sens.items():
m = re.fullmatch(r"years_(\d+(?:\.\d+)?)", k)
if not m:
p.append(f"lca_frame: sensitivity key {k!r} is not of the form years_N")
else:
pairs.append((float(m.group(1)), v))
by_life = [v for _, v in sorted(pairs)]
if by_life != sorted(by_life, reverse=True):
p.append("lca_frame: the embodied term rises with the life of the hardware")
if lf.get("review", "none") == "none":
n.append("lca_frame: no critical review; it supports internal decisions, not a public comparison")
return p, n
A.5 The benefit record BEN-*
Owner and question. The accountable owner of the benefit, outside the sponsor's line, answers: what does this use achieve, against which alternative and with what rebound (Chapter 9)?
Table A.5.1: Fields of the benefit record BEN-*.
| Field | Meaning and rule |
|---|---|
footprint_record |
The footprint record whose unit the benefit is stated in; the number matches the footprint of the use |
intended_benefit |
The unit of benefit and its ledger: A (environmental, same unit), B (physical, not yet environmental) or C (not environmental) |
baseline, alternative |
The control: a hold-out, a paired comparison or a before-and-after, with its period; and the non-AI alternative chosen and the ones untested |
measured_effect |
The effect with its range, the quality sample and, in a separate ledger, the cost |
comparison |
The footprint per unit of benefit, the footprint of the alternative and environmental_effect (shown or not shown) |
rebound |
The volume at the start, its unit and the date of the recheck |
decision |
proceed, redesign, defer or decline, by whom, when, the AI Decision Record and the threshold |
claims_allowed, claims_withheld |
What the organisation may say and what it may not |
evidence |
When measured, the days valid and the expiry |
comparison_case, functional_unit_same_as_fpr, second_order_effects |
Optional. comparison_case is 1 for an AI system against a non-AI reference and 2 for two AI systems (Chapter 9, after ITU-T L.1801); functional_unit_same_as_fpr says whether the benefit and the footprint are stated on one functional unit; second_order_effects is a separate, labelled block and is never added to the footprint |
Schema.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://aienvironment.example/schemas/ben.schema.json",
"title": "Benefit record (BEN)",
"type": "object",
"required": ["id", "footprint_record", "use", "functional_unit", "owner", "sponsor", "intended_benefit", "baseline", "alternative", "measured_effect", "comparison", "rebound", "decision", "claims_allowed", "claims_withheld", "evidence"],
"additionalProperties": false,
"properties": {
"id": {"type": "string", "pattern": "^BEN-(NR|HM)-[0-9]{4}$"},
"footprint_record": {"type": "string", "pattern": "^FPR-(NR|HM)-[0-9]{4}$"},
"use": {"type": "string"},
"functional_unit": {"type": "string"},
"owner": {"type": "string", "minLength": 1},
"sponsor": {"type": "string", "minLength": 1},
"intended_benefit": {"type": "object", "required": ["unit", "ledger"], "properties": {"unit": {"type": "string"}, "ledger": {"enum": ["A", "B", "C"]}}},
"baseline": {"type": "object", "required": ["kind", "period"]},
"alternative": {"type": "object", "required": ["chosen"]},
"measured_effect": {"type": "object", "minProperties": 1},
"comparison": {
"type": "object",
"required": ["environmental_effect"],
"properties": {"environmental_effect": {"enum": ["shown", "not shown"]}}
},
"rebound": {"type": "object", "required": ["volume_at_start", "unit", "recheck"]},
"decision": {
"type": "object",
"required": ["value", "by", "date", "record"],
"properties": {"value": {"enum": ["proceed", "redesign", "defer", "decline"]}, "record": {"type": "string", "pattern": "^AIDR-13[0-9]{2}$"}}
},
"claims_allowed": {"type": "array", "items": {"type": "string"}},
"claims_withheld": {"type": "array", "items": {"type": "string"}},
"comparison_case": {"enum": [1, 2]},
"functional_unit_same_as_fpr": {"type": "boolean"},
"second_order_effects": {"type": "object"},
"evidence": {"type": "object", "required": ["measured_on", "valid_days", "expires"]},
"labels": {"type": "array", "items": {"type": "string"}}
}
}
Example: Nordvik Region. The hold-out shows 7 calls fewer within 48 hours per 100 enquiries (5 to 9), which is 7.4 g of carbon dioxide equivalent per call avoided (2.1 to 27.0) on revision 1 of the footprint. The footprint of a handled call is unknown, so the environmental effect is not shown and the claim that emissions were reduced is withheld. The cost ledger is separate and is not netted.
# register/ben/BEN-NR-0001.yaml (illustrative, Nordvik Region)
id: BEN-NR-0001
footprint_record: FPR-NR-0001 # revision 1: 0.52 g CO2e per resolved enquiry (0.19 to 1.35), 2032-09
use: citizen-service assistant, open-weight generation route
functional_unit: resolved enquiry
owner: service-desk-manager # outside the sponsor's line
sponsor: henrik.dahl
intended_benefit: {unit: call avoided within 48 hours, ledger: B}
baseline: {kind: randomised hold-out, period: 2032-10-11/2032-10-24, control: static FAQ and form}
alternative: {chosen: static FAQ and form, untested: rule-based search over same pages}
measured_effect:
calls_per_100_enquiries: {control: 21, assistant: 14, difference: {low: 5, central: 7, high: 9}}
quality: {sampled: 400, materially_wrong: 14}
cost_eur_per_month: {use: 7300, calls_avoided: 76650} # separate ledger, not netted
comparison:
footprint_g_per_call_avoided: {low: 2.1, central: 7.4, high: 27.0}
footprint_of_alternative: unknown # handled call; energy-manager estimate due 2032-12-15
environmental_effect: not shown
rebound: {volume_at_start: 146000, unit: enquiries per month, recheck: 2033-03-31}
decision: {value: proceed, by: henrik.dahl, date: 2032-11-08, record: AIDR-1309,
threshold: "footprint high end below 250 kg CO2e per month; review if volume +50%"}
claims_allowed: [service benefit, cost benefit]
claims_withheld: [emissions reduced]
evidence: {measured_on: 2032-10-24, valid_days: 180, expires: 2033-05-07} # clock from the decision date, 2032-11-08
labels: [illustrative]
Example: Hansa Mutual. The agent routes 93.5 per cent of audited claims correctly against 91.8 per cent for the rules. The gain is concentrated in free text (87.4 against 83.3 per cent), so the decision is to redesign: rules for structured claims, the agent for free text, and a retest in 90 days. The benefit is service quality (ledger C) and no environmental effect is shown.
# register/ben/BEN-HM-0002.yaml (illustrative, Hansa Mutual)
id: BEN-HM-0002
footprint_record: FPR-HM-0002 # 0.81 g CO2e per claim (0.38 to 1.68), 2032-09, Cloud A burst unmetered
use: claims-triage agent (Mode 5)
functional_unit: claim triaged
owner: head-claims-operations-pl # outside the platform team's line
sponsor: anja.weiss
intended_benefit: {unit: claim routed correctly at registration, ledger: C}
baseline: {kind: paired comparison on audited sample, claims: 6000, period: 2032-09-05/2032-10-31}
alternative: {chosen: rule-based router, footprint_wh_per_claim: "<0.01 (estimate, processor time, not metered)"}
measured_effect:
correct_route_pct: {agent: 93.5, rules: 91.8}
by_class: {structured_62pct: {agent: 97.2, rules: 97.0}, free_text_38pct: {agent: 87.4, rules: 83.3}}
delay_if_misrouted_days_median: 1.3
comparison:
extra_correct_routes_per_month: 2380
footprint_g_per_extra_correct_route: {low: 22, central: 48, high: 99} # footprint range at the central effect
environmental_effect: not shown # case C: no physical activity displaced
rebound: {volume_at_start: 140000, unit: claims per month, recheck: 2033-03-31}
decision: {value: redesign, by: annette.kraemer, date: 2032-11-15, record: AIDR-1359,
change: "rules for structured claims; agent for free text", retest_days: 90}
claims_allowed: [service benefit]
claims_withheld: [AI work became more efficient] # see CLM-HM-0001
evidence: {measured_on: 2032-10-31, valid_days: 180, expires: 2033-05-14} # clock from the decision date, 2032-11-15
labels: [illustrative]
Check. The check recomputes the footprint per unit of benefit from the footprint record and the measured effect, refuses an environmental claim where no environmental effect is shown, and tests the dates. The clock of a benefit record runs from the decision date in the examples of Chapter 9 (the expiry of BEN-NR-0001 is 2033-05-07, 180 days after 2032-11-08), and the check reports, as a note, that the measurement itself is older.
# record_checks.py, part 2: benefit record
def per_benefit(fp_g: tuple, effect: tuple) -> tuple:
"""Footprint per unit of benefit: (smallest footprint / largest effect, central, largest / smallest)."""
return fp_g[0] / effect[2], fp_g[1] / effect[1], fp_g[2] / effect[0]
def _footprints(rec: dict, index: dict) -> list[dict]:
return [r for (i, _), r in index.items() if i == rec["footprint_record"] and "result" in r]
def check_ben(rec: dict, today: date, index: dict) -> Result:
p: list[str] = []
n: list[str] = []
fps = _footprints(rec, index)
if not fps:
p.append(f"footprint record {rec['footprint_record']} not found")
me, cmp_ = rec["measured_effect"], rec["comparison"]
given = cmp_.get("footprint_g_per_call_avoided") or cmp_.get("footprint_g_per_extra_correct_route")
if "calls_per_100_enquiries" in me:
diff = me["calls_per_100_enquiries"]["difference"]
effect = tuple(diff[k] / 100 for k in ("low", "central", "high"))
else:
c = me["correct_route_pct"]
e = (c["agent"] - c["rules"]) / 100
effect = (e, e, e)
ok = False
for fp in fps:
r = fp["result"]["carbon_g_per_unit"]
lo, mid, hi = per_benefit((r["low"], r["central"], r["high"]), effect)
same_centre = close(mid, given["central"], 0.02)
same_ends = close(lo, given["low"], 0.03) and close(hi, given["high"], 0.03)
ok = ok or (same_centre and same_ends)
if fps and not ok:
p.append("footprint per unit of benefit does not follow from the footprint record and the measured effect")
if cmp_["environmental_effect"] == "not shown":
for claim in rec["claims_allowed"]:
if re.search(r"emission|carbon|energy|water", claim, re.I):
p.append(f"claim '{claim}' is allowed although no environmental effect is shown")
if not rec["claims_withheld"]:
p.append("no environmental effect is shown, so some claim must be withheld")
dec, ev = rec["decision"], rec["evidence"]
if d(ev["expires"]) != d(dec["date"]) + timedelta(days=ev["valid_days"]):
p.append("expires is not the decision date plus valid_days")
if expires(ev["measured_on"], ev["valid_days"]) != d(ev["expires"]):
n.append("the clock runs from the decision date; the measurement is older "
f"(measurement plus {ev['valid_days']} days is {expires(ev['measured_on'], ev['valid_days'])})")
if d(ev["expires"]) < today:
p.append("the benefit record has expired")
if d(rec["rebound"]["recheck"]) <= d(dec["date"]):
p.append("the rebound recheck is not after the decision")
if rec["owner"] == rec["sponsor"]:
p.append("the benefit is owned by its sponsor")
if rec.get("functional_unit_same_as_fpr") is False:
n.append("the benefit and the footprint are not on one functional unit; the comparison needs a stated conversion")
return p, n
A.6 The environmental budget EBG-*
Owner and question. A person who is not the agent and not the service owner sets the budget and answers: what may this use spend in a period, who can stop it, and does the stop path work (Chapters 4, 12, 13, 15 and 20)?
Table A.6.1: Fields of the environmental budget EBG-*.
| Field | Meaning and rule |
|---|---|
use, unit, period |
The footprint record of the use, the functional unit and the period |
status |
proposed until a stop drill has been recorded; then active. A budget with no valid drill is not counted as a cap |
set_by, approved_by, reviewed_by |
Never the agent and not the use's own service owner |
budget |
The limits: energy per month, carbon per unit, cost, and for a cascade the escalation maximum and the quality floor, which is never traded for energy |
quota, conversion |
The limit in units of work, derived once at approval, and the latest energy per unit with its date |
basis, measured_by |
How the limit was derived, and the meters and counters that are read outside the system limited |
stop |
Holders, the path, that it is independent of the system it stops, the last drill and its validity |
on_breach |
The ladder of thresholds and what each step does |
rebound_check |
The monthly volume against its baseline and the rise that is reported |
Schema.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://aienvironment.example/schemas/ebg.schema.json",
"title": "Environmental budget (EBG)",
"type": "object",
"required": [
"id",
"use",
"status",
"period",
"set_by",
"unit",
"budget",
"basis",
"measured_by",
"stop",
"on_breach",
"rebound_check"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^EBG-(NR|HM)-[0-9]{4}$"
},
"use": {
"type": "string",
"pattern": "^FPR-(NR|HM)-[0-9]{4}$"
},
"status": {
"enum": [
"proposed",
"active",
"suspended",
"retired"
]
},
"period": {
"enum": [
"monthly",
"quarterly",
"yearly"
]
},
"set_by": {
"type": "string",
"minLength": 1
},
"approved_by": {
"type": "string"
},
"reviewed_by": {
"type": "string"
},
"unit": {
"type": "string"
},
"budget": {
"type": "object",
"minProperties": 1,
"properties": {
"energy_kwh_per_month": {
"type": "number",
"exclusiveMinimum": 0
},
"carbon_g_per_unit": {
"type": "number",
"exclusiveMinimum": 0
},
"cost_eur_per_month": {
"type": "number",
"exclusiveMinimum": 0
},
"escalation_rate_max": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 1
},
"quality_floor": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
},
"quota": {
"type": "object",
"required": [
"units_per_month",
"derived_with_wh_per_unit"
]
},
"conversion": {
"type": "object",
"required": [
"wh_per_unit",
"measured",
"valid_days"
]
},
"baseline_units_per_month": {
"type": "number",
"exclusiveMinimum": 0
},
"basis": {
"type": "string",
"minLength": 1
},
"measured_by": {
"type": "object",
"minProperties": 1
},
"stop": {
"type": "object",
"required": [
"path",
"independent_of_assistant",
"last_drill",
"drill_valid_days"
],
"properties": {
"holder": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"holders": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"path": {
"type": "string"
},
"independent_of_assistant": {
"type": "boolean"
},
"last_drill": {
"type": [
"string",
"null"
],
"format": "date"
},
"drill_valid_days": {
"type": "integer",
"minimum": 1
},
"drills": {
"type": "array",
"items": {
"type": "object",
"required": [
"date",
"result"
]
}
}
},
"anyOf": [
{
"required": [
"holder"
]
},
{
"required": [
"holders"
]
}
]
},
"on_breach": {
"type": "object",
"minProperties": 1
},
"rebound_check": {
"type": "string"
},
"rebound_alert_share": {
"type": "number",
"minimum": 0
},
"resolution_floor": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
Example: Nordvik Region. The budget of the citizen-service assistant, 4,450 kWh a month before facility overhead, is turned into a quota of 160,650 resolved enquiries by the energy per unit used at approval. The latest conversion, 25.2 Wh, would use 9 per cent less of the budget at the quota; the quota is not recomputed silently. The first drill, on 2032-11-16, failed after 14 minutes; the second, on 2032-12-07, passed in 6 minutes 20 seconds (6.3 minutes in the record), and the budget became active.
# budget/EBG-NR-0001.yaml (illustrative; composed from the records of Chapters 4 and 20)
id: EBG-NR-0001
use: FPR-NR-0001 # citizen-service assistant, open-weight route
status: active # the stop drill of 2032-12-07 passed
period: monthly
set_by: Henrik Dahl # Head of IT and Digitalisation; not the agent, not the service owner of the assistant
approved_by: Elisabet Holmgren
unit: resolved enquiry
budget:
energy_kwh_per_month: 4450 # GPU servers and host, before facility overhead, 2032 (illustrative)
carbon_g_per_unit: 2.0 # existing target of control FIN-COST-01, SCI method (Chapter 8)
cost_eur_per_month: 18000 # existing monthly budget
quota: # derived once at approval, not recomputed silently
units_per_month: 160650 # 4,450 kWh / 27.7 Wh per unit
derived_with_wh_per_unit: 27.7
conversion: # latest estimate, re-checked each quarter
wh_per_unit: 25.2
measured: 2032-12-14
valid_days: 90
baseline_units_per_month: 146000
basis: "FPR-NR-0001 measured period 2026-10 (aged), 27.7 Wh per resolved enquiry x 146,000 x 1.1 headroom"
measured_by:
energy: provider metering, read by the platform team's scripts (Joakim Wester)
volume: AI gateway counts, outside the assistant
reviewed_by: Astrid Nyberg
stop:
holder: [Henrik Dahl, platform on-call]
path: gateway route switched to the published FAQ page and the phone service
independent_of_assistant: true
last_drill: 2032-12-07 # a first drill on 2032-11-16 failed after 14 minutes
drill_valid_days: 90
drills:
- {date: 2032-11-16, result: fail, minutes: 14}
- {date: 2032-12-07, result: pass, minutes: 6.3}
on_breach:
alert: 0.80 # alert the service owner and the register owner
defer: 1.00 # route deferrable requests to the FAQ page
stop: 1.10 # stop the route; the non-AI path continues
rebound_check: monthly volume against 146,000 (September 2032); a rise of more than 20 per cent is reported to the register owner
rebound_alert_share: 0.20
resolution_floor: 0.80
Example: Hansa Mutual. The cascade budget of the claims assistant is stated at the node boundary on the evaluation set, 0.996 Wh per query. It has an escalation maximum and a quality floor. It is never added to or compared with the whole-serving-path budget EBG-HM-0003 of Chapter 13, which is stated at the rack boundary on the sentinel pool.
# budget/EBG-HM-0002.yaml (illustrative, Hansa Mutual)
id: EBG-HM-0002
use: FPR-HM-0001 # claims assistant; routing policy RP-HM-CLAIMS-2026-02 revision 3
status: active # a stop drill is on record
period: monthly
set_by: rainer-lehmann # group CIO; not the platform owner, not the assistant
reviewed_by: verena-lindner
unit: query answered
budget:
energy_kwh_per_month: 1260 # node boundary, before facility overhead, 2032 (illustrative)
escalation_rate_max: 0.35 # share of queries reaching the large model
quality_floor: 0.96 # correct and cited, on the monthly sample; never traded for energy
basis: "MCR-HM-0001: 0.996 Wh per query at 22 per cent escalation x 1.1 million x 1.15 headroom"
measured_by:
energy: GPU rack meters, Frankfurt (Katja Neumann), attribution by gateway call counts
routes: AI gateway counters, outside the assistant (Jan Berger, showback)
stop:
holders: [anja-weiss, platform-on-call]
path: claims workbench flag switches the assistant off and shows the wording search
independent_of_assistant: true # the flag lives in the claims application, not in the gateway
last_drill: 2032-10-27
drill_valid_days: 90 # valid to 2033-01-25
on_breach:
escalation_0.35: alert the owner and the register owner; no automatic change
escalation_0.50: freeze the router at the last good revision; review before any change
energy_1.00: report to the register owner; the owner decides scope, quality is not lowered
energy_1.15: the owner and the budget setter decide together whether to narrow the use
rebound_check: monthly queries against 1.1 million; a rise above 20 per cent is reported
Check, and the evaluation of a quota. The check refuses an active budget without a drill inside its validity, a stop path that depends on what it stops, thresholds that do not ascend, an escalation limit without a quality floor and a quota that does not follow from the budget. The function evaluate_quota is the one of Chapter 20: from the gateway counts of one day it returns the state (ok, alert, defer, stop), the projected share and whether the budget counts as a cap.
# record_checks.py, part 3: environmental budget (record check and the quota evaluation of Chapter 20)
import calendar
def check_ebg(rec: dict, today: date, index: dict | None = None) -> Result:
p: list[str] = []
n: list[str] = []
stop = rec["stop"]
if not stop["independent_of_assistant"]:
p.append("the stop path is not independent of the system it stops")
last = d(stop["last_drill"])
fresh = last is not None and (today - last).days <= stop["drill_valid_days"]
if rec["status"] == "active" and not fresh:
p.append("status is active without a stop drill inside its validity")
if rec["status"] == "proposed" and not fresh:
n.append("no valid stop drill: the budget is not counted as a cap")
for dr in stop.get("drills", []):
if dr["result"] == "pass" and last is not None and d(dr["date"]) > last:
p.append("a passing drill is later than last_drill")
breach = rec["on_breach"]
steps = [breach[k] for k in ("alert", "defer", "stop") if k in breach]
if steps and steps != sorted(steps):
p.append("breach thresholds are not ascending")
q, conv = rec.get("quota"), rec.get("conversion")
if q and conv:
want = round(rec["budget"]["energy_kwh_per_month"] * 1000 / q["derived_with_wh_per_unit"])
if want != q["units_per_month"]:
p.append(f"quota is {q['units_per_month']}, the budget gives {want}")
if expires(conv["measured"], conv["valid_days"]) < today:
p.append("the conversion factor has expired")
drift = q["units_per_month"] * conv["wh_per_unit"] / 1000 / rec["budget"]["energy_kwh_per_month"] - 1
n.append(f"quota at the latest conversion would use {drift:+.1%} of the energy budget")
b = rec["budget"]
if "escalation_rate_max" in b and "quality_floor" not in b:
p.append("an escalation limit without a quality floor")
return p, n
def evaluate_quota(budget: dict, usage: dict, today: date) -> dict:
"""State of a quota-based budget on one day, from gateway counts (illustrative)."""
quota, conv, stop = budget["quota"], budget["conversion"], budget["stop"]
elapsed = today.day / calendar.monthrange(today.year, today.month)[1]
share = usage["units"] / quota["units_per_month"]
state = "ok"
for name in ("alert", "defer", "stop"): # ascending thresholds
if share >= budget["on_breach"][name]:
state = name
return {
"state": state,
"share_of_quota": round(share, 3),
"projected_share": round(share / elapsed, 3),
"counts_as_cap": (today - d(stop["last_drill"])).days <= stop["drill_valid_days"],
"conversion_expired": (today - d(conv["measured"])).days > conv["valid_days"],
"rebound": usage["units"] / elapsed / budget["baseline_units_per_month"] - 1
> budget["rebound_alert_share"],
"outcome_ok": usage["resolved"] / usage["sessions"] >= budget["resolution_floor"],
}
A.7 The placement policy PLC-*
Owner and question. The platform lead, with a reviewer who reads the meter, answers: where and when may deferrable work run, on which signal, and what may the scheduler never do (Chapter 17)?
Table A.7.1: Fields of the placement policy PLC-*.
| Field | Meaning and rule |
|---|---|
applies_to, classes |
The classes of deferrable work, each with its window or starts, deadline and run time |
signal |
The basis (location-based, hourly, average or marginal), the named source and its maximum age; not used for claims |
regions, space_shift |
The regions a use may run in, with zone, data classes and basin stress; or a flag that the work may not leave its region |
water |
The basin stress above which a region is excluded, and that an unknown value counts as stressed for a move into it |
time_shift, min_saving |
Whether shifting in time is enabled (only after a replay record) and the saving below which the work stays where it is |
floors |
When not to shift: interactive use, special-category data, deadline, a region without a record |
budget, stop |
The budget EBG-*, measured by the facility meter and not the scheduler; the stop path and its drill |
scheduler_may, scheduler_may_not |
What the scheduler may choose, and what it never may: edit the policy, add a region, raise the budget, disable the meter |
Schema.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://aienvironment.example/schemas/plc.schema.json",
"title": "Placement policy (PLC)",
"type": "object",
"required": ["id", "status", "owner", "reviewed_by", "approved_by", "review_by", "applies_to", "signal", "regions", "classes", "budget", "stop", "scheduler_may_not"],
"additionalProperties": false,
"properties": {
"id": {"type": "string", "pattern": "^PLC-(NR|HM)-[0-9]{4}$"},
"status": {"enum": ["proposed", "active", "suspended", "retired"]},
"owner": {"type": "string"},
"reviewed_by": {"type": "array", "items": {"type": "string"}, "minItems": 1},
"approved_by": {"type": "string"},
"review_by": {"type": "string", "format": "date"},
"applies_to": {"type": "array", "items": {"type": "string"}, "minItems": 1},
"signal": {"type": "object", "required": ["basis", "source"]},
"space_shift": {"type": "boolean"},
"regions": {"oneOf": [{"type": "array", "items": {"type": "string"}}, {"type": "object", "minProperties": 1, "additionalProperties": {"type": "object", "required": ["zone", "data_classes"]}}]},
"water": {"type": "object", "required": ["exclude_above_pct", "unknown_counts_as_stressed"]},
"classes": {
"type": "object",
"minProperties": 1,
"additionalProperties": {"type": "object", "required": ["deadline", "runtime_h"]}
},
"time_shift": {"type": "object", "required": ["enabled", "min_saving"]},
"min_saving": {"type": "object", "required": ["relative", "kg_co2e"]},
"floors": {"type": "array", "items": {"type": "string"}, "minItems": 1},
"budget": {"type": "object", "required": ["record", "energy_kwh_per_month", "measured_by"], "properties": {"record": {"type": "string", "pattern": "^EBG-(NR|HM)-[0-9]{4}$"}}},
"stop": {"type": "object", "required": ["holder", "path", "independent_of_scheduler", "last_drill", "drill_valid_days"]},
"scheduler_may": {"type": "array", "items": {"type": "string"}},
"scheduler_may_not": {"type": "array", "items": {"type": "string"}, "minItems": 1}
}
}
Example: Nordvik Region. The Region's contract keeps its work in the European Economic Area with customer-held keys, so space shifting is off, time shifting is off until a replay record shows a saving above the threshold, and the policy stays proposed until the stop path has been drilled.
id: PLC-NR-0001
status: proposed # active once the stop path has a recorded drill
owner: maja-lindqvist # platform lead
reviewed_by: [astrid-nyberg, mats-oberg]
approved_by: henrik-dahl
review_by: "2033-09-30"
applies_to: [nightly_indexing, retraining_quarterly]
signal:
basis: location-based, hourly, average
source: hourly-grid-intensity-service
zone_of_site: { nordvik-dc: SE3, hosting-provider-site: null } # SE3 illustrative; null until disclosed
space_shift: false # floor: contract NR-2026-031 (EEA only, customer-held keys), public procurement, sovereignty
regions: [nordvik-dc, hosting-provider-site] # each use stays where its record says
classes:
nightly_indexing:
window: { earliest_start: "22:00", latest_start: "04:00" }
deadline: "06:30"
runtime_h: 2
retraining_quarterly:
window: { earliest_start: "Fri 18:00", latest_start: "Sun 06:00" }
deadline: "Mon 06:00"
runtime_h: 40
time_shift:
enabled: false # on only after a replay record shows a saving above min_saving
min_saving: { relative: 0.10, kg_co2e: 1.0 }
replay_record: null
budget:
record: EBG-NR-0003
energy_kwh_per_month: 3000 # indexing only, facility boundary, illustrative; retraining is unmetered
measured_by: facility meter of nordvik-dc (Mats Öberg), not the scheduler
stop:
holder: [mats-oberg, platform-on-call]
path: batch queue suspended in cluster admission control; scheduler job credential revoked at the identity provider
independent_of_scheduler: true
last_drill: null
drill_valid_days: 90
scheduler_may_not: [edit_policy, add_region, change_zone, raise_budget, disable_meter]
Example: Hansa Mutual. Three regions are listed with the data classes each may hold. Their basin stress is not yet filled, so a move into any of them is blocked while the home region stays. The policy is proposed, with the budget EBG-HM-0004.
id: PLC-HM-0001
status: proposed # active once the stop path has a recorded drill
owner: anja-weiss # head of the group AI platform
reviewed_by: [katja-neumann, jan-berger, verena-lindner]
approved_by: annette-kraemer # group AI governance board, budgets above the threshold
review_by: "2033-09-30"
applies_to: [evaluation_weekly, fine_tuning, batch_rescoring]
signal:
basis: location-based, hourly, average # a marginal series is not available
source: hourly-grid-intensity-service # named in the supplier record
max_age_hours: 3
not_used_for: [environmental_claims] # claims use Chapter 22 methods
regions: # figures: EEA WEI+ for April to September
hansa-dc-frankfurt: { zone: DE, data_classes: [standard, special_category], wei_plus_apr_sep_pct: null }
cloud-a-ireland: { zone: IE, data_classes: [standard], wei_plus_apr_sep_pct: null }
cloud-b-france: { zone: FR, data_classes: [standard], wei_plus_apr_sep_pct: null }
water:
exclude_above_pct: 20
unknown_counts_as_stressed: true # for moves into a region; the home region stays
classes:
evaluation_weekly:
starts: ["Mon 09:00", "Mon 20:00", "Tue 11:00", "Wed 11:00"] # latest start leaves the run time
deadline: "Thu 12:00"
runtime_h: 6
min_saving: { relative: 0.10, kg_co2e: 50 }
floors: # when not to shift
- interactive or latency-bound use
- special-category data, underwriting model, or any region not listed for the data class
- deadline closer than the run time plus the wait
- saving below min_saving
- a region with no footprint record or supplier disclosure
budget:
record: EBG-HM-0004
energy_kwh_per_month: 9500 # facility boundary, illustrative
measured_by: facility meter, Frankfurt data centre (Katja Neumann), not the scheduler
stop:
holder: [jan-berger, platform-on-call]
path: queue admission quota set to zero in the cluster; credential of the scheduler revoked
independent_of_scheduler: true
last_drill: null
drill_valid_days: 90
scheduler_may: [choose_start, choose_region_within_policy]
scheduler_may_not: [edit_policy, add_region, move_special_category_data, raise_budget, disable_meter]
Check, and the placement function. The check refuses a scheduler that is not forbidden to edit the policy, add a region, raise the budget or disable the meter, time shifting without a replay record, and an active policy without a drill. The function place is the one of Chapter 17; it applies the floors first, then the water condition, then the saving threshold, and returns the region, the start and the reason.
# record_checks.py, part 4: placement policy and the placement function of Chapter 17
MUST_NOT = {"edit_policy", "add_region", "raise_budget", "disable_meter"}
def check_plc(rec: dict, today: date, index: dict | None = None) -> Result:
p: list[str] = []
n: list[str] = []
missing = MUST_NOT - set(rec["scheduler_may_not"])
if missing:
p.append(f"the scheduler is not forbidden to: {', '.join(sorted(missing))}")
stop = rec["stop"]
if not stop["independent_of_scheduler"]:
p.append("the stop path is not independent of the scheduler")
last = d(stop["last_drill"])
fresh = last is not None and (today - last).days <= stop["drill_valid_days"]
if rec["status"] == "active" and not fresh:
p.append("status is active without a stop drill inside its validity")
if rec["status"] == "proposed" and not fresh:
n.append("no valid stop drill: the policy stays proposed")
ts = rec.get("time_shift")
if ts and ts["enabled"] and not ts.get("replay_record"):
p.append("time shifting is enabled without a replay record")
if d(rec["review_by"]) < today:
p.append("the review date has passed")
for name, spec in (rec["regions"].items() if isinstance(rec["regions"], dict) else []):
if spec.get("wei_plus_apr_sep_pct") is None:
n.append(f"region {name}: basin stress unknown: a move into it is blocked")
if "min_saving" in rec and not rec.get("floors"):
p.append("a saving threshold without floors")
return p, n
def place(job: dict, policy: dict, forecast: dict) -> tuple:
"""forecast: {(region, start): g CO2e per kWh}. Returns (region, start, reason)."""
cls = policy["classes"].get(job["class"])
home = job["home"]
if job["interactive"] or cls is None:
return home, None, "floor: interactive or class not listed"
eligible = []
for region, spec in policy["regions"].items():
if job["data_class"] not in spec["data_classes"]:
continue
if region != home:
wei = spec["wei_plus_apr_sep_pct"]
if wei is None and policy["water"]["unknown_counts_as_stressed"]:
continue
if wei is not None and wei > policy["water"]["exclude_above_pct"]:
continue
eligible.append(region)
base = forecast[(home, job["default_start"])]
g, region, start = min((forecast[(r, s)], r, s)
for r in eligible for s in cls["starts"] if (r, s) in forecast)
kg = job["energy_kwh"] * (base - g) / 1000
if kg < policy["min_saving"]["kg_co2e"] or (base - g) / base < policy["min_saving"]["relative"]:
return home, job["default_start"], "floor: saving below threshold"
return region, start, f"saves {kg:.0f} kg CO2e"
A.8 The supplier disclosure record SDR-*
Owner and question. The procurement officer who holds the supplier relation answers: what does the supplier say, at which boundary and year, on which rung of the ladder of Chapter 8, and what is missing and who has asked for it?
Table A.8.1: Fields of the supplier disclosure record SDR-*.
| Field | Meaning and rule |
|---|---|
supplier, holder, received_on, valid_until |
The supplier and contract, the person who holds the record, and the dates |
items |
Each figure with its boundary, year, kind (metered, calculated, estimated, vendor-reported), the check made, the rung 1 to 5 and the date to which it holds |
not_given |
Each item the supplier did not give, the rung the record stands on without it (4 or 5) and the clause or tender item that asks for it |
independent_check |
Whether anyone other than the supplier has checked a figure, and what is requested |
evidence_age |
The limit in days and the events that end validity early: a change of region, hardware pool or method |
group_estimate, asked_via, review |
The buyer's own estimate where the supplier's tool reports a different figure on a different basis; the contract or tender vehicle; the next review |
The rungs are: 1, metered by the supplier on a stated boundary with an independent check; 2, reported by the supplier on a stated boundary without a check; 3, reported on a partial or undefined boundary; 4, estimated by the buyer from parameters or benchmarks; 5, not measured. A figure on rung 3 or lower is kept out of totals.
Schema.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://aienvironment.example/schemas/sdr.schema.json",
"title": "Supplier disclosure record (SDR)",
"type": "object",
"required": ["id", "supplier", "holder", "received_on", "items", "not_given"],
"additionalProperties": false,
"properties": {
"id": {"type": "string", "pattern": "^SDR-(NR|HM)-[0-9]{4}$"},
"supplier": {"type": "string"},
"holder": {"type": "string"},
"received_on": {"type": "string", "format": "date"},
"source_document": {"type": "string"},
"valid_until": {"type": "string", "format": "date"},
"items": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/item"}},
"not_given": {"type": "array", "items": {"$ref": "#/$defs/item"}},
"group_estimate": {"type": "object"},
"asked_via": {"type": "string"},
"independent_check": {"type": "object", "required": ["status"]},
"evidence_age": {"type": "object", "required": ["limit_days"]},
"published_by_region": {"type": "object"},
"review": {"type": "object", "required": ["due", "by"]}
},
"$defs": {
"item": {
"type": "object",
"required": ["item", "rung"],
"properties": {
"item": {"type": "string"},
"boundary": {"type": "string"},
"year": {"type": "integer"},
"basis": {"type": "string"},
"cadence": {"type": "string"},
"kind": {"enum": ["metered", "calculated", "estimated", "vendor-reported"]},
"check": {"type": "string"},
"rung": {"type": "integer", "minimum": 1, "maximum": 5},
"valid_until": {"type": "string", "format": "date"},
"asked_via": {"type": "string"},
"note": {"type": "string"}
}
}
}
}
Example: Nordvik Region, form version 2. The hosting provider's report under the Energy Efficiency Directive gives three site figures for reporting year 2031 on rung 2 and 3, and four items are not given, each asked for in the tender annex TA-NR-ENV-01.
# supplier/SDR-NR-0001.yaml (illustrative; form version 2, 2033-02-14)
# composed: the record-level valid_until is the earliest item date of the form of Chapter 23
id: SDR-NR-0001
supplier: European hosting provider, contract NR-2026-031
holder: ida-pettersson
received_on: 2032-05-15
source_document: provider report under Energy Efficiency Directive Art. 12, reporting year 2031
valid_until: 2033-05-15
items:
- {item: installed IT power, boundary: site, year: 2031, kind: vendor-reported, check: none, rung: 2, valid_until: 2033-05-15}
- {item: PUE, boundary: site, year: 2031, kind: vendor-reported, check: none, rung: 2, valid_until: 2033-05-15}
- {item: total water input, boundary: site, year: 2031, kind: vendor-reported, check: none, rung: 3, valid_until: 2033-05-15,
note: site figure; allocation to customers not stated}
not_given:
- {item: energy per reserved accelerator or per customer, rung: 4, asked_via: TA-NR-ENV-01 D1}
- {item: grid mix and location-based factor of the hall, rung: 4, asked_via: TA-NR-ENV-01 D3}
- {item: embodied footprint of the accelerators, rung: 5, asked_via: TA-NR-ENV-01 D4}
- {item: water by customer, rung: 5, asked_via: TA-NR-ENV-01 D4}
independent_check: {status: none, next: assurance statement requested for D1 in the re-tender}
evidence_age: {limit_days: 365, event_triggers: [region change, hardware pool change, method change]}
published_by_region: {allowed: facility indicators only, basis: publication condition of the contract}
review: {due: 2033-05-01, by: astrid-nyberg}
Example: Hansa Mutual. Cloud A gives an account-level, market-based monthly report on rung 3. The re-scoring batch of about 9,500 accelerator-hours shows the cost of that gap: the tool reports 0.41 tonnes (market-based) against the group's own estimate of 2.2 tonnes (location-based), two figures on two bases that are not compared as if they were one.
# supplier/SDR-HM-0002.yaml (illustrative)
id: SDR-HM-0002
supplier: "Cloud A, EU region (placeholder, Ireland)"
holder: stefan-wiedemann
received_on: 2032-11-08 # the Cloud A answers of the comparison sheet HCS-HM-2032-11, Chapter 19
items:
- {item: account-level carbon report, boundary: account, basis: market-based, cadence: monthly with lag, kind: vendor-reported, rung: 3, note: boundary only partly documented}
not_given:
- {item: energy for accelerator-hours of the burst capacity, rung: 4}
- {item: location-based factor and hourly data for the region, rung: 4}
- {item: water by region and customer, rung: 5}
- {item: notice of hardware or method change, rung: 5}
group_estimate: {item: re-scoring batch, accelerator_hours: 9500, tool_report_t_co2e: 0.41, own_estimate_t_co2e: 2.2, bases: [market-based, location-based], year: 2032}
asked_via: HM-PROC-ENV-02, HM-PROC-ENV-05
valid_until: 2033-11-08
Check. The check refuses an item that stands on rung 1 without an independent check, an item that is vendor-reported but placed on rung 1, a disclosure that is past its age limit, and an item that is not given with nobody asking for it.
# record_checks.py, part 5: supplier disclosure record
def check_sdr(rec: dict, today: date, index: dict | None = None) -> Result:
p: list[str] = []
n: list[str] = []
limit = rec.get("evidence_age", {}).get("limit_days", 365)
if d(rec["received_on"]) + timedelta(days=limit) < today:
p.append(f"the disclosure is older than {limit} days")
if "valid_until" in rec and d(rec["valid_until"]) < today:
p.append("the record has expired")
for it in rec["items"]:
if it.get("valid_until") and d(it["valid_until"]) < today:
p.append(f"item '{it['item']}' has expired")
if it["rung"] == 1 and it.get("check", "none") == "none":
p.append(f"item '{it['item']}' stands on rung 1 without an independent check")
if it.get("kind") == "vendor-reported" and it["rung"] < 2:
p.append(f"item '{it['item']}' is vendor-reported and cannot stand on rung 1")
if it["rung"] >= 3:
n.append(f"item '{it['item']}' is on rung {it['rung']} and is kept out of totals")
for it in rec["not_given"]:
if it["rung"] < 4:
p.append(f"'{it['item']}' is not given but sits above rung 4")
if not (it.get("asked_via") or rec.get("asked_via")):
p.append(f"'{it['item']}' is not given and no clause or tender item asks for it")
ge = rec.get("group_estimate")
if ge and ge["tool_report_t_co2e"] >= ge["own_estimate_t_co2e"]:
n.append("the supplier's tool reports at least as much as the own estimate")
return p, n
A.9 The environmental claim record CLM-*
Owner and question. The person who answers for the statement answers: what may the organisation say, at which boundary, for which period, on what evidence, checked by whom, and approved by which named person? The record is the artefact of Chapter 22, and a statement is not published until it passes.
Table A.9.1: Fields of the environmental claim record CLM-*.
| Field | Meaning and rule |
|---|---|
statement |
The exact words to be published |
claim_kind |
footprint, benefit or commitment; one kind per record |
object, boundary, period, baseline, unit |
The footprint or benefit record the statement rests on, the boundary, the period, the baseline and the unit |
evidence, independent_check |
The kind (measured, estimated, vendor-reported, none), the date and validity; who checked, who did not make the change, and the result |
claimed_by, reviewed_by, approved_for_publication_by |
The claimant, the reviewers (two in both examples) and a named approver; never an agent |
decision, published, withheld, declined_claims |
The AI Decision Record, where it is published and when it must be withdrawn, and what was held back or declined |
comparative_assertion, categories_complete, weighting, critical_review |
Optional. A statement that compares two products or services to the public is a comparative assertion (ISO 14044, as Chapter 22 reads it): it needs all the impact categories, no weighting and a critical review by a panel of at least three with an independent chair. critical_review carries panel_size, chair_independent and the attached statement |
Schema. When approved_for_publication_by has a value, the schema requires the whole record; while it is null, the record may be incomplete and is, for the check, not publishable.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://aienvironment.example/schemas/clm.schema.json",
"title": "Environmental claim record (CLM)",
"type": "object",
"required": ["id", "statement", "claimed_by", "reviewed_by", "approved_for_publication_by"],
"additionalProperties": false,
"if": {"properties": {"approved_for_publication_by": {"type": "string"}}, "required": ["approved_for_publication_by"]},
"then": {"required": ["revision", "claim_kind", "object", "boundary", "period", "evidence", "independent_check", "decision"]},
"properties": {
"id": {"type": "string", "pattern": "^CLM-(NR|HM)-[0-9]{4}$"},
"revision": {"type": "integer", "minimum": 1},
"supersedes": {"type": "object", "required": ["revision", "statement", "status"]},
"statement": {"type": "string", "minLength": 1},
"status": {"enum": ["not-publishable", "approved", "published", "withdrawn"]},
"claim_kind": {"enum": ["footprint", "benefit", "commitment"]},
"object": {"oneOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]},
"boundary": {"type": ["object", "null"]},
"period": {"type": ["string", "null"]},
"baseline": {"type": ["object", "string", "null"]},
"unit": {"type": ["string", "null"]},
"evidence": {"type": "object", "required": ["kind"], "properties": {"kind": {"enum": ["measured", "estimated", "vendor-reported", "none"]}}},
"evidence_valid_until": {"type": ["string", "null"]},
"independent_check": {"type": ["object", "null"]},
"claimed_by": {"type": "string"},
"reviewed_by": {"type": "array", "items": {"type": "string"}, "minItems": 1},
"approved_for_publication_by": {"type": ["string", "null"]},
"decision": {"type": "object", "required": ["record", "approved_on"], "properties": {"record": {"type": "string", "pattern": "^AIDR-13[0-9]{2}$"}}},
"published": {"type": "object"},
"withheld": {"type": "array", "items": {"type": "string"}},
"declined_claims": {"type": "array", "items": {"type": "string"}},
"comparative_assertion": {"type": "boolean"},
"categories_complete": {"type": "boolean"},
"weighting": {"type": "string"},
"critical_review": {"type": "object", "required": ["panel_size", "chair_independent", "statement"],
"properties": {"panel_size": {"type": "integer", "minimum": 0}, "chair_independent": {"type": "boolean"}, "statement": {"type": "string"}}},
"republish_when": {"type": "string"},
"labels": {"type": "array", "items": {"type": "string"}}
}
}
Example: revision 2 of the Hansa Mutual claim. The board's statement of revision 1, that AI work became more efficient, is withheld. What the record supports is narrow: on a metered test pool, IT energy of the accelerator racks per query fell from 3.9 to 2.4 Wh (minus 38 per cent) with answer quality held within the gate. A second run by the person who meters the pool, and who did not make the change, reproduced the readings within 2 per cent. The evidence is valid to 2033-01-26 and the claim is withdrawn if the model or the routing changes.
# claims/CLM-HM-0001.yaml, revision 2 (illustrative; of 2032-12-13)
id: CLM-HM-0001
revision: 2
supersedes: {revision: 1, statement: "AI work at the group became more efficient in the year to August 2032", status: withheld}
statement: >-
In October 2032 the claims assistant used 2.4 Wh of accelerator-rack energy per query on a
metered test pool, against 3.9 Wh before the configuration changes (minus 38 per cent), with
answer quality held within the agreed gate. Production measurement follows.
claim_kind: footprint # footprint | benefit | commitment; one kind per record
object: FPR-HM-0001
boundary: {phase: operation, energy: IT energy of the accelerator racks, before facility overhead,
site: test pool in the Frankfurt data centre, carbon: not claimed}
period: 2032-10
baseline: {what: same pool, same 400 sentinel queries, settings before the change, measured 2032-10}
unit: query
evidence:
kind: measured # measured | estimated | vendor-reported
measured_on: 2032-10-28
valid_days: 90
valid_until: 2033-01-26
independent_check:
by: Katja Neumann # meters the pool; did not make the change
result: second run reproduced the readings within 2 per cent (2032-11-03)
claimed_by: Dorothea Keil
reviewed_by: [Dr. Verena Lindner, Ulf Zimmermann]
approved_for_publication_by: Dr. Annette Krämer # a named person; never an agent
decision: {record: AIDR-1372, approved_on: 2032-12-13}
published: {where: group intranet note and sustainability statement draft, status: approved, withdraw_if: [evidence expires, model or routing changes]}
withheld: [AI work at the group became more efficient]
labels: [illustrative]
Example: a correction at Nordvik Region. A claim record may state what is not known. The 1.90 g figure of October 2026 is withdrawn, because it was measured at another boundary, is more than six years old and excluded the hosted route; two claims are declined; and the record says when the Region may publish again.
# claims/CLM-NR-0001.yaml (illustrative; revision 2 of 2032-12-13)
id: CLM-NR-0001
revision: 2
supersedes:
revision: 1
statement: "The citizen-service assistant uses 1.90 g CO2e per resolved enquiry"
status: withdrawn
reason: figure of 2026-10, other boundary (embodied emissions included), more than six years old, hosted route excluded
statement: >-
The figure of 1.90 g CO2e per resolved enquiry published for October 2026 is withdrawn. The
Region is measuring the assistant again. The explanation route, which uses a hosted model,
has never been measured.
claim_kind: footprint
object: [FPR-NR-0001, FPR-NR-0002]
boundary: {phase: not applicable, carbon: no figure is claimed}
period: 2032-12
evidence:
kind: none # a correction states what is not known
measured_on: null
independent_check: {by: Astrid Nyberg, result: wording checked against FPR-NR-0001 draft and FPR-NR-0002}
claimed_by: Henrik Dahl
reviewed_by: [Astrid Nyberg, Maria Åkesson]
approved_for_publication_by: Elisabet Holmgren
decision: {record: AIDR-1322, approved_on: 2032-12-13}
declined_claims: [energy per enquiry fell since 2026, the assistant is low-carbon]
republish_when: FPR-NR-0001 has an independent check and the hosted route has a figure or a stated gap
labels: [illustrative]
Example of a record that is not publishable: revision 1. The board's statement exists and nothing stands behind it. The record does not say that the statement is false; it says that the statement cannot be published until the empty fields have a value. It passes the schema, because no approver is named, and fails the check.
# claims/CLM-HM-0001.yaml, revision 1 (illustrative): the board's statement, not publishable
id: CLM-HM-0001
statement: "AI work at the group became more efficient in the year to August 2032" # the board's wording
status: not-publishable # until the fields below are filled
claimed_by: Dorothea Keil
boundary: null # operational or lifecycle; location- or market-based; which entities
period: null
baseline: null
unit: null
independent_check: null # who, when, with what result
evidence_valid_until: null # the reporting year at most
reviewed_by: [Dr. Verena Lindner, Ulf Zimmermann]
approved_for_publication_by: null # a named person; never an agent
Check. The check is the one of Chapter 22: it lists the fields that are missing, a claim kind that is not one of three, an approver who is an agent or the only reviewer, an independent check made by the claimant, evidence that has expired and vague or offsetting wording (green, net zero, offset). For a comparative assertion it also lists a missing category set, a weighting, a review panel of fewer than three and a chair who is not independent.
# record_checks.py, part 6: environmental claim record (the check of Chapter 22)
REQUIRED = ["id", "statement", "claim_kind", "object", "boundary", "period",
"evidence", "independent_check", "claimed_by", "reviewed_by",
"approved_for_publication_by"]
VAGUE = ["green", "eco-friendly", "carbon neutral", "climate neutral", "net zero",
"sustainable", "offset"]
def check_clm(rec: dict, today: date, index: dict | None = None) -> Result:
"""Problems that stop publication; an empty list means the record may be published."""
p = [f"missing {k}" for k in REQUIRED if not rec.get(k)]
if rec.get("claim_kind") not in {"footprint", "benefit", "commitment"}:
p.append("claim_kind must be one of footprint, benefit, commitment")
approver = str(rec.get("approved_for_publication_by") or "")
if re.search(r"\b(agent|assistant|bot|AI)\b", approver, re.I):
p.append("approver must be a named person")
if approver and approver in (rec.get("reviewed_by") or []) and len(rec["reviewed_by"]) < 2:
p.append("approver must not also be the only reviewer")
check = rec.get("independent_check") or {}
if check.get("by") and check["by"] == rec.get("claimed_by"):
p.append("the independent check was made by the claimant")
until = (rec.get("evidence") or {}).get("valid_until")
if until and d(until) < today:
p.append(f"evidence expired on {until}")
words = str(rec.get("statement", "")).lower()
p += [f"vague or offset wording: {w}" for w in VAGUE if w in words]
if rec.get("comparative_assertion"):
review = rec.get("critical_review") or {}
if not rec.get("categories_complete"):
p.append("a comparative assertion needs all the impact categories")
if rec.get("weighting", "none") != "none":
p.append("a comparative assertion must not weight the categories into one score")
if review.get("panel_size", 0) < 3 or not review.get("chair_independent"):
p.append("a comparative assertion needs a review panel of at least three with an independent chair")
n = []
if (rec.get("evidence") or {}).get("kind") == "none":
n.append("a correction: the record states what is not known")
return p, n
A.10 The hardware lifecycle record HWL-*
Owner and question. The platform owner, with the person who meters and can stop the racks, answers: what is the hardware's life and use, what do the options cost over a year at one boundary, and what happens at the end (Chapter 16)? A second form carries the clauses that a buyer of reserved capacity asks the supplier to accept.
Table A.10.1: Fields of the hardware lifecycle record HWL-*.
| Field | Meaning and rule |
|---|---|
kind |
inventory for hardware the organisation owns, clause_set for capacity it reserves |
created, valid_until |
The record is valid for 90 days from the measured utilisation |
inventory, utilisation, energy |
Servers, accelerators, install date and planned life; measured and target utilisation with an alert floor; facility energy and the grid factor |
embodied |
A status (lower_bound or better) and what it leaves out; a lower bound states its exclusions and its stress multiplier |
options, decision |
The options with their servers, facility energy and tonnes a year at the same boundary, and the one chosen with its AI Decision Record |
end_of_life |
The route, the erasure certificate and what is reported |
reservation, need_at_target, clauses_requested |
For a clause set: the reservation and its measured utilisation, the quantity needed at the target and the clauses asked for |
Schema.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://aienvironment.example/schemas/hwl.schema.json",
"title": "Hardware lifecycle record (HWL)",
"type": "object",
"required": ["id", "kind", "owner", "reviewer", "created", "valid_until"],
"additionalProperties": false,
"properties": {
"id": {"type": "string", "pattern": "^HWL-(NR|HM)-[0-9]{4}$"},
"kind": {"enum": ["inventory", "clause_set"]},
"pool": {"type": "string"},
"supplier": {"type": "string"},
"owner": {"type": "string"},
"facility_owner": {"type": "string"},
"reviewer": {"type": "string"},
"created": {"type": "string", "format": "date"},
"valid_until": {"type": "string", "format": "date"},
"inventory": {"type": "object", "required": ["servers", "accelerators", "installed", "planned_life_years"]},
"utilisation": {"type": "object", "required": ["measured", "target"]},
"energy": {"type": "object"},
"embodied": {"type": "object", "required": ["status"]},
"options": {"type": "array", "items": {"type": "object", "required": ["id", "what", "servers", "facility_mwh", "tco2e_year"]}},
"decision": {"type": "object", "required": ["aidr", "chosen", "date"]},
"stop_path": {"type": "object"},
"end_of_life": {"type": "object"},
"reservation": {"type": "object", "required": ["accelerators", "measured_utilisation", "target"]},
"need_at_target": {"type": "integer", "minimum": 0},
"clauses_requested": {"type": "array", "minItems": 1},
"status": {"type": "object"},
"fallback": {"type": "string"}
},
"allOf": [
{"if": {"properties": {"kind": {"const": "inventory"}}}, "then": {"required": ["inventory", "utilisation", "energy", "embodied", "options", "decision"]}},
{"if": {"properties": {"kind": {"const": "clause_set"}}}, "then": {"required": ["supplier", "reservation", "need_at_target", "clauses_requested"]}}
]
}
Example: the Frankfurt pool at Hansa Mutual. Twelve servers at 52 per cent utilisation. Consolidating to nine and releasing three (option B) saves about 41 tonnes a year at the same boundary (116 MWh at 350 g/kWh; the rounded figures of the record differ by 40), and the pool is benchmarked before any purchase of new hardware (options C and D), whose embodied impact of 13.7 and 10.3 tonnes is counted once.
# HWL-HM-0001: Frankfurt GPU pool (illustrative figures)
id: HWL-HM-0001
kind: inventory
pool: hansa-dc-frankfurt/gpu-platform
owner: anja-weiss # platform owner
facility_owner: katja-neumann # meters and can stop the racks
reviewer: verena-lindner
created: 2032-11-08
valid_until: 2033-02-06 # 90 days: measured utilisation
inventory: {servers: 12, accelerators: 96, installed: 2029-03, planned_life_years: 5}
utilisation:
measured: 0.52 # period 2032-09, rack meters and gateway share
target: 0.70
floor_alert: 0.45
energy:
facility_mwh_per_year: 826 # modelled: PUE 1.38, whole facility
location_based_g_per_kwh: 350
embodied:
status: lower_bound
baseboard_kg_per_server: 1312 # vendor PCF, cradle-to-gate (NVIDIA, 2025)
host_kg_per_server: 600 # assumption; proxy from a general-purpose server LCA
excluded: [network, rack, building]
stress_multiplier: 3
options:
- {id: A, what: keep 12 servers, servers: 12, facility_mwh: 826, tco2e_year: 289}
- {id: B, what: consolidate to 9, release 3, servers: 9, facility_mwh: 710, tco2e_year: 249}
- {id: C, what: replace with 4 new, servers: 4, facility_mwh: 365, tco2e_year: 128, new_embodied_t: 13.7}
- {id: D, what: 3 new for heavy, 3 old for light, servers: 6, facility_mwh: 489, tco2e_year: 171, new_embodied_t: 10.3}
decision: {aidr: AIDR-1366, chosen: B, then: benchmark-before-C-or-D, date: 2032-11-22}
stop_path: {who: katja-neumann, how: facility power control, outside_the_agent: true}
end_of_life: {route: remarket-then-recycle, erasure_certificate: required, report: [reused_share, recycled_share, destination]}
Example: reserved accelerators at Nordvik Region. The Region reserves 24 accelerators and uses 58 per cent of them. At the target of 70 per cent it needs 20. The clause set asks for a partial release at renewal, among other things, and the supplier has not yet answered.
# HWL-NR-0001: reserved accelerators, contract NR-2026-031 (illustrative figures)
id: HWL-NR-0001
kind: clause_set
supplier: reserved-accelerators-hosting-provider
owner: ida-pettersson # procurement manager
reviewer: astrid-nyberg
created: 2032-11-15
valid_until: 2033-02-13
reservation: {accelerators: 24, measured_utilisation: 0.58, period: 2032-Q3, target: 0.70}
need_at_target: 20 # 24 x 0.58 / 0.70, rounded up
clauses_requested:
- release_unit: partial release of reserved accelerators at renewal
- generation_and_age: generation and install date per reservation
- utilisation_report: monthly, ISO/IEC 30134-5 definition, per customer pool
- refresh_policy: notice and evidence before hardware is replaced
- end_of_life: re-use share, recycling share, destination, erasure certificate
- annex_vii: facility data yearly, with per-customer energy where metered
status: {sent: 2032-11-15, answered: null}
fallback: rung 3, estimate from invoiced hours and assumed draw (Chapter 8)
Check. The check recomputes the tonnes a year of each option from its facility energy and the grid factor, the quantity needed at the target, and the dates, and refuses an embodied lower bound that does not say what it leaves out and an end of life without an erasure certificate.
# record_checks.py, part 7: hardware lifecycle record
def check_hwl(rec: dict, today: date, index: dict | None = None) -> Result:
p: list[str] = []
n: list[str] = []
if d(rec["valid_until"]) < today:
p.append("the record has expired")
if (d(rec["valid_until"]) - d(rec["created"])).days > 90:
p.append("a measured utilisation is valid for 90 days at most")
if rec["kind"] == "inventory":
g = rec["energy"]["location_based_g_per_kwh"]
for o in rec["options"]:
if abs(o["facility_mwh"] * g / 1000 - o["tco2e_year"]) > 1.0:
p.append(f"option {o['id']}: {o['tco2e_year']} t is not {o['facility_mwh']} MWh x {g} g/kWh")
if "new_embodied_t" in o:
n.append(f"option {o['id']}: {o['new_embodied_t']} t of embodied impact is counted once, not per year")
chosen = [o for o in rec["options"] if o["id"] == rec["decision"]["chosen"]]
if not chosen:
p.append("the decision names an option that is not listed")
if rec["utilisation"]["measured"] < rec["utilisation"]["floor_alert"]:
n.append("utilisation is below the alert floor")
if rec["embodied"]["status"] == "lower_bound" and not rec["embodied"].get("excluded"):
p.append("an embodied lower bound that does not say what it leaves out")
if not rec["end_of_life"].get("erasure_certificate"):
p.append("no erasure certificate at end of life")
else:
r = rec["reservation"]
need = math.ceil(r["accelerators"] * r["measured_utilisation"] / r["target"])
if need != rec["need_at_target"]:
p.append(f"need at target is {need}, the record says {rec['need_at_target']}")
if rec["status"]["answered"] is None:
n.append("the supplier has not answered the request")
return p, n
A.11 The mandate manifest MND-*-ENV-*
Owner and question. The owner of the agent, with a person who sets its limits, answers: what may this agent spend, who can stop it, and what is it never allowed to do (Chapter 15)? The budget is set by someone else and measured outside the agent; the agent sees only allow or deny.
Table A.11.1: Fields of the mandate manifest MND-*-ENV-*.
| Field | Meaning and rule |
|---|---|
agent, service, decision, operational_mandate |
The agent, its service, the AI Decision Record and the operational mandate it extends |
status |
proposed until a stop drill has passed; then active |
resource |
Who set the limits (never the agent); the limits per call, run or session, day and month; the paired outcome that stops the budget being met by handing work to people |
measured_by |
The gateway, the inference server and the meters, all outside the agent |
delegation, never_level_4 |
The highest degree of delegation per class of action (0 to 3), and the four things for which Level 4 is never used |
stop |
The path or paths, the holders (none of them the agent), the target minutes and the drills |
Schema.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://aienvironment.example/schemas/mnd.schema.json",
"title": "Mandate manifest for an environmental agent (MND)",
"type": "object",
"required": [
"id",
"agent",
"decision",
"status",
"resource",
"measured_by",
"stop"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^MND-(NR|HM)-ENV-[0-9]{4}$"
},
"agent": {
"type": "string"
},
"service": {
"type": "string"
},
"operational_mandate": {
"type": "string"
},
"decision": {
"type": "string",
"pattern": "^AIDR-13[0-9]{2}$"
},
"footprint": {
"type": "string",
"pattern": "^FPR-(NR|HM)-[0-9]{4}$"
},
"status": {
"enum": [
"proposed",
"active",
"suspended",
"retired"
]
},
"resource": {
"type": "object",
"required": [
"set_by"
],
"properties": {
"set_by": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
}
]
},
"approved_by": {
"type": "string"
},
"budget_view": {
"type": "string",
"pattern": "^EBG-(NR|HM)-[0-9]{4}$"
},
"basis": {
"type": "string"
},
"boundary": {
"type": "object"
},
"per_run": {
"type": "object"
},
"per_session": {
"type": "object"
},
"per_day": {
"type": "object"
},
"per_month": {
"type": "object"
},
"per_month_team": {
"type": "object"
},
"burst_cloud_a": {
"type": "object"
},
"paired_outcome": {
"type": "object"
},
"background_or_scheduled_work": {
"type": "string"
}
},
"anyOf": [
{
"required": [
"per_run"
]
},
{
"required": [
"per_session"
]
}
]
},
"measured_by": {
"type": "object",
"minProperties": 1
},
"reporting": {
"type": "string"
},
"delegation": {
"type": "object",
"additionalProperties": {
"type": "integer",
"minimum": 0,
"maximum": 3
}
},
"never_level_4": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"stop": {
"type": "object",
"required": [
"path",
"holders"
],
"properties": {
"path": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"holders": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"target_minutes": {
"type": "number",
"exclusiveMinimum": 0
},
"last_drill": {
"type": [
"string",
"null"
],
"format": "date"
},
"drill_valid_days": {
"type": "integer",
"minimum": 1
},
"drills": {
"type": "array",
"items": {
"type": "object",
"required": [
"date",
"result"
]
}
}
}
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
Example: the claims-triage agent at Hansa Mutual (Mode 5). Per run: 18 model calls, 25 tool calls, 120 seconds and about 7.0 Wh (about three times the central 2.3 Wh of the bottom-up footprint); per day 13 kWh; per month 390 kWh at facility level; a volume report above 168,000 claims. The agent has Level 3 only for starting a run on a registered event and for retrying inside the run limit, and Level 0 for spawning sub-agents, background work, provisioning or scaling compute, changing its own limits, meter, credential or stop, and publishing a claim. The first drill, on 2032-11-15, failed in 11 minutes because the burst route in Cloud A used a provider-held key outside the gateway; the second, on 2032-11-29, passed in 2.2 minutes against a target of 5.
id: MND-HM-ENV-0001 # illustrative, Hansa Mutual
agent: claims-triage-agent
service: SVC-HM-002 # Mode 5
operational_mandate: AIDR-0034
decision: AIDR-1365 # 2032-11-08; owner anja.weiss
status: active # after the passing drill of 2032-11-29
resource:
set_by: [anja.weiss, verena.lindner] # not the agent; approved by the group AI governance board
budget_view: EBG-HM-0001
boundary: {scope: operational, included: [accelerators, host share, facility], carbon: location-based, grid_g_per_kwh: 350, pue: 1.38, year: 2032}
per_run:
model_calls: 18
tool_calls: 25
wall_s: 120
energy_wh: 7.0 # about 3 x the central 2.3 Wh; estimated at the gateway from metered accelerator seconds
on_breach: stop the run, route the claim to a handler, no retry by the agent
per_day: {energy_kwh: 13, soft_at: 0.8, on_hard: revoke the credential}
per_month: {energy_kwh: 390, claims_report_above: 168000} # 1.2 x September volume
burst_cloud_a: {share_max: 0.10, counted_by: gateway calls, energy: estimated at 0.22 Wh per call, confidence: low}
paired_outcome: {energy_wh_per_claim_mean_max: 3.0, handler_share_max: 0.08} # 0.08 provisional, from baseline
measured_by:
calls_and_tokens: AI gateway
accelerator_seconds: inference server on the Frankfurt platform
rack_energy: PDU meters (katja.neumann), reconciled monthly (jan.berger)
delegation: # ceiling of DLG-HM-ENV-0001
start_run_on_registered_event: 3
retry_inside_per_run_limit: 3
spawn_sub_agent: 0
schedule_or_background_work: 0
provision_or_scale_compute: 0
change_own_limits_meter_credential_or_stop: 0
publish_environmental_claim: 0
never_level_4: [provision or scale beyond budget, disable measurement or stop, publish a claim, decide about a named person's access to work]
stop:
path: [gateway identity service (revoke credential, close burst route), claims core routing flag (manual routing)]
holders: [anja.weiss, sre-on-call, claims-duty-manager] # none of them is the agent
target_minutes: 5
drills:
- {date: 2032-11-15, result: fail, minutes: 11, finding: burst route in Cloud A used a provider-held key outside the gateway}
- {date: 2032-11-29, result: pass, minutes: 2.2, valid_until: 2033-02-27}
labels: [illustrative]
Example: the platform team's agentic work tools at Nordvik Region (Mode 3). The budget is in proxies (calls, tokens and sandbox time), because no energy figure exists until FPR-NR-0008 does. Reporting is by team and use only. No drill is recorded, so the mandate is proposed and the budget is not a cap.
id: MND-NR-ENV-0001 # illustrative, Nordvik Region
agent: platform-agentic-work-tools # Mode 3, platform team only (seven engineers)
decision: AIDR-1315 # 2032-11-02
footprint: FPR-NR-0008 # allocated here; not yet measured, measurement plan per Chapter 8
status: proposed # becomes active when the stop path has been drilled
resource:
set_by: henrik.dahl # not the agent and not the platform team that uses it
approved_by: elisabet.holmgren
basis: proxies # calls, tokens and sandbox time; no energy figure until FPR-NR-0008 exists
per_session:
model_calls: 80
tool_calls: 150
wall_minutes: 45
input_tokens: 1500000
on_breach: halt the session and report to the engineer who started it
per_month_team: {sessions: 800, input_tokens: 60000000, alerts: [0.5, 0.8, 0.95], hard: 1.10}
background_or_scheduled_work: not delegated
measured_by:
calls_and_tokens: AI gateway, read by joakim.wester
sandbox_time: sandbox host logs
reviewed_by: astrid.nyberg
reporting: by team and use only # no per-person meter; MBL-NR-IT-2027-01 applies before any is switched on
stop:
path: [gateway key revocation, sandbox host job kill]
holders: [maja.lindqvist, platform-on-call, henrik.dahl]
last_drill: null # planned for 2032-11-22; until a drill is recorded the budget is not a cap
drill_valid_days: 90
labels: [illustrative]
Check. The check refuses a mandate whose limits are set by the agent, a delegation above Level 0 for provisioning or scaling compute, changing its own limits, meter, credential or stop, or publishing a claim, a never_level_4 list that leaves one of the four out, a stop holder that is the agent, and an active mandate without a passing drill inside its validity and its target time.
# record_checks.py, part 8: mandate manifest of an environmental agent
ZERO = ["provision_or_scale_compute", "change_own_limits_meter_credential_or_stop", "publish_environmental_claim"]
NEVER = ["provision", "measurement", "claim", "named person"]
def check_mnd(rec: dict, today: date, index: dict | None = None) -> Result:
p: list[str] = []
n: list[str] = []
res = rec["resource"]
set_by = res["set_by"] if isinstance(res["set_by"], list) else [res["set_by"]]
if any("agent" in s.lower() for s in set_by):
p.append("the limits are set by the agent")
deleg = rec.get("delegation")
if deleg:
for k in ZERO:
if deleg.get(k, 0) != 0:
p.append(f"{k} is delegated at Level {deleg[k]}; the ceiling is 0")
if rec.get("never_level_4"):
text = " ".join(rec["never_level_4"]).lower()
p += [f"never_level_4 does not name '{w}'" for w in NEVER if w not in text]
stop = rec["stop"]
if rec["agent"] in stop["holders"]:
p.append("a stop holder is the agent")
drills = stop.get("drills", [])
if not drills and stop.get("last_drill"):
drills = [{"date": stop["last_drill"], "result": "pass", "minutes": 0,
"valid_until": expires(stop["last_drill"], stop["drill_valid_days"])}]
passing = [x for x in drills if x["result"] == "pass" and d(x["valid_until"]) >= today]
if rec["status"] == "active":
if not passing:
p.append("status is active without a passing stop drill inside its validity")
elif "target_minutes" in stop and passing[-1]["minutes"] > stop["target_minutes"]:
p.append("the passing drill took longer than the target")
elif not passing:
n.append("no passing stop drill: the budget is not counted as a cap")
for x in drills:
if x["result"] == "pass" and "valid_until" in x and expires(x["date"], 90) != d(x["valid_until"]):
p.append(f"drill of {x['date']}: valid_until is not 90 days later")
if res.get("per_month_team") and "alerts" in res["per_month_team"]:
a = res["per_month_team"]["alerts"]
if a != sorted(a) or a[-1] >= res["per_month_team"]["hard"]:
p.append("team alerts are not ascending below the hard limit")
return p, n
The gateway. The limits of the manifest are enforced by code that the agent cannot edit. The class below holds the counters and the credential. admit is called before every model or tool call and returns allow or deny; record is called with the accelerator seconds that the inference server measured, not with anything the agent reports; at the day limit the credential is revoked through the gateway identity service, which is the stop path. A run that is refused is routed to a person, and the agent does not retry. The figures are those of MND-HM-ENV-0001.
# gateway.py: budget enforcement at the gateway, outside the agent (illustrative, Hansa Mutual)
from dataclasses import dataclass
import time
WH_PER_ACCEL_S = 650 * 1.38 / 3600 # draw x PUE, from FPR-HM-0002 (illustrative)
@dataclass(frozen=True)
class Limits:
model_calls: int = 18 # per run
tool_calls: int = 25 # per run
wall_s: float = 120.0 # per run
run_wh: float = 7.0 # per run, estimated from metered accelerator seconds
day_wh: float = 13_000.0 # per day, per credential
class Gateway:
"""Holds the counters and the credential; the agent sees only allow or deny."""
def __init__(self, limits, revoke, to_manual, clock=time.monotonic):
self.lim, self.revoke, self.to_manual, self.clock = limits, revoke, to_manual, clock
self.runs, self.day_wh, self.revoked = {}, 0.0, False
def admit(self, run_id, kind):
"""Called before a model or tool call is forwarded. Returns (allowed, reason)."""
if self.revoked:
return False, "credential revoked"
r = self.runs.setdefault(run_id, {"t0": self.clock(), "model": 0, "tool": 0, "wh": 0.0})
reason = None
if self.clock() - r["t0"] > self.lim.wall_s:
reason = "run wall clock"
elif kind == "model" and r["model"] >= self.lim.model_calls:
reason = "run model calls"
elif kind == "tool" and r["tool"] >= self.lim.tool_calls:
reason = "run tool calls"
elif r["wh"] >= self.lim.run_wh:
reason = "run energy"
if reason:
self.to_manual(run_id) # the claim goes to a person; the agent does not retry
return False, reason
r[kind] += 1
return True, "ok"
def record(self, run_id, accel_s):
"""Called with accelerator seconds measured by the inference server, not by the agent."""
wh = accel_s * WH_PER_ACCEL_S
self.runs[run_id]["wh"] += wh
self.day_wh += wh
if self.day_wh >= self.lim.day_wh and not self.revoked:
self.revoked = True
self.revoke() # stop path: the gateway identity service
A.12 The runbook manifest RBK-*
Owner and question. The owner unit answers: when the budget of a use is reached, what happens, automatically and by whom, and what is the fallback while the use is stopped (Chapter 20)?
Table A.12.1: Fields of the runbook manifest RBK-*.
| Field | Meaning and rule |
|---|---|
service, budget, decision_record |
The service, its budget and the AI Decision Record that adopted the runbook |
trigger |
The signal (quota_share or projected_share), the threshold and the action: alert, defer or stop |
delegation |
The delegation profile, the actions that run automatically at the gateway and what the assistant may do (nothing) |
steps |
Detect, stop, assess, restart (by a named person, after the cause is recorded) and review |
fallback, verification |
The non-AI path and when it is staffed; the meters outside the assistant |
stop |
The holders, the path, that it is independent, and the last drill with its minutes against its target |
Schema.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://aienvironment.example/schemas/rbk.schema.json",
"title": "Runbook manifest for an environmental budget breach (RBK)",
"type": "object",
"required": ["runbook", "title", "version", "service", "budget", "owner_unit", "accountable", "decision_record", "trigger", "delegation", "steps", "fallback", "verification", "stop", "review"],
"additionalProperties": false,
"properties": {
"runbook": {"type": "string", "pattern": "^RBK-(NR|HM)-ENV-[0-9]{3}$"},
"title": {"type": "string"},
"version": {"type": "integer", "minimum": 1},
"service": {"type": "string", "pattern": "^SVC-(NR|HM)-[0-9]{3}$"},
"budget": {"type": "string", "pattern": "^EBG-(NR|HM)-[0-9]{4}$"},
"owner_unit": {"type": "string"},
"accountable": {"type": "string"},
"decision_record": {"type": "string", "pattern": "^AIDR-13[0-9]{2}$"},
"trigger": {
"type": "array", "minItems": 1,
"items": {"type": "object", "required": ["signal", "at", "action"], "properties": {"signal": {"enum": ["quota_share", "projected_share"]}, "at": {"type": "number", "exclusiveMinimum": 0}, "action": {"enum": ["alert", "defer", "stop"]}}}
},
"delegation": {
"type": "object",
"required": ["profile", "automatic_actions", "assistant_may"],
"properties": {"profile": {"type": "string", "pattern": "^DLG-(NR|HM)-ENV-[0-9]{4}$"}, "automatic_actions": {"type": "array", "items": {"enum": ["alert", "defer", "stop"]}}, "assistant_may": {"type": "array"}}
},
"steps": {"type": "object", "required": ["detect", "stop", "assess", "restart", "review"]},
"fallback": {"type": "object", "required": ["path", "staffed"]},
"verification": {"type": "object", "required": ["meter", "volume"]},
"stop": {
"type": "object",
"required": ["held_by", "path", "independent_of_assistant", "drill"],
"properties": {"drill": {"type": "object", "required": ["last", "result_minutes", "target_minutes", "valid_days"]}}
},
"review": {"type": "object", "required": ["due", "approved_by"]}
}
}
Example: the quota breach at Nordvik Region. The runbook is the one the January 2033 breach tested. The thresholds are those of EBG-NR-0001: alert at 0.80, defer at 1.00, stop at 1.10.
# runbook/RBK-NR-ENV-001.yaml (illustrative)
runbook: RBK-NR-ENV-001
title: Environmental budget breach on the citizen-service assistant
version: 1
service: SVC-NR-005
budget: EBG-NR-0001
owner_unit: Platform team, Nordvik Region
accountable: Maja Lindqvist # platform lead; register owner is Henrik Dahl
decision_record: AIDR-1320
trigger:
- {signal: quota_share, at: 0.80, action: alert}
- {signal: quota_share, at: 1.00, action: defer}
- {signal: quota_share, at: 1.10, action: stop}
- {signal: projected_share, at: 1.25, action: alert, note: early warning from day 7}
delegation:
profile: DLG-NR-ENV-0001
automatic_actions: [alert, defer, stop] # enforced by the AI gateway, not by the assistant
assistant_may: [] # the assistant cannot change the quota, meter or route
steps:
detect: "Gateway raises the alert; on-call opens an incident record INC-NR-*"
stop: "Confirm the gateway has switched the route; if not, switch it by hand (stop path STOP-NR-ENV-01)"
assess: "Cause: volume, energy per unit, meter fault, retry or loop, or rebound; check the non-AI path is staffed"
restart: "Only by Henrik Dahl or the platform lead, after the cause is recorded; at the next period or on a new decision"
review: "Post-incident review PIR-* within 5 working days; update register row and budget"
fallback: {path: published FAQ page and phone service, staffed: "07:00-17:00 working days"}
verification:
meter: provider metering read by Joakim Wester's scripts # outside the assistant
volume: AI gateway counts
stop:
held_by: [Henrik Dahl, platform on-call]
path: STOP-NR-ENV-01
independent_of_assistant: true
drill: {last: 2032-12-07, result_minutes: 6.3, target_minutes: 10, valid_days: 90}
review: {due: 2033-03-07, approved_by: Henrik Dahl}
Check. The check refuses triggers that do not ascend through alert, defer and stop, a trigger whose action is not delegated, an assistant that may act on its own budget, a stop that depends on the assistant, a drill that took longer than its target, and thresholds that differ from the budget they serve.
# record_checks.py, part 9: runbook manifest
def check_rbk(rec: dict, today: date, index: dict | None = None) -> Result:
p: list[str] = []
n: list[str] = []
quota = [t for t in rec["trigger"] if t["signal"] == "quota_share"]
if [t["at"] for t in quota] != sorted(t["at"] for t in quota):
p.append("quota triggers are not in ascending order")
if [t["action"] for t in quota] != ["alert", "defer", "stop"][:len(quota)]:
p.append("quota triggers do not run alert, defer, stop")
if not set(t["action"] for t in rec["trigger"]) <= set(rec["delegation"]["automatic_actions"]):
p.append("a trigger uses an action that is not delegated")
if rec["delegation"]["assistant_may"]:
p.append("the assistant may act on its own budget")
s = rec["stop"]
dr = s["drill"]
if not s["independent_of_assistant"]:
p.append("the stop path is not independent of the assistant")
if dr["result_minutes"] > dr["target_minutes"]:
p.append("the last drill took longer than the target")
if expires(dr["last"], dr["valid_days"]) < today:
p.append("the stop drill has expired")
if index:
budget = index.get((rec["budget"], None))
if budget:
for t in quota:
if budget["on_breach"][t["action"]] != t["at"]:
p.append(f"{t['action']} at {t['at']} differs from {rec['budget']}")
if budget["stop"]["last_drill"] != dr["last"]:
p.append("the drill differs from the budget's last drill")
if d(rec["review"]["due"]) < today:
p.append("the runbook review is overdue")
return p, n
A.13 The environmental register and the scale-up decision
Owner and question. The register owner answers: which uses exist, who owns each, which evidence stands behind each, how old it is and which decision was taken. The register has one row per AI use. A use is complete when every kind of evidence is valid and all three tests (Count, Compare and Cap) are pass. Where the organisation runs an environmental management system, a row may also carry significance (the documented criteria, the result, the date and the person), which turns the register into the aspects register of that system (Chapter 24, Table 24.10). A scale-up, a renewal or a new use is a gate: with three tests passed the register owner decides, and with a test open or failed the regional AI board or the group AI governance board decides (Chapter 24).
Schema of the register.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://aienvironment.example/schemas/register.schema.json",
"title": "Environmental register (one file per organisation)",
"type": "object",
"required": ["register", "organisation", "register_owner", "as_of", "limits_days", "uses"],
"additionalProperties": false,
"properties": {
"register": {"type": "string", "pattern": "^environment-(nr|hm)$"},
"organisation": {"enum": ["Nordvik Region", "Hansa Mutual"]},
"register_owner": {"type": "string"},
"as_of": {"type": "string", "format": "date"},
"limits_days": {
"type": "object",
"required": ["footprint", "benefit", "stop_drill"],
"additionalProperties": {"type": "integer", "minimum": 1}
},
"uses": {
"type": "array", "minItems": 1,
"items": {
"type": "object",
"required": ["use", "service", "owner", "evidence", "tests", "decision", "claim"],
"additionalProperties": false,
"properties": {
"use": {"type": "string", "pattern": "^FPR-(NR|HM)-[0-9]{4}$"},
"service": {"type": "string", "pattern": "^SVC-(NR|HM)-[0-9]{3}$"},
"owner": {"type": "string"},
"evidence": {
"type": "object", "minProperties": 1,
"additionalProperties": {
"type": "object", "required": ["record", "measured"],
"properties": {"record": {"type": ["string", "null"]}, "measured": {"type": ["string", "null"], "format": "date"}}
}
},
"tests": {
"type": "object", "required": ["count", "compare", "cap"],
"additionalProperties": {"enum": ["pass", "fail", "open"]}
},
"decision": {"type": "string", "pattern": "^AIDR-13[0-9]{2}$"},
"claim": {"type": ["string", "null"]},
"significance": {
"type": "object", "required": ["criteria", "result", "decided", "by"],
"properties": {"criteria": {"type": "string"}, "result": {"enum": ["significant", "not_significant"]}, "decided": {"type": "string", "format": "date"}, "by": {"type": "string"}}
}
}
}
}
}
}
Example: Nordvik Region. The citizen-service assistant has a valid record of every kind and three passed tests. The staff assistant has no record at all, and its three tests are open.
# register/environment-nr.yaml (extract; illustrative)
register: environment-nr
organisation: Nordvik Region
register_owner: Henrik Dahl
as_of: 2032-12-13
limits_days: {footprint: 90, benefit: 180, stop_drill: 90, supplier: 365, hardware: 90}
uses:
- use: FPR-NR-0001
service: SVC-NR-005
owner: Sara Ekdahl
evidence:
footprint: {record: FPR-NR-0001, measured: 2032-10-04}
benefit: {record: BEN-NR-0001, measured: 2032-11-08} # for a benefit record the clock starts at the decision date
stop_drill: {record: EBG-NR-0001, measured: 2032-12-07}
supplier: {record: SDR-NR-0001, measured: 2032-05-15}
hardware: {record: HWL-NR-0001, measured: 2032-11-15}
tests: {count: pass, compare: pass, cap: pass}
decision: AIDR-1309
claim: null
- use: FPR-NR-0003
service: SVC-NR-006
owner: Gunilla Roos
evidence:
footprint: {record: null, measured: null}
benefit: {record: null, measured: null}
stop_drill: {record: null, measured: null}
tests: {count: open, compare: open, cap: open}
decision: AIDR-1326
claim: null
Example: Hansa Mutual. The claims assistant has passed Count and Cap and has no benefit record; the triage agent has a footprint, a benefit record and a drill, and fails Compare. The record of the Hansa Mutual register is composed from the ledger, because Chapter 24 prints the Region's extract only.
# register/environment-hm.yaml (extract; illustrative; composed from the ledger of identifiers)
register: environment-hm
organisation: Hansa Mutual
register_owner: Anja Weiß
as_of: 2032-12-13
limits_days: {footprint: 90, benefit: 180, stop_drill: 90, supplier: 365, hardware: 90}
uses:
- use: FPR-HM-0001
service: SVC-HM-007
owner: Katrin Ohlsen
evidence:
footprint: {record: FPR-HM-0001, measured: 2032-10-18}
benefit: {record: null, measured: null}
stop_drill: {record: EBG-HM-0002, measured: 2032-10-27}
tests: {count: pass, compare: open, cap: pass}
decision: AIDR-1376
claim: CLM-HM-0001
- use: FPR-HM-0002
service: SVC-HM-002
owner: Anja Weiß
evidence:
footprint: {record: FPR-HM-0002, measured: 2032-10-06}
benefit: {record: BEN-HM-0002, measured: 2032-11-15}
stop_drill: {record: EBG-HM-0001, measured: 2032-11-29}
hardware: {record: HWL-HM-0001, measured: 2032-11-08}
tests: {count: pass, compare: fail, cap: pass}
decision: AIDR-1359
claim: null
Schema of the decision at the gate.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://aienvironment.example/schemas/aidr.schema.json",
"title": "AI Decision Record at the scale-up gate (AIDR)",
"type": "object",
"required": ["id", "date", "organisation", "subject", "use", "trigger", "tests", "decision", "conditions", "decided_by", "claim_effect", "review"],
"additionalProperties": false,
"properties": {
"id": {"type": "string", "pattern": "^AIDR-13[0-9]{2}$"},
"date": {"type": "string", "format": "date"},
"organisation": {"enum": ["Nordvik Region", "Hansa Mutual"]},
"subject": {"type": "string"},
"use": {"type": "string", "pattern": "^FPR-(NR|HM)-[0-9]{4}$"},
"trigger": {"enum": ["scale-up", "renewal", "new-use", "breach", "claim"]},
"tests": {
"type": "object", "required": ["count", "compare", "cap"],
"additionalProperties": {"type": "object", "required": ["result", "basis"], "properties": {"result": {"enum": ["pass", "fail", "open"]}}}
},
"decision": {"type": "string"},
"conditions": {"type": "array", "items": {"type": "object", "required": ["what", "by"]}},
"decided_by": {"type": "string"},
"claim_effect": {"type": "string"},
"review": {"type": "string", "format": "date"},
"labels": {"type": "array", "items": {"type": "string"}}
}
}
Example: Nordvik Region, AIDR-1326. The proposal to extend the staff assistant from about 3,200 to about 4,400 users is not approved, because no test is passed. The assistant continues under an interim quota, and each open test has a condition and a date.
# decision/AIDR-1326.yaml (illustrative, Nordvik Region)
id: AIDR-1326
date: 2032-12-13
organisation: Nordvik Region
subject: Proposal to extend the staff assistant from about 3,200 to about 4,400 users
use: FPR-NR-0003 # service SVC-NR-006, Mode 4
trigger: scale-up
tests:
count: {result: open, basis: no footprint record; share of the reserved pool unmetered}
compare: {result: open, basis: adoption claim ADP-NR-2029-01 has no recorded result}
cap: {result: open, basis: no environmental budget; gateway cost counts only}
decision: do not extend; continue at about 3,200 users under an interim gateway quota of 110 per cent of the September 2032 requests
conditions:
- {what: footprint record from a measurement plan like MPL-NR-0001, by: 2033-02-28}
- {what: benefit record from a comparison on a sample of work, not usage, by: 2033-04-29}
- {what: environmental budget with a drilled stop, by: 2033-03-14}
decided_by: regional AI board # tier 3; recorded by Henrik Dahl
claim_effect: none
review: 2033-03-14
labels: [illustrative]
Example: Hansa Mutual, AIDR-1376. The extension of the claims assistant to the UK and Swiss entities passes Count and Cap and has no benefit record. The board approves it inside the budget's volume trigger and refuses growth beyond it, with the benefit record due on 2033-03-31.
# decision/AIDR-1376.yaml (illustrative, Hansa Mutual)
id: AIDR-1376
date: 2032-12-13
organisation: Hansa Mutual
subject: Extension of the claims assistant to the UK and Swiss entities, about 140 further handlers
use: FPR-HM-0001 # service SVC-HM-007, Mode 4
trigger: scale-up
tests:
count: {result: pass, basis: FPR-HM-0001 measured 2032-10-18, node boundary}
compare: {result: open, basis: no benefit record BEN-HM-0001}
cap: {result: pass, basis: EBG-HM-0002, drill 2032-10-27}
decision: approve inside the budget's volume trigger of 1,210,000 queries a month; refuse any growth beyond it
conditions:
- {what: benefit record BEN-HM-0001, owner: head of claims operations, by: 2033-03-31}
- {what: footprint record re-measured and drill repeated, by: 2033-01-16}
decided_by: group AI governance board # tier 3; chair Dr. Annette Krämer
claim_effect: none
review: 2033-01-16
labels: [illustrative]
Checks. evaluate is the function of Chapter 24 that reads the register at its as_of date and reports each row as valid, expired or missing for each kind of evidence, whether the row is complete, and the date by which the earliest expiry should be reviewed (14 days before it). check_aidr refuses a gate with an open test that the register owner decided, and an open test with no condition that closes it.
# record_checks.py, part 10: environmental register and scale-up decision
LEAD_DAYS = 14 # a review falls this long before the earliest expiry
CORE_KINDS = ("footprint", "benefit", "stop_drill") # a row without these is missing them, not exempt
def _state(item: dict, limit: int, today: date):
if item["record"] is None or item["measured"] is None:
return "missing", None
end = expires(item["measured"], limit)
return ("valid" if end >= today else "expired"), end
def evaluate(reg: dict):
"""Yield (use, owner, state by evidence kind, complete, earliest expiries) for each row."""
today = d(reg["as_of"])
for row in reg["uses"]:
found = {kind: _state(row["evidence"].get(kind) or {"record": None, "measured": None}, days, today)
for kind, days in reg["limits_days"].items()
if kind in row["evidence"] or kind in CORE_KINDS}
ages = {kind: s for kind, (s, _) in found.items()}
expiries = sorted((e, k) for k, (s, e) in found.items() if s == "valid")
complete = all(s == "valid" for s in ages.values()) \
and all(t == "pass" for t in row["tests"].values())
yield row["use"], row["owner"], ages, complete, expiries
def check_register(reg: dict, today: date, index: dict | None = None) -> Result:
p: list[str] = []
n: list[str] = []
for use, owner, ages, complete, expiries in evaluate(reg):
due = expiries[0][0] - timedelta(days=LEAD_DAYS) if expiries else None
n.append(f"{use} ({owner}): {'complete' if complete else 'incomplete'}, "
f"{', '.join(f'{k} {v}' for k, v in ages.items())}; review by {due or 'now'}")
row_uses = [r["use"] for r in reg["uses"]]
if len(set(row_uses)) != len(row_uses):
p.append("a use appears twice")
for r in reg["uses"]:
passed = [t == "pass" for t in r["tests"].values()]
if r["claim"] and not all(passed) and r["claim"].startswith("CLM") and r["tests"]["count"] != "pass":
p.append(f"{r['use']}: a claim is attached to a use that has not passed Count")
return p, n
GATE = {"count": ("footprint",), "compare": ("benefit",), "cap": ("budget", "drill")}
def check_aidr(rec: dict, today: date, index: dict | None = None) -> Result:
p: list[str] = []
n: list[str] = []
passed = all(t["result"] == "pass" for t in rec["tests"].values())
if not passed and "board" not in rec["decided_by"]:
p.append("a gate with a test open or failed is decided by the board, not by the register owner")
for test, spec in rec["tests"].items():
if spec["result"] != "pass":
text = " ".join(c["what"] for c in rec["conditions"]).lower()
if not any(w in text for w in GATE[test]):
p.append(f"the {test} test is {spec['result']} and no condition closes it")
if any(d(c["by"]) <= d(rec["date"]) for c in rec["conditions"]):
p.append("a condition falls due on or before the decision")
if d(rec["review"]) < d(rec["date"]):
p.append("the review is before the decision")
return p, n
A.14 The harness and its tests
The harness reads a folder of schemas and a folder of records, validates each record against the schema of its family, and then runs the check of that family. It needs Python 3.12 with PyYAML and jsonschema. The schemas of this appendix are saved as schemas/fpr.schema.json and so on, the records as records/<id>.yaml (a revision of the same identifier gets a suffix; the record of the book, FPR-BK-0001, goes to a folder book/ of its own), and the checks of A.3 to A.13, in order, as record_checks.py. The gateway of A.11 is saved as gateway.py.
#!/usr/bin/env python3
"""validate_records.py: validate every record file against its JSON Schema, then run its check.
python3 validate_records.py SCHEMA_DIR RECORD_DIR [--today YYYY-MM-DD]
Needs PyYAML and jsonschema. Exit status 1 if any record fails; a note never fails a record.
"""
import argparse
import json
import sys
from pathlib import Path
import yaml
from jsonschema import Draft202012Validator, FormatChecker
from record_checks import (check_aidr, check_ben, check_clm, check_ebg, check_fpr, check_hwl,
check_mnd, check_plc, check_rbk, check_register, check_sdr, d)
SCHEMA = {"FPR": "fpr", "BEN": "ben", "EBG": "ebg", "PLC": "plc", "SDR": "sdr", "CLM": "clm",
"HWL": "hwl", "MND": "mnd", "AIDR": "aidr"}
CHECK = {"fpr": check_fpr, "ben": check_ben, "ebg": check_ebg, "plc": check_plc, "sdr": check_sdr,
"clm": check_clm, "hwl": check_hwl, "mnd": check_mnd, "rbk": check_rbk,
"register": check_register, "aidr": check_aidr}
def kind_of(rec: dict) -> str:
if "register" in rec:
return "register"
if "runbook" in rec:
return "rbk"
return SCHEMA[rec["id"].split("-")[0]]
def key_of(rec: dict):
return (rec.get("id") or rec.get("runbook") or rec["register"], rec.get("revision"))
def as_json(x):
return json.loads(json.dumps(x, default=lambda v: v.isoformat()))
def main(argv=None) -> int:
ap = argparse.ArgumentParser()
ap.add_argument("schemas", type=Path)
ap.add_argument("records", type=Path)
ap.add_argument("--today", default="2032-12-13")
args = ap.parse_args(argv)
today = d(args.today)
validators = {p.name.split(".")[0]: Draft202012Validator(json.loads(p.read_text()), format_checker=FormatChecker())
for p in args.schemas.glob("*.schema.json")}
records = {}
for path in sorted(args.records.glob("*.yaml")):
for rec in yaml.safe_load_all(path.read_text(encoding="utf-8")):
records[key_of(rec)] = (path.name, rec)
index = {k: rec for k, (_, rec) in records.items()}
failed = 0
for key, (name, rec) in records.items():
kind = kind_of(rec)
errors = sorted(validators[kind].iter_errors(as_json(rec)), key=lambda e: list(e.path))
problems, notes = ([f"schema: {'/'.join(map(str, e.path)) or '(record)'}: {e.message[:120]}" for e in errors], [])
if not errors:
problems, notes = CHECK[kind](rec, today, index)
status = "FAIL" if problems else "ok"
failed += bool(problems)
print(f"{status:4} {name}")
for line in problems:
print(f" problem: {line}")
for line in notes:
print(f" note: {line}")
print(f"{len(records) - failed} of {len(records)} records pass")
return 1 if failed else 0
if __name__ == "__main__":
sys.exit(main())
The tests do not test the records; they test the checks. Each assertion feeds a check a record that has been broken in one way and expects the check to name the break, and the three functions of the chapters (the quota evaluation, the placement function and the gateway) are run on the cases that the chapters describe: the three days of the January 2033 breach, a placement that saves 90 kg and one that is refused as below threshold, and a run that is stopped at 18 calls and a credential that is revoked at the day limit.
#!/usr/bin/env python3
"""test_records.py: the checks must catch what they claim to catch. Run: python3 test_records.py RECORD_DIR"""
import copy
import sys
from datetime import date
from pathlib import Path
import yaml
from gateway import Gateway, Limits
from record_checks import (check_clm, check_ebg, check_fpr, check_mnd, check_plc, check_rbk,
evaluate_quota, place)
R = Path(sys.argv[1] if len(sys.argv) > 1 else "records")
TODAY = date(2032, 12, 13)
def load(name):
return yaml.safe_load((R / name).read_text(encoding="utf-8"))
def has(problems, text):
return any(text in line for line in problems)
# 1. The three days of the January 2033 breach at Nordvik Region (Chapter 20).
ebg = load("EBG-NR-0001.yaml")
for day, units, want in ((17, 129_400, "alert"), (22, 167_400, "defer"), (24, 177_800, "stop")):
usage = {"units": units, "resolved": 0.86 * units, "sessions": units}
got = evaluate_quota(ebg, usage, date(2033, 1, day))
assert got["state"] == want, (day, got)
assert got["counts_as_cap"], got
# 2. Placement at Hansa Mutual: other regions are blocked while their basin stress is unknown.
plc = load("PLC-HM-0001.yaml")
home = "hansa-dc-frankfurt"
fc = {(home, "Mon 09:00"): 420, (home, "Mon 20:00"): 330, (home, "Tue 11:00"): 400, (home, "Wed 11:00"): 410,
("cloud-a-ireland", "Mon 20:00"): 150}
job = {"class": "evaluation_weekly", "home": home, "data_class": "standard", "interactive": False,
"default_start": "Mon 09:00", "energy_kwh": 1000}
region, start, why = place(job, plc, fc)
assert (region, start) == (home, "Mon 20:00") and why == "saves 90 kg CO2e", (region, start, why)
assert place({**job, "interactive": True}, plc, fc)[2].startswith("floor")
assert place({**job, "energy_kwh": 100}, plc, fc)[2] == "floor: saving below threshold"
# 3. The gateway stops a run at its limit and revokes the credential at the day limit.
sent, revoked = [], []
gw = Gateway(Limits(), revoke=lambda: revoked.append(True), to_manual=sent.append)
assert all(gw.admit("run-1", "model")[0] for _ in range(18))
assert gw.admit("run-1", "model") == (False, "run model calls") and sent == ["run-1"]
gw.admit("run-2", "model")
gw.record("run-2", 60_000) # accelerator seconds (about 15 kWh) from the inference server
assert gw.admit("run-2", "model") == (False, "credential revoked") and revoked == [True]
# 4. Each check refuses what it exists to refuse.
bad = copy.deepcopy(load("EBG-HM-0002.yaml")); bad["stop"]["last_drill"] = date(2032, 6, 1)
assert has(check_ebg(bad, TODAY)[0], "active without a stop drill")
bad = copy.deepcopy(load("FPR-HM-0002.yaml")); bad["result"]["carbon_g_per_unit"]["central"] = 2.0
assert has(check_fpr(bad, TODAY)[0], "is not energy x grid")
bad = copy.deepcopy(load("FPR-NR-0001-r1.yaml")); bad["independence"]["checked_by"] = "platform-team"
assert has(check_fpr(bad, TODAY)[0], "not independent")
bad = copy.deepcopy(load("MND-HM-ENV-0001.yaml")); bad["delegation"]["provision_or_scale_compute"] = 3
assert has(check_mnd(bad, TODAY)[0], "ceiling is 0")
bad = copy.deepcopy(load("PLC-NR-0001.yaml")); bad["time_shift"]["enabled"] = True
assert has(check_plc(bad, TODAY)[0], "without a replay record")
bad = copy.deepcopy(load("RBK-NR-ENV-001.yaml")); bad["trigger"][1]["at"] = 1.2
assert has(check_rbk(bad, TODAY)[0], "ascending")
bad = copy.deepcopy(load("CLM-HM-0001-r2.yaml")); bad["statement"] += " The assistant is green."
assert has(check_clm(bad, TODAY)[0], "vague or offset wording: green")
bad = copy.deepcopy(load("CLM-HM-0001-r2.yaml")); bad["approved_for_publication_by"] = "the reporting agent"
assert has(check_clm(bad, TODAY)[0], "named person")
bad = copy.deepcopy(load("CLM-HM-0001-r2.yaml")); bad["comparative_assertion"] = True
assert has(check_clm(bad, TODAY)[0], "all the impact categories")
bad.update(categories_complete=True, weighting="none", critical_review={"panel_size": 2, "chair_independent": True, "statement": "attached"})
assert has(check_clm(bad, TODAY)[0], "at least three")
bad["critical_review"]["panel_size"] = 3
assert not has(check_clm(bad, TODAY)[0], "comparative")
bad = copy.deepcopy(load("FPR-HM-0007.yaml")); bad["lca_frame"]["categories"] = ["water use"]
assert has(check_fpr(bad, TODAY)[0], "climate change")
bad = copy.deepcopy(load("FPR-HM-0007.yaml")); bad["lca_frame"]["embodied_life_sensitivity_kgco2e"]["years_6"] = 30.0
assert has(check_fpr(bad, TODAY)[0], "rises with the life")
assert not check_clm(load("CLM-HM-0001-r2.yaml"), TODAY)[0]
assert has(check_clm(load("CLM-HM-0001-r2.yaml"), date(2033, 2, 1))[0], "evidence expired")
print("all checks behave")
A.15 Running it
python3 validate_records.py schemas records --today 2032-12-13
python3 validate_records.py schemas book --today 2026-11-16 # the book's own record, on its own date
python3 validate_records.py schemas negative --today 2032-12-13 # exits 1: the claim is not publishable
python3 test_records.py records
The records of the book itself are saved in a folder of their own (book/FPR-BK-0001-r1.yaml) and run on the date of their measurement, because the records of the two organisations are dated to December 2032 and the evidence of FPR-BK-0001 runs out 90 days after 16 November 2026. The first command prints one line per file and the notes under it. The notes are what the records carry open on purpose: a budget that is not yet a cap, a benefit record whose clock runs from the decision date, a supplier item on rung 3 that is kept out of totals. The output below is that of the records of this appendix, as of the date given.
ok AIDR-1326.yaml
ok AIDR-1376.yaml
ok BEN-HM-0002.yaml
note: the clock runs from the decision date; the measurement is older (measurement plus 180 days is 2033-04-29)
ok BEN-NR-0001.yaml
note: the clock runs from the decision date; the measurement is older (measurement plus 180 days is 2033-04-22)
ok CLM-HM-0001-r2.yaml
ok CLM-NR-0001-r2.yaml
note: a correction: the record states what is not known
ok EBG-HM-0002.yaml
ok EBG-NR-0001.yaml
note: quota at the latest conversion would use -9.0% of the energy budget
ok FPR-HM-0002.yaml
ok FPR-HM-0007.yaml
note: evidence 'embodied impact per accelerator' is an assumption, not a measurement
note: independent check is none
note: lca_frame: no critical review; it supports internal decisions, not a public comparison
ok FPR-NR-0001-r1.yaml
ok FPR-NR-0001-r2.yaml
note: allocated energy per unit 30.5 Wh; implied grid 32 g/kWh
note: evidence 'power_per_accelerator' is an assumption, not a measurement
note: independent check is partial
ok HWL-HM-0001.yaml
note: option C: 13.7 t of embodied impact is counted once, not per year
note: option D: 10.3 t of embodied impact is counted once, not per year
ok HWL-NR-0001.yaml
note: the supplier has not answered the request
ok MND-HM-ENV-0001.yaml
ok MND-NR-ENV-0001.yaml
note: no passing stop drill: the budget is not counted as a cap
ok PLC-HM-0001.yaml
note: no valid stop drill: the policy stays proposed
note: region hansa-dc-frankfurt: basin stress unknown: a move into it is blocked
note: region cloud-a-ireland: basin stress unknown: a move into it is blocked
note: region cloud-b-france: basin stress unknown: a move into it is blocked
ok PLC-NR-0001.yaml
note: no valid stop drill: the policy stays proposed
ok RBK-NR-ENV-001.yaml
ok SDR-HM-0002.yaml
note: item 'account-level carbon report' is on rung 3 and is kept out of totals
ok SDR-NR-0001.yaml
note: item 'total water input' is on rung 3 and is kept out of totals
ok environment-hm.yaml
note: FPR-HM-0001 (Katrin Ohlsen): incomplete, footprint valid, benefit missing, stop_drill valid; review by 2033-01-02
note: FPR-HM-0002 (Anja Weiß): incomplete, footprint valid, benefit valid, stop_drill valid, hardware valid; review by 2032-12-21
ok environment-nr.yaml
note: FPR-NR-0001 (Sara Ekdahl): complete, footprint valid, benefit valid, stop_drill valid, supplier valid, hardware valid; review by 2032-12-19
note: FPR-NR-0003 (Gunilla Roos): incomplete, footprint missing, benefit missing, stop_drill missing; review by now
23 of 23 records pass
The second command prints the book's own record. The notes are the honest gaps of the record: two assumptions in its evidence, no independent check and no owner.
ok FPR-BK-0001-r1.yaml
note: evidence 'energy per token' is an assumption, not a measurement
note: evidence 'cached-token share' is an assumption, not a measurement
note: independent check is none
note: no owner is named for the figure
1 of 1 records pass
Run on the date of the illustrative records, the same file fails with problem: evidence 'token counts' expired on 2027-02-14: the counting of the book is dated, and it is re-measured before release.
The third command prints the problems that stop CLM-HM-0001 revision 1:
FAIL CLM-HM-0001-r1.yaml
problem: missing claim_kind
problem: missing object
problem: missing boundary
problem: missing period
problem: missing evidence
problem: missing independent_check
problem: missing approved_for_publication_by
problem: claim_kind must be one of footprint, benefit, commitment
0 of 1 records pass
The fourth prints all checks behave.
Summary
Every record of the book has a schema that says what the structure must be and a check that says what the figures and the dates must satisfy. A schema passes a record that is complete and wrong; a check passes a record that is complete and in order; neither passes a record that a named person has not read. The three rules that run through every check are the three of the method: a figure carries its boundary and year (Count), a benefit is measured against an alternative and a rebound and kept in its own ledger (Compare), and a use runs under a budget set by someone else, measured outside it and stopped by a path that does not run through it (Cap).