@bongos/core 1.19.203 → 1.19.204

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.203",
-  "core_contract": "1.19.203",
-  "source_commit": "3596d383ae4955438fc6ab7f9599e680ddafb570",
+  "core_version": "1.19.204",
+  "core_contract": "1.19.204",
+  "source_commit": "1b831b99695f793cf8d6e7fdf248e20ea2486c77",
   "source_ref": "HEAD",
-  "built_at": "2026-08-17T19:20:16.116Z",
+  "built_at": "2026-08-17T19:29:56.265Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 310,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1295,
+    "functional_verbatim": 1296,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1626,
-  "tree_sha256": "d4a2fd8d4540f54177859f2312a5a48c6539b34b12e1e61757d0b242f92be615",
+  "file_count": 1627,
+  "tree_sha256": "a44dd13817d43a88eb9a226b742a2c039888e0390bf5a5cb428c312e95db4aaf",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -4127,7 +4127,7 @@
     {
       "path": "modules/security/routes/scans.js",
       "mode": "0000644",
-      "sha256": "008bee59c78d7e67726f30d770da81b5c16f4fe01905f22a47a5d2ab6c5e68d8"
+      "sha256": "c32d481210539609844d3c9abd8ccb3dd349a512d055e2a9f8bc055105b29c08"
     },
     {
       "path": "modules/security/scan-store.js",
@@ -4169,6 +4169,11 @@
       "mode": "0000644",
       "sha256": "4af88247bed3dcb3c12370e48380625871a9b50a0b430a6da34db0ce6d6c8aca"
     },
