@blamejs/core 0.8.42 → 0.8.49

package/lib/gate-contract.js

@@ -1,61 +1,48 @@
 "use strict";
 /**
- * gate-contract — uniform composition contract for the safe-* primitive
- * family.
- *
- * Every safe-* primitive (b.safeCsv / b.safeHtml / b.safeLink / b.safeMime
- * / b.safeFilename / etc.) ships a `.gate(opts)` factory that returns the
- * shape defined here. Host primitives (b.staticServe / b.fileUpload /
- * b.mail / b.objectStore / b.notify / b.audit / etc.) call gate.check()
- * at their byte-boundary moment with a uniform context.
- *
- * The gate decision is captured as:
- *
- *   { ok, action, sanitized?, issues, contentTypeOverride?, headers?,
- *     forensicHash, forensicSnapshot?, runtimeMs, cacheKey? }
- *
- * Operator extension surface — every primitive inherits these patterns
- * from this module (configuration uniform across the family):
- *
- *   - Profile composition (extends + overrides + removes; cycle detection)
- *   - Hook system (beforeCheck / afterCheck / onIssue / onSanitize / onRefuse / onAudit)
- *   - Mode posture (enforce / warn-only / shadow / audit-only / log-only / canary)
- *   - Versioned policies (version + ruleHash) with policyDiff helper
- *   - Forensic snapshot store (operator-supplied evidence vault)
- *   - Decision cache (per-forensicHash memoization)
- *   - Runtime cap with timeout
- *   - Sandbox isolation (in-process / worker-thread / child-process)
- *   - Threat-intelligence feed integration
- *   - Compliance posture pre-sets
- *
- * Host-side helpers exported here:
- *
- *   runGate(gate, ctx, opts?)            — execute single gate with timeout
- *   composeGates([g1, g2, ...], opts?)   — chain; first refusal wins
- *   multiplexGates({ ext: gate, ... })   — file-extension dispatch
- *   contentTypeMux({ mime: gate, ... })  — Content-Type dispatch
- *   byActorTier({ tier: gate, ... })     — actor-tier dispatch
- *   byRoute({ pattern: gate, ... })      — route-pattern dispatch
- *   byDirection({ inbound, outbound })   — direction-aware dispatch
- *   shadowMode(primary, candidate)       — A/B compare; emit divergence
- *   canaryGate(gate, { rate })           — N% rollout
- *   cachingGate(gate, { backend, ttlMs }) — memoize per-forensicHash
- *   workerThreadGate(gate, { worker })   — offload to worker
- *   validateGateShape(g, label, errClass) — schema check at wire-up
- *   buildProfile({ baseProfile, extends, overrides, removes })
- *   composeHooks(hooks)                  — chain operator hooks
- *
- * Module-level constants:
- *
- *   ACTIONS          — allowed action enum
- *   MODES            — allowed mode enum
- *   ISSUE_SEVERITIES — allowed severity enum
- *
- * The gate contract is the foundation of the guard-* family. Every
- * content-safety primitive that ships in the family composes through it
- * (b.guardCsv, future b.guardHtml / b.guardSvg / etc.). b.guardAll then
- * aggregates the registered guards into a single security-on-by-default
- * gate with operator opt-out via exceptFor.
+ * @module b.gateContract
+ * @nav    Guards
+ * @title  Gate Contract
+ *
+ * @intro
+ *   Shared substrate every `b.guard*` primitive composes against —
+ *   `resolveProfileAndPosture`, `makeProfileBuilder`,
+ *   `makeRulePackLoader`, `lookupCompliancePosture`, `buildGuardGate`,
+ *   `aggregateIssues`, `extractBytesAsText`. The contract every guard
+ *   implements; ensures the action vocabulary
+ *   (`serve` / `sanitize` / `refuse` / `audit-only`) and the
+ *   profile-and-posture resolution shape stay identical across the
+ *   family.
+ *
+ *   Every guard ships a `.gate(opts)` factory returning the shape
+ *   defined here. Host primitives (`b.staticServe` / `b.fileUpload` /
+ *   `b.mail` / `b.objectStore`) call `gate.check(ctx)` at their
+ *   byte-boundary moment with a uniform context. The decision shape
+ *   is `{ ok, action, sanitized?, issues, contentTypeOverride?,
+ *   headers?, forensicHash, forensicSnapshot?, runtimeMs, cacheKey? }`.
+ *
+ *   Operator extension surface inherited by every member:
+ *
+ *     - Profile composition (extends + overrides + removes; cycle detection)
+ *     - Hook system (beforeCheck / afterCheck / onIssue / onSanitize / onRefuse / onAudit)
+ *     - Mode posture (enforce / warn-only / shadow / audit-only / log-only / canary)
+ *     - Versioned policies (version + ruleHash) with policyDiff helper
+ *     - Forensic snapshot store (operator-supplied evidence vault)
+ *     - Decision cache (per-forensicHash memoization)
+ *     - Runtime cap with timeout
+ *     - Compliance-posture pre-sets (hipaa / pci-dss / gdpr / soc2)
+ *
+ *   Module-level constants `ACTIONS` / `MODES` / `ISSUE_SEVERITIES`
+ *   carry the frozen enums every guard validates against.
+ *
+ *   Foundation for the guard-* family. Every content-safety primitive
+ *   shipped under `b.guard*` composes through `buildGuardGate`,
+ *   `makeProfileBuilder`, `makeRulePackLoader`, and
+ *   `lookupCompliancePosture`; `b.guardAll` aggregates the registered
+ *   guards into a single security-on-by-default gate.
+ *
+ * @card
+ *   Shared substrate every `b.guard*` primitive composes against — `resolveProfileAndPosture`, `makeProfileBuilder`, `makeRulePackLoader`, `lookupCompliancePosture`, `buildGuardGate`, `aggregateIssues`, `extractBytesAsText`.
  */
 
 var C = require("./constants");
@@ -77,10 +64,53 @@ var FINGERPRINT_HEX_LENGTH = C.BYTES.bytes(16);
 // Default cachingGate TTL when operator doesn't supply one.
 var DEFAULT_CACHE_TTL_MS = C.TIME.minutes(5);
 
+/**
+ * @primitive  b.gateContract.GateContractError
+ * @signature  b.gateContract.GateContractError
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.defineGate, b.gateContract.validateGateShape
+ *
+ * FrameworkError subclass thrown by gate-contract entry points on
+ * shape violations: `gate-contract/bad-shape` from
+ * `validateGateShape`, `gate-contract/bad-opt` from `defineGate` /
+ * `cachingGate` / `workerThreadGate`, `gate-contract/profile-cycle`
+ * and `gate-contract/unknown-profile` from `buildProfile`.
+ * `alwaysPermanent` — never retried by `b.retry`.
+ *
+ * @example
+ *   try {
+ *     b.gateContract.validateGateShape({}, "broken");
+ *   } catch (e) {
+ *     e instanceof b.gateContract.GateContractError;     // → true
+ *     e.code;                                            // → "gate-contract/bad-shape"
+ *   }
+ */
 var _err = GateContractError.factory;
 
 // ---- Enumerations (module-level constants) ----
 
