license: apache-2.0 tags:

• energy
• governance
• provenance
• software
• measurement
• receipts language:
• en pretty_name: Attestable Energy Receipts for Governed Compute

SZL Holdings · Doctrine v11 · Λ = Conjecture 1 (advisory, never "green"/theorem) · canonical a-11-oy.com

szl_energy_attest — attestable energy receipts for governed compute

Canonical source. This GitHub repository is the source of truth for the energy-attestation artifact and vendors the runnable energy core under energy_core/, co-located with the wrapped measurement path. It is real, tested, and downloadable for direct consumption. Note on the flagship: the a11oy governed substrate at a-11-oy.com currently serves its own inline energy implementation (szl_joules_truth.py / szl_energy_operator.py) under /api/a11oy/v1/energy/*; this package is the canonical kernel available for direct use — it is not yet the flagship's served code path.

📦 Canonical energy package (Wave D consolidation). This repo is the canonical SZL energy package. The former szl-holdings/governed-inference-meter has been folded in here: its live inference metering code — the NVML EnergyMeter (hardware energy counter + power-integral / trapezoidal fallback), an advisory policy gate, and the meter() / metered() inference wrappers that emit tokens-per-joule hash-chained receipts — now lives under szl_energy_attest.inference_meter. The meter-specific attestation, receipt-chain hardening, and PCGI adapters are also retained there for import continuity; the root package's energy receipt is a different schema, so parity is not invented. File-level source and destination hashes are recorded in MIGRATION_PROVENANCE.json. governed-inference-meter is DEPRECATED, not deleted, and archiving remains a later owner decision. Λ = Conjecture 1 (advisory) is preserved verbatim; no conjecture is upgraded to proven.

Turn the energy a unit of compute spends into a receipt you can verify — offline, by anyone, with nothing but a hash function.

This package turns one unit of governed compute into an attestable energy receipt: a small, canonical, hash-chained JSON record that states — honestly — how many joules the work measured (from real NVML), and links to the receipt before it so any tampering or reordering breaks the chain. When no GPU is present, the energy field is null and labeled UNAVAILABLE — never a fabricated number.

Doctrine. MEASURED joules only, via real NVML. We never fabricate a joule, a price, or a receipt. Λ is Conjecture 1 — advisory, trust never 100%. An honest UNAVAILABLE receipt that still hash-verifies beats a fake-green number.

Artifact truth card

Investor value. The package turns an otherwise ephemeral hardware reading into portable evidence with explicit missing-data semantics, reducing the risk that estimated or absent energy data is presented as measured fact.

Developer/evaluator path. Install the package, import capability_report from szl_energy_attest.inference_meter, inspect it before metering, run one known workload, and verify the resulting chain offline. On the inference-meter path, missing hardware evidence terminates as mode="unmeasured" with joules: null; the separate root receipt schema uses the UNAVAILABLE label.

Product value without a novelty claim

Energy tools expose different layers: counters, estimates, dashboards, and audit records. This package focuses narrowly on binding a supported hardware observation, its availability state, and receipt provenance into one record.

The value is the explicit evidence boundary. This repository makes no ecosystem-wide novelty claim.

What is MEASURED vs UNAVAILABLE

This is the most important section. Read it before trusting any field.

• MEASURED — measured_joules is a real number only when a real, fresh NVML / exporter joule delta produced it. The label is decided by the energy core's joule-truth path, never by a convenience flag. Requires a GPU and a live metering exporter on the node that did the work.
• UNAVAILABLE — there is no reachable GPU/NVML measurement capability on this box (e.g. a CPU-only laptop, CI runner, or this Space). measured_joules is null and the label says so. The receipt chain still verifies — the provenance is real even when the joules cannot be.
• SAMPLE — the selected path initialized NVML and found at least one device, but produced no fresh supported counter delta. Energy is not a billable MEASURED joule, so we report null, never a guess. This label speaks only to measurement-path state; by itself it proves neither device-handle acquisition, workload execution, nor token provenance.

price_per_mwh and gCO2 are pass-through only: a live grid meter value verbatim, or null. They are never assumed, modeled-as-fact, or back-filled.

On a CPU-only machine, the example below runs end-to-end with measured_joules: null, label: "UNAVAILABLE", and a chain that verifies. That is the correct, shippable behavior — not a bug.

grid_context — documenting when/where a run happened (REPORTED, optional)

A receipt can carry an optional grid_context block: the observed grid signal at run time — the grid's carbon intensity (gCO₂/kWh) and, where a provider publishes one, the wholesale price. It lets a run document that it happened in a cleaner / cheaper / curtailed window — the software-scheduling discipline that is the one honest transfer from demand-response operators.

It is pass-through provenance, not measurement. grid_context is completely independent of the NVML joule-truth path: with no GPU, measured_joules stays null + UNAVAILABLE exactly as before. A grid_context block never turns an unmeasured run into a measured one, and never becomes a joule.

This does not create or measure free energy; scheduling compute into cleaner windows is the only transfer. There is no free-energy, perpetual-motion, or zero-cost-energy claim here — "curtailed / dumped" power is real waste energy that still costs real money and hardware to capture. Λ remains Conjecture 1 (open).

Honest labels (every field)

• REPORTED — a value carried verbatim from a real public signal, together with its source URL and its observed_at / fetched_at timestamps.
• UNAVAILABLE — the signal was missing, unreachable, malformed, or the provider publishes no such value. The field is null. Never invented, modelled, or defaulted.

The carbon number is labelled by kind so it is never over-claimed: carbon_intensity_kind: "grid_average" for the UK signal (an average mix, not marginal) vs "marginal" only when a provider that actually reports marginal operating emissions is used.

Providers

• uk_carbon_intensity — the default, keyless provider (UK Carbon Intensity API). Reports grid-average carbon intensity (actual/forecast). It publishes no price, so price_per_mwh is null / UNAVAILABLE for this provider — honestly.
• electricity_maps, watttime — OPTIONAL, key-gated providers. Without a caller-supplied api_key they return an honest UNAVAILABLE block. A key is never required — the keyless UK signal always works.

from szl_energy_attest import (
    build_receipt, fetch_grid_context, verify_chain, GENESIS_PREV,
)

# Keyless UK Carbon Intensity API. Network failure => honest UNAVAILABLE nulls.
gc = fetch_grid_context("uk_carbon_intensity")   # REPORTED pass-through block

r = build_receipt(tokens=128, node="node-a", prev=GENESIS_PREV, grid_context=gc)
# measured_joules stays null/UNAVAILABLE on a CPU box — grid_context adds context,
# not joules. The block is hashed into the receipt, so it is tamper-evident too.
assert verify_chain([r])[0]

A grid_context block (REPORTED, from the keyless UK signal):

{
  "provider": "uk_carbon_intensity",
  "source": "https://api.carbonintensity.org.uk/intensity",
  "region": "GB",
  "observed_at": "2026-07-09T18:30Z",
  "fetched_at": "2026-07-09T19:05:00Z",
  "carbon_intensity_gco2_per_kwh": 121,
  "carbon_intensity_kind": "grid_average",
  "carbon_intensity_index": "moderate",
  "carbon_intensity_label": "REPORTED",
  "price_per_mwh": null,
  "price_label": "UNAVAILABLE",
  "note": "REPORTED grid-average carbon intensity (actual) …; NOT marginal, NOT a MEASURED joule."
}

grid_context is hashed into the receipt body only when present, so it is tamper-evident (a forged intensity breaks the chain) while receipts without it re-hash byte-identically to the pre-grid_context schema (full back-compat).

Install / layout

This repository vendors two co-located packages:

• szl_energy_attest/ — the publishable attestation surface (this package).
• energy_core/szl_energy_core/ — the runnable SZL energy core (measured-joule accounting + cheapest-watt placement), folded in as a sibling so the wrapped measurement path ships alongside the attestation layer. See energy_core/README.md.

Pure-stdlib for the verification and fallback hashing path (hashlib + json); no network. When the runnable SZL energy core (szl_energy_core) is importable, this package wraps it: receipts use the core's canonical hash (SHA3-256) and real measure_energy() NVML delta path, so digests are platform-consistent and the energy numbers come from the same metering code the operator uses. It never duplicates that code. With no core present it falls back to a byte-identical local SHA-256 so the chain still verifies offline. canon_source() reports which is active (here: szl_energy_core).

szl_energy_attest/
  szl_energy_attest/__init__.py   # build_receipt(), verify_chain(), measure_joules()
  szl_energy_attest/cli.py        # `emit` / `verify` sample receipt chains
  examples/sample_receipt.json    # a clearly-labeled SAMPLE chain (UNAVAILABLE energy)
  SPEC.md                         # receipt schema + verification procedure
  LICENSE                         # Apache-2.0
  CITATION.cff

Quickstart

# Emit a clearly-labeled SAMPLE receipt chain to stdout (or --out file.json)
python -m szl_energy_attest.cli emit

# Emit + re-walk the hash chain, then prove tampering breaks it
python -m szl_energy_attest.cli verify

Programmatic use:

from szl_energy_attest import build_receipt, verify_chain, measure_joules, GENESIS_PREV

# measure_joules() is honest: (None, "UNAVAILABLE") on a CPU-only box.
joules, label = measure_joules()

r0 = build_receipt(tokens=128, node="node-a",
                   measured_joules=joules, label=label, prev=GENESIS_PREV)
r1 = build_receipt(tokens=256, node="node-b",
                   measured_joules=joules, label=label, prev=r0["digest"])

ok, length, first_break = verify_chain([r0, r1])
assert ok  # re-hashes cleanly; energy is null/UNAVAILABLE but provenance is real

An example receipt body (UNAVAILABLE, from a CPU-only box):

{
  "schema": "szl_energy_attest/receipt@1",
  "measured_joules": null,
  "label": "UNAVAILABLE",
  "tokens": 128,
  "node": "example-node-a",
  "price_per_mwh": null,
  "gCO2": null,
  "decision": "no_choice",
  "lambda": "Conjecture 1 (advisory; trust never 100%)",
  "sovereign": false,
  "prev": "0000000000000000000000000000000000000000000000000000000000000000",
  "payload_digest": "sha3-256:…",
  "digest": "sha3-256:…"
}

See SPEC.md for the full field-by-field schema and the offline verification procedure.

Detached chain signature verification

sign_chain(receipts) re-walks the supplied list before constructing its detached envelope; an invalid chain raises ValueError before any signer is called. verify_signature(receipts, envelope, key=...) verifies that chain and requires the envelope's canonical payload to match its terminal digest, length and payload type. A valid envelope for another chain cannot authenticate these receipts. Missing/malformed envelopes, contradictory signing states, noncanonical payloads and unsupported signature backends return valid=False.

The emitted envelope format is unchanged. A coherent UNSIGNED envelope retains signed=False, valid=True for chain integrity only; it does not authenticate a signer. Callers requiring keyed authentication must require both signed=True and valid=True under their configured key policy. HMAC validates possession of that shared key, without proving a public signer identity or measurement accuracy. An empty chain can verify against its genesis/zero-length envelope, which is no evidence of execution or energy measurement.

How the real capability fits together

szl_energy_attest is the publishable surface over a real, running stack:

• MEASURED-NVML energy accounting. Joules come from a real, fresh (<30s) NVML exporter delta on the node that computed the work; stale or absent samples are labeled and excluded — never fabricated.
• Cheapest-watt placement. When two or more nodes have a comparable MEASURED energy intensity (joules/token) and a live grid price is present, the policy records which node minimizes energy-cost-per-token. With fewer than two comparable measured nodes it records no_choice — it never invents an alternative to claim a saving against.
• Hash-chained, signable receipts. Every decision is re-hashable offline (payload_digest) and chained (prev → digest); DSSE signing is layered on by the caller when a real cosign key is present — absent a key, the receipt is honest-but-unsigned, never faked.

This is the energy lens of the a11oy governed-AI platform (SZL Holdings), which records governed decisions as cryptographically signed, tamper-evident receipts verifiable offline by anyone with a public key. It composes with:

• lutar-lean — Lean 4 formalization of Λ (Conjecture 1, uniqueness proof-deferred — NOT a theorem) plus the machine-checked Egyptian-exactness lemma (DOI 10.5281/zenodo.20434308).
• vsp-otel — the verifiable-span OpenTelemetry exporter that carries these receipts as spans (DOI 10.5281/zenodo.19944926).

Honesty notes (what this is NOT)

• It does not execute inference and does not generate joules. It records and verifies what was measured elsewhere.
• There are no benchmarks, no headline energy numbers, and no savings claims in this README — those only exist on hardware that actually measured them, inside a receipt you can re-hash.
• Λ is a conjecture, used advisorily. Nothing here asserts certainty, sovereignty, or 100% trust.
• On a box that cannot measure, the correct output is UNAVAILABLE. We publish that honestly rather than a green number we cannot defend.

Citation

See CITATION.cff. Author: Stephen Lutar (ORCID 0009-0001-0110-4173), SZL Holdings.

License

Apache-2.0. © 2026 SZL Holdings. See LICENSE.

Hugging Face presentation boundary

The GitHub repository is the canonical source for this package. Use the SZL Holdings Hugging Face organization to discover separately published compatibility artifacts or presentation Spaces. Names, reachability, and runtime state may change and are not asserted here. The deprecated meter's immutable loading contract remains under hf-kernels/governed-inference-meter.

Signed-off-by: Stephen Lutar stephenlutar2@gmail.com