@emilia-protocol/gate 0.9.0 → 0.9.2

package/index.js

@@ -47,7 +47,7 @@ import { MemoryConsumptionStore } from './store.js';
 import { createEvidenceLog } from './evidence.js';
 import { DEFAULT_GATE_MANIFEST, HIGH_RISK_ACTION_PACKS, createDefaultActionRiskManifest } from './action-packs.js';
 import { hashCanonical, verifyExecutionBinding } from './execution-binding.js';
-import { buildReliancePacket } from './reliance-packet.js';
+import { buildReliancePacket, ADMISSIBILITY_VERDICTS } from './reliance-packet.js';
 import { createEg1Harness, makeGateInvoke, runEg1, EG1_DEFAULT_SELECTOR, mintDeviceSignoff, mintQuorumEvidence } from './eg1-conformance.js';
 import { CF1_VERSION, CF1_CHECKS, runCf1 } from './cf1-conformance.js';
 import { createKeyRegistry, asKeyRegistry } from './key-registry.js';
@@ -72,7 +72,14 @@ export {
   validateActionControlManifest,
 } from './action-control-manifest.js';
 export { EXECUTION_BINDING_VERSION, canonicalize, hashCanonical, materialFieldsFor, verifyExecutionBinding } from './execution-binding.js';
-export { RELIANCE_PACKET_VERSION, buildReliancePacket } from './reliance-packet.js';
+export { RELIANCE_PACKET_VERSION, ADMISSIBILITY_VERDICTS, buildReliancePacket } from './reliance-packet.js';
+export {
+  EXTERNAL_VERIFICATION_STATEMENT_VERSION,
+  EXTERNAL_VERIFICATION_DOMAIN,
+  externalVerificationDigest,
+  signExternalVerificationStatement,
+  verifyExternalVerificationStatement,
+} from './reports/external-verification.js';
 export {
   EG1_VERSION, EG1_CHECKS, EG1_DEFAULT_ACTION, EG1_DEFAULT_SELECTOR,
   createEg1Harness, makeGateInvoke, runEg1, mintDeviceSignoff, mintQuorumEvidence,
@@ -81,6 +88,55 @@ export { CF1_VERSION, CF1_CHECKS, runCf1 } from './cf1-conformance.js';
 export const ASSURANCE_TIERS = ['software', 'class_a', 'quorum'];
 const TIER_RANK = { software: 0, class_a: 1, quorum: 2 };
 
+/**
+ * Verify a PRE-COMPUTED reliance packet's admissibility block against a profile
+ * the relying party PINNED. This is the gate's whole job re: admissibility — it
+ * does NOT re-evaluate raw evidence and does NOT define the bar. The relying
+ * party's own evaluator (lib/evidence/admissibility-profiles.js) computes the
+ * verdict OFFLINE against its pinned profile and produces the reliance packet;
+ * the gate only confirms the packet answers the SAME profile_hash and carries an
+ * 'admissible' verdict. Pure, dependency-light, fail-closed.
+ *
+ * @param {{id?:string, profile_hash:string}} pinned  the profile the relying party requires
+ * @param {object|null} presented  a reliance packet, or its `.admissibility` block,
+ *   as produced by buildReliancePacket / the relying party's evaluator
+ * @returns {{ok:boolean, reason:string|null, pinned_hash:string, presented_hash:string|null, verdict:string|null}}
+ *   ok:true ONLY when the presented profile_hash equals the pinned hash AND the
+ *   verdict is exactly 'admissible'. Every other case fails closed with a distinct reason.
+ */
+export function verifyAdmissibilityAgainstPinnedProfile(pinned, presented) {
+  const pinnedHash = pinned && typeof pinned.profile_hash === 'string' ? pinned.profile_hash : null;
+  // A pin with no hash is a misconfiguration: refuse, do not silently pass.
+  if (!pinnedHash) {
+    return { ok: false, reason: 'pinned_profile_missing_hash', pinned_hash: null, presented_hash: null, verdict: null };
+  }
+  // Accept either a full reliance packet (has .admissibility) or the block itself.
+  const adm = presented && typeof presented === 'object'
+    ? (presented.admissibility !== undefined ? presented.admissibility : presented)
+    : null;
+  if (!adm || typeof adm !== 'object') {
+    return { ok: false, reason: 'admissibility_profile_pinned_but_absent', pinned_hash: pinnedHash, presented_hash: null, verdict: null };
+  }
+  const presentedHash = typeof adm.profile_hash === 'string' ? adm.profile_hash : null;
+  const verdict = typeof adm.verdict === 'string' ? adm.verdict : null;
+  // Constant-work equality is unnecessary (hashes are public), but the mismatch
+  // MUST be a distinct, named refusal: a presented verdict for a DIFFERENT bar is
+  // not evidence about the pinned bar.
+  if (presentedHash === null || presentedHash !== pinnedHash) {
+    return { ok: false, reason: 'profile_hash_mismatch', pinned_hash: pinnedHash, presented_hash: presentedHash, verdict };
+  }
+  // Verdict must be recognized AND exactly 'admissible'. Any other closed-set
+  // member (missing_evidence/stale/conflicted/unverifiable), an unrecognized
+  // string, or a missing verdict fails closed and names the verdict it saw.
+  if (verdict === null || !ADMISSIBILITY_VERDICTS.includes(verdict)) {
+    return { ok: false, reason: 'admissibility_verdict_unrecognized', pinned_hash: pinnedHash, presented_hash: presentedHash, verdict };
+  }
+  if (verdict !== 'admissible') {
+    return { ok: false, reason: `admissibility_not_admissible:${verdict}`, pinned_hash: pinnedHash, presented_hash: presentedHash, verdict };
+  }
+  return { ok: true, reason: null, pinned_hash: pinnedHash, presented_hash: presentedHash, verdict };
+}
+
 /**
  * The assurance tier a receipt has CRYPTOGRAPHICALLY EARNED.
  *
@@ -183,7 +239,7 @@ function isSignoffEvidence(s) {
  *   if given it supersedes trustedKeys — a receipt is verified only against keys valid (and not
  *   revoked) at its issuance time.
  */
-export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900, store, log, allowInlineKey = false, allowEphemeralStore = false, strictEvidence = true, now = Date.now, keyRegistry = null, approverKeys = {}, approver_keys = null, verifyAssurance = null, rpId = null } = {}) {
+export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900, store, log, allowInlineKey = false, allowEphemeralStore = false, strictEvidence = true, now = Date.now, keyRegistry = null, approverKeys = {}, approver_keys = null, verifyAssurance = null, rpId = null, requiredAdmissibilityProfile = null } = {}) {
   // Production key custody: a registry (rotation + revocation) supersedes a flat
   // trustedKeys list. A flat list is coerced to an always-valid registry, so
   // existing callers are unchanged.
@@ -210,10 +266,19 @@ export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900,
   }
   const evidence = log || createEvidenceLog({ strict: strictEvidence });
 
