@bongos/core 1.19.478 → 1.19.480

package/modules/ui-design/styles/blueprint/pack.json

@@ -0,0 +1,33 @@
+{
+  "_doc": "A look from the ui-design module's style library (task 1003323): the theme.ui overlay a branding pack carries, and nothing else. The stub lays it over the instance's pack (STYLE=blueprint); an instance adopts it by copying `theme` into config/branding.json. Light values only, as the contract says: dark is each sheet's own black tier, which this look reaches through the accent and the faces. Authored through the /style session of task 1003475.",
+  "name": "blueprint",
+  "title": "The Blueprint",
+  "summary": "A drafting table under north light: cool grey-blue paper, graphite rules, one cyanotype blue on everything pressable or live, and a rust annotation held for what went wrong.",
+  "origin": "authored through the /style session (task 1003475, ADR 0231) from a two-line brief: \"a drafting table under north light, cool paper and graphite; one cyanotype blue on what is pressable, a rust pencil for what went wrong\". The library had no cool look and no cool accent; the retune against the contract is recorded in DESIGN.md.",
+  "theme": {
+    "ui": {
+      "colors": {
+        "bg": "#e6ebf0",
+        "bgCard": "#f7fafc",
+        "bgDeep": "#d3dae2",
+        "bgFrame": "#edf1f5",
+        "ink": "#10161d",
+        "inkSoft": "#464f5a",
+        "inkFaint": "#566069",
+        "rule": "#aeb9c4",
+        "ruleSoft": "#cfd7de",
+        "accent": "#4f9fd6",
+        "accentDeep": "#17527e",
+        "sea": "#3f7f6a",
+        "terracotta": "#b04a2c"
+      },
+      "fonts": {
+        "display": "\"IBM Plex Sans\", \"Segoe UI\", system-ui, -apple-system, sans-serif",
+        "body": "\"IBM Plex Sans\", \"Segoe UI\", system-ui, -apple-system, sans-serif",
+        "links": [
+          "https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@300;400;500;600&family=JetBrains+Mono:wght@400&display=swap"
+        ]
+      }
+    }
+  }
+}

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.478",
+  "version": "1.19.480",
   "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/src/module-api.js

@@ -34,7 +34,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // 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.478'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.480'; // 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/credit_ledger_read.mjs

