@ciromaciel/contract 1.0.0

package/README.md

@@ -0,0 +1,38 @@
+# @ciromaciel/contract
+
+O contrato de API da stack RiLiGar: um envelope, um catálogo de códigos de erro,
+e os helpers que tornam impossível responder fora dele.
+
+A norma escrita vive [no
+infrastructure](https://github.com/riligar/infrastructure/blob/prod/apps/website/docs/2026-09-09-api-contract.md).
+Este pacote é a norma **executável**: o que os produtos importam para responder,
+e o que os testes importam para conferir.
+
+```bash
+bun add @ciromaciel/contract
+```
+
+```js
+import { ok, created, failure, collection } from '@ciromaciel/contract'
+import { CODES } from '@ciromaciel/contract/codes'
+
+return ok({ id, nome })
+return failure(CODES.NOT_FOUND, 'projeto não encontrado')
+```
+
+## Os schemas ficam num caminho próprio
+
+```js
+import { envelope } from '@ciromaciel/contract/schemas'   // requer zod
+```
+
+`schemas.js` importa Zod, que é um peer **opcional** — um worker que só precisa
+responder não deveria carregar um validador de 60 kB. Enquanto o índice
+reexportava os schemas, o import era eager: pedir `failure` puxava Zod junto, e
+a instalação quebrava com *"Cannot find package 'zod'"* para quem tratou o peer
+como opcional. Quem quer os schemas importa o caminho deles, onde Zod é um
+requisito legítimo e declarado.
+
+## A regra que este pacote torna mecânica
+
+Um agente que aprendeu um produto da RiLiGar já sabe usar os outros seis.

package/package.json

@@ -0,0 +1,40 @@
+{
+    "name": "@ciromaciel/contract",
+    "version": "1.0.0",
+    "license": "MIT",
+    "type": "module",
+    "description": "The API contract of the RiLiGar stack: a single envelope, a catalogue of error codes, and the helpers that make it impossible to answer outside it.",
+    "main": "src/index.js",
+    "files": [
+        "src",
+        "README.md"
+    ],
+    "exports": {
+        ".": "./src/index.js",
+        "./codes": "./src/codes.js",
+        "./schemas": "./src/schemas.js",
+        "./plan": "./src/plan/index.js"
+    },
+    "scripts": {
+        "test": "bun test tests/"
+    },
+    "peerDependencies": {
+        "zod": "^4.0.0"
+    },
+    "peerDependenciesMeta": {
+        "zod": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "zod": "^4.5.4"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/riligar/packages.git",
+        "directory": "contract"
+    }
+}

package/src/codes.js

@@ -0,0 +1,227 @@
+// ============================================================================
+// ERROR CODES — the stack's closed vocabulary
+// ============================================================================
+//
+// `code` is the part of the error the AGENT reads. `message` is for the human
+// and its wording may change at any time; `code` may not — renaming a code is
+// a breaking change to the contract, and that is why it lives here, in a closed
+// enum, instead of loose in each handler.
+//
+// This vocabulary was not invented: it is the consolidation of the `reason`
+// values that already existed scattered across the seven products
+// (`plan_limit`, `has_resources`, `taken`, `expired`, `duplicate_name`,
+// `no_access`…). The stack had already converged on its own — it just had never
+// written it down, and so each product spelled the same concept its own way.
+//
+// Adding a code is a deliberate change: it goes here, not in the handler.
+
+export const CODES = {
+    // ── Identity and access ──────────────────────────────────────────────
+    /** No credential, or an unreadable one. The client did not identify itself. */
+    UNAUTHORIZED: 'UNAUTHORIZED',
+    /** Identified, but without permission for THIS resource. */
+    FORBIDDEN: 'FORBIDDEN',
+    /** Valid token, issued for ANOTHER server (RFC 8707). */
+    WRONG_AUDIENCE: 'WRONG_AUDIENCE',
+    /** The credential does not cover the operation — missing scope, not permission. */
+    INSUFFICIENT_SCOPE: 'INSUFFICIENT_SCOPE',
+
+    // ── The resource ─────────────────────────────────────────────────────
+    /** Does not exist, or is not visible to whoever is asking. */
+    NOT_FOUND: 'NOT_FOUND',
+    /** Another one already exists with the same natural key (name, slug, e-mail). */
+    CONFLICT: 'CONFLICT',
+    /** The requested name is taken. It is a CONFLICT with its own diagnosis. */
+    NAME_TAKEN: 'NAME_TAKEN',
+    /** It existed and no longer holds — deploy version, token, invite link. */
+    EXPIRED: 'EXPIRED',
+    /** The removal runs into dependents that have to go first. */
+    HAS_RESOURCES: 'HAS_RESOURCES',
+
+    // ── The request ──────────────────────────────────────────────────────
+    /** Malformed body, query or path. `details` carries what failed. */
+    VALIDATION_ERROR: 'VALIDATION_ERROR',
+    /** Syntactically valid, but impossible in the resource's current state. */
+    UNPROCESSABLE: 'UNPROCESSABLE',
+    /** Exceeded the call window. `details.retryAfter` says when to come back. */
+    RATE_LIMITED: 'RATE_LIMITED',
+    /** Body larger than the accepted ceiling. */
+    PAYLOAD_TOO_LARGE: 'PAYLOAD_TOO_LARGE',
+
+    // ── Commercial ───────────────────────────────────────────────────────
+    /** The current plan does not cover it. `details` brings current/limit/requiredPlan. */
+    PLAN_LIMIT: 'PLAN_LIMIT',
+    /** The owner's subscription is not active. Blocks the whole operation. */
+    SUBSCRIPTION_REQUIRED: 'SUBSCRIPTION_REQUIRED',
+
+    // ── Us ───────────────────────────────────────────────────────────────
+    /** Unexpected failure. NEVER carries an internal exception message. */
+    INTERNAL_ERROR: 'INTERNAL_ERROR',
+    /** External dependency down. It is transient — worth retrying. */
+    SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
+    /** A third-party provider refused (gateway, SES, Cloudflare). */
+    UPSTREAM_ERROR: 'UPSTREAM_ERROR',
+}
+
+/**
+ * The HTTP status of each code.
+ *
+ * The table lives here so that status and code NEVER disagree: a `NOT_FOUND`
+ * with a 200 is the defect this migration exists to eliminate, and the only way
+ * to guarantee that is for the caller not to pick the number.
+ */
+export const STATUS_BY_CODE = {
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    WRONG_AUDIENCE: 401,
+    INSUFFICIENT_SCOPE: 403,
+
+    NOT_FOUND: 404,
+    CONFLICT: 409,
+    NAME_TAKEN: 409,
+    EXPIRED: 410,
+    HAS_RESOURCES: 409,
+
+    VALIDATION_ERROR: 400,
+    UNPROCESSABLE: 422,
+    RATE_LIMITED: 429,
+    PAYLOAD_TOO_LARGE: 413,
+
+    PLAN_LIMIT: 402,
+    SUBSCRIPTION_REQUIRED: 402,
+
+    INTERNAL_ERROR: 500,
+    SERVICE_UNAVAILABLE: 503,
+    UPSTREAM_ERROR: 502,
+}
+
+/** A transient error deserves a retry; the others do not. */
+export const RETRIABLE = new Set([CODES.RATE_LIMITED, CODES.SERVICE_UNAVAILABLE, CODES.UPSTREAM_ERROR])
+
+/**
+ * The old `reason` values, and the code each one became.
+ *
+ * WHY THIS EXISTS, AND WHY IT IS NOT DEBT
+ *
+ * Before this package, each product had its own vocabulary of `reason` values
+ * in snake_case: `invalid_request`, `plan_limit`, `not_found`. There are
+ * hundreds of calls scattered around — in Auth alone there are 54. Swapping
+ * them all at once would be a sweeping refactor, with real risk and zero
+ * visible gain: what the API client reads is the `code` of the RESPONSE, and
+ * that already comes out correct.
+ *
+ * The translation happens at the edge, once, here. `failure('invalid_request')`
+ * emits `VALIDATION_ERROR` — the handler stays readable in the language it
+ * already spoke, and the response honours the contract.
+ *
+ * WHAT THIS IS NOT
+ *
+ * It is not a second vocabulary. Nothing here is a valid output code: the map
+ * only translates INTO `CODES`, never out of it. New code writes
+ * `CODES.VALIDATION_ERROR` directly; this table only covers what already
+ * existed.
+ *
+ * The map is closed on purpose. A `reason` that is not here falls into
+ * `INTERNAL_ERROR` — loud, and that is the right call: an unknown code is a bug
+ * in whoever called, not something to guess at.
+ */
+export const ALIASES = {
+    // ── Validation ───────────────────────────────────────────────────────
+    validation_error: CODES.VALIDATION_ERROR,
+    invalid_request: CODES.VALIDATION_ERROR,
+    invalid_email: CODES.VALIDATION_ERROR,
+    bad_request: CODES.VALIDATION_ERROR,
+    missing_field: CODES.VALIDATION_ERROR,
+
+    // ── Identity and access ──────────────────────────────────────────────
+    unauthorized: CODES.UNAUTHORIZED,
+    forbidden: CODES.FORBIDDEN,
+    access_denied: CODES.FORBIDDEN,
+    no_access: CODES.FORBIDDEN,
+    application_mismatch: CODES.FORBIDDEN,
+    wrong_audience: CODES.WRONG_AUDIENCE,
+    insufficient_scope: CODES.INSUFFICIENT_SCOPE,
+
+    // ── Resource ─────────────────────────────────────────────────────────
+    not_found: CODES.NOT_FOUND,
+    conflict: CODES.CONFLICT,
+    taken: CODES.NAME_TAKEN,
+    name_taken: CODES.NAME_TAKEN,
+    duplicate_name: CODES.NAME_TAKEN,
+    expired: CODES.EXPIRED,
+    expired_token: CODES.EXPIRED,
+    has_resources: CODES.HAS_RESOURCES,
+    organization_not_empty: CODES.HAS_RESOURCES,
+
+    // ── Unprocessable ────────────────────────────────────────────────────
+    unprocessable: CODES.UNPROCESSABLE,
+    no_op: CODES.UNPROCESSABLE,
+    last_owner: CODES.UNPROCESSABLE,
+    // RFC 8628: the device flow waits for the human to type the code. It is
+    // neither a client error nor a server failure — it is "not yet".
+    authorization_pending: CODES.UNPROCESSABLE,
+
+    // ── Plan and billing ─────────────────────────────────────────────────
+    plan_limit: CODES.PLAN_LIMIT,
+    subscription_required: CODES.SUBSCRIPTION_REQUIRED,
+
+    // ── Pace and size ────────────────────────────────────────────────────
+    rate_limited: CODES.RATE_LIMITED,
+    slow_down: CODES.RATE_LIMITED,
+    payload_too_large: CODES.PAYLOAD_TOO_LARGE,
+
+    // ── Our failure, or a third party's ──────────────────────────────────
+    server_error: CODES.INTERNAL_ERROR,
+    internal_error: CODES.INTERNAL_ERROR,
+    service_unavailable: CODES.SERVICE_UNAVAILABLE,
+    upstream_error: CODES.UPSTREAM_ERROR,
+    email_delivery_failed: CODES.UPSTREAM_ERROR,
+}
+
+export const isCode = value => Object.prototype.hasOwnProperty.call(STATUS_BY_CODE, value)
+
+/**
+ * The canonical code, derived from whatever the handler wrote.
+ *
+ * Accepts the already canonical code (passes straight through), an old `reason`
+ * (translates it), or anything else (`INTERNAL_ERROR`). It is the only point in
+ * the stack that decides this — before, each product had its own table, and they
+ * diverged.
+ */
+export const toCode = value => (isCode(value) ? value : ALIASES[value] || CODES.INTERNAL_ERROR)
+
+/**
+ * The code, derived from an HTTP status.
+ *
+ * For the places that already had the number at hand — a `throw { status: 401 }`
+ * caught in a catch, for example — and have nowhere to get the code from.
+ */
+export const STATUS_TO_CODE = {
+    400: CODES.VALIDATION_ERROR,
+    401: CODES.UNAUTHORIZED,
+    402: CODES.PLAN_LIMIT,
+    403: CODES.FORBIDDEN,
+    404: CODES.NOT_FOUND,
+    /*
+     * 405 is VALIDATION_ERROR: the route exists, the METHOD does not belong to
+     * it — the client sent something malformed, not the server failing.
+     *
+     * It was missing here while Functions and Monitors each carried it in their
+     * own copy of the table, which is the shape this omission takes: whoever
+     * copies adds what they need, and the package that is supposed to be the
+     * norm ends up the poorest of the four. Without this line their `405`s
+     * would fall into `INTERNAL_ERROR` and announce a server failure for what
+     * is a caller mistake.
+     */
+    405: CODES.VALIDATION_ERROR,
+    409: CODES.CONFLICT,
+    410: CODES.EXPIRED,
+    413: CODES.PAYLOAD_TOO_LARGE,
+    422: CODES.UNPROCESSABLE,
+    429: CODES.RATE_LIMITED,
+    500: CODES.INTERNAL_ERROR,
+    502: CODES.UPSTREAM_ERROR,
+    503: CODES.SERVICE_UNAVAILABLE,
+}
+
+export const codeFromStatus = status => STATUS_TO_CODE[status] || CODES.INTERNAL_ERROR

package/src/index.js

@@ -0,0 +1,25 @@
+// ============================================================================
+// @ciromaciel/contract — the API contract of the seven products
+// ============================================================================
+//
+// The written norm lives in https://github.com/riligar/infrastructure/blob/prod/apps/website/docs/2026-09-09-api-contract.md. This
+// package is the EXECUTABLE norm: what the products import in order to respond,
+// and what the tests import in order to check.
+//
+// The golden rule is the one this package makes mechanical: **an agent that has
+// learned one RiLiGar product already knows how to use the other six.**
+//
+// WHY THE SCHEMAS DO NOT COME OUT OF HERE
+//
+// `schemas.js` imports Zod, which is an OPTIONAL peer — a worker that only needs
+// to respond should not have to load a 60 kB validator. But as long as this file
+// reexported the schemas, the import was eager: `import { failure } from
+// '@ciromaciel/contract'` pulled in `schemas.js`, which pulled in Zod, and the
+// install broke with "Cannot find package 'zod'" for anyone who treated the peer
+// as optional. The optional peer was not optional.
+//
+// Whoever wants the schemas imports `@ciromaciel/contract/schemas`, and there Zod
+// is a legitimate requirement of that path — declared in the export map, not
+// hidden in a chain of reexports.
+export { CODES, STATUS_BY_CODE, RETRIABLE, isCode, toCode, codeFromStatus, ALIASES } from './codes.js'
+export { ok, created, collection, failure, failureWithStatus, failureBody, pagination, page } from './responses.js'

package/src/plan/entitlements.js

@@ -0,0 +1,365 @@
+// ============================================================================
+// THE PLAN GATE — one implementation for the seven products
+// ============================================================================
+//
+// Seven copies of this file existed, one per product, and they had ALREADY
+// diverged in ways that cost money in production. None of them raised an error:
+// a billing gate fails by returning the WRONG NUMBER, and the wrong number
+// looks exactly like the right one.
+//
+//   - Six granted every product to whoever subscribed to any ONE of them,
+//     because `hasActiveSubscription` is global to the stack. Measured: one
+//     Hoster subscription running 27 monitors.
+//   - One read the answer under a `data` envelope that no longer existed, so
+//     every subscriber silently fell to the floor.
+//   - One read the limit from `plan_features.value`, NULL across the whole
+//     catalog, pinning a Scale subscriber to one project.
+//   - One announced a limit in its MCP that its own gate then refused.
+//
+// The last one is the shape of all of them: TWO READERS OF THE SAME RULE, one
+// of which drifted. That is what this package removes — not the lines, the
+// second reader.
+//
+// WHY THIS IS SHARED WHEN `gate-telemetry.js` DELIBERATELY WAS NOT: the
+// telemetry is counting nobody gets wrong, and sharing it would tie five
+// release cycles together to save forty lines. This is the reasoning that took
+// three production incidents to get right.
+//
+// IT RUNS ON BOTH RUNTIMES — four Workers, three Node/Bun managers. Only
+// `fetch`, `AbortSignal.timeout`, `Map` and `JSON`, with no binding of either.
+//
+// The full rule, including when a product should freeze rather than warn, is in
+// docs/2026-09-16-gate-de-plano.md.
+
+import { recordGateDecision } from './telemetry.js'
+
+const PERMISSIONS_TIMEOUT_MS = 3000
+
+/**
+ * How long a KNOWN answer is reused.
+ *
+ * The two costs are not symmetric. Too long, and somebody who just paid keeps
+ * being told to pay — the moment they are most likely to ask for a refund. Too
+ * short, and we make more calls to Payments, which is cheap and bounded. Sixty
+ * seconds keeps the post-checkout wait under a minute, and `invalidate()` makes
+ * the good case immediate anyway.
+ */
+const CACHE_TTL_MS = 60_000
+
+/** A ceiling, not a working set: past it the map is dropped, not evicted. */
+const CACHE_MAX_ENTRIES = 1000
+
+/**
+ * Builds the plan gate for one product.
+ *
+ * @param {object}   options
+ * @param {string}   options.product   Slug prefix proving THIS product was paid
+ *                                     for: `auth`, `monitors`, …
+ * @param {string}   options.resource  What is counted, for the error payload.
+ * @param {Array<{slug: string, limit: number}>} options.tiers
+ *                                     Quantity slugs, any order — the LARGEST
+ *                                     match wins.
+ * @param {number}   [options.free=1]  Floor for whoever has no plan of this
+ *                                     product. Hoster passes 0: there, a
+ *                                     project cannot publish without a
+ *                                     subscription, so a free one would be a
+ *                                     project that does nothing.
+ * @param {string}   [options.freePlanName]
+ *                                     Name of the free tier when the catalog
+ *                                     actually has one — Payments' `Base`.
+ *                                     Null everywhere else, which is what makes
+ *                                     `canCreate` answer SUBSCRIPTION_REQUIRED
+ *                                     instead of PLAN_LIMIT.
+ */
+export function createPlanGate({ product, resource, tiers, free = 1, freePlanName = null } = {}) {
+    if (!product) throw new Error('createPlanGate: `product` is required — it is the slug prefix that proves this product was paid for')
+    if (!resource) throw new Error('createPlanGate: `resource` is required — it names what is counted in the error payload')
+    if (!Array.isArray(tiers) || tiers.length === 0) throw new Error('createPlanGate: `tiers` must list at least one quantity slug')
+
+    /**
+     * A KNOWN answer: Payments replied, and there is no plan of this product.
+     *
+     * The floor is `free`, and for six products that is 1 rather than 0 —
+     * enough to make the product real to whoever is evaluating it, and a
+     * product that cannot be tried cannot be bought.
+     */
+    const noPlan = () => ({ plan: freePlanName, limit: free, subscribed: false, unknown: false, slugs: new Set() })
+
+    /**
+     * We could not ask — Payments down, erroring, or the secret is missing.
+     *
+     * `subscribed: true` does NOT assert that the person subscribed: it asserts
+     * that this gate has no basis on which to deny. `unknown: true` is what
+     * separates "could not ask" from "asked, and there is no limit" — both
+     * carry Infinity and both release, and only the first is a problem. Without
+     * the flag, every legitimate unlimited plan would count as blindness.
+     */
+    const unknown = () => ({ plan: null, limit: Infinity, subscribed: true, unknown: true, slugs: null })
+
+    /** ownerId -> { entitlements, expiresAt }. Only KNOWN answers land here. */
+    const cache = new Map()
+
+    function readCache(ownerId) {
+        const hit = cache.get(ownerId)
+        if (!hit) return null
+        if (hit.expiresAt <= Date.now()) {
+            cache.delete(ownerId)
+            return null
+        }
+        return hit.entitlements
+    }
+
+    function writeCache(ownerId, entitlements) {
+        /*
+         * NEVER remember a blind decision: it would turn one timeout into a
+         * full minute of blind releases, and would under-count the blind rate —
+         * the monitor would see one where there were hundreds.
+         */
+        if (entitlements.unknown) return
+        if (cache.size >= CACHE_MAX_ENTRIES) cache.clear()
+        cache.set(ownerId, { entitlements, expiresAt: Date.now() + CACHE_TTL_MS })
+    }
+
+    async function resolve(cfg, ownerId) {
+        if (!ownerId) return noPlan()
+
+        const secretKey = cfg?.PAYMENTS_SECRET_KEY
+        const base = cfg?.PAYMENTS_API_URL
+
+        /*
+         * SERVER TO SERVER, with the secret key. The public key lives in the
+         * dashboard bundle and answers for any userId a visitor happens to
+         * know, which makes it enumerable and useless for authorization.
+         *
+         * Unconfigured, the gate is OFF rather than closed: that is the state
+         * of a deploy that has not yet received its secret, and locking
+         * everyone out during that window is worse than having no gate.
+         */
+        if (!secretKey || !base) return unknown()
+
+        try {
+            const res = await fetch(`${base}/sdk/v1/permissions?userId=${encodeURIComponent(ownerId)}`, {
+                headers: { Authorization: `Bearer ${secretKey}` },
+                signal: AbortSignal.timeout(PERMISSIONS_TIMEOUT_MS),
+            })
+
+            if (!res.ok) {
+                console.error(`[plan] Payments answered ${res.status} for ${ownerId} — allowing`)
+                return unknown()
+            }
+
+            /*
+             * THE RESOURCE IS AT THE ROOT — no fallback to `body.data`. The old
+             * envelope is gone everywhere, and accepting it would only hide a
+             * Payments that did not migrate, which is exactly the case where
+             * the read goes wrong in silence.
+             */
+            const data = (await res.json()) ?? {}
+
+            if (!data.hasActiveSubscription) return noPlan()
+
+            const slugs = new Set((data.features || []).map(f => f.slug))
+            const matched = tiers.filter(t => slugs.has(t.slug))
+
+            /*
+             * O PLANO DESTE PRODUTO, não o primeiro da lista.
+             *
+             * `subscriptions[0]` foi o que os sete produtos fizeram desde
+             * sempre, e é arbitrário: quem assina dois vê o nome de um deles
+             * por ordem de chegada. Medido em produção em 2026-09-16 — uma
+             * conta com Hoster Scale e Monitors Scale recebia
+             * `plan: "Hoster — Scale"` do `monitors_get_account`.
+             *
+             * O dano não é cosmético. A recusa monta a frase a partir daqui, e
+             * ela sairia como "O plano Hoster — Scale inclui 5 monitores" — um
+             * limite que aquele plano não define, sobre um produto que ele não
+             * cobre. Quem lê não tem como saber que a frase está errada.
+             *
+             * O nome do plano deste produto começa com o nome do produto
+             * ("Monitors — Scale"), que é a convenção do catálogo inteiro. Sem
+             * casar nenhum, cai no primeiro: é melhor um nome aproximado do que
+             * nenhum, e é o comportamento que existia.
+             */
+            const subscriptions = data.subscriptions || []
+            const own = subscriptions.find(sub => typeof sub?.planName === 'string' && sub.planName.toLowerCase().startsWith(product))
+            const plan = (own || subscriptions[0])?.planName || null
+
+            /*
+             * TWO CASES USED TO LOOK THE SAME HERE, and telling them apart is
+             * the whole fix. `hasActiveSubscription` is GLOBAL — one Payments
+             * project bills the stack — so it says `true` for a subscriber of
+             * ANY product. Finding no quantity slug therefore meant either:
+             *
+             * 1. A plan OF THIS PRODUCT with an incomplete catalog entry. Our
+             *    fault, not the customer's: refusing would be charging without
+             *    delivering, so this allows.
+             * 2. A subscription to ANOTHER product — the leak described at the
+             *    top of this file.
+             *
+             * The product PREFIX separates them, because it is what says which
+             * product was paid for.
+             */
+            const paysForThis = [...slugs].some(s => s.startsWith(`${product}-`))
+
+            if (matched.length === 0) {
+                /*
+                 * `otherProductPlan` PRESERVA O NOME DO PLANO ALHEIO, e a
+                 * distinção custa uma linha mas muda a mensagem que o cliente
+                 * lê.
+                 *
+                 * Quem paga Hoster — Scale e é barrado aqui não pode ler "o
+                 * plano gratuito inclui 1 monitor": ele ESTÁ pagando, e uma
+                 * frase que ignora isso soa como erro de cobrança. O que é
+                 * verdade é que o plano dele é de outro produto — e dizer isso
+                 * exige saber qual.
+                 *
+                 * `plan` continua `freePlanName` porque é o plano DESTE
+                 * produto, e não há nenhum; o nome alheio viaja num campo
+                 * próprio, para nunca ser confundido com um direito.
+                 */
+                if (!paysForThis) return { plan: freePlanName, otherProductPlan: plan, limit: free, subscribed: false, unknown: false, slugs }
+                console.warn(`[plan] ${ownerId} has a ${product} plan with no quantity slug — allowing (catalog divergence)`)
+                return { plan, limit: Infinity, subscribed: true, unknown: false, slugs }
+            }
+
+            /*
+             * THE LARGEST WINS. An upgrade mid-cycle leaves both slugs, and
+             * charging for two plans while delivering the smaller one is the
+             * expensive mistake in this direction.
+             */
+            return { plan, limit: Math.max(...matched.map(t => t.limit)), subscribed: true, unknown: false, slugs }
+        } catch (error) {
+            console.error(`[plan] could not reach Payments for ${ownerId} — allowing:`, error?.message)
+            return unknown()
+        }
+    }
+
+    /**
+     * What this owner is entitled to. The single entry point, and the ONLY
+     * place a decision is recorded — the counting wraps the whole function
+     * rather than sitting beside each `return`, so a path added tomorrow cannot
+     * forget to be counted.
+     */
+    async function getEntitlements(cfg, ownerId) {
+        /*
+         * A CACHE HIT IS NOT A DECISION. The blind rate is blind decisions over
+         * decisions actually MADE; counting hits would pad the denominator with
+         * reads that asked nothing, so the more we cache, the healthier a
+         * broken gate would look.
+         */
+        const cached = ownerId ? readCache(ownerId) : null
+        if (cached) return cached
+
+        const entitlements = await resolve(cfg, ownerId)
+        recordGateDecision(!entitlements.unknown)
+        if (ownerId) writeCache(ownerId, entitlements)
+
+        return entitlements
+    }
+
+    /**
+     * Can this owner create one more?
+     *
+     * ONLY on the path that creates. Renaming or editing something that already
+     * exists must never hit a QUANTITY limit — whoever is over their plan keeps
+     * managing what they have, they just cannot add the next one.
+     */
+    async function canCreate(cfg, ownerId, current) {
+        /*
+         * NO OWNER IS NOT A FREE OWNER.
+         *
+         * Missing `ownerId` is absence of a subject, not uncertainty. `resolve`
+         * answers `noPlan()` for it, which carries the free floor — so a route
+         * that forgot to require auth would create the free resource with no
+         * owner attached, in every product at once. Closed here rather than in
+         * each product, because the mistake is the same everywhere.
+         */
+        if (!ownerId) {
+            return { allowed: false, plan: null, otherProductPlan: null, current, limit: free, resource, code: 'SUBSCRIPTION_REQUIRED' }
+        }
+
+        const ent = await getEntitlements(cfg, ownerId)
+
+        if (current < ent.limit) return { allowed: true, plan: ent.plan }
+
+        return {
+            allowed: false,
+            plan: ent.plan,
+            // O plano de OUTRO produto, quando existe: é o que permite dizer
+            // "a assinatura X é de outro produto" em vez de "o plano gratuito".
+            otherProductPlan: ent.otherProductPlan ?? null,
+            current,
+            limit: ent.limit === Infinity ? null : ent.limit,
+            resource,
+            /*
+             * TWO CODES, because there are two ways out. `PLAN_LIMIT` is "your
+             * plan ran out" — upgrade. `SUBSCRIPTION_REQUIRED` is "there is no
+             * plan" — subscribe, or settle a failed payment. Both are 402, and
+             * telling somebody to upgrade a plan they never had is how a screen
+             * becomes a support ticket.
+             */
+            code: ent.subscribed ? 'PLAN_LIMIT' : 'SUBSCRIPTION_REQUIRED',
+        }
+    }
+
+    /**
+     * Drops an owner's cached answer, so the next read asks again.
+     *
+     * Call it from whatever changes the ANSWER — subscribing, cancelling,
+     * returning from checkout. NOT from whatever changes the COUNT: the cache
+     * holds the plan's ceiling, and the count is read fresh from the database
+     * every time.
+     *
+     * With no argument it clears everything, which is what tests need — the
+     * cache is state that otherwise leaks between cases.
+     */
+    function invalidate(ownerId) {
+        if (ownerId) cache.delete(ownerId)
+        else cache.clear()
+    }
+
+    return { getEntitlements, canCreate, invalidate, product, resource, free }
+}
+
+// ============================================================================
+// READING SLUGS — for the gates that are not about quantity
+// ============================================================================
+//
+// Every non-quantity gate in the stack turns out to be one of two questions
+// about `ent.slugs`: "does it have this one?" (Hoster's `canDeploy`) or "which
+// tier does it reach?" (Hoster's `getRetention`, Monitors' status pages).
+//
+// They live here because writing them by hand is what produced the Monitors
+// defect: `monitors_get_account` carried its own copy of the pages rule,
+// `!ent.subscribed ? 1 : !ent.slugs ? Infinity : Infinity`, whose last two
+// branches are identical. Every subscriber was told "unlimited status pages",
+// including Starter, whose slug caps them at one. The gate itself was right, so
+// the agent was promised what the server would refuse — and nothing errored.
+//
+// The product still names its own gate. What it stops owning is the reading.
+
+/**
+ * Does this entitlement carry a given feature slug?
+ *
+ * `unknown` answers TRUE: could-not-ask releases, like everywhere else in this
+ * file. A gate that closed here would turn a Payments outage into an outage of
+ * the feature.
+ */
+export function hasSlug(ent, slug) {
+    if (ent?.unknown) return true
+    return Boolean(ent?.slugs?.has(slug))
+}
+
+/**
+ * The largest tier this entitlement reaches, or `free` when it reaches none.
+ *
+ * @param {Array<{slug: string, limit: number}>} tiers
+ * @param {number} free Floor for whoever matches no tier.
+ */
+export function tierLimit(ent, tiers, free = 1) {
+    if (ent?.unknown) return Infinity
+
+    const matched = ent?.slugs ? tiers.filter(t => ent.slugs.has(t.slug)).map(t => t.limit) : []
+
+    return matched.length ? Math.max(...matched) : free
+}

package/src/plan/index.js

@@ -0,0 +1,28 @@
+// ============================================================================
+// @ciromaciel/contract/plan — the plan gate of the seven products
+// ============================================================================
+//
+//     import { createPlanGate } from '@ciromaciel/contract/plan'
+//
+//     export const plan = createPlanGate({
+//         product: 'auth',            // the prefix proving THIS product was paid for
+//         resource: 'applications',   // what is counted, for the error payload
+//         tiers: [
+//             { slug: 'auth-applications-1', limit: 1 },
+//             { slug: 'auth-applications-5', limit: 5 },
+//             { slug: 'auth-applications-unlimited', limit: Infinity },
+//         ],
+//     })
+//
+// A product owns three things, and they are the three genuinely its own: the
+// prefix, the slugs, and the wording of the notice. The cache, the fail-open,
+// the product-prefix check, the telemetry and the choice between PLAN_LIMIT and
+// SUBSCRIPTION_REQUIRED are the same reasoning everywhere, so they can only be
+// right or wrong once.
+//
+// The rule itself — including when a product should freeze rather than warn —
+// is in docs/2026-09-16-gate-de-plano.md.
+
+export { createPlanGate, hasSlug, tierLimit } from './entitlements.js'
+export { getPlanNotice, withPlanNotice } from './notice.js'
+export { gateTelemetry, recordGateDecision, resetGateTelemetry } from './telemetry.js'

package/src/plan/notice.js

@@ -0,0 +1,98 @@
+// ============================================================================
+// notice.js — the billing warning the dashboard and the MCP both read
+// ============================================================================
+//
+// FREEZE, DO NOT DISCONNECT. When a subscription lapses, the people who would
+// be cut off are usually not the people who can pay: an application's end
+// users, a site's visitors, a monitored service's audience. So nothing goes
+// down. Growth freezes — the NEXT thing cannot be created — and the owner is
+// told, in the two places an owner looks.
+//
+// THE MCP IS WARNED, NEVER BLOCKED. An agent whose tool returns an error cannot
+// tell "the owner must pay" from "this integration is broken": it retries, it
+// falls back, or it reports an outage. None of those reaches the person who can
+// act. A notice attached to a SUCCESSFUL result is read and relayed.
+//
+// The three states, and why `unknown` is silent, are in `entitlements.js`.
+
+/**
+ * Describes an owner's plan for display. It NEVER decides access.
+ *
+ * @param {object} gate   What `createPlanGate` returned.
+ * @param {object} cfg    Where the secret and the Payments URL live.
+ * @param {string} ownerId
+ * @param {object} [copy] Product wording. `product` is the name a person reads
+ *                        ("RiLiGar Auth"), `keeps` is what goes on working,
+ *                        `frozen` is what does not.
+ * @returns {Promise<{state: 'active'|'none'|'unknown', plan: string|null,
+ *   limit: number|null, message: string|null}>}
+ */
+export async function getPlanNotice(gate, cfg, ownerId, copy = {}) {
+    const ent = await gate.getEntitlements(cfg, ownerId)
+
+    // `Infinity` does not survive JSON.stringify — it becomes `null` silently.
+    // Converting on purpose is what keeps the wire honest.
+    const limit = ent.limit === Infinity ? null : ent.limit
+
+    // Could not ask: say nothing. Dunning somebody because our OWN billing call
+    // timed out is worse than staying quiet for the length of an outage.
+    if (ent.unknown) return { state: 'unknown', plan: null, limit: null, message: null }
+
+    if (ent.subscribed) return { state: 'active', plan: ent.plan, limit, message: null }
+
+    /*
+     * ONE MESSAGE, WRITTEN ONCE, for both surfaces — a banner and an MCP
+     * warning that disagree is how a customer ends up arguing with support
+     * about which is true.
+     *
+     * IT SAYS WHAT STILL WORKS BEFORE WHAT DOES NOT. The first question of
+     * anyone who sees this is "did my users just go down?", and an answer that
+     * opens with the refusal makes them assume the worst.
+     *
+     * Portuguese, because this is the one string here a person reads.
+     */
+    const product = copy.product || 'este produto'
+    const keeps = copy.keeps || 'O que você já criou continua funcionando'
+    const frozen = copy.frozen || 'apenas a criação de novos recursos está bloqueada'
+
+    return {
+        state: 'none',
+        plan: ent.plan,
+        limit,
+        message: `Sua assinatura do ${product} não está ativa. ${keeps} — ${frozen} até a regularização do pagamento.`,
+    }
+}
+
+/**
+ * Attaches the notice to an MCP tool result, without ever refusing it.
+ *
+ * IT TRAVELS AS A FIELD, NOT AS PROSE. The stack's MCP rule is that
+ * `content[0].text` is the `JSON.stringify` of the same object in
+ * `structuredContent`. Appending a second text block would break that mirror,
+ * and a client reading one field would disagree with one reading the other.
+ *
+ * ERRORS ARE LEFT ALONE: an `isError` result already carries the reason the
+ * agent needs, and billing copy on top of a permission failure buries it.
+ *
+ * AND IT NEVER BREAKS A TOOL CALL — the notice is decoration, so an unreachable
+ * Payments or an outright throw both leave the result untouched.
+ */
+export async function withPlanNotice(result, gate, cfg, ownerId, copy) {
+    if (!result || result.isError || !result.structuredContent) return result
+
+    try {
+        const notice = await getPlanNotice(gate, cfg, ownerId, copy)
+        if (notice.state !== 'none') return result
+
+        const payload = { ...result.structuredContent, planNotice: notice }
+
+        return {
+            ...result,
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            structuredContent: payload,
+        }
+    } catch (error) {
+        console.error('[plan] could not resolve the notice — continuing without it:', error?.message)
+        return result
+    }
+}

package/src/plan/telemetry.js

@@ -0,0 +1,68 @@
+// ============================================================================
+// telemetry.js — how often the gate decides blind
+// ============================================================================
+//
+// THE GATE FAILS OPEN, and that is right: Payments down, a timeout or a missing
+// secret all release. An incident in billing must not become an incident in
+// every product.
+//
+// WHAT IS WRONG IS THE SILENCE. The 2026-09-15 survey of the stack found this
+// to be the largest revenue hole: the whole stack could be giving itself away
+// for days and nothing anywhere would say so. It does not close by turning the
+// fail-open off — it closes by making it VISIBLE.
+//
+// A ONE-HOUR SLIDING WINDOW, because that is the question being asked: "is the
+// gate deciding blind RIGHT NOW?". A counter accumulated since boot answers
+// "has it ever", which is always yes after the first timeout and never returns
+// to zero — a number that can only go up is one nobody can assert on.
+//
+// IN MEMORY AND PER ISOLATE. The number exists to raise a hand, not for
+// accounting. A `/status` answering from any isolate shows that isolate's
+// window, and if Payments is down they will all be counting.
+
+/** When each blind decision happened, oldest first. */
+const blind = []
+
+/** When EVERY decision happened, so the rate means something. */
+const total = []
+
+const WINDOW_MS = 3600_000
+
+/** Drops what fell out of the window. Called on every read and write. */
+function trim(list, now) {
+    const cutoff = now - WINDOW_MS
+    while (list.length && list[0] < cutoff) list.shift()
+}
+
+/**
+ * Records one decision of the gate.
+ *
+ * `known` is `false` when the answer from Payments could not be obtained or
+ * read — the path that returns Infinity and releases.
+ */
+export function recordGateDecision(known) {
+    const now = Date.now()
+    total.push(now)
+    if (!known) blind.push(now)
+    trim(total, now)
+    trim(blind, now)
+}
+
+/**
+ * The last hour, for `/status`.
+ *
+ * `gateBlindLastHour` is the number a monitor asserts on: anything above zero
+ * means somebody was granted access without us knowing whether they could.
+ */
+export function gateTelemetry() {
+    const now = Date.now()
+    trim(total, now)
+    trim(blind, now)
+    return { gateDecisionsLastHour: total.length, gateBlindLastHour: blind.length }
+}
+
+/** For the tests. */
+export function resetGateTelemetry() {
+    blind.length = 0
+    total.length = 0
+}

package/src/responses.js

@@ -0,0 +1,189 @@
+// ============================================================================
+// RESPONSES — the only way out of the server
+// ============================================================================
+//
+// Four functions. If a handler in any of the seven products builds a
+// `Response` by hand, it has stepped outside the contract.
+//
+// The point of this file is not to save typing — it is to make the defect
+// IMPOSSIBLE. `failure()` derives the status from the code: there is no
+// signature that lets you return `NOT_FOUND` with a 200. That discordant pair
+// was exactly what made an agent read 200, conclude success, and carry on with
+// data that did not exist.
+import { CODES, STATUS_BY_CODE, RETRIABLE, isCode, toCode, codeFromStatus } from './codes.js'
+
+const JSON_HEADERS = { 'content-type': 'application/json; charset=utf-8' }
+
+const respond = (body, status, headers) => new Response(JSON.stringify(body), { status, headers: { ...JSON_HEADERS, ...headers } })
+
+/**
+ * One resource, at the root.
+ *
+ *   ok({ id: 'mon_a1', name: 'checkout' })
+ *   → 200 {"id":"mon_a1","name":"checkout"}
+ *
+ * No `data`, no `success`, no `message`. The HTTP status already said it went
+ * well; repeating that in the body is noise the agent has to learn to ignore —
+ * once per product.
+ */
+export const ok = (resource, { status = 200, headers } = {}) => respond(resource, status, headers)
+
+/**
+ * A resource that has just been BORN.
+ *
+ * 201 is the creation signal, and nothing else. An upsert that updated returns
+ * `ok()`; the one that created returns `created()`. That is what lets the agent
+ * know whether its own call was the one that created — without having to
+ * compare timestamps.
+ */
+export const created = (resource, { headers } = {}) => respond(resource, 201, headers)
+
+/**
+ * A collection, always in the same shape.
+ *
+ *   collection([a, b], { limit: 50, offset: 0, total: 128 })
+ *   → {"items":[…],"page":{"limit":50,"offset":0,"total":128,"hasMore":true}}
+ *
+ * `items` is always an array — empty is a legitimate response and has the SAME
+ * shape as a full one. Pruning the empty list (which Payments used to do) broke
+ * on the very first client, because every test environment has seeded data.
+ *
+ * `hasMore` is explicit on purpose: the consumer should not have to compare
+ * `offset + limit` against `total` to know whether to keep paginating.
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * `total: null` WHEN NOBODY COUNTED — and that is the whole point of this helper.
+ *
+ * Until 09/10 the defaults filled `page` from the array itself: a route that
+ * NEVER paginated returned `{limit: N, offset: 0, total: N, hasMore: false}`,
+ * byte for byte identical to a route that paginated and reached the end. Of the
+ * stack's 39 collection routes, 29 did not paginate and all 29 asserted
+ * `hasMore: false` — the very field that exists so the agent need not deduce
+ * was deducing wrong in 87% of cases.
+ *
+ * Now: whoever does not pass `total` gets `total: null` and `hasMore: null`.
+ * Null means "I don't know", and that differs from zero and from false. An
+ * agent reading `total: null` knows it must ask another way; one reading
+ * `hasMore: false` stops paginating — and those two conclusions must not come
+ * out of the same response.
+ *
+ * Whoever truly paginates passes `total` and gets `hasMore` computed. Whoever
+ * returns the whole list on purpose passes `total: items.length`, and then
+ * `hasMore: false` is an assertion, not a default.
+ */
+export const collection = (list, page = {}, { status = 200, headers } = {}) => {
+    const items = Array.isArray(list) ? list : []
+    const limit = page.limit ?? items.length
+    const offset = page.offset ?? 0
+
+    // `null` only when NOBODY counted. `total: 0` is a legitimate count.
+    const total = page.total ?? null
+    const hasMore = page.hasMore ?? (total === null ? null : offset + items.length < total)
+
+    /*
+     * `extra` goes at the ROOT, not inside `page`. Hoster's `activeDeployId`
+     * and Monitors' `counts` are context about the SET, not about pagination —
+     * inside `page` they would claim to be pagination, and a generic client
+     * reading `page` to paginate would trip over them.
+     */
+    return respond({ items, page: { limit, offset, total, hasMore }, ...(page.extra ?? {}) }, status, headers)
+}
+
+/**
+ * A failure. The status comes from the CODE — the caller does not pick the number.
+ *
+ *   failure(CODES.NOT_FOUND, 'Project not found.')
+ *   → 404 {"error":{"code":"NOT_FOUND","message":"Project not found."}}
+ *
+ * `details` is for what the agent can ACT on: the limit that was exceeded, the
+ * field that was missing, how many seconds to wait. Never for a stack trace.
+ *
+ * An unknown code becomes INTERNAL_ERROR rather than a silent 500 with a
+ * malformed body: if someone wrote a code outside the enum, the bug is ours,
+ * and the response to the client stays well formed.
+ */
+export const failure = (code, message, { details, headers, status } = {}) => {
+    const resolved = toCode(code)
+    const body = { error: { code: resolved, message: String(message ?? '') } }
+
+    if (details && Object.keys(details).length) body.error.details = details
+    if (RETRIABLE.has(resolved)) body.error.retriable = true
+
+    return respond(body, status ?? STATUS_BY_CODE[resolved], headers)
+}
+
+/**
+ * The error body, without the `Response` around it.
+ *
+ * For whoever answers through a framework that assembles the response itself —
+ * the Elysia of Storage and Functions, where the handler returns an object and
+ * the status travels via `set.status`. Returns `{ body, status }` so the two go
+ * together and there is no way to forget one.
+ */
+export const failureBody = (code, message, details) => {
+    const resolved = toCode(code)
+    const error = { code: resolved, message: String(message ?? '') }
+
+    if (details && Object.keys(details).length) error.details = details
+    if (RETRIABLE.has(resolved)) error.retriable = true
+
+    return { body: { error }, status: STATUS_BY_CODE[resolved] }
+}
+
+/**
+ * Reads `limit`/`offset` from a URL, with a ceiling.
+ *
+ * A `limit` with no ceiling is a way to take the service down with one query; a
+ * ceiling with no `offset` is what made record 101 of Messages unreachable. The
+ * two travel together.
+ */
+export const pagination = (url, { defaultLimit = 50, maxLimit = 200 } = {}) => {
+    const p = url instanceof URL ? url.searchParams : new URL(url, 'http://x').searchParams
+    const rawLimit = Number(p.get('limit'))
+    const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.min(Math.floor(rawLimit), maxLimit) : defaultLimit
+    const rawOffset = Number(p.get('offset'))
+    const offset = Number.isFinite(rawOffset) && rawOffset > 0 ? Math.floor(rawOffset) : 0
+    return { limit, offset }
+}
+
+/**
+ * The page of a paginated query, ready for `collection`.
+ *
+ * It exists to make MECHANICAL what the stack got wrong by hand on two fronts:
+ *
+ * 1. **The reported `limit` must be the APPLIED one.** Two routes clamped in
+ *    the data layer and reported the raw query value: with `?limit=5000` they
+ *    returned 200 rows and said `page:{limit:5000, hasMore:false}`. The client
+ *    concludes "I asked for 5000, got 200, therefore it's over" — and stops
+ *    paginating halfway.
+ *
+ * 2. **`total` comes from whoever counted.** Passing `total` is mandatory here,
+ *    because `collection` on its own has no way to tell whether nobody counted
+ *    or the count happened to equal the array length.
+ *
+ *   const { limit, offset } = pagination(url)
+ *   const rows = await fetchRows(limit, offset)
+ *   const [{ total }] = await count()
+ *   return collection(rows, page({ limit, offset, total }))
+ */
+export const page = ({ limit, offset = 0, total, extra }) => {
+    if (!Number.isFinite(total)) {
+        throw new TypeError('page() requires a numeric `total` — use collection(items) directly when nobody counted.')
+    }
+    return { limit, offset, total, extra }
+}
+
+/**
+ * A failure for which only the HTTP status is known.
+ *
+ * For the global error handler, where a `throw { status, message }` arrives
+ * from any layer and there is no code at hand. It derives the `code` from the
+ * number instead of always falling into `INTERNAL_ERROR` — a 401 that turns
+ * into a 500 at the edge hides the real problem from whoever is debugging.
+ *
+ * `status` is preserved: whoever already had the number keeps it, even when the
+ * canonical code maps to another (401 for `UNAUTHORIZED`, 402 for `PLAN_LIMIT`).
+ */
+export const failureWithStatus = (status, message, details, headers) => failure(codeFromStatus(status), message, { details, headers, status })
+
+export { CODES, STATUS_BY_CODE }

package/src/schemas.js

@@ -0,0 +1,81 @@
+// ============================================================================
+// SCHEMAS — the contract as an executable thing
+// ============================================================================
+//
+// The same rules as `responses.js`, from the READER's side. They let the
+// contract test assert the shape without reimplementing the assertion in every
+// suite, and let a consumer validate what it received.
+//
+// Zod is a peer: the seven products already have it (v4), and embedding a
+// second copy in a worker means paying the bundle cost twice.
+import { z } from 'zod'
+
+import { STATUS_BY_CODE } from './codes.js'
+
+/** The code is the closed enum — no free-form strings. */
+export const codeSchema = z.enum(Object.keys(STATUS_BY_CODE))
+
+export const errorSchema = z.object({
+    error: z.object({
+        code: codeSchema,
+        message: z.string().min(1),
+        details: z.record(z.string(), z.unknown()).optional(),
+        retriable: z.boolean().optional(),
+    }),
+})
+
+export const pageSchema = z.object({
+    limit: z.number().int().nonnegative(),
+    offset: z.number().int().nonnegative(),
+    total: z.number().int().nonnegative(),
+    hasMore: z.boolean(),
+})
+
+/** `{items, page}` — a forma de TODA coleção. */
+export const collectionSchema = item =>
+    z.object({
+        items: z.array(item ?? z.unknown()),
+        page: pageSchema,
+    })
+
+/**
+ * The resource goes at the root, so there is no envelope to validate — what can
+ * be asserted is what it must NOT be.
+ *
+ * The three forbidden keys are exactly the envelopes the stack used to use. A
+ * resource that still carries `data`, `success` or `message` at the top is a
+ * product that has not migrated — and the contract test must say so in plain
+ * words, instead of passing because "an object came back".
+ */
+export const resourceSchema = body =>
+    (body ?? z.object({}).loose()).refine(v => !v || typeof v !== 'object' || (!('data' in v) && !('success' in v) && !('message' in v)), {
+        message: 'a resource must not be wrapped in `data`, `success` or `message`',
+    })
+
+const CAMEL = /^[a-z][a-zA-Z0-9]*$/
+
+/**
+ * Every key in the body is camelCase, at any depth.
+ *
+ * Storage used to return `tenant_id` in the body and `tenantId` in the path of
+ * the SAME route. A consumer had to know, field by field, which vocabulary to
+ * use.
+ *
+ * Keys that are user DATA (the name of a collection, of an environment
+ * variable, of a header) do not follow the rule — they are not our contract.
+ * Hence `ignore`.
+ */
+export const camelCaseKeys = (value, { ignore = [] } = {}, path = '') => {
+    const offenders = []
+    const walk = (v, path) => {
+        if (Array.isArray(v)) return v.forEach((x, i) => walk(x, `${path}[${i}]`))
+        if (!v || typeof v !== 'object') return
+        for (const [k, sub] of Object.entries(v)) {
+            const here = path ? `${path}.${k}` : k
+            if (!ignore.includes(k) && !CAMEL.test(k)) offenders.push(here)
+            walk(sub, here)
+        }
+    }
+    walk(value, path)
+    return offenders
+}