drupal-mcp-connector 2.12.0 → 2.13.0

package/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.13.0] - 2026-09-02
+
+### Security
+- **Attributable usage, quotas, and abuse signals on the relay edge (#256).**
+  Optional usage ledger (`MCP_EDGE_USAGE_MAX_RECORDS` / `relay.usage`)
+  records every edge decision (allow or deny) and every fan-down receipt
+  against the grant-resolved tenant and the validated principal, carrying
+  the frame's `requestId`, a `decisionId`, the bound `policyDigest`, and
+  measured cost signals (units, bytes, duration). Optional `auth.quotas`
+  (tenant / principal request windows plus an abuse lock) fails closed at
+  the edge: an unlisted tenant or principal is `not_entitled`, an exhausted
+  window is `429 quota_exceeded` with `Retry-After`, and a principal that
+  keeps earning refusals is `429 abuse_locked` — all with zero frames on any
+  tunnel. A shared tenant window running out never feeds an individual
+  principal's lock; a quota table the edge cannot read refuses startup and
+  names the offending path. A response the listener cannot relay is
+  `502 fan_down_failed` with a `failed` receipt, and a metering failure
+  never changes a verdict. `GET /usage` serves the caller's own tenant
+  partition (tenant from `auth.tenantGrants`; any other tenant is
+  `not_entitled` with no records) with a reconciliation naming `missing`,
+  `duplicate`, and `uncertain` chains; unmatched response frames are
+  recorded against the sending tunnel. Omitting both keeps the 2.12.0 path.
+  Lab/loopback only — measured usage, not pricing, billing, a hosted
+  metering sink, or a hosted-service claim.
+
 ## [2.12.0] - 2026-09-02
 
 ### Security
@@ -1393,6 +1418,7 @@ The connector is now **dual-protocol**: every tool runs against an abstract back
 - User tools gained explicit PII-access assertions.
 - Whole tree lint-clean (`npm run lint`) with object-injection sinks rewritten to safe lookups.
 
+[2.13.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.13.0
 [2.12.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.12.0
 [2.11.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.11.0
 [2.10.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.10.1

package/bin/drupal-mcp-edge.js

@@ -32,6 +32,13 @@
  *   MCP_RATE_LIMIT / MCP_RATE_WINDOW_SEC
  *                     Northbound /mcp rate limit (same defaults as the
  *                     primary entry point).
+ *   MCP_EDGE_USAGE_MAX_RECORDS
+ *                     Positive integer enables the in-process usage ledger
+ *                     (or config relay.usage.maxRecords). Every decision and
+ *                     receipt is recorded per tenant and principal, and
+ *                     GET /usage serves the caller's own tenant partition.
+ *                     Unset: nothing is recorded and /usage is 404. Set but
+ *                     unreadable: fatal.
  *
  * Config: auth.grants (client id -> [site names]) is mandatory; the edge
  * refuses to start without it. Optional auth.tenantGrants (client id ->
@@ -41,14 +48,27 @@
  * (sub / azp -> SHA-256 digest) is the expected signed policy on the edge.
  * Optional auth.promotions (digest -> sealed document + two operator ids)
  * is the W&L-operated dual-control ledger; the edge fans eligible bundles
- * to the tenant agent and requires a matching local attestation.
+ * to the tenant agent and requires a matching local attestation. Optional
+ * auth.quotas (tenant / principal request windows plus an abuse lock)
+ * fails closed at the edge with zero frames on any refusal; a table the
+ * edge cannot read refuses startup.
  */
 
 import { readFileSync } from "node:fs";
 import process from "node:process";
-import { getInboundActors, getInboundGrants, getInboundPolicies, getInboundPromotions, getInboundTenantGrants, getTlsConfig, loadConfig } from "../src/lib/config.js";
+import {
+  getInboundActors,
+  getInboundGrants,
+  getInboundPolicies,
+  getInboundPromotions,
+  getInboundQuotas,
+  getInboundTenantGrants,
+  getTlsConfig,
+  loadConfig,
+} from "../src/lib/config.js";
 import { resolveInboundAuthConfig } from "../src/lib/http-auth.js";
 import { createRateLimiter } from "../src/lib/rate-limit.js";
+import { createUsageLedger } from "../src/lib/usage.js";
 import {
   createChannelCredentialStore,
   startEdge,
@@ -126,6 +146,29 @@ const rateLimit = rateLimitEnv === undefined || rateLimitEnv === ""
   ? rateLimitDefault
   : Number(rateLimitEnv);
 
+// Usage ledger (#256): opt-in, in-process, bounded. A restart clears it.
+// A value that is set but unreadable is fatal: the operator asked for
+// metering, and silently running without it would be a lie.
+const usageEnv = process.env.MCP_EDGE_USAGE_MAX_RECORDS;
+const usageRaw = usageEnv !== undefined && usageEnv !== ""
+  ? usageEnv
+  : config.relay?.usage?.maxRecords;
+let usageMaxRecords = 0;
+if (usageRaw !== undefined && usageRaw !== null) {
+  const parsed = typeof usageRaw === "string" && /^[0-9]+$/.test(usageRaw.trim())
+    ? Number(usageRaw.trim())
+    : usageRaw;
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    fatal(
+      "MCP_EDGE_USAGE_MAX_RECORDS (or relay.usage.maxRecords) must be a positive "
+      + `integer; got ${JSON.stringify(usageRaw)}. Unset it to run without the usage ledger.`,
+    );
+  }
+  usageMaxRecords = parsed;
+}
+const usage = usageMaxRecords > 0 ? createUsageLedger({ maxRecords: usageMaxRecords }) : null;
+const quotas = getInboundQuotas();
+
 let edge;
 try {
   edge = await startEdge({
@@ -135,6 +178,8 @@ try {
     actors: getInboundActors(),
     policies: getInboundPolicies(),
     promotions: getInboundPromotions(),
+    quotas,
+    usage,
     sites,
     defaultSite: config.defaultSite,
     channelCredentials: createChannelCredentialStore({ filePath: channelFile }),
@@ -162,3 +207,11 @@ if (rateLimit > 0) {
     `[drupal-mcp-edge] Rate limiting: ${rateLimit} req / ${rateWindowSec}s per client IP on /mcp.`,
   );
 }
+if (usage) {
+  console.error(
+    `[drupal-mcp-edge] Usage ledger: in-process, ${usageMaxRecords} records max; GET /usage serves one tenant partition.`,
+  );
+}
+if (quotas) {
+  console.error("[drupal-mcp-edge] Quotas: auth.quotas in force; unlisted tenants / principals are refused.");
+}

package/config/config.example.json

@@ -44,6 +44,9 @@
     "promotions": {
       "_comment": "Optional W&L-operated dual-control ledger. Map a SHA-256 digest to { document, approvals } where document is the sealed portable Sentinel bundle (claims + digest + hmac-sha256 seal) and approvals is two distinct operator ids. When present, the edge fans eligible documents to the tenant agent; non-diagnostic tools/call require a matching local attestation. The edge never mints a seal. Omit to keep the digest-only path. Tenant self-service is not this table."
     },
+    "quotas": {
+      "_comment": "Optional, drupal-mcp-edge only. { tenants: { \"<agent id>\": { requests, windowSec } }, principals: { \"<sub or client_id>\": { requests, windowSec } }, abuse: { denials, windowSec, lockSec } }. When a tenants or principals table names any id, an id without a row is not_entitled; an exhausted window is 429 quota_exceeded with Retry-After; a principal that earns `denials` refusals inside windowSec is 429 abuse_locked for lockSec. Every refusal is zero frames on any tunnel. A shared tenant window running out never feeds an individual principal's abuse lock. A table the edge cannot read refuses startup and names the offending path. Omit to keep the prior path (no quota at the edge). Counting is measured usage, not pricing."
+    },
     "revocationFile": "",
     "introspectionUrl": "",
     "introspectionClientIdEnv": "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
   "type": "module",
   "main": "src/index.js",

package/src/lib/config.js

@@ -308,6 +308,30 @@ export function getInboundPromotions() {
   return entries.length ? Object.fromEntries(entries) : null;
 }
 
+/**
+ * Tenant / principal quota table plus abuse lock (`auth.quotas`).
+ * When present, the relay edge fails closed: a tenant or principal without
+ * a row is refused, exhausted windows and locked principals are refused,
+ * and a table the edge cannot read refuses startup. Validation lives in
+ * usage.js (`normalizeQuotas`).
+ * @returns {object|null|unknown} Null when omitted or comment-only; the
+ *   comment-stripped table when it is an object; otherwise the configured
+ *   value unchanged (a string, array, number, ...) so `startEdge()` refuses
+ *   to start on it instead of running unmetered.
+ */
+export function getInboundQuotas() {
+  const quotas = loadConfig().auth?.quotas;
+  if (quotas === undefined || quotas === null) return null;
+  // A present value that is not an object is passed through unchanged so
+  // the edge refuses to start on it (usage.js normalizeQuotas names it);
+  // returning null here would silently run without quotas.
+  if (typeof quotas !== "object" || Array.isArray(quotas)) return quotas;
+  const entries = Object.entries(quotas)
+    .map(([key, value]) => [key.trim(), value])
+    .filter(([key]) => key && !key.startsWith("_"));
+  return entries.length ? Object.fromEntries(entries) : null;
+}
+
 // ---------------------------------------------------------------------------
 // Auth headers — never logged, never exposed in tool responses
 // ---------------------------------------------------------------------------

package/src/lib/relay/edge.js

@@ -1,7 +1,8 @@
 /**
- * Relay northbound edge (#232, #242, #244, #247, #250, #253) — DEV-294 AC4,
- * DEV-122 isolation, DEV-124 tenant routing, DEV-123 actor mapping, DEV-125
- * policy digest and W&L-operated bundle promotion.
+ * Relay northbound edge (#232, #242, #244, #247, #250, #253, #256) — DEV-294
+ * AC4, DEV-122 isolation, DEV-124 tenant routing, DEV-123 actor mapping,
+ * DEV-125 policy digest and W&L-operated bundle promotion, DEV-126
+ * attributable usage, quotas, and abuse signals.
  *
  * Terminates northbound MCP over the OAuth resource server and fans requests
  * down outbound tenant-agent channels. The edge proposes; the tenant-side
@@ -27,6 +28,11 @@
  *     no `Mcp-Session-Id` crosses in either direction.
  *   - Revocation is per-request with no grace window, for both credential
  *     kinds (northbound principal, agent channel).
+ *   - Metering is optional and fail-closed. With a `usage` ledger every
+ *     decision and receipt is recorded against the grant-resolved tenant and
+ *     the validated principal; with `auth.quotas` a tenant or principal
+ *     without a row, an exhausted window, or a locked principal is refused
+ *     with zero frames. `GET /usage` serves one tenant partition only.
  */
 
 import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
@@ -36,7 +42,11 @@ import { createServer as createHttpsServer } from "node:https";
 import { createServer as createNetServer } from "node:net";
 import { createServer as createTlsServer } from "node:tls";
 import { createLocalRelay } from "../contracts/relay.js";
-import { createInboundHttpsAuth, SPOOFABLE_IDENTITY_HEADERS } from "../http-auth.js";
+import {
+  createInboundHttpsAuth,
+  formatWwwAuthenticate,
+  SPOOFABLE_IDENTITY_HEADERS,
+} from "../http-auth.js";
 import { createLegacySessionHandler, createMcpRequestHandler } from "../http-handler.js";
 import { isWriteLikeCall } from "../operations.js";
 import {
@@ -46,6 +56,13 @@ import {
   resolveEligiblePromotion,
 } from "../policy-promotion.js";
 import { DIAGNOSTIC_TOOLS, resolveActor, resolveGrantedSites, resolvePolicy } from "../principal.js";
+import {
+  attributedTenant,
+  createQuotaGate,
+  readUsage,
+  reconcileUsage,
+  usagePrincipalKey,
+} from "../usage.js";
 import {
   attachFramer,
   createRequestBroker,
@@ -93,6 +110,16 @@ const SITE_CREDENTIAL_KEYS = Object.freeze([
 
 const DEFAULT_FAN_DOWN_TIMEOUT_MS = 10_000;
 
+/** Post-authentication refusals that count toward a principal's abuse lock. */
+const ABUSE_SIGNAL_ERRORS = new Set(["not_entitled", "quota_exceeded"]);
+
+/**
+ * Refusal scopes that describe something other than the caller's own
+ * behaviour — a shared tenant window, or a table the operator misconfigured.
+ * They never feed a principal's abuse lock.
+ */
+const SHARED_SCOPES = new Set(["tenant", "config"]);
+
 /**
  * Normalize a channel-record `sites` list. Empty / missing means unscoped
  * (legal only as the sole connected agent — the DEV-294 compatibility path).
@@ -458,11 +485,16 @@ function assertBindAllowed(role, host, hasTls) {
   }
 }
 
-function jsonResponse(res, status, body) {
-  res.writeHead(status, { "content-type": "application/json" })
+function jsonResponse(res, status, body, headers = {}) {
+  res.writeHead(status, { ...headers, "content-type": "application/json" })
     .end(JSON.stringify(body));
 }
 
+function byteLength(value) {
+  if (value === null || value === undefined) return 0;
+  return Buffer.byteLength(typeof value === "string" ? value : JSON.stringify(value), "utf8");
+}
+
 /**
  * Start the relay edge: an authenticated northbound MCP listener and the
  * agent channel listener the tenant dials into.
@@ -489,6 +521,14 @@ function jsonResponse(res, status, body) {
  * @param {number} [options.agentPort] Agent channel port (0 = ephemeral).
  * @param {{cert: string|Buffer, key: string|Buffer}} [options.tls]
  * @param {boolean} [options.allowHttpLoopback] Permit plain listeners on loopback.
+ * @param {object|null} [options.quotas] Optional `auth.quotas` (tenant /
+ *   principal windows plus an abuse lock). When present, a tenant or
+ *   principal without a row is refused; exhausted windows and locked
+ *   principals are refused with `Retry-After`. Zero frames on any refusal.
+ * @param {?object} [options.usage] Optional usage ledger (usage.js). When
+ *   present, every decision and receipt is recorded and `GET /usage` serves
+ *   the caller's tenant partition. Omit to record nothing (404 on /usage).
+ * @param {() => number} [options.now] Clock for quotas and cost signals.
  * @param {?object} [options.rateLimiter] Optional rate limiter (rate-limit.js).
  * @param {number} [options.fanDownTimeoutMs]
  * @param {typeof fetch} [options.fetchFn] Issuer discovery/JWKS fetch.
@@ -511,6 +551,9 @@ export async function startEdge({
   agentPort = 0,
   tls = null,
   allowHttpLoopback = false,
+  quotas = null,
+  usage = null,
+  now = () => Date.now(),
   rateLimiter = null,
   fanDownTimeoutMs = DEFAULT_FAN_DOWN_TIMEOUT_MS,
   fetchFn = fetch,
@@ -541,6 +584,39 @@ export async function startEdge({
     ? promotions
     : null;
   const promoRequired = promotionsRequired(promotionTable);
+  const quotaGate = createQuotaGate({ quotas, now });
+  if (quotaGate.invalid) {
+    throw new EdgeStartupError(
+      `Relay edge refuses to start: auth.quotas is not readable at "${quotaGate.reason}". `
+      + "A quota table that cannot be read authorizes nobody; fix the row or remove the table.",
+    );
+  }
+  const usageLedger = usage === null || usage === undefined ? null : usage;
+  if (usageLedger !== null && (
+    typeof usageLedger !== "object"
+    || typeof usageLedger.record !== "function"
+    || typeof usageLedger.query !== "function"
+    || typeof usageLedger.stats !== "function"
+  )) {
+    throw new EdgeStartupError(
+      "Relay edge usage ledger must expose record(), query(), and stats() "
+      + "(see createUsageLedger in usage.js), or be omitted.",
+    );
+  }
+
+  /**
+   * Record without ever changing the verdict: a metering failure is logged
+   * (without the error detail) and the request proceeds as decided.
+   */
+  function meter(entry) {
+    if (!usageLedger) return null;
+    try {
+      return usageLedger.record(entry) ?? null;
+    } catch {
+      console.error("[drupal-mcp-edge] usage record failed; the decision stands and is unmetered.");
+      return null;
+    }
+  }
   if (typeof channelCredentials?.lookup !== "function") {
     throw new EdgeStartupError(
       "Relay edge requires an agent channel credential store; without one no "
@@ -637,7 +713,24 @@ export async function startEdge({
         return;
       }
       if (frame.type === "mcp-response") {
-        broker.settle(frame, { owner: agentId });
+        const settled = broker.settle(frame, { owner: agentId });
+        if (!settled && usageLedger) {
+          // A response nobody is waiting for: late, repeated, fabricated, or
+          // injected from another tenant's tunnel. Recorded against the
+          // sending tunnel so reconciliation and abuse signals can see it.
+          meter({
+            phase: "receipt",
+            requestId: typeof frame.id === "string" && frame.id ? frame.id : null,
+            decisionId: null,
+            tenant: agentId,
+            principalKey: null,
+            outcome: "unknown",
+            reason: "unmatched_receipt",
+            status: Number.isInteger(frame.status) ? frame.status : null,
+            bytesOut: byteLength(frame.body),
+            durationMs: null,
+          });
+        }
         return;
       }
       // Any other frame type on the agent channel is a protocol violation.
@@ -661,11 +754,57 @@ export async function startEdge({
       return;
     }
 
+    // Attribution context (#256): who this is, which tenant the grant names,
+    // and what it cost. Stamped on every decision, allow or deny. Caller
+    // fields never reach it — the identity object and grant tables do.
+    const startedAt = now();
+    const isCall = body?.method === "tools/call";
+    const toolName = isCall && typeof body?.params?.name === "string" && body.params.name.trim()
+      ? body.params.name.trim()
+      : null;
+    const principalKey = usagePrincipalKey(identity);
+    const principal = Object.freeze({
+      clientId: identity.clientId ?? null,
+      sub: identity.sub ?? null,
+    });
+    const bytesIn = byteLength(body);
+    let usageTenant = attributedTenant(identity, tenantGrantTable);
+    let policyDigest = null;
+
+    function refuse(status, error, {
+      scope = null, exposeScope = true, retryAfterSec = 0, extra = {},
+    } = {}) {
+      if (ABUSE_SIGNAL_ERRORS.has(error) && !SHARED_SCOPES.has(scope)) {
+        quotaGate.noteDenial(principalKey);
+      }
+      meter({
+        phase: "decision",
+        decision: "deny",
+        reason: error,
+        scope,
+        requestId: null,
+        tenant: usageTenant,
+        principal,
+        principalKey,
+        method: body?.method ?? null,
+        tool: toolName,
+        policyDigest,
+        units: 1,
+        bytesIn,
+      });
+      jsonResponse(
+        res,
+        status,
+        { error, ...(scope && exposeScope ? { scope } : {}), ...extra },
+        retryAfterSec > 0 ? { "Retry-After": String(retryAfterSec) } : {},
+      );
+    }
+
     // Entitlement at the seam, before anything about the tenant is revealed:
     // an unlisted client learns nothing, not even whether an agent exists.
     const granted = resolveGrantedSites(identity, catalog, grantTable);
     if (!granted.length) {
-      jsonResponse(res, 403, { error: "not_entitled" });
+      refuse(403, "not_entitled");
       return;
     }
     const args = body?.params?.arguments ?? {};
@@ -673,34 +812,31 @@ export async function startEdge({
     const siteArgs = { ...args };
     delete siteArgs.tenant;
     let targetName = null;
-    if (body?.method === "tools/call") {
+    if (isCall) {
       try {
         targetName = targetRelay.resolve(identity, siteArgs).name;
       } catch {
-        jsonResponse(res, 403, { error: "not_entitled" });
+        refuse(403, "not_entitled");
         return;
       }
     }
 
     const mapped = resolveActor({ identity, actors: actorTable });
     const boundPolicy = resolvePolicy({ identity, policies: policyTable });
-    const isCall = body?.method === "tools/call";
-    const toolName = isCall && typeof body?.params?.name === "string" && body.params.name.trim()
-      ? body.params.name.trim()
-      : null;
+    policyDigest = boundPolicy.policy ?? null;
     if (mapped.required && mapped.reason && isCall && (!toolName || isWriteLikeCall(toolName, args))) {
-      jsonResponse(res, 403, { error: "not_entitled" });
+      refuse(403, "not_entitled");
       return;
     }
     const policyCall = isCall && (!toolName || !DIAGNOSTIC_TOOLS.has(toolName));
     if (
       boundPolicy.required && boundPolicy.reason && policyCall
     ) {
-      jsonResponse(res, 403, { error: "not_entitled" });
+      refuse(403, "not_entitled");
       return;
     }
     if (promoRequired && policyCall && !boundPolicy.policy) {
-      jsonResponse(res, 403, { error: "not_entitled" });
+      refuse(403, "not_entitled");
       return;
     }
 
@@ -712,6 +848,30 @@ export async function startEdge({
       targetName,
       sessions: [...sessions.values()],
     });
+    if (selected.tenant) usageTenant = selected.tenant;
+    if (!selected.session && selected.reason === "not_entitled") {
+      refuse(403, "not_entitled");
+      return;
+    }
+    if (!selected.session && !selected.tenant) {
+      // Site-derived path with no agent: there is no tenant to meter against,
+      // so this is an outage answer, not a quota or abuse signal.
+      refuse(503, "no_agent");
+      return;
+    }
+    // Quota boundary (#256): the tenant is now grant-resolved. Every request
+    // reaching this line counts; a tenant or principal without a row, an
+    // exhausted window, or a locked principal is refused with zero frames.
+    const verdict = quotaGate.check({ tenant: selected.tenant, principalKey });
+    if (!verdict.allowed) {
+      const unassigned = verdict.reason === "not_entitled";
+      refuse(unassigned ? 403 : 429, verdict.reason, {
+        scope: verdict.scope,
+        exposeScope: !unassigned,
+        retryAfterSec: verdict.retryAfterSec,
+      });
+      return;
+    }
     if (promoRequired && policyCall) {
       const promo = resolveEligiblePromotion({
         digest: boundPolicy.policy,
@@ -719,25 +879,22 @@ export async function startEdge({
       });
       const attested = selected.session?.attestedDigests;
       if (!promo.eligible || !attested || !attested.has(boundPolicy.policy)) {
-        jsonResponse(res, 403, { error: "not_entitled" });
+        refuse(403, "not_entitled");
         return;
       }
     }
     if (!selected.session) {
-      const entitled = selected.reason === "not_entitled";
-      jsonResponse(res, entitled ? 403 : 503, {
-        error: entitled ? "not_entitled" : "no_agent",
-      });
+      refuse(503, "no_agent");
       return;
     }
     const record = channelCredentials.lookup(selected.session.token);
     if (!record || record.revoked) {
-      jsonResponse(res, 403, { error: "revoked", bound: EDGE_REVOCATION_BOUND.name });
+      refuse(403, "revoked", { extra: { bound: EDGE_REVOCATION_BOUND.name } });
       return;
     }
     if (siteBindingKey(record.sites) !== siteBindingKey(selected.session.sites)) {
       selected.session.socket.destroy();
-      jsonResponse(res, 503, { error: "no_agent" });
+      refuse(503, "no_agent");
       return;
     }
 
@@ -769,14 +926,55 @@ export async function startEdge({
     });
     if (!wrote) {
       broker.settle({ id, status: 503 }, { owner: selected.session.agentId });
-      jsonResponse(res, 503, { error: "no_agent" });
+      refuse(503, "no_agent");
       return;
     }
+    const decisionRecord = meter({
+      phase: "decision",
+      decision: "allow",
+      reason: null,
+      requestId: id,
+      tenant: selected.tenant,
+      principal,
+      principalKey,
+      method: body?.method ?? null,
+      tool: toolName,
+      target: selected.target ?? null,
+      actor: mapped.actor ?? null,
+      policyDigest,
+      units: 1,
+      bytesIn,
+    });
+
+    function receipt(fields) {
+      meter({
+        phase: "receipt",
+        requestId: id,
+        decisionId: decisionRecord?.decisionId ?? null,
+        tenant: selected.tenant,
+        principalKey,
+        durationMs: Math.max(0, now() - startedAt),
+        ...fields,
+      });
+    }
 
     let result;
     try {
       result = await waited;
     } catch {
+      // The frame crossed; no settled response came back. The tenant may
+      // have executed it — reconciliation names this chain uncertain.
+      receipt({ outcome: "unknown", reason: "fan_down_failed", status: null, bytesOut: 0 });
+      jsonResponse(res, 502, { error: "fan_down_failed" });
+      return;
+    }
+    // The agent frame is unvalidated input. A status the northbound
+    // listener cannot emit, or a header it refuses, is a failed receipt and
+    // a 502 — never an "ok" receipt for a response nobody received.
+    const status = result.status;
+    const bytesOut = byteLength(result.body);
+    if (!Number.isInteger(status) || status < 100 || status > 999) {
+      receipt({ outcome: "failed", reason: "invalid_status", status: null, bytesOut });
       jsonResponse(res, 502, { error: "fan_down_failed" });
       return;
     }
@@ -784,8 +982,86 @@ export async function startEdge({
       Object.entries(forwardHeaders(result.headers ?? {}))
         .filter(([name]) => String(name).toLowerCase() !== "mcp-session-id"),
     );
-    res.writeHead(result.status || 200, headers);
+    try {
+      res.writeHead(status, headers);
+    } catch {
+      receipt({ outcome: "failed", reason: "relay_write_failed", status, bytesOut });
+      if (!res.headersSent) {
+        for (const name of res.getHeaderNames()) res.removeHeader(name);
+        jsonResponse(res, 502, { error: "fan_down_failed" });
+      } else {
+        res.destroy();
+      }
+      return;
+    }
     res.end(result.body ?? "");
+    receipt({ outcome: status >= 500 ? "failed" : "ok", reason: null, status, bytesOut });
+  }
+
+  /**
+   * `GET /usage` — the caller's own tenant partition (#256). Authenticated
+   * on the same resource server as `/mcp`; the tenant comes from
+   * `auth.tenantGrants`, a `tenant` query value is a confirming hint, and
+   * any other tenant is `not_entitled` with no records. 404 without a ledger.
+   */
+  async function serveUsage(req, res) {
+    if (!usageLedger) {
+      res.writeHead(404).end("Not found");
+      return;
+    }
+    if (req.method !== "GET") {
+      res.writeHead(405, { Allow: "GET" }).end("Method Not Allowed");
+      return;
+    }
+    if (rateLimiter) {
+      const verdict = rateLimiter.check(req.socket?.remoteAddress || "unknown");
+      if (!verdict.allowed) {
+        res.writeHead(429, { "Retry-After": String(verdict.retryAfterSec) }).end("Too Many Requests");
+        return;
+      }
+    }
+    let auth;
+    try {
+      auth = await inbound.authenticate(req);
+    } catch {
+      res.writeHead(401, {
+        "WWW-Authenticate": formatWwwAuthenticate({
+          error: "invalid_token",
+          errorDescription: "Token validation failed",
+        }),
+      }).end("Unauthorized");
+      return;
+    }
+    if (!auth.ok) {
+      res.writeHead(auth.status, auth.headers).end(auth.body);
+      return;
+    }
+    try {
+      const query = new URL(String(req.url || "/usage"), "http://edge.invalid").searchParams;
+      const read = readUsage({
+        identity: auth.identity,
+        tenantGrants: tenantGrantTable,
+        tenant: query.get("tenant"),
+        principalKey: query.get("principal"),
+        ledger: usageLedger,
+      });
+      if (!read.ok) {
+        jsonResponse(res, 403, { error: "not_entitled" });
+        return;
+      }
+      jsonResponse(res, 200, {
+        tenant: read.tenant,
+        records: read.records,
+        reconciliation: reconcileUsage(read.records, { dropped: usageLedger.stats().dropped }),
+      });
+    } catch {
+      console.error("[drupal-mcp-edge] usage read failed.");
+      if (res.headersSent) {
+        res.destroy();
+        return;
+      }
+      res.writeHead(500).end("Internal Server Error");
+    }
   }
 
   const requestHandler = createMcpRequestHandler({
@@ -804,9 +1080,16 @@ export async function startEdge({
     rateLimiter,
   });
 
+  function northbound(req, res) {
+    if (String(req.url || "").split("?")[0] === "/usage") {
+      void serveUsage(req, res);
+      return;
+    }
+    void requestHandler(req, res);
+  }
   const northServer = hasTls
-    ? createHttpsServer(tls, (req, res) => { void requestHandler(req, res); })
-    : createHttpServer((req, res) => { void requestHandler(req, res); });
+    ? createHttpsServer(tls, northbound)
+    : createHttpServer(northbound);
 
   const channelAddr = await listen(channelServer, agentBindHost, agentPort, "edge-agent-channel");
   const northAddr = await listen(northServer, bindHost, port, "edge-northbound");

package/src/lib/usage.js

@@ -0,0 +1,611 @@
+/**
+ * Attributable usage, quotas, and abuse signals on the relay edge (#256 /
+ * DEV-126).
+ *
+ * Metering at the seam, lab bounds. Every edge decision (allow or deny) and
+ * every fan-down receipt is a record keyed by the grant-resolved tenant and
+ * the validated principal, carrying the request / decision / receipt ids the
+ * frame already stamps. Quotas fail closed at this boundary: a tenant or
+ * principal without a row is refused, an exhausted window is refused, and a
+ * principal that keeps earning denials is locked. Cost signals are measured
+ * (units, bytes, duration), never priced — pricing and invoicing are not this
+ * module.
+ *
+ * Nothing here is a hosted metering sink. The ledger is in-process and
+ * bounded; a restart clears it, and `reconcileUsage` says so when it dropped
+ * rows. Caller-supplied tenant / principal fields are never authority: the
+ * edge attributes from its own identity object and grant tables.
+ */
+
+import { randomUUID } from "node:crypto";
+import { createRateLimiter } from "./rate-limit.js";
+
+/** Record phases. A denied decision never has a receipt. */
+export const USAGE_PHASES = Object.freeze(["decision", "receipt"]);
+
+/** Decision vocabulary at the edge. */
+export const USAGE_DECISIONS = Object.freeze(["allow", "deny"]);
+
+/**
+ * Receipt outcomes. `unknown` means the frame crossed but no settled
+ * response came back — the tenant may have executed the request.
+ */
+export const RECEIPT_OUTCOMES = Object.freeze(["ok", "failed", "unknown"]);
+
+/** Reconciliation states over one request / decision / receipt chain. */
+export const RECONCILE_STATES = Object.freeze([
+  "settled",
+  "denied",
+  "missing",
+  "duplicate",
+  "uncertain",
+]);
+
+const PHASE_SET = new Set(USAGE_PHASES);
+const DECISION_SET = new Set(USAGE_DECISIONS);
+const OUTCOME_SET = new Set(RECEIPT_OUTCOMES);
+
+const DEFAULT_WINDOW_SEC = 60;
+const DEFAULT_LOCK_SEC = 300;
+const DEFAULT_MAX_RECORDS = 10_000;
+const DEFAULT_MAX_KEYS = 10_000;
+
+function cleanKey(value) {
+  const key = typeof value === "string" ? value.trim() : "";
+  return key && !key.startsWith("_") ? key : "";
+}
+
+function positiveInt(value) {
+  return Number.isInteger(value) && value > 0 ? value : null;
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function grantIds(values) {
+  if (!Array.isArray(values)) return [];
+  return [...new Set(values.map((value) => cleanKey(value)).filter(Boolean))];
+}
+
+function identityValue(value) {
+  return typeof value === "string" && value ? value : null;
+}
+
+/**
+ * Principal partition key: inbound `sub`, then `azp` / client id, exactly
+ * as the issuer minted them. Matches the precedence and the raw-value
+ * convention of `auth.actors` / `auth.policies` / `resolveTenantRoute`:
+ * config keys are trimmed, identity values are not, so a padded claim never
+ * matches a row and fails closed. Never a caller field.
+ *
+ * @param {object|null} identity
+ * @returns {string|null}
+ */
+export function usagePrincipalKey(identity) {
+  if (!isRecord(identity)) return null;
+  return identityValue(identity.sub) ?? identityValue(identity.clientId);
+}
+
+/**
+ * Tenant a principal's usage is attributed to when the edge has not yet
+ * routed (early denials): the unique tenant its grant names, else null.
+ * Attribution only — routing authority stays with `resolveTenantRoute`.
+ *
+ * @param {object|null} identity
+ * @param {object|null} tenantGrants
+ * @returns {string|null}
+ */
+export function attributedTenant(identity, tenantGrants) {
+  if (!isRecord(identity) || !isRecord(tenantGrants)) return null;
+  const clientId = typeof identity.clientId === "string" ? identity.clientId : "";
+  if (!clientId) return null;
+  const granted = grantIds(new Map(Object.entries(tenantGrants)).get(clientId));
+  return granted.length === 1 ? granted[0] : null;
+}
+
+const QUOTA_KEYS = new Set(["tenants", "principals", "abuse"]);
+
+function invalid(reason) {
+  return Object.freeze({ invalid: true, reason });
+}
+
+/**
+ * @returns {{rows: object, required: boolean}|{invalid: true, reason: string}}
+ */
+function quotaRows(raw, name) {
+  if (raw === undefined || raw === null) return { rows: Object.freeze({}), required: false };
+  if (!isRecord(raw)) return invalid(name);
+  const entries = [];
+  for (const [rawKey, value] of Object.entries(raw)) {
+    const key = cleanKey(rawKey);
+    if (!key) continue;
+    if (!isRecord(value)) return invalid(`${name}.${key}`);
+    const requests = positiveInt(value.requests);
+    if (requests === null) return invalid(`${name}.${key}.requests`);
+    const windowSec = value.windowSec === undefined
+      ? DEFAULT_WINDOW_SEC
+      : positiveInt(value.windowSec);
+    if (windowSec === null) return invalid(`${name}.${key}.windowSec`);
+    entries.push([key, Object.freeze({ requests, windowSec })]);
+  }
+  return { rows: Object.freeze(Object.fromEntries(entries)), required: entries.length > 0 };
+}
+
+function abuseBlock(raw) {
+  if (raw === undefined || raw === null) return null;
+  if (!isRecord(raw)) return invalid("abuse");
+  const denials = positiveInt(raw.denials);
+  if (denials === null) return invalid("abuse.denials");
+  const windowSec = raw.windowSec === undefined ? DEFAULT_WINDOW_SEC : positiveInt(raw.windowSec);
+  if (windowSec === null) return invalid("abuse.windowSec");
+  const lockSec = raw.lockSec === undefined ? DEFAULT_LOCK_SEC : positiveInt(raw.lockSec);
+  if (lockSec === null) return invalid("abuse.lockSec");
+  return Object.freeze({ denials, windowSec, lockSec });
+}
+
+/**
+ * Normalize `auth.quotas`.
+ *
+ * Shape: `{ tenants: { "<agentId>": { requests, windowSec? } },
+ * principals: { "<sub|azp>": { requests, windowSec? } },
+ * abuse: { denials, windowSec?, lockSec? } }`. Comment keys are ignored.
+ * Anything else that is not exactly that shape — a table that is not an
+ * object, an unknown key, a sub-table that is not an object, a row with a
+ * non-positive-integer `requests` / `windowSec`, a malformed `abuse` block
+ * — makes the whole table **invalid**, never "omitted": the gate then
+ * refuses everything and the edge refuses to start. Only `null` /
+ * `undefined` (absent) and a comment-only object mean "omitted". A sub-table that names any id is *required*,
+ * so an id without a row fails closed.
+ *
+ * @param {object|null} raw
+ * @returns {object|null} Null when the table is omitted or comment-only;
+ *   `{ invalid: true, reason }` naming the offending path; else the table.
+ */
+export function normalizeQuotas(raw) {
+  if (raw === null || raw === undefined) return null;
+  if (!isRecord(raw)) return invalid("quotas");
+  for (const rawKey of Object.keys(raw)) {
+    const key = cleanKey(rawKey);
+    if (key && !QUOTA_KEYS.has(key)) return invalid(key);
+  }
+  const bag = new Map(Object.entries(raw));
+  const tenants = quotaRows(bag.get("tenants"), "tenants");
+  if (tenants.invalid) return tenants;
+  const principals = quotaRows(bag.get("principals"), "principals");
+  if (principals.invalid) return principals;
+  const abuse = abuseBlock(bag.get("abuse"));
+  if (abuse?.invalid) return abuse;
+  if (!tenants.required && !principals.required && abuse === null) return null;
+  return Object.freeze({
+    tenants: tenants.rows,
+    tenantsRequired: tenants.required,
+    principals: principals.rows,
+    principalsRequired: principals.required,
+    abuse,
+  });
+}
+
+/**
+ * Whether a quota table is in force (fail-closed even when every row is
+ * malformed).
+ *
+ * @param {object|null} raw
+ * @returns {boolean}
+ */
+export function quotasRequired(raw) {
+  return normalizeQuotas(raw) !== null;
+}
+
+/**
+ * Quota and abuse gate. Fixed windows per tenant and per principal, plus a
+ * denial counter that locks a principal. Every request reaching the window
+ * checks counts whether or not it is then allowed, so a flood of refused
+ * requests cannot probe for free; a request refused by the abuse lock is
+ * refused before the windows and does not drain the tenant's shared one.
+ *
+ * @param {object} [options]
+ * @param {object|null} [options.quotas] Raw `auth.quotas`.
+ * @param {() => number} [options.now]
+ * @param {number} [options.maxKeys] Soft cap on tracked principals in the
+ *   abuse table; expired entries are pruned first, then the oldest.
+ * @returns {{enabled: boolean, check: Function, noteDenial: Function, state: Function, stats: Function}}
+ */
+export function createQuotaGate({
+  quotas = null,
+  now = () => Date.now(),
+  maxKeys = DEFAULT_MAX_KEYS,
+} = {}) {
+  const table = normalizeQuotas(quotas);
+  if (!table) {
+    return Object.freeze({
+      enabled: false,
+      invalid: false,
+      reason: null,
+      check: () => ({ allowed: true }),
+      noteDenial: () => ({ locked: false }),
+      state: () => ({ locked: false, retryAfterSec: 0, denials: 0 }),
+      stats: () => ({ trackedPrincipals: 0, maxKeys: 0 }),
+    });
+  }
+  if (table.invalid) {
+    // A quota table that cannot be read authorizes nobody. The edge refuses
+    // to start on this; the gate refuses every request as defense in depth.
+    return Object.freeze({
+      enabled: true,
+      invalid: true,
+      reason: table.reason,
+      check: () => ({ allowed: false, reason: "not_entitled", scope: "config", retryAfterSec: 0 }),
+      noteDenial: () => ({ locked: false }),
+      state: () => ({ locked: false, retryAfterSec: 0, denials: 0 }),
+      stats: () => ({ trackedPrincipals: 0, maxKeys: 0 }),
+    });
+  }
+
+  function limiters(rows) {
+    return new Map(Object.entries(rows).map(([id, row]) => [
+      id,
+      createRateLimiter({ limit: row.requests, windowMs: row.windowSec * 1000, now }),
+    ]));
+  }
+  const tenantLimiters = limiters(table.tenants);
+  const principalLimiters = limiters(table.principals);
+  const abuse = table.abuse;
+  const keyBound = positiveInt(maxKeys) ?? DEFAULT_MAX_KEYS;
+  /** @type {Map<string, {times: number[], lockedUntil: number}>} */
+  const denials = new Map();
+
+  function live(entry, t) {
+    if (entry.lockedUntil > t) return true;
+    if (entry.lockedUntil) return false;
+    return entry.times.some((ts) => t - ts < abuse.windowSec * 1000);
+  }
+
+  /** Drop expired principals; if still at the bound, drop the oldest. */
+  function prune(t) {
+    for (const [key, entry] of denials) {
+      if (!live(entry, t)) denials.delete(key);
+    }
+    while (denials.size >= keyBound) {
+      const oldest = denials.keys().next().value;
+      if (oldest === undefined) break;
+      denials.delete(oldest);
+    }
+  }
+
+  function deny(reason, scope, retryAfterSec = 0) {
+    return { allowed: false, reason, scope, retryAfterSec };
+  }
+
+  function lockState(key) {
+    if (!abuse || !key) return { locked: false, retryAfterSec: 0, denials: 0 };
+    const entry = denials.get(key);
+    if (!entry) return { locked: false, retryAfterSec: 0, denials: 0 };
+    const t = now();
+    if (entry.lockedUntil > t) {
+      return {
+        locked: true,
+        retryAfterSec: Math.ceil((entry.lockedUntil - t) / 1000),
+        denials: entry.times.length,
+      };
+    }
+    if (entry.lockedUntil) {
+      denials.delete(key);
+      return { locked: false, retryAfterSec: 0, denials: 0 };
+    }
+    entry.times = entry.times.filter((ts) => t - ts < abuse.windowSec * 1000);
+    if (!entry.times.length) denials.delete(key);
+    return { locked: false, retryAfterSec: 0, denials: entry.times.length };
+  }
+
+  return Object.freeze({
+    enabled: true,
+    invalid: false,
+    reason: null,
+
+    /**
+     * The abuse lock is checked first: a locked principal is refused before
+     * the windows and does not consume the tenant's shared window. Every
+     * request that reaches the window checks counts, allowed or not.
+     *
+     * @param {{tenant?: string|null, principalKey?: string|null}} params
+     * @returns {{allowed: true}|{allowed: false, reason: string, scope: string, retryAfterSec: number}}
+     */
+    check({ tenant = null, principalKey = null } = {}) {
+      const key = identityValue(principalKey);
+      const lock = lockState(key);
+      if (lock.locked) return deny("abuse_locked", "abuse", lock.retryAfterSec);
+      if (table.tenantsRequired) {
+        const tenantId = identityValue(tenant);
+        const limiter = tenantId ? tenantLimiters.get(tenantId) : undefined;
+        if (!limiter) return deny("not_entitled", "tenant");
+        const verdict = limiter.check(tenantId);
+        if (!verdict.allowed) return deny("quota_exceeded", "tenant", verdict.retryAfterSec);
+      }
+      if (table.principalsRequired) {
+        const limiter = key ? principalLimiters.get(key) : undefined;
+        if (!limiter) return deny("not_entitled", "principal");
+        const verdict = limiter.check(key);
+        if (!verdict.allowed) return deny("quota_exceeded", "principal", verdict.retryAfterSec);
+      }
+      return { allowed: true };
+    },
+
+    /**
+     * Count one post-authentication denial against a principal.
+     * @param {string|null} principalKey
+     * @returns {{locked: boolean, retryAfterSec?: number}}
+     */
+    noteDenial(principalKey) {
+      if (!abuse) return { locked: false };
+      const key = identityValue(principalKey);
+      if (!key) return { locked: false };
+      const current = lockState(key);
+      if (current.locked) return { locked: true, retryAfterSec: current.retryAfterSec };
+      const entry = denials.get(key) ?? { times: [], lockedUntil: 0 };
+      if (!denials.has(key) && denials.size >= keyBound) prune(now());
+      entry.times.push(now());
+      denials.set(key, entry);
+      if (entry.times.length >= abuse.denials) {
+        entry.lockedUntil = now() + abuse.lockSec * 1000;
+        return { locked: true, retryAfterSec: abuse.lockSec };
+      }
+      return { locked: false };
+    },
+
+    /**
+     * @param {string|null} principalKey
+     * @returns {{locked: boolean, retryAfterSec: number, denials: number}}
+     */
+    state(principalKey) {
+      return lockState(identityValue(principalKey));
+    },
+
+    /** @returns {{trackedPrincipals: number, maxKeys: number}} */
+    stats() {
+      return { trackedPrincipals: denials.size, maxKeys: keyBound };
+    },
+  });
+}
+
+/**
+ * Bounded in-process usage ledger.
+ *
+ * Decision records carry `decision` (`allow` / `deny`), `reason`,
+ * `requestId` (the frame id, only when dispatched), and a `decisionId`.
+ * Receipt records carry `outcome`, `status`, cost signals, the same
+ * `requestId`, and the `decisionId` they settle. Records are frozen.
+ *
+ * @param {object} [options]
+ * @param {() => number} [options.now]
+ * @param {number} [options.maxRecords] Oldest rows are dropped beyond this.
+ * @returns {object}
+ */
+export function createUsageLedger({
+  now = () => Date.now(),
+  maxRecords = DEFAULT_MAX_RECORDS,
+} = {}) {
+  const bound = positiveInt(maxRecords);
+  if (bound === null) {
+    throw new TypeError("createUsageLedger requires maxRecords to be a positive integer.");
+  }
+  const rows = [];
+  let seq = 0;
+  let dropped = 0;
+
+  return {
+    get size() {
+      return rows.length;
+    },
+
+    /**
+     * @param {object} entry
+     * @returns {object} The frozen, stamped record.
+     */
+    record(entry) {
+      if (!isRecord(entry)) throw new TypeError("A usage record must be an object.");
+      const bag = new Map(Object.entries(entry));
+      const phase = bag.get("phase");
+      if (!PHASE_SET.has(phase)) throw new TypeError(`Unknown usage phase: ${String(phase)}`);
+      if (phase === "decision" && !DECISION_SET.has(bag.get("decision"))) {
+        throw new TypeError(`Unknown usage decision: ${String(bag.get("decision"))}`);
+      }
+      if (phase === "receipt" && !OUTCOME_SET.has(bag.get("outcome"))) {
+        throw new TypeError(`Unknown receipt outcome: ${String(bag.get("outcome"))}`);
+      }
+      seq += 1;
+      const existingDecision = bag.get("decisionId");
+      const stamped = {
+        ...entry,
+        seq,
+        at: new Date(now()).toISOString(),
+        decisionId: typeof existingDecision === "string" && existingDecision
+          ? existingDecision
+          : (phase === "decision" ? randomUUID() : null),
+      };
+      if (phase === "receipt") {
+        const existingReceipt = bag.get("receiptId");
+        stamped.receiptId = typeof existingReceipt === "string" && existingReceipt
+          ? existingReceipt
+          : randomUUID();
+      }
+      const frozen = Object.freeze(stamped);
+      rows.push(frozen);
+      if (rows.length > bound) {
+        rows.shift();
+        dropped += 1;
+      }
+      return frozen;
+    },
+
+    /** @returns {object[]} Every retained record, oldest first. */
+    records() {
+      return rows.slice();
+    },
+
+    /**
+     * One tenant partition, optionally narrowed to one principal. A missing
+     * tenant selects nothing — there is no all-tenants read on this surface.
+     *
+     * @param {{tenant?: string|null, principalKey?: string|null}} [params]
+     * @returns {object[]}
+     */
+    query({ tenant = null, principalKey = null } = {}) {
+      const tenantId = typeof tenant === "string" ? tenant.trim() : "";
+      if (!tenantId) return [];
+      const key = typeof principalKey === "string" && principalKey.trim()
+        ? principalKey.trim()
+        : null;
+      return rows.filter((row) => row.tenant === tenantId
+        && (key === null || row.principalKey === key));
+    },
+
+    /** @returns {{size: number, dropped: number, maxRecords: number}} */
+    stats() {
+      return { size: rows.length, dropped, maxRecords: bound };
+    },
+  };
+}
+
+const READ_DENIED = Object.freeze({ ok: false, reason: "not_entitled" });
+
+/**
+ * Tenant-scoped usage read. The tenant is resolved from the caller's
+ * `auth.tenantGrants` row; a `tenant` argument is a confirming hint inside
+ * that grant, never authority. Without a grant table, without a ledger, for
+ * a principal with no grant, for a hint outside the grant, or for a
+ * multi-tenant grant with no hint, the read is `not_entitled` with no
+ * records.
+ *
+ * @param {object} params
+ * @param {object|null} [params.identity]
+ * @param {object|null} [params.tenantGrants]
+ * @param {string|null} [params.tenant]
+ * @param {string|null} [params.principalKey]
+ * @param {object|null} [params.ledger]
+ * @returns {{ok: true, tenant: string, records: object[]}|{ok: false, reason: "not_entitled"}}
+ */
+export function readUsage({
+  identity = null,
+  tenantGrants = null,
+  tenant = null,
+  principalKey = null,
+  ledger = null,
+} = {}) {
+  if (!ledger || typeof ledger.query !== "function") return READ_DENIED;
+  if (!isRecord(identity) || typeof identity.clientId !== "string" || !identity.clientId) {
+    return READ_DENIED;
+  }
+  if (!isRecord(tenantGrants)) return READ_DENIED;
+  const granted = grantIds(new Map(Object.entries(tenantGrants)).get(identity.clientId));
+  if (!granted.length) return READ_DENIED;
+  const hint = typeof tenant === "string" && tenant.trim() ? tenant.trim() : null;
+  if (hint && !granted.includes(hint)) return READ_DENIED;
+  if (!hint && granted.length > 1) return READ_DENIED;
+  const resolved = hint ?? granted[0];
+  const key = typeof principalKey === "string" && principalKey.trim() ? principalKey.trim() : null;
+  return { ok: true, tenant: resolved, records: ledger.query({ tenant: resolved, principalKey: key }) };
+}
+
+/**
+ * Reconcile a set of records into request / decision / receipt chains.
+ *
+ * - `settled`: one allow decision, one receipt, matching tenant and
+ *   decision id, outcome known.
+ * - `denied`: a deny decision (never dispatched; no receipt expected).
+ * - `missing`: a dispatch with no receipt, or a receipt with no dispatch.
+ * - `duplicate`: more than one decision or more than one receipt for a
+ *   request id.
+ * - `uncertain`: the receipt outcome is `unknown`, or the receipt disagrees
+ *   with its decision (tenant or decision id).
+ *
+ * `truncated` is true when the ledger dropped rows; findings may then be
+ * incomplete and must not be read as a clean bill.
+ *
+ * @param {object[]} records
+ * @param {{dropped?: number}} [options]
+ * @returns {{findings: object[], summary: object}}
+ */
+export function reconcileUsage(records, { dropped = 0 } = {}) {
+  const list = Array.isArray(records) ? records : [];
+  const order = [];
+  const groups = new Map();
+
+  for (const row of list) {
+    if (!isRecord(row) || !PHASE_SET.has(row.phase)) continue;
+    if (row.phase === "decision" && row.decision === "deny") {
+      const key = `deny:${row.decisionId ?? order.length}`;
+      order.push(key);
+      groups.set(key, { deny: row });
+      continue;
+    }
+    const requestId = typeof row.requestId === "string" && row.requestId ? row.requestId : null;
+    const key = requestId
+      ? `req:${requestId}`
+      : `orphan:${row.decisionId ?? row.receiptId ?? order.length}`;
+    if (!groups.has(key)) {
+      order.push(key);
+      groups.set(key, { requestId, decisions: [], receipts: [] });
+    }
+    const group = groups.get(key);
+    if (row.phase === "decision") group.decisions.push(row);
+    else group.receipts.push(row);
+  }
+
+  const findings = [];
+  const summary = {
+    total: 0, settled: 0, denied: 0, missing: 0, duplicate: 0, uncertain: 0, truncated: dropped > 0,
+  };
+  const tally = new Map(Object.entries(summary));
+
+  for (const key of order) {
+    const group = groups.get(key);
+    let finding;
+    if (group.deny) {
+      finding = {
+        requestId: group.deny.requestId ?? null,
+        decisionId: group.deny.decisionId ?? null,
+        state: "denied",
+        reason: group.deny.reason ?? null,
+      };
+    } else {
+      const decisionId = group.decisions[0]?.decisionId ?? group.receipts[0]?.decisionId ?? null;
+      let state;
+      let reason;
+      if (group.decisions.length > 1) {
+        state = "duplicate";
+        reason = "duplicate_decision";
+      } else if (group.receipts.length > 1) {
+        state = "duplicate";
+        reason = "duplicate_receipt";
+      } else if (group.decisions.length === 1 && group.receipts.length === 0) {
+        state = "missing";
+        reason = "receipt_missing";
+      } else if (group.decisions.length === 0) {
+        state = "missing";
+        reason = "decision_missing";
+      } else {
+        const decision = group.decisions[0];
+        const receipt = group.receipts[0];
+        if (receipt.outcome === "unknown") {
+          state = "uncertain";
+          reason = typeof receipt.reason === "string" && receipt.reason
+            ? receipt.reason
+            : "outcome_unknown";
+        } else if (receipt.tenant !== decision.tenant || receipt.decisionId !== decision.decisionId) {
+          state = "uncertain";
+          reason = "chain_mismatch";
+        } else {
+          state = "settled";
+          reason = null;
+        }
+      }
+      finding = { requestId: group.requestId, decisionId, state, reason };
+    }
+    findings.push(Object.freeze(finding));
+    tally.set(finding.state, tally.get(finding.state) + 1);
+    tally.set("total", tally.get("total") + 1);
+  }
+
+  return { findings, summary: Object.fromEntries(tally) };
+}