@blamejs/blamejs-shop 0.4.31 → 0.4.32

package/lib/vendor/blamejs/examples/wiki/lib/source-comment-block-validator.js

@@ -89,8 +89,13 @@ function _firstSegment(primTag) {
 // Probe the universe of primitive signatures available for @related
 // cross-reference. Sources: every @primitive block under lib/, plus
 // every primitive heading in seeded page bodies (which includes
-// hand-authored AND generated pages once the seeder ran).
-function _knownPrimitiveSet(docs, seederIndex) {
+// hand-authored AND generated pages once the seeder ran), plus the
+// factory-synthesized ABI methods (compliancePosture / buildProfile /
+// loadRulePack / gate) every defineGuard / defineParser guard exposes —
+// these have no in-source @primitive block (the doc lives once in
+// gate-contract.js's @abiTemplate blocks) but the page generator renders
+// them per guard, so a real guard block's @related to them must resolve.
+function _knownPrimitiveSet(docs, seederIndex, parser) {
   var set = {};
   Object.keys(docs).forEach(function (file) {
     docs[file].primitives.forEach(function (p) {
@@ -98,6 +103,22 @@ function _knownPrimitiveSet(docs, seederIndex) {
       if (sig) set[_bare(sig)] = true;
     });
   });
+  // Register the per-guard ABI method sigs the factory synthesizes.
+  if (parser && typeof parser.factoryTemplates === "function") {
+    var templates = parser.factoryTemplates(docs);
+    Object.keys(docs).forEach(function (file) {
+      var rec = docs[file];
+      if (!rec.factory) return;
+      var ns = rec.module && rec.module.tags
+        ? _moduleNs(rec.module.tags.module)
+        : null;
+      if (!ns) return;
+      (templates[rec.factory.kind] || []).forEach(function (tpl) {
+        var method = tpl.tags && tpl.tags.method;
+        if (method) set[ns + "." + method] = true;
+      });
+    });
+  }
   if (seederIndex) {
     try {
       var pages = require(seederIndex);
@@ -131,73 +152,113 @@ function _knownPrimitiveSet(docs, seederIndex) {
 function _extractExportKeys(source) {
   var keys = {};
 
-  // Shape 2: per-property module.exports.foo = ...
+  // Shape A: per-property module.exports.foo = ...
   var perPropRe = /\bmodule\.exports\.([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=/g;
   var pm;
   while ((pm = perPropRe.exec(source)) !== null) keys[pm[1]] = true;
 
-  // Shape 1: object-literal module.exports = { ... }
-  var openMatch = source.match(/module\.exports\s*=\s*\{/);
-  if (openMatch) {
-    // Bracket-count from the opening { until matching close.
-    var i = openMatch.index + openMatch[0].length;
-    var depth = 1;
-    var inStr = null;       // null | '"' | "'" | '`'
-    var inSlash = false;     // line comment
-    var inBlock = false;     // block comment
-    var prev = "";
-    while (i < source.length && depth > 0) {
-      var c = source[i];
-      if (inSlash) {
-        if (c === "\n") inSlash = false;
-      } else if (inBlock) {
-        if (prev === "*" && c === "/") inBlock = false;
-      } else if (inStr) {
-        if (c === "\\") { i += 2; prev = source[i - 1]; continue; }
-        if (c === inStr) inStr = null;
-      } else if (c === "/" && source[i + 1] === "/") {
-        inSlash = true;
-      } else if (c === "/" && source[i + 1] === "*") {
-        inBlock = true;
-      } else if (c === '"' || c === "'" || c === "`") {
-        inStr = c;
-      } else if (c === "{") {
-        depth++;
-      } else if (c === "}") {
-        depth--;
-      }
-      prev = c;
-      i++;
+  // Shape B: object literal `module.exports = {`.  Shape C: factory call
+  // `module.exports = [ns.]defineGuard({` / `defineParser({` — the guard
+  // family's consolidated wiring assembles the frozen exports object inside
+  // gateContract.defineGuard/defineParser, so there is no object literal to
+  // scan. Both forms open an object whose keys we collect identically; the
+  // factory form additionally yields the per-guard FUNCTION exports it wires
+  // in (the spec's `validate` / `sanitize` / `gate` / `entry` references and
+  // any functions passed through `extra: { ... }`). The factory-generated
+  // wiring (buildProfile / compliancePosture / loadRulePack / gate default)
+  // has no in-source `function NAME`, so the arity filter in the missing-block
+  // pass skips it — but a per-guard function the author forgot to document is
+  // still caught, so the doc gate survives the factory refactor.
+  var litMatch = source.match(/module\.exports\s*=\s*\{/);
+  var factoryMatch = source.match(/module\.exports\s*=\s*(?:[a-zA-Z_$][a-zA-Z0-9_$]*\.)?define(?:Guard|Parser)\s*\(\s*\{/);
+  var openIdx = -1;
+  var factoryMode = false;
+  if (litMatch) {
+    openIdx = litMatch.index + litMatch[0].length - 1;
+  } else if (factoryMatch) {
+    openIdx = factoryMatch.index + factoryMatch[0].lastIndexOf("{");
+    factoryMode = true;
+  }
+  if (openIdx >= 0) {
+    _collectObjectKeys(source, openIdx, factoryMode).forEach(function (k) { keys[k] = true; });
+  }
+
+  return Object.keys(keys).filter(function (k) { return !/^_/.test(k); });
+}
+
+// Bracket-count the object literal whose opening `{` is at openIdx and return
+// its top-level property names. In factoryMode it also returns bare-identifier
+// property VALUES (e.g. `entry: validate` -> `validate`, the exported function
+// the spec references) and the keys/values of a nested `extra: { ... }` map.
+// The missing-block pass arity-filters the result, so non-function names
+// (NAME / PROFILES / error classes) are harmless.
+function _collectObjectKeys(source, openIdx, factoryMode) {
+  var i = openIdx + 1;
+  var depth = 1;
+  var inStr = null;       // null | '"' | "'" | '`'
+  var inSlash = false;     // line comment
+  var inBlock = false;     // block comment
+  var prev = "";
+  while (i < source.length && depth > 0) {
+    var c = source[i];
+    if (inSlash) {
+      if (c === "\n") inSlash = false;
+    } else if (inBlock) {
+      if (prev === "*" && c === "/") inBlock = false;
+    } else if (inStr) {
+      if (c === "\\") { i += 2; prev = source[i - 1]; continue; }
+      if (c === inStr) inStr = null;
+    } else if (c === "/" && source[i + 1] === "/") {
+      inSlash = true;
+    } else if (c === "/" && source[i + 1] === "*") {
+      inBlock = true;
+    } else if (c === '"' || c === "'" || c === "`") {
+      inStr = c;
+    } else if (c === "{") {
+      depth++;
+    } else if (c === "}") {
+      depth--;
     }
-    if (depth === 0) {
-      var body = source.slice(openMatch.index + openMatch[0].length, i - 1);
-      // Match `name:` or `name,` or `name }` at the start of an
-      // object-property position. This is conservative — runs on the
-      // body after stripping nested object-literal interiors via a
-      // simple depth-aware scan.
-      var depth2 = 0;
-      var line = "";
-      var lines = [];
-      for (var j = 0; j < body.length; j++) {
-        var ch = body[j];
-        if (ch === "{" || ch === "(" || ch === "[") depth2++;
-        else if (ch === "}" || ch === ")" || ch === "]") depth2--;
-        if (depth2 === 0) {
-          line += ch;
-          if (ch === "," || ch === "\n") {
-            lines.push(line); line = "";
-          }
-        }
+    prev = c;
+    i++;
+  }
+  var found = [];
+  if (depth !== 0) return found;
+  var body = source.slice(openIdx + 1, i - 1);
+  // Match `name:` or `name,` at the start of an object-property position,
+  // after stripping nested object/array/call interiors via a depth scan.
+  var depth2 = 0;
+  var line = "";
+  var lines = [];
+  for (var j = 0; j < body.length; j++) {
+    var ch = body[j];
+    if (ch === "{" || ch === "(" || ch === "[") depth2++;
+    else if (ch === "}" || ch === ")" || ch === "]") depth2--;
+    if (depth2 === 0) {
+      line += ch;
+      if (ch === "," || ch === "\n") {
+        lines.push(line); line = "";
       }
-      if (line) lines.push(line);
-      lines.forEach(function (l) {
-        var lm = l.match(/^\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*[:,]/);
-        if (lm) keys[lm[1]] = true;
+    }
+  }
+  if (line) lines.push(line);
+  lines.forEach(function (l) {
+    var lm = l.match(/^\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*[:,]/);
+    if (lm) found.push(lm[1]);
+    if (factoryMode) {
+      var vm = l.match(/:\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*,?\s*$/);
+      if (vm) found.push(vm[1]);
+    }
+  });
+  if (factoryMode) {
+    var em = body.match(/(^|[\s,{])extra\s*:\s*\{/);
+    if (em) {
+      _collectObjectKeys(body, em.index + em[0].lastIndexOf("{"), true).forEach(function (k) {
+        found.push(k);
       });
     }
   }
-
-  return Object.keys(keys).filter(function (k) { return !/^_/.test(k); });
+  return found;
 }
 
 // Count parameters in a signature like `b.X.Y(a, b, opts?)`. The `?`
@@ -276,7 +337,7 @@ function validate(config) {
 
   var findings = [];
   var docs = parser.parseTree(libDir);
-  var known = _knownPrimitiveSet(docs, seederIndex);
+  var known = _knownPrimitiveSet(docs, seederIndex, parser);
 
   var declaredNs = {};
   curationPages.forEach(function (page) {
@@ -578,9 +639,108 @@ function validate(config) {
     }
   });
 
+  // ---- Pass: @abiTemplate structural checks ----
+  // ABI doc templates are single-sourced placeholder blocks (b.{NS}.<method>
+  // with {NS}/{ERR} substituted per guard at page-gen time). They are NOT
+  // resolvable primitives, so the per-primitive pass skips them (the parser
+  // routes them to rec.abiTemplates, not rec.primitives). Validate their
+  // template shape instead: a known factory kind, a @method, a placeholder
+  // @signature, valid @status, real prose, and at least one @example. The
+  // placeholder sig + placeholder @example bodies are intentional, so the
+  // resolvable-primitive / JS-parse passes do not apply.
+  Object.keys(docs).forEach(function (file) {
+    var rec = docs[file];
+    if (!rec.abiTemplates || rec.abiTemplates.length === 0) return;
+    var rel = path.relative(libDir, file);
+    var seen = {};
+    rec.abiTemplates.forEach(function (t) {
+      var tags = t.tags || {};
+      var kind = tags.abiTemplate;
+      var label = "@abiTemplate " + (kind || "?") + (tags.method ? " " + tags.method : "");
+      if (kind !== "defineGuard" && kind !== "defineParser") {
+        findings.push({
+          kind: "abi-template", file: rel, primitive: label,
+          msg: "@abiTemplate value must be `defineGuard` or `defineParser` (got `" + kind + "`)",
+        });
+      }
+      if (!tags.method) {
+        findings.push({
+          kind: "abi-template", file: rel, primitive: label,
+          msg: "@abiTemplate block lacks @method — name the factory-generated ABI method it documents",
+        });
+      } else {
+        var dupeKey = kind + "::" + tags.method;
+        if (seen[dupeKey]) {
+          findings.push({
+            kind: "abi-template", file: rel, primitive: label,
+            msg: "duplicate @abiTemplate for " + dupeKey + " — one template per (factory, method)",
+          });
+        }
+        seen[dupeKey] = true;
+      }
+      if (!tags.signature) {
+        findings.push({
+          kind: "abi-template", file: rel, primitive: label,
+          msg: "@abiTemplate block lacks @signature",
+        });
+      } else if (tags.signature.indexOf("{NS}") === -1) {
+        findings.push({
+          kind: "abi-template", file: rel, primitive: label,
+          msg: "@abiTemplate @signature must carry the `{NS}` placeholder (got `" + tags.signature + "`)",
+        });
+      } else if (tags.method && _bareTemplateMethod(tags.signature) !== tags.method) {
+        findings.push({
+          kind: "abi-template", file: rel, primitive: label,
+          msg: "@abiTemplate @signature method `" + _bareTemplateMethod(tags.signature) + "` does not match @method `" + tags.method + "`",
+        });
+      }
+      if (tags.status && !KNOWN_STATUSES[tags.status]) {
+        findings.push({
+          kind: "abi-template", file: rel, primitive: label,
+          msg: "@abiTemplate @status must be one of " + Object.keys(KNOWN_STATUSES).join(" / ") + " (got `" + tags.status + "`)",
+        });
+      }
+      if (tags.compliance) {
+        String(tags.compliance).split(",").map(function (s) { return s.trim(); }).filter(Boolean).forEach(function (p2) {
+          if (!KNOWN_POSTURES[p2]) {
+            findings.push({
+              kind: "abi-template", file: rel, primitive: label,
+              msg: "@abiTemplate @compliance value `" + p2 + "` not in posture catalog",
+            });
+          }
+        });
+      }
+      if (!t.prose || t.prose.replace(/\s/g, "").length < 12) {
+        findings.push({
+          kind: "abi-template", file: rel, primitive: label,
+          msg: "@abiTemplate prose body is empty or too short (<12 non-whitespace chars)",
+        });
+      }
+      if (t.proseAfterMultiLine) {
+        findings.push({
+          kind: "abi-template", file: rel, primitive: label,
+          msg: "prose appears AFTER a multi-line tag (@opts/@example) — move prose ABOVE the multi-line tags",
+        });
+      }
+      if (!Array.isArray(tags.examples) || tags.examples.length === 0) {
+        findings.push({
+          kind: "abi-template", file: rel, primitive: label,
+          msg: "@abiTemplate block lacks @example",
+        });
+      }
+    });
+  });
+
   return findings;
 }
 
+// Extract the bare method name from a placeholder template signature like
+// `b.{NS}.compliancePosture(name)` → `compliancePosture`.
+function _bareTemplateMethod(sig) {
+  var m = String(sig).replace(/\([^)]*\)/g, "").match(/\.([a-zA-Z_$][a-zA-Z0-9_$]*)\s*$/);
+  return m ? m[1] : null;
+}
+
 module.exports = {
   validate:           validate,
   KNOWN_STATUSES:     KNOWN_STATUSES,

package/lib/vendor/blamejs/examples/wiki/lib/source-doc-parser.js

@@ -58,6 +58,13 @@ var SINGLE_LINE_TAGS = {
   primitive:   true,
   module:      true,
   concept:     true,
+  // @abiTemplate <factoryKind> — single-sourced ABI doc text for a
+  // factory-generated guard method (defineGuard / defineParser). Routed
+  // to a separate template bucket, NOT the primitive list, so it renders
+  // per guard instead of as a gateContract primitive. @method names the
+  // ABI method the template documents.
+  abiTemplate: true,
+  method:      true,
   title:       true,
   nav:         true,
   order:       true,
@@ -202,6 +209,10 @@ function parseBlock(raw) {
   if (tags.primitive) kindFlags.push("primitive");
   if (tags.module) kindFlags.push("module");
   if (tags.concept) kindFlags.push("concept");
+  // @abiTemplate blocks are a distinct kind — single-sourced ABI doc
+  // text routed to the per-factory template bucket, never the primitive
+  // list. They carry no @primitive tag, so they don't trip mixedKind.
+  if (tags.abiTemplate) kindFlags.push("abiTemplate");
   var kind = kindFlags[0] || null;
   var mixedKind = kindFlags.length > 1 ? kindFlags : null;
 
@@ -235,17 +246,111 @@ function extractBlocks(source) {
   return blocks;
 }
 
+// Detect a guard-family factory call at module scope:
+//   module.exports = [ns.]defineGuard({ ...
+//   module.exports = [ns.]defineParser({ ...
+// Returns { kind, errorClass } or null. The errorClass is read from the
+// spec's `errorClass: Ident` (the guard supplies a pre-built class) and
+// falls back to a `Guard<Name>Error` stem derived from `errorName:` or
+// `name:` — matching the factory's own default-class minting — so the
+// rendered ABI template's `{ERR}` placeholder resolves even when the
+// guard lets the factory mint the class.
+function _detectFactory(source) {
+  var m = source.match(/module\.exports\s*=\s*(?:[a-zA-Z_$][a-zA-Z0-9_$]*\.)?define(Guard|Parser)\s*\(\s*\{/);
+  if (!m) return null;
+  var kind = "define" + m[1];
+  // Scan the spec object literal (bracket-counted) for errorClass /
+  // errorName / name / errCodePrefix.
+  var openIdx = m.index + m[0].lastIndexOf("{");
+  var spec = _sliceObjectLiteral(source, openIdx);
+  var errorClass = null;
+  var name = null;
+  var errCodePrefix = null;
+  if (spec) {
+    var nameMatch = spec.match(/(^|[\s,{])name\s*:\s*["']([^"']+)["']/);
+    if (nameMatch) name = nameMatch[2];
+    var ecpMatch = spec.match(/(^|[\s,{])errCodePrefix\s*:\s*["']([^"']+)["']/);
+    if (ecpMatch) errCodePrefix = ecpMatch[2];
+
+    var ecMatch = spec.match(/(^|[\s,{])errorClass\s*:\s*([a-zA-Z_$][a-zA-Z0-9_$]*)/);
+    if (ecMatch) {
+      errorClass = ecMatch[2];
+    } else {
+      var enMatch = spec.match(/(^|[\s,{])errorName\s*:\s*["']([^"']+)["']/);
+      if (enMatch) {
+        errorClass = enMatch[2];
+      } else if (name) {
+        errorClass = _defaultErrorClassName(name);
+      }
+    }
+  }
+  // Error-code prefix mirrors the factory: errCodePrefix || name. This is
+  // the stem used in thrown codes ("csv.bad-posture"), which differs from
+  // the namespace ("guardCsv") — the ABI templates carry both placeholders.
+  return {
+    kind:          kind,
+    errorClass:    errorClass,
+    codePrefix:    errCodePrefix || name,
+  };
+}
+
+// Mirror gate-contract.js's default-class stem: Guard + PascalCase(name) +
+// Error (name's leading char upper-cased, rest verbatim — matches
+// `"Guard" + name.charAt(0).toUpperCase() + name.slice(1) + "Error"`).
+function _defaultErrorClassName(name) {
+  if (!name) return null;
+  return "Guard" + name.charAt(0).toUpperCase() + name.slice(1) + "Error";
+}
+
+// Return the substring of `source` spanning the object literal whose
+// opening brace is at `openIdx` (inclusive of both braces), string- and
+// comment-aware so braces inside strings / comments don't miscount.
+function _sliceObjectLiteral(source, openIdx) {
+  var i = openIdx + 1;
+  var depth = 1;
+  var inStr = null;
+  var inSlash = false;
+  var inBlock = false;
+  var prev = "";
+  while (i < source.length && depth > 0) {
+    var c = source[i];
+    if (inSlash) {
+      if (c === "\n") inSlash = false;
+    } else if (inBlock) {
+      if (prev === "*" && c === "/") inBlock = false;
+    } else if (inStr) {
+      if (c === "\\") { i += 2; prev = source[i - 1]; continue; }
+      if (c === inStr) inStr = null;
+    } else if (c === "/" && source[i + 1] === "/") {
+      inSlash = true;
+    } else if (c === "/" && source[i + 1] === "*") {
+      inBlock = true;
+    } else if (c === '"' || c === "'" || c === "`") {
+      inStr = c;
+    } else if (c === "{") {
+      depth++;
+    } else if (c === "}") {
+      depth--;
+    }
+    prev = c;
+    i++;
+  }
+  if (depth !== 0) return null;
+  return source.slice(openIdx, i);
+}
+
 function parseFile(source, sourcePath) {
   var blocks = extractBlocks(source);
   var module_ = null;
   var primitives = [];
   var concepts = [];
+  var abiTemplates = [];
   for (var i = 0; i < blocks.length; i++) {
     var parsed = parseBlock(blocks[i].raw);
     if (!parsed.kind) continue;
     if (parsed.kind === "module") {
       if (module_) {
-         
+
         console.warn("[source-doc-parser] duplicate @module block in", sourcePath); // allow:console-direct — wiki seeder helper, runs at boot before b.log is wired
       }
       module_ = parsed;
@@ -253,13 +358,22 @@ function parseFile(source, sourcePath) {
       primitives.push(parsed);
     } else if (parsed.kind === "concept") {
       concepts.push(parsed);
+    } else if (parsed.kind === "abiTemplate") {
+      abiTemplates.push(parsed);
     }
   }
   return {
-    sourcePath: sourcePath,
-    module:     module_,
-    primitives: primitives,
-    concepts:   concepts,
+    sourcePath:   sourcePath,
+    module:       module_,
+    primitives:   primitives,
+    concepts:     concepts,
+    // ABI doc templates declared in this file (only gate-contract.js
+    // carries them today). parseTree aggregates them across the tree.
+    abiTemplates: abiTemplates,
+    // Guard-family factory detection — populated when this file's
+    // module.exports is a defineGuard / defineParser call. Drives the
+    // page generator's per-guard ABI-method synthesis.
+    factory:      _detectFactory(source),
   };
 }
 
@@ -310,9 +424,30 @@ function parseTree(rootDir) {
   return byPath;
 }
 
+// Aggregate every @abiTemplate block across a parsed tree into a map
+// keyed by factory kind ("defineGuard" / "defineParser"). Each value is
+// an array of template records ({ kind:"abiTemplate", tags, prose }).
+// Both the page generator (to synthesize per-guard ABI sections) and the
+// comment-block validator (to register the templated method sigs as
+// resolvable @related targets) read from this single derivation.
+function factoryTemplates(byPath) {
+  var byKind = { defineGuard: [], defineParser: [] };
+  Object.keys(byPath).forEach(function (file) {
+    var tpls = byPath[file].abiTemplates || [];
+    tpls.forEach(function (t) {
+      var kind = t.tags && t.tags.abiTemplate;
+      if (!kind) return;
+      if (!byKind[kind]) byKind[kind] = [];
+      byKind[kind].push(t);
+    });
+  });
+  return byKind;
+}
+
 module.exports = {
-  parseBlock:    parseBlock,
-  parseFile:     parseFile,
-  parseTree:     parseTree,
-  extractBlocks: extractBlocks,
+  parseBlock:       parseBlock,
+  parseFile:        parseFile,
+  parseTree:        parseTree,
+  extractBlocks:    extractBlocks,
+  factoryTemplates: factoryTemplates,
 };

package/lib/vendor/blamejs/examples/wiki/test/e2e.js

@@ -628,6 +628,105 @@ async function run() {
       navFailures.forEach(function (f) { console.error("  nav-cov: " + f); });
     }
 
+    // ---- Guard ABI completeness gate ----
+    // For every guard built on the gateContract.defineGuard / defineParser
+    // FACTORY, assert that EVERY non-constant runtime export (a function
+    // that isn't the guard's error class) renders as a section on that
+    // guard's wiki page. The factory single-sources its generated ABI docs
+    // (compliancePosture / buildProfile / loadRulePack / gate) in
+    // gate-contract.js's @abiTemplate blocks; the page generator
+    // instantiates them per guard. This gate makes it impossible for that
+    // de-duplication to silently DROP a method — a method that stops
+    // rendering (template not instantiated, dedup mis-firing, a removed
+    // floating block with no template behind it) fails here, on the live
+    // page, not just in the parser.
+    //
+    // Scope: only factory-built guards. Guards still hand-wiring the export
+    // surface (not yet migrated to the factory) are out of scope for this
+    // mechanism — their pages render whatever doc blocks they carry today,
+    // and they enter this gate the moment they adopt the factory. Runtime
+    // exports are the ground truth: walk b.<guard>.* the same way the
+    // api-snapshot does. Constants (NAME / KIND / PROFILES / DEFAULTS /
+    // COMPLIANCE_POSTURES / MIME_TYPES / EXTENSIONS / INTEGRATION_FIXTURES /
+    // verb tables) are non-functions and excluded; the per-guard error
+    // class is the one function whose prototype is an Error subclass and is
+    // excluded too (it documents under the error-catalog harvester).
+    var bCore = require("@blamejs/core");
+    var abiParser = require("../lib/source-doc-parser");
+    var autoSiteEntries = require("../lib/auto-site-entries");
+    var abiLibDir = path.join(__dirname, "..", "..", "..", "lib");
+    var abiDocs = abiParser.parseTree(abiLibDir);
+    // Namespaces whose owning file is a defineGuard / defineParser call —
+    // walked directly (not via b.guardAll.allGuards(), which only
+    // aggregates the gate-bearing content/filename/identifier guards and
+    // omits the defineParser line-protocol guards).
+    var factoryNsList = [];
+    Object.keys(abiDocs).forEach(function (file) {
+      var rec = abiDocs[file];
+      if (rec.factory && rec.module && rec.module.tags && rec.module.tags.module) {
+        factoryNsList.push(rec.module.tags.module.replace(/^\s*b\./, ""));
+      }
+    });
+    var abiEntries = autoSiteEntries.deriveFromLib(abiLibDir);
+    var nsToSlug = {};
+    abiEntries.forEach(function (e) {
+      (e.namespaces || []).forEach(function (ns) { nsToSlug[ns] = e.slug; });
+    });
+    var pageCache = {};
+    var abiFailures = [];
+    var abiMethodsChecked = 0;
+    var abiGuardsChecked = 0;
+    for (var agi = 0; agi < factoryNsList.length; agi++) {
+      var nsKey = factoryNsList[agi];
+      var guardObj = bCore[nsKey];
+      if (!guardObj || typeof guardObj !== "object") { abiFailures.push(nsKey + " has no b.<ns> runtime binding"); continue; }
+      var slug = nsToSlug[nsKey];
+      if (!slug) { abiFailures.push(nsKey + " has no derived wiki page slug"); continue; }
+      abiGuardsChecked++;
+      // Required methods: every PUBLIC function export that isn't the error
+      // class. Underscore-prefixed names are private by convention (the wiki
+      // renderer + comment-block validator filter them too) — they carry no
+      // @primitive block and render no section, so they are not required here.
+      var required = Object.keys(guardObj).filter(function (k) {
+        var v = guardObj[k];
+        if (typeof v !== "function") return false;             // skip constants
+        if (v.prototype instanceof Error) return false;        // skip the error class
+        if (k.charAt(0) === "_") return false;                 // skip private (underscore) exports
+        return true;
+      });
+      // Fetch the page once per slug.
+      if (!pageCache[slug]) {
+        var gp = await _request({
+          method: "GET", host: "127.0.0.1", port: info.port, path: "/" + slug,
+          headers: BROWSER_HEADERS,
+        });
+        pageCache[slug] = gp.statusCode === 200 ? gp.body : null;
+        if (pageCache[slug] === null) { abiFailures.push("/" + slug + " -> " + gp.statusCode); }
+      }
+      var pageBody = pageCache[slug];
+      if (!pageBody) continue;
+      for (var rqi = 0; rqi < required.length; rqi++) {
+        var method = required[rqi];
+        abiMethodsChecked++;
+        // A rendered section is `<h2|h3 id="...">b.<ns>.<method>(...) ...`.
+        // Match the signature heading text — the method name immediately
+        // after `b.<ns>.` and followed by `(` or whitespace / `<`.
+        var sig = "b." + nsKey + "." + method;
+        var headingRe = new RegExp(
+          "<h[23][^>]*>\\s*" + sig.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "\\s*(?:\\(|<|\\s)");  // allow:dynamic-regex — nsKey/method come from runtime export keys (identifier chars); the full metacharacter escape (incl. backslash) keeps the constructed RegExp injection-safe regardless
+        if (!headingRe.test(pageBody)) {
+          abiFailures.push(sig + " — not rendered as a section on /" + slug);
+        }
+      }
+    }
+    assert("guard-abi-completeness: every factory-guard runtime method (" + abiMethodsChecked +
+      " across " + abiGuardsChecked + " factory guards) renders a wiki section (" +
+      abiFailures.length + " missing)",
+      abiMethodsChecked > 0 && abiFailures.length === 0);
+    if (abiFailures.length > 0) {
+      abiFailures.forEach(function (f) { console.error("  guard-abi: " + f); });
+    }
+
     // ---- env-var snapshot gate ----
     // Catches drift between the wiki's source `process.env.X` reads,
     // the framework's `safeEnv.readVar("X")` reads (in lib/), and the