@blamejs/core 0.12.27 → 0.12.29

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.29 (2026-05-24) — **`b.ai.dp` — float-safe differential privacy: snapping-mechanism Laplace + discrete Gaussian + Rényi-DP budgets.** Differential privacy adds calibrated noise so an aggregate is provably insensitive to any single record — but the guarantee is fragile: Mironov (2012) showed that a Laplace mechanism sampled with naive double-precision floats lets an attacker distinguish neighbouring datasets with > 35% probability from a single output, silently destroying the promise. `b.ai.dp` ships only mechanisms whose sampling is hardened against that attack class: Laplace via the snapping mechanism (clamp + CSPRNG sign + full-mantissa uniform + power-of-two-grid rounding) and the discrete Gaussian (Canonne–Kamath–Steinke 2020) via integer-exact rejection sampling built from Bernoulli(exp(−γ)) over exact rationals — no floating-point noise at all. All randomness comes from `b.crypto.generateBytes` (SHAKE256 over the OS CSPRNG), never `Math.random`. `b.ai.dp.budget({ scope, epsilon, delta })` tracks a privacy budget per scope and refuses a `consume` that would exceed it, accounting composition either by basic summation (default) or a Rényi-DP accountant (Mironov 2017) for a much tighter bound under repeated Gaussian releases. NIST SP 800-226 (2025) is the evaluation standard; Dwork & Roth is the canonical reference. The exponential and sparse-vector mechanisms are deferred-with-condition — their float-safe constructions (base-2 / permute-and-flip; snapped SVT) re-open on operator demand, since shipping them float-unsafe would defeat the module's purpose. **Added:** *`b.ai.dp.mechanism({ type, sensitivity, epsilon, ... })` — float-safe noise mechanisms* — `type: "laplace"` is the snapping mechanism (pure ε-DP, real-valued, requires a clamp `bound` the guarantee depends on); `type: "gaussian"` is the discrete Gaussian (integer-valued, (ε, δ)-DP, requires `delta`). The Gaussian uses the classic calibration σ = √(2 ln(1.25/δ))·Δ/ε, proven for ε ≤ 1 — larger ε is refused with a pointer to splitting the release under an rdp budget. Descriptors are validated + frozen at construction so a malformed parameter fails fast. · *`b.ai.dp.budget({ scope, epsilon, delta, accounting })` — per-scope privacy budget* — Returns `{ consume, remaining, spent, reset }`. `consume(mechanism, value)` adds the mechanism's noise, charges the accountant, and throws `aiDp/budget-exhausted` if the release would push the scope past its (ε, δ). `accounting: "basic"` (default) sums per-release ε and δ; `accounting: "rdp"` runs a Rényi-DP accountant across a grid of orders and converts to (ε, δ) at the scope's δ for a tight composition bound under repeated Gaussian releases (requires `delta > 0`). The scope budget is enforced on both ε and δ independently. **Security:** *`b.crypto.generateBytes` uniformity fix at 1-byte length* — Node's SHAKE256 XOF is non-uniform at `outputLength: 1` — the byte values 0x00 and 0xff never occur and the low bit skews to ~0.54. `b.crypto.generateBytes(1)` (and the underlying `random(1)`) now draws at least 2 bytes and slices, so a single-byte CSPRNG request is uniform. Surfaced by `b.ai.dp` per-byte noise sampling; any per-byte consumer of `generateBytes` inherits the fix. A regression test asserts 0x00 / 0xff occur and the low bit is balanced.
+
+- v0.12.28 (2026-05-24) — **`b.ai.capability` — model-capability registry + cheapest-satisfying-model router.** `b.ai.capability.create({ models })` turns a fleet of AI model descriptors into a routing decision: given a set of requirements (context window, input/output modalities, tool use, structured output, reasoning tier, citation support, prompt-caching size), it picks the cheapest model that satisfies all of them. NIST AI RMF (AI 100-1) MAP 2.x requires documenting each model's capabilities and limitations; the Model Cards convention (Mitchell et al., 2019) formalizes that descriptor — this primitive makes the descriptor actionable. Routing to the cheapest sufficient model is a front-line defense against over-provisioning spend and composes directly with `b.ai.quota`'s `cost-usd` dimension (the chosen descriptor's rate feeds the budget charge); refusing to route a request to a model that cannot satisfy it (missing modality, too-small context window, no tool use) catches a capability mismatch before the inference call burns tokens on a guaranteed-bad result. Cost ranking uses a supplied `costBasis` (`{ inputTokens, outputTokens }`) for real per-call spend, else the sum of the per-1k rates; ties break by model id so the choice is deterministic across calls and nodes. **Added:** *`b.ai.capability.create({ models })` — capability registry + router* — Returns `{ describe, list, register, satisfies, route }`. A descriptor carries `maxContextTokens`, `maxOutputTokens`, `modalitiesIn` / `modalitiesOut` (arrays), `toolUse`, `structuredOutput`, `fineTunable`, `reasoningTier` (`none` / `basic` / `standard` / `advanced`, ordered), `citationSupport`, `promptCachingMaxTokens`, and the cost rates `costPer1kInputTokens` / `costPer1kOutputTokens`. Descriptors are validated + frozen at registration so a typo (negative cost, unknown reasoning tier, non-array modality list) surfaces at config time rather than as a silent mis-route. `describe(modelId)` returns the frozen descriptor; `register(modelId, descriptor)` adds or replaces one at runtime. · *`route({ requirements, fallback?, costBasis? })` — cheapest-satisfying selection* — Collects every model whose descriptor satisfies all requirements, then returns the cheapest (`{ modelId, descriptor, estimatedCost, reason }`). Requirements: `minContextTokens`, `minOutputTokens`, `modalitiesIn` / `modalitiesOut` (model must support every listed modality), `toolUse`, `structuredOutput`, `fineTunable`, `minReasoningTier` (tier ordering — `standard` is met by `standard` or `advanced`), `citationSupport`, `minPromptCachingTokens`. When no model matches, `fallback` (a registered model id) is returned with `reason: "fallback"`, or the call refuses with `aiCapability/no-candidate` if no fallback was supplied. Routing decisions emit `ai/capability-routed` / `ai/capability-fallback` / `ai/capability-no-candidate` through the drop-silent audit chain. · *`satisfies(modelId, requirements)` — precise capability-mismatch reasons* — Returns `{ ok, failures }` where each failure names the `requirement`, the `need`, and what the model `have`s — so a caller surfaces a precise reason (e.g. `minReasoningTier need advanced have basic`) instead of a bare boolean. Use it to explain a routing miss or to gate a request against a specific model before calling it.
+
 - v0.12.27 (2026-05-24) — **`b.ai.quota` — per-tenant, per-model AI usage budgets with atomic consume-and-check.** `b.ai.quota.create(opts)` builds an enforcer that caps AI inference usage per `(tenant, model, dimension, period)` and defends OWASP LLM Top 10 2025 LLM10 (Unbounded Consumption) — the class that includes denial-of-wallet, where an attacker drives a high volume of pay-per-use inferences until the bill itself is the attack. Meter by `tokens`, `requests`, `cost-usd`, or `compute-hours` over a calendar-aligned UTC window (`second` through `month`). `consume(tenant, model, amount)` is a single atomic check-and-charge: under the default `hard` enforcement it reserves the amount only if it fits under the ceiling, otherwise it refuses without charging — the limit test and the charge are one indivisible operation, so there is no charge-then-refund window for a concurrent call to observe. The in-memory counter is per-process; multi-node deployments supply an `opts.store` adapter whose `reserve` (an atomic conditional test-and-charge — a Redis Lua script, a SQL `UPDATE ... WHERE used + :amt <= :limit RETURNING used`) and `add` are atomic on the shared backend to enforce one aggregate ceiling across the cluster without false denials under contention. Limit resolution is most-specific-first: `perTenantModel` over `perTenant` over `perModel` over the default `limit`; tenant and model identifiers are percent-encoded into the counter key so a hostile tenant name cannot collide with another tenant's budget. **Added:** *`b.ai.quota.create(opts)` — per-tenant AI usage-budget enforcer* — Returns `{ consume, check, snapshot, reset }` scoped to one `dimension` (`tokens` / `requests` / `cost-usd` / `compute-hours`) and one `period` (`second` / `minute` / `hour` / `day` / `week` (Monday-aligned) / `month` (1st-of-month), all UTC-aligned). `consume(tenant, model, amount, opts?)` returns `{ used, limit, remaining, allowed, exceeded, windowStart, resetsAt, ... }`. `check(tenant, model)` is the read-only snapshot. Spin up one enforcer per dimension you meter — a monthly `cost-usd` budget and a per-minute `tokens` burst cap coexist as two `create()` calls sharing one store. Defends OWASP LLM10:2025 Unbounded Consumption / denial-of-wallet; maps to NIST AI RMF (AI 100-1) MANAGE 2.x and EU AI Act Art. 15 (robustness / resource-exhaustion resilience). · *`hard` / `soft` / `warn` enforcement* — `hard` (default) refuses the over-budget call and throws `aiQuota/exceeded` without charging — the rejected reservation is refunded so the counter is untouched. `soft` admits the charge but reports `allowed: false` so the caller decides whether to honor it. `warn` admits and allows (advisory), flagging `exceeded: true`. A per-call `consume(..., { enforcement })` override lets one endpoint soften the mode for a trusted internal caller without a second enforcer. Every over-budget event emits `ai/quota-exceeded` through the drop-silent audit chain (`ai/quota-applied` on success), tagged with the active cluster node id for attribution. · *Cross-node aggregate budgets via `opts.store`* — The default counter is in-memory (per-process). Supply `opts.store` exposing atomic `reserve` / `add` / `get` / `reset` (a Redis Lua script, a shared SQL row) and the ceiling is enforced on the cluster-wide aggregate. `hard` mode goes through `reserve`, an atomic conditional test-and-charge that adds the amount only if it fits — so a concurrent over-budget call cannot transiently inflate the counter and falsely deny a smaller call that should fit. Per-tenant and per-model limit overrides (`perTenant` / `perModel` / `perTenantModel`) are validated at config time so a malformed cap surfaces at boot, not as a silent fall-through to the default.
 
 - v0.12.26 (2026-05-24) — **`b.compliance` posture cascades — `eu-ai-act` + `ca-ab-853` + `cac-genai-label` POSTURE_DEFAULTS + backup encryption refusal.** Three new posture cascades wired into `b.compliance.POSTURE_DEFAULTS` + `KNOWN_POSTURES` + `REGIME_MAP` so operators globally pinning the EU AI Act / California AB-853 / China CAC GenAI postures get the right floors automatically: backupEncryptionRequired:true, auditChainSignedRequired:true, tlsMinVersion:TLSv1.3, requireVacuumAfterErase:true. `b.backup.bundleAdapterStorage` extends the encryption-required posture list to include the three new postures so `cryptoStrategy: "none"` is refused upfront under any of them (parity with HIPAA + PCI-DSS, which the operator surface has carried since v0.12.10). The canonical `eu-ai-act` posture is the production name; the legacy `ai-act` short name stays in KNOWN_POSTURES for back-compat with operators who pinned it pre-v0.12.26. **Added:** *`eu-ai-act` posture cascade — Regulation (EU) 2024/1689* — POSTURE_DEFAULTS entry: backupEncryptionRequired:true (Art. 12 logging + Art. 15 robustness/cybersecurity demand encryption-at-rest for high-risk system training logs), auditChainSignedRequired:true (Art. 12 + Art. 13 audit-chain integrity), tlsMinVersion:TLSv1.3, requireVacuumAfterErase:true (Art. 50(4) synthetic-content provenance — residual EXIF / metadata pointing at the generating model must be cleared on erase). REGIME_MAP entry under jurisdiction:"EU" domain:"ai-governance". KNOWN_POSTURES carries both `eu-ai-act` (canonical) and `ai-act` (legacy short name). · *`ca-ab-853` posture cascade — California AB-853 effective 2026* — Same encryption + audit floor as eu-ai-act; jurisdiction:"US-CA". Model-generated content watermarking + disclosure regime. Operators serving California traffic pin this posture for the AB-853 §22949.91 obligations the v0.12.12 deepfake primitive's crossWalk references. · *`cac-genai-label` posture cascade — China CAC GenAI Service Measures* — Synthetic-content labelling per Art. 12 + algorithm filing per Art. 4. Same backup encryption + signed audit chain floor. Operators serving Chinese traffic pin this posture so the bundleAdapterStorage refuses plaintext bundles and the disclosure primitive's `jurisdiction: "cn"` cross-walk produces the right legal-reference array. · *`bundleAdapterStorage` BACKUP_ENCRYPTION_REQUIRED_POSTURES extended* — `hipaa` + `pci-dss` (the v0.12.10 baseline) joined by the three AI postures. `cryptoStrategy: "none"` refused upfront under any of `eu-ai-act` / `ca-ab-853` / `cac-genai-label` with `backup/posture-requires-encryption`. Operators wiring backup storage in a regulated AI deployment now get the same posture-driven gate that the storage primitive has always applied to health + payment data.

package/README.md

@@ -163,6 +163,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **Agent identity** — A2A signed agent-card primitive (Linux Foundation Agentic AI Foundation v1.x, ML-DSA-87) (`b.a2a`)
 - **Content provenance** — C2PA 2.1 + California SB-942 / AB-853 manifest builder for AI-generated media (provider, model id + version, timestamp, content ID, signed) (`b.contentCredentials`)
 - **AI usage quotas** — per-tenant / per-model budgets metered by tokens / requests / cost-usd / compute-hours over calendar-aligned windows, with an atomic conditional reserve (no charge-then-refund race) + hard/soft/warn enforcement and an optional cross-node store; defends OWASP LLM10:2025 unbounded consumption / denial-of-wallet (`b.ai.quota`)
+- **AI capability routing** — model-capability registry (context window / modalities / tool use / reasoning tier / cost rates) + a router that picks the cheapest model satisfying a request's requirements, refusing capability mismatches before the inference call (NIST AI RMF MAP + Model Cards); composes with `b.ai.quota` cost budgets (`b.ai.capability`)
 ### Compliance regimes
 
 - **Posture coordinator** — `b.compliance` cascades operator-declared regime into retention / audit / db / cryptoField via POSTURE_DEFAULTS:
@@ -181,6 +182,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **Audit + segregation** — 21 CFR Part 11 §11.10(e) audit-content gate + §11.50(b) electronicSignature (`b.fda21cfr11`); PCI DSS 4.0 Req 10.4.1.1 daily-review automation (`b.auditDailyReview`); SOX §404 + SOC 2 CC1.3 segregation-of-duties via Postgres trigger DDL (`b.audit.bindActor`, `b.audit.assertSegregation`)
 - **Change control + WORM** — m-of-n approver DDL change-control with maintenance-window + ML-DSA-87 signed proposals (`b.ddlChangeControl`); row-level WORM triggers boot-asserted under `sec-17a-4` / `finra-4511` / `fda-21cfr11` (`b.db.declareWorm`); dual-control physical delete + crypto-erase + REINDEX in one transaction (`b.db.declareRequireDualControl`, `b.db.eraseHard`)
 - **Consumer-protection** — FTC click-to-cancel UX-parity attestation (`ftc-2024` / `ca-sb942` / `strict`) (`b.darkPatterns`)
+- **Differential privacy** — float-safe DP for aggregate releases: snapping-mechanism Laplace (Mironov 2012) + discrete Gaussian (Canonne–Kamath–Steinke 2020), CSPRNG noise, per-scope ε/δ budgets with basic + Rényi-DP accounting; defends the floating-point distinguishing attack that breaks naive Laplace samplers (NIST SP 800-226) (`b.ai.dp`)
 - **Privacy / DSR** — GDPR Articles 15–22 / CCPA / CPRA / LGPD / PIPEDA data-subject-rights workflow (`b.dsr`); IAB TCF v2.3 consent-string parser + `disclosedVendors` validator (`b.iabTcf`); IAB MSPA / GPP universal-opt-out (USNAT / USCA / USVA / USCO / USCT / USUT) + GPC mirror (`b.iabMspa`); generic consent capture + withdrawal (`b.consent`)
 - **Incident reporters** — EU DORA Article 17 ICT-incident workflow per Commission Delegated Regulation 2024/1772 (`b.dora`); EU NIS2 (`b.nis2`); EU Cyber Resilience Act SBOM + secure-software-attestation (`b.cra`); SEC Form 8-K Item 1.05 cybersecurity-incident materiality-disclosure (`b.secCyber`); incident lifecycle coordinator (`b.incident`)
 - **Outbound DLP** — interceptor-installed on httpClient + mail + webhook with built-in detectors for PAN (Luhn), SSN, EIN, IBAN (mod-97), api-key shapes, PEM, SSH private keys, JWTs, AWS access keys, PHI composite; refuse / redact / audit-only verdicts under pci-dss / hipaa / fapi2 / soc2 / gdpr presets (`b.redact.installOutboundDlp`)

package/index.js

@@ -444,6 +444,8 @@ module.exports = {
     modelManifest:   require("./lib/ai-model-manifest"),
     disclosure:      require("./lib/ai-disclosure"),
     quota:           require("./lib/ai-quota"),
+    capability:      require("./lib/ai-capability"),
+    dp:              require("./lib/ai-dp"),
   },
   promisePool:      require("./lib/promise-pool"),
   sdNotify:         require("./lib/sd-notify"),

package/lib/ai-capability.js

@@ -0,0 +1,482 @@
+"use strict";
+/**
+ * @module b.ai.capability
+ * @nav    AI
+ * @title  AI capability routing
+ *
+ * @intro
+ *   A capability registry + capability-aware router for AI model
+ *   fleets. NIST AI RMF (AI 100-1) MAP 2.x requires documenting each
+ *   model's capabilities and limitations; the Model Cards convention
+ *   (Mitchell et al., 2019) formalizes that descriptor. This module
+ *   turns those descriptors into a routing decision: given a set of
+ *   requirements (context window, modalities, tool use, reasoning
+ *   tier, …), pick the <em>cheapest</em> model in the fleet that
+ *   satisfies all of them, or fall back deterministically.
+ *
+ *   <code>b.ai.capability.create({ models })</code> builds a registry
+ *   from operator-supplied descriptors and returns:
+ *
+ *   - <code>describe(modelId)</code> — the frozen descriptor.
+ *   - <code>list()</code> — every registered model id.
+ *   - <code>register(modelId, descriptor)</code> — add / replace one.
+ *   - <code>satisfies(modelId, requirements)</code> —
+ *     <code>{ ok, failures }</code> where each failure names the
+ *     requirement, the need, and what the model has.
+ *   - <code>route({ requirements, fallback?, costBasis? })</code> —
+ *     the cheapest satisfying model, or the fallback, or a refusal.
+ *
+ *   A descriptor carries: <code>maxContextTokens</code>,
+ *   <code>maxOutputTokens</code>, <code>modalitiesIn</code> /
+ *   <code>modalitiesOut</code> (arrays — e.g. <code>"text"</code>,
+ *   <code>"image"</code>, <code>"audio"</code>, <code>"video"</code>),
+ *   <code>toolUse</code>, <code>structuredOutput</code>,
+ *   <code>fineTunable</code>, <code>reasoningTier</code>
+ *   (<code>"none" | "basic" | "standard" | "advanced"</code>,
+ *   ordered), <code>citationSupport</code>,
+ *   <code>promptCachingMaxTokens</code>, and the cost rates
+ *   <code>costPer1kInputTokens</code> / <code>costPer1kOutputTokens</code>.
+ *
+ *   <strong>Routing picks the cheapest match.</strong> When a
+ *   <code>costBasis</code> (<code>{ inputTokens, outputTokens }</code>)
+ *   is supplied the router estimates the per-call cost and ranks by
+ *   it; otherwise it ranks by the sum of the per-1k rates. Ties break
+ *   by model id so the choice is deterministic. Routing to the
+ *   cheapest sufficient model is the front-line defense against
+ *   over-provisioning spend — it composes with
+ *   <code>b.ai.quota</code>'s <code>cost-usd</code> dimension, where
+ *   the chosen descriptor's rate feeds the budget charge.
+ *
+ *   Refusing to route a request to a model that cannot satisfy it
+ *   (missing modality, too-small context window, no tool use) catches
+ *   a capability mismatch before the inference call burns tokens on a
+ *   guaranteed-bad result.
+ *
+ * @card
+ *   Capability registry + cheapest-satisfying-model router for AI
+ *   model fleets (context / modalities / tool use / reasoning tier /
+ *   cost). Composes with b.ai.quota cost budgets.
+ */
+
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var AiCapabilityError = defineClass("AiCapabilityError", { alwaysPermanent: true });
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+// Ordered reasoning tiers — a requirement of `minReasoningTier:
+// "standard"` is satisfied by "standard" or "advanced", not "basic".
+var REASONING_TIERS = ["none", "basic", "standard", "advanced"];
+
+// Cost rates are quoted per 1000 tokens (industry convention; the
+// descriptor fields are costPer1kInputTokens / costPer1kOutputTokens).
+// Dividing a token count by this rate unit converts a per-1k rate into
+// the per-token multiplier — a rate denominator, not a byte size.
+var COST_RATE_TOKEN_UNIT = 1000;   // allow:raw-byte-literal — per-1k-token cost-rate denominator, not a byte count
+
+var DESCRIPTOR_KEYS = [
+  "maxContextTokens", "maxOutputTokens", "modalitiesIn", "modalitiesOut",
+  "toolUse", "structuredOutput", "fineTunable", "reasoningTier",
+  "citationSupport", "promptCachingMaxTokens",
+  "costPer1kInputTokens", "costPer1kOutputTokens", "provider", "version",
+];
+
+var REQUIREMENT_KEYS = [
+  "minContextTokens", "minOutputTokens", "modalitiesIn", "modalitiesOut",
+  "toolUse", "structuredOutput", "fineTunable", "minReasoningTier",
+  "citationSupport", "minPromptCachingTokens",
+];
+
+function _isPositiveInt(n) {
+  return typeof n === "number" && isFinite(n) && n > 0 && Math.floor(n) === n;
+}
+function _isNonNegFinite(n) {
+  return typeof n === "number" && isFinite(n) && n >= 0;
+}
+function _isStringArray(a) {
+  if (!Array.isArray(a)) return false;
+  for (var i = 0; i < a.length; i++) {
+    if (typeof a[i] !== "string" || a[i].length === 0) return false;
+  }
+  return true;
+}
+
+// Normalize + validate one descriptor at registration time so a typo
+// (negative cost, unknown reasoning tier, non-array modality list)
+// surfaces at config time rather than as a silent mis-route.
+function _normalizeDescriptor(modelId, d) {
+  if (!d || typeof d !== "object" || Array.isArray(d)) {
+    throw new AiCapabilityError("aiCapability/bad-descriptor",
+      "ai.capability: descriptor for '" + modelId + "' must be a plain object");
+  }
+  validateOpts(d, DESCRIPTOR_KEYS, "ai.capability descriptor['" + modelId + "']");
+
+  if (!_isPositiveInt(d.maxContextTokens)) {
+    throw new AiCapabilityError("aiCapability/bad-descriptor",
+      "ai.capability: '" + modelId + "'.maxContextTokens must be a positive integer");
+  }
+  var maxOut = (d.maxOutputTokens == null) ? d.maxContextTokens : d.maxOutputTokens;
+  if (!_isPositiveInt(maxOut)) {
+    throw new AiCapabilityError("aiCapability/bad-descriptor",
+      "ai.capability: '" + modelId + "'.maxOutputTokens must be a positive integer");
+  }
+
+  var modIn = (d.modalitiesIn == null) ? ["text"] : d.modalitiesIn;
+  var modOut = (d.modalitiesOut == null) ? ["text"] : d.modalitiesOut;
+  if (!_isStringArray(modIn) || !_isStringArray(modOut)) {
+    throw new AiCapabilityError("aiCapability/bad-descriptor",
+      "ai.capability: '" + modelId + "'.modalitiesIn / modalitiesOut must be arrays of non-empty strings");
+  }
+
+  var tier = (d.reasoningTier == null) ? "standard" : d.reasoningTier;
+  if (REASONING_TIERS.indexOf(tier) === -1) {
+    throw new AiCapabilityError("aiCapability/bad-descriptor",
+      "ai.capability: '" + modelId + "'.reasoningTier must be one of " + REASONING_TIERS.join(" / "));
+  }
+
+  var cachingMax = (d.promptCachingMaxTokens == null) ? 0 : d.promptCachingMaxTokens;
+  var costIn = (d.costPer1kInputTokens == null) ? 0 : d.costPer1kInputTokens;
+  var costOut = (d.costPer1kOutputTokens == null) ? 0 : d.costPer1kOutputTokens;
+  if (!_isNonNegFinite(cachingMax) || !_isNonNegFinite(costIn) || !_isNonNegFinite(costOut)) {
+    throw new AiCapabilityError("aiCapability/bad-descriptor",
+      "ai.capability: '" + modelId + "'.promptCachingMaxTokens / costPer1kInputTokens / " +
+      "costPer1kOutputTokens must be non-negative finite numbers");
+  }
+
+  return Object.freeze({
+    modelId:                modelId,
+    maxContextTokens:       d.maxContextTokens,
+    maxOutputTokens:        maxOut,
+    modalitiesIn:           Object.freeze(modIn.slice()),
+    modalitiesOut:          Object.freeze(modOut.slice()),
+    toolUse:                d.toolUse === true,
+    structuredOutput:       d.structuredOutput === true,
+    fineTunable:            d.fineTunable === true,
+    reasoningTier:          tier,
+    citationSupport:        d.citationSupport === true,
+    promptCachingMaxTokens: cachingMax,
+    costPer1kInputTokens:   costIn,
+    costPer1kOutputTokens:  costOut,
+    provider:               (typeof d.provider === "string") ? d.provider : null,
+    version:                (typeof d.version === "string") ? d.version : null,
+  });
+}
+
+/**
+ * @primitive b.ai.capability.create
+ * @signature b.ai.capability.create(opts)
+ * @since     0.12.28
+ * @status    stable
+ * @compliance soc2
+ * @related   b.ai.quota.create, b.ai.modelManifest.build
+ *
+ * Build a capability registry + router from operator-supplied model
+ * descriptors. Returns <code>{ describe, list, register, satisfies,
+ * route }</code>. Pair it with <code>b.ai.quota</code>:
+ * <code>route()</code> picks the cheapest model that meets the
+ * request, and the chosen descriptor's cost rate feeds the
+ * <code>cost-usd</code> budget charge.
+ *
+ * @opts
+ *   {
+ *     models: {                       // required, ≥ 1 entry
+ *       [modelId: string]: {
+ *         maxContextTokens:        number,    // required, positive int
+ *         maxOutputTokens?:        number,    // default: maxContextTokens
+ *         modalitiesIn?:           string[],  // default: ["text"]
+ *         modalitiesOut?:          string[],  // default: ["text"]
+ *         toolUse?:                boolean,   // default: false
+ *         structuredOutput?:       boolean,   // default: false
+ *         fineTunable?:            boolean,   // default: false
+ *         reasoningTier?:          string,    // none|basic|standard|advanced
+ *         citationSupport?:        boolean,   // default: false
+ *         promptCachingMaxTokens?: number,    // default: 0
+ *         costPer1kInputTokens?:   number,    // default: 0
+ *         costPer1kOutputTokens?:  number,    // default: 0
+ *         provider?:               string,
+ *         version?:                string,
+ *       }
+ *     },
+ *     audit?: boolean,                // default: true (route decisions)
+ *   }
+ *
+ * @example
+ *   var fleet = b.ai.capability.create({
+ *     models: {
+ *       "haiku":  { maxContextTokens: 200000, reasoningTier: "basic",
+ *                   costPer1kInputTokens: 0.001, costPer1kOutputTokens: 0.005 },
+ *       "opus":   { maxContextTokens: 200000, reasoningTier: "advanced",
+ *                   toolUse: true, modalitiesIn: ["text", "image"],
+ *                   costPer1kInputTokens: 0.015, costPer1kOutputTokens: 0.075 },
+ *     },
+ *   });
+ *   var pick = fleet.route({
+ *     requirements: { minContextTokens: 100000, toolUse: true,
+ *                     modalitiesIn: ["text", "image"] },
+ *     costBasis:    { inputTokens: 4000, outputTokens: 500 },
+ *   });
+ *   // → { modelId: "opus", descriptor: {...}, estimatedCost: 0.0975, reason: "cheapest-of-1" }
+ */
+function create(opts) {
+  validateOpts.requireObject(opts, "ai.capability.create", AiCapabilityError);
+  validateOpts(opts, ["models", "audit"], "ai.capability.create");
+
+  if (!opts.models || typeof opts.models !== "object" || Array.isArray(opts.models)) {
+    throw new AiCapabilityError("aiCapability/bad-models",
+      "ai.capability.create: models must be a plain object { modelId: descriptor }");
+  }
+  var ids = Object.keys(opts.models);
+  if (ids.length === 0) {
+    throw new AiCapabilityError("aiCapability/bad-models",
+      "ai.capability.create: models must declare at least one model");
+  }
+
+  var registry = new Map();
+  for (var i = 0; i < ids.length; i++) {
+    registry.set(ids[i], _normalizeDescriptor(ids[i], opts.models[ids[i]]));
+  }
+  var auditOn = opts.audit !== false;
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({ action: action, outcome: outcome, metadata: metadata || {} });
+    } catch (_e) { /* audit best-effort — drop-silent */ }
+  }
+
+  function describe(modelId) {
+    var d = registry.get(modelId);
+    if (!d) {
+      throw new AiCapabilityError("aiCapability/unknown-model",
+        "ai.capability.describe: unknown model '" + modelId + "'");
+    }
+    return d;
+  }
+
+  function list() {
+    return Array.from(registry.keys());
+  }
+
+  function register(modelId, descriptor) {
+    validateOpts.requireNonEmptyString(modelId,
+      "ai.capability.register: modelId", AiCapabilityError, "aiCapability/bad-model");
+    registry.set(modelId, _normalizeDescriptor(modelId, descriptor));
+    return registry.get(modelId);
+  }
+
+  // Returns { ok, failures } — every unmet requirement names what was
+  // needed and what the model has, so a caller can surface a precise
+  // capability-mismatch reason instead of a bare boolean.
+  function _evaluate(descriptor, requirements) {
+    var failures = [];
+    function fail(requirement, need, have) {
+      failures.push({ requirement: requirement, need: need, have: have });
+    }
+    if (requirements.minContextTokens != null &&
+        descriptor.maxContextTokens < requirements.minContextTokens) {
+      fail("minContextTokens", requirements.minContextTokens, descriptor.maxContextTokens);
+    }
+    if (requirements.minOutputTokens != null &&
+        descriptor.maxOutputTokens < requirements.minOutputTokens) {
+      fail("minOutputTokens", requirements.minOutputTokens, descriptor.maxOutputTokens);
+    }
+    if (requirements.modalitiesIn != null) {
+      for (var a = 0; a < requirements.modalitiesIn.length; a++) {
+        if (descriptor.modalitiesIn.indexOf(requirements.modalitiesIn[a]) === -1) {
+          fail("modalitiesIn", requirements.modalitiesIn[a], descriptor.modalitiesIn);
+        }
+      }
+    }
+    if (requirements.modalitiesOut != null) {
+      for (var b = 0; b < requirements.modalitiesOut.length; b++) {
+        if (descriptor.modalitiesOut.indexOf(requirements.modalitiesOut[b]) === -1) {
+          fail("modalitiesOut", requirements.modalitiesOut[b], descriptor.modalitiesOut);
+        }
+      }
+    }
+    if (requirements.toolUse === true && descriptor.toolUse !== true) {
+      fail("toolUse", true, false);
+    }
+    if (requirements.structuredOutput === true && descriptor.structuredOutput !== true) {
+      fail("structuredOutput", true, false);
+    }
+    if (requirements.fineTunable === true && descriptor.fineTunable !== true) {
+      fail("fineTunable", true, false);
+    }
+    if (requirements.citationSupport === true && descriptor.citationSupport !== true) {
+      fail("citationSupport", true, false);
+    }
+    if (requirements.minReasoningTier != null &&
+        REASONING_TIERS.indexOf(descriptor.reasoningTier) <
+        REASONING_TIERS.indexOf(requirements.minReasoningTier)) {
+      fail("minReasoningTier", requirements.minReasoningTier, descriptor.reasoningTier);
+    }
+    if (requirements.minPromptCachingTokens != null &&
+        descriptor.promptCachingMaxTokens < requirements.minPromptCachingTokens) {
+      fail("minPromptCachingTokens", requirements.minPromptCachingTokens, descriptor.promptCachingMaxTokens);
+    }
+    return { ok: failures.length === 0, failures: failures };
+  }
+
+  function _validateRequirements(requirements) {
+    if (requirements == null) return {};
+    if (typeof requirements !== "object" || Array.isArray(requirements)) {
+      throw new AiCapabilityError("aiCapability/bad-requirements",
+        "ai.capability: requirements must be a plain object");
+    }
+    validateOpts(requirements, REQUIREMENT_KEYS, "ai.capability requirements");
+    if (requirements.minReasoningTier != null &&
+        REASONING_TIERS.indexOf(requirements.minReasoningTier) === -1) {
+      throw new AiCapabilityError("aiCapability/bad-requirements",
+        "ai.capability: minReasoningTier must be one of " + REASONING_TIERS.join(" / "));
+    }
+    if (requirements.modalitiesIn != null && !_isStringArray(requirements.modalitiesIn)) {
+      throw new AiCapabilityError("aiCapability/bad-requirements",
+        "ai.capability: requirements.modalitiesIn must be an array of non-empty strings");
+    }
+    if (requirements.modalitiesOut != null && !_isStringArray(requirements.modalitiesOut)) {
+      throw new AiCapabilityError("aiCapability/bad-requirements",
+        "ai.capability: requirements.modalitiesOut must be an array of non-empty strings");
+    }
+    // Numeric minimums are compared with `<` against the descriptor; a
+    // non-numeric value (NaN, "128k", a bad parse) makes that compare
+    // false and SILENTLY satisfies the requirement, so an undersized
+    // model could be selected. Reject non-finite / negative here so a
+    // malformed requirement fails fast instead of fail-open.
+    var numericMins = ["minContextTokens", "minOutputTokens", "minPromptCachingTokens"];
+    for (var ni = 0; ni < numericMins.length; ni++) {
+      var nk = numericMins[ni];
+      if (requirements[nk] != null && !_isNonNegFinite(requirements[nk])) {
+        throw new AiCapabilityError("aiCapability/bad-requirements",
+          "ai.capability: requirements." + nk + " must be a non-negative finite number");
+      }
+    }
+    // Boolean opt-in requirements are matched with `=== true`; a
+    // non-boolean (truthy 1, "false") would silently fail to require
+    // the capability. Reject non-booleans so the intent is explicit.
+    var booleanReqs = ["toolUse", "structuredOutput", "fineTunable", "citationSupport"];
+    for (var bi = 0; bi < booleanReqs.length; bi++) {
+      var bk = booleanReqs[bi];
+      if (requirements[bk] != null && typeof requirements[bk] !== "boolean") {
+        throw new AiCapabilityError("aiCapability/bad-requirements",
+          "ai.capability: requirements." + bk + " must be a boolean");
+      }
+    }
+    return requirements;
+  }
+
+  function satisfies(modelId, requirements) {
+    return _evaluate(describe(modelId), _validateRequirements(requirements));
+  }
+
+  // Per-call cost estimate. With a costBasis the estimate is the
+  // real per-call spend (input + output tokens at the model's rates);
+  // without one it is the sum of the per-1k rates — a stable proxy
+  // for "cheaper model" when the caller hasn't sized the request.
+  function _estimateCost(descriptor, costBasis) {
+    if (costBasis) {
+      var inTok = _isNonNegFinite(costBasis.inputTokens) ? costBasis.inputTokens : 0;
+      var outTok = _isNonNegFinite(costBasis.outputTokens) ? costBasis.outputTokens : 0;
+      return (inTok / COST_RATE_TOKEN_UNIT) * descriptor.costPer1kInputTokens +
+             (outTok / COST_RATE_TOKEN_UNIT) * descriptor.costPer1kOutputTokens;
+    }
+    return descriptor.costPer1kInputTokens + descriptor.costPer1kOutputTokens;
+  }
+
+  function route(routeOpts) {
+    routeOpts = routeOpts || {};
+    validateOpts(routeOpts, ["requirements", "fallback", "costBasis"], "ai.capability.route");
+    var requirements = _validateRequirements(routeOpts.requirements);
+    var costBasis = null;
+    if (routeOpts.costBasis != null) {
+      if (typeof routeOpts.costBasis !== "object" || Array.isArray(routeOpts.costBasis)) {
+        throw new AiCapabilityError("aiCapability/bad-requirements",
+          "ai.capability.route: costBasis must be a plain object { inputTokens, outputTokens }");
+      }
+      validateOpts(routeOpts.costBasis, ["inputTokens", "outputTokens"],
+        "ai.capability.route costBasis");
+      // A malformed costBasis field silently underprices a candidate
+      // and biases the "cheapest" choice toward the wrong model — fail
+      // fast instead. An absent field is fine (treated as 0 tokens on
+      // that side); a present-but-non-numeric field is rejected.
+      var cbFields = ["inputTokens", "outputTokens"];
+      for (var ci = 0; ci < cbFields.length; ci++) {
+        var ck = cbFields[ci];
+        if (routeOpts.costBasis[ck] != null && !_isNonNegFinite(routeOpts.costBasis[ck])) {
+          throw new AiCapabilityError("aiCapability/bad-requirements",
+            "ai.capability.route: costBasis." + ck + " must be a non-negative finite number");
+        }
+      }
+      costBasis = routeOpts.costBasis;
+    }
+
+    // Collect every satisfying model, then pick the cheapest. Tie
+    // break by model id (lexicographic) so the choice is deterministic
+    // across calls and across nodes.
+    var candidates = [];
+    var modelIds = Array.from(registry.keys());
+    for (var i = 0; i < modelIds.length; i++) {
+      var d = registry.get(modelIds[i]);
+      if (_evaluate(d, requirements).ok) {
+        candidates.push({ modelId: modelIds[i], descriptor: d, cost: _estimateCost(d, costBasis) });
+      }
+    }
+    candidates.sort(function (x, y) {
+      if (x.cost !== y.cost) return x.cost - y.cost;
+      return x.modelId < y.modelId ? -1 : (x.modelId > y.modelId ? 1 : 0);
+    });
+
+    if (candidates.length > 0) {
+      var pick = candidates[0];
+      _emitAudit("ai/capability-routed", "allowed", {
+        modelId: pick.modelId, candidateCount: candidates.length,
+        estimatedCost: pick.cost, requirements: requirements,
+      });
+      return {
+        modelId:       pick.modelId,
+        descriptor:    pick.descriptor,
+        estimatedCost: pick.cost,
+        reason:        "cheapest-of-" + candidates.length,
+      };
+    }
+
+    // No model satisfies the requirements.
+    if (routeOpts.fallback != null) {
+      var fb = registry.get(routeOpts.fallback);
+      if (!fb) {
+        throw new AiCapabilityError("aiCapability/unknown-model",
+          "ai.capability.route: fallback '" + routeOpts.fallback + "' is not a registered model");
+      }
+      _emitAudit("ai/capability-fallback", "allowed", {
+        modelId: routeOpts.fallback, requirements: requirements,
+      });
+      return {
+        modelId:       routeOpts.fallback,
+        descriptor:    fb,
+        estimatedCost: _estimateCost(fb, costBasis),
+        reason:        "fallback",
+      };
+    }
+
+    _emitAudit("ai/capability-no-candidate", "denied", { requirements: requirements });
+    throw new AiCapabilityError("aiCapability/no-candidate",
+      "ai.capability.route: no registered model satisfies the requirements " +
+      "and no fallback was supplied");
+  }
+
+  return {
+    describe:  describe,
+    list:      list,
+    register:  register,
+    satisfies: satisfies,
+    route:     route,
+  };
+}
+
+module.exports = {
+  create:             create,
+  REASONING_TIERS:    REASONING_TIERS,
+  AiCapabilityError:  AiCapabilityError,
+};