@@ -0,0 +1,347 @@
+// tests/credit_ledger_read.mjs
+//
+// task 1003484 (goal 1000067) — the credit ledger gets a read surface, resolving
+// blocker 1000127. Until this, `credit_log` had NO reader anywhere in the API:
+// every in-tree query was an internal aggregate or an existence probe, so the
+// three ideator streams (ADR 0172) could not be audited from outside at all.
+//
+// What this pins, in the order it matters:
+//
+//   1. THE ANTI-DRIFT GUARD. The stream reason keys EMBED the idea id
+//      (`idea.credit.full_pass:<ideaId>`), because that string is the
+//      idempotency predicate. So per-stream audit is a PREFIX question, and the
+//      prefixes this route publishes are asserted against the actual writers in
+//      credits.js — not against a transcription of them. If someone renames a
+//      reason key, this test fails rather than the audit filter silently
+//      returning nothing forever.
+//   2. The filter SQL: builder scoping, exact vs prefix reason, LIKE-wildcard
+//      escaping (a `%` in a query string must not widen the scan), and the
+//      unpaginated total.
+//   3. The leak rule: reward_basis is session top-up bookkeeping, not money a
+//      reader should see.
+//   4. The two gates: /me/credits takes its builder from the SESSION (there is
+//      no parameter to tamper with), and /builders/:id/credits refuses a caller
+//      without the roster-read atom.
+//
+// Pure — a recording fake pool over the real router, no Postgres, no network
+// beyond a loopback listener. Runs in the DB-free unit gate.
+//
+// Run:  node tests/credit_ledger_read.mjs
+
+import { strict as assert } from 'node:assert';
+import { test, after } from 'node:test';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const express = require('express');
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const CREDITS_SRC = readFileSync(join(ROOT, 'modules/economy/credits.js'), 'utf8');
+
+// ---- the recording fake pool ----------------------------------------------
+//
+// One shared pool object, so the domain's `pool` (destructured once at require
+// time, through the pinned module-api below) and each test's queue are the same
+// thing.
+let queued = [];
+let calls = [];
+const pool = {
+  query: async (text, params) => {
+    calls.push({ text: String(text), params: params || [] });
+    return queued.shift() || { rows: [], rowCount: 0 };
+  },
+};
+function expect(...responses) { queued = responses; calls = []; }
+const lastCall = () => calls[calls.length - 1];
+// Collapse whitespace so an assertion reads like the SQL, not like its indentation.
+const sqlOf = (c) => c.text.replace(/\s+/g, ' ').trim();
+
+// ---- the route over the real domain, with core pinned ----------------------
+
+const SESSION = { id: 77, github_login: 'octo', rank: 'xenos' };
+let permissionGranted = true;    // flipped by the refusal test
+let knownBuilder = true;         // flipped by the 404 test
+
+const helpers = require('../src/bongos/routes/_helpers.js');
+const moduleApiPath = require.resolve('../src/module-api.js');
+require.cache[moduleApiPath] = {
+  id: moduleApiPath, filename: moduleApiPath, loaded: true,
+  exports: {
+    pool,
+    parsePagination: helpers.parsePagination,
+    pageMeta: helpers.pageMeta,
+    parseId: helpers.parseId,
+    validateOrRespond: helpers.validateOrRespond,
+    LIMITS: helpers.LIMITS,
+    // The own-scope stub: a live session, exactly as requireBuilder leaves it.
+    requireBuilder: (req, _res, next) => { req.builder = { ...SESSION }; next(); },
+    // The atom gate, controllable — so the refusal is proven, not assumed.
+    requirePermission: () => (req, res, next) => (
+      permissionGranted ? next() : res.fail('permission_forbidden', 403)
+    ),
+    getBuilderById: async (id) => (knownBuilder ? { id, github_login: 'target' } : null),
+    // Loaded-but-unused by the credit domain at require time.
+    branding: () => ({}),
+    llmPricing: { priceModelUsage: () => ({ totalUsd: 0 }), PRICES: {} },
+  },
+};
+
+const credits = require('../modules/economy/credits.js');
+const buildCreditsRouter = require('../modules/economy/routes/credits.js');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+
+const app = express();
+app.use(express.json());
+app.use(attachFail);
+app.use('/api/gds', buildCreditsRouter());
+const server = app.listen(0, '127.0.0.1');
+await new Promise((r) => server.once('listening', r));
+const port = server.address().port;
+after(() => server.close());
+
+function call(method, path) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({ host: '127.0.0.1', port, method, path }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const text = Buffer.concat(chunks).toString('utf8');
+        let json = null; try { json = JSON.parse(text); } catch { /* non-JSON body */ }
+        resolve({ status: res.statusCode, json, text });
+      });
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+// A ledger row as the SELECT hands it back (window count rides along).
+const row = (over = {}) => ({
+  id: '5', delta: 5, reason: 'idea.credit.full_pass:20', description: null,
+  task_id: null, session_id: null, recorded_at: '2026-09-01T00:00:00.000Z',
+  total_count: 1, ...over,
+});
+
+// ---- 1. the anti-drift guard ----------------------------------------------
+
+test('the published stream prefixes are the REAL writers in credits.js, not a transcription', () => {
+  const p = credits.IDEA_STREAM_REASON_PREFIXES;
+  // Each writer builds its reason as `<prefix>${...}` — assert that exact
+  // template literal is present in the source. A renamed key breaks this test
+  // instead of silently making the audit filter match nothing, forever.
+  for (const [stream, prefix] of Object.entries(p)) {
+    assert.ok(
+      CREDITS_SRC.includes('`' + prefix + '${'),
+      `stream '${stream}' publishes prefix '${prefix}', but no writer in credits.js builds a reason with it`
+    );
+  }
+});
+
+test('all three ideator streams are covered — one missing prefix is one unauditable lane', () => {
+  assert.deepEqual(
+    Object.keys(credits.IDEA_STREAM_REASON_PREFIXES).sort(),
+    ['full_pass', 'governance_pass', 'task_ship'],
+    'ADR 0172 defines exactly three streams; each needs a prefix or it cannot be filtered for'
+  );
+});
+
+test('the prefixes are prefixes, not whole keys — the reason embeds the idea id', () => {
+  for (const prefix of Object.values(credits.IDEA_STREAM_REASON_PREFIXES)) {
+    assert.ok(prefix.endsWith(':'), `'${prefix}' must end at the separator, or it matches nothing`);
+  }
+});
+
+// ---- 2. the filter SQL -----------------------------------------------------
+
+test('an unfiltered read is scoped to the builder, newest-first, and paged', async () => {
+  expect({ rows: [row()] });
+  const out = await credits.creditLedger(77, { limit: 10, offset: 0 });
+  const sql = sqlOf(lastCall());
+  assert.match(sql, /WHERE builder_id = \$1/, 'the ledger is never read unscoped');
+  assert.match(sql, /ORDER BY recorded_at DESC, id DESC/, 'newest first, with id as the stable tiebreak');
+  assert.match(sql, /LIMIT \$2 OFFSET \$3/);
+  assert.deepEqual(lastCall().params, [77, 10, 0]);
+  assert.equal(out.total, 1);
+});
+
+test('total is the UNPAGINATED count, so a caller can tell more rows exist', async () => {
+  expect({ rows: [row({ total_count: 412 }), row({ id: '6', total_count: 412 })] });
+  const out = await credits.creditLedger(77, { limit: 2, offset: 0 });
+  assert.match(sqlOf(lastCall()), /COUNT\(\*\) OVER \(\)::int AS total_count/);
+  assert.equal(out.total, 412, 'the window count, not the page length');
+  assert.equal(out.rows.length, 2);
+});
+
+test('an empty page reports total 0 rather than throwing on rows[0]', async () => {
+  expect({ rows: [] });
+  const out = await credits.creditLedger(77, { limit: 10, offset: 900 });
+  assert.deepEqual(out, { rows: [], total: 0 });
+});
+
+test('reason is an EXACT match — right for the unparameterized keys', async () => {
+  expect({ rows: [] });
+  await credits.creditLedger(77, { reason: 'task.shipped' });
+  assert.match(sqlOf(lastCall()), /reason = \$2/);
+  assert.equal(lastCall().params[1], 'task.shipped');
+});
+
+test('reasonPrefix is a LIKE with an explicit ESCAPE — the per-stream audit filter', async () => {
+  expect({ rows: [] });
+  await credits.creditLedger(77, { reasonPrefix: credits.IDEA_STREAM_REASON_PREFIXES.full_pass });
+  // ESCAPE '\' — one literal backslash, which is what the SQL carries.
+  assert.match(sqlOf(lastCall()), /reason LIKE \$2 ESCAPE '\\'/);
+  // The stream keys contain '_', which is itself a LIKE wildcard — so our OWN
+  // prefix has to be escaped too, or 'full_pass' would also match 'fullXpass'.
+  assert.equal(lastCall().params[1], 'idea.credit.full\\_pass:%', 'anchored at the start, open at the end');
+});
+
+test("a caller's LIKE wildcards are escaped — a '%' cannot widen the scan", async () => {
+  expect({ rows: [] });
+  await credits.creditLedger(77, { reasonPrefix: '100%_off\\x' });
+  assert.equal(lastCall().params[1], '100\\%\\_off\\\\x%',
+    'every %, _ and backslash is escaped; only the trailing % is ours');
+});
+
+test('filters AND together and number their placeholders in order', async () => {
+  expect({ rows: [] });
+  await credits.creditLedger(77, {
+    reason: 'task.shipped', taskId: 1234, since: '2026-01-01T00:00:00Z', limit: 5, offset: 10,
+  });
+  const sql = sqlOf(lastCall());
+  assert.match(sql, /WHERE builder_id = \$1 AND reason = \$2 AND task_id = \$3 AND recorded_at >= \$4::timestamptz/);
+  assert.match(sql, /LIMIT \$5 OFFSET \$6/);
+  assert.deepEqual(lastCall().params, [77, 'task.shipped', 1234, '2026-01-01T00:00:00Z', 5, 10]);
+});
+
+test('a non-positive builder id reads nothing at all — it never reaches SQL', async () => {
+  expect({ rows: [row()] });
+  const out = await credits.creditLedger(0);
+  assert.deepEqual(out, { rows: [], total: 0 });
+  assert.equal(calls.length, 0, 'a bad id must not turn into an unscoped query');
+});
+
+// ---- 3. the leak rule ------------------------------------------------------
+
+test('reward_basis is never selected — it is bookkeeping, not money a reader should see', async () => {
+  expect({ rows: [] });
+  await credits.creditLedger(77, {});
+  assert.doesNotMatch(sqlOf(lastCall()), /reward_basis/);
+});
+
+test('total_count is stripped from the rows it rode in on', async () => {
+  expect({ rows: [row({ total_count: 9 })] });
+  const out = await credits.creditLedger(77, {});
+  assert.equal(out.total, 9);
+  assert.ok(!('total_count' in out.rows[0]), 'an internal window count is not a ledger field');
+  assert.deepEqual(Object.keys(out.rows[0]).sort(),
+    ['delta', 'description', 'id', 'reason', 'recorded_at', 'session_id', 'task_id']);
+});
+
+// ---- 4. the two gates ------------------------------------------------------
+
+test('GET /me/credits takes its builder from the SESSION — there is no parameter to tamper with', async () => {
+  expect({ rows: [row()] });
+  const res = await call('GET', '/api/gds/me/credits?builder_id=999');
+  assert.equal(res.status, 200);
+  assert.equal(res.json.builder_id, 77, 'the session id, never the query string');
+  assert.equal(lastCall().params[0], 77);
+});
+
+test('GET /me/credits serves the stream prefixes beside the rows, so the filter is discoverable', async () => {
+  expect({ rows: [row()] });
+  const res = await call('GET', '/api/gds/me/credits');
+  assert.deepEqual(res.json.streams, credits.IDEA_STREAM_REASON_PREFIXES);
+  assert.deepEqual(res.json.page, { limit: 50, offset: 0, total: 1 });
+});
+
+test('the page limit is clamped — the ledger grows forever, so an uncapped read cannot be asked for', async () => {
+  expect({ rows: [] });
+  const res = await call('GET', '/api/gds/me/credits?limit=100000');
+  assert.equal(res.json.page.limit, 200);
+});
+
+test('a ledger read is never cached — a stale balance is a wrong one', async () => {
+  expect({ rows: [] });
+  const res = await new Promise((resolve, reject) => {
+    http.request({ host: '127.0.0.1', port, method: 'GET', path: '/api/gds/me/credits' }, (r) => {
+      r.resume(); r.on('end', () => resolve(r));
+    }).on('error', reject).end();
+  });
+  assert.equal(res.headers['cache-control'], 'no-store');
+});
+
+test('a caller WITHOUT the roster-read atom cannot read another builder ledger', async () => {
+  permissionGranted = false;
+  expect({ rows: [row()] });
+  const res = await call('GET', '/api/gds/builders/999/credits');
+  permissionGranted = true;
+  assert.equal(res.status, 403);
+  assert.equal(calls.length, 0, 'refused before any query — the gate is not decorative');
+});
+
+test('a permitted caller reads the TARGET builder ledger, not their own', async () => {
+  expect({ rows: [row()] });
+  const res = await call('GET', '/api/gds/builders/999/credits');
+  assert.equal(res.status, 200);
+  assert.equal(res.json.builder_id, 999);
+  assert.equal(lastCall().params[0], 999);
+});
+
+test('an unknown builder is a 404, not an empty ledger that reads like "paid nothing"', async () => {
+  knownBuilder = false;
+  expect({ rows: [] });
+  const res = await call('GET', '/api/gds/builders/999/credits');
+  knownBuilder = true;
+  assert.equal(res.status, 404);
+  assert.equal(res.json.error.code, 'builder_not_found');
+});
+
+test('a non-numeric builder id is refused — /builders/me/credits is not a route', async () => {
+  const res = await call('GET', '/api/gds/builders/me/credits');
+  assert.equal(res.status, 400);
+  assert.equal(res.json.error.code, 'bad_builder_id');
+});
+
+// ---- 5. bad filters are 400s, not 500s -------------------------------------
+
+test('an unparseable since is a bad request, not a Postgres error surfacing as a 500', async () => {
+  expect({ rows: [] });
+  const res = await call('GET', '/api/gds/me/credits?since=not-a-date');
+  assert.equal(res.status, 400);
+  assert.equal(res.json.error.code, 'bad_since');
+  assert.equal(calls.length, 0);
+});
+
+test('a non-positive task_id filter is refused', async () => {
+  const res = await call('GET', '/api/gds/me/credits?task_id=0');
+  assert.equal(res.status, 400);
+  assert.equal(res.json.error.code, 'bad_task_id');
+});
+
+test('an over-long reason filter is refused rather than passed to the scan', async () => {
+  const res = await call('GET', `/api/gds/me/credits?reason=${'x'.repeat(201)}`);
+  assert.equal(res.status, 400);
+  assert.equal(res.json.error.code, 'bad_reason_filter');
+});
+
+test('the reason_prefix query param reaches the domain as a prefix filter', async () => {
+  expect({ rows: [] });
+  const res = await call('GET', '/api/gds/me/credits?reason_prefix=idea.credit.governance_pass%3A');
+  assert.equal(res.status, 200);
+  assert.equal(lastCall().params[1], 'idea.credit.governance\\_pass:%',
+    "the writer's own '_' is escaped, so it matches literally");
+});
+
+// ---- 6. the port ------------------------------------------------------------
+
+test('the read rides the reward PORT, so a core hall view can resolve it without importing economy', async () => {
+  const reward = require('../modules/economy/reward.js');
+  assert.equal(typeof reward.creditLedger, 'function');
+  expect({ rows: [row()] });
+  const out = await reward.creditLedger(77, { limit: 1 });
+  assert.equal(out.total, 1, 'delegated, not spread — the port reaches the live function');
+});

