@bongos/core 1.19.1047 → 1.19.1048

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.1047",
-  "core_contract": "1.19.1047",
-  "source_commit": "a83322a2af0bab901b143a098fb0a5cc337f9e64",
+  "core_version": "1.19.1048",
+  "core_contract": "1.19.1048",
+  "source_commit": "64aa3088cc068647e5de41e2f87ab9fc416debb7",
   "source_ref": "HEAD",
-  "built_at": "2026-09-26T23:42:01.064Z",
+  "built_at": "2026-09-27T01:33:19.203Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 543,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2512,
+    "functional_verbatim": 2513,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3082,
-  "tree_sha256": "0fdbcc97739c2b07898a2eb701e2f0a991cf6b1f173450143e6df73720b60231",
+  "file_count": 3083,
+  "tree_sha256": "6f357e234dc4c052c43532cc7d280e9a51fa2731009c99e74eda18ec0ef06164",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2772,7 +2772,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "de85c4f3489d17d7b82c0cc64a3049a1cba09589f67e551ffcafbc9354ec3a8d"
+      "sha256": "425c39cac8e66f234ff1558841f45fa8d33eaad6311b5ee3c0f6ebaa7e9dc7fe"
     },
     {
       "path": "docs/modules-contract.md",
@@ -6812,7 +6812,7 @@
     {
       "path": "modules/platform-identity/read-rate-limit.js",
       "mode": "0000644",
-      "sha256": "db17891c79447950b68d55e6e81db6f3c524491bac5ee1caa375b0611c3248c7"
+      "sha256": "dc11b89460e4cca22af1ab61672104ac99298f477c1bad890d688f87456494fa"
     },
     {
       "path": "modules/platform-identity/recruiter-sliver.js",
@@ -6862,7 +6862,7 @@
     {
       "path": "modules/platform-identity/routes/public-profile.js",
       "mode": "0000644",
-      "sha256": "e59f99d6f323e70611a08fa2c8299af815e350dbb81bd7cc79e9d96bd93cdbba"
+      "sha256": "141aab9e7f1bd513d4d3c5d6e6ef51aa2e3cbfd138ee7fae60be6f52cfedb080"
     },
     {
       "path": "modules/platform-identity/routes/scouting.js",
@@ -7152,7 +7152,7 @@
     {
       "path": "modules/provisioning/rate-limit.js",
       "mode": "0000644",
-      "sha256": "27046325beffad5d1edfcc91c331048038900ef7d32f1d38796755c7990ba202"
+      "sha256": "b9cad1df215eba3dc415dc5a4ac8ade054dd53a823ce0ad0a5e5303be84df876"
     },
     {
       "path": "modules/provisioning/recommendations.js",
@@ -8497,12 +8497,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "71c9088d184288d783c7ca384d4cff140ec48251157bb3557c5c76854d1829e8"
+      "sha256": "f8821b1b474225bcb1658d4ccee4aca9c9439f6757ee8624f36643af567d39e0"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "888aceb332ce59d940cc7c4b42b63a896d773a387b957e7581a10f9b4d2a56be"
+      "sha256": "5fa9fe3e161288c87dacff6bc04ef6a4f9c1e7c0f0f5b8684ec2c887dd289484"
     },
     {
       "path": "public-docs/index.html",
@@ -8522,7 +8522,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "b2e95686e68d9e0321f3dba1807d8747ff43f2739aa3738c7d0eed8516eb20cd"
+      "sha256": "4b8836320c211dcd59f9f978755c247998fbc3bbbfc78d4aaa073a3051f367f0"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -10377,7 +10377,7 @@
     {
       "path": "src/bongos/middleware/rate-limit.js",
       "mode": "0000644",
-      "sha256": "d19b83f04b32d5ca942fb2ed3a210af6ef8607e3e9c949338f816337a3b6cf8c"
+      "sha256": "2c4cb05109bd3a931acba1967e1d01e4c3c069273d22b4356211aac103a04781"
     },
     {
       "path": "src/bongos/module-overrides.js",
@@ -10452,7 +10452,7 @@
     {
       "path": "src/bongos/routes.js",
       "mode": "0000644",
-      "sha256": "274cbf93d292dfb1d605ad318f5d94def6c05a06e71a14f7a47360f168045e1b"
+      "sha256": "c165e3ee08a2d48ab16f5b9889b26ed831131439ea69368f2eab512d4680dee2"
     },
     {
       "path": "src/bongos/routes/CLAUDE.md",
@@ -10497,7 +10497,7 @@
     {
       "path": "src/bongos/routes/healthz.js",
       "mode": "0000644",
-      "sha256": "5d22031a1acd21a9a244d9f68809450e811fe6a6c98a2f4e2330452515757c37"
+      "sha256": "6adb006126407f87e3d57d7a9c6c283fcc0d713d6f8c4ce0ba403692edf7fea2"
     },
     {
       "path": "src/bongos/routes/instance.js",
@@ -10592,7 +10592,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "948f2239e756563cee5b97cc98254d5041e1edcb283139087f7e07bbf3368441"
+      "sha256": "097ef7d2d748ad98273257de5771d10d2ffa523e558ff8b3de6b039aeecfab1f"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -14214,6 +14214,11 @@
       "mode": "0000644",
       "sha256": "caa611e8f29f1ac55e2c15d139e90f064b69b17f8b77517d888218f17ce23dc8"
     },
+    {
+      "path": "tests/read_default_meter.mjs",
+      "mode": "0000644",
+      "sha256": "63f169b03605bc96a89107fdd1395672383d8e282141ddf02cc6dd076793f072"
+    },
     {
       "path": "tests/read_session_export.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -2581,5 +2581,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.1045 with no explicit bump. run 36265788618. (task 1002620)
   1.19.1047 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.1046 with no explicit bump. run 36280220559. (task 1002620)
+  1.19.1048 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1047 with no explicit bump. run 36285856717. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/platform-identity/read-rate-limit.js

@@ -33,7 +33,7 @@ function createReadRateLimit({ scope, limit, windowMs = 60 * 1000, maxTrackedIps
   }, SWEEP_EVERY_MS);
   if (typeof sweepTimer.unref === 'function') sweepTimer.unref();
 
-  return function readRateLimit(req, res, next) {
+  const limiter = function readRateLimit(req, res, next) {
     const now = Date.now();
     const key = req.ip || req.socket?.remoteAddress || 'unknown';
     let bucket = buckets.get(key);
@@ -57,6 +57,10 @@ function createReadRateLimit({ scope, limit, windowMs = 60 * 1000, maxTrackedIps
     bucket.push(now);
     return next();
   };
+  // Self-metered tag (task 1003883): the core's default read ceiling skips a route carrying
+  // one, so this surface is not also counted in a second, looser bucket. See rate-limit.js.
+  limiter.meteredScope = scope;
+  return limiter;
 }
 
 module.exports = { createReadRateLimit, MAX_TRACKED_IPS };

package/modules/platform-identity/routes/public-profile.js

@@ -56,6 +56,10 @@ function profileReadRateLimit(req, res, next) {
   return next();
 }
 
+// Self-metered tag (task 1003883): the core's default read ceiling skips a route that
+// carries one, so this surface is not also counted in a second bucket. See rate-limit.js.
+profileReadRateLimit.meteredScope = 'public-profile-read';
+
 module.exports = function publicProfileRoutes() {
   const router = express.Router();
 

package/modules/provisioning/rate-limit.js

@@ -26,7 +26,7 @@ function clientIp(req) {
 
 function makeAskRateLimiter({ windowMs = 60_000, max = 60, now = Date.now, key = clientIp } = {}) {
   const buckets = new Map(); // key -> array of recent hit timestamps within the window
-  return function askRateLimit(req, res, next) {
+  const limiter = function askRateLimit(req, res, next) {
     const t = now();
     const ip = key(req) || 'unknown';
     // Prune this caller's bucket to the window, then decide.
@@ -40,6 +40,12 @@ function makeAskRateLimiter({ windowMs = 60_000, max = 60, now = Date.now, key =
     buckets.set(ip, hits);
     return next();
   };
+  // Tag it as a self-metered route (task 1003883): the core's default read ceiling skips
+  // any route carrying a `meteredScope`, so a route behind THIS limiter is not counted a
+  // second time in a looser bucket. Plain property, no import — a module reaches core only
+  // through the doorway, and the convention is the contract (see rate-limit.js).
+  limiter.meteredScope = 'provisioning-ask';
+  return limiter;
 }
 
 module.exports = { makeAskRateLimiter, clientIp };

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1047",
+  "version": "1.19.1048",
   "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/release-notes.json

@@ -7583,5 +7583,11 @@
       "id": "1004306",
       "text": "An update that would be refused no longer takes a database backup first, and the server keeps only the ten newest pre-update backups, so frequent update checks can't fill the disk."
     }
+  ],
+  "1.19.1048": [
+    {
+      "id": "1003883",
+      "text": "Public read endpoints are now rate-limited by default, so a newly added endpoint can no longer go live unprotected; existing protected endpoints keep their own limits."
+    }
   ]
 }

package/src/bongos/middleware/rate-limit.js

@@ -70,6 +70,22 @@
 //                            route's Cache-Control) while capping a
 //                            cache-ignoring scraper at ~2 req/s.
 //
+//   6. DEFAULT read limiter — 600 reads / 60s per IP on EVERY GET/HEAD whose route
+//                            does not carry its own meter (task 1003883, owner
+//                            decision 2026-09-13: metered is the default, a route
+//                            opts OUT). #3-#5 and the provisioning pair were each
+//                            mounted by hand after a red-team finding (tasks 1035,
+//                            1003339, 1002327, 1945), which is fail-open: every new
+//                            public read was unmetered until a reviewer remembered.
+//                            This inverts it. It is a CEILING, deliberately far
+//                            above the per-surface budgets, so it never tightens an
+//                            honest client and never becomes a second, looser bucket
+//                            on a surface that already has its own: a route that
+//                            carries a `meteredScope` tag (every per-surface limiter
+//                            wears one) or `readLimitOptOut(reason)` is NOT counted
+//                            here (the ADR 0209 double-rate trap). See the block
+//                            above module.exports.
+//
 // Any limiter tripping → 429 with Retry-After (seconds rounded up to the
 // nearest whole second). Audit middleware still fires on a write 429 — the row
 // in audit_log is forensic value for "who tried too hard." (Reads are never
@@ -96,6 +112,13 @@ const ACCOUNT_EXISTENCE_WINDOW_MS = 60 * 1000;
 const ACCOUNT_EXISTENCE_LIMIT     = 120;
 const PROJECT_FEED_WINDOW_MS = 60 * 1000;
 const PROJECT_FEED_LIMIT     = 120;
+const DEFAULT_READ_WINDOW_MS = 60 * 1000;
+const DEFAULT_READ_LIMIT     = 600;
+// Cap on tracked IPs for the default ceiling — it sees the whole read surface, so an
+// address-rotating caller must not be able to grow the map without bound between sweeps
+// (same bound as modules/platform-identity/read-rate-limit.js).
+const DEFAULT_READ_MAX_TRACKED_IPS = 10000;
+const OPT_OUT_REASON_MIN_LENGTH = 20;
 const SWEEP_MS              = 5 * 60 * 1000;
 
 const ipBuckets         = new Map();
@@ -106,6 +129,8 @@ const publicReadBuckets = new Map();
 const accountExistenceBuckets = new Map();
 // Limiter #5's bucket map — the public projects feed (task 1002327, ADR 0252 §5.3).
 const projectFeedBuckets = new Map();
+// Limiter #6's bucket map — the default read ceiling (task 1003883).
+const defaultReadBuckets = new Map();
 
 const WRITE_METHODS = new Set(['POST', 'PATCH', 'PUT', 'DELETE']);
 // HEAD is metered too: Express runs the GET handler (incl. the DB query) for a
@@ -175,6 +200,10 @@ function sweep() {
     pruneAndCount(arr, now, PROJECT_FEED_WINDOW_MS);
     if (arr.length === 0) projectFeedBuckets.delete(k);
   }
+  for (const [k, arr] of defaultReadBuckets) {
+    pruneAndCount(arr, now, DEFAULT_READ_WINDOW_MS);
+    if (arr.length === 0) defaultReadBuckets.delete(k);
+  }
 }
 
 // Schedule the sweep. unref() so it doesn't keep the process alive during
@@ -258,12 +287,18 @@ function publicReadRateLimitMiddleware(req, res, next) {
 // names that budget in the 429 body + headers so a caller can tell which ceiling
 // it hit. Keyed on req.ip — the same real-client-IP resolution the write limiter
 // uses (Caddy forwards the client IP, server sets 'trust proxy').
-function perIpSlidingWindow(buckets, { limit, windowMs, scope }) {
-  return function slidingWindowRateLimit(req, res, next) {
+function perIpSlidingWindow(buckets, { limit, windowMs, scope, maxTracked = Infinity }) {
+  return markMetered(function slidingWindowRateLimit(req, res, next) {
     const now = Date.now();
     const ip = req.ip || req.socket?.remoteAddress || 'unknown';
     let bucket = buckets.get(ip);
-    if (!bucket) { bucket = []; buckets.set(ip, bucket); }
+    if (!bucket) {
+      // Bound the map: a caller rotating source addresses (an IPv6 /64) mints a fresh
+      // bucket per request. Evict the longest-tracked entry (Map iterates oldest first).
+      if (buckets.size >= maxTracked) buckets.delete(buckets.keys().next().value);
+      bucket = [];
+      buckets.set(ip, bucket);
+    }
     if (pruneAndCount(bucket, now, windowMs) >= limit) {
       const retryAfter = Math.max(1, Math.ceil((bucket[0] + windowMs - now) / 1000));
       res.set('Retry-After', String(retryAfter));
@@ -274,7 +309,7 @@ function perIpSlidingWindow(buckets, { limit, windowMs, scope }) {
     }
     bucket.push(now);
     return next();
-  };
+  }, scope);
 }
 
 // accountExistenceReadRateLimit — limiter #4 in the header. ONE instance, mounted
@@ -299,11 +334,123 @@ const publicProjectFeedRateLimit = perIpSlidingWindow(projectFeedBuckets, {
   scope: 'public-project-feed',
 });
 
+// ── the default read ceiling (limiter #6, task 1003883) ─────────────────────────
+//
+// HOW A ROUTE OPTS OUT. A read route is exempt from the default ceiling when one of the
+// handlers on it carries a `meteredScope` string — the tag every per-surface limiter above
+// wears (`perIpSlidingWindow` and `publicReadRateLimitMiddleware` set it), and which
+// `readLimitOptOut(reason)` puts on a route that needs no meter at all. Grep `meteredScope`
+// or `readLimitOptOut` to list them. The tag is what makes the exemption impossible to
+// forget in the OTHER direction: a surface that has its own budget IS the one that is not
+// counted here, so it can never end up with a second, looser bucket (the ADR 0209 trap).
+//
+// WHY A WALK OF THE ROUTER, NOT A TABLE. A table of exempt paths in this file would have to
+// name the modules that own them (the kernel must stay module-agnostic) and would drift
+// from the route files. The tag lives on the route, so the route file is the declaration.
+// The default limiter is mounted FIRST, before any route exists to inspect, so it reads the
+// composed router lazily on the first read and asks Express's own layer matching whether
+// the request lands on a tagged route.
+//
+// EXPRESS 4 DEPENDENCY. This leans on Layer#match, Route#_handles_method and Layer#path /
+// #regexp, which are Express 4 internals. tests/read_default_meter.mjs asserts the major
+// version and the production exempt set, so an upgrade fails there, loudly, instead of
+// quietly changing which reads are metered. Layer#match writes layer.path/params; that is
+// safe only because the walk is synchronous and Express re-matches each layer itself when
+// it dispatches. The exempt list is read once, on the first read: a router mounted after
+// traffic starts is not seen (every mount happens in buildGdsRouter, before listen).
+function markMetered(fn, scope) {
+  fn.meteredScope = scope;
+  return fn;
+}
+markMetered(publicReadRateLimitMiddleware, 'public-read');
+
+// readLimitOptOut(reason) — an explicit, visible opt-out for a read route that must not be
+// metered by the default (a liveness probe). `router.get('/healthz', readLimitOptOut('…'), h)`.
+function readLimitOptOut(reason) {
+  if (typeof reason !== 'string' || reason.trim().length < OPT_OUT_REASON_MIN_LENGTH) {
+    throw new Error(`readLimitOptOut needs a reason of at least ${OPT_OUT_REASON_MIN_LENGTH} characters saying why this read is not metered`);
+  }
+  return markMetered(function readLimitOptOutMarker(_req, _res, next) { next(); }, 'opt-out');
+}
+
+// Every route (and mount) on the router that carries a `meteredScope` handler, as chains of
+// the Express layers to match in order. Nested routers extend the chain; a tagged
+// `router.use(prefix, limiter)` ends it on a prefix layer.
+function collectSelfMetered(stack, chain = [], out = [], seen = new Set()) {
+  if (!Array.isArray(stack) || seen.has(stack)) return out;
+  seen.add(stack);
+  for (const layer of stack) {
+    if (layer.route && Array.isArray(layer.route.stack)) {
+      const tag = layer.route.stack.map((l) => l.handle && l.handle.meteredScope).find(Boolean);
+      if (tag) out.push({ scope: tag, chain: [...chain, layer], route: layer.route });
+    } else if (layer.handle && Array.isArray(layer.handle.stack)) {
+      collectSelfMetered(layer.handle.stack, [...chain, layer], out, seen);
+    } else if (layer.handle && layer.handle.meteredScope) {
+      // A limiter mounted with NO prefix (`router.use(limiter)`) would match every path and
+      // silently exempt the whole API from the ceiling — a fail-open. Only a prefixed mount
+      // can exempt; an unprefixed one is ignored, so those reads stay on the ceiling.
+      if (layer.regexp && layer.regexp.fast_slash) continue;
+      out.push({ scope: layer.handle.meteredScope, chain: [...chain, layer], route: null });
+    }
+  }
+  return out;
+}
+
+// Does the path land on an entry? Mirrors what Express does when it dispatches: a mount
+// layer strips its matched prefix before the next layer sees the rest.
+function entryMatches(entry, method, p) {
+  let rest = p;
+  for (const layer of entry.chain) {
+    if (!layer.match(rest)) return false;
+    if (layer.route) return layer.route._handles_method(method.toLowerCase());
+    rest = rest.slice(String(layer.path || '').length) || '/';
+  }
+  // Ended on a prefix layer holding a tagged limiter: the prefix matching is the answer.
+  return true;
+}
+
+// selfMeteredRoutes(router) — for tests and diagnostics: [{ scope, path }] of the reads that
+// are NOT on the default ceiling. `path` is the route's own (mount-relative) pattern.
+function selfMeteredRoutes(router) {
+  return collectSelfMetered(router.stack).map((e) => ({
+    scope: e.scope,
+    path: e.route ? e.route.path : String(e.chain[e.chain.length - 1].regexp),
+  }));
+}
+
+// defaultReadRateLimit(router) — limiter #6. Mount it ONCE, first, on the router it guards:
+// `router.use(defaultReadRateLimit(router))`. Keyed on req.ip only: keying on a bearer token
+// would let an unauthenticated caller escape the ceiling by attaching any Authorization
+// header.
+function defaultReadRateLimit(router) {
+  const meter = perIpSlidingWindow(defaultReadBuckets, {
+    limit: DEFAULT_READ_LIMIT,
+    windowMs: DEFAULT_READ_WINDOW_MS,
+    scope: 'default-read',
+    maxTracked: DEFAULT_READ_MAX_TRACKED_IPS,
+  });
+  let entries = null;
+  return function defaultReadRateLimitMiddleware(req, res, next) {
+    if (!READ_METHODS.has(req.method)) return next();
+    // Lazy: the router is still being composed when this is mounted. By the first request
+    // it is complete (and every module router has been mounted).
+    if (entries === null) entries = collectSelfMetered(router.stack);
+    for (const e of entries) if (entryMatches(e, req.method, req.path)) return next();
+    return meter(req, res, next);
+  };
+}
+
 module.exports = {
   rateLimitMiddleware,
   publicReadRateLimitMiddleware,
   accountExistenceReadRateLimit,
   publicProjectFeedRateLimit,
+  defaultReadRateLimit,
+  readLimitOptOut,
+  markMetered,
+  selfMeteredRoutes,
+  DEFAULT_READ_LIMIT,
+  DEFAULT_READ_MAX_TRACKED_IPS,
   // exported for tests + the security-baseline-check script
   PER_IP_WINDOW_MS,
   PER_IP_LIMIT,

package/src/bongos/routes/healthz.js

@@ -10,12 +10,13 @@
 
 const express = require('express');
 const auth = require('../auth');
+const { readLimitOptOut } = require('../middleware/rate-limit');
 
 module.exports = function buildHealthzRouter() {
   const router = express.Router();
 
   // rank: public — liveness probe; the status dashboard (status.<apex>) hits this anonymously.
-  router.get('/healthz', async (_req, res) => {
+  router.get('/healthz', readLimitOptOut('a liveness probe must answer 200 while everything else is being throttled'), async (_req, res) => {
     res.json({
       ok: true,
       auth_configured: auth.authConfigured(),

package/src/bongos/routes.js

@@ -68,7 +68,7 @@ const buildLlmCacheRouter = require('./routes/llm-cache');
 const { isModuleEnabled } = require('../modules');
 const moduleLoader = require('../module-loader/loader');
 const { auditMiddleware } = require('./middleware/audit');
-const { rateLimitMiddleware } = require('./middleware/rate-limit');
+const { rateLimitMiddleware, defaultReadRateLimit } = require('./middleware/rate-limit');
 const { attachFail, errorEnvelopeHandler } = require('./middleware/error-envelope');
 const { hardenRouterStack } = require('./routes/_helpers');
 
@@ -128,9 +128,13 @@ function buildGdsRouter() {
   router.use(auditMiddleware());
 
   // Rate-limit middleware (V3.R34 #255) — sliding-window in-memory limiter.
-  // 30 writes/min per IP, 60 writes/min per session. Reads uncapped.
+  // 30 writes/min per IP, 60 writes/min per session.
   // 429 + Retry-After + X-RateLimit-* headers on trip.
   router.use(rateLimitMiddleware);
+  // Reads are METERED BY DEFAULT (task 1003883): a 600/min per-IP ceiling on every
+  // GET/HEAD unless the route carries its own meter (a `meteredScope` tag) or an
+  // explicit readLimitOptOut(reason) — see the default-read block in rate-limit.js.
+  router.use(defaultReadRateLimit(router));
 
   router.use(buildHealthzRouter());
   router.use(buildInstanceRouter());

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.1047'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1048'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/read_default_meter.mjs

@@ -0,0 +1,194 @@
+// tests/read_default_meter.mjs
+//
+// Task 1003883 — API reads are METERED BY DEFAULT; a route opts OUT explicitly.
+//
+// Before this, the two global limiters bypassed reads and each read surface was mounted
+// by hand after a red-team finding (tasks 1035, 1003339, 1002327, 1945), so every NEW
+// public read was unmetered until a reviewer remembered. The default limiter inverts
+// that. A route opts out by carrying a `meteredScope` tag (every per-surface limiter
+// wears one) or `readLimitOptOut(reason)`.
+//
+// Pins (against a REAL Express router, matched by Express's own layers):
+//   1. A read on a route nobody thought about is metered at DEFAULT_READ_LIMIT / 60s per
+//      IP, with the 429 shape + X-RateLimit-Scope: default-read.
+//   2. A route behind its own limiter is NOT counted here (no second bucket — the
+//      ADR 0209 trap), including one inside a nested router and one mounted by prefix.
+//   3. Non-read methods bypass it; HEAD is metered like GET.
+//   4. readLimitOptOut demands a real reason.
+//   5. The composed production router: every read that is exempt is exempt on purpose —
+//      exactly the known per-surface set — so a new tagged route shows up as a diff here.
+//
+// Run:  node --test tests/read_default_meter.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const express = require('express');
+const {
+  defaultReadRateLimit,
+  readLimitOptOut,
+  markMetered,
+  selfMeteredRoutes,
+  publicReadRateLimitMiddleware,
+  accountExistenceReadRateLimit,
+  publicProjectFeedRateLimit,
+  DEFAULT_READ_LIMIT,
+  DEFAULT_READ_MAX_TRACKED_IPS,
+} = require('../src/bongos/middleware/rate-limit.js');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+
+function fakeRes() {
+  const headers = {};
+  const res = {
+    statusCode: 200, headers, body: undefined,
+    set(k, v) { headers[k.toLowerCase()] = String(v); return this; },
+    status(c) { this.statusCode = c; return this; },
+    json(o) { this.body = o; return this; },
+  };
+  attachFail({}, res, () => {});
+  return res;
+}
+function hit(mw, method, p, ip) {
+  const req = { method, path: p, ip, headers: {}, socket: { remoteAddress: ip } };
+  const res = fakeRes();
+  let nexted = false;
+  mw(req, res, () => { nexted = true; });
+  return { res, nexted };
+}
+
+// A router shaped like the real one: unlisted routes, a self-metered route, a nested router
+// mounted at the root (how modules mount), a prefix mount carrying a limiter (/public), and
+// an explicit opt-out.
+const ok = (_req, res) => res.json({});
+function buildRouter() {
+  const router = express.Router();
+  const guard = defaultReadRateLimit(router);
+  router.use(guard);
+  router.get('/plain', ok);
+  router.get('/things/:id', ok);
+  router.post('/plain', ok);
+  router.get('/own-budget', accountExistenceReadRateLimit, ok);
+  router.get('/feed', publicProjectFeedRateLimit, ok);
+  router.get('/probe', readLimitOptOut('a liveness probe must answer while everything else is throttled'), ok);
+  const mod = express.Router();
+  mod.get('/from-module', markMetered((_q, _s, n) => n(), 'module-own'), ok);
+  mod.get('/module-plain', ok);
+  router.use(mod);
+  const pub = express.Router();
+  pub.use('/public', publicReadRateLimitMiddleware);
+  pub.get('/public/uptime', ok);
+  router.use(pub);
+  return { router, guard };
+}
+
+test('a read on a route nobody thought about is metered: DEFAULT_READ_LIMIT pass, then 429', () => {
+  const { guard } = buildRouter();
+  const ip = '198.51.100.1';
+  for (let i = 0; i < DEFAULT_READ_LIMIT; i++) {
+    assert.equal(hit(guard, 'GET', '/plain', ip).nexted, true, `read ${i + 1} passes`);
+  }
+  const { res, nexted } = hit(guard, 'GET', '/plain', ip);
+  assert.equal(nexted, false);
+  assert.equal(res.statusCode, 429);
+  assert.equal(res.headers['x-ratelimit-scope'], 'default-read');
+  assert.ok(Number(res.headers['retry-after']) >= 1);
+});
+
+test('the ceiling is per IP and shared across every unlisted route, param routes included', () => {
+  const { guard } = buildRouter();
+  const a = '198.51.100.2';
+  for (let i = 0; i < DEFAULT_READ_LIMIT; i++) hit(guard, 'GET', i % 2 ? '/plain' : `/things/${i}`, a);
+  assert.equal(hit(guard, 'GET', '/module-plain', a).nexted, false, 'a route in a nested router spends it too');
+  assert.equal(hit(guard, 'GET', '/things/9', '198.51.100.3').nexted, true, 'another IP is untouched');
+});
+
+test('HEAD is metered like GET; a write is not this limiter\'s business', () => {
+  const { guard } = buildRouter();
+  const ip = '198.51.100.4';
+  for (let i = 0; i < DEFAULT_READ_LIMIT; i++) hit(guard, 'HEAD', '/plain', ip);
+  assert.equal(hit(guard, 'GET', '/plain', ip).nexted, false, 'HEAD spent the budget');
+  for (let i = 0; i < 5; i++) assert.equal(hit(guard, 'POST', '/plain', ip).nexted, true);
+});
+
+test('a route with its own meter is not counted here — nested, prefix-mounted and explicit alike', () => {
+  const { guard } = buildRouter();
+  const ip = '198.51.100.5';
+  const exempt = ['/own-budget', '/feed', '/probe', '/from-module', '/public/uptime', '/public/anything'];
+  for (let i = 0; i < DEFAULT_READ_LIMIT + 50; i++) {
+    for (const p of exempt) assert.equal(hit(guard, 'GET', p, ip).nexted, true, `${p} is not on the ceiling`);
+  }
+  assert.equal(hit(guard, 'GET', '/plain', ip).nexted, true, 'and none of that spent the ceiling for everything else');
+});
+
+test('an exhausted ceiling never blocks an opted-out route', () => {
+  const { guard } = buildRouter();
+  const ip = '198.51.100.6';
+  for (let i = 0; i < DEFAULT_READ_LIMIT + 1; i++) hit(guard, 'GET', '/plain', ip);
+  assert.equal(hit(guard, 'GET', '/plain', ip).nexted, false);
+  assert.equal(hit(guard, 'GET', '/probe', ip).nexted, true);
+});
+
+test('prefix opt-outs respect segment boundaries', () => {
+  const { guard } = buildRouter();
+  const ip = '198.51.100.7';
+  for (let i = 0; i < DEFAULT_READ_LIMIT + 1; i++) hit(guard, 'GET', '/plain', ip);
+  assert.equal(hit(guard, 'GET', '/public/x', ip).nexted, true);
+  assert.equal(hit(guard, 'GET', '/publicity', ip).nexted, false, '/publicity is not under /public');
+});
+
+test('the default ceiling bounds its own memory against address rotation', () => {
+  const { guard } = buildRouter();
+  const before = process.memoryUsage().heapUsed;
+  for (let i = 0; i < DEFAULT_READ_MAX_TRACKED_IPS + 500; i++) hit(guard, 'GET', '/plain', `2001:db8::${i.toString(16)}`);
+  // The oldest tracked address was evicted: it gets a fresh bucket rather than a stale one.
+  assert.equal(hit(guard, 'GET', '/plain', '2001:db8::0').nexted, true);
+  assert.ok(process.memoryUsage().heapUsed - before < 200 * 1024 * 1024, 'no runaway growth');
+});
+
+test('a limiter mounted with no prefix cannot exempt the whole API (fails closed)', () => {
+  const router = express.Router();
+  const guard = defaultReadRateLimit(router);
+  router.use(guard);
+  router.use(accountExistenceReadRateLimit); // unprefixed: would match every path
+  router.get('/plain', ok);
+  const ip = '198.51.100.9';
+  for (let i = 0; i < DEFAULT_READ_LIMIT; i++) hit(guard, 'GET', '/plain', ip);
+  assert.equal(hit(guard, 'GET', '/plain', ip).nexted, false, 'the ceiling still applies');
+});
+
+test('the exemption walk runs on Express 4 (its Layer internals), and fails here if that changes', () => {
+  assert.match(require('express/package.json').version, /^4\./,
+    'rate-limit.js reads Express 4 Layer#match / Route#_handles_method — re-verify defaultReadRateLimit before upgrading');
+});
+
+test('readLimitOptOut refuses a missing or token reason', () => {
+  assert.throws(() => readLimitOptOut(), /reason/);
+  assert.throws(() => readLimitOptOut('nope'), /reason/);
+});
+
+// The composed production router: the reads that are NOT on the default ceiling. The core
+// mounts are checked here; modules are only loaded when enabled, so their limiters are pinned
+// by the tag test below. Adding a per-surface limiter or an opt-out changes this list on
+// purpose — the diff is the review; a route that quietly stops being tagged is a REMOVAL.
+test('the production router exempts exactly the core per-surface reads', () => {
+  const { buildGdsRouter } = require('../src/bongos/routes.js');
+  const got = selfMeteredRoutes(buildGdsRouter()).map((r) => `${r.scope} ${r.path}`).sort();
+  // The /public/* prefix mount has no route path of its own, so it is described by its regexp.
+  const isPublicPrefix = (g) => g.startsWith('public-read ') && g.includes('public') && g.includes('(?=');
+  assert.ok(got.some(isPublicPrefix), 'the /public/* prefix mount is exempt');
+  assert.deepEqual(got.filter((g) => !isPublicPrefix(g)).filter((g) => !g.startsWith('account-existence /access-requests')), [
+    'account-existence /auth/web/admission-status',
+    'opt-out /healthz',
+    'public-read /builders/:id/profile',
+  ]);
+});
+
+test('every module-side read limiter wears the self-metered tag', () => {
+  assert.equal(require('../modules/provisioning/rate-limit.js').makeAskRateLimiter().meteredScope, 'provisioning-ask');
+  const { createReadRateLimit } = require('../modules/platform-identity/read-rate-limit.js');
+  assert.equal(createReadRateLimit({ scope: 'x-read', limit: 5 }).meteredScope, 'x-read');
+  assert.equal(publicProjectFeedRateLimit.meteredScope, 'public-project-feed');
+  assert.equal(accountExistenceReadRateLimit.meteredScope, 'account-existence');
+});