+/**
+ * @primitive  b.gateContract.ACTIONS
+ * @signature  b.gateContract.ACTIONS
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.MODES, b.gateContract.defineGate
+ *
+ * Frozen list of every action a gate decision is allowed to set.
+ * `serve` emits the bytes unchanged; `refuse` rejects with an
+ * operator-meaningful error; `sanitize` substitutes `decision.sanitized`
+ * for the original bytes; `strip` removes the offending content;
+ * `audit-only` serves but emits an audit entry; `warn` serves and
+ * emits a warning counter; `challenge-mfa` triggers step-up auth
+ * before serving; `deny-and-revoke` rejects and invalidates the
+ * actor's session.
+ *
+ * @example
+ *   b.gateContract.ACTIONS.indexOf("serve");             // → 0
+ *   b.gateContract.ACTIONS.indexOf("warp-speed");        // → -1
+ *   Object.isFrozen(b.gateContract.ACTIONS);             // → true
+ */
 var ACTIONS = Object.freeze([
   "serve",          // host emits the bytes as-is
   "refuse",         // host rejects with operator-meaningful error
@@ -92,6 +122,24 @@ var ACTIONS = Object.freeze([
   "deny-and-revoke", // host rejects + invalidates the actor's session
 ]);
 
+/**
+ * @primitive  b.gateContract.MODES
+ * @signature  b.gateContract.MODES
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.ACTIONS, b.gateContract.defineGate
+ *
+ * Frozen list of mode-posture values a gate can run in. `enforce`
+ * honors the decision; `warn-only` translates every `refuse` to
+ * `warn` for staged rollout; `shadow` runs alongside a primary and
+ * never refuses (observability-only); `audit-only` and `log-only`
+ * emit an audit entry but never block; `canary` enforces on a
+ * sampled subset and warns on the rest.
+ *
+ * @example
+ *   b.gateContract.MODES.indexOf("enforce");             // → 0
+ *   b.gateContract.MODES.indexOf("yolo");                // → -1
+ */
 var MODES = Object.freeze([
   "enforce",     // gate decision honored
   "warn-only",   // gate emits but never refuses (staged rollout)
@@ -101,6 +149,22 @@ var MODES = Object.freeze([
   "canary",      // enforce on N% of requests; warn on the rest
 ]);
 
+/**
+ * @primitive  b.gateContract.ISSUE_SEVERITIES
+ * @signature  b.gateContract.ISSUE_SEVERITIES
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.aggregateIssues, b.gateContract.summarizeIssues
+ *
+ * Frozen list of severity levels a guard issue may carry. `info` and
+ * `warn` are observability-only — `aggregateIssues` keeps `ok: true`
+ * with them present. `high` and `critical` flip the result to
+ * `ok: false`, refusing the input.
+ *
+ * @example
+ *   b.gateContract.ISSUE_SEVERITIES;                     // → ["info","warn","high","critical"]
+ *   b.gateContract.ISSUE_SEVERITIES.indexOf("critical"); // → 3
+ */
 var ISSUE_SEVERITIES = Object.freeze([
   "info",
   "warn",
@@ -108,13 +172,33 @@ var ISSUE_SEVERITIES = Object.freeze([
   "critical",
 ]);
 
-// ---- validateGateShape ----
-//
-// Throws if `gate` doesn't satisfy the contract. Operator-supplied gates
-// (or framework-supplied gates with operator-toggled hooks) all flow
-// through this check at host-primitive wire-up time. Shape errors at
-// boot are far cheaper than at request time.
-
+/**
+ * @primitive  b.gateContract.validateGateShape
+ * @signature  b.gateContract.validateGateShape(gate, label, errorClass)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.defineGate, b.gateContract.runGate
+ *
+ * Throws when `gate` does not satisfy the contract — `gate.check`
+ * must be a function, `gate.mode` (when present) must be one of the
+ * `MODES` enum values, and `gate.metrics` / `gate.close` (when
+ * present) must be functions. Operator-supplied gates (and
+ * framework-supplied gates with operator-toggled hooks) all flow
+ * through this check at host-primitive wire-up time. Shape errors at
+ * boot are cheaper than at request time. Returns `gate` unchanged on
+ * success.
+ *
+ * @example
+ *   var gate = b.guardCsv.gate({ profile: "strict" });
+ *   b.gateContract.validateGateShape(gate, "uploads.csv");
+ *   // → returns the gate unchanged when shape is valid
+ *
+ *   try {
+ *     b.gateContract.validateGateShape({}, "broken");
+ *   } catch (e) {
+ *     e.code;                                            // → "gate-contract/bad-shape"
+ *   }
+ */
 function validateGateShape(gate, label, errorClass) {
   errorClass = errorClass || GateContractError;
   label = label || "gate";
@@ -142,23 +226,60 @@ function validateGateShape(gate, label, errorClass) {
   return gate;
 }
 
-// ---- defineGate factory ----
-//
-// Primitives use this to build their .gate(opts) implementation. Wraps
-// the operator's check() with the cross-cutting concerns (hooks /
-// observability / forensic snapshot / runtime cap / cache). Returns a
-// gate that satisfies validateGateShape.
-//
-//   defineGate({
-//     name:        "safeCsv:strict",
-//     version:     "1.0.0",
-//     mode:        "enforce",
-//     check:       async (ctx) => decision,
-//     beforeCheck, afterCheck, onIssue, onSanitize, onRefuse, onAudit,
-//     audit, observability, forensicEvidenceStore, forensicSnippetBytes,
-//     cache, cacheTtlMs, maxRuntimeMs, ruleHash,
-//   }) → gate
-
+/**
+ * @primitive  b.gateContract.defineGate
+ * @signature  b.gateContract.defineGate(opts)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.buildGuardGate, b.gateContract.validateGateShape
+ *
+ * Build a gate that satisfies the contract. Wraps the
+ * operator-supplied `check(ctx)` with the cross-cutting concerns
+ * (hooks, observability, forensic snapshot, runtime cap, decision
+ * cache, mode-posture translation) so guards only write the per-guard
+ * inspection logic. Returns a gate exposing
+ * `{ check, mode, audit, observability, metrics, reset, close, name,
+ * version, ruleHash, dryRun, policyDiff }`. Most guards forward through
+ * `b.gateContract.buildGuardGate` instead — `defineGate` is the lower-level
+ * factory used by host-side composers (`composeGates` / `byRoute` / etc.).
+ *
+ * @opts
+ *   name:                  string,           // identifier surfaced in audit / counters
+ *   version:               string,           // semver default "1.0.0"
+ *   mode:                  string,           // one of MODES; default "enforce"
+ *   check:                 function,         // async (ctx) → decision
+ *   beforeCheck:           function|null,    // (ctx) → { skip?, transform? }
+ *   afterCheck:            function|null,    // (ctx, decision) → decision
+ *   onIssue:               function|null,    // (issue, ctx) → issue|{suppress|promote}
+ *   onSanitize:            function|null,    // (bytes, sanitized, ctx) → sanitized
+ *   onRefuse:              function|null,    // (ctx, decision) → void
+ *   onAudit:               function|null,    // (entry) → entry|false (false suppresses)
+ *   audit:                 object|null,      // b.audit handle
+ *   observability:         object|null,      // b.observability handle
+ *   forensicEvidenceStore: object|null,      // { write({ ... }) }
+ *   forensicSnippetBytes:  number,           // 0 = disabled
+ *   cache:                 object|null,      // b.cache shape
+ *   cacheTtlMs:            number,
+ *   maxRuntimeMs:          number,           // 0 = uncapped
+ *   ruleHash:              string,           // override fingerprint
+ *
+ * @example
+ *   var gate = b.gateContract.defineGate({
+ *     name: "tenant:csv:strict",
+ *     mode: "enforce",
+ *     maxRuntimeMs: 250,
+ *     check: async function (ctx) {
+ *       var text = b.gateContract.extractBytesAsText(ctx);
+ *       if (text.indexOf("=cmd|") === 0) {
+ *         return { ok: false, action: "refuse",
+ *                  issues: [{ kind: "csv.formula-injection", severity: "high" }] };
+ *       }
+ *       return { ok: true, action: "serve" };
+ *     },
+ *   });
+ *   var d = await gate.check({ bytes: Buffer.from("name,age\nada,36") });
+ *   d.action;                                            // → "serve"
+ */
 function defineGate(opts) {
   validateOpts.requireObject(opts, "gateContract.defineGate", GateContractError);
   validateOpts.requireNonEmptyString(opts.name, "gateContract.defineGate: name", GateContractError, "gate-contract/bad-opt");
@@ -439,13 +560,66 @@ function _hashFingerprint(obj) {
 
 // ---- Host-side helpers ----
 
+/**
+ * @primitive  b.gateContract.runGate
+ * @signature  b.gateContract.runGate(gate, ctx, opts?)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.defineGate, b.gateContract.composeGates
+ *
+ * Execute a gate's `check(ctx)` and return its decision. When `gate`
+ * is null or has no `check` function, returns the canonical
+ * `{ ok: true, action: "serve" }` shape — host primitives invoke
+ * `runGate` with an operator-configurable gate that may legitimately
+ * be unset. The `opts` argument is reserved for future host-side
+ * cross-cutting concerns and is currently unused.
+ *
+ * @opts
+ *   // reserved for future host-side cross-cutting concerns; pass `{}` today
+ *
+ * @example
+ *   var gate = b.guardCsv.gate({ profile: "strict" });
+ *   var decision = await b.gateContract.runGate(gate, {
+ *     bytes:    Buffer.from("name,age\nada,36"),
+ *     route:    "/api/imports",
+ *     filename: "people.csv",
+ *   });
+ *   decision.action;                                     // → "serve"
+ *
+ *   // Unset gate is a no-op serve.
+ *   (await b.gateContract.runGate(null, {})).action;     // → "serve"
+ */
 async function runGate(gate, ctx, opts) {
   opts = opts || {};
   if (!gate || typeof gate.check !== "function") return _build({ ok: true, action: "serve" });
   return await gate.check(ctx);
 }
 
-// composeGates — chain a list of gates left-to-right; first refusal wins.
+/**
+ * @primitive  b.gateContract.composeGates
+ * @signature  b.gateContract.composeGates(gates, opts?)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.multiplexGates, b.gateContract.contentTypeMux
+ *
+ * Chain a list of gates left-to-right. First refusal wins. When a
+ * gate returns `action: "sanitize"` and `firstRefusalWins` is true
+ * (default), the sanitized bytes feed into the next gate's context —
+ * letting an HTML sanitizer hand its scrubbed output to a downstream
+ * link-shape guard. Returns a wrapping gate that satisfies the
+ * contract (so the composition is itself composable).
+ *
+ * @opts
+ *   name:             string,    // wrapper gate name (default "composed")
+ *   firstRefusalWins: boolean,   // default true
+ *
+ * @example
+ *   var bidi  = b.guardCsv.gate({ profile: "strict" });
+ *   var pii   = b.guardCsv.gate({ compliancePosture: "hipaa" });
+ *   var chain = b.gateContract.composeGates([bidi, pii], { name: "csv:chain" });
+ *   var d = await chain.check({ bytes: Buffer.from("name,ssn\nada,123-45-6789") });
+ *   d.action;                                            // → "refuse"
+ */
 function composeGates(gates, opts) {
   opts = opts || {};
   var firstRefusalWins = opts.firstRefusalWins !== false;
@@ -464,7 +638,32 @@ function composeGates(gates, opts) {
   });
 }
 
-// multiplexGates — extension-keyed dispatch.
+/**
+ * @primitive  b.gateContract.multiplexGates
+ * @signature  b.gateContract.multiplexGates(gateMap, opts?)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.contentTypeMux, b.gateContract.composeGates
+ *
+ * File-extension-keyed gate dispatch. Looks at `ctx.filename`,
+ * extracts the lowercased final extension (`.csv` / `.html` / etc.),
+ * and dispatches to the matching gate. The `"default"` key serves as
+ * the fallback; missing entries (no key match, no fallback) return
+ * the canonical serve decision so host primitives can wire a single
+ * mux gate without per-extension special-casing.
+ *
+ * @opts
+ *   name: string,   // wrapper gate name (default "multiplex")
+ *
+ * @example
+ *   var mux = b.gateContract.multiplexGates({
+ *     ".csv":  b.guardCsv.gate({ profile: "strict" }),
+ *     ".html": b.guardHtml.gate({ profile: "strict" }),
+ *     "default": b.guardCsv.gate({ profile: "permissive" }),
+ *   });
+ *   var d = await mux.check({ bytes: Buffer.from("a,b\n1,2"), filename: "x.csv" });
+ *   d.action;                                            // → "serve"
+ */
 function multiplexGates(gateMap, opts) {
   opts = opts || {};
   var lookup = Object.create(null);
@@ -484,8 +683,34 @@ function multiplexGates(gateMap, opts) {
   });
 }
 
-// contentTypeMux — Content-Type-keyed dispatch. Match on the bare type
-// (strip parameters like `; charset=utf-8`).
+/**
+ * @primitive  b.gateContract.contentTypeMux
+ * @signature  b.gateContract.contentTypeMux(gateMap, opts?)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.multiplexGates, b.gateContract.composeGates
+ *
+ * Content-Type-keyed gate dispatch. Reads `ctx.contentType`, strips
+ * parameters (`; charset=utf-8`), lowercases, and routes to the
+ * matching gate. The `"default"` key is the fallback; unknown types
+ * (no key match, no fallback) serve uninspected. Useful when one
+ * route accepts multiple media types and each needs its own guard.
+ *
+ * @opts
+ *   name: string,   // wrapper gate name (default "contentTypeMux")
+ *
+ * @example
+ *   var mux = b.gateContract.contentTypeMux({
+ *     "text/csv":   b.guardCsv.gate({ profile: "strict" }),
+ *     "text/html":  b.guardHtml.gate({ profile: "strict" }),
+ *     "default":    b.guardCsv.gate({ profile: "permissive" }),
+ *   });
+ *   var d = await mux.check({
+ *     bytes:       Buffer.from("name,age\nada,36"),
+ *     contentType: "text/csv; charset=utf-8",
+ *   });
+ *   d.action;                                            // → "serve"
+ */
 function contentTypeMux(gateMap, opts) {
   opts = opts || {};
   var lookup = Object.create(null);
@@ -503,7 +728,35 @@ function contentTypeMux(gateMap, opts) {
   });
 }
 
-// byActorTier — actor-tier-keyed dispatch (free / paid / admin).
+/**
+ * @primitive  b.gateContract.byActorTier
+ * @signature  b.gateContract.byActorTier(gateMap, opts?)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.byRoute, b.gateContract.byDirection
+ *
+ * Actor-tier-keyed gate dispatch. Reads `ctx.actor.tier` (e.g.
+ * `"free"` / `"paid"` / `"admin"`) and routes to the matching gate.
+ * Falls back to `gateMap["default"]` when the tier is missing or
+ * unmapped; missing fallback serves uninspected. Lets free-tier
+ * tenants run a stricter posture than paid customers without
+ * branching at every call site.
+ *
+ * @opts
+ *   name: string,   // wrapper gate name (default "byActorTier")
+ *
+ * @example
+ *   var byTier = b.gateContract.byActorTier({
+ *     free:    b.guardCsv.gate({ profile: "strict" }),
+ *     paid:    b.guardCsv.gate({ profile: "balanced" }),
+ *     default: b.guardCsv.gate({ profile: "strict" }),
+ *   });
+ *   var d = await byTier.check({
+ *     bytes: Buffer.from("name,age\nada,36"),
+ *     actor: { tier: "paid" },
+ *   });
+ *   d.action;                                            // → "serve"
+ */
 function byActorTier(gateMap, opts) {
   opts = opts || {};
   return defineGate({
@@ -517,8 +770,35 @@ function byActorTier(gateMap, opts) {
   });
 }
 
-// byRoute — route-pattern-keyed dispatch. Patterns are simple
-// glob-prefix matches: "/admin/*" matches "/admin/foo".
+/**
+ * @primitive  b.gateContract.byRoute
+ * @signature  b.gateContract.byRoute(gateMap, opts?)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.byActorTier, b.gateContract.byDirection
+ *
+ * Route-pattern-keyed gate dispatch. Patterns are simple glob-prefix
+ * matches — `/admin/*` matches every path beginning with `/admin/`.
+ * Tries each entry in declaration order, falling back to `"*"` /
+ * `"default"`; missing fallback serves uninspected. Lets `/admin/*`
+ * routes apply a stricter guard than the public surface without
+ * threading per-route opts through every call site.
+ *
+ * @opts
+ *   name: string,   // wrapper gate name (default "byRoute")
+ *
+ * @example
+ *   var byPath = b.gateContract.byRoute({
+ *     "/admin/*": b.guardCsv.gate({ profile: "strict" }),
+ *     "/api/*":   b.guardCsv.gate({ profile: "balanced" }),
+ *     "*":        b.guardCsv.gate({ profile: "permissive" }),
+ *   });
+ *   var d = await byPath.check({
+ *     bytes: Buffer.from("name,age\nada,36"),
+ *     route: "/admin/imports",
+ *   });
+ *   d.action;                                            // → "serve"
+ */
 function byRoute(gateMap, opts) {
   opts = opts || {};
   var entries = Object.keys(gateMap).map(function (pattern) {
@@ -540,7 +820,33 @@ function byRoute(gateMap, opts) {
   });
 }
 
-// byDirection — inbound vs outbound dispatch.
+/**
+ * @primitive  b.gateContract.byDirection
+ * @signature  b.gateContract.byDirection(gateMap, opts?)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.byRoute, b.gateContract.byActorTier
+ *
+ * Direction-aware gate dispatch. Reads `ctx.direction` (`"inbound"`
+ * or `"outbound"`; default `"outbound"`) and routes to the matching
+ * gate. Lets a single guard wiring run a stricter posture on bytes
+ * arriving from an external source than on bytes the framework is
+ * about to emit. Missing direction maps serve uninspected.
+ *
+ * @opts
+ *   name: string,   // wrapper gate name (default "byDirection")
+ *
+ * @example
+ *   var byDir = b.gateContract.byDirection({
+ *     inbound:  b.guardCsv.gate({ profile: "strict" }),
+ *     outbound: b.guardCsv.gate({ profile: "balanced" }),
+ *   });
+ *   var d = await byDir.check({
+ *     bytes:     Buffer.from("name,age\nada,36"),
+ *     direction: "inbound",
+ *   });
+ *   d.action;                                            // → "serve"
+ */
 function byDirection(gateMap, opts) {
   opts = opts || {};
   return defineGate({
@@ -554,8 +860,30 @@ function byDirection(gateMap, opts) {
   });
 }
 
-// shadowMode — run candidate alongside primary; emit divergence.
-// Primary's decision is honored; candidate is observability-only.
+/**
+ * @primitive  b.gateContract.shadowMode
+ * @signature  b.gateContract.shadowMode(primary, candidate, opts?)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.canaryGate, b.gateContract.composeGates
+ *
+ * Run a candidate gate alongside the primary; emit a divergence
+ * counter when their actions disagree. The primary's decision is the
+ * one honored — candidate runs are observability-only and don't
+ * block the request. Useful for staged rollout of a new profile
+ * (run it shadowed for a week, watch the divergence rate, then
+ * promote it to primary).
+ *
+ * @opts
+ *   name: string,   // wrapper gate name (default "shadow")
+ *
+ * @example
+ *   var primary   = b.guardCsv.gate({ profile: "strict" });
+ *   var candidate = b.guardCsv.gate({ profile: "balanced" });
+ *   var staged    = b.gateContract.shadowMode(primary, candidate, { name: "csv:staged" });
+ *   var d = await staged.check({ bytes: Buffer.from("name,age\nada,36") });
+ *   d.action;                                            // → "serve"  (primary's decision)
+ */
 function shadowMode(primary, candidate, opts) {
   opts = opts || {};
   return defineGate({
@@ -575,7 +903,28 @@ function shadowMode(primary, candidate, opts) {
   });
 }
 
-// canaryGate — enforce on rate%; warn on the rest.
+/**
+ * @primitive  b.gateContract.canaryGate
+ * @signature  b.gateContract.canaryGate(gate, opts?)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.shadowMode, b.gateContract.cachingGate
+ *
+ * Enforce the wrapped gate's refuse decisions on `rate` of requests;
+ * downgrade the rest to `warn`. Default rate is `0.1` (10% enforced,
+ * 90% warned). Sampling uses a non-cryptographic random source — fine
+ * for rollout shaping, never for security-critical sampling.
+ *
+ * @opts
+ *   rate: number,   // 0..1, default 0.1
+ *   name: string,   // wrapper gate name (default "canary")
+ *
+ * @example
+ *   var strict = b.guardCsv.gate({ profile: "strict" });
+ *   var canary = b.gateContract.canaryGate(strict, { rate: 0.25 });
+ *   var d = await canary.check({ bytes: Buffer.from("name,age\nada,36") });
+ *   d.ok;                                                // → true
+ */
 function canaryGate(gate, opts) {
   opts = opts || {};
   var rate = typeof opts.rate === "number" ? opts.rate : 0.1;
@@ -591,9 +940,34 @@ function canaryGate(gate, opts) {
   });
 }
 
-// cachingGate — wrap with explicit TTL cache (separate from the
-// per-gate built-in cache; useful when the operator wants a SHARED
-// cache across multiple gates).
+/**
+ * @primitive  b.gateContract.cachingGate
+ * @signature  b.gateContract.cachingGate(gate, opts)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.defineGate, b.gateContract.canaryGate
+ *
+ * Wrap a gate with an explicit shared cache backend. The per-gate
+ * built-in cache (configured via `defineGate({ cache, cacheTtlMs })`)
+ * is per-gate-instance; this wrapper is the operator-side variant
+ * for sharing one cache across multiple gates. `opts.backend` must
+ * expose the `b.cache` shape (`{ get(key), set(key, value, opts) }`).
+ *
+ * @opts
+ *   backend: object,   // b.cache-shaped { get, set } (required)
+ *   ttlMs:   number,   // cache TTL
+ *   name:    string,   // wrapper gate name (default "<gate>:cached")
+ *
+ * @example
+ *   var cache  = b.cache.create({ backend: "memory", maxEntries: 10000 });
+ *   var strict = b.guardCsv.gate({ profile: "strict" });
+ *   var cached = b.gateContract.cachingGate(strict, {
+ *     backend: cache,
+ *     ttlMs:   60000,
+ *   });
+ *   var d = await cached.check({ bytes: Buffer.from("name,age\nada,36") });
+ *   d.action;                                            // → "serve"
+ */
 function cachingGate(gate, opts) {
   opts = opts || {};
   var backend = opts.backend;
@@ -617,7 +991,30 @@ function cachingGate(gate, opts) {
   });
 }
 
-// workerThreadGate — offload check() to a worker thread.
+/**
+ * @primitive  b.gateContract.workerThreadGate
+ * @signature  b.gateContract.workerThreadGate(gate, opts)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.defineGate, b.gateContract.cachingGate
+ *
+ * Offload a gate's `check(ctx)` to a worker. `opts.worker` must
+ * expose `run({ gate, ctx })` returning the decision (matches the
+ * `b.worker` shape). Useful when a guard's per-request CPU cost
+ * (large-doc HTML parsing, archive entry inspection) is high enough
+ * that running it on the request thread would impact throughput.
+ *
+ * @opts
+ *   worker: object,   // b.worker-shaped { run } (required)
+ *   name:   string,   // wrapper gate name (default "<gate>:worker")
+ *
+ * @example
+ *   var worker = b.worker.create({ pool: 4, modulePath: "./guards/csv-worker.js" });
+ *   var strict = b.guardCsv.gate({ profile: "strict" });
+ *   var offloaded = b.gateContract.workerThreadGate(strict, { worker: worker });
+ *   var d = await offloaded.check({ bytes: Buffer.from("name,age\nada,36") });
+ *   d.action;                                            // → "serve"
+ */
 function workerThreadGate(gate, opts) {
   opts = opts || {};
   if (!opts.worker) {
@@ -632,10 +1029,33 @@ function workerThreadGate(gate, opts) {
   });
 }
 
-// makeProfileBuilder — closes over a guard's PROFILES map and returns
-// a buildProfile(opts) function that delegates to the recursive
-// composition entry point. Used so each guard's buildProfile export is
-// just a binding instead of a duplicate forwarding wrapper.
+/**
+ * @primitive  b.gateContract.makeProfileBuilder
+ * @signature  b.gateContract.makeProfileBuilder(profiles)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.buildProfile, b.gateContract.resolveProfileAndPosture
+ *
+ * Closes over a guard's `PROFILES` map and returns a `buildProfile(opts)`
+ * function that delegates to the recursive composition entry point.
+ * Every guard's `buildProfile` export is therefore a single binding,
+ * not a duplicate forwarding wrapper. The returned function accepts
+ * `{ baseProfile, extends, overrides, removes }` plus inline keys, and
+ * resolves names through the closed-over profile table.
+ *
+ * @example
+ *   var PROFILES = {
+ *     strict:    { formulaInjectionPolicy: "reject",     bidiCharPolicy: "reject" },
+ *     balanced:  { formulaInjectionPolicy: "prefix-tab", bidiCharPolicy: "strip"  },
+ *   };
+ *   var buildProfile = b.gateContract.makeProfileBuilder(PROFILES);
+ *   var custom = buildProfile({
+ *     baseProfile: "strict",
+ *     overrides:   { trailingWhitespacePolicy: "preserve" },
+ *   });
+ *   custom.formulaInjectionPolicy;                       // → "reject"
+ *   custom.trailingWhitespacePolicy;                     // → "preserve"
+ */
 function makeProfileBuilder(profiles) {
   return function (opts) {
     return buildProfile(Object.assign({}, opts, {
@@ -644,10 +1064,30 @@ function makeProfileBuilder(profiles) {
   };
 }
 
-// lookupCompliancePosture — throws errorFactory(prefix + ".bad-posture")
-// when the name is not in the posture map; returns a shallow clone of
-// the posture object otherwise. Used by every guard's
-// compliancePosture(name) export.
+/**
+ * @primitive  b.gateContract.lookupCompliancePosture
+ * @signature  b.gateContract.lookupCompliancePosture(name, postures, errorFactory, codePrefix)
+ * @since      0.7.5
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.gateContract.resolveProfileAndPosture, b.gateContract.makeProfileBuilder
+ *
+ * Look up a compliance-posture overlay by name. Throws
+ * `errorFactory(codePrefix + ".bad-posture")` when the name is not in
+ * the posture map; returns a shallow clone of the posture object
+ * otherwise. Every guard's `compliancePosture(name)` export forwards
+ * here so the error code, error class, and clone semantics stay
+ * identical across the family.
+ *
+ * @example
+ *   var POSTURES = {
+ *     hipaa:   { piiPolicy: "redact", bidiCharPolicy: "reject" },
+ *     "pci-dss": { piiPolicy: "redact", bidiCharPolicy: "reject" },
+ *   };
+ *   var posture = b.gateContract.lookupCompliancePosture(
+ *     "hipaa", POSTURES, b.guardCsv.GuardCsvError.factory, "csv");
+ *   posture.piiPolicy;                                   // → "redact"
+ */
 function lookupCompliancePosture(name, postures, errorFactory, codePrefix) {
   if (!postures || !postures[name]) {
     throw errorFactory(codePrefix + ".bad-posture",
@@ -656,10 +1096,30 @@ function lookupCompliancePosture(name, postures, errorFactory, codePrefix) {
   return Object.assign({}, postures[name]);
 }
 
-// makeRulePackLoader — returns a `loadRulePack(pack)` closure with
-// per-guard storage. Validates pack shape via validateOpts; the
-// closure stores accepted packs in a closed-over map keyed by pack.id.
-// Operators can later inspect via the returned `list()` function.
+/**
+ * @primitive  b.gateContract.makeRulePackLoader
+ * @signature  b.gateContract.makeRulePackLoader(errorClass, codePrefix)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.makeProfileBuilder, b.gateContract.lookupCompliancePosture
+ *
+ * Build a per-guard rule-pack registry. Returns
+ * `{ load(pack), list(), get(id) }`. `load` validates that `pack`
+ * is an object with a non-empty string `pack.id` (throwing
+ * `errorClass(codePrefix + ".bad-opt")` when not) and stores it in
+ * a closed-over map keyed by `pack.id`. `list` returns the stored
+ * packs; `get(id)` returns one or `null`. Used so every guard's
+ * `loadRulePack` export shares storage shape and validation.
+ *
+ * @example
+ *   var packs = b.gateContract.makeRulePackLoader(b.guardCsv.GuardCsvError, "csv");
+ *   packs.load({
+ *     id: "pii-extra",
+ *     rules: [{ id: "ssn", severity: "critical",
+ *               detect: function (cell) { return /^\d{3}-\d{2}-\d{4}$/.test(cell); } }],
+ *   });
+ *   packs.get("pii-extra").rules.length;                 // → 1
+ */
 function makeRulePackLoader(errorClass, codePrefix) {
   var store = Object.create(null);
   return {
@@ -677,15 +1137,26 @@ function makeRulePackLoader(errorClass, codePrefix) {
   };
 }
 
-// extractBytesAsText — every guard's check(ctx) opens by reading
-// ctx.bytes and converting to a UTF-8 string for inspection.
-// Centralizes the string|Buffer|empty handling so each guard's check
-// body just deals with the inspection logic.
-//
-//   var text = gateContract.extractBytesAsText(ctx);
-//   if (!text) return { ok: true, action: "serve" };
-//
-// Returns "" if ctx.bytes is missing — caller treats empty as serve.
+/**
+ * @primitive  b.gateContract.extractBytesAsText
+ * @signature  b.gateContract.extractBytesAsText(ctx)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.buildGuardGate, b.gateContract.aggregateIssues
+ *
+ * Read `ctx.bytes` and return a UTF-8 string for inspection. Centralizes
+ * the string-or-Buffer-or-empty handling so each guard's `check(ctx)`
+ * body deals with the inspection logic only. Returns `""` when
+ * `ctx.bytes` is missing — callers treat empty as the serve case.
+ *
+ * @example
+ *   var ctx  = { bytes: Buffer.from("name,age\nada,36") };
+ *   var text = b.gateContract.extractBytesAsText(ctx);
+ *   text;                                                // → "name,age\nada,36"
+ *
+ *   b.gateContract.extractBytesAsText({});               // → ""
+ *   b.gateContract.extractBytesAsText({ bytes: "x,y" }); // → "x,y"
+ */
 function extractBytesAsText(ctx) {
   if (!ctx) return "";
   var bytes = ctx.bytes;
@@ -693,16 +1164,52 @@ function extractBytesAsText(ctx) {
   return Buffer.isBuffer(bytes) ? bytes.toString("utf8") : String(bytes);
 }
 
-// buildGuardGate — gate-construction shorthand. Every guard-*
-// primitive's gate(opts) factory forwards the same ~16-key opts bag
-// (mode, audit, observability, forensicEvidenceStore, cache, hooks,
-// runtime cap, ...) to defineGate. Centralizes that forwarding so each
-// guard's gate() body is just the check function plus a label.
-//
-//   gateContract.buildGuardGate(
-//     opts.name || "guardCsv:" + (opts.profile || "default"),
-//     opts,
-//     async function (ctx) { ... per-guard check ... });
+/**
+ * @primitive  b.gateContract.buildGuardGate
+ * @signature  b.gateContract.buildGuardGate(name, opts, check)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.defineGate, b.gateContract.extractBytesAsText
+ *
+ * Gate-construction shorthand for guard-* primitives. Forwards the
+ * uniform ~16-key opts bag (`mode`, `audit`, `observability`,
+ * `forensicEvidenceStore`, `forensicSnippetBytes`, `cache`,
+ * `cacheTtlMs`, `maxRuntimeMs`, all six lifecycle hooks) to
+ * `defineGate`, so each guard's `gate(opts)` body is just the per-guard
+ * `check` function plus a label. Result satisfies `validateGateShape`.
+ *
+ * @opts
+ *   mode:                  string,        // one of MODES; default "enforce"
+ *   audit:                 object|null,   // b.audit handle for emission
+ *   observability:         object|null,   // b.observability handle
+ *   forensicEvidenceStore: object|null,   // { write({ ... }) }
+ *   forensicSnippetBytes:  number,        // 0 = disabled
+ *   cache:                 object|null,   // b.cache shape
+ *   cacheTtlMs:            number,
+ *   maxRuntimeMs:          number,        // 0 = uncapped
+ *   beforeCheck:           function|null,
+ *   afterCheck:            function|null,
+ *   onIssue:               function|null,
+ *   onSanitize:            function|null,
+ *   onRefuse:              function|null,
+ *   onAudit:               function|null,
+ *
+ * @example
+ *   var myGuardGate = b.gateContract.buildGuardGate(
+ *     "myGuard:strict",
+ *     { mode: "enforce", maxRuntimeMs: 250 },
+ *     async function (ctx) {
+ *       var text = b.gateContract.extractBytesAsText(ctx);
+ *       if (text.length === 0) return { ok: true, action: "serve" };
+ *       if (/\s/.test(text)) {
+ *         return { ok: false, action: "refuse",
+ *                  issues: [{ kind: "whitespace", severity: "high" }] };
+ *       }
+ *       return { ok: true, action: "serve" };
+ *     });
+ *   var d = await myGuardGate.check({ bytes: Buffer.from("hello") });
+ *   d.action;                                            // → "serve"
+ */
 function buildGuardGate(name, opts, check) {
   opts = opts || {};
   return defineGate({
@@ -726,10 +1233,28 @@ function buildGuardGate(name, opts, check) {
   });
 }
 
-// aggregateIssues — wrap an issues array in the canonical
-// `{ ok, issues }` validate-result shape. ok=true when no issue is
-// `critical` or `high` severity. Used by guards whose validate path
-// can't go through runIssueValidator (raw-Buffer input cases).
+/**
+ * @primitive  b.gateContract.aggregateIssues
+ * @signature  b.gateContract.aggregateIssues(issues)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.runIssueValidator, b.gateContract.summarizeIssues
+ *
+ * Wrap an issues array in the canonical `{ ok, issues }` validate-result
+ * shape. `ok` is `true` only when no issue carries `critical` or `high`
+ * severity — `info` and `warn` issues do not flip `ok`. Used by guards
+ * whose validate path can't route through `runIssueValidator` (raw-Buffer
+ * input cases such as svg magic detection or filename byte scans).
+ *
+ * @example
+ *   var result = b.gateContract.aggregateIssues([
+ *     { kind: "csv.bidi", severity: "high",
+ *       snippet: "U+202E embedded in cell" },
+ *     { kind: "csv.trailing-whitespace", severity: "info" },
+ *   ]);
+ *   result.ok;                                           // → false
+ *   result.issues.length;                                // → 2
+ */
 function aggregateIssues(issues) {
   return {
     ok: !issues.some(function (i) {
@@ -739,12 +1264,27 @@ function aggregateIssues(issues) {
   };
 }
 
-// badInputResultIfNotStringOrBuffer — returns the canonical
-// `{ ok: false, issues: [{ kind: "bad-input", ... }] }` result when
-// `input` is neither a string nor a Buffer; null otherwise. Used by
-// guards whose validate path can't pre-convert (e.g. guard-svg needs
-// raw bytes for SVGZ magic detection; guard-filename needs raw bytes
-// for overlong-UTF-8 byte scan).
+/**
+ * @primitive  b.gateContract.badInputResultIfNotStringOrBuffer
+ * @signature  b.gateContract.badInputResultIfNotStringOrBuffer(input)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.runIssueValidator, b.gateContract.aggregateIssues
+ *
+ * Type-guard for guard-* validate entry points. Returns the canonical
+ * `{ ok: false, issues: [{ kind: "bad-input", severity: "high", ... }] }`
+ * result when `input` is neither a string nor a Buffer; `null`
+ * otherwise. Used by guards whose validate path can't pre-convert —
+ * `b.guardSvg` needs raw bytes for SVGZ magic detection,
+ * `b.guardFilename` needs raw bytes for the overlong-UTF-8 byte scan.
+ *
+ * @example
+ *   b.gateContract.badInputResultIfNotStringOrBuffer("hello");      // → null
+ *   b.gateContract.badInputResultIfNotStringOrBuffer(Buffer.from("x")); // → null
+ *   var bad = b.gateContract.badInputResultIfNotStringOrBuffer(42);
+ *   bad.ok;                                              // → false
+ *   bad.issues[0].kind;                                  // → "bad-input"
+ */
 function badInputResultIfNotStringOrBuffer(input) {
   if (typeof input === "string" || Buffer.isBuffer(input)) return null;
   return {
@@ -754,17 +1294,40 @@ function badInputResultIfNotStringOrBuffer(input) {
   };
 }
 
-// runIssueValidator — boilerplate for guard-* validate(input, opts)
-// entry points. Normalizes string|Buffer input, returns the canonical
-// { ok: false, issues: [{ kind: "bad-input", ... }] } shape on type
-// mismatch, otherwise calls the operator-supplied detector and
-// computes ok = no issue is critical/high. Used so every guard's
-// validate() body is identical scaffolding around the per-guard
-// _detectIssues function.
-//
-//   gateContract.runIssueValidator(input, opts, function (text, opts) {
-//     return _detectIssues(text, opts);
-//   });
+/**
+ * @primitive  b.gateContract.runIssueValidator
+ * @signature  b.gateContract.runIssueValidator(input, opts, detector)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.aggregateIssues, b.gateContract.badInputResultIfNotStringOrBuffer
+ *
+ * Boilerplate for guard-* `validate(input, opts)` entry points.
+ * Normalizes string-or-Buffer input to a UTF-8 string, returns the
+ * canonical `{ ok: false, issues: [{ kind: "bad-input", ... }] }` shape
+ * on type mismatch, otherwise calls the operator-supplied `detector`
+ * and aggregates its issues array. Result `ok` is `true` only when no
+ * detected issue is `critical` / `high` severity. Lets every guard's
+ * `validate()` body be identical scaffolding around the per-guard
+ * detector. The `opts` argument is forwarded verbatim as the second
+ * argument to `detector(text, opts)` — its shape is detector-defined,
+ * not constrained by gate-contract.
+ *
+ * @opts
+ *   ...:   any,                     // detector-defined; passed through to detector(text, opts)
+ *
+ * @example
+ *   function detectFormulaTrigger(text) {
+ *     if (/^[=+\-@]/.test(text)) {
+ *       return [{ kind: "csv.formula-injection", severity: "high",
+ *                 snippet: text.slice(0, 16) }];
+ *     }
+ *     return [];
+ *   }
+ *   var bad = b.gateContract.runIssueValidator("=cmd|x", {}, detectFormulaTrigger);
+ *   bad.ok;                                              // → false
+ *   var ok  = b.gateContract.runIssueValidator("ada,36", {}, detectFormulaTrigger);
+ *   ok.ok;                                               // → true
+ */
 function runIssueValidator(input, opts, detector) {
   var text = typeof input === "string"
     ? input
@@ -779,18 +1342,52 @@ function runIssueValidator(input, opts, detector) {
   return aggregateIssues(detector(text, opts));
 }
 
-// resolveProfileAndPosture — overlay opts.profile + opts.compliancePosture
-// over a defaults object using guard-supplied tables. Used by every guard
-// primitive's create()/factory entry point so the resolution shape is
-// identical across the family.
-//
-//   resolveProfileAndPosture(opts, {
-//     profiles:           PROFILES,
-//     compliancePostures: COMPLIANCE_POSTURES,
-//     defaults:           DEFAULTS,
-//     errorClass:         GuardCsvError,
-//     errCodePrefix:      "csv",        // throws "csv.bad-profile" / "csv.bad-posture"
-//   })
+/**
+ * @primitive  b.gateContract.resolveProfileAndPosture
+ * @signature  b.gateContract.resolveProfileAndPosture(opts, cfg)
+ * @since      0.7.5
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.gateContract.makeProfileBuilder, b.gateContract.lookupCompliancePosture
+ *
+ * Overlay `opts.profile` and `opts.compliancePosture` on top of a
+ * defaults object using guard-supplied tables. Every guard primitive's
+ * factory routes through this so the resolution shape — defaults
+ * first, profile overlay, posture overlay, inline opts last — stays
+ * identical across the family. When `opts.compliancePosture` is unset
+ * and `b.compliance.set()` has declared a global posture, the global
+ * posture takes effect (the value-add of the top-level coordinator).
+ *
+ * Throws `cfg.errorClass.factory(cfg.errCodePrefix + ".bad-profile")`
+ * for unknown profile names and `... + ".bad-posture"` for unknown
+ * postures.
+ *
+ * @opts
+ *   profiles:           object,        // PROFILES table (required)
+ *   compliancePostures: object,        // COMPLIANCE_POSTURES table (required)
+ *   defaults:           object,        // baseline before overlay
+ *   errorClass:         FrameworkError,// throws via .factory(code, msg)
+ *   errCodePrefix:      string,        // e.g. "csv" → "csv.bad-profile"
+ *
+ * @example
+ *   var PROFILES = {
+ *     strict:   { formulaInjectionPolicy: "reject",     bidiCharPolicy: "reject" },
+ *     balanced: { formulaInjectionPolicy: "prefix-tab", bidiCharPolicy: "strip"  },
+ *   };
+ *   var POSTURES = { hipaa: { piiPolicy: "redact" } };
+ *   var resolved = b.gateContract.resolveProfileAndPosture(
+ *     { profile: "balanced", compliancePosture: "hipaa", maxCellBytes: 65536 },
+ *     {
+ *       profiles:           PROFILES,
+ *       compliancePostures: POSTURES,
+ *       defaults:           { maxCellBytes: 1024 },
+ *       errorClass:         b.guardCsv.GuardCsvError,
+ *       errCodePrefix:      "csv",
+ *     });
+ *   resolved.formulaInjectionPolicy;                     // → "prefix-tab"
+ *   resolved.piiPolicy;                                  // → "redact"
+ *   resolved.maxCellBytes;                               // → 65536
+ */
 function resolveProfileAndPosture(opts, cfg) {
   opts = opts || {};
   validateOpts.requireObject(cfg, "gateContract.resolveProfileAndPosture",
@@ -830,15 +1427,47 @@ function resolveProfileAndPosture(opts, cfg) {
   return Object.assign({}, cfg.defaults || {}, overlay, opts);
 }
 
-// buildProfile — recursive profile composition with cycle detection.
-//
-//   buildProfile({
-//     baseProfile: "blog-post",
-//     extends:     ["custom-tags"],
-//     overrides:   { allowedTags: [...] },
-//     removes:     { allowedAttrs: { a: ["target"] } },
-//     resolveProfile: name => profile,    // operator-supplied resolver
-//   })
+/**
+ * @primitive  b.gateContract.buildProfile
+ * @signature  b.gateContract.buildProfile(opts)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.makeProfileBuilder, b.gateContract.resolveProfileAndPosture
+ *
+ * Recursive profile composition with cycle detection. Walks
+ * `opts.baseProfile` and every name in `opts.extends` through the
+ * caller-supplied `opts.resolveProfile` resolver, deep-merging arrays
+ * (set-union, later-wins on duplicates) and objects (recursive). Then
+ * applies inline `opts.overrides` and finally `opts.removes` (which
+ * can drop array entries or whole keys). Cycles throw
+ * `gate-contract/profile-cycle`; unknown names throw
+ * `gate-contract/unknown-profile`. Most guards bind through
+ * `makeProfileBuilder` and never call `buildProfile` directly.
+ *
+ * @opts
+ *   baseProfile:    string,        // start from this profile name
+ *   extends:        string[],      // additional bases (later-wins)
+ *   overrides:      object,        // inline merge after extends
+ *   removes:        object,        // drop array entries or keys
+ *   resolveProfile: function,      // (name) → profile|null  (required)
+ *
+ * @example
+ *   var PROFILES = {
+ *     "blog-post": {
+ *       allowedTags: ["p", "a", "strong"],
+ *       allowedAttrs: { a: ["href", "target"] },
+ *     },
+ *     "with-images": { extends: ["blog-post"], allowedTags: ["img"] },
+ *   };
+ *   var resolved = b.gateContract.buildProfile({
+ *     baseProfile:    "with-images",
+ *     overrides:      { allowedTags: ["em"] },
+ *     removes:        { allowedAttrs: { a: ["target"] } },
+ *     resolveProfile: function (n) { return PROFILES[n] || null; },
+ *   });
+ *   resolved.allowedTags;                                // → ["p","a","strong","img","em"]
+ *   resolved.allowedAttrs.a;                             // → ["href"]
+ */
 function buildProfile(opts) {
   validateOpts.requireObject(opts, "gateContract.buildProfile", GateContractError);
   var resolve = opts.resolveProfile;
@@ -924,11 +1553,30 @@ function _applyRemoves(target, removes) {
   return out;
 }
 
-// summarizeIssues — project a gate decision's `issues` array down to the
-// audit-shape (kind / severity / ruleId only — full snippets stay in the
-// forensic store). Replaces the per-host inline `(d.issues || []).map(
-// function (i) { return { kind: i.kind, severity: i.severity, ruleId:
-// i.ruleId }; })` shape.
+/**
+ * @primitive  b.gateContract.summarizeIssues
+ * @signature  b.gateContract.summarizeIssues(issues)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.aggregateIssues, b.gateContract.defineGate
+ *
+ * Project a gate decision's `issues` array down to the audit-friendly
+ * shape — `{ kind, severity, ruleId }` only. Full snippets stay in the
+ * forensic evidence store; the audit log records the classification
+ * without the offending bytes. Replaces the inline
+ * `(d.issues || []).map(...)` pattern host primitives previously
+ * carried per emit site.
+ *
+ * @example
+ *   var summary = b.gateContract.summarizeIssues([
+ *     { kind: "csv.bidi", severity: "high", ruleId: "BIDI-OVERRIDE",
+ *       snippet: "<offending bytes redacted>" },
+ *     { kind: "csv.trailing-whitespace", severity: "info", ruleId: "TRIM" },
+ *   ]);
+ *   summary.length;                                      // → 2
+ *   summary[0].snippet;                                  // → undefined  (stripped)
+ *   summary[0].ruleId;                                   // → "BIDI-OVERRIDE"
+ */
 function summarizeIssues(issues) {
   if (!Array.isArray(issues)) return [];
   return issues.map(function (i) {
@@ -936,8 +1584,34 @@ function summarizeIssues(issues) {
   });
 }
 
-// composeHooks — chain operator hooks. First non-null filter result
-// wins; transformer hooks run sequentially.
+/**
+ * @primitive  b.gateContract.composeHooks
+ * @signature  b.gateContract.composeHooks(hooks)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.gateContract.defineGate, b.gateContract.buildGuardGate
+ *
+ * Chain a list of operator hooks into a single async hook. Empty
+ * arrays return `null` (so `defineGate` can pass the result through
+ * its `hooks.X || null` slot); single-element arrays return the
+ * lone hook unchanged. Multi-element chains run sequentially —
+ * `{ suppress: true }` or `{ skip: true }` from any hook short-
+ * circuits and returns; otherwise the last non-null hook result wins.
+ *
+ * @example
+ *   var redactPii = function (issue) {
+ *     return Object.assign({}, issue, { snippet: "<redacted>" });
+ *   };
+ *   var dropInfo  = function (issue) {
+ *     return issue.severity === "info" ? { suppress: true } : null;
+ *   };
+ *   var onIssue = b.gateContract.composeHooks([dropInfo, redactPii]);
+ *   var infoHit = await onIssue({ kind: "csv.trim", severity: "info" });
+ *   infoHit.suppress;                                    // → true
+ *   var bidi = await onIssue({ kind: "csv.bidi", severity: "high",
+ *                              snippet: "U+202E" });
+ *   bidi.snippet;                                        // → "<redacted>"
+ */
 function composeHooks(hooks) {
   hooks = (hooks || []).filter(Boolean);
   if (hooks.length === 0) return null;