package/tests/hall_reading_world.mjs

@@ -428,3 +428,83 @@ test('with no repo bases the resolver degrades instead of crashing the page', ()
   assert.equal(resolve('../../CLAUDE.md'), '../../CLAUDE.md',
     'the bases are fetched at boot; before they land a relative href passes through and 404s harmlessly');
 });
+
+// A link target reaches an href only if the reader vouches for its scheme
+// (task 1003482). escapeHtml stops markup, not URI schemes: a `javascript:`
+// target would run on click. Every document the hall renders today is
+// repo-controlled, but the reference room widened what flows through the
+// shared reader, so the door closes before it meets a document someone else
+// wrote. The hostile list carries the shapes a browser's URL parser would
+// still read as a scheme: tab/newline inside, whitespace before, backslashes
+// for slashes.
+const HOSTILE_TARGETS = [
+  'javascript:alert(1)',
+  'JavaScript:alert(1)',
+  'java\tscript:alert(1)',
+  ' javascript:alert(1)',
+  'data:text/html;base64,PHNjcmlwdD5hbGVydCgxKTwvc2NyaXB0Pg==',
+  'vbscript:MsgBox(1)',
+  'file:///etc/passwd',
+  'ftp://example.org/x',
+  '//evil.example/x',
+  '\\\\evil.example/x',
+  '/\\evil.example/x',
+];
+const REPO_BASES = {
+  baseDir: 'docs/onboarding/',
+  getBlobBase: () => 'https://github.com/o/r/blob/main',
+  getTreeBase: () => 'https://github.com/o/r/tree/main',
+};
+const VOUCHED_TARGETS = [
+  ['https://example.org/x', 'https://example.org/x'],
+  ['http://example.org/x', 'http://example.org/x'],
+  ['mailto:hello@example.org', 'mailto:hello@example.org'],
+  ['tel:+15555550100', 'tel:+15555550100'],
+  ['#a-section', '#a-section'],
+  ['../../CLAUDE.md', 'https://github.com/o/r/blob/main/CLAUDE.md'],
+];
+
+test('the allowlist is the reader\'s own, and it is short', () => {
+  const MD = loadReader();
+  for (const [target] of VOUCHED_TARGETS) assert.ok(MD.isAllowedLinkHref(target), `${target} is vouched for`);
+  assert.ok(MD.isAllowedLinkHref('docs/recipes/'), 'a bare relative path is a repo path');
+  assert.ok(MD.isAllowedLinkHref('/docs/recipes/'), 'one leading slash is a repo path, not a host');
+  for (const target of HOSTILE_TARGETS) assert.ok(!MD.isAllowedLinkHref(target), `${JSON.stringify(target)} is refused`);
+});
+
+test('a hostile link target renders as its text, with no <a> at all', () => {
+  const MD = loadReader();
+  const resolvers = {
+    'no bases': MD.makeResolveLinkHref({ baseDir: 'docs/onboarding/' }),
+    'bases up': MD.makeResolveLinkHref(REPO_BASES),
+    identity: (h) => h,
+  };
+  for (const target of HOSTILE_TARGETS) {
+    for (const [name, resolve] of Object.entries(resolvers)) {
+      const { html } = MD.parseMarkdown(`see [the door](${target}) here\n`, resolve);
+      assert.doesNotMatch(html, /<a[\s>]|href=/, `${JSON.stringify(target)} under the ${name} resolver writes no anchor`);
+      // (a `)` inside a target ends the link — the parser's own limit, so
+      // `alert(1)` leaves one behind as text; what matters is no anchor)
+      assert.match(html, /<p>see the door\)? here<\/p>/, `… and the label survives as text`);
+    }
+  }
+});
+
+test('the resolver refuses a hostile target before the repo bases can dress it as a GitHub path', () => {
+  const MD = loadReader();
+  const resolve = MD.makeResolveLinkHref(REPO_BASES);
+  for (const target of HOSTILE_TARGETS) {
+    assert.equal(resolve(target), null, `${JSON.stringify(target)} is refused, not rewritten to ${resolve(target)}`);
+  }
+});
+
+test('the vouched shapes still become links, exactly as before', () => {
+  const MD = loadReader();
+  const resolve = MD.makeResolveLinkHref(REPO_BASES);
+  for (const [target, href] of VOUCHED_TARGETS) {
+    const { html } = MD.parseMarkdown(`[t](${target})\n`, resolve);
+    assert.ok(html.includes(`<a href="${href}"`), `${target} → ${href}, got ${html}`);
+  }
+  const degraded = MD.parseMarkdown('[t](../../CLAUDE.md)\n', MD.makeResolveLinkHref({ baseDir: 'docs/onboarding/' })).html;
+  assert.ok(degraded.includes('<a href="../../CLAUDE.md"'), 'and with no bases a repo path still degrades to a link, as §10 pins above');
+});