package/lib/ai-dp.js

@@ -0,0 +1,539 @@
+"use strict";
+/**
+ * @module b.ai.dp
+ * @nav    Compliance
+ * @title  Differential privacy
+ *
+ * @intro
+ *   Float-safe differential-privacy mechanisms with per-scope privacy
+ *   budgeting. Differential privacy adds calibrated noise to an
+ *   aggregate so the output is provably insensitive to any single
+ *   record — but the guarantee is fragile: Mironov (2012) showed that
+ *   a Laplace mechanism implemented with naive double-precision
+ *   sampling lets an attacker distinguish neighbouring datasets with
+ *   &gt; 35% probability from a <em>single</em> output, silently
+ *   destroying the promise. This module ships only mechanisms whose
+ *   sampling is hardened against that class of attack:
+ *
+ *   - <strong>Laplace via the snapping mechanism</strong> (Mironov
+ *     2012): clamp to a bound, draw a CSPRNG sign + full-mantissa
+ *     uniform, then round to a power-of-two grid — the rounding
+ *     removes the exploitable low-order mantissa bits. Pure
+ *     ε-differential privacy.
+ *   - <strong>Discrete Gaussian</strong> (Canonne–Kamath–Steinke
+ *     2020): integer-exact rejection sampling built from
+ *     Bernoulli(exp(−γ)) over exact rationals — no floating-point
+ *     noise at all. (ε, δ)-differential privacy, integer-valued.
+ *
+ *   All randomness comes from <code>b.crypto.generateBytes</code>
+ *   (SHAKE256 over the OS CSPRNG), never <code>Math.random</code>.
+ *
+ *   <code>b.ai.dp.budget({ scope, epsilon, delta })</code> tracks a
+ *   privacy budget per scope (per-user / per-tenant / per-query-class)
+ *   and refuses a <code>consume</code> that would exceed it.
+ *   Composition is accounted two ways:
+ *
+ *   - <code>"basic"</code> (default) — sum the per-release ε and δ.
+ *     Always valid; conservative.
+ *   - <code>"rdp"</code> — a Rényi DP accountant (Mironov 2017) tracks
+ *     RDP across a grid of orders and converts to (ε, δ) at the
+ *     scope's δ, giving a much tighter bound under repeated Gaussian
+ *     releases. Requires <code>delta &gt; 0</code>.
+ *
+ *   NIST SP 800-226 (2025) is the evaluation standard for these
+ *   guarantees; Dwork &amp; Roth, "The Algorithmic Foundations of
+ *   Differential Privacy", is the canonical reference.
+ *
+ *   The exponential and sparse-vector mechanisms are
+ *   deferred-with-condition: their float-safe constructions (the
+ *   base-2 / permute-and-flip exponential mechanism, Ilvento 2019; a
+ *   snapped sparse-vector) are a distinct effort, and shipping them
+ *   float-<em>unsafe</em> would defeat the module's purpose. They
+ *   re-open on operator demand with the named construction.
+ *
+ * @card
+ *   Float-safe differential privacy — snapping-mechanism Laplace
+ *   (Mironov 2012) + discrete Gaussian (CKS20), CSPRNG noise, per-
+ *   scope ε/δ budgets with basic + Rényi-DP accounting.
+ */
+
+var bCrypto = require("./crypto");
+var validateOpts = require("./validate-opts");
+var lazyRequire = require("./lazy-require");
+var { defineClass } = require("./framework-error");
+
+var AiDpError = defineClass("AiDpError", { alwaysPermanent: true });
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+var MECHANISMS = ["laplace", "gaussian"];
+var ACCOUNTINGS = ["basic", "rdp"];
+
+// Rational approximation precision for a real-valued σ² fed to the
+// integer-exact discrete-Gaussian sampler. 2^32 keeps the deviation
+// from the target σ² below 2^-32 — far under the noise scale — while
+// keeping the BigInt denominators bounded.
+var SIGMA2_RATIONAL_DEN = 4294967296;          // allow:raw-byte-literal — 2^32 rational-approx denominator, not a byte size
+
+// ---- Minimal exact rational (BigInt num / den, den > 0) ----
+
+function _gcd(a, b) {
+  a = a < 0n ? -a : a;
+  b = b < 0n ? -b : b;
+  while (b) { var t = a % b; a = b; b = t; }
+  return a;
+}
+function _fr(num, den) {
+  if (den < 0n) { num = -num; den = -den; }
+  var g = _gcd(num, den) || 1n;
+  return { num: num / g, den: den / g };
+}
+function _frFromFloat(x, den) {
+  // den is a Number power-of-two-ish denominator; round(x*den)/den.
+  return _fr(BigInt(Math.round(x * den)), BigInt(den));
+}
+function _frMul(a, b) { return _fr(a.num * b.num, a.den * b.den); }
+function _frSub(a, b) { return _fr(a.num * b.den - b.num * a.den, a.den * b.den); }
+function _frLte(a, b) { return a.num * b.den <= b.num * a.den; }       // a <= b
+function _frGt(a, b)  { return a.num * b.den >  b.num * a.den; }       // a >  b
+
+// ---- CSPRNG primitives (all noise routes through b.crypto) ----
+
+// Uniform BigInt in [0, m) via rejection sampling on CSPRNG bytes —
+// no modulo bias.
+function _uniformBelow(m) {
+  if (m <= 0n) throw new AiDpError("aiDp/internal", "ai.dp: _uniformBelow needs m > 0");
+  if (m === 1n) return 0n;
+  var bits = m.toString(2).length;
+  var bytes = Math.ceil(bits / 8);                        // allow:raw-byte-literal — bits-per-byte divisor, not a size
+  var mask = (1n << BigInt(bits)) - 1n;
+  for (;;) {
+    var buf = bCrypto.generateBytes(bytes);
+    var x = 0n;
+    for (var i = 0; i < bytes; i++) x = (x << 8n) | BigInt(buf[i]);
+    x = x & mask;
+    if (x < m) return x;
+  }
+}
+
+// Uniform double in (0, 1] with full 53-bit mantissa entropy — the
+// snapping mechanism's noise source. A 53-bit integer is drawn via
+// the BigInt rejection sampler (accumulating 53 bits in a JS Number
+// would overflow the 2^53 safe-integer range and skew the draw), then
+// mapped (val + 1) / 2^53 → (0, 1].
+var TWO_POW_53 = 9007199254740992;                         // allow:raw-byte-literal — 2^53 mantissa range, not a byte size
+function _uniformOpen() {
+  var v = Number(_uniformBelow(9007199254740992n));        // [0, 2^53) exact
+  return (v + 1) / TWO_POW_53;                             // (0, 1]
+}
+
+function _randomSign() {
+  return (bCrypto.generateBytes(1)[0] & 1) === 1 ? 1 : -1;
+}
+
+// ---- Canonne–Kamath–Steinke 2020 integer-exact samplers ----
+// Ported verbatim from the reference implementation
+// (github.com/IBM/discrete-gaussian-differential-privacy). All
+// arithmetic is exact (BigInt rationals); no floating-point noise.
+
+function _bernoulli(p) {                                   // p rational in [0,1]
+  return _uniformBelow(p.den) < p.num ? 1 : 0;
+}
+function _bernoulliExp1(x) {                               // x rational in [0,1]
+  var k = 1n;
+  for (;;) {
+    if (_bernoulli(_fr(x.num, x.den * k)) === 1) k = k + 1n;
+    else break;
+  }
+  return Number(k % 2n);
+}
+function _bernoulliExp(x) {                                // x rational >= 0
+  while (_frGt(x, _fr(1n, 1n))) {
+    if (_bernoulliExp1(_fr(1n, 1n)) === 1) x = _frSub(x, _fr(1n, 1n));
+    else return 0;
+  }
+  return _bernoulliExp1(x);
+}
+function _geometricExpSlow(x) {                            // x rational >= 0
+  var k = 0n;
+  for (;;) {
+    if (_bernoulliExp(x) === 1) k = k + 1n;
+    else return k;
+  }
+}
+function _geometricExpFast(x) {                            // x rational > 0; returns BigInt
+  if (x.num === 0n) return 0n;
+  var t = x.den;
+  var u;
+  for (;;) {
+    u = _uniformBelow(t);
+    if (_bernoulliExp(_fr(u, t)) === 1) break;
+  }
+  var v = _geometricExpSlow(_fr(1n, 1n));
+  var value = v * t + u;
+  return value / x.num;                                   // integer division
+}
+function _sampleDLaplace(scaleNum, scaleDen) {            // Lap_Z(scale); returns BigInt
+  var invScale = _fr(scaleDen, scaleNum);                 // 1 / scale
+  for (;;) {
+    var sign = _bernoulli(_fr(1n, 2n));
+    var magnitude = _geometricExpFast(invScale);
+    if (sign === 1 && magnitude === 0n) continue;
+    return magnitude * BigInt(1 - 2 * sign);
+  }
+}
+function _floorSqrtFrac(fr) {                              // floor(sqrt(rational)); returns BigInt
+  var num = fr.num, den = fr.den;
+  var a = 0n, b = 1n;
+  while (b * b * den <= num) b = 2n * b;
+  while (a + 1n < b) {
+    var c = (a + b) / 2n;
+    if (c * c * den <= num) a = c; else b = c;
+  }
+  return a;
+}
+function _sampleDGauss(sigma2) {                          // sigma2 rational > 0; returns BigInt
+  var t = _floorSqrtFrac(sigma2) + 1n;
+  var two_sigma2 = _fr(2n * sigma2.num, sigma2.den);      // 2 * sigma2
+  var sigma2_over_t = _fr(sigma2.num, sigma2.den * t);    // sigma2 / t
+  for (;;) {
+    var candidate = _sampleDLaplace(t, 1n);
+    var absC = candidate < 0n ? -candidate : candidate;
+    var diff = _frSub(_fr(absC, 1n), sigma2_over_t);       // |candidate| - sigma2/t
+    // bias = diff^2 / (2 sigma2)  — multiply diff^2 by the reciprocal of 2σ².
+    var diff2 = _fr(diff.num * diff.num, diff.den * diff.den);
+    var bias = _frMul(diff2, _fr(two_sigma2.den, two_sigma2.num));
+    if (_bernoulliExp(bias) === 1) return candidate;
+  }
+}
+
+// ---- Snapping-mechanism Laplace (Mironov 2012), float-safe ----
+
+function _clamp(x, bound) {
+  if (x < -bound) return -bound;
+  if (x > bound) return bound;
+  return x;
+}
+function _snappingLaplace(value, scale, bound) {
+  // scale = sensitivity / epsilon (Laplace b). bound B clamps the
+  // input + output; the privacy guarantee depends on it. Lambda is
+  // the smallest power of two >= scale, so inner / Lambda and
+  // Lambda * round(...) are exact float ops — that is what removes
+  // the attackable low-order bits the naive sampler leaks.
+  var xc = _clamp(value, bound);
+  var S = _randomSign();
+  var U = _uniformOpen();                                 // (0, 1]
+  var lambdaPow = Math.pow(2, Math.ceil(Math.log2(scale)));
+  var inner = xc + S * scale * Math.log(U);
+  var rounded = lambdaPow * Math.round(inner / lambdaPow);
+  return _clamp(rounded, bound);
+}
+
+// ---- Rényi-DP costs (Mironov 2017) ----
+
+var RDP_ORDERS = [1.25, 1.5, 1.75, 2, 2.5, 3, 4, 5, 6, 8, 12, 16, 24, 32, 48, 64, 128, 256];   // allow:raw-byte-literal — Rényi DP orders (α), not byte sizes
+
+// Gaussian mechanism with noise-to-sensitivity z = sigma / sensitivity:
+// RDP(alpha) = alpha / (2 z^2).
+function _rdpGaussian(alpha, sigma, sensitivity) {
+  var z = sigma / sensitivity;
+  return alpha / (2 * z * z);
+}
+// Laplace mechanism with pure-DP parameter eps0 (= sensitivity / scale):
+// RDP(alpha) = (1/(alpha-1)) * ln( (alpha/(2alpha-1)) e^{(alpha-1)eps0}
+//              + ((alpha-1)/(2alpha-1)) e^{-alpha eps0} ).
+function _rdpLaplace(alpha, eps0) {
+  var a = alpha;
+  var num1 = a / (2 * a - 1);
+  var num2 = (a - 1) / (2 * a - 1);
+  var term = num1 * Math.exp((a - 1) * eps0) + num2 * Math.exp(-a * eps0);
+  return Math.log(term) / (a - 1);
+}
+// Convert an RDP curve (rdp[order]) to (eps, delta): the standard
+// RDP -> DP bound eps(delta) = min_alpha ( rdp(alpha) + ln(1/delta)/(alpha-1) ).
+function _rdpToEpsilon(rdpByOrder, delta) {
+  var best = Infinity;
+  for (var i = 0; i < RDP_ORDERS.length; i++) {
+    var a = RDP_ORDERS[i];
+    var e = rdpByOrder[i] + Math.log(1 / delta) / (a - 1);
+    if (e < best) best = e;
+  }
+  return best;
+}
+
+// ---- mechanism descriptor ----
+
+/**
+ * @primitive b.ai.dp.mechanism
+ * @signature b.ai.dp.mechanism(opts)
+ * @since     0.12.29
+ * @status    stable
+ * @compliance gdpr, soc2
+ * @related   b.ai.dp.budget, b.ai.quota.create
+ *
+ * Build a float-safe DP noise mechanism. <code>type: "laplace"</code>
+ * is the snapping mechanism (pure ε-DP, real-valued, needs a
+ * <code>bound</code>); <code>type: "gaussian"</code> is the discrete
+ * Gaussian (integer-valued, (ε, δ)-DP, needs <code>delta</code>).
+ * Pass the result to <code>budget.consume(mechanism, value)</code>.
+ *
+ * @opts
+ *   {
+ *     type:        string,   // "laplace" | "gaussian"
+ *     sensitivity: number,   // required, > 0 (L1 for laplace, L1/integer for gaussian)
+ *     epsilon:     number,   // required, > 0 (per-release ε; ε ≤ 1 for the
+ *                            //   classic Gaussian calibration)
+ *     delta?:      number,   // gaussian only, required, 0 < δ < 1
+ *     bound?:      number,   // laplace only, required, > 0 — clamp bound B
+ *   }
+ *
+ * @example
+ *   var lap = b.ai.dp.mechanism({ type: "laplace", sensitivity: 1, epsilon: 0.5, bound: 1000 });
+ *   var gss = b.ai.dp.mechanism({ type: "gaussian", sensitivity: 1, epsilon: 0.5, delta: 1e-6 });
+ */
+function mechanism(opts) {
+  validateOpts.requireObject(opts, "ai.dp.mechanism", AiDpError);
+  validateOpts(opts, ["type", "sensitivity", "epsilon", "delta", "bound"], "ai.dp.mechanism");
+
+  if (MECHANISMS.indexOf(opts.type) === -1) {
+    throw new AiDpError("aiDp/bad-mechanism",
+      "ai.dp.mechanism: type must be one of " + MECHANISMS.join(" / ") +
+      " (exponential / sparse-vector are deferred — their float-safe constructions " +
+      "re-open on demand)");
+  }
+  if (typeof opts.sensitivity !== "number" || !isFinite(opts.sensitivity) || opts.sensitivity <= 0) {
+    throw new AiDpError("aiDp/bad-sensitivity",
+      "ai.dp.mechanism: sensitivity must be a positive finite number");
+  }
+  if (typeof opts.epsilon !== "number" || !isFinite(opts.epsilon) || opts.epsilon <= 0) {
+    throw new AiDpError("aiDp/bad-epsilon",
+      "ai.dp.mechanism: epsilon must be a positive finite number");
+  }
+
+  if (opts.type === "laplace") {
+    if (typeof opts.bound !== "number" || !isFinite(opts.bound) || opts.bound <= 0) {
+      throw new AiDpError("aiDp/bad-bound",
+        "ai.dp.mechanism: laplace requires bound > 0 (the snapping clamp; the " +
+        "privacy guarantee depends on it)");
+    }
+    var scale = opts.sensitivity / opts.epsilon;
+    return Object.freeze({
+      type: "laplace", sensitivity: opts.sensitivity, epsilon: opts.epsilon,
+      delta: 0, scale: scale, bound: opts.bound,
+    });
+  }
+
+  // gaussian
+  if (typeof opts.delta !== "number" || !isFinite(opts.delta) || opts.delta <= 0 || opts.delta >= 1) {
+    throw new AiDpError("aiDp/bad-delta",
+      "ai.dp.mechanism: gaussian requires 0 < delta < 1");
+  }
+  if (opts.epsilon > 1) {
+    throw new AiDpError("aiDp/epsilon-too-large",
+      "ai.dp.mechanism: the classic Gaussian calibration is proven for epsilon <= 1; " +
+      "split into multiple releases under an rdp budget, or the analytic Gaussian " +
+      "mechanism (Balle-Wang 2018) re-opens this path on demand");
+  }
+  // Classic Gaussian calibration (Dwork & Roth Thm 3.22), valid for ε ≤ 1.
+  var sigma = Math.sqrt(2 * Math.log(1.25 / opts.delta)) * opts.sensitivity / opts.epsilon;
+  return Object.freeze({
+    type: "gaussian", sensitivity: opts.sensitivity, epsilon: opts.epsilon,
+    delta: opts.delta, sigma: sigma, sigma2: sigma * sigma,
+  });
+}
+
+// Apply a mechanism's noise to a numeric value (no accounting — the
+// budget wraps this).
+function _applyMechanism(m, value) {
+  if (typeof value !== "number" || !isFinite(value)) {
+    throw new AiDpError("aiDp/bad-value", "ai.dp: value must be a finite number");
+  }
+  if (m.type === "laplace") {
+    return _snappingLaplace(value, m.scale, m.bound);
+  }
+  // gaussian — discrete, integer noise added to the (rounded) value.
+  var sigma2Frac = _frFromFloat(m.sigma2, SIGMA2_RATIONAL_DEN);
+  var noise = _sampleDGauss(sigma2Frac);
+  return Math.round(value) + Number(noise);
+}
+
+function _mechRdp(m, orderIndex) {
+  var alpha = RDP_ORDERS[orderIndex];
+  if (m.type === "gaussian") return _rdpGaussian(alpha, m.sigma, m.sensitivity);
+  return _rdpLaplace(alpha, m.epsilon);
+}
+
+// ---- per-scope budget ----
+
+/**
+ * @primitive b.ai.dp.budget
+ * @signature b.ai.dp.budget(opts)
+ * @since     0.12.29
+ * @status    stable
+ * @compliance gdpr, soc2
+ * @related   b.ai.dp.mechanism, b.ai.quota.create
+ *
+ * Track a differential-privacy budget for one scope (per-user /
+ * per-tenant / per-query-class) and refuse a release that would
+ * exceed it. Returns <code>{ consume, remaining, spent, reset }</code>.
+ * <code>consume(mechanism, value)</code> adds the mechanism's noise,
+ * charges the accountant, and throws <code>aiDp/budget-exhausted</code>
+ * if the release would push the scope past its (ε, δ). With
+ * <code>accounting: "rdp"</code> the charge is accounted via Rényi DP
+ * for a tight composition bound (requires <code>delta &gt; 0</code>);
+ * <code>"basic"</code> (default) sums per-release ε and δ.
+ *
+ * @opts
+ *   {
+ *     scope:       string,   // required, the budget scope id
+ *     epsilon:     number,   // required, total ε budget (> 0)
+ *     delta?:      number,   // total δ budget (>= 0; required > 0 for rdp / gaussian)
+ *     accounting?: string,   // "basic" (default) | "rdp"
+ *     audit?:      boolean,  // default: true
+ *   }
+ *
+ * @example
+ *   var b1 = b.ai.dp.budget({ scope: "tenant-acme:daily", epsilon: 3, delta: 1e-6, accounting: "rdp" });
+ *   var m  = b.ai.dp.mechanism({ type: "gaussian", sensitivity: 1, epsilon: 0.5, delta: 1e-6 });
+ *   var out = b1.consume(m, trueCount);
+ *   // → { value: <noised>, cost: { epsilon: 0.5, delta: 1e-6 }, remaining: { epsilon, delta } }
+ */
+function budget(opts) {
+  validateOpts.requireObject(opts, "ai.dp.budget", AiDpError);
+  validateOpts(opts, ["scope", "epsilon", "delta", "accounting", "audit"], "ai.dp.budget");
+
+  validateOpts.requireNonEmptyString(opts.scope,
+    "ai.dp.budget: scope", AiDpError, "aiDp/bad-scope");
+  if (typeof opts.epsilon !== "number" || !isFinite(opts.epsilon) || opts.epsilon <= 0) {
+    throw new AiDpError("aiDp/bad-epsilon", "ai.dp.budget: epsilon must be a positive finite number");
+  }
+  var totalEpsilon = opts.epsilon;
+  var totalDelta = (opts.delta == null) ? 0 : opts.delta;
+  if (typeof totalDelta !== "number" || !isFinite(totalDelta) || totalDelta < 0 || totalDelta >= 1) {
+    throw new AiDpError("aiDp/bad-delta", "ai.dp.budget: delta must be in [0, 1)");
+  }
+  var accounting = (opts.accounting == null) ? "basic" : opts.accounting;
+  if (ACCOUNTINGS.indexOf(accounting) === -1) {
+    throw new AiDpError("aiDp/bad-accounting",
+      "ai.dp.budget: accounting must be one of " + ACCOUNTINGS.join(" / "));
+  }
+  if (accounting === "rdp" && totalDelta <= 0) {
+    throw new AiDpError("aiDp/bad-accounting",
+      "ai.dp.budget: rdp accounting requires delta > 0 (the RDP→(ε,δ) conversion is " +
+      "undefined at delta = 0; use basic accounting for pure-ε budgets)");
+  }
+  var auditOn = opts.audit !== false;
+
+  var scope = opts.scope;
+  var spentEpsilon = 0;          // basic accounting
+  var spentDelta = 0;
+  var rdp = RDP_ORDERS.map(function () { return 0; });   // rdp accounting
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try { audit().safeEmit({ action: action, outcome: outcome, metadata: metadata || {} }); }
+    catch (_e) { /* drop-silent */ }
+  }
+
+  function _currentEpsilon(rdpCurve) {
+    if (accounting === "basic") return spentEpsilon;
+    return _rdpToEpsilon(rdpCurve, totalDelta);
+  }
+
+  function remaining() {
+    if (accounting === "basic") {
+      return {
+        epsilon: Math.max(0, totalEpsilon - spentEpsilon),
+        delta:   Math.max(0, totalDelta - spentDelta),
+      };
+    }
+    return { epsilon: Math.max(0, totalEpsilon - _rdpToEpsilon(rdp, totalDelta)), delta: totalDelta };
+  }
+
+  function spent() {
+    if (accounting === "basic") return { epsilon: spentEpsilon, delta: spentDelta };
+    return { epsilon: _rdpToEpsilon(rdp, totalDelta), delta: totalDelta };
+  }
+
+  function consume(m, value) {
+    if (!m || typeof m !== "object" || MECHANISMS.indexOf(m.type) === -1) {
+      throw new AiDpError("aiDp/bad-mechanism",
+        "ai.dp.budget.consume: first argument must be a b.ai.dp.mechanism");
+    }
+    if (m.type === "gaussian" && totalDelta <= 0) {
+      throw new AiDpError("aiDp/bad-delta",
+        "ai.dp.budget.consume: a gaussian mechanism needs a scope delta > 0");
+    }
+
+    // Prospective accounting: would this release fit under the budget?
+    var cost;
+    if (accounting === "basic") {
+      if (spentEpsilon + m.epsilon > totalEpsilon + 1e-12 ||
+          spentDelta + m.delta > totalDelta + 1e-12) {
+        _emitAudit("dp/budget-exhausted", "denied", {
+          scope: scope, accounting: accounting, mechanism: m.type,
+          requestEpsilon: m.epsilon, requestDelta: m.delta,
+          spentEpsilon: spentEpsilon, totalEpsilon: totalEpsilon,
+        });
+        throw new AiDpError("aiDp/budget-exhausted",
+          "ai.dp.budget.consume: scope '" + scope + "' would spend ε=" +
+          (spentEpsilon + m.epsilon) + "/" + totalEpsilon + ", δ=" +
+          (spentDelta + m.delta) + "/" + totalDelta + "; refused");
+      }
+      cost = { epsilon: m.epsilon, delta: m.delta };
+    } else {
+      var trial = rdp.map(function (r, i) { return r + _mechRdp(m, i); });
+      var trialEps = _rdpToEpsilon(trial, totalDelta);
+      if (trialEps > totalEpsilon + 1e-12) {
+        _emitAudit("dp/budget-exhausted", "denied", {
+          scope: scope, accounting: accounting, mechanism: m.type,
+          projectedEpsilon: trialEps, totalEpsilon: totalEpsilon,
+        });
+        throw new AiDpError("aiDp/budget-exhausted",
+          "ai.dp.budget.consume: scope '" + scope + "' would reach ε=" +
+          trialEps.toFixed(4) + " of " + totalEpsilon + " at δ=" + totalDelta + "; refused");
+      }
+      var before = _rdpToEpsilon(rdp, totalDelta);
+      cost = { epsilon: trialEps - before, delta: 0 };
+    }
+
+    // Charge, then sample. (Sampling never fails; charging first keeps
+    // the budget monotone even if a caller ignores the throw path.)
+    var noised = _applyMechanism(m, value);
+    if (accounting === "basic") {
+      spentEpsilon += m.epsilon;
+      spentDelta += m.delta;
+    } else {
+      rdp = rdp.map(function (r, i) { return r + _mechRdp(m, i); });
+    }
+
+    _emitAudit("dp/budget-consumed", "allowed", {
+      scope: scope, accounting: accounting, mechanism: m.type,
+      epsilon: m.epsilon, delta: m.delta,
+    });
+    return { value: noised, cost: cost, remaining: remaining() };
+  }
+
+  function reset() {
+    spentEpsilon = 0;
+    spentDelta = 0;
+    rdp = RDP_ORDERS.map(function () { return 0; });
+  }
+
+  return {
+    consume:    consume,
+    remaining:  remaining,
+    spent:      spent,
+    reset:      reset,
+    scope:      scope,
+    accounting: accounting,
+  };
+}
+
+module.exports = {
+  mechanism:   mechanism,
+  budget:      budget,
+  MECHANISMS:  MECHANISMS,
+  ACCOUNTINGS: ACCOUNTINGS,
+  AiDpError:   AiDpError,
+};

