@blamejs/blamejs-shop 0.4.55 → 0.4.57

package/lib/vendor/blamejs/lib/gate-contract.js

@@ -50,6 +50,8 @@ var bCrypto = require("./crypto");
 var lazyRequire = require("./lazy-require");
 var safeAsync = require("./safe-async");
 var validateOpts = require("./validate-opts");
+var numericBounds = require("./numeric-bounds");
+var codepointClass = require("./codepoint-class");
 var { GateContractError, defineClass } = require("./framework-error");
 
 var observability = lazyRequire(function () { return require("./observability"); });
@@ -977,10 +979,8 @@ function canaryGate(gate, opts) {
 function cachingGate(gate, opts) {
   opts = opts || {};
   var backend = opts.backend;
-  if (!backend || typeof backend.get !== "function" || typeof backend.set !== "function") {
-    throw _err("gate-contract/bad-opt",
-      "cachingGate: opts.backend must expose { get, set } (b.cache shape)");
-  }
+  validateOpts.requireMethods(backend, ["get", "set"],
+    "cachingGate: opts.backend (b.cache shape)", GateContractError, "gate-contract/bad-opt");
   // ttlMs is read inside check() via closure; keep DEFAULT_CACHE_TTL_MS
   // referenced even if the host-side cache wrapping path doesn't need
   // explicit TTL today (the gate's per-instance cache uses cacheTtlMs).
@@ -1166,6 +1166,44 @@ function makeProfileResolver(cfg) {
   };
 }
 
+/**
+ * @primitive  b.gateContract.resolveProfileName
+ * @signature  b.gateContract.resolveProfileName(opts, postures, defaultProfile)
+ * @since      0.15.13
+ * @status     stable
+ * @related    b.gateContract.makeProfileResolver
+ *
+ * Resolve a profile NAME from create-time opts with PROFILE precedence: an
+ * explicit `opts.profile` wins, else `opts.posture` mapped through the
+ * compliance-posture table, else `defaultProfile`. Returns the name WITHOUT
+ * validating it — the caller checks membership in its own `PROFILES` map and
+ * throws its own typed, field-specific error. This is the resolution EXPRESSION
+ * the mail-scanner / envelope factories (mail-greylist / mail-rbl / mail-scan /
+ * mail-spam-score / mail-helo / guard-envelope) each hand-rolled identically.
+ *
+ * It differs from `makeProfileResolver` in two deliberate ways: it does not
+ * throw (so the caller keeps its bespoke bad-profile message) and it gives
+ * `profile` precedence rather than `posture` precedence. The two precedences
+ * coexist in the framework today (the `defineParser`-shaped guards resolve
+ * posture-first); unifying them is a policy decision, and routing every caller
+ * through one of these two helpers is what makes that decision a single edit.
+ *
+ * @opts
+ *   profile:   string,   // explicit profile name — wins when present
+ *   posture:   string,   // compliance posture, mapped through `postures`
+ *
+ * @example
+ *   var name = b.gateContract.resolveProfileName(
+ *     { profile: "balanced" }, COMPLIANCE_POSTURES, "strict");
+ *   // → "balanced"
+ */
+function resolveProfileName(opts, postures, defaultProfile) {
+  opts = opts || {};
+  return opts.profile ||
+    (opts.posture && postures && postures[opts.posture]) ||
+    defaultProfile;
+}
+
 /**
  * @primitive  b.gateContract.throwOnRefusalSeverity
  * @signature  b.gateContract.throwOnRefusalSeverity(issues, cfg)
@@ -1249,6 +1287,244 @@ var ALL_STRICT_POSTURES = Object.freeze({
   soc2:      "strict",
 });
 
+/**
+ * @primitive  b.gateContract.CHAR_THREATS_REJECT_ALL
+ * @signature  b.gateContract.CHAR_THREATS_REJECT_ALL
+ * @since      0.15.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.gateContract.charThreatDisposition, b.gateContract.makeProfileBuilder
+ *
+ * The universal character-safety floor: the four invisible-character
+ * threats — BIDI overrides, C0/C1 control bytes, embedded null bytes,
+ * and zero-width characters — each set to `"reject"`. These four
+ * classes are categorically unsafe in an identifier or structured
+ * value (forgery, log injection, label-segmentation, parser
+ * confusion), so every identifier/protocol guard refuses them in
+ * every profile tier and the content guards refuse them in `strict`.
+ *
+ * Spread this frozen block into a profile tier instead of re-declaring
+ * the four lines: `{ ...gateContract.CHAR_THREATS_REJECT_ALL, ... }`.
+ * A tier that relaxes one class overrides after the spread (e.g.
+ * `{ ...CHAR_THREATS_REJECT_ALL, zeroWidthPolicy: "strip" }`), keeping
+ * the floor for the other three. Frozen and shared by reference; the
+ * spread copies the values into each consumer's own tier object.
+ *
+ * @example
+ *   var PROFILES = Object.freeze({
+ *     strict: { ...b.gateContract.CHAR_THREATS_REJECT_ALL, maxBytes: 256 },
+ *   });
+ *   PROFILES.strict.bidiPolicy;                           // → "reject"
+ *   Object.isFrozen(b.gateContract.CHAR_THREATS_REJECT_ALL); // → true
+ */
+var CHAR_THREATS_REJECT_ALL = Object.freeze({
+  bidiPolicy:      "reject",
+  controlPolicy:   "reject",
+  nullBytePolicy:  "reject",
+  zeroWidthPolicy: "reject",
+});
+
+/**
+ * @primitive  b.gateContract.DANGEROUS_URL_SCHEMES
+ * @signature  b.gateContract.DANGEROUS_URL_SCHEMES
+ * @since      0.15.13
+ * @status     stable
+ * @compliance soc2
+ * @related    b.gateContract.CHAR_THREATS_REJECT_ALL, b.guardHtml.validate, b.guardSvg.validate
+ *
+ * The frozen denylist of URL schemes that are categorically unsafe inside a
+ * markup attribute value (`href` / `src` / `xlink:href`) — the markup XSS and
+ * dangerous-resource vector set. `javascript` / `vbscript` / `livescript` /
+ * `mocha` / `ecmascript` execute script; `data` / `view-source` / `mhtml` /
+ * `feed` carry or expose renderable content; `file` / `jar` / `intent` reach
+ * local resources or protocol handlers. A markup sanitizer rejects an
+ * attribute whose scheme is in this list.
+ *
+ * Lower-cased, scheme-name only (no trailing colon) so callers compare against
+ * a lower-cased parsed scheme via `indexOf(scheme) !== -1`. This is the
+ * markup-attribute DENYLIST — distinct from `b.safeUrl`'s protocol ALLOWLIST,
+ * which governs full-URL parsing where only an explicit set of protocols is
+ * permitted.
+ *
+ * @example
+ *   b.gateContract.DANGEROUS_URL_SCHEMES.indexOf("javascript");  // → 0 (dangerous)
+ *   b.gateContract.DANGEROUS_URL_SCHEMES.indexOf("https");       // → -1 (allowed)
+ *   Object.isFrozen(b.gateContract.DANGEROUS_URL_SCHEMES);       // → true
+ */
+var DANGEROUS_URL_SCHEMES = Object.freeze([
+  "javascript", "vbscript", "livescript", "mocha", "ecmascript",
+  "file", "mhtml", "jar", "intent", "view-source", "feed", "data",
+]);
+
+/**
+ * @primitive  b.gateContract.SAFE_URL_SCHEMES
+ * @signature  b.gateContract.SAFE_URL_SCHEMES
+ * @since      0.15.13
+ * @status     stable
+ * @compliance soc2
+ * @related    b.gateContract.DANGEROUS_URL_SCHEMES
+ *
+ * The frozen base allowlist of URL schemes a markup sanitizer accepts in an
+ * attribute value at the `strict` tier — `http` / `https` / `mailto` / `tel`.
+ * A guard extends it for looser tiers (e.g. `SAFE_URL_SCHEMES.concat(["ftp"])`)
+ * rather than re-declaring the base. Scheme names only, no trailing colon.
+ *
+ * @example
+ *   b.gateContract.SAFE_URL_SCHEMES;                       // → ["http","https","mailto","tel"]
+ *   Object.isFrozen(b.gateContract.SAFE_URL_SCHEMES);      // → true
+ */
+var SAFE_URL_SCHEMES = Object.freeze(["http", "https", "mailto", "tel"]);
+
+/**
+ * @primitive  b.gateContract.identifierFixtures
+ * @signature  b.gateContract.identifierFixtures(benign, hostile, encoding?)
+ * @since      0.15.13
+ * @status     stable
+ * @related    b.gateContract.defineGuard
+ *
+ * Build an identifier guard's frozen `INTEGRATION_FIXTURES` from one benign
+ * and one hostile sample string. The layer-5 host harness feeds the string
+ * form to `gate.check({ identifier })` and the byte form to the upload /
+ * digest paths, so the two are the same value in two representations. A guard
+ * that hand-writes both forms repeats its sample literal twice (`benignBytes:
+ * Buffer.from("x"), benignIdentifier: "x"`); declaring the string once and
+ * deriving the buffer removes that per-guard duplication. `encoding` defaults
+ * to `"utf8"` — pass `"ascii"` for line-protocol command samples whose bytes
+ * must stay single-octet.
+ *
+ * @example
+ *   var INTEGRATION_FIXTURES =
+ *     b.gateContract.identifierFixtures("example.com", "192.168.1.1");
+ *   INTEGRATION_FIXTURES.benignIdentifier;      // → "example.com"
+ *   INTEGRATION_FIXTURES.benignBytes;           // → Buffer "example.com"
+ *   Object.isFrozen(INTEGRATION_FIXTURES);      // → true
+ */
+function identifierFixtures(benign, hostile, encoding) {
+  validateOpts.requireNonEmptyString(benign,
+    "gateContract.identifierFixtures: benign", GateContractError, "gate-contract/bad-opt");
+  validateOpts.requireNonEmptyString(hostile,
+    "gateContract.identifierFixtures: hostile", GateContractError, "gate-contract/bad-opt");
+  var enc = encoding || "utf8";
+  if (typeof enc !== "string" || !Buffer.isEncoding(enc)) {
+    throw _err("gate-contract/bad-opt",
+      "gateContract.identifierFixtures: encoding must be a valid Buffer encoding, got " +
+      JSON.stringify(encoding));
+  }
+  return Object.freeze({
+    kind:              "identifier",
+    benignBytes:       Buffer.from(benign, enc),
+    hostileBytes:      Buffer.from(hostile, enc),
+    benignIdentifier:  benign,
+    hostileIdentifier: hostile,
+  });
+}
+
+/**
+ * @primitive  b.gateContract.compliancePostures
+ * @signature  b.gateContract.compliancePostures(profiles, spec)
+ * @since      0.15.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.gateContract.ALL_STRICT_POSTURES, b.gateContract.resolveProfileAndPosture
+ *
+ * Build a content guard's four-posture `COMPLIANCE_POSTURES` map from its
+ * profile set and a single forensic-snippet budget, encoding the framework's
+ * regulation-disposition policy in one place instead of re-declaring it in
+ * every guard. Each regulation maps to the profile tier whose disposition
+ * matches its intent:
+ *
+ *   - `hipaa` / `pci-dss` / `soc2` → the `strict` profile. These regimes
+ *     demand forensic integrity — the record must not be silently
+ *     altered — so every threat class is rejected, never sanitized.
+ *   - `gdpr` → the `balanced` profile. Data-minimization favors removing
+ *     the offending bytes over rejecting the whole value, so on free-text
+ *     content the balanced tier strips the sanitizable character classes (bidi
+ *     / control / zero-width) while still rejecting structural threats. For an
+ *     identifier guard the balanced tier rejects those classes too —
+ *     stripping bytes from an identifier would change its identity — so
+ *     the disposition follows the guard's own content kind automatically.
+ *
+ * The forensic snippet budget scales with each regime's retention posture:
+ * `hipaa` / `pci-dss` keep `base` bytes, `gdpr` keeps `base / 2` (retain less
+ * hostile data under data-minimization), `soc2` keeps `base * 2` (audit
+ * retention). Pass `spec.overlays` to layer a deliberate per-posture delta on
+ * top of the tier — e.g. a filename guard stripping bidi / control under
+ * `gdpr` where its balanced profile would reject them. Each returned posture is
+ * frozen and shared by reference.
+ *
+ * @opts
+ *   {
+ *     base:     number,    // required, positive even byte count: the hipaa/pci snippet budget
+ *     overlays: {          // optional per-posture policy deltas, merged last
+ *       hipaa:     object,
+ *       "pci-dss": object,
+ *       gdpr:      object,
+ *       soc2:      object,
+ *     },
+ *   }
+ *
+ * @example
+ *   var COMPLIANCE_POSTURES = b.gateContract.compliancePostures(PROFILES, {
+ *     base: 256,
+ *   });
+ *   COMPLIANCE_POSTURES.gdpr.forensicSnippetBytes;       // → 128
+ *   Object.isFrozen(COMPLIANCE_POSTURES.hipaa);          // → true
+ */
+function compliancePostures(profiles, spec) {
+  validateOpts.requireObject(profiles, "gateContract.compliancePostures", GateContractError);
+  if (!profiles.strict || !profiles.balanced) {
+    throw _err("gate-contract/bad-profiles",
+      "compliancePostures: profiles must include 'strict' and 'balanced'");
+  }
+  spec = spec || {};
+  var base = spec.base;
+  if (typeof base !== "number" || !isFinite(base) || base <= 0 || base % 2 !== 0) {
+    throw _err("gate-contract/bad-base",
+      "compliancePostures: spec.base must be a positive even byte count");
+  }
+  var overlays = spec.overlays || {};
+  function build(tier, snippetBytes, overlay) {
+    return Object.freeze(Object.assign({}, profiles[tier],
+      { forensicSnippetBytes: C.BYTES.bytes(snippetBytes) }, overlay || {}));
+  }
+  return Object.freeze({
+    hipaa:     build("strict",   base,     overlays.hipaa),
+    "pci-dss": build("strict",   base,     overlays["pci-dss"]),
+    gdpr:      build("balanced", base / 2, overlays.gdpr),
+    soc2:      build("strict",   base * 2, overlays.soc2),
+  });
+}
+
+/**
+ * @primitive  b.gateContract.strictDefaults
+ * @signature  b.gateContract.strictDefaults(profiles, overlay?)
+ * @since      0.15.13
+ * @status     stable
+ * @related    b.gateContract.compliancePostures, b.gateContract.defineGuard
+ *
+ * Build a guard's frozen `DEFAULTS` opts: its `strict` profile, in `enforce`
+ * mode, plus any per-guard overlay. Every guard's no-opts call path starts from
+ * the strictest profile with enforcement on (security-on by default); the only
+ * variation is a guard that adds a parse runtime cap (`maxRuntimeMs`) or another
+ * default override. Replaces the hand-rolled `Object.freeze(Object.assign({},
+ * PROFILES["strict"], { mode: "enforce", … }))` every guard repeated.
+ *
+ * @opts
+ *   overlay: object   // optional per-guard default overrides merged last (e.g. { maxRuntimeMs: C.TIME.seconds(10) }); may override `mode`
+ *
+ * @example
+ *   var DEFAULTS = b.gateContract.strictDefaults(PROFILES);                          // strict + enforce
+ *   var DEFAULTS = b.gateContract.strictDefaults(PROFILES, { maxRuntimeMs: 10000 }); // + a parse runtime cap
+ */
+function strictDefaults(profiles, overlay) {
+  validateOpts.requireObject(profiles, "gateContract.strictDefaults", GateContractError);
+  if (!profiles.strict) {
+    throw _err("gate-contract/bad-profiles",
+      "strictDefaults: profiles must include 'strict'");
+  }
+  return Object.freeze(Object.assign({}, profiles.strict, { mode: "enforce" }, overlay || {}));
+}
+
 /**
  * @primitive  b.gateContract.makeRulePackLoader
  * @signature  b.gateContract.makeRulePackLoader(errorClass, codePrefix)
@@ -1386,6 +1662,234 @@ function buildGuardGate(name, opts, check) {
   });
 }
 
+/**
+ * @primitive  b.gateContract.severityDisposition
+ * @signature  b.gateContract.severityDisposition(issues)
+ * @since      0.15.13
+ * @status     stable
+ * @related    b.gateContract.buildGuardGate, b.gateContract.buildContentGate
+ *
+ * The non-sanitizing guard gate's severity action-chain in one place. A guard
+ * that cannot repair its subject (an auth bundle, an OAuth flow, a GraphQL
+ * request, image / PDF metadata, an archive entry list, an email body, a regex
+ * pattern) ends its `gate` check with the identical disposition: `serve` when
+ * there are no findings, `audit-only` when no finding reaches refusal severity,
+ * else `refuse`. This is the sibling of `buildContentGate` (which adds the
+ * sanitize attempt for content that CAN be repaired). Each guard keeps its own
+ * subject extraction + validate call, then returns `severityDisposition(rv.issues)`.
+ *
+ * A finding of `critical` OR `high` severity refuses; anything lower is
+ * `audit-only`. The returned shape matches a gate `check` result:
+ * `{ ok, action }` (no `issues` on a clean serve) or `{ ok, action, issues }`.
+ *
+ * @example
+ *   var rv = module.exports.validate(bundle, opts);
+ *   return b.gateContract.severityDisposition(rv.issues);
+ *   // [] → { ok: true, action: "serve" }
+ *   // [{ severity: "low" }] → { ok: true, action: "audit-only", issues: [...] }
+ *   // [{ severity: "high" }] → { ok: false, action: "refuse", issues: [...] }
+ */
+function severityDisposition(issues) {
+  if (issues.length === 0) return { ok: true, action: "serve" };
+  var hasCritical = issues.some(function (i) { return i.severity === "critical"; });
+  var hasHigh = issues.some(function (i) { return i.severity === "high"; });
+  if (!hasCritical && !hasHigh) {
+    return { ok: true, action: "audit-only", issues: issues };
+  }
+  return { ok: false, action: "refuse", issues: issues };
+}
+
+/**
+ * @primitive  b.gateContract.buildContentGate
+ * @signature  b.gateContract.buildContentGate(spec)
+ * @since      0.15.13
+ * @status     stable
+ * @related    b.gateContract.buildGuardGate, b.gateContract.defineGuard
+ *
+ * The content-guard gate action-chain in one place. Every content guard's
+ * `gate(opts)` ran the identical chain — extract the bytes, `serve` a clean
+ * input, `audit-only` when no issue reaches the refusal severity, attempt
+ * `sanitize` when the input is eligible, else `refuse` — differing only in
+ * declarative axes. Passing those axes to one primitive replaces ~30 lines of
+ * per-guard gate body and makes the chain impossible to drift between guards.
+ *
+ * A CRITICAL finding always `refuse`s — too severe to serve even sanitized (a
+ * stripped script can still carry an mXSS / parser-differential vector). Only
+ * HIGH findings are sanitize-eligible, and even then the action is PROVEN, not
+ * guessed: the gate runs `produceSanitized` then RE-VALIDATES its output,
+ * returning `sanitize` only when the result is verifiably clean — otherwise
+ * `refuse`. An operator's `reject` choice lands as critical (→ refuse) and a
+ * `strip` choice as high (→ sanitize-if-verified), so the severity carries the
+ * disposition with no per-policy bookkeeping — replacing a global "is any
+ * policy set to reject?" guess that wrongly froze sanitize for findings
+ * unrelated to the rejected policy. The sanitizer's own policy-respecting
+ * behaviour does the rest: it throws on / leaves a reject-class finding so the
+ * re-validate still refuses, and refuses anything it cannot actually repair.
+ * `sanitizeBlockingKinds` skips the attempt for inputs a text sanitizer must not
+ * touch (gzipped SVGZ bytes); a thrown producer falls through to `refuse`.
+ *
+ * @opts
+ *   name:                  string,                   // gate label (audit/metric/cache identity)
+ *   opts:                  object,                   // already resolved profile/posture opts
+ *   validate:              function,                 // (subject, opts) -> { ok, issues }
+ *   produceSanitized:      function,                 // (subject, opts) -> Buffer|string
+ *   ctxField:              "text"|"bytes",           // default "text" (extractBytesAsText); "bytes" reads ctx.bytes raw
+ *   sanitizeBlockingKinds: string[],                 // issue kinds that skip the sanitize attempt (e.g. ["svgz-compressed"])
+ *
+ * @example
+ *   var g = b.gateContract.buildContentGate({
+ *     name: "guardXml:strict", opts: resolved, validate: validate,
+ *     produceSanitized: function (t, o) { return sanitize(t, o); },
+ *   });
+ *   (await g.check({ bytes: Buffer.from("<a>1</a>") })).action;   // → "serve"
+ */
+function buildContentGate(spec) {
+  var opts = spec.opts || {};
+  var ctxField = spec.ctxField === "bytes" ? "bytes" : "text";
+  var blockKind = Array.isArray(spec.sanitizeBlockingKinds) ? spec.sanitizeBlockingKinds : [];
+
+  // A finding's disposition is what the operator's POLICY for that finding
+  // class chose, not the finding's impact severity. The guard declares the
+  // binding via spec.dispositionFor(issue, opts); anything it doesn't classify
+  // (an operator-injected rule, a structural hard-cap, an un-mapped kind) falls
+  // back to severity — and that fallback is CONSERVATIVE (a refusal-severity
+  // finding refuses, because the gate has no proof it can be repaired).
+  function _disposition(issue, fromGuard) {
+    if (fromGuard && typeof spec.dispositionFor === "function") {
+      var d = spec.dispositionFor(issue, opts);
+      if (d === "refuse" || d === "sanitize" || d === "audit") return d;
+    }
+    if (issue.disposition === "refuse" || issue.disposition === "sanitize" ||
+        issue.disposition === "audit") return issue.disposition;
+    return (issue.severity === "critical" || issue.severity === "high") ? "refuse" : "audit";
+  }
+
+  return buildGuardGate(spec.name, opts, async function (ctx) {
+    var subject = ctxField === "bytes" ? (ctx && ctx.bytes) : extractBytesAsText(ctx);
+    if (!subject) return { ok: true, action: "serve" };
+
+    var rv = spec.validate(subject, opts);
+    var entries = rv.issues.map(function (i) { return { issue: i, disp: _disposition(i, true) }; });
+    // Operator-injected detect-only findings (spec.extraIssues): the guard owns
+    // no sanitizer for them, so a refusal-severity hit can only refuse — never
+    // serve a "sanitized" output that still carries the operator's finding.
+    if (typeof spec.extraIssues === "function") {
+      var extra = spec.extraIssues(subject, opts, ctx) || [];
+      for (var k = 0; k < extra.length; k++) {
+        entries.push({ issue: extra[k], disp: _disposition(extra[k], false) });
+      }
+    }
+    if (entries.length === 0) return { ok: true, action: "serve" };
+
+    var issues = entries.map(function (e) { return e.issue; });
+    // refuse wins over sanitize wins over audit. A finding whose policy is
+    // `reject` (→ refuse), an always-dangerous denylist hit, or a structural
+    // hard-cap refuses the whole input regardless of any sanitizable siblings.
+    if (entries.some(function (e) { return e.disp === "refuse"; })) {
+      return { ok: false, action: "refuse", issues: issues };
+    }
+    // Some finding's policy chose to mitigate (strip / prefix / redact / drop):
+    // run the guard's own sanitizer, which performs exactly the policy-selected
+    // transform, and serve its output. The operator picked sanitize-and-serve
+    // over reject for these classes, so the result is trusted — no re-validation
+    // (a mitigation like CSV's prefix-tab is in-place, not removal, so a second
+    // detector pass would wrongly refuse it). sanitizeBlockingKinds skips the
+    // attempt for inputs a text sanitizer must not touch (gzipped SVGZ bytes);
+    // a sanitizer that throws (e.g. a reject-policy parse) falls through.
+    if (entries.some(function (e) { return e.disp === "sanitize"; })) {
+      var blocked = blockKind.some(function (kind) {
+        return issues.some(function (it) { return it.kind === kind; });
+      });
+      if (!blocked && typeof spec.produceSanitized === "function") {
+        try {
+          var clean = spec.produceSanitized(subject, opts);
+          var cleanBuf = Buffer.isBuffer(clean) ? clean : Buffer.from(String(clean), "utf8");
+          return { ok: true, action: "sanitize", sanitized: cleanBuf, issues: issues };
+        } catch (_e) { /* sanitizer could not repair → refuse */ }
+      }
+      return { ok: false, action: "refuse", issues: issues };
+    }
+    // Only audit-disposition (sub-refusal observational) findings remain.
+    return { ok: true, action: "audit-only", issues: issues };
+  });
+}
+
+/**
+ * @primitive  b.gateContract.policyDisposition
+ * @signature  b.gateContract.policyDisposition(policy)
+ * @since      0.15.13
+ * @status     stable
+ * @related    b.gateContract.buildContentGate
+ *
+ * Map an operator content-policy value to the gate disposition it selects.
+ * A content guard emits a finding only when the governing policy is not
+ * `allow`; this turns that policy into what the gate should DO with the
+ * finding — independent of the finding's impact severity:
+ *
+ * - `reject` → `refuse` (operator chose to reject this class outright)
+ * - `audit` / `audit-only` → `audit` (observe, do not block or alter)
+ * - a known mitigation (`strip`, `prefix-tab`, `prefix-quote`,
+ *   `wrap-with-quotes-and-prefix`, `allowlist`, `redact`, `trim`) →
+ *   `sanitize` (the guard's sanitizer performs the chosen transform)
+ *
+ * Fails CLOSED: an unrecognized policy value (a typo such as `rejet`, or a
+ * mitigation name not in the known set) maps to `refuse`, never `sanitize` —
+ * a misconfiguration must not silently downgrade a finding to serve-after-
+ * best-effort. Add a new mitigation to MITIGATION_POLICIES when one ships.
+ *
+ * @example
+ *   b.gateContract.policyDisposition("reject");      // → "refuse"
+ *   b.gateContract.policyDisposition("strip");       // → "sanitize"
+ *   b.gateContract.policyDisposition("audit-only");  // → "audit"
+ *   b.gateContract.policyDisposition("rejet");       // → "refuse" (fail closed)
+ */
+var MITIGATION_POLICIES = Object.freeze({
+  strip: true, "prefix-tab": true, "prefix-quote": true,
+  "wrap-with-quotes-and-prefix": true, allowlist: true, redact: true, trim: true,
+});
+function policyDisposition(policy) {
+  if (policy === "reject") return "refuse";
+  if (policy === "audit" || policy === "audit-only") return "audit";
+  if (MITIGATION_POLICIES[policy] === true) return "sanitize";
+  return "refuse";
+}
+
+/**
+ * @primitive  b.gateContract.charThreatDisposition
+ * @signature  b.gateContract.charThreatDisposition(issue, opts)
+ * @since      0.15.13
+ * @status     stable
+ * @related    b.gateContract.policyDisposition, b.codepointClass.detectCharThreats
+ *
+ * Gate disposition for the shared character-threat findings every content
+ * guard collects via `codepointClass.detectCharThreats` — `bidi-override`,
+ * `null-byte`, `control-char` — resolved from the guard's per-class policy
+ * (`bidiPolicy` / `nullBytePolicy` / `controlPolicy`). Returns `null` for any
+ * other kind so a guard's own `dispositionFor` can fall through to it for the
+ * shared kinds and handle its guard-specific findings itself.
+ *
+ * @opts
+ *   bidiPolicy:      string,   // governs the bidi-override finding
+ *   nullBytePolicy:  string,   // governs the null-byte finding
+ *   controlPolicy:   string,   // governs the control-char finding
+ *   zeroWidthPolicy: string,   // governs the zero-width finding
+ *
+ * @example
+ *   function dispositionFor(issue, opts) {
+ *     return b.gateContract.charThreatDisposition(issue, opts) ||
+ *            mySpecificMapping(issue, opts);
+ *   }
+ */
+function charThreatDisposition(issue, opts) {
+  switch (issue.kind) {
+    case "bidi-override": return policyDisposition(opts.bidiPolicy);
+    case "null-byte":     return policyDisposition(opts.nullBytePolicy);
+    case "control-char":  return policyDisposition(opts.controlPolicy);
+    case "zero-width":    return policyDisposition(opts.zeroWidthPolicy);
+    default:              return null;
+  }
+}
+
 /**
  * @primitive  b.gateContract.aggregateIssues
  * @signature  b.gateContract.aggregateIssues(issues)
@@ -1439,34 +1943,159 @@ function aggregateIssues(issues) {
  *   bad.issues[0].kind;                                  // → "bad-input"
  */
 function badInputResultIfNotStringOrBuffer(input) {
-  if (typeof input === "string" || Buffer.isBuffer(input)) return null;
+  // The "bytes" input contract IS this check — compose it so there is one
+  // source of truth for "string or Buffer, else bad-input".
+  var extracted = INPUT_CONTRACTS.bytes(input);
+  if (!extracted.badInput) return null;
   return {
     ok: false,
     issues: [{ kind: "bad-input", severity: "high",
-               snippet: "input is not string or Buffer" }],
+               snippet: extracted.badInput }],
   };
 }
 