package/tests/own_scope_guard.mjs

@@ -89,6 +89,20 @@ const OWN_SCOPED_SURFACES = [
     why: 'the per-builder preference domain (wandering, skill, sound, render, model-allocation, display name) carved out of /me — read and write, all keyed on req.builder.id.',
     crossOwner: [],
   },
+  {
+    file: 'modules/economy/routes/credits.js',
+    why: 'the credit-ledger read (task 1003484, blocker 1000127). GET /me/credits takes its builder from req.builder.id and never reads an id off the request, so there is no parameter to tamper with. The one cross-owner route names its target in the path and is gate-verified below.',
+    // Two routes, one of them cross-owner — so one own-scoped route is the whole
+    // truth here, not a parser that stopped matching.
+    minOwnScoped: 1,
+    crossOwner: [
+      {
+        path: '/builders/:builderId/credits',
+        gate: /requirePermission\(\s*['"]builder\.roster\.read['"]\s*\)/,
+        why: "itemised read of ANOTHER builder's credit ledger — permission-gated on the builder.roster.read atom, the same gate /builders/:id/active-claims carries for the same act (reading another builder's record off the roster).",
+      },
+    ],
+  },
   {
     file: 'modules/platform-identity/routes/profile.js',
     why: "the builder's OWN cross-project profile controls (hide flag, handle, bio/links) — all keyed on req.builder.github_id.",
@@ -139,6 +153,12 @@ const OWN_SCOPED_SURFACES = [
 
 // Floors that keep this guard from going quietly vacuous (a regex that stops
 // matching would otherwise "pass" by checking nothing).
+//
+// The per-file floor is a DEFAULT, not a law: a surface may declare its own
+// `minOwnScoped` when it genuinely mounts fewer (modules/economy/routes/credits.js
+// is one own-scoped read plus one gated cross-owner read). The floor's job is to
+// notice a file whose routes STOPPED parsing — so what matters is that every
+// surface has a non-zero floor it must clear, not that they all share one number.
 const MIN_OWN_SCOPED_ROUTES_TOTAL = 28;
 const MIN_OWN_SCOPED_ROUTES_PER_FILE = 3;
 
@@ -416,9 +436,11 @@ for (const surface of OWN_SCOPED_SURFACES) {
   }
 
   t(`${surface.file} — contributes a real number of own-scoped routes (not vacuous)`, () => {
+    const floor = surface.minOwnScoped ?? MIN_OWN_SCOPED_ROUTES_PER_FILE;
+    assert.ok(floor > 0, 'a declared floor of 0 would exempt the file from this check entirely');
     assert.ok(
-      ownScopedHere >= MIN_OWN_SCOPED_ROUTES_PER_FILE,
-      `only ${ownScopedHere} own-scoped routes found (floor ${MIN_OWN_SCOPED_ROUTES_PER_FILE}) — either routes moved out or the parser stopped seeing them`
+      ownScopedHere >= floor,
+      `only ${ownScopedHere} own-scoped routes found (floor ${floor}) — either routes moved out or the parser stopped seeing them`
     );
   });