@blamejs/core 0.8.43 → 0.8.49

package/lib/guard-template.js

@@ -1,29 +1,53 @@
 "use strict";
 /**
- * guard-template — Template-injection identifier-safety primitive
- * (b.guardTemplate).
+ * @module b.guardTemplate
+ * @nav    Guards
+ * @title  Guard Template
  *
- * Detects Server-Side Template Injection (SSTI) shapes in user-input
- * strings before they're rendered through any template engine. Refused
- * by default at every profile — operator-untrusted input rarely
- * legitimately contains template-engine syntax. KIND="identifier" —
- * consumes ctx.identifier (or ctx.text).
+ * @intro
+ *   Server-Side Template Injection (SSTI) content-safety guard —
+ *   refuses user-supplied strings that contain template-engine
+ *   syntax BEFORE they're rendered. Template-injection vulnerable
+ *   surfaces escape sandboxes through engine helpers (`render`,
+ *   `lookup`, `with`, `attr_filter`); the safe shape is "logic-less
+ *   templates only, untrusted strings are data not code". This
+ *   primitive enforces that boundary by refusing engine syntax in
+ *   any operator-untrusted input. Pair with logic-less Mustache
+ *   helpers, Handlebars `noEscape: false`, and Liquid's strict-
+ *   variables mode so the framework's defense-in-depth holds even
+ *   when an operator forgets to escape. KIND=`identifier`; the
+ *   gate consumes `ctx.identifier` (or `ctx.text`) and refuses on
+ *   hostile shapes.
  *
- * Threat catalog (engine-shape detection):
- *   - Jinja2 / Django / Twig / Liquid — `{{...}}` and `{%...%}`.
- *     Recent CVEs: CVE-2024-22195 (Jinja xml_attr filter),
- *     CVE-2024-26139 (Bottle), CVE-2024-23348 (Pyrogram).
- *   - Handlebars — `{{...}}` (same shape as Jinja; flagged together).
- *   - ERB / Tornado — `<%...%>` and `<%=...%>`.
- *   - Pug — `#{...}` interpolation, `!{...}` raw-HTML interpolation.
- *   - Mako / Velocity / Tornado — `${...}` interpolation.
- *   - Velocity directive — `#set(...)`, `#if(...)`, `#foreach(...)`.
- *   - AngularJS — `{{...}}` (covered by Jinja shape; legacy).
- *   - BIDI / null / control / zero-width universal refuse.
+ *   Threat catalog (engine-shape detection): Jinja2 / Django / Twig
+ *   / Liquid / Handlebars / Mustache / AngularJS — `{{...}}`
+ *   expressions and `{%...%}` statements (CVE-2024-22195 Jinja
+ *   `xml_attr_filter`, CVE-2024-26139 Bottle, CVE-2024-23348
+ *   Pyrogram); ERB / Tornado — `<%...%>` and `<%=...%>`; Pug —
+ *   `#{...}` interpolation and `!{...}` raw-HTML interpolation
+ *   (prototype-pollution exit when the model is operator-fed);
+ *   Mako / Velocity / Tornado / JS template-literal — `${...}`
+ *   interpolation; Velocity directives (`#set`, `#if`, `#foreach`,
+ *   `#parse`, `#include`); BIDI / null / C0 control / zero-width
+ *   universal refuse.
  *
- *   var rv = b.guardTemplate.validate("Hello {{ name }}",
- *                                     { profile: "strict" });
- *   var g  = b.guardTemplate.gate({ profile: "strict" });
+ *   Profiles: `strict` / `balanced` / `permissive`. Compliance
+ *   postures: `hipaa` / `pci-dss` / `gdpr` / `soc2`. Operators
+ *   select via `{ profile: "strict" }` or
+ *   `{ compliance: "hipaa" }`; postures overlay on top of the
+ *   profile baseline. Jinja / ERB / Pug shape rejection holds at
+ *   every profile — the SSTI class is never an operator opt-in.
+ *
+ *   Template input cannot be repaired safely (stripping `{{` from
+ *   `{{name}}` produces a different document); `sanitize` either
+ *   passes through clean input or throws `GuardTemplateError`; the
+ *   gate returns `serve` / `audit-only` / `refuse` (no `sanitize`
+ *   action). The `${...}` and Velocity-directive policies default
+ *   to `audit` outside `strict` because they overlap with legitimate
+ *   JS / shell substrings, so operators tune via overrides.
+ *
+ * @card
+ *   Server-Side Template Injection (SSTI) content-safety guard — refuses user-supplied strings that contain template-engine syntax BEFORE they're rendered.
  */
 
 var codepointClass = require("./codepoint-class");