+/**
+ * @primitive  b.gateContract.detectStringInput
+ * @signature  b.gateContract.detectStringInput(input, opts, cfg)
+ * @since      0.15.13
+ * @status     stable
+ * @related    b.gateContract.badInputResultIfNotStringOrBuffer, b.codepointClass.detectCharThreats
+ *
+ * The whole detector preamble every `raw`-contract string guard opens with:
+ * reject a non-string input, then an empty one, then one over the byte cap,
+ * else collect the codepoint-class threats (BIDI / control / null / zero-width)
+ * the guard then appends its own findings to. A guard on the `raw` input
+ * contract owns its own input check (see `INPUT_CONTRACTS`); this builds that
+ * preamble once, guard-named, instead of re-spelling its four steps in every
+ * `_detectIssues`. Returns `{ done, issues }`: when `done` the detector returns
+ * `issues` verbatim (the `<name>.bad-input` / `<name>.empty` / cap issue, or
+ * `[]` for a legal empty); when not `done`, `issues` is the codepoint-threat
+ * list the detector continues from. The byte cap runs before the codepoint
+ * scan so a huge input is rejected before the O(n) scan.
+ *
+ * The cap's divergence is data, not branching: `cap.bytes` is the limit (the
+ * guard's resolved `maxBytes` / `maxPatternBytes` / `maxDomainOctets`),
+ * `cap.kind` the issue kind (default `<name>-cap`), and `cap.snippet` the
+ * message — a string, or a `function(byteLen, bytes)` when it embeds the
+ * measured length. Omit `cap` for a guard with no byte cap.
+ *
+ * @opts
+ *   {
+ *     name:      string,    // required: the guard name — ruleId prefix + default noun
+ *     noun:      string,    // default name — the subject word in the bad-input/empty snippet
+ *     emptyMode: string,    // "issue" (default) → <name>.empty issue · "ok" → [] (empty is legal) · "skip" → no empty check
+ *     cap: {                // omit when the guard has no byte cap
+ *       bytes:   number,            // required: the byte limit
+ *       kind:    string,            // default "<name>-cap" — the cap issue kind (and ruleId suffix)
+ *       snippet: string|function,   // default "<noun> input exceeds maxBytes <bytes>"; fn(byteLen, bytes) when it needs the measured length
+ *     },
+ *     scanCodepoints: boolean,      // default true: the not-done result carries the codepoint-class scan. Pass false for a guard that scans codepoints later in its own detection (or parses them via its format, e.g. JSON) — the not-done result is then `[]`.
+ *   }
+ *
+ * @example
+ *   function _detectIssues(input, opts) {
+ *     var pre = b.gateContract.detectStringInput(input, opts, {
+ *       name: "cidr", cap: { bytes: opts.maxBytes },
+ *     });
+ *     if (pre.done) return pre.issues;
+ *     var issues = pre.issues;            // codepoint-class threats so far
+ *     // … guard-specific detection appends to issues …
+ *     return issues;
+ *   }
+ */
+function detectStringInput(input, opts, cfg) {
+  validateOpts.requireObject(cfg, "gateContract.detectStringInput", GateContractError);
+  validateOpts.requireNonEmptyString(cfg.name,
+    "gateContract.detectStringInput: cfg.name", GateContractError, "gate-contract/bad-opt");
+  var noun = cfg.noun || cfg.name;
+  if (typeof input !== "string") {
+    return { done: true, issues: [{ kind: "bad-input", severity: "high",
+      ruleId: cfg.name + ".bad-input", snippet: noun + " is not a string" }] };
+  }
+  var emptyMode = cfg.emptyMode || "issue";
+  if (emptyMode !== "skip" && input.length === 0) {
+    return { done: true, issues: emptyMode === "ok" ? [] :
+      [{ kind: "empty", severity: "high", ruleId: cfg.name + ".empty",
+         snippet: noun + " is empty" }] };
+  }
+  if (cfg.cap) {
+    var byteLen = Buffer.byteLength(input, "utf8");
+    if (byteLen > cfg.cap.bytes) {
+      var capKind = cfg.cap.kind || (cfg.name + "-cap");
+      var capSnippet = typeof cfg.cap.snippet === "function"
+        ? cfg.cap.snippet(byteLen, cfg.cap.bytes)
+        : (cfg.cap.snippet || (noun + " input exceeds maxBytes " + cfg.cap.bytes));
+      return { done: true, issues: [{ kind: capKind, severity: "high",
+        ruleId: cfg.name + "." + capKind, snippet: capSnippet }] };
+    }
+  }
+  if (cfg.scanCodepoints === false) return { done: false, issues: [] };
+  return { done: false, issues: codepointClass.detectCharThreats(input, opts, cfg.name) };
+}
+
+// Input contracts — the one place that knows how to turn a raw guard input
+// into the subject its detector expects (or flag bad input). Every guard's
+// `validate` differs only in its input shape; the contract captures that
+// difference so one `runIssueValidator` serves them all:
+//
+//   - "text": string / Buffer → UTF-8 text; anything else is bad input. The
+//     content guards (csv / html / markdown / json / ...) whose detector takes
+//     a string but does NOT type-check it themselves.
+//   - "bytes": string / Buffer is accepted and reaches the detector UNCHANGED
+//     (no utf8 coercion); anything else is bad input. The guards that inspect
+//     raw bytes before decoding (filename overlong-UTF-8, sql encoding gate) —
+//     converting to text first would hide the very bytes they check. This is
+//     exactly `badInputResultIfNotStringOrBuffer(input) ||
+//     aggregateIssues(detect(input))`.
+//   - "raw" (default): identity — the value reaches the detector untouched and
+//     the detector owns its own (often typed) bad-input. The object-bag guards
+//     (image / pdf metadata, archive entries) and the string guards whose
+//     detector type-checks itself (email). This is exactly
+//     `aggregateIssues(detect(input))`.
+//
+// A guard with a bespoke shape passes its own `function(input){ return
+// { subject } | { badInput: msg } }` instead of a name. New input shapes
+// extend the class by adding a contract, never by branching in defineGuard.
+var INPUT_CONTRACTS = {
+  text: function (input) {
+    if (typeof input === "string") return { subject: input };
+    if (Buffer.isBuffer(input)) return { subject: input.toString("utf8") };
+    return { badInput: "input is not string or Buffer" };
+  },
+  bytes: function (input) {
+    if (typeof input === "string" || Buffer.isBuffer(input)) return { subject: input };
+    return { badInput: "input is not string or Buffer" };
+  },
+  raw: function (input) { return { subject: input }; },
+};
+Object.freeze(INPUT_CONTRACTS);
+
+function resolveInputContract(contract) {
+  if (typeof contract === "function") return contract;
+  return INPUT_CONTRACTS[contract] || INPUT_CONTRACTS.text;
+}
+
 /**
  * @primitive  b.gateContract.runIssueValidator
- * @signature  b.gateContract.runIssueValidator(input, opts, detector)
+ * @signature  b.gateContract.runIssueValidator(input, opts, detector, contract?)
  * @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.
+ * The single `validate(input, opts)` engine for the whole guard family. An
+ * input contract normalizes the raw input to the subject the detector expects
+ * (or flags bad input), then the detector runs and its issues aggregate. One
+ * engine spans every input shape in the family: `"text"` (the default) coerces
+ * string / Buffer to UTF-8 and refuses anything else; `"raw"` hands the value
+ * through so an object-bag or byte-level detector owns its own bad-input
+ * (identical to `aggregateIssues(detector(input, opts))`); a guard with a
+ * bespoke shape passes its own extractor `function(input) -> { subject } |
+ * { badInput: message }`. Result `ok` is `true` only when no detected issue is
+ * `critical` / `high` severity. The `opts` argument is forwarded verbatim as
+ * the detector's second argument — its shape is detector-defined.
  *
  * @opts
- *   ...:   any,                     // detector-defined; passed through to detector(text, opts)
+ *   ...:   any,                     // detector-defined; passed through to detector(subject, opts)
  *
  * @example
  *   function detectFormulaTrigger(text) {
@@ -1481,18 +2110,16 @@ function badInputResultIfNotStringOrBuffer(input) {
  *   var ok  = b.gateContract.runIssueValidator("ada,36", {}, detectFormulaTrigger);
  *   ok.ok;                                               // → true
  */
