@bongos/core 1.19.710 → 1.19.712

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.710",
+  "version": "1.19.712",
   "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/agent-invoke.js

@@ -446,33 +446,11 @@ function parseArgv(argv = []) {
   return { name, question, outArg, asJson, error: null };
 }
 
-/**
- * The gate. Decides whether this definition may be invoked on demand, and gives
- * the reason in the same breath — rule 2 needs the reason as much as the verdict,
- * because the reason is the whole content of the ledger row a refusal writes.
- *
- * PURE: takes the registry row, returns `{ decision, reason }`.
- */
-function gateFor(row) {
-  if (!row) return { decision: 'no-go', reason: 'no such agent in the registry' };
-  if (row.trigger_type !== 'on-demand') {
-    return {
-      decision: 'no-go',
-      reason: `trigger_type is '${row.trigger_type}', not 'on-demand' — this agent is dispatched by an event, not asked a question`,
-    };
-  }
-  // Checked before `enabled` even though the schema's flagged_not_armed CHECK
-  // makes a flagged row necessarily disabled: the two states have the same
-  // verdict and completely different fixes, and the reason is what the caller
-  // acts on.
-  if (isNonEmptyString(row.scope_violation)) {
-    return { decision: 'no-go', reason: `disarmed by the scope wall: ${row.scope_violation}` };
-  }
-  if (row.enabled !== true) {
-    return { decision: 'no-go', reason: 'the definition is present in the registry but not enabled' };
-  }
-  return { decision: 'go', reason: null };
-}
+// THE GATE lives in the module, not here: the same question is asked by
+// POST /agents/:name/invoke on the other side of the trust boundary, and a gate
+// with two implementations has two behaviours the day one is edited. Required
+// directly from a script the way agents-sync requires the validator.
+const { gateFor } = require('../../modules/agents/lib/gate.js');
 
 // ---- the chain -------------------------------------------------------------
 

package/scripts/gds/sandbox-stage.js

@@ -44,10 +44,27 @@ const HEALTH_POLL_MS = 2_000;
 // GAME-ONLY entry (src/preview-server.js, ADR 0052), so only game-rendering paths
 // are previewable — GDS/internal-tooling diffs have nothing to look at there.
 // src/preview-server.js + server.js are the entrypoints that render the game.
-const PREVIEWABLE_PREFIXES = ['public/', 'src/world/', 'src/rooms/'];
-const PREVIEWABLE_FILES = new Set(['server.js', 'src/preview-server.js']);
-// Same surfaces as git pathspecs (no trailing slash) for scoped plumbing calls.
-const PREVIEWABLE_PATHSPECS = ['public', 'src/world', 'src/rooms', 'server.js', 'src/preview-server.js'];
+// The GAME CLIENT directories the sandbox renders. These MOVED in the module
+// carve (ADR 0083, BV1.R49 / task 1418): public/ -> modules/game/public/,
+// src/world/ -> modules/game/world/, src/rooms/ -> modules/game/rooms/. The
+// pre-carve spelling sat here matching NOTHING, and staging still reported
+// success because the two entrypoints below kept syncing — so a builder staged,
+// saw 'synced previewable surfaces', and got a sandbox serving whatever client
+// was already on /workspace (task 1002062; found when a new /studio page 404'd).
+const PREVIEWABLE_DIRS = ['modules/game/public', 'modules/game/world', 'modules/game/rooms'];
+// The single directory the preview serves AT THE URL ROOT: modules/game/public/x
+// is served as /x. pickVerifyTarget maps between the two, so it must be exactly
+// one dir — hence its own constant rather than PREVIEWABLE_DIRS[0].
+const PREVIEWABLE_STATIC_DIR = 'modules/game/public';
+// The entrypoints that render the game. A sparse box (STARTER_SPARSE_PATHS) may
+// legitimately lack these, which is why a miss here is not on its own an error.
+const PREVIEWABLE_ENTRYPOINTS = ['server.js', 'src/preview-server.js'];
+// DERIVED, all three of them. They used to be three hand-maintained copies of the
+// same list, and the carve updated none of them; deriving removes the drift class
+// rather than just this instance of it.
+const PREVIEWABLE_PREFIXES = PREVIEWABLE_DIRS.map((d) => `${d}/`);
+const PREVIEWABLE_FILES = new Set(PREVIEWABLE_ENTRYPOINTS);
+const PREVIEWABLE_PATHSPECS = [...PREVIEWABLE_DIRS, ...PREVIEWABLE_ENTRYPOINTS];
 
 // On a box, box-game-preview.service has WorkingDirectory=/workspace and serves
 // /workspace/public — the MAIN checkout. A Claude session, though, runs in a git