@@ -195,6 +219,45 @@ function _detectIssues(input, opts) {
   return issues;
 }
 
+/**
+ * @primitive  b.guardTemplate.validate
+ * @signature  b.guardTemplate.validate(input, opts)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardTemplate.gate, b.guardTemplate.sanitize
+ *
+ * Inspect a user-supplied template-rendering input and return an
+ * aggregated issue list. Pure inspection — never throws on
+ * hostile input; caller decides what to do with the issues. The
+ * `ok` flag is `true` only when zero `critical` / `high` issues
+ * fire. Throws `GuardTemplateError("template.bad-opt")` when a
+ * numeric opt is non-finite / negative (config-time mistake by
+ * the operator).
+ *
+ * @opts
+ *   profile:                 "strict"|"balanced"|"permissive",
+ *   compliance:              "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   bidiPolicy:              "reject"|"audit"|"allow",
+ *   controlPolicy:           "reject"|"audit"|"allow",
+ *   nullBytePolicy:          "reject"|"audit"|"allow",
+ *   zeroWidthPolicy:         "reject"|"strip"|"audit"|"allow",
+ *   jinjaPolicy:             "reject"|"audit"|"allow",
+ *   erbPolicy:               "reject"|"audit"|"allow",
+ *   pugPolicy:               "reject"|"audit"|"allow",
+ *   dollarBracePolicy:       "reject"|"audit"|"allow",
+ *   velocityDirectivePolicy: "reject"|"audit"|"allow",
+ *   maxBytes:                number,
+ *   maxRuntimeMs:            number,
+ *
+ * @example
+ *   var clean = b.guardTemplate.validate("Hello world", { profile: "strict" });
+ *   clean.ok;                                          // → true
+ *
+ *   var hostile = b.guardTemplate.validate("Hello {{7*7}}", { profile: "strict" });
+ *   hostile.ok;                                        // → false
+ *   hostile.issues.some(function (i) { return i.kind === "jinja-expression"; });  // → true
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -203,6 +266,45 @@ function validate(input, opts) {
   return gateContract.aggregateIssues(_detectIssues(input, opts));
 }
 
+/**
+ * @primitive  b.guardTemplate.sanitize
+ * @signature  b.guardTemplate.sanitize(input, opts)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardTemplate.validate, b.guardTemplate.gate
+ *
+ * Pass-through-or-throw. Template-input strings cannot be safely
+ * repaired (stripping `{{` from `{{name}}` produces a different
+ * document and silently changes operator intent); this primitive
+ * returns the input unchanged when no `critical` or `high` issue
+ * fires, otherwise throws `GuardTemplateError` with the offending
+ * rule id (e.g. `template.jinja-expression`,
+ * `template.erb-expression`, `template.pug-interpolation`,
+ * `template.velocity-directive`). Operators that need a "best-
+ * effort cleanup" semantic should pre-escape the input through
+ * the rendering engine's own escape helper instead.
+ *
+ * @opts
+ *   profile:                 "strict"|"balanced"|"permissive",
+ *   compliance:              "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   jinjaPolicy:             "reject"|"audit"|"allow",
+ *   erbPolicy:               "reject"|"audit"|"allow",
+ *   pugPolicy:               "reject"|"audit"|"allow",
+ *   dollarBracePolicy:       "reject"|"audit"|"allow",
+ *   velocityDirectivePolicy: "reject"|"audit"|"allow",
+ *   maxBytes:                number,
+ *
+ * @example
+ *   var safe = b.guardTemplate.sanitize("Hello world", { profile: "strict" });
+ *   safe;                                              // → "Hello world"
+ *
+ *   try {
+ *     b.guardTemplate.sanitize("Hello {{7*7}}", { profile: "strict" });
+ *   } catch (e) {
+ *     e.code;                                          // → "template.jinja-expression"
+ *   }
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   if (typeof input !== "string") {
@@ -218,6 +320,46 @@ function sanitize(input, opts) {
   return input;
 }
 
+/**
+ * @primitive  b.guardTemplate.gate
+ * @signature  b.guardTemplate.gate(opts)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardTemplate.validate, b.guardTemplate.sanitize
+ *
+ * Build a `b.gateContract` gate that screens `ctx.identifier` (or
+ * `ctx.text`) before any template engine renders the input.
+ * Action chain: `serve` (no issues) → `audit-only` (warn-only) →
+ * `refuse` (any `critical` or `high`). No `sanitize` action —
+ * template input cannot be repaired. Compose into form handlers /
+ * comment renderers / model fields fed to Mustache / Handlebars /
+ * Liquid so operator-untrusted strings never reach the rendering
+ * engine carrying engine syntax.
+ *
+ * @opts
+ *   profile:                 "strict"|"balanced"|"permissive",
+ *   compliance:              "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   name:                    string,    // override gate name in audit emissions
+ *   jinjaPolicy:             "reject"|"audit"|"allow",
+ *   erbPolicy:               "reject"|"audit"|"allow",
+ *   pugPolicy:               "reject"|"audit"|"allow",
+ *   dollarBracePolicy:       "reject"|"audit"|"allow",
+ *   velocityDirectivePolicy: "reject"|"audit"|"allow",
+ *   maxBytes:                number,
+ *
+ * @example
+ *   var gate = b.guardTemplate.gate({ profile: "strict" });
+ *
+ *   gate({ identifier: "Hello {{7*7}}" }).then(function (rv) {
+ *     rv.ok;                                           // → false
+ *     rv.action;                                       // → "refuse"
+ *   });
+ *
+ *   gate({ identifier: "Hello world" }).then(function (rv) {
+ *     rv.action;                                       // → "serve"
+ *   });
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -243,14 +385,83 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive  b.guardTemplate.buildProfile
+ * @signature  b.guardTemplate.buildProfile(opts)
+ * @since      0.7.13
+ * @status     stable
+ * @related    b.guardTemplate.gate, b.guardTemplate.compliancePosture
+ *
+ * Compose a derived guardTemplate profile from one or more named
+ * bases plus inline overrides. `opts.extends` is a profile name
+ * (`"strict"` / `"balanced"` / `"permissive"`) or an array of
+ * names; later entries shadow earlier ones. Inline `opts` keys win
+ * last. Used to keep operator-defined profiles traceable to a
+ * baseline rather than re-typing every key.
+ *
+ * @opts
+ *   extends: string|string[],   // base profile name(s) to compose
+ *   ...:     any guardTemplate key, // inline override of resolved keys
+ *
+ * @example
+ *   var custom = b.guardTemplate.buildProfile({
+ *     extends: "balanced",
+ *     dollarBracePolicy: "reject",
+ *   });
+ *   custom.dollarBracePolicy;                          // → "reject"
+ *   custom.jinjaPolicy;                                // → "reject"
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive  b.guardTemplate.compliancePosture
+ * @signature  b.guardTemplate.compliancePosture(name)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardTemplate.gate, b.guardTemplate.buildProfile
+ *
+ * Look up a compliance-posture overlay by name (`"hipaa"` /
+ * `"pci-dss"` / `"gdpr"` / `"soc2"`). Returns a shallow clone of
+ * the posture object — the caller may mutate freely. Throws
+ * `GuardTemplateError("template.bad-posture")` on unknown name.
+ *
+ * @example
+ *   var posture = b.guardTemplate.compliancePosture("hipaa");
+ *   posture.jinjaPolicy;                               // → "reject"
+ *   posture.forensicSnippetBytes;                      // → 512
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
     _err, "template");
 }
 
 var _tplRulePacks = gateContract.makeRulePackLoader(GuardTemplateError, "template");
+/**
+ * @primitive  b.guardTemplate.loadRulePack
+ * @signature  b.guardTemplate.loadRulePack(pack)
+ * @since      0.7.13
+ * @status     stable
+ * @related    b.guardTemplate.gate
+ *
+ * Register an operator-supplied rule pack with the guardTemplate
+ * registry. The pack is identified by `pack.id` (non-empty string)
+ * and stored for later inspection / dispatch by gates that opt in
+ * via `opts.rulePackId`. Returns the pack object unchanged on
+ * success; throws `GuardTemplateError("template.bad-opt")` when
+ * `pack` is missing or `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardTemplate.loadRulePack({
+ *     id: "no-prototype-keys",
+ *     rules: [
+ *       { id: "proto-key", severity: "critical",
+ *         detect: function (text) { return /__proto__|constructor/.test(text); },
+ *         reason: "input references prototype-pollution sink" },
+ *     ],
+ *   });
+ *   pack.id;                                           // → "no-prototype-keys"
+ */
 var loadRulePack = _tplRulePacks.load;
 
 module.exports = {

package/lib/guard-time.js

@@ -1,37 +1,40 @@
 "use strict";
 /**
- * guard-time — RFC 3339 / ISO 8601 datetime identifier-safety primitive
- * (b.guardTime).
+ * @module b.guardTime
+ * @nav    Guards
+ * @title  Guard Time
  *
- * Validates user-supplied datetime strings destined for audit
- * timestamps, scheduling, retention windows, query ranges, and
- * cross-system event correlation. KIND="identifier" — consumes
- * ctx.identifier (or ctx.timestamp).
+ * @intro
+ *   ISO 8601 / RFC 3339 datetime identifier-safety guard. Validates
+ *   user-supplied datetime strings destined for audit timestamps,
+ *   scheduling, retention windows, query ranges, and cross-system
+ *   event correlation. KIND="identifier" — the gate consumes
+ *   `ctx.identifier` / `ctx.timestamp` / `ctx.time`.
  *
- * Threat catalog:
- *   - Shape malformation — not RFC 3339 / ISO 8601 datetime.
- *   - Pre-epoch / far-future — year before 1970 or after the
- *     operator's far-future ceiling (default 9999); often a parsing
- *     bug or sentinel-leak shape.
- *   - Naive datetime (no offset) — strict refuses; downstream
- *     interpretation depends on local timezone, breaks
- *     cross-region equality.
- *   - Non-UTC offset — strict accepts only `Z` / `+00:00`; balanced
- *     accepts any offset; permissive allows naive too.
- *   - Leap-second `60` in seconds field — RFC 3339 §5.6 explicitly
- *     valid (`23:59:60Z` is a real wall-clock time); most parsers
- *     panic. Flagged-by-default with operator policy.
- *   - Excessive fractional precision — RFC 3339 allows any digits
- *     after the dot but every consuming system has a cap; flag > 9
- *     fractional digits.
- *   - Date-only / time-only — refused for full-datetime contexts.
- *   - Whitespace / control / null-byte / BIDI universal refuse.
+ *   Threat catalog: shape malformation (not RFC 3339 datetime
+ *   grammar); pre-epoch / far-future (year before 1970 or after
+ *   the operator's ceiling, default 9999 — often a parsing bug or
+ *   sentinel-leak shape); naive datetime with no offset (strict
+ *   refuses — downstream interpretation depends on local timezone,
+ *   breaks cross-region equality); non-UTC offset (strict accepts
+ *   only `Z` / `+00:00`; balanced accepts any offset; permissive
+ *   allows naive too); leap-second `60` in seconds field (RFC 3339
+ *   §5.6 explicitly valid, most parsers panic — flagged-by-default
+ *   with operator policy); excessive fractional precision (cap at
+ *   9 digits = nanosecond floor); date-only / time-only refused for
+ *   full-datetime contexts; BIDI / zero-width / C0-control /
+ *   null-byte universal-refuse.
  *
- *   var rv = b.guardTime.validate("2026-05-05T12:34:56Z",
- *                                 { profile: "strict" });
- *   var safe = b.guardTime.sanitize("2026-05-05T12:34:56.123+05:30",
- *                                   { profile: "balanced" });
- *   var g = b.guardTime.gate({ profile: "strict" });
+ *   Far-future / pre-epoch refusal is critical-severity by default:
+ *   year-2038 wrap shapes, Y10K sentinels, and `0000-01-01` poison
+ *   pills routinely leak through downstream parsers as silent
+ *   `NaN` / `0` rows; the guard refuses at the boundary instead.
+ *
+ *   Profiles: `strict` / `balanced` / `permissive`. Compliance
+ *   postures: `hipaa` / `pci-dss` / `gdpr` / `soc2`.
+ *
+ * @card
+ *   ISO 8601 / RFC 3339 datetime identifier-safety guard.
  */
 
 var codepointClass = require("./codepoint-class");
@@ -327,6 +330,47 @@ function _detectIssues(input, opts) {
   return issues;
 }
 
+/**
+ * @primitive  b.guardTime.validate
+ * @signature  b.guardTime.validate(input, opts?)
+ * @since      0.7.46
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardTime.sanitize, b.guardTime.gate
+ *
+ * Inspect a datetime string against the resolved profile and return
+ * `{ ok, issues }`. Each issue carries `kind` / `severity`
+ * (`critical` | `high` | `medium` | `low`) / `ruleId` / `snippet`.
+ * Non-string input returns a single `time.bad-input` issue rather
+ * than throwing — callers that prefer an exception use
+ * `b.guardTime.sanitize`.
+ *
+ * @opts
+ *   profile:                "strict"|"balanced"|"permissive",
+ *   compliance:             "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   bidiPolicy:             "reject"|"strip"|"audit"|"allow",
+ *   controlPolicy:          "reject"|"strip"|"allow",
+ *   nullBytePolicy:         "reject"|"strip"|"allow",
+ *   zeroWidthPolicy:        "reject"|"strip"|"allow",
+ *   naiveDatetimePolicy:    "reject"|"audit"|"allow",
+ *   nonUtcOffsetPolicy:     "reject"|"audit"|"allow",
+ *   leapSecondPolicy:       "reject"|"audit"|"allow",
+ *   fractionalDigitsPolicy: "reject"|"truncate"|"audit"|"allow",
+ *   dateOnlyPolicy:         "reject"|"audit"|"allow",
+ *   timeOnlyPolicy:         "reject"|"audit"|"allow",
+ *   minYear:                number,    // default 1970
+ *   maxYear:                number,    // default 9999
+ *   maxFractionalDigits:    number,    // default 9 (nanosecond)
+ *   maxBytes:               number,    // default 64
+ *
+ * @example
+ *   var rv = b.guardTime.validate("2026-05-05T12:34:56Z", { profile: "strict" });
+ *   rv.ok;                                             // → true
+ *
+ *   var bad = b.guardTime.validate("1969-12-31T23:59:59Z", { profile: "strict" });
+ *   bad.ok;                                            // → false
+ *   bad.issues[0].ruleId;                              // → "time.year-out-of-range"
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -343,6 +387,36 @@ function validate(input, opts) {
   return gateContract.aggregateIssues(_detectIssues(input, opts));
 }
 
+/**
+ * @primitive  b.guardTime.sanitize
+ * @signature  b.guardTime.sanitize(input, opts?)
+ * @since      0.7.46
+ * @status     stable
+ * @related    b.guardTime.validate, b.guardTime.gate
+ *
+ * Normalize a datetime string in-place: replace the legacy
+ * space-separator with `T`, upper-case the trailing `Z` UTC
+ * marker. Throws `GuardTimeError` when any `critical` or `high`
+ * issue fires (year out of range, leap-second under reject,
+ * naive datetime under reject). Use `validate` to inspect issues
+ * without throwing.
+ *
+ * @opts
+ *   profile:                "strict"|"balanced"|"permissive",
+ *   compliance:             "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   ...:                    same shape as b.guardTime.validate opts,
+ *
+ * @example
+ *   var safe = b.guardTime.sanitize("2026-05-05 12:34:56z",
+ *                                   { profile: "balanced" });
+ *   safe;                                              // → "2026-05-05T12:34:56Z"
+ *
+ *   try {
+ *     b.guardTime.sanitize("9999-12-31T23:59:60Z", { profile: "strict" });
+ *   } catch (e) {
+ *     e.code;                                          // → "time.leap-second"
+ *   }
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   if (typeof input !== "string") {
@@ -360,6 +434,35 @@ function sanitize(input, opts) {
   return input.replace(/(\d) /, "$1T").replace(/z$/, "Z");
 }
 
+/**
+ * @primitive  b.guardTime.gate
+ * @signature  b.guardTime.gate(opts?)
+ * @since      0.7.46
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardTime.validate, b.guardTime.sanitize, b.guardAll.gate
+ *
+ * Build an async gate `(ctx) -> { ok, action, issues }` consumable
+ * by `b.guardAll`, audit pipelines, scheduling primitives, and
+ * retention readers. The gate reads `ctx.identifier` (or
+ * `ctx.timestamp` / `ctx.time`), runs `validate`, and maps
+ * severity to action: zero issues `serve`; only low/medium
+ * `audit-only`; any high/critical `refuse`.
+ *
+ * @opts
+ *   name:                   string,    // gate label for audit / observability
+ *   profile:                "strict"|"balanced"|"permissive",
+ *   compliance:             "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   ...:                    same shape as b.guardTime.validate opts,
+ *
+ * @example
+ *   var g = b.guardTime.gate({ profile: "strict" });
+ *   var rv = await g({ identifier: "2026-05-05T12:34:56Z" });
+ *   rv.action;                                         // → "serve"
+ *
+ *   var bad = await g({ identifier: "2026-05-05 12:34:56" });
+ *   bad.action;                                        // → "refuse"
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -383,14 +486,77 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive  b.guardTime.buildProfile
+ * @signature  b.guardTime.buildProfile(opts)
+ * @since      0.7.46
+ * @status     stable
+ * @related    b.guardTime.gate, b.guardTime.compliancePosture
+ *
+ * Compose a derived profile from one or more named bases plus
+ * inline overrides. `opts.extends` is a profile name or array of
+ * names (later entries shadow earlier ones); inline keys win last.
+ *
+ * @opts
+ *   extends: string|string[],   // base profile name(s) to compose
+ *   ...:     any guard-time key, // inline override of resolved keys
+ *
+ * @example
+ *   var custom = b.guardTime.buildProfile({
+ *     extends: "balanced",
+ *     leapSecondPolicy: "audit",
+ *     maxYear: 2200,
+ *   });
+ *   custom.naiveDatetimePolicy;                        // → "audit"
+ *   custom.maxYear;                                    // → 2200
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive  b.guardTime.compliancePosture
+ * @signature  b.guardTime.compliancePosture(name)
+ * @since      0.7.46
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardTime.gate, b.guardTime.buildProfile
+ *
+ * Look up a compliance-posture overlay by name (`"hipaa"` /
+ * `"pci-dss"` / `"gdpr"` / `"soc2"`). Returns a shallow clone of
+ * the posture object — the caller may mutate freely. Throws
+ * `GuardTimeError("time.bad-posture")` on unknown name.
+ *
+ * @example
+ *   var posture = b.guardTime.compliancePosture("hipaa");
+ *   posture.naiveDatetimePolicy;                       // → "reject"
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
     _err, "time");
 }
 
 var _timeRulePacks = gateContract.makeRulePackLoader(GuardTimeError, "time");
+/**
+ * @primitive  b.guardTime.loadRulePack
+ * @signature  b.guardTime.loadRulePack(pack)
+ * @since      0.7.46
+ * @status     stable
+ * @related    b.guardTime.gate
+ *
+ * Register an operator-supplied rule pack with the guard-time
+ * registry. The pack is identified by `pack.id` (non-empty
+ * string) and stored for later inspection / dispatch by gates
+ * that opt in via `opts.rulePackId`. Throws
+ * `GuardTimeError("time.bad-opt")` when `pack` is missing or
+ * `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardTime.loadRulePack({
+ *     id: "audit-window",
+ *     minYear: 2020,
+ *     maxYear: 2030,
+ *   });
+ *   pack.id;                                           // → "audit-window"
+ */
 var loadRulePack = _timeRulePacks.load;
 
 module.exports = {