-  async function check({ selector = {}, receipt = null, observedAction = null, consumptionMode = 'consume' } = {}) {
+  async function check({ selector = {}, receipt = null, observedAction = null, consumptionMode = 'consume', admissibilityProfile = null, reliancePacket: presentedPacket = null, admissibility = null } = {}) {
     const requirement = manifest ? findActionRequirement(manifest, selector) : null;
     const action = requirement?.action_type || selector.action_type || selector.action || null;
-    const requiredTier = requirement?.assurance_class || selector.assurance_class || 'software';
+    // Assurance tier the action requires (cryptographically checked below). For a
+    // manifest-guarded action the tier MUST be declared explicitly: never fall
+    // back to the weakest 'software' tier because assurance_class was omitted —
+    // that would let a guarded, possibly critical, action accept a bare
+    // machine-signed receipt (a fail-open). A guarded requirement with no tier
+    // is a misconfiguration and fails closed just below. Only selector-only
+    // checks (no manifest requirement) use the documented 'software' default.
+    const requiredTier = requirement
+      ? requirement.assurance_class
+      : (selector.assurance_class || 'software');
     const observed = observedAction || selector.observedAction || selector.actionDetails || null;
 
     async function decide(allow, status, reason, extra = {}) {
@@ -268,6 +333,14 @@ export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900,
     if (!receipt) {
       return decide(false, RECEIPT_REQUIRED_STATUS, 'receipt_required');
     }
+    // A manifest-guarded action that declares no assurance_class is a
+    // misconfiguration. Fail CLOSED rather than defaulting to the weakest tier
+    // (which would accept a bare machine-signed receipt for a guarded action).
+    // validateActionRiskManifest also rejects such a manifest at author time;
+    // this is defense in depth for a manifest loaded without re-validation.
+    if (requirement && requirement.receipt_required !== false && !requiredTier) {
+      return decide(false, RECEIPT_REQUIRED_STATUS, 'manifest_missing_assurance_class');
+    }
     // Signature / freshness / action-binding / outcome. Production key custody:
     // resolve the issuer keys valid (and not revoked) at THIS receipt's issuance
     // time. A revoked or out-of-window key is excluded, so its signature does not
@@ -324,6 +397,29 @@ export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900,
     if (!executionBinding.ok) {
       return decide(false, RECEIPT_REQUIRED_STATUS, 'execution_binding_failed', { execution_binding: executionBinding, have_tier: have, assurance_tier_source: 'cryptographic_verification' });
     }
+    // OPT-IN admissibility pinning. When the caller pins a required admissibility
+    // profile {id, profile_hash} (gate-level requiredAdmissibilityProfile, a
+    // per-call admissibilityProfile, or selector.admissibilityProfile), the gate
+    // REFUSES unless a presented reliance packet's admissibility block was computed
+    // against the SAME pinned profile_hash AND carries an 'admissible' verdict. The
+    // gate does NOT re-evaluate raw evidence and does NOT define the bar — the
+    // relying party's own evaluator produced the verdict OFFLINE against its pinned
+    // profile. Checked BEFORE consumption so a mismatch never burns the receipt.
+    // When no profile is pinned, this whole block is inert — behavior is
+    // byte-for-byte unchanged from the pre-admissibility gate.
+    const pinnedProfile = admissibilityProfile || selector.admissibilityProfile || requiredAdmissibilityProfile;
+    if (pinnedProfile) {
+      const presentedAdmissibility = admissibility ?? presentedPacket ?? selector.reliancePacket ?? selector.admissibility ?? null;
+      const adm = verifyAdmissibilityAgainstPinnedProfile(pinnedProfile, presentedAdmissibility);
+      if (!adm.ok) {
+        return decide(false, RECEIPT_REQUIRED_STATUS, adm.reason, {
+          admissibility_check: adm,
+          pinned_profile: { id: pinnedProfile.id ?? null, profile_hash: pinnedProfile.profile_hash ?? null },
+          have_tier: have,
+          assurance_tier_source: 'cryptographic_verification',
+        });
+      }
+    }
     // One-time consumption (replay defense). Require a stable, issuer-generated
     // receipt_id — never fall back to a content hash, whose canonicalization can
     // differ across language implementations and silently break replay detection
@@ -346,7 +442,16 @@ export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900,
     if (!fresh) {
       return decide(false, RECEIPT_REQUIRED_STATUS, 'replay_refused', { consumption_key: receiptId });
     }
-    return decide(true, 200, 'allow', { signer: v.signer, outcome: v.outcome, have_tier: have, assurance_tier_source: 'cryptographic_verification', execution_binding: executionBinding, consumption_mode: consumptionMode });
+    const allowExtra = { signer: v.signer, outcome: v.outcome, have_tier: have, assurance_tier_source: 'cryptographic_verification', execution_binding: executionBinding, consumption_mode: consumptionMode };
+    // Carry the admissibility block (from the presented packet) onto the decision
+    // so a reliance packet built from this decision embeds the verdict the relying
+    // party's evaluator computed. Only when something was actually presented.
+    const presentedAdmForAllow = admissibility ?? presentedPacket ?? selector.reliancePacket ?? selector.admissibility ?? null;
+    if (presentedAdmForAllow) {
+      const admBlock = presentedAdmForAllow.admissibility !== undefined ? presentedAdmForAllow.admissibility : presentedAdmForAllow;
+      if (admBlock) allowExtra.admissibility = admBlock;
+    }
+    return decide(true, 200, 'allow', allowExtra);
   }
 
   /** Express/Connect middleware: refuse the route unless a sufficient receipt is present. */
@@ -400,9 +505,9 @@ export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900,
    * If the side effect throws, the reservation is released so the approval can
    * be retried safely.
    */
-  async function run({ selector = {}, receipt = null, observedAction = null } = {}, fn, opts = {}) {
+  async function run({ selector = {}, receipt = null, observedAction = null, admissibilityProfile = null, reliancePacket: presentedPacket = null, admissibility = null } = {}, fn, opts = {}) {
     if (typeof fn !== 'function') throw new Error('EMILIA Gate run(): fn is required');
-    const authorization = await check({ selector, receipt, observedAction, consumptionMode: 'reserve' });
+    const authorization = await check({ selector, receipt, observedAction, consumptionMode: 'reserve', admissibilityProfile, reliancePacket: presentedPacket, admissibility });
     if (!authorization.allow) {
       return { ok: false, status: authorization.status, body: authorization.challenge, authorization };
     }
@@ -441,7 +546,13 @@ export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900,
       const observedAction = typeof opts.observedAction === 'function'
         ? opts.observedAction(...args)
         : (opts.observedAction || selector.observedAction || null);
-      const out = await run({ selector, receipt, observedAction }, () => fn(...args), { recordExecution: opts.recordExecution });
+      const admissibilityProfile = typeof opts.admissibilityProfile === 'function'
+        ? opts.admissibilityProfile(...args)
+        : (opts.admissibilityProfile ?? null);
+      const presentedPacket = typeof opts.reliancePacket === 'function'
+        ? opts.reliancePacket(...args)
+        : (opts.reliancePacket ?? opts.admissibility ?? null);
+      const out = await run({ selector, receipt, observedAction, admissibilityProfile, reliancePacket: presentedPacket }, () => fn(...args), { recordExecution: opts.recordExecution });
       if (!out.ok) {
         const e = new Error(`EMILIA Gate refused (${out.authorization.reason})`);
         e.code = 'EMILIA_RECEIPT_REQUIRED';
@@ -452,13 +563,22 @@ export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900,
     };
   }
 
-  function reliancePacket({ authorization, execution = null, binding = null } = {}) {
+  function reliancePacket({ authorization, execution = null, binding = null, admissibility = null } = {}) {
+    // The admissibility block rides on the authorization decision's evidence when
+    // a reliance packet was presented at check() time; an explicit `admissibility`
+    // arg overrides it. buildReliancePacket fails closed on a non-'admissible'
+    // block, so a do_not_rely verdict can never be laundered into rely here.
+    const adm = admissibility
+      ?? authorization?.evidence?.admissibility
+      ?? authorization?.admissibility
+      ?? null;
     return buildReliancePacket({
       decision: authorization,
       execution,
       evidence,
       manifest,
       binding,
+      admissibility: adm,
     });
   }
 
@@ -560,6 +680,8 @@ export default {
   createGate,
   createTrustedActionFirewall,
   receiptAssuranceTier,
+  verifyAdmissibilityAgainstPinnedProfile,
+  ADMISSIBILITY_VERDICTS,
   MemoryConsumptionStore,
   createEvidenceLog,
   ASSURANCE_TIERS,

package/metering.js

@@ -0,0 +1,227 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * EMILIA Gate — usage metering (the value metric, EP-GATE-USAGE-v1).
+ *
+ * Pricing scales with what the gate actually protects: PROTECTED IRREVERSIBLE
+ * ACTIONS (guarded decisions — allows AND denies both consume enforcement) plus
+ * RECEIPT-YEARS under retention (one receipt kept one year = one receipt-year;
+ * horizons follow retention.js, default 6y = 2190 days). NEVER seats.
+ *
+ * Pure functions over evidence-log entries (`evidence.all()`); no clock, no
+ * network. The billing period is an explicit [periodStart, periodEnd) window —
+ * INCLUSIVE start, EXCLUSIVE end — so adjacent periods never double-count an
+ * entry sitting exactly on a boundary.
+ *
+ * Fail-closed posture for billing: an unbounded or reversed period is refused
+ * (thrown); malformed entries are surfaced in `integrity_warnings` rather than
+ * silently dropped; an entry whose allow flag is not literally `true` is
+ * counted as a deny; a statement over foreign or malformed usage is refused.
+ * `buildUsageStatement` output is deterministic (sorted keys + content hash)
+ * and UNSIGNED — the deployer signs it; the content hash binds that signature
+ * to exactly these numbers for billing reconciliation.
+ */
+import crypto from 'node:crypto';
+
+export const USAGE_VERSION = 'EP-GATE-USAGE-v1';
+
+const DAYS_PER_YEAR = 365;
+// Mirrors retention.js's cold-horizon default (coldDays = 2190 = 6y): a receipt
+// is presumed retained for the full audit horizon unless the entry states its own.
+const DEFAULT_RETENTION_YEARS = 2190 / DAYS_PER_YEAR;
+
+function sha256hex(s) {
+  return crypto.createHash('sha256').update(s).digest('hex');
+}
+
+/** Canonical JSON (recursive sorted keys) — matches evidence.js / @emilia-protocol/verify. */
+function canonical(v) {
+  if (v === null || v === undefined) return JSON.stringify(v);
+  if (Array.isArray(v)) return `[${v.map(canonical).join(',')}]`;
+  if (typeof v === 'object') {
+    return `{${Object.keys(v).sort().map((k) => JSON.stringify(k) + ':' + canonical(v[k])).join(',')}}`;
+  }
+  return JSON.stringify(v);
+}
+
+function toMs(t) {
+  if (t == null) return null;
+  const ms = typeof t === 'number' ? t : Date.parse(t);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+/** Key-sorted copy so output is byte-stable regardless of entry order. */
+function sortedCounts(map) {
+  const out = {};
+  for (const k of Object.keys(map).sort()) out[k] = map[k];
+  return out;
+}
+
+/** Entry-level day resolution (1/365y ≈ 0.00274) without float noise. */
+function round6(x) {
+  return Math.round(x * 1e6) / 1e6;
+}
+
+/**
+ * The retention this entry STATES for itself, in years.
+ * @returns {number|null|NaN} years, `null` when unstated (default applies),
+ *   `NaN` when stated but invalid (default applies + integrity warning — a
+ *   malformed stated value must never silently shrink the metered total).
+ */
+function statedRetentionYears(e) {
+  if (e.retention_years != null) {
+    const y = Number(e.retention_years);
+    return Number.isFinite(y) && y >= 0 ? y : NaN;
+  }
+  if (e.retention_days != null) {
+    const d = Number(e.retention_days);
+    return Number.isFinite(d) && d >= 0 ? d / DAYS_PER_YEAR : NaN;
+  }
+  return null;
+}
+
+/**
+ * Meter a billing period over evidence entries.
+ *
+ * Billable = `kind: 'decision'` entries on GUARDED actions (`not_guarded`
+ * pass-throughs are free; execution records are provenance, not enforcement).
+ * Window is [periodStart, periodEnd): inclusive start, exclusive end.
+ *
+ * @param {Array<object>} entries  evidence.all()
+ * @param {object} o
+ * @param {string|number} o.periodStart  ISO or ms — required
+ * @param {string|number} o.periodEnd    ISO or ms — required, >= periodStart
+ * @param {number} [o.retentionYearsDefault=6]  applied when an entry states no retention
+ * @returns {{protected_actions:number, allows:number, denies:number,
+ *   replays_blocked:number, by_action_type:object, by_tier:object,
+ *   receipt_years:number, period:object, integrity_warnings:object[]}}
+ */
+export function meterUsage(entries = [], { periodStart, periodEnd, retentionYearsDefault = DEFAULT_RETENTION_YEARS } = {}) {
+  const startMs = toMs(periodStart);
+  const endMs = toMs(periodEnd);
+  // An unbounded or reversed period is not meterable — refuse rather than emit
+  // a statement whose window cannot be reconciled.
+  if (startMs == null || endMs == null) {
+    throw new Error('meterUsage: periodStart and periodEnd are required (ISO string or ms)');
+  }
+  if (endMs < startMs) throw new Error('meterUsage: periodEnd must be >= periodStart');
+  if (!Number.isFinite(retentionYearsDefault) || retentionYearsDefault < 0) {
+    throw new Error('meterUsage: retentionYearsDefault must be a finite number >= 0');
+  }
+
+  const warnings = [];
+  const byAction = Object.create(null);
+  const byTier = Object.create(null);
+  let protectedActions = 0;
+  let allows = 0;
+  let denies = 0;
+  let replaysBlocked = 0;
+  let receiptYears = 0;
+
+  entries.forEach((e, index) => {
+    if (!e || typeof e !== 'object' || Array.isArray(e)) {
+      warnings.push({ index, reason: 'not_an_object' });
+      return;
+    }
+    const t = toMs(e.at);
+    if (t == null) {
+      // Unplaceable in ANY period — surfaced, never silently dropped.
+      warnings.push({ index, reason: 'unparseable_at' });
+      return;
+    }
+    if (t < startMs || t >= endMs) return; // outside [start, end)
+    if (typeof e.kind !== 'string' || e.kind.length === 0) {
+      warnings.push({ index, reason: 'missing_kind' });
+      return;
+    }
+    if (e.kind !== 'decision') return; // execution/other records are not billable
+    if (e.reason === 'not_guarded') return; // pass-throughs are free by design
+
+    protectedActions += 1;
+    // Fail closed: only a literal `true` counts as an allow.
+    if (e.allow === true) allows += 1; else denies += 1;
+    if (e.reason === 'replay_refused') replaysBlocked += 1;
+
+    const action = typeof e.action === 'string' && e.action ? e.action : 'unknown';
+    byAction[action] = (byAction[action] || 0) + 1;
+    const tier = typeof e.required_tier === 'string' && e.required_tier ? e.required_tier : 'unknown';
+    byTier[tier] = (byTier[tier] || 0) + 1;
+
+    const stated = statedRetentionYears(e);
+    if (Number.isNaN(stated)) {
+      warnings.push({ index, reason: 'invalid_stated_retention' });
+      receiptYears += retentionYearsDefault;
+    } else {
+      receiptYears += stated ?? retentionYearsDefault;
+    }
+  });
+
+  return {
+    '@version': USAGE_VERSION,
+    period: {
+      start: new Date(startMs).toISOString(),
+      end: new Date(endMs).toISOString(),
+      bounds: 'inclusive_start_exclusive_end',
+    },
+    protected_actions: protectedActions,
+    allows,
+    denies,
+    replays_blocked: replaysBlocked,
+    by_action_type: sortedCounts(byAction),
+    by_tier: sortedCounts(byTier),
+    receipt_years: round6(receiptYears),
+    retention_years_default: retentionYearsDefault,
+    integrity_warnings: warnings,
+  };
+}
+
+/**
+ * Build the signed-ready usage statement handed to billing reconciliation.
+ * UNSIGNED — the deployer signs it; `content_hash` (sha256 over the canonical
+ * JSON of everything else) binds that signature to exactly these numbers.
+ * Deterministic: same usage + org → byte-identical statement, regardless of
+ * the entry order the usage was metered from.
+ */
+export function buildUsageStatement(usage, { org } = {}) {
+  // Never emit a statement over an artifact of a different or unknown format,
+  // and never one that fails to name who it bills.
+  if (!usage || usage['@version'] !== USAGE_VERSION) {
+    throw new Error(`buildUsageStatement: usage must be a ${USAGE_VERSION} object from meterUsage`);
+  }
+  if (!org || typeof org !== 'string') {
+    throw new Error('buildUsageStatement: org is required — a statement must name the billed party');
+  }
+  if (!usage.period || !usage.period.start || !usage.period.end) {
+    throw new Error('buildUsageStatement: usage.period is missing');
+  }
+  for (const k of ['protected_actions', 'allows', 'denies', 'replays_blocked', 'receipt_years']) {
+    if (!Number.isFinite(usage[k]) || usage[k] < 0) {
+      throw new Error(`buildUsageStatement: usage.${k} must be a finite number >= 0`);
+    }
+  }
+  const warningCount = Array.isArray(usage.integrity_warnings) ? usage.integrity_warnings.length : 0;
+  const body = {
+    '@version': USAGE_VERSION,
+    kind: 'usage_statement',
+    org,
+    period: {
+      start: usage.period.start,
+      end: usage.period.end,
+      bounds: 'inclusive_start_exclusive_end',
+    },
+    protected_actions: usage.protected_actions,
+    allows: usage.allows,
+    denies: usage.denies,
+    replays_blocked: usage.replays_blocked,
+    by_action_type: sortedCounts(usage.by_action_type || {}),
+    by_tier: sortedCounts(usage.by_tier || {}),
+    receipt_years: usage.receipt_years,
+    retention_years_default: usage.retention_years_default ?? DEFAULT_RETENTION_YEARS,
+    // Data-quality signal for the reconciler: a statement metered over a log
+    // with integrity warnings is flagged incomplete, never silently clean.
+    integrity_warning_count: warningCount,
+    complete: warningCount === 0,
+  };
+  return { ...body, content_hash: sha256hex(canonical(body)) };
+}
+
+export default { meterUsage, buildUsageStatement, USAGE_VERSION };