-function runIssueValidator(input, opts, detector) {
-  var text = typeof input === "string"
-    ? input
-    : (Buffer.isBuffer(input) ? input.toString("utf8") : null);
-  if (text == null) {
+function runIssueValidator(input, opts, detector, contract) {
+  var extracted = resolveInputContract(contract)(input);
+  if (extracted && typeof extracted.badInput === "string") {
     return {
       ok: false,
       issues: [{ kind: "bad-input", severity: "high",
-                 snippet: "input is not string or Buffer" }],
+                 snippet: extracted.badInput }],
     };
   }
-  return aggregateIssues(detector(text, opts));
+  return aggregateIssues(detector(extracted.subject, opts));
 }
 
 /**
@@ -1910,8 +2537,10 @@ function _ctxValueForKind(kind, ctx, override) {
  *   errorName:            string,     // defineClass name (mutually exclusive with errorClass)
  *   errorClass:           function,   // pre-built FrameworkError subclass
  *   profiles:             object,     // PROFILES (must include strict/balanced/permissive); required
- *   defaults:             object,     // DEFAULTS baseline (default profiles.strict)
- *   postures:             object,     // COMPLIANCE_POSTURES (default ALL_STRICT_POSTURES)
+ *   defaults:             object,     // DEFAULTS baseline (default profiles.strict, or strictDefaults(profiles, defaultsOverlay) when `base` is given)
+ *   postures:             object,     // COMPLIANCE_POSTURES (default ALL_STRICT_POSTURES, or compliancePostures(profiles, { base }) when `base` is given)
+ *   base:                 number,     // forensic snippet budget — when given (and defaults/postures omitted), the factory derives both via strictDefaults + compliancePostures
+ *   defaultsOverlay:      object,     // per-guard default overrides merged into the derived strictDefaults (e.g. { maxRuntimeMs: ... }); only used with `base`
  *   mimeTypes:            string[],   // content guards only
  *   extensions:           string[],   // content guards only
  *   integrationFixtures:  object,     // INTEGRATION_FIXTURES (consumed by host harness)
@@ -1953,9 +2582,6 @@ function defineGuard(spec) {
   }
   validateOpts.requireObject(spec.profiles, "gateContract.defineGuard: profiles",
     GateContractError);
-  if (typeof spec.validate !== "function") {
-    throw _err("gate-contract/bad-opt", "defineGuard: validate must be a function");
-  }
   if (spec.errorClass && spec.errorName) {
     throw _err("gate-contract/bad-opt",
       "defineGuard: pass errorClass OR errorName, not both");
@@ -1967,8 +2593,130 @@ function defineGuard(spec) {
       spec.name.charAt(0).toUpperCase() + spec.name.slice(1) + "Error"),
       { alwaysPermanent: true });
   var profiles = spec.profiles;
-  var defaults = spec.defaults || profiles.strict || {};
-  var postures = spec.postures || ALL_STRICT_POSTURES;
+  // A guard may hand `defaults` / `postures` explicitly, OR pass `base` (the
+  // forensic snippet budget) and let the factory derive the standard config —
+  // `strictDefaults(profiles, defaultsOverlay)` + `compliancePostures(profiles,
+  // { base })` — so the guard file needn't declare the two module-vars itself.
+  var defaults = spec.defaults ||
+    (typeof spec.base === "number" ? strictDefaults(profiles, spec.defaultsOverlay)
+                                   : (profiles.strict || {}));
+  var postures = spec.postures ||
+    (typeof spec.base === "number" ? compliancePostures(profiles, { base: spec.base })
+                                   : ALL_STRICT_POSTURES);
+
+  // Dynamic guard assembly — the upstream primitive absorbs the per-guard
+  // binding wrappers. A guard may pass a raw `detect(input, opts) -> issues[]`
+  // (the guard-specific detection logic) plus an optional `sanitizeTransform(
+  // input, resolvedOpts) -> value`, instead of hand-rolling `_resolveOpts`,
+  // `validate`, and the `sanitize` resolve→detect→throw boilerplate that every
+  // guard otherwise duplicates. defineGuard already owns the profile/posture/
+  // defaults/errorClass/prefix, so it binds the resolver here and builds
+  // validate + sanitize. Behaviour matches the hand-written wrappers exactly:
+  // validate runs detect on the RAW opts (detect resolves what it needs);
+  // sanitize resolves first, then detect → throwOnRefusalSeverity → transform.
+  // The bound profile/posture resolver — built once from the spec's binding
+  // config (profiles/postures/defaults/errorClass/prefix) and EXPOSED on the
+  // guard as `resolveOpts` (below), so a bespoke gate calls
+  // `module.exports.resolveOpts(opts)` instead of each guard hand-rolling the
+  // identical `function _resolveOpts(o){ return resolveProfileAndPosture(o,
+  // {...}) }` binding wrapper. The binding config lives in ONE place.
+  var _resolveGuardOpts = function (o) {
+    return resolveProfileAndPosture(o || {}, {
+      profiles:           profiles,
+      compliancePostures: postures,
+      defaults:           defaults,
+      errorClass:         ErrorClass,
+      errCodePrefix:      prefix,
+    });
+  };
+  if (typeof spec.detect === "function") {
+    var intOpts = Array.isArray(spec.intOpts) ? spec.intOpts.slice() : null;
+    if (typeof spec.validate !== "function") {
+      spec.validate = function (input, opts) {
+        var resolved = _resolveGuardOpts(opts);
+        if (intOpts) {
+          numericBounds.requireAllPositiveFiniteIntIfPresent(resolved, intOpts,
+            spec.name + ".validate", ErrorClass, prefix + ".bad-opt");
+        }
+        // One engine, the guard's input contract picks the shape. Default
+        // "raw" reproduces the historical aggregateIssues(detect(input)) — the
+        // detector owns its own bad-input (object-bag guards image/pdf, the
+        // byte-level guards). A guard whose detector takes a string but does
+        // not type-check it (e.g. csv returns [] on a non-string) sets
+        // inputContract: "text" so non-text input is refused as bad-input.
+        return runIssueValidator(input, resolved, spec.detect,
+          spec.inputContract || "raw");
+      };
+    }
+    if (typeof spec.sanitizeTransform === "function" && typeof spec.sanitize !== "function") {
+      // spec.sanitizeSeverities narrows which severities REFUSE (throw) vs are
+      // stripped/repaired by sanitizeTransform. Default ['critical','high'];
+      // a guard that repairs high-severity findings and refuses only the
+      // unrepairable critical shapes (markdown / email / xml / yaml) passes
+      // ['critical'] so the generated sanitize matches its hand-written one.
+      // An empty array means "strip unconditionally, never refuse" (csv / text
+      // best-effort scrubbers, whose sanitize never throws on a detected issue).
+      var sanitizeSeverities = Array.isArray(spec.sanitizeSeverities)
+        ? spec.sanitizeSeverities.slice() : null;
+      var refusesOnDetect = sanitizeSeverities === null || sanitizeSeverities.length > 0;
+      // spec.sanitizeAmplificationCap (a string = the resolved-opts field name
+      // carrying the max growth ratio) opts the guard into the "sanitize must
+      // shrink, never grow" post-condition: the transform runs on extracted
+      // text and the output length is capped at ratio×input. Used by the text
+      // scrubbers (csv / text) whose hand-written sanitize threw
+      // `<prefix>.sanitize-amplified`. When unset, sanitize keeps the raw input
+      // (binary passthrough guards image / pdf must not be utf8-decoded).
+      var ampCapField = typeof spec.sanitizeAmplificationCap === "string"
+        ? spec.sanitizeAmplificationCap : null;
+      spec.sanitize = function (input, opts) {
+        var resolved = _resolveGuardOpts(opts);
+        var subject = input;
+        if (ampCapField) {
+          // Same text contract the validate engine uses — string/Buffer→text,
+          // refuse anything else (here as a throw, sanitize's contract).
+          var extracted = INPUT_CONTRACTS.text(input);
+          if (extracted.badInput) {
+            throw ErrorClass.factory(prefix + ".bad-input",
+              "sanitize requires string or Buffer input");
+          }
+          subject = extracted.subject;
+        }
+        if (refusesOnDetect) {
+          var issues = spec.detect(subject, resolved);
+          // A `bad-input` issue means the input is UNPROCESSABLE (wrong type /
+          // shape), not a content finding — a scrubber must never let it slip
+          // into the transform (which would return the garbage verbatim). So it
+          // refuses ALWAYS, independent of which CONTENT severities this guard's
+          // sanitize tolerates via sanitizeSeverities. (csv/text reach the same
+          // refusal earlier through the ampCapField text contract above.)
+          for (var bi = 0; bi < issues.length; bi += 1) {
+            if (issues[bi].kind === "bad-input") {
+              throw ErrorClass.factory(prefix + ".bad-input",
+                issues[bi].snippet || "sanitize: input is not processable");
+            }
+          }
+          var throwOpts = { errorClass: ErrorClass, codePrefix: prefix };
+          if (sanitizeSeverities) throwOpts.severities = sanitizeSeverities;
+          throwOnRefusalSeverity(issues, throwOpts);
+        }
+        var out = spec.sanitizeTransform(subject, resolved);
+        if (ampCapField) {
+          var cap = resolved[ampCapField];
+          if (typeof cap === "number") {
+            var amp = out.length / Math.max(subject.length, 1);
+            if (amp > cap) {
+              throw ErrorClass.factory(prefix + ".sanitize-amplified",
+                "sanitize grew output " + amp.toFixed(2) + "x; cap " + cap);
+            }
+          }
+        }
+        return out;
+      };
+    }
+  }
+  if (typeof spec.validate !== "function") {
+    throw _err("gate-contract/bad-opt", "defineGuard: validate (or detect) must be a function");
+  }
 
   var buildProfileFn = makeProfileBuilder(profiles);
   function compliancePostureFn(name) {
@@ -2012,12 +2760,7 @@ function defineGuard(spec) {
       var value = _ctxValueForKind(spec.kind, ctx, ctxFields);
       if (!value) return { ok: true, action: "serve" };
       var rv = spec.validate(value, opts);
-      if (!rv.issues || rv.issues.length === 0) return { ok: true, action: "serve" };
-      var hasBlocking = rv.issues.some(function (i) {
-        return i.severity === "critical" || i.severity === "high";
-      });
-      if (!hasBlocking) return { ok: true, action: "audit-only", issues: rv.issues };
-      return { ok: false, action: "refuse", issues: rv.issues };
+      return severityDisposition(rv.issues || []);
     };
     return buildGuardGate(
       opts.name || (gateNamePrefix + ":" + (opts.profile || "default")),
@@ -2031,6 +2774,7 @@ function defineGuard(spec) {
     NAME:                spec.name,
     KIND:                spec.kind,
     validate:            spec.validate,
+    resolveOpts:         _resolveGuardOpts,
     buildProfile:        buildProfileFn,
     compliancePosture:   compliancePostureFn,
     loadRulePack:        rulePacks.load,
@@ -2259,6 +3003,81 @@ function defineParser(spec) {
  *   decision.action;                                     // → "serve" | "refuse" | …
  */
 
