@blamejs/core 0.14.26 → 0.15.0

package/lib/gate-contract.js

@@ -50,10 +50,16 @@ var bCrypto = require("./crypto");
 var lazyRequire = require("./lazy-require");
 var safeAsync = require("./safe-async");
 var validateOpts = require("./validate-opts");
-var { GateContractError } = require("./framework-error");
+var { GateContractError, defineClass } = require("./framework-error");
 
 var observability = lazyRequire(function () { return require("./observability"); });
 var compliance = lazyRequire(function () { return require("./compliance"); });
+var audit = lazyRequire(function () { return require("./audit"); });
+
+// One-time dedupe for the "global posture pinned but this guard maps no
+// overlay" warning. Keyed `<posture>::<errCodePrefix>` so each guard
+// family surfaces the gap once instead of on every gate construction.
+var _unmappedPostureWarned = Object.create(null);
 
 // Forensic-id token width (bytes); 64 bits is enough for cross-gate
 // correlation in a single request scope.
@@ -1096,6 +1102,153 @@ function lookupCompliancePosture(name, postures, errorFactory, codePrefix) {
   return Object.assign({}, postures[name]);
 }
 
+// "GuardCidrError" -> "guardCidr" — the guard's audit/message identity, derived
+// once from its error class name. Used for the default gate's audit/metric
+// prefix AND the profile resolver's error message, so neither re-cases the name.
+function _guardLabelFromError(ErrorClass) {
+  var n = String(ErrorClass.name).replace(/Error$/, "");
+  return n.charAt(0).toLowerCase() + n.slice(1);
+}
+
+/**
+ * @primitive  b.gateContract.makeProfileResolver
+ * @signature  b.gateContract.makeProfileResolver(cfg)
+ * @since      0.15.0
+ * @status     stable
+ * @related    b.gateContract.makeProfileBuilder, b.gateContract.lookupCompliancePosture
+ *
+ * Closes over a guard's profile config and returns a `resolveProfile(opts)`
+ * function: maps `opts.posture` through the compliance-posture table, else
+ * falls back to `opts.profile || cfg.defaults`, validates the name against
+ * `cfg.profiles`, and throws `cfg.errorClass.factory(cfg.codePrefix +
+ * "/bad-profile")` on an unknown name. The sibling of `makeProfileBuilder` /
+ * `makeRulePackLoader` / `lookupCompliancePosture` for the resolution step —
+ * every `defineParser`-shaped line-protocol / mail / agent guard reuses it
+ * instead of re-declaring an identical `_resolveProfile`.
+ *
+ * @opts
+ *   profiles:   object,    // the guard's PROFILES map; required
+ *   postures:   object,    // COMPLIANCE_POSTURES (posture -> profile name)
+ *   defaults:   string,    // fallback profile name when no posture/profile given
+ *   errorClass: function,  // the guard's FrameworkError subclass
+ *   codePrefix: string,    // error-code namespace (e.g. "mail-compose")
+ *   byObject:   boolean,   // true -> return the profile config object, not its name
+ *
+ * @example
+ *   var resolveProfile = b.gateContract.makeProfileResolver({
+ *     profiles: PROFILES, postures: COMPLIANCE_POSTURES,
+ *     defaults: "strict", errorClass: GuardMailComposeError,
+ *     codePrefix: "mail-compose",
+ *   });
+ *   resolveProfile({ posture: "hipaa" });   // → "strict"
+ */
+function makeProfileResolver(cfg) {
+  var profiles   = cfg.profiles;
+  var postures   = cfg.postures;
+  var dft        = cfg.defaults;
+  var ErrorClass = cfg.errorClass;
+  var codePrefix = cfg.codePrefix;
+  var byObject   = cfg.byObject === true;
+  var label      = _guardLabelFromError(ErrorClass);
+  return function resolveProfile(opts) {
+    opts = opts || {};
+    if (opts.posture && postures && postures[opts.posture]) {
+      var pn = postures[opts.posture];
+      return byObject ? profiles[pn] : pn;
+    }
+    var p = opts.profile || dft;
+    if (!profiles[p]) {
+      throw ErrorClass.factory(codePrefix + "/bad-profile",
+        label + ": unknown profile '" + p + "' (use " +
+        Object.keys(profiles).join(" / ") + ")");
+    }
+    return byObject ? profiles[p] : p;
+  };
+}
+
+/**
+ * @primitive  b.gateContract.throwOnRefusalSeverity
+ * @signature  b.gateContract.throwOnRefusalSeverity(issues, cfg)
+ * @since      0.15.0
+ * @status     stable
+ * @related    b.gateContract.aggregateIssues, b.gateContract.makeProfileResolver
+ *
+ * Throw on the first critical/high-severity issue in a detector's issue
+ * list — the refusal step every guard `sanitize` runs after detection
+ * (sanitize can serve a clean value but never repair a critical/high
+ * finding). Builds the guard's error via `cfg.errorClass.factory` with code
+ * `issue.ruleId || (cfg.codePrefix + ".refused")` and message
+ * `guard<Name>.<op>: <issue.snippet>` (op default `"sanitize"`; the guard
+ * identity derives from the error class name). The throw sibling of
+ * `aggregateIssues` (which returns `{ ok, issues }` instead of throwing) —
+ * replaces the per-guard hand-rolled severity-gating loop.
+ *
+ * @opts
+ *   errorClass: function,  // the guard's FrameworkError subclass; required
+ *   codePrefix: string,    // error-code namespace; the `.refused` fallback code
+ *   op:         string,    // operation name in the message (default "sanitize")
+ *   severities: string[],  // refusal severities (default ["critical","high"])
+ *
+ * @example
+ *   var issues = detect(input, opts);
+ *   b.gateContract.throwOnRefusalSeverity(issues, {
+ *     errorClass: GuardCidrError, codePrefix: "cidr",
+ *   });
+ *   // throws GuardCidrError(ruleId || "cidr.refused", "guardCidr.sanitize: " + snippet)
+ *   // on the first critical/high issue
+ */
+function throwOnRefusalSeverity(issues, cfg) {
+  var errFactory = cfg.errorClass.factory;
+  var prefix = _guardLabelFromError(cfg.errorClass) + "." + (cfg.op || "sanitize");
+  var fallback = cfg.codePrefix + ".refused";
+  // Default refuses critical + high; cfg.severities narrows it (e.g.
+  // ["critical"] for guards that strip high-severity findings but refuse
+  // only unrepairable critical shapes — email / markdown / xml / yaml).
+  var severities = cfg.severities || ["critical", "high"];
+  for (var i = 0; i < issues.length; i += 1) {
+    var iss = issues[i];
+    if (severities.indexOf(iss.severity) !== -1) {
+      throw errFactory(iss.ruleId || fallback, prefix + ": " + iss.snippet);
+    }
+  }
+}
+
+/**
+ * @primitive  b.gateContract.ALL_STRICT_POSTURES
+ * @signature  b.gateContract.ALL_STRICT_POSTURES
+ * @since      0.15.0
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.gateContract.lookupCompliancePosture, b.gateContract.makeProfileBuilder
+ *
+ * Canonical strict-all `COMPLIANCE_POSTURES` map every command/parser
+ * guard composes. Maps each of the four baseline regulatory postures —
+ * `hipaa` / `pci-dss` / `gdpr` / `soc2` — onto the guard's `strict`
+ * profile name. Guards whose four postures all resolve to `strict`
+ * (the command/protocol validators: POP3 / IMAP / SMTP / ManageSieve
+ * commands, mail-compose / query / sieve / move / reply, the envelope
+ * and event-bus shapes, the mail pipeline scorers, and the
+ * `safe-*` line-protocol parsers) reference this single frozen object
+ * instead of re-declaring it. Guards that overlay per-posture
+ * byte-limits or redaction flags (the content guards: CSV / HTML /
+ * JSON / XML / YAML / JWT / OAuth / template, etc.) keep their own
+ * posture map and do not compose this.
+ *
+ * Frozen once and shared by reference: every consumer reads it through
+ * its own `COMPLIANCE_POSTURES` binding and never mutates it.
+ *
+ * @example
+ *   var COMPLIANCE_POSTURES = b.gateContract.ALL_STRICT_POSTURES;
+ *   COMPLIANCE_POSTURES.hipaa;                            // → "strict"
+ *   Object.isFrozen(COMPLIANCE_POSTURES);                 // → true
+ */
+var ALL_STRICT_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
 /**
  * @primitive  b.gateContract.makeRulePackLoader
  * @signature  b.gateContract.makeRulePackLoader(errorClass, codePrefix)
@@ -1415,6 +1568,16 @@ function resolveProfileAndPosture(opts, cfg) {
     if (typeof globalPosture === "string" &&
         cfg.compliancePostures && cfg.compliancePostures[globalPosture]) {
       posture = globalPosture;
+    } else if (typeof globalPosture === "string" && globalPosture.length > 0) {
+      // A global posture IS pinned, but this guard family ships no
+      // COMPLIANCE_POSTURES overlay for it (e.g. fedramp-rev5-moderate
+      // against a guard whose table only covers hipaa/pci-dss/gdpr/soc2).
+      // Falling through to the unposture-d default is the SAFE behavior,
+      // but operators must know the posture is a no-op for THIS guard —
+      // silently no-oping reads as "enforced" (compliance theater).
+      // Emit a one-time, grep-able audit warning per (posture, guard)
+      // and keep the safe default.
+      _warnUnmappedPosture(globalPosture, prefix);
     }
   }
   if (typeof posture === "string") {
@@ -1427,6 +1590,42 @@ function resolveProfileAndPosture(opts, cfg) {
   return Object.assign({}, cfg.defaults || {}, overlay, opts);
 }
 
+// _warnUnmappedPosture — emit a one-time, grep-able audit warning that a
+// globally-pinned posture has no overlay in THIS guard family's
+// COMPLIANCE_POSTURES table, so the operator doesn't read the
+// safe-default fall-through as "the posture is enforced here." Drop-
+// silent (hot-path observability sink): a warning emit must never throw
+// past the guard-gate construction that triggered it.
+function _warnUnmappedPosture(posture, prefix) {
+  var dedupeKey = posture + "::" + (prefix || "guard");
+  if (_unmappedPostureWarned[dedupeKey]) return;
+  _unmappedPostureWarned[dedupeKey] = true;
+  try {
+    // Canonical audit outcome triple is success/failure/denied; a
+    // posture that maps no overlay is an advisory NOTICE, not a failure
+    // of this construction — the severity rides in metadata.severity so
+    // the audit row carries the warning intent without abusing outcome.
+    audit().safeEmit({
+      action:  "gateContract.posture.unmapped",
+      outcome: "success",
+      metadata: {
+        severity: "warning",
+        posture:  posture,
+        guard:    prefix || "guard",
+        recommendation: "The pinned compliance posture '" + posture +
+          "' has no overlay in this guard's COMPLIANCE_POSTURES table, so " +
+          "its gate runs the unposture-d default. Pass an explicit " +
+          "compliancePosture this guard maps, or add the overlay, if the " +
+          "posture is meant to tighten this surface.",
+      },
+    });
+  } catch (_e) { /* drop-silent — warning must not break gate construction */ }
+}
+
+function _resetForTest() {
+  for (var k in _unmappedPostureWarned) delete _unmappedPostureWarned[k];
+}
+
 /**
  * @primitive  b.gateContract.buildProfile
  * @signature  b.gateContract.buildProfile(opts)
@@ -1628,8 +1827,453 @@ function composeHooks(hooks) {
   };
 }
 
+// ---- Guard-module factories ----
+//
+// Every b.guard* primitive of the gate-bearing kinds (content / filename
+// / identifier) hand-wires the SAME export surface: an error class, a
+// resolveProfileAndPosture-backed _resolveOpts, a buildGuardGate-backed
+// gate, a makeProfileBuilder-backed buildProfile, a
+// lookupCompliancePosture-backed compliancePosture, a makeRulePackLoader-
+// backed loadRulePack, and a frozen module.exports carrying the
+// guard-* registry fields (NAME / KIND / MIME_TYPES / EXTENSIONS /
+// PROFILES / DEFAULTS / COMPLIANCE_POSTURES / INTEGRATION_FIXTURES) plus
+// the per-guard inspection surface (validate / sanitize / gate). They
+// differ only in the per-guard inspection LOGIC + the PROFILES /
+// COMPLIANCE_POSTURES / DEFAULTS tables. `defineGuard` assembles the
+// boilerplate; the spec injects the logic and the tables.
+//
+// `defineParser` is the sibling for the minimal command / line-protocol
+// / safe-* parser shape — the guards whose four postures all resolve to
+// `strict` (ALL_STRICT_POSTURES) and whose surface is a self-contained
+// `validate` / `parse` plus a `compliancePosture(name)` that returns the
+// effective PROFILE NAME (or null) rather than an overlay clone. Those
+// guards carry no gate / buildProfile / loadRulePack, so forcing them
+// through `defineGuard` would be a leaky abstraction.
+
+// _KIND_CTX_FIELDS — per-KIND ordered list of ctx field names a
+// buildGuardGate-backed default gate reads, mirroring the hand-written
+// gate bodies: filename reads ctx.filename || ctx.name, identifier reads
+// ctx.identifier || ctx.token || ctx.jwt, command reads ctx.line ||
+// ctx.command. content has no entry — it falls through to
+// extractBytesAsText (the ctx.bytes string/Buffer normalizer).
+var _KIND_CTX_FIELDS = Object.freeze({
+  filename:   ["filename", "name"],
+  identifier: ["identifier", "token", "jwt"],
+  command:    ["line", "command"],
+});
+
+// override (when given) replaces the per-KIND field table — lets a guard whose
+// gate is the standard chain but reads a custom ctx field take the default gate.
+function _ctxValueForKind(kind, ctx, override) {
+  ctx = ctx || {};
+  var fields = override || _KIND_CTX_FIELDS[kind];
+  if (!fields) return extractBytesAsText(ctx);   // content (default)
+  for (var i = 0; i < fields.length; i += 1) {
+    if (ctx[fields[i]]) return ctx[fields[i]];
+  }
+  return "";
+}
+
+/**
+ * @primitive  b.gateContract.defineGuard
+ * @signature  b.gateContract.defineGuard(spec)
+ * @since      0.15.0
+ * @status     stable
+ * @related    b.gateContract.defineParser, b.gateContract.buildGuardGate, b.gateContract.resolveProfileAndPosture
+ *
+ * Assemble a complete `b.guard*` module from a spec. Mints the per-guard
+ * error class (via `framework-error.defineClass`, or accepts a supplied
+ * `errorClass`), wires `resolveProfileAndPosture` / `buildGuardGate` /
+ * `makeProfileBuilder` / `lookupCompliancePosture` / `makeRulePackLoader`,
+ * and returns the frozen module.exports object every guard ships —
+ * `NAME` / `KIND` / `PROFILES` / `DEFAULTS` / `COMPLIANCE_POSTURES` /
+ * `INTEGRATION_FIXTURES` / `validate` / `sanitize?` / `gate?` /
+ * `buildProfile` / `compliancePosture` / `loadRulePack` plus the spec's
+ * `extra` exports (verb tables, `escapeCell`, `schema`, `kidSafe`, …) and
+ * the error class under its own name.
+ *
+ * The per-guard inspection logic is INJECTED, not abstracted: `validate`
+ * / `sanitize` / `gate` are spec functions that close over the resolved
+ * opts. A guard whose `gate` body is the standard
+ * serve→audit-only→sanitize→refuse chain can omit `spec.gate` and take
+ * the factory default (built from `spec.validate` + `spec.sanitize` per
+ * KIND); a guard with a bespoke gate (CSV's sanitize-reparse-reserialize,
+ * filename's per-policy canSanitize matrix) passes its own. Behavior is
+ * preserved byte-for-byte because the genuinely-divergent code stays
+ * verbatim in the spec — the factory only removes the wiring every guard
+ * copies.
+ *
+ * @opts
+ *   name:                 string,     // NAME (e.g. "csv"); required
+ *   kind:                 string,     // "content"|"filename"|"identifier"|"command" for the default gate; any non-empty label with a bespoke spec.gate; required
+ *   errCodePrefix:        string,     // error-code namespace (default name)
+ *   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)
+ *   mimeTypes:            string[],   // content guards only
+ *   extensions:           string[],   // content guards only
+ *   integrationFixtures:  object,     // INTEGRATION_FIXTURES (consumed by host harness)
+ *   validate:             function,   // (input, resolvedOpts) -> { ok, issues }; required
+ *   sanitize:             function,   // (input, resolvedOpts) -> cleaned (optional)
+ *   gate:                 function,   // (resolvedOpts) -> async (ctx) -> decision (optional; default built per kind)
+ *   ctxFields:            string[],   // ordered ctx field names the default gate reads (overrides the per-KIND table; e.g. ["identifier","cidr"])
+ *   defaultGateCheck:     function,   // override the default gate's per-ctx check
+ *   extra:                object,     // additional exports merged verbatim into module.exports
+ *
+ * @example
+ *   module.exports = b.gateContract.defineGuard({
+ *     name: "csv", kind: "content", errorClass: GuardCsvError,
+ *     profiles: PROFILES, defaults: DEFAULTS, postures: COMPLIANCE_POSTURES,
+ *     mimeTypes: ["text/csv"], extensions: [".csv"],
+ *     integrationFixtures: INTEGRATION_FIXTURES,
+ *     validate: validate, sanitize: sanitize, gate: gate,
+ *     extra: { serialize: serialize, escapeCell: escapeCell, schema: schema },
+ *   });
+ */
+function defineGuard(spec) {
+  validateOpts.requireObject(spec, "gateContract.defineGuard", GateContractError);
+  validateOpts.requireNonEmptyString(spec.name, "gateContract.defineGuard: name",
+    GateContractError, "gate-contract/bad-opt");
+  validateOpts.requireNonEmptyString(spec.kind, "gateContract.defineGuard: kind",
+    GateContractError, "gate-contract/bad-opt");
+  // The four known kinds drive the default gate's ctx-field dispatch
+  // (_ctxValueForKind). A guard with a bespoke spec.gate reads its own ctx
+  // fields, so any non-empty kind is allowed there — the kind is then just
+  // the KIND export label (e.g. "oauth-flow" / "graphql-request" / "sql" /
+  // "metadata"). A custom kind WITHOUT a bespoke gate is refused, because
+  // the default gate could not dispatch it to the right ctx field.
+  if (["content", "filename", "identifier", "command"].indexOf(spec.kind) === -1 &&
+      typeof spec.gate !== "function") {
+    throw _err("gate-contract/bad-opt",
+      "defineGuard: kind must be content|filename|identifier|command for the " +
+      "default gate, got " + JSON.stringify(spec.kind) +
+      " — pass spec.gate for a custom kind (the bespoke gate reads its own ctx fields)");
+  }
+  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");
+  }
+
+  var prefix = spec.errCodePrefix || spec.name;
+  var ErrorClass = spec.errorClass ||
+    defineClass(spec.errorName || ("Guard" +
+      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;
+
+  var buildProfileFn = makeProfileBuilder(profiles);
+  function compliancePostureFn(name) {
+    return lookupCompliancePosture(name, postures, ErrorClass.factory, prefix);
+  }
+  var rulePacks = makeRulePackLoader(ErrorClass, prefix);
+
+  // spec.ctxFields (ordered field names) overrides the per-KIND table that
+  // the default gate's _ctxValueForKind reads — lets a guard whose gate is the
+  // standard chain but reads a custom ctx field (e.g. ctx.cidr) drop its
+  // bespoke gate and take the default. null -> _ctxValueForKind uses the
+  // per-KIND table.
+  var ctxFields = Array.isArray(spec.ctxFields) ? spec.ctxFields.slice() : null;
+  // Gate identity is surfaced in audit events / metric counters / cache keys.
+  // Preserve the "guard<Name>:profile" naming the hand-written gates used so
+  // moving a guard onto the default gate does not rename its audit/metric
+  // stream (e.g. "guardCidr:strict"), via the shared error-name derivation.
+  var gateNamePrefix = _guardLabelFromError(ErrorClass);
+
+  // Default gate — the standard serve→audit-only→refuse chain, dispatched
+  // to the right ctx field by KIND (or spec.ctxFields). Guards with a bespoke
+  // gate pass spec.gate; guards whose gate is the standard chain take this
+  // default.
+  // Raw opts pass straight through to spec.validate and buildGuardGate —
+  // matching the hand-written gates, whose validate resolves profile/posture
+  // internally (validate calls its own _resolveOpts). Pre-resolving here
+  // would double-resolve.
+  function defaultGate(opts) {
+    opts = opts || {};
+    var perCtx = spec.defaultGateCheck || function (ctx) {
+      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 buildGuardGate(
+      opts.name || (gateNamePrefix + ":" + (opts.profile || "default")),
+      opts,
+      async function (ctx) { return perCtx(ctx, opts); });
+  }
+
+  var gateFn = spec.gate || defaultGate;
+
+  var out = {
+    NAME:                spec.name,
+    KIND:                spec.kind,
+    validate:            spec.validate,
+    buildProfile:        buildProfileFn,
+    compliancePosture:   compliancePostureFn,
+    loadRulePack:        rulePacks.load,
+    PROFILES:            profiles,
+    DEFAULTS:            defaults,
+    COMPLIANCE_POSTURES: postures,
+  };
+  if (spec.kind === "content") {
+    out.MIME_TYPES = Object.freeze((spec.mimeTypes || []).slice());
+    out.EXTENSIONS = Object.freeze((spec.extensions || []).slice());
+  }
+  if (spec.integrationFixtures) out.INTEGRATION_FIXTURES = spec.integrationFixtures;
+  if (typeof spec.sanitize === "function") out.sanitize = spec.sanitize;
+  out.gate = gateFn;
+  // Error class exported under its own constructor name (GuardCsvError etc.)
+  out[ErrorClass.name] = ErrorClass;
+  // Per-guard extras (verb tables, escapeCell, schema, kidSafe, …) merged
+  // verbatim via the prototype-safe own-enumerable copy (no computed-name
+  // write; __proto__/constructor/prototype are skipped). Extras win over
+  // factory defaults only when the guard explicitly re-exports a shared
+  // name (rare; documented per guard).
+  if (spec.extra) validateOpts.assignOwnEnumerable(out, spec.extra);
+  return out;
+}
+
+/**
+ * @primitive  b.gateContract.defineParser
+ * @signature  b.gateContract.defineParser(spec)
+ * @since      0.15.0
+ * @status     stable
+ * @related    b.gateContract.defineGuard, b.gateContract.ALL_STRICT_POSTURES
+ *
+ * Assemble the minimal command / line-protocol / `safe-*` parser module
+ * shape — guards whose four compliance postures all resolve to `strict`
+ * (composing `ALL_STRICT_POSTURES`) and whose surface is a single
+ * self-contained `validate` / `parse` entry point plus a
+ * `compliancePosture(name)` that returns the effective PROFILE NAME (or
+ * `null` for unknown names) rather than an overlay clone. These guards
+ * carry no `gate` / `buildProfile` / `loadRulePack`, so `defineGuard`'s
+ * full assembly would be wrong for them.
+ *
+ * Mints the error class (or accepts one), exposes the spec's primary
+ * entry point under `spec.entryName` (default `"validate"`), and returns
+ * the frozen module.exports with `PROFILES` / `COMPLIANCE_POSTURES` /
+ * `compliancePosture` plus the spec's `extra` exports and the error
+ * class.
+ *
+ * @opts
+ *   name:        string,     // module identity / error-name stem; required
+ *   entry:       function,   // the validate/parse entry point; required
+ *   entryName:   string,     // export key for the entry (default "validate")
+ *   profiles:    object,     // PROFILES; required
+ *   postures:    object,     // COMPLIANCE_POSTURES (default ALL_STRICT_POSTURES)
+ *   errorClass:  function,   // pre-built FrameworkError subclass
+ *   errorName:   string,     // defineClass name (mutually exclusive with errorClass)
+ *   extra:       object,     // additional exports (verb tables, KNOWN_*, …)
+ *
+ * @example
+ *   module.exports = b.gateContract.defineParser({
+ *     name: "pop3-command", entry: validate,
+ *     errorClass: GuardPop3CommandError,
+ *     profiles: PROFILES, postures: COMPLIANCE_POSTURES,
+ *     extra: { KNOWN_VERBS: KNOWN_VERBS, ZERO_ARG_VERBS: ZERO_ARG_VERBS },
+ *   });
+ */
+function defineParser(spec) {
+  validateOpts.requireObject(spec, "gateContract.defineParser", GateContractError);
+  validateOpts.requireNonEmptyString(spec.name, "gateContract.defineParser: name",
+    GateContractError, "gate-contract/bad-opt");
+  if (typeof spec.entry !== "function") {
+    throw _err("gate-contract/bad-opt", "defineParser: entry must be a function");
+  }
+  validateOpts.requireObject(spec.profiles, "gateContract.defineParser: profiles",
+    GateContractError);
+  if (spec.errorClass && spec.errorName) {
+    throw _err("gate-contract/bad-opt",
+      "defineParser: pass errorClass OR errorName, not both");
+  }
+  var ErrorClass = spec.errorClass ||
+    defineClass(spec.errorName || ("Guard" +
+      spec.name.charAt(0).toUpperCase() + spec.name.slice(1) + "Error"),
+      { alwaysPermanent: true });
+  var postures = spec.postures || ALL_STRICT_POSTURES;
+
+  function compliancePostureFn(name) {
+    return postures[name] || null;
+  }
+
+  var out = {
+    compliancePosture:   compliancePostureFn,
+    PROFILES:            spec.profiles,
+    COMPLIANCE_POSTURES: postures,
+  };
+  out[spec.entryName || "validate"] = spec.entry;
+  out[ErrorClass.name] = ErrorClass;
+  if (spec.extra) validateOpts.assignOwnEnumerable(out, spec.extra);
+  return out;
+}
+
+// ---- ABI doc templates (single-sourced; rendered per guard) ----
+//
+// Every guard built through `defineGuard` / `defineParser` exposes the
+// SAME factory-generated ABI methods (`compliancePosture` and, for
+// `defineGuard`, `buildProfile` / `loadRulePack` / a default `gate`).
+// Those methods have no per-guard `function` declaration — the factory
+// wires them — so a refactored guard that wants its wiki page to keep
+// listing them used to carry a floating `@primitive` block per method,
+// duplicating the same prose across every member of the family.
+//
+// The `@abiTemplate` blocks below are the ONE copy of that prose. The
+// wiki parser (`examples/wiki/lib/source-doc-parser.js`) collects them
+// into a per-factory template bucket (keyed `defineGuard` / `defineParser`)
+// instead of the gateContract primitive list, and the page generator
+// (`examples/wiki/lib/page-generator.js`) instantiates them per guard —
+// substituting `{NS}` (the guard namespace, e.g. `guardCsv`) and `{ERR}`
+// (its error class, e.g. `GuardCsvError`) and filling `@since` from the
+// guard's own `@module` / first-primitive metadata — so each guard's page
+// renders every ABI method with usage correct for THAT guard. The
+// duplicated prose collapses to a single source; the rendered surface is
+// unchanged. A guard that keeps a bespoke per-method block (a custom
+// `gate`, or a guard that documents its own `compliancePosture`) wins —
+// the page generator skips the template for any method already present.
+//
+// These blocks intentionally carry the placeholder primitive form
+// `b.{NS}.<method>` and placeholder-bearing `@example` bodies; the
+// validator routes them through its template-shape pass, not the
+// resolvable-primitive pass.
+
+/**
+ * @abiTemplate defineGuard
+ * @method      compliancePosture
+ * @signature   b.{NS}.compliancePosture(name)
+ * @status      stable
+ * @compliance  hipaa, pci-dss, gdpr, soc2
+ * @related     b.{NS}.gate, b.{NS}.buildProfile
+ *
+ * Look up a compliance-posture overlay by name (one of `"hipaa"` /
+ * `"pci-dss"` / `"gdpr"` / `"soc2"`). Returns a fresh clone of the
+ * posture overlay so the caller may mutate it freely without disturbing
+ * the shared table. Throws `{ERR}` with code `"{CODE}.bad-posture"` when
+ * the name is not one this guard maps. Wired by `gateContract.defineGuard`
+ * through `gateContract.lookupCompliancePosture`, so the clone semantics
+ * and error code are identical across every guard in the family.
+ *
+ * @example
+ *   var posture = b.{NS}.compliancePosture("hipaa");
+ *   posture;                                             // → overlay clone (mutable)
+ *
+ *   try {
+ *     b.{NS}.compliancePosture("not-a-regime");
+ *   } catch (e) {
+ *     e.code;                                            // → "{CODE}.bad-posture"
+ *   }
+ */
+
+/**
+ * @abiTemplate defineGuard
+ * @method      buildProfile
+ * @signature   b.{NS}.buildProfile(opts)
+ * @status      stable
+ * @related     b.{NS}.gate, b.{NS}.compliancePosture
+ *
+ * Compose a derived profile from one or more named bases plus inline
+ * overrides, resolving names through this guard's own `PROFILES` table.
+ * `opts.extends` is a base profile name (`"strict"` / `"balanced"` /
+ * `"permissive"`) or an array of names — later entries shadow earlier
+ * ones, and inline `opts` keys win last. Wired by
+ * `gateContract.defineGuard` through `gateContract.makeProfileBuilder`,
+ * so operator-defined profiles stay traceable to a baseline instead of a
+ * hand-typed dictionary.
+ *
+ * @opts
+ *   extends:   string|string[],   // base profile name(s) to compose
+ *   ...:       any guard key,      // inline override of resolved keys
+ *
+ * @example
+ *   var custom = b.{NS}.buildProfile({ extends: "strict" });
+ *   custom;                                              // → composed profile object
+ */
+
+/**
+ * @abiTemplate defineGuard
+ * @method      loadRulePack
+ * @signature   b.{NS}.loadRulePack(pack)
+ * @status      stable
+ * @related     b.{NS}.gate
+ *
+ * Register an operator-supplied rule pack with this guard's rule-pack
+ * registry. The pack is identified by `pack.id` (a non-empty string) and
+ * stored for later dispatch by gates that opt in via `opts.rulePackId`.
+ * Returns the pack unchanged on success; throws `{ERR}` with code
+ * `"{CODE}.bad-opt"` when `pack` is missing or `pack.id` is not a non-empty
+ * string. Wired by `gateContract.defineGuard` through
+ * `gateContract.makeRulePackLoader`, so storage shape and validation are
+ * identical across the family.
+ *
+ * @example
+ *   var pack = b.{NS}.loadRulePack({ id: "tenant-policy", rules: [] });
+ *   pack.id;                                             // → "tenant-policy"
+ */
+
+/**
+ * @abiTemplate defineGuard
+ * @method      gate
+ * @signature   b.{NS}.gate(opts?)
+ * @status      stable
+ * @related     b.{NS}.validate, b.gateContract.buildGuardGate
+ *
+ * Build the guard's request-boundary gate — a contract-shaped object
+ * exposing `check(ctx)` that host primitives call at their byte moment.
+ * This is the factory default chain: `serve` when no issue, `audit-only`
+ * for `info` / `warn` issues, and `refuse` for any `high` / `critical`
+ * issue, dispatched to the right `ctx` field by the guard's KIND. Wired
+ * by `gateContract.defineGuard` through `gateContract.buildGuardGate`; a
+ * guard whose gate diverges (a bespoke sanitize-and-reserialize chain,
+ * for example) ships its own `gate` block instead of this template.
+ *
+ * @opts
+ *   profile:           string,    // one of PROFILES; default this guard's default
+ *   compliancePosture: string,    // overlay one of hipaa/pci-dss/gdpr/soc2
+ *   mode:              string,    // one of gateContract MODES; default "enforce"
+ *
+ * @example
+ *   var gate = b.{NS}.gate({ profile: "strict" });
+ *   var decision = await gate.check({ bytes: Buffer.from("...") });
+ *   decision.action;                                     // → "serve" | "refuse" | …
+ */
+
+/**
+ * @abiTemplate defineParser
+ * @method      compliancePosture
+ * @signature   b.{NS}.compliancePosture(name)
+ * @status      stable
+ * @compliance  hipaa, pci-dss, gdpr, soc2
+ * @related     b.{NS}.validate, b.gateContract.ALL_STRICT_POSTURES
+ *
+ * Return the effective profile NAME for a compliance posture, or `null`
+ * for a name this parser does not map. Unlike the content-guard variant
+ * this returns the resolved profile string (every line-protocol parser
+ * composes `gateContract.ALL_STRICT_POSTURES`, so `"hipaa"` / `"pci-dss"`
+ * / `"gdpr"` / `"soc2"` all resolve to `"strict"`) and never throws —
+ * the parser shape carries no overlay-clone, no `buildProfile`, and no
+ * `loadRulePack`. Wired by `gateContract.defineParser`.
+ *
+ * @example
+ *   b.{NS}.compliancePosture("hipaa");                   // → "strict"
+ *   b.{NS}.compliancePosture("not-a-regime");            // → null
+ */
+
 module.exports = {
   defineGate:         defineGate,
+  defineGuard:        defineGuard,
+  defineParser:       defineParser,
   validateGateShape:  validateGateShape,
   runGate:            runGate,
   composeGates:       composeGates,
@@ -1648,8 +2292,11 @@ module.exports = {
   buildGuardGate:     buildGuardGate,
   extractBytesAsText: extractBytesAsText,
   lookupCompliancePosture: lookupCompliancePosture,
+  ALL_STRICT_POSTURES: ALL_STRICT_POSTURES,
   makeRulePackLoader: makeRulePackLoader,
   makeProfileBuilder: makeProfileBuilder,
+  makeProfileResolver: makeProfileResolver,
+  throwOnRefusalSeverity: throwOnRefusalSeverity,
   badInputResultIfNotStringOrBuffer: badInputResultIfNotStringOrBuffer,
   aggregateIssues:    aggregateIssues,
   composeHooks:       composeHooks,
@@ -1658,4 +2305,5 @@ module.exports = {
   MODES:              MODES,
   ISSUE_SEVERITIES:   ISSUE_SEVERITIES,
   GateContractError:      GateContractError,
+  _resetForTest:      _resetForTest,
 };