@@ -316,6 +333,11 @@ function syncWorktreeToServed(deps = {}) {
   // then overlay the session branch's content.
   let synced = false;
   let lastErr = null;
+  // task 1002062: this collapsed to a single boolean, so a run that synced ONLY
+  // the entrypoints and missed every client directory reported plain success.
+  // Track them by name — the caller warns on a missed DIRECTORY, which is the
+  // shape a stale pathspec list takes.
+  const missed = [];
   for (const ps of PREVIEWABLE_PATHSPECS) {
     try {
       run('git', ['-C', servedRoot, 'checkout', '--', ps], { stdio: 'ignore' });
@@ -327,12 +349,16 @@ function syncWorktreeToServed(deps = {}) {
       synced = true;
     } catch (e) {
       lastErr = e; // pathspec absent in the branch (sparse/missing) — skip it
+      missed.push(ps);
     }
   }
   if (!synced) {
-    return { ok: false, synced: false, reason: `git checkout ${branch} -- <previewable> in ${servedRoot} synced nothing${lastErr ? ` (${lastErr.message})` : ''}` };
+    return { ok: false, synced: false, missed, reason: `git checkout ${branch} -- <previewable> in ${servedRoot} synced nothing${lastErr ? ` (${lastErr.message})` : ''}` };
   }
-  return { ok: true, synced: true, branch };
+  // A missed ENTRYPOINT is normal on a sparse box. A missed client DIRECTORY means
+  // the sandbox is about to serve a client this stage never touched.
+  const missedDirs = missed.filter((m) => PREVIEWABLE_DIRS.includes(m));
+  return { ok: true, synced: true, branch, missed, missedDirs };
 }
 
 // Pick the smallest cheap-to-compare changed previewable static file to verify,
@@ -343,21 +369,26 @@ function pickVerifyTarget(deps = {}) {
   const cwd = deps.cwd || process.cwd();
   const f = deps.fs || fs;
   try {
-    const out = run('git', ['status', '--porcelain', '--', 'public'], { cwd, encoding: 'utf8' });
+    // task 1002062: this hardcoded 'public' three times, independently of the
+    // constants above, so it kept the pre-carve spelling even after they moved.
+    // Derived from PREVIEWABLE_STATIC_DIR now, so there is one place to change.
+    const staticDir = deps.staticDir || PREVIEWABLE_STATIC_DIR;
+    const prefix = `${staticDir}/`;
+    const out = run('git', ['status', '--porcelain', '--', staticDir], { cwd, encoding: 'utf8' });
     let chosen = out
       .split('\n')
       .map((line) => line.slice(3).replace(/^"|"$/g, '').trim())
-      .find((rel) => rel && rel.startsWith('public/') && f.existsSync(path.join(cwd, rel)));
+      .find((rel) => rel && rel.startsWith(prefix) && f.existsSync(path.join(cwd, rel)));
     if (!chosen) {
       // committed-only change: fall back to the diff vs the frozen origin/main
-      const diff = run('git', ['diff', '--name-only', 'origin/main...HEAD', '--', 'public'], { cwd, encoding: 'utf8' });
+      const diff = run('git', ['diff', '--name-only', 'origin/main...HEAD', '--', staticDir], { cwd, encoding: 'utf8' });
       chosen = diff
         .split('\n')
         .map((s) => s.trim())
-        .find((p) => p.startsWith('public/') && f.existsSync(path.join(cwd, p)));
+        .find((p) => p.startsWith(prefix) && f.existsSync(path.join(cwd, p)));
     }
     if (!chosen) return null;
-    return { relPath: chosen, urlPath: '/' + chosen.replace(/^public\//, '') };
+    return { relPath: chosen, urlPath: '/' + chosen.slice(prefix.length) };
   } catch {
     return null;
   }
@@ -374,7 +405,7 @@ async function verifyServedFresh(deps = {}) {
   const cwd = deps.cwd || process.cwd();
   const base = (deps.healthUrl || HEALTH_URL).replace(/\/$/, '');
   const target = pickVerifyTarget(deps);
-  if (!target) return { ok: true, skipped: true, reason: 'no served static change to verify (e.g. only src/rooms changed)' };
+  if (!target) return { ok: true, skipped: true, reason: `no served static change to verify (e.g. only ${PREVIEWABLE_DIRS.filter((d) => d !== PREVIEWABLE_STATIC_DIR).join(' or ')} changed)` };
   let want;
   try {
     want = f.readFileSync(path.join(cwd, target.relPath), 'utf8');
@@ -455,6 +486,16 @@ async function stage({ taskId } = {}, deps = {}) {
       return { ok: false, hard: true, reason: `could not sync your worktree to the served checkout (${sync.reason}); the sandbox would show stale ${deps.servedRoot || BOX_SERVED_ROOT} code` };
     }
     if (sync.synced) console.log(`  synced previewable surfaces from ${sync.branch} into ${deps.servedRoot || BOX_SERVED_ROOT}`);
+    // task 1002062 — the tell that went unsaid for 69 days. Staging "succeeded"
+    // while every game-client directory matched nothing, so the sandbox served a
+    // client the stage never touched and the only hint was a freshness-verify skip.
+    if (sync.missedDirs && sync.missedDirs.length) {
+      console.warn(
+        `  ⚠ these previewable directories matched NOTHING in ${sync.branch}: ${sync.missedDirs.join(', ')}`
+        + ' — the sandbox will serve whatever client is already on the served checkout.'
+        + ' If this repo carved or renamed them, PREVIEWABLE_DIRS in sandbox-stage.js is stale.'
+      );
+    }
   }
   try {
     ctx.restart(deps);
@@ -699,6 +740,9 @@ module.exports = {
   BOX_ENV_PATH,
   BOX_SERVED_ROOT,
   PREVIEWABLE_PATHSPECS,
+  PREVIEWABLE_DIRS,
+  PREVIEWABLE_ENTRYPOINTS,
+  PREVIEWABLE_STATIC_DIR,
   sessionCheckoutRoot,
   syncWorktreeToServed,
   pickVerifyTarget,

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.710'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.712'; // 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/agents_authoring.mjs

@@ -0,0 +1,306 @@
+// tests/agents_authoring.mjs — the decisions behind the agent WRITE surface
+// (task 1002493, goal 1000038 Phase 2a).
+//
+// Four rules, each a way an authoring surface turns into an escalation, plus the
+// pickup counter a server-side fire delivers its answer through. All pure — no
+// database, no HTTP, no model. The routes that consume these are asserted
+// structurally in tests/agents_routes.mjs.
+//
+// In tests/ rather than modules/agents/tests/ for the reason task 1002487 gave:
+// `agents` is default:false, so a module-local suite would never run.
+//
+// Run:  node tests/agents_authoring.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const authoring = require('../modules/agents/lib/authoring.js');
+const { gateFor, ON_DEMAND } = require('../modules/agents/lib/gate.js');
+const { createAnswerHold } = require('../modules/agents/lib/answer-hold.js');
+const { createFireBudget, MAX_TRACKED_BUILDERS } = require('../modules/agents/lib/fire-budget.js');
+const validate = require('../modules/agents/lib/validate.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed += 1; console.log(`  ok  ${name}`); }
+  catch (err) { failed += 1; console.error(`  FAIL ${name}\n    ${err.message}`); }
+}
+
+const DB_ROW = Object.freeze({
+  name: 'librarian', title: 'The Librarian', persona: 'P',
+  trigger_type: 'on-demand', trigger_spec: {}, model_tier: 'default',
+  scope_modules: [], scope_paths: [], scope_violation: null,
+  source: 'db', provenance: 'instance', author_rank: 'metic', enabled: false,
+});
+
+console.log('\nrule 1 — authority fields are never read from the request:');
+
+t('every server-owned field is refused BY NAME, with the reason', () => {
+  for (const field of Object.keys(authoring.SERVER_OWNED_FIELDS)) {
+    const hits = authoring.forbiddenFields({ name: 'x', [field]: 'anything' });
+    assert.equal(hits.length, 1, `${field} was not refused`);
+    assert.equal(hits[0].field, field);
+    assert.ok(hits[0].reason.length > 0, `${field} was refused without saying why`);
+  }
+});
+
+t('author_rank is on that list, and the reason names the live-rank rule', () => {
+  const [hit] = authoring.forbiddenFields({ author_rank: 'archon' });
+  assert.equal(hit.field, 'author_rank');
+  assert.match(hit.reason, /live DB rank/);
+});
+
+t('a clean body is clean, and a non-object body is not an error to report here', () => {
+  assert.deepEqual(authoring.forbiddenFields({ name: 'x', persona: 'p' }), []);
+  assert.deepEqual(authoring.forbiddenFields(null), []);
+  assert.deepEqual(authoring.forbiddenFields('nope'), []);
+  assert.deepEqual(authoring.forbiddenFields([{ author_rank: 'archon' }]), []);
+});
+
+t('the authorable set and the server-owned set do not overlap', () => {
+  // A field in both would be decided in two places, and the one that ran last
+  // would win silently.
+  for (const f of authoring.AUTHORABLE_FIELDS) {
+    assert.ok(!Object.prototype.hasOwnProperty.call(authoring.SERVER_OWNED_FIELDS, f),
+      `${f} is both authorable and server-owned`);
+  }
+});
+
+console.log('\nrule 3 — a DB-authored definition may not reach a protected surface:');
+
+const PROTECTED_MODULES = ['government', 'lifecycle'];
+const IS_PROTECTED = (p) => p.startsWith('src/bongos/') || p.startsWith('migrations/');
+
+t('a protected MODULE is a hit', () => {
+  const h = authoring.protectedScopeHits({ scope_modules: ['government', 'copy-desk'] },
+    { protectedModules: PROTECTED_MODULES, isProtectedPath: IS_PROTECTED });
+  assert.equal(h.protected, true);
+  assert.deepEqual(h.modules, ['government']);
+});
+
+t('a protected PATH is a hit — the same surface, spelled the other way', () => {
+  const h = authoring.protectedScopeHits({ scope_paths: ['src/bongos/auth.js', 'public/app.css'] },
+    { protectedModules: PROTECTED_MODULES, isProtectedPath: IS_PROTECTED });
+  assert.equal(h.protected, true);
+  assert.deepEqual(h.paths, ['src/bongos/auth.js']);
+});
+
+t('a clean scope is clean, and so is no scope at all', () => {
+  const ctx = { protectedModules: PROTECTED_MODULES, isProtectedPath: IS_PROTECTED };
+  assert.equal(authoring.protectedScopeHits({ scope_modules: ['copy-desk'], scope_paths: ['docs/'] }, ctx).protected, false);
+  assert.equal(authoring.protectedScopeHits({}, ctx).protected, false);
+  assert.equal(authoring.protectedScopeHits(null, ctx).protected, false);
+});
+
+t('FAIL-CLOSED: declared paths with NO matcher are all hits', () => {
+  // "Nobody checked" must not read as "nothing was protected" — the same rule
+  // the validator's scope_paths wall applies (task 1002492).
+  const h = authoring.protectedScopeHits({ scope_paths: ['anything/at/all'] }, { protectedModules: [] });
+  assert.equal(h.protected, true);
+  assert.deepEqual(h.paths, ['anything/at/all']);
+});
+
+t('FAIL-CLOSED: a throwing matcher is a hit, and only an explicit false clears a path', () => {
+  const ctx = (fn) => ({ protectedModules: [], isProtectedPath: fn });
+  assert.equal(authoring.protectedScopeHits({ scope_paths: ['x'] }, ctx(() => { throw new Error('boom'); })).protected, true);
+  assert.equal(authoring.protectedScopeHits({ scope_paths: ['x'] }, ctx(() => undefined)).protected, true);
+  assert.equal(authoring.protectedScopeHits({ scope_paths: ['x'] }, ctx(() => null)).protected, true);
+  assert.equal(authoring.protectedScopeHits({ scope_paths: ['x'] }, ctx(() => 'yes')).protected, true);
+  assert.equal(authoring.protectedScopeHits({ scope_paths: ['x'] }, ctx(() => false)).protected, false);
+});
+
+t('this wall is STRICTER than the validator, which is the point', () => {
+  // An Archon clears validate.js's Metic+ rank floor on a protected scope...
+  const verdict = validate.validateAgentDefinition(
+    { ...DB_ROW, scope_modules: ['government'] },
+    { authorRank: 'archon', allowedModules: ['government'], protectedModules: PROTECTED_MODULES, isProtectedPath: () => false },
+  );
+  assert.equal(verdict.ok, true, 'the rank floor admits an Archon');
+  // ...and still cannot author it over HTTP, because the reviewed path and the
+  // unreviewed one do not get the same wall.
+  assert.equal(
+    authoring.protectedScopeHits(verdict.value, { protectedModules: PROTECTED_MODULES, isProtectedPath: () => false }).protected,
+    true,
+  );
+});
+
+console.log('\nrule 4 — the sync owns its own rows:');
+
+t('a file-sourced definition is not editable here, and the reason names the file', () => {
+  const w = authoring.writableByApi({ ...DB_ROW, source: 'file', source_path: '.claude/agents/historian.md' });
+  assert.equal(w.ok, false);
+  assert.match(w.reason, /\.claude\/agents\/historian\.md/);
+  assert.match(w.reason, /silently undone/);
+  // ...and it points at the one write that DOES work on a file row.
+  assert.match(w.reason, /enable\/disable/);
+});
+
+t('a db-authored definition is editable; a missing one is not', () => {
+  assert.equal(authoring.writableByApi(DB_ROW).ok, true);
+  assert.equal(authoring.writableByApi(null).ok, false);
+});
+
+console.log('\nthe merge — a PATCH is judged as a whole definition:');
+
+t('unsent fields come from the stored row', () => {
+  const merged = authoring.mergeForValidation(DB_ROW, { title: 'Renamed' });
+  assert.equal(merged.title, 'Renamed');
+  assert.equal(merged.persona, 'P');
+  assert.equal(merged.trigger_type, 'on-demand');
+});
+
+t('a partial trigger change is caught BECAUSE the whole definition is re-judged', () => {
+  // Switch to an event trigger without sending trigger_spec. Validating the
+  // delta alone would see nothing wrong; validating the merged definition sees a
+  // trigger that can never fire.
+  const merged = authoring.mergeForValidation(DB_ROW, { trigger_type: 'event' });
+  const verdict = validate.validateAgentDefinition(merged, { allowedModules: [], protectedModules: [], authorRank: 'metic' });
+  assert.equal(verdict.ok, false);
+  assert.ok(verdict.errors.some((e) => e.code === 'trigger_event_missing'), verdict.errors.map((e) => e.code).join(','));
+});
+
+t('a server-owned key in the patch cannot ride in through the merge', () => {
+  const merged = authoring.mergeForValidation(DB_ROW, { enabled: true, author_rank: 'archon', source: 'file' });
+  assert.equal(merged.enabled, undefined);
+  assert.equal(merged.author_rank, undefined);
+  assert.equal(merged.source, undefined);
+});
+
+t('an explicit null clears an optional field rather than being ignored', () => {
+  const merged = authoring.mergeForValidation({ ...DB_ROW, title: 'The Librarian' }, { title: null });
+  assert.equal(merged.title, null);
+});
+
+console.log('\nthe gate — shared with the CLI, so the two cannot drift:');
+
+t('off means off on the on-demand path too', () => {
+  assert.equal(gateFor({ ...DB_ROW, enabled: true }).decision, 'go');
+  const off = gateFor({ ...DB_ROW, enabled: false });
+  assert.equal(off.decision, 'no-go');
+  assert.match(off.reason, /not enabled/);
+});
+
+t('an event agent cannot be asked, a flagged one is named as flagged, a missing one is named', () => {
+  assert.match(gateFor({ ...DB_ROW, enabled: true, trigger_type: 'event' }).reason, /not 'on-demand'/);
+  assert.match(gateFor({ ...DB_ROW, scope_violation: 'reaches src/bongos/auth.js' }).reason, /scope wall/);
+  assert.match(gateFor(null).reason, /no such agent/);
+});
+
+t("the gate's trigger-type constant matches the validator's vocabulary", () => {
+  assert.ok(validate.TRIGGER_TYPES.includes(ON_DEMAND),
+    'gate.js spells a trigger type the validator does not admit');
+});
+
+console.log('\nthe answer hold — a pickup counter, not a database:');
+
+t('an answer is held for the caller and survives being read twice', () => {
+  const hold = createAnswerHold();
+  hold.put(7, 'the answer');
+  assert.equal(hold.take(7), 'the answer');
+  // A caller polling while the fire is in flight must not consume it with the
+  // first successful poll.
+  assert.equal(hold.take(7), 'the answer');
+  assert.equal(hold.take('7'), 'the answer', 'the id is keyed by value, not by type');
+});
+
+t('nothing held is null, not an error', () => {
+  const hold = createAnswerHold();
+  assert.equal(hold.take(99), null);
+  assert.equal(hold.take(null), null);
+  assert.equal(hold.take(undefined), null);
+});
+
+t('a runless put is refused rather than keyed under "null"', () => {
+  const hold = createAnswerHold();
+  assert.equal(hold.put(null, 'x'), false);
+  assert.equal(hold.put(undefined, 'x'), false);
+  assert.equal(hold.size(), 0);
+});
+
+t('it EXPIRES — an uncollected answer is a copy of what the agent read, sitting in memory', () => {
+  let clock = 1000;
+  const hold = createAnswerHold({ ttlMs: 500, now: () => clock });
+  hold.put(1, 'early');
+  clock += 499;
+  assert.equal(hold.take(1), 'early');
+  clock += 2;
+  assert.equal(hold.take(1), null);
+  assert.equal(hold.size(), 0);
+});
+
+t('it is BOUNDED — a loop of invocations cannot grow the process', () => {
+  const hold = createAnswerHold({ maxHeld: 3 });
+  for (let i = 1; i <= 10; i++) hold.put(i, `a${i}`);
+  assert.equal(hold.size(), 3);
+  assert.equal(hold.take(1), null, 'the oldest went first');
+  assert.equal(hold.take(10), 'a10', 'the newest is still there');
+});
+
+t('re-putting an entry moves it to the BACK of the eviction queue', () => {
+  // Without the delete-then-set, a refreshed entry keeps its original position
+  // and can be evicted while it is the newest thing here.
+  const hold = createAnswerHold({ maxHeld: 2 });
+  hold.put(1, 'a');
+  hold.put(2, 'b');
+  hold.put(1, 'a-again');
+  hold.put(3, 'c');
+  assert.equal(hold.take(2), null, '2 was the oldest once 1 was refreshed');
+  assert.equal(hold.take(1), 'a-again');
+  assert.equal(hold.take(3), 'c');
+});
+
+console.log('\nthe fire budget — a blast radius, not an accounting:');
+
+t('a builder gets exactly `limit` fires per window, then is refused with a retry', () => {
+  let clock = 0;
+  const budget = createFireBudget({ limit: 3, windowMs: 1000, now: () => clock });
+  for (let i = 0; i < 3; i++) assert.equal(budget.check(5).ok, true, `fire ${i + 1}`);
+  const refused = budget.check(5);
+  assert.equal(refused.ok, false);
+  assert.ok(refused.retryAfterSeconds > 0, 'a refusal has to say when to come back');
+});
+
+t('the window SLIDES — it is a rate, not a quota that never refills', () => {
+  let clock = 0;
+  const budget = createFireBudget({ limit: 2, windowMs: 1000, now: () => clock });
+  budget.check(5); budget.check(5);
+  assert.equal(budget.check(5).ok, false);
+  clock += 1001;
+  assert.equal(budget.check(5).ok, true, 'the oldest fire aged out of the window');
+});
+
+t('the ceiling is per BUILDER — one caller cannot exhaust another', () => {
+  const budget = createFireBudget({ limit: 1, windowMs: 1000, now: () => 0 });
+  assert.equal(budget.check(5).ok, true);
+  assert.equal(budget.check(5).ok, false);
+  assert.equal(budget.check(6).ok, true, 'a different builder has their own window');
+});
+
+t('FAIL-CLOSED on an unidentified caller — never a shared "unknown" bucket', () => {
+  // A shared key is worse than no limit: one caller could exhaust it for
+  // everyone. An unattributable fire is what the ledger exists to prevent.
+  const budget = createFireBudget({ limit: 5, windowMs: 1000, now: () => 0 });
+  for (const id of [null, undefined, '']) assert.equal(budget.check(id).ok, false, String(id));
+  assert.equal(budget.size(), 0, 'no bucket was created for an unidentified caller');
+});
+
+t('a numeric and a string builder id are the same builder', () => {
+  const budget = createFireBudget({ limit: 1, windowMs: 1000, now: () => 0 });
+  assert.equal(budget.check(5).ok, true);
+  assert.equal(budget.check('5').ok, false, 'pg returns bigints as strings — these must not be two windows');
+});
+
+t('the bucket map is bounded, and eviction forgives the QUIETEST builder', () => {
+  let clock = 0;
+  const budget = createFireBudget({ limit: 1, windowMs: 1_000_000, now: () => (clock += 1) });
+  for (let i = 0; i < MAX_TRACKED_BUILDERS + 10; i++) budget.check(i);
+  assert.ok(budget.size() <= MAX_TRACKED_BUILDERS);
+  // The most recent spender keeps their bucket; the least recent is the one let go.
+  assert.equal(budget.check(MAX_TRACKED_BUILDERS + 9).ok, false, 'the newest spender is still tracked');
+  assert.equal(budget.check(0).ok, true, 'the quietest was forgiven, not the busiest');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/tests/agents_routes.mjs

@@ -20,6 +20,7 @@ const require = createRequire(import.meta.url);
 const routes = require('../modules/agents/routes/agents.js');
 const validate = require('../modules/agents/lib/validate.js');
 const api = require('../src/module-api.js');
+const catalog = require('../modules/government/catalog.js');
 
 const { serializeDefinition } = routes;
 
@@ -128,28 +129,88 @@ t('null arrays degrade to [], and a missing row serializes to null', () => {
   assert.equal(serializeDefinition(undefined), null);
 });
 
-console.log('\nthe gate — self-gated means requireBuilder, on EVERY route:');
+console.log('\nthe gate — nothing here is anonymous, and every WRITE is rank-gated:');
 
-t('both routes mount requireBuilder, and neither is left ungated', () => {
-  const router = routes();
-  const mounted = router.stack.filter((l) => l.route);
-  assert.equal(mounted.length, 2, 'exactly two routes — a third needs its own gate and its own row here');
-  const paths = mounted.map((l) => l.route.path).sort();
-  assert.deepEqual(paths, ['/agents', '/agents/:name']);
-  for (const layer of mounted) {
+// The surface, spelled out. A route added without a row here fails the roster
+// check below, which is the point: a new verb must state its floor deliberately
+// rather than inherit whatever its neighbour happened to have.
+//
+// The third column is the AUTHORITY ATOM a write gates on, or 'builder' for a
+// self-gated read. Atoms rather than ranks because BV1.R105 requires it of every
+// modules/*/routes gate — tests/government_require_permission.mjs fails the
+// build on a module route that still spells requireRank.
+const SURFACE = Object.freeze([
+  ['get', '/agents', 'builder'],
+  ['get', '/agents/:name', 'builder'],
+  ['post', '/agents', 'agent.author'],
+  ['patch', '/agents/:name', 'agent.author'],
+  ['delete', '/agents/:name', 'agent.author'],
+  ['post', '/agents/:name/enable', 'agent.arm'],
+  ['post', '/agents/:name/disable', 'agent.arm'],
+  ['post', '/agents/:name/invoke', 'builder'],
+  ['get', '/agent-runs/:id', 'builder'],
+]);
+
+t('the mounted surface is exactly the declared one — a new route needs a row here', () => {
+  const mounted = routes().stack.filter((l) => l.route)
+    .map((l) => [Object.keys(l.route.methods)[0], l.route.path]);
+  assert.deepEqual(
+    mounted.map((m) => m.join(' ')).sort(),
+    SURFACE.map(([m, p]) => `${m} ${p}`).sort(),
+  );
+});
+
+t('every route mounts requireBuilder — nothing on this surface is anonymous', () => {
+  for (const layer of routes().stack.filter((l) => l.route)) {
     const handlers = layer.route.stack.map((s) => s.handle);
     assert.ok(handlers.includes(api.requireBuilder),
-      `${layer.route.path} does not mount requireBuilder — a registry read must not be anonymous`);
+      `${layer.route.path} does not mount requireBuilder`);
     assert.ok(handlers.length >= 2, `${layer.route.path} has no handler behind its gate`);
   }
 });
 
-t('every mounted route is a GET — this surface writes nothing', () => {
-  // The read half is a separate task from authoring on purpose. A write verb
-  // appearing here would carry no author-rank clamp and no scope wall.
-  for (const layer of routes().stack.filter((l) => l.route)) {
-    assert.deepEqual(Object.keys(layer.route.methods), ['get'],
-      `${layer.route.path} exposes a non-GET verb on the read surface`);
+t('EVERY WRITE carries a gate behind requireBuilder, and the reads carry none', () => {
+  // The wall this whole task is about: a write verb with no authority gate would
+  // carry no author-rank clamp and no scope wall, because both of those run
+  // inside a handler only a permitted caller reaches.
+  const layers = routes().stack.filter((l) => l.route);
+  for (const [method, path, atom] of SURFACE) {
+    const layer = layers.find((l) => l.route.path === path && l.route.methods[method]);
+    assert.ok(layer, `${method} ${path} is not mounted`);
+    const handlers = layer.route.stack.map((s) => s.handle);
+    // requirePermission returns a fresh closure per call, so it is identified by
+    // POSITION: gate, then handler. A self-gated read has exactly two layers.
+    assert.equal(handlers.length >= 3, atom !== 'builder',
+      `${method} ${path} should be ${atom === 'builder' ? 'self-gated' : `gated on ${atom}`} and is not`);
+    assert.equal(handlers[0], api.requireBuilder, `${method} ${path}: requireBuilder must come first`);
+  }
+});
+
+t('each write names its atom, and no gate has regressed to requireRank', () => {
+  // Two failures this catches. A modules/*/routes gate spelling requireRank
+  // fails BV1.R105 outright; and an atom the catalog does not declare makes
+  // requirePermission deny everyone, so a typo'd key reads as a locked route
+  // rather than an open one — fail-closed, but silent without this.
+  const raw = require('node:fs').readFileSync(new URL('../modules/agents/routes/agents.js', import.meta.url), 'utf8');
+  // Comments stripped first: the header explains WHY these are atoms and not
+  // ranks, and naming requireRank in that explanation must not read as using it.
+  const src = raw.replace(/^\s*\/\/.*$/gm, '');
+  assert.doesNotMatch(src, /requireRank\(/, 'a module route gate must be an authority atom (BV1.R105)');
+  for (const atom of new Set(SURFACE.map(([, , a]) => a).filter((a) => a !== 'builder'))) {
+    const uses = SURFACE.filter(([, , a]) => a === atom).length;
+    const mounted = [...src.matchAll(new RegExp(`api\\.requirePermission\\('${atom}'\\)`, 'g'))].length;
+    assert.equal(mounted, uses, `${atom}: ${uses} routes declared, ${mounted} gates mounted`);
+    assert.ok(catalog.byKey(atom), `${atom} is not declared in the permission catalog — requirePermission would deny everyone`);
+  }
+});
+
+t('the two agent atoms are operational and seed at the Metic floor', () => {
+  // Operational (system:false) so an instance can delegate them from the
+  // Government tab; Metic so this admits exactly who the rank gate would have.
+  for (const key of ['agent.author', 'agent.arm']) {
+    const perm = catalog.byKey(key);
+    assert.equal(perm.system, false, `${key} must be delegable`);
+    assert.equal(perm.floor, 'metic', `${key} must seed at the Metic floor`);
   }
 });