package/lib/crypto.js

@@ -387,9 +387,16 @@ function random(byteLength) {
   // when callers requested more. SHAKE256 is also already the
   // framework's KDF / browser-side derivation primitive, so the same
   // hash family does double duty.
-  return nodeCrypto.createHash("shake256", { outputLength: n })
-    .update(nodeCrypto.randomBytes(n))
+  //
+  // Node's SHAKE256 XOF is non-uniform at outputLength 1 (the byte
+  // values 0x00 and 0xff never occur and the low bit skews to ~0.54);
+  // outputLength >= 2 is uniform. Draw at least 2 bytes and slice so a
+  // 1-byte request still returns a uniform byte.
+  var drawN = n < 2 ? 2 : n;
+  var out = nodeCrypto.createHash("shake256", { outputLength: drawN })
+    .update(nodeCrypto.randomBytes(drawN))
     .digest();
+  return drawN === n ? out : out.subarray(0, n);
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.27",
+  "version": "0.12.29",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:a1889d46-3ca4-496a-b702-7def3d36c9f8",
+  "serialNumber": "urn:uuid:ae86440d-174b-4c3d-8fee-c92df10a498a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-24T15:36:49.117Z",
+    "timestamp": "2026-05-24T17:32:55.663Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.27",
+      "bom-ref": "@blamejs/core@0.12.29",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.27",
+      "version": "0.12.29",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.27",
+      "purl": "pkg:npm/%40blamejs/core@0.12.29",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.27",
+      "ref": "@blamejs/core@0.12.29",
       "dependsOn": []
     }
   ]