+    {
+      "path": "modules/security/tests/scan_route_schema.mjs",
+      "mode": "0000644",
+      "sha256": "434e69a1bfd9da64462f7f063336cc3b31c19c7643bb33692a45b18cef2ce5f6"
+    },
     {
       "path": "modules/security/tests/scan_store.mjs",
       "mode": "0000644",
@@ -4272,12 +4277,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "30f113e605eea7d404a3393045402c6234a6822724656d0830a5a553a6215fac"
+      "sha256": "45a21ec8d9e8ffae13d85a59beb598f381a10fb85746c42888f0b8c3be098e0f"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "fa8341a0a90d43e710d3f9e04589ce7f055c8f180cf915f28fa074b0b9206977"
+      "sha256": "07c27a2b49959b9022ad8465bc02abe9fbce3bceb9068385a457d01c32423f0f"
     },
     {
       "path": "public-docs/index.html",
@@ -4942,7 +4947,7 @@
     {
       "path": "scripts/gds/gen-api-docs.js",
       "mode": "0000644",
-      "sha256": "ccdebd47cc53a4896c766c6a70f43dfb91e3b84264b82bd927c918ac941a6905"
+      "sha256": "03b4263f19c0f7157160011f43a174599e5294f0b62fdaf3a6e943e9bfeec855"
     },
     {
       "path": "scripts/gds/gen-atlas.js",
@@ -5887,7 +5892,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "f5b425d9be5b552f40d72f31cd96dbcb901b15478ed7a60a35221aaeb09b4fb7"
+      "sha256": "acfdae5a37ae7fa878a752cb566ec930dec8a7703cb86ef9d16609f6ec8c1bab"
     },
     {
       "path": "src/module-loader/catalog.js",

package/modules/security/routes/scans.js

@@ -23,18 +23,50 @@ const { validateOrRespond } = api;
 // Interposed BEFORE api.requireRank so a Xenos gets the documented degraded
 // path instead of the generic rank refusal. Anyone Metic+ falls through to the
 // real gate (which fitness/route-rank-check reads as this route's rank).
+// try-first: a throw here (e.g. a doorway-version skew dropping
+// rankMeetsThreshold) must answer NAMED, never fall to the global
+// internal_error net — the failure mode of the first real scan (task 1003057).
 function xenosDegradedPath(req, res, next) {
-  if (api.rankMeetsThreshold(req.builder?.rank, 'metic')) return next();
-  return res.fail('scan_row_requires_metic', 403, {
-    degraded_path:
-      'Your scan itself is unaffected — keep the report file in your user directory and the chat summary. ' +
-      'What your rank cannot do is write the SHARED scan record other builders query. ' +
-      'Ask any Metic+ builder to POST this scan, or re-run the record step after promotion.',
-    kept: ['report_file', 'chat_summary'],
-    not_recorded: ['gds_scan_row'],
-  });
+  try {
+    if (api.rankMeetsThreshold(req.builder?.rank, 'metic')) return next();
+    return res.fail('scan_row_requires_metic', 403, {
+      degraded_path:
+        'Your scan itself is unaffected — keep the report file in your user directory and the chat summary. ' +
+        'What your rank cannot do is write the SHARED scan record other builders query. ' +
+        'Ask any Metic+ builder to POST this scan, or re-run the record step after promotion.',
+      kept: ['report_file', 'chat_summary'],
+      not_recorded: ['gds_scan_row'],
+    });
+  } catch (err) {
+    console.error('[gds] scans gate', err);
+    return res.fail('scan_record_failed', 500);
+  }
 }
 
+// Built ONCE at module scope, not per request: the [...scanStore.X] spreads
+// mean a missing/renamed scan-store export now crashes at BOOT with a named
+// stack in the server log, instead of throwing on every request forever while
+// the route "exists". Deep checks stay in scanStore.normalizeScanPayload.
+const SCAN_ROW_SCHEMA = Object.freeze({
+  target_url:        { required: true, type: 'string', maxLength: 2048, minLength: 9 },
+  artifact_kind:     { required: true, type: 'string', enum: [...scanStore.ARTIFACT_KINDS] },
+  resolved_sha:      { type: 'string', maxLength: 40 },
+  content_hash:      { type: 'string', maxLength: 64 },
+  file_count:        { type: 'integer', min: 0 },
+  total_bytes:       { type: 'integer', min: 0 },
+  tier:              { required: true, type: 'string', enum: [...scanStore.TIERS] },
+  verdict:           { type: 'string', enum: [...scanStore.VERDICTS] },
+  completion:        { required: true, type: 'string', enum: [...scanStore.COMPLETIONS] },
+  abort_code:        { type: 'string', maxLength: 64 },
+  findings_critical: { type: 'integer', min: 0 },
+  findings_high:     { type: 'integer', min: 0 },
+  findings_medium:   { type: 'integer', min: 0 },
+  findings_low:      { type: 'integer', min: 0 },
+  findings_summary:  { type: 'array' },
+  action_taken:      { type: 'string', enum: [...scanStore.ACTIONS] },
+  engine_version:    { required: true, type: 'string', maxLength: 64, minLength: 1 },
+});
+
 module.exports = function buildSecurityScansRouter() {
   const router = express.Router();
 
@@ -52,35 +84,20 @@ module.exports = function buildSecurityScansRouter() {
     xenosDegradedPath,
     api.requireRank('metic', 'archon'),
     async (req, res) => {
-      if (validateOrRespond(req, res, {
-        target_url:        { required: true, type: 'string', maxLength: 2048, minLength: 9 },
-        artifact_kind:     { required: true, type: 'string', enum: [...scanStore.ARTIFACT_KINDS] },
-        resolved_sha:      { type: 'string', maxLength: 40 },
-        content_hash:      { type: 'string', maxLength: 64 },
-        file_count:        { type: 'integer', min: 0 },
-        total_bytes:       { type: 'integer', min: 0 },
-        tier:              { required: true, type: 'string', enum: [...scanStore.TIERS] },
-        verdict:           { type: 'string', enum: [...scanStore.VERDICTS] },
-        completion:        { required: true, type: 'string', enum: [...scanStore.COMPLETIONS] },
-        abort_code:        { type: 'string', maxLength: 64 },
-        findings_critical: { type: 'integer', min: 0 },
-        findings_high:     { type: 'integer', min: 0 },
-        findings_medium:   { type: 'integer', min: 0 },
-        findings_low:      { type: 'integer', min: 0 },
-        findings_summary:  { type: 'array' },
-        action_taken:      { type: 'string', enum: [...scanStore.ACTIONS] },
-        engine_version:    { required: true, type: 'string', maxLength: 64, minLength: 1 },
-      })) return;
+      try {
+        if (validateOrRespond(req, res, SCAN_ROW_SCHEMA)) return;
 
-      const norm = scanStore.normalizeScanPayload(req.body);
-      if (!norm.ok) return res.fail(norm.code, 400, norm.detail);
+        const norm = scanStore.normalizeScanPayload(req.body);
+        if (!norm.ok) return res.fail(norm.code, 400, norm.detail);
 
-      try {
         const scan = await scanStore.insertScan(norm.value, req.builder.id);
         res.status(201).json({ ok: true, scan });
       } catch (err) {
+        // NO statement in this handler runs outside the try: any throw —
+        // validator, normalizer, or insert — answers this named envelope with
+        // the stack in the server log, never the global internal_error net.
         console.error('[gds] POST /security/scans', err);
-        res.fail('scan_record_failed', 500);
+        if (!res.headersSent) res.fail('scan_record_failed', 500);
       }
     }
   );
@@ -113,3 +130,7 @@ module.exports = function buildSecurityScansRouter() {
 
   return router;
 };
+
+// Exposed for the schema-contract test (scan_route_schema.mjs): every enum
+// spread must resolve at require time, and required fields must stay pinned.
+module.exports.SCAN_ROW_SCHEMA = SCAN_ROW_SCHEMA;

package/modules/security/tests/scan_route_schema.mjs

@@ -0,0 +1,69 @@
+// routes/scans.js failure-path contract (task 1003057, idea 1000781).
+//
+// The first real scan could not record its row: live answered 500
+// {internal_error} for EVERY POST body — even an invalid tier that should have
+// produced a named 400 — meaning the handler threw before validation could
+// answer and the global error net swallowed the name. Two properties keep that
+// class of failure loud and named from now on:
+//
+//   1. The request schema (with its [...scanStore.X] enum spreads) is built at
+//      MODULE SCOPE — a missing/renamed scan-store export now crashes at boot
+//      (named, in the server log) instead of throwing per-request forever.
+//   2. Every failure inside the POST handler answers a NAMED envelope
+//      (scan_record_failed at worst) — internal_error must never escape it.
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const scansRoute = require('../routes/scans.js');
+const scanStore = require('../scan-store.js');
+
+const routeSource = readFileSync(
+  path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'routes', 'scans.js'),
+  'utf8'
+);
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+await test('the POST schema exists at module scope with every enum resolved', () => {
+  const schema = scansRoute.SCAN_ROW_SCHEMA;
+  assert.ok(schema && typeof schema === 'object', 'SCAN_ROW_SCHEMA must be exported');
+  assert.deepEqual(schema.tier.enum, [...scanStore.TIERS]);
+  assert.deepEqual(schema.artifact_kind.enum, [...scanStore.ARTIFACT_KINDS]);
+  assert.deepEqual(schema.verdict.enum, [...scanStore.VERDICTS]);
+  assert.deepEqual(schema.completion.enum, [...scanStore.COMPLETIONS]);
+  assert.deepEqual(schema.action_taken.enum, [...scanStore.ACTIONS]);
+  for (const field of ['target_url', 'artifact_kind', 'tier', 'completion', 'engine_version']) {
+    assert.equal(schema[field].required, true, `${field} must stay required`);
+  }
+  // Every enum really resolved — an undefined spread here is exactly the
+  // per-request TypeError class this test exists to prevent.
+  for (const [field, rule] of Object.entries(schema)) {
+    if (rule.enum) assert.ok(rule.enum.length > 0, `${field}.enum resolved empty`);
+  }
+});
+
+await test('the POST handler body opens with try and answers scan_record_failed on any throw', () => {
+  // Source-shape pin (the route-rank-check idiom): the async handler must not
+  // run ANY statement outside its try, and the catch must answer a named code.
+  assert.match(routeSource, /async \(req, res\) => \{\s*\n\s*try \{/,
+    'POST handler must enter try before its first statement');
+  assert.match(routeSource, /res\.fail\('scan_record_failed', 500\)/,
+    'the catch must answer the named scan_record_failed envelope');
+});
+
+await test('the xenos degraded-path gate cannot throw unnamed', () => {
+  assert.match(routeSource, /function xenosDegradedPath\(req, res, next\) \{\s*\n\s*try \{/,
+    'xenosDegradedPath must enter try before its first statement');
+});
+
+console.log(`\nscan_route_schema: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.203",
+  "version": "1.19.204",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.203",
+      "version": "1.19.204",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.203",
+  "version": "1.19.204",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/gen-api-docs.js

@@ -412,7 +412,23 @@ function extractBody(lines, i, method, constants = {}) {
   let strict = false;
   if (validateCall) {
     const after = validateCall.index + validateCall[0].length;
-    const lit = captureBalanced(window, after);
+    let lit = captureBalanced(window, after);
+    // captureBalanced seeks the NEXT '{' anywhere — when the third argument is
+    // an identifier, that grabs some unrelated later block. Only trust the
+    // capture when the brace directly follows the call.
+    if (lit && !/^\s*\{/.test(window.slice(after))) lit = null;
+    if (!lit) {
+      // Schema hoisted to a module-scope const (the boot-loud enum-spread
+      // pattern, task 1003057): resolve `validateOrRespond(req, res, IDENT)`
+      // against `const IDENT = [Object.freeze(] { … }` anywhere in the file,
+      // so hoisting a schema never silently drops a route from the API docs.
+      const ident = /^\s*([A-Za-z_$][\w$]*)\s*[,)]/.exec(window.slice(after));
+      if (ident) {
+        const whole = stripComments(lines.join('\n'));
+        const decl = new RegExp(`const\\s+${ident[1]}\\s*=\\s*(?:Object\\.freeze\\s*\\(\\s*)?`).exec(whole);
+        if (decl) lit = captureBalanced(whole, decl.index + decl[0].length);
+      }
+    }
     if (lit) {
       for (const { key, value } of topLevelEntries(lit)) {
         if (/^\d/.test(key)) continue; // defensive: no numeric-leading field names
@@ -420,8 +436,11 @@ function extractBody(lines, i, method, constants = {}) {
         rules[key] = parseRule(value, constants);
       }
       if (orRespond) {
-        // The opts arg follows the schema literal; strict unless it passes strict:false.
-        const optsWindow = window.slice(window.indexOf(lit, after) + lit.length);
+        // The opts arg follows the schema literal; strict unless it passes
+        // strict:false. When the schema was resolved from a module-scope const,
+        // the literal is not in the window — read the call tail instead.
+        const litAt = window.indexOf(lit, after);
+        const optsWindow = litAt >= 0 ? window.slice(litAt + lit.length) : window.slice(after);
         strict = !/\bstrict\s*:\s*false\b/.test(optsWindow);
       }
     }

package/src/module-api.js

@@ -833,8 +833,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.201 with no explicit bump. run 32059276345. (task 1002620)
 //   1.19.203 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.202 with no explicit bump. run 32059705946. (task 1002620)
+//   1.19.204 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.203 with no explicit bump. run 32060607072. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.203'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.204'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');