+/**
+ * @abiTemplate defineGuard
+ * @method      validate
+ * @signature   b.{NS}.validate(input, opts?)
+ * @status      stable
+ * @related     b.{NS}.gate, b.{NS}.sanitize
+ *
+ * Inspect `input` under a resolved profile + compliance posture and return a
+ * structured result `{ ok, issues }` WITHOUT throwing — `ok` is false when any
+ * `high` / `critical` issue fired, and `issues` lists every finding (kind,
+ * severity, ruleId, snippet). `opts` selects the `profile` /
+ * `compliancePosture`; omitted opts use this guard's default profile. Wired by
+ * `gateContract.defineGuard` from the guard's detection logic through
+ * `gateContract.aggregateIssues`, so the result shape and severity gating are
+ * identical across the guard family.
+ *
+ * @opts
+ *   profile:           string,    // one of PROFILES; default this guard's default
+ *   compliancePosture: string,    // overlay one of hipaa/pci-dss/gdpr/soc2
+ *
+ * @example
+ *   var rv = b.{NS}.validate(input, { profile: "strict" });
+ *   rv.ok;                                               // → true | false
+ *   rv.issues;                                           // → [ { kind, severity, … }, … ]
+ */
+
+/**
+ * @abiTemplate defineGuard
+ * @method      sanitize
+ * @signature   b.{NS}.sanitize(input, opts?)
+ * @status      stable
+ * @related     b.{NS}.validate, b.{NS}.gate
+ *
+ * Return a normalized form of `input` when no `high` / `critical` issue fires;
+ * throw `{ERR}` on any such refusal (best-effort repair, never a silent pass).
+ * Resolves the profile + posture, runs the guard's detection, throws via
+ * `gateContract.throwOnRefusalSeverity` on a refusal, then applies the guard's
+ * own safe transform. Wired by `gateContract.defineGuard`, so the
+ * resolve → detect → throw → transform order is identical across the family; a
+ * guard with no safe transform ships no `sanitize`.
+ *
+ * @opts
+ *   profile:           string,    // one of PROFILES; default this guard's default
+ *   compliancePosture: string,    // overlay one of hipaa/pci-dss/gdpr/soc2
+ *
+ * @example
+ *   var safe = b.{NS}.sanitize(input, { profile: "permissive" });
+ *   safe;                                                // → normalized value
+ */
+
+/**
+ * @abiTemplate defineGuard
+ * @method      resolveOpts
+ * @signature   b.{NS}.resolveOpts(opts?)
+ * @status      stable
+ * @related     b.{NS}.validate, b.{NS}.gate
+ *
+ * Resolve caller `opts` against this guard's `PROFILES` + compliance-posture
+ * overlays into the fully-defaulted option set the guard runs on — the same
+ * resolution `validate` / `sanitize` / `gate` apply internally. Wired by
+ * `gateContract.defineGuard` from the guard's binding config (profiles /
+ * postures / defaults / error class), so a guard's bespoke `gate` calls
+ * `resolveOpts` instead of re-declaring the per-guard resolver wrapper. Throws
+ * `{ERR}` with code `"{CODE}.bad-opt"` / `"{CODE}.bad-posture"` on an unknown
+ * profile or posture name.
+ *
+ * @opts
+ *   profile:           string,    // one of PROFILES; default this guard's default
+ *   compliancePosture: string,    // overlay one of hipaa/pci-dss/gdpr/soc2
+ *
+ * @example
+ *   var resolved = b.{NS}.resolveOpts({ profile: "strict" });
+ *   resolved.profile;                                    // → "strict"
+ */
+
 /**
  * @abiTemplate defineParser
  * @method      compliancePosture
@@ -2300,12 +3119,24 @@ module.exports = {
   resolveProfileAndPosture: resolveProfileAndPosture,
   runIssueValidator:  runIssueValidator,
   buildGuardGate:     buildGuardGate,
+  severityDisposition: severityDisposition,
+  buildContentGate:   buildContentGate,
+  policyDisposition:  policyDisposition,
+  charThreatDisposition: charThreatDisposition,
   extractBytesAsText: extractBytesAsText,
   lookupCompliancePosture: lookupCompliancePosture,
   ALL_STRICT_POSTURES: ALL_STRICT_POSTURES,
+  CHAR_THREATS_REJECT_ALL: CHAR_THREATS_REJECT_ALL,
+  DANGEROUS_URL_SCHEMES: DANGEROUS_URL_SCHEMES,
+  SAFE_URL_SCHEMES:   SAFE_URL_SCHEMES,
+  identifierFixtures: identifierFixtures,
+  compliancePostures: compliancePostures,
+  strictDefaults:     strictDefaults,
+  detectStringInput:  detectStringInput,
   makeRulePackLoader: makeRulePackLoader,
   makeProfileBuilder: makeProfileBuilder,
   makeProfileResolver: makeProfileResolver,
+  resolveProfileName: resolveProfileName,
   throwOnRefusalSeverity: throwOnRefusalSeverity,
   badInputResultIfNotStringOrBuffer: badInputResultIfNotStringOrBuffer,
   aggregateIssues:    aggregateIssues,