@bongos/core 1.19.518 → 1.19.519

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.518",
-  "core_contract": "1.19.518",
-  "source_commit": "bc3f5970f369e4ec55b26ce60b6f005dbf49da27",
+  "core_version": "1.19.519",
+  "core_contract": "1.19.519",
+  "source_commit": "90936b1d6d76a6e72180bcda5829a33cd130e23e",
   "source_ref": "HEAD",
-  "built_at": "2026-09-03T20:22:13.017Z",
+  "built_at": "2026-09-03T20:29:09.958Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 431,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 1967,
+    "functional_verbatim": 1969,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2422,
-  "tree_sha256": "08479cae8b3ade851270b261e3dcb9dd3b40bf8a6c7efd83bb0fe7d4015993fa",
+  "file_count": 2424,
+  "tree_sha256": "ac3f45936dd7cae4fca5673e5a6f137a59f8fc05c173c58ed0c1ee2a22d9fc64",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -2597,7 +2597,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "068a2fc4cfc8dedd335a836a51b909665d6c3519d9e1e725b8c68627e159df23"
+      "sha256": "0006d40a2c0f79224da4831191e3c1d64a5adf42cadfca08507369a5026bc044"
     },
     {
       "path": "docs/modules-contract.md",
@@ -3574,6 +3574,11 @@
       "mode": "0000644",
       "sha256": "8ae32be783a4ca41637f56626bd83375aa4ae0755e701a0c0170eada8d8303b8"
     },
+    {
+      "path": "modules/agents/lib/validate.js",
+      "mode": "0000644",
+      "sha256": "505b62e453d62b820720c00abf661f1ca1ffbfd93d3eba1bdcdf20c7cca95ba7"
+    },
     {
       "path": "modules/agents/migrations/agents_001_definitions.sql",
       "mode": "0000644",
@@ -7292,12 +7297,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "db1984a27b6127b30741f7bd471e667e18c99966a3a0538e764d1d076b590515"
+      "sha256": "a98e002e52d95a3fbdeee7753bdee264e9beb75b05e98ec78d76e717f761a6a6"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "19fc3311cbafc3efd6980c973a3788b9e4358e9e1da75c29309d204e14a02600"
+      "sha256": "b949b82136e44474714296bbac73758f16c34d51ccafd1fa68859ad701500520"
     },
     {
       "path": "public-docs/index.html",
@@ -8967,7 +8972,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "522ec6fecfe7f0954e86dfeab8e2a06c843fda1d568451d8a248c0401652ef30"
+      "sha256": "96bec9279e853e935c59aeb89ed60538750db43c6b34c2fc0f363cb214b300e5"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9059,6 +9064,11 @@
       "mode": "0000644",
       "sha256": "8cc261471a36e3c447df57b46082997b6a50da3c8ff4b214787ae55ab27cb9ef"
     },
+    {
+      "path": "tests/agents_validate.mjs",
+      "mode": "0000644",
+      "sha256": "c698b80ab8d64421b5c81e91172e1f219c41924af19721106f1899cd29c2fabc"
+    },
     {
       "path": "tests/api_cli_flags.mjs",
       "mode": "0000644",
@@ -11337,7 +11347,7 @@
     {
       "path": "tests/rank_tier_single_source.mjs",
       "mode": "0000644",
-      "sha256": "7840efed42f6960ff25ad9fdd182f979049280566de4831973e5476ab5a6e8ed"
+      "sha256": "6436fe1c0779514294cdd5391149b54d3afd634501ae7a70166348fa25739dce"
     },
     {
       "path": "tests/rate_limit_public.mjs",

package/docs/module-api-changelog.md

@@ -1473,5 +1473,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.516 with no explicit bump. run 33799755382. (task 1002620)
   1.19.518 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.517 with no explicit bump. run 33801792364. (task 1002620)
+  1.19.519 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.518 with no explicit bump. run 33802471495. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/agents/lib/validate.js

@@ -0,0 +1,306 @@
+'use strict';
+
+// modules/agents/lib/validate.js — the pure agent-definition validator (task
+// 1002487, goal 1000038 Phase 1; criterion `agents-malformed-rejected`).
+//
+// Answers one question with no I/O: "is this object a definition this instance is
+// willing to register?" Given a candidate definition and the caller's context
+// (the author's LIVE rank, the module keys in bounds), it returns a verdict plus
+// the full list of what is wrong with it.
+//
+// WHY IT IS PURE, AND WHY THAT IS THE POINT. Definitions arrive from two places —
+// a committed `.claude/agents/*.md` file reconciled at deploy (agents-sync, task
+// 1002490) and an instance-authored DB row. Both paths need the SAME answer, and
+// the answer must be checkable without a database, a model call, or a booted
+// server. So this file requires NOTHING: not the module doorway, not a sibling,
+// not even a node builtin. That also keeps it trivially inside the ADR 0083
+// boundary — `modules/**` may import only `src/module-api.js`, and importing
+// nothing clears that bar by construction.
+//
+// IT MUST NEVER THROW. The loader's contract is log-and-skip: one malformed
+// definition makes the registry smaller, never makes the boot fail. Every access
+// below is therefore defensive — a hostile getter, a circular `trigger_spec`, a
+// frozen object, `null`: all become a returned error, none become an exception
+// into the caller. The tests assert this directly (tests/agents_validate.mjs).
+//
+// FAIL CLOSED IS THE HOUSE RULE, in three specific places a future reader will be
+// tempted to relax:
+//   1. EVENT_CATALOG is the WIRED set, not the imaginable set. v1 dispatches
+//      exactly `task.shipped`. An unwired event name is refused rather than
+//      stored, because a definition carrying one looks armed in the registry and
+//      can never fire — the worst of both readings.
+//   2. An EMPTY allowed-module set means NOTHING is in scope, never everything.
+//      A caller that forgets to pass `allowedModules` gets refusals, not a
+//      wide-open agent. Same rule, same reason as goal-scope-check's `empty_scope`.
+//   3. An UNRESOLVED author rank has no authority over a protected module. A file
+//      cannot grant authority (ADR 0016), so "we could not determine the rank" is
+//      treated as "not enough rank", not as "skip the check".
+//
+// THE DB HOLDS THESE BOUNDS TOO, DELIBERATELY. Every limit here mirrors a CHECK
+// constraint in agents_001_definitions.sql. That duplication is defense in depth
+// and is meant to stay: the constraint is what stops a row that skipped this
+// validator, and this validator is what turns a would-be constraint violation
+// into a readable message naming the offending field — an insert that throws at
+// boot is precisely the crash the log-and-skip contract exists to prevent.
+
+// The WIRED event set for v1. Widening this is a deliberate act that must land
+// together with something that actually dispatches the new event.
+const EVENT_CATALOG = Object.freeze(['task.shipped']);
+
+// Mirrors agents_definitions_trigger_type_chk. 'event' consumes the catalog above;
+// 'on-demand' is the historian shape (a builder asks, the agent answers).
+const TRIGGER_TYPES = Object.freeze(['event', 'on-demand']);
+
+// Mirrors agents_definitions_model_tier_chk. No 'main' tier by design — an agent
+// is a subagent, never the main session.
+const MODEL_TIERS = Object.freeze(['default', 'routine']);
+
+// The rank ladder, low → high. Mirrors government/catalog.js RANK_ORDER and the
+// agents_definitions_author_rank_chk vocabulary. Duplicated rather than imported
+// because the module boundary forbids reaching into core (ADR 0083) — and it is a
+// closed, rarely-changing vocabulary the DB constraint pins independently.
+const RANK_ORDER = Object.freeze(['xenos', 'thetes', 'metic', 'archon']);
+
+// Sub-Metic builders stay out of the permission/methodology core (ADR 0043), and
+// that applies to an agent they author just as it applies to a task they claim.
+const SCOPE_RANK_FLOOR = 'metic';
+
+// Filename / URL-segment / CLI-argument safe — the same shape a module key takes,
+// mirroring agents_definitions_name_fmt_chk.
+const NAME_RE = /^[a-z][a-z0-9-]*$/;
+const NAME_MAX = 64;
+// Mirrors agents_definitions_persona_size_chk / _trigger_spec_size_chk. A persona
+// is a prompt sent to a paid model on every fire, so an unbounded one is both a
+// cost and a blast radius.
+const PERSONA_MAX = 32768;
+const TRIGGER_SPEC_MAX = 8192;
+
+// A plain data object — not an array, not null, not a boxed primitive. Arrays are
+// excluded explicitly because `typeof [] === 'object'` would otherwise let a list
+// masquerade as a spec.
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function isNonEmptyString(v) {
+  return typeof v === 'string' && v.trim().length > 0;
+}
+
+// Read one property without trusting the object. A definition can arrive as a
+// db-sourced object with an accessor on it; a throwing getter must become a
+// refusal, not an exception into the loader.
+function safeGet(obj, key) {
+  try { return obj[key]; } catch (_) { return undefined; }
+}
+
+// A scope path must stay inside the tree. Rejects absolute POSIX and Windows
+// paths, and any `..` segment on either separator — the escape a scope wall
+// exists to stop.
+function isSafeScopePath(p) {
+  if (!isNonEmptyString(p)) return false;
+  if (p.startsWith('/') || p.startsWith('\\')) return false;
+  if (/^[a-zA-Z]:/.test(p)) return false;
+  return !p.split(/[\\/]/).includes('..');
+}
+
+/**
+ * Validate one candidate agent definition. Pure, total, and never throws.
+ *
+ * @param {object} obj  the candidate definition (file frontmatter or a db row).
+ * @param {object} [opts]
+ * @param {string|null} [opts.authorRank]      the author's LIVE DB rank (ADR 0016).
+ *                                             Never read from the definition itself.
+ * @param {string[]} [opts.allowedModules]     module keys this definition may be
+ *                                             scoped to. Empty ⇒ nothing is in scope.
+ * @param {string[]} [opts.protectedModules]   the subset of those that require Metic+.
+ * @returns {{ok: boolean, errors: Array<{code: string, field: string, message: string}>, value: object|null}}
+ *          `value` is the normalized definition (defaults applied) on success, and
+ *          `null` on any failure — a rejected definition must never hand back a row
+ *          something downstream could insert.
+ */
+function validateAgentDefinition(obj, opts = {}) {
+  const errors = [];
+  const E = (code, field, message) => errors.push({ code, field, message });
+
+  if (!isPlainObject(obj)) {
+    return {
+      ok: false,
+      errors: [{
+        code: 'not_an_object',
+        field: '(root)',
+        message: `An agent definition must be an object; received ${obj === null ? 'null' : Array.isArray(obj) ? 'an array' : typeof obj}.`,
+      }],
+      value: null,
+    };
+  }
+
+  // Read through safeGet for the same reason the definition is: a caller may hand
+  // us a proxy or an accessor-bearing object, and the never-throws contract covers
+  // the whole call, not just the definition half of it.
+  const options = isPlainObject(opts) ? opts : {};
+  const authorRank = safeGet(options, 'authorRank');
+  const rawAllowed = safeGet(options, 'allowedModules');
+  const rawProtected = safeGet(options, 'protectedModules');
+  const allowedModules = Array.isArray(rawAllowed) ? rawAllowed : [];
+  const protectedModules = Array.isArray(rawProtected) ? rawProtected : [];
+
+  // --- name ----------------------------------------------------------------
+  const name = safeGet(obj, 'name');
+  if (!isNonEmptyString(name) || !NAME_RE.test(name) || name.length > NAME_MAX) {
+    E('name_invalid', 'name',
+      `name: ${JSON.stringify(name)} must be lowercase kebab-case matching ${NAME_RE} and at most ${NAME_MAX} characters — it is used as a filename, a URL segment and a CLI argument.`);
+  }
+
+  // --- persona --------------------------------------------------------------
+  const persona = safeGet(obj, 'persona');
+  if (!isNonEmptyString(persona)) {
+    E('persona_missing', 'persona',
+      'persona: required — an agent with no role prompt has nothing to run. Give it a non-empty string saying what it observes and reports.');
+  } else if (persona.length > PERSONA_MAX) {
+    E('persona_too_long', 'persona',
+      `persona: ${persona.length} characters exceeds the ${PERSONA_MAX} limit — the persona is sent to a paid model on every fire.`);
+  }
+
+  // --- trigger type ---------------------------------------------------------
+  const triggerType = safeGet(obj, 'trigger_type');
+  const triggerTypeOk = typeof triggerType === 'string' && TRIGGER_TYPES.includes(triggerType);
+  if (!triggerTypeOk) {
+    E('trigger_type_unknown', 'trigger_type',
+      `trigger_type: ${JSON.stringify(triggerType)} is not a wired trigger type. v1 wires exactly: ${TRIGGER_TYPES.join(', ')}.`);
+  }
+
+  // --- trigger spec ---------------------------------------------------------
+  // Defaults to {} when absent, matching the column default. Present-but-wrong is
+  // a refusal; absent is a legitimate on-demand definition.
+  const rawSpec = safeGet(obj, 'trigger_spec');
+  let spec = null;
+  if (rawSpec === undefined || rawSpec === null) {
+    spec = {};
+  } else if (!isPlainObject(rawSpec)) {
+    E('trigger_spec_not_object', 'trigger_spec',
+      `trigger_spec: must be an object of parameters; received ${Array.isArray(rawSpec) ? 'an array' : typeof rawSpec}. It carries the trigger's parameters, never a payload.`);
+  } else {
+    spec = rawSpec;
+    // The size bound is over the SERIALIZED spec, exactly as the DB CHECK measures
+    // it — and JSON.stringify throws on a cycle, which is why this is guarded.
+    let serialized = null;
+    try {
+      serialized = JSON.stringify(spec);
+    } catch (err) {
+      E('trigger_spec_unserializable', 'trigger_spec',
+        `trigger_spec: could not be serialized (${(err && err.message) || 'circular structure'}) — it must be plain JSON data.`);
+      spec = null;
+    }
+    if (serialized !== null && serialized.length > TRIGGER_SPEC_MAX) {
+      E('trigger_spec_too_long', 'trigger_spec',
+        `trigger_spec: ${serialized.length} serialized characters exceeds the ${TRIGGER_SPEC_MAX} limit — it is parameters, never payload.`);
+    }
+  }
+
+  // --- the event catalog, fail-closed ---------------------------------------
+  // Checked whenever an event NAME is present, and additionally REQUIRED for an
+  // event trigger. An inert `event:` on an on-demand definition is either a
+  // typo'd trigger_type or dead config; refusing an unwired name in both places
+  // is what "fails closed on any unwired event name" actually means.
+  if (spec) {
+    const event = safeGet(spec, 'event');
+    const hasEventKey = event !== undefined && event !== null;
+    if (triggerType === 'event' && !isNonEmptyString(event)) {
+      E('trigger_event_missing', 'trigger_spec.event',
+        `trigger_spec.event: required for an 'event' trigger — a definition with no event name can never fire. Wired events: ${EVENT_CATALOG.join(', ')}.`);
+    } else if (hasEventKey && isNonEmptyString(event) && !EVENT_CATALOG.includes(event)) {
+      E('trigger_event_unwired', 'trigger_spec.event',
+        `trigger_spec.event: ${JSON.stringify(event)} is not a wired event and is refused rather than stored — nothing dispatches it, so the agent would look armed and never fire. Wired events: ${EVENT_CATALOG.join(', ')}.`);
+    } else if (hasEventKey && !isNonEmptyString(event) && triggerType !== 'event') {
+      E('trigger_event_unwired', 'trigger_spec.event',
+        `trigger_spec.event: ${JSON.stringify(event)} is not a wired event name. Wired events: ${EVENT_CATALOG.join(', ')}.`);
+    }
+  }
+
+  // --- model tier -----------------------------------------------------------
+  const rawTier = safeGet(obj, 'model_tier');
+  const modelTier = rawTier === undefined || rawTier === null ? 'default' : rawTier;
+  if (!MODEL_TIERS.includes(modelTier)) {
+    E('model_tier_unknown', 'model_tier',
+      `model_tier: ${JSON.stringify(rawTier)} is not a known tier (${MODEL_TIERS.join(', ')}). The tier is stored and resolved to a concrete model at fire time; there is deliberately no 'main' tier.`);
+  }
+
+  // --- scope: shape ---------------------------------------------------------
+  const rawScopeModules = safeGet(obj, 'scope_modules');
+  let scopeModules = null;
+  if (rawScopeModules === undefined || rawScopeModules === null) {
+    scopeModules = [];
+  } else if (!Array.isArray(rawScopeModules) || !rawScopeModules.every(isNonEmptyString)) {
+    E('scope_modules_invalid', 'scope_modules',
+      'scope_modules: must be an array of non-empty module-key strings.');
+  } else {
+    scopeModules = rawScopeModules;
+  }
+
+  const rawScopePaths = safeGet(obj, 'scope_paths');
+  let scopePaths = null;
+  if (rawScopePaths === undefined || rawScopePaths === null) {
+    scopePaths = [];
+  } else if (!Array.isArray(rawScopePaths) || !rawScopePaths.every(isNonEmptyString)) {
+    E('scope_paths_invalid', 'scope_paths',
+      'scope_paths: must be an array of non-empty repo-relative path strings.');
+  } else {
+    const escaping = rawScopePaths.filter((p) => !isSafeScopePath(p));
+    if (escaping.length > 0) {
+      E('scope_paths_invalid', 'scope_paths',
+        `scope_paths: ${escaping.map((p) => JSON.stringify(p)).join(', ')} escape the repository tree — a scope path must be relative and contain no '..' segment.`);
+    } else {
+      scopePaths = rawScopePaths;
+    }
+  }
+
+  // --- scope: the wall ------------------------------------------------------
+  // Note the empty-allowlist behaviour: with nothing allowed, every declared
+  // module is out of bounds. That is the fail-closed default, not an oversight.
+  if (scopeModules && scopeModules.length > 0) {
+    const outOfBounds = scopeModules.filter((m) => !allowedModules.includes(m));
+    if (outOfBounds.length > 0) {
+      E('scope_out_of_bounds', 'scope_modules',
+        `scope_modules: ${outOfBounds.map((m) => JSON.stringify(m)).join(', ')} ${outOfBounds.length === 1 ? 'is' : 'are'} outside the allowed module set (${allowedModules.length ? allowedModules.join(', ') : 'none — no allowed modules were supplied, so nothing is in scope'}).`);
+    }
+
+    // The rank wall, over whatever scope survived the bounds check. An unresolved
+    // rank is treated as insufficient, never as a reason to skip the check.
+    const protectedHits = scopeModules.filter((m) => protectedModules.includes(m));
+    if (protectedHits.length > 0) {
+      const rankIdx = typeof authorRank === 'string' ? RANK_ORDER.indexOf(authorRank) : -1;
+      if (rankIdx < RANK_ORDER.indexOf(SCOPE_RANK_FLOOR)) {
+        E('scope_protected_rank', 'scope_modules',
+          `scope_modules: ${protectedHits.map((m) => JSON.stringify(m)).join(', ')} ${protectedHits.length === 1 ? 'is a protected module' : 'are protected modules'} and require a ${SCOPE_RANK_FLOOR}+ author; the author's resolved rank is ${JSON.stringify(authorRank ?? null)} (ADR 0016 / ADR 0043). Authority comes from the author's live rank, never from the definition.`);
+      }
+    }
+  }
+
+  if (errors.length > 0) return { ok: false, errors, value: null };
+
+  // The normalized row, built fresh — the caller's object is never mutated, and
+  // arrays are copied so a later mutation of the input cannot reach the registry.
+  return {
+    ok: true,
+    errors: [],
+    value: {
+      name,
+      title: isNonEmptyString(safeGet(obj, 'title')) ? safeGet(obj, 'title') : null,
+      persona,
+      trigger_type: triggerType,
+      trigger_spec: { ...spec },
+      model_tier: modelTier,
+      scope_modules: [...scopeModules],
+      scope_paths: [...scopePaths],
+    },
+  };
+}
+
+module.exports = {
+  validateAgentDefinition,
+  EVENT_CATALOG,
+  TRIGGER_TYPES,
+  MODEL_TIERS,
+  RANK_ORDER,
+  SCOPE_RANK_FLOOR,
+};

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.518",
+  "version": "1.19.519",
   "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

@@ -45,7 +45,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.518'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.519'; // 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_validate.mjs

@@ -0,0 +1,354 @@
+// tests/agents_validate.mjs — the pure agent-definition validator (task 1002487,
+// goal 1000038).
+//
+// Gates criterion `agents-malformed-rejected`: a malformed definition (unknown
+// trigger; missing persona; `trigger_spec.event` not in EVENT_CATALOG; scope
+// exceeding an allowed module) is refused with a clear error, and the validator
+// NEVER throws — the loader logs and skips, it does not crash the boot.
+//
+// No database, no fixtures, no fs. Every input is a literal, because the thing
+// under test is a pure decision.
+//
+// Run:  node tests/agents_validate.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const {
+  validateAgentDefinition,
+  EVENT_CATALOG,
+  TRIGGER_TYPES,
+  MODEL_TIERS,
+  RANK_ORDER,
+  SCOPE_RANK_FLOOR,
+} = require('../modules/agents/lib/validate.js');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.error(`  FAIL ${name}\n    ${err.message}`); }
+}
+
+// A definition that passes everything, so each case below can break exactly one
+// thing and attribute the refusal to that one thing.
+const OK_DEF = Object.freeze({
+  name: 'historian',
+  persona: 'Observe the shipped task and report what changed.',
+  trigger_type: 'event',
+  trigger_spec: { event: 'task.shipped' },
+  model_tier: 'default',
+  scope_modules: ['agents'],
+});
+const OPTS = Object.freeze({ authorRank: 'archon', allowedModules: ['agents'] });
+
+const codes = (r) => r.errors.map((e) => e.code);
+const hasCode = (r, code) => codes(r).includes(code);
+
+// --- THE BASELINE -----------------------------------------------------------
+
+await test('the exemplar definition validates, and normalizes into a value', () => {
+  const r = validateAgentDefinition(OK_DEF, OPTS);
+  assert.equal(r.ok, true, `expected ok, got errors: ${JSON.stringify(r.errors)}`);
+  assert.deepEqual(r.errors, []);
+  assert.equal(r.value.name, 'historian');
+  assert.equal(r.value.model_tier, 'default');
+  assert.deepEqual(r.value.scope_modules, ['agents']);
+});
+
+await test('a failed validation returns NO value — nothing downstream can insert it', () => {
+  const r = validateAgentDefinition({ ...OK_DEF, persona: '' }, OPTS);
+  assert.equal(r.ok, false);
+  assert.equal(r.value, null, 'a rejected definition must not hand back a usable row');
+});
+
+// --- THE EVENT CATALOG — the fail-closed rule -------------------------------
+
+await test('EVENT_CATALOG is exactly the v1 wired set, and is frozen', () => {
+  assert.deepEqual(EVENT_CATALOG, ['task.shipped']);
+  assert.equal(Object.isFrozen(EVENT_CATALOG), true, 'a caller must not be able to widen the catalog at runtime');
+});
+
+await test('an UNWIRED event name is REFUSED, never silently accepted', () => {
+  // The whole point of the catalog: an event nothing dispatches would produce an
+  // agent that looks armed and never fires.
+  for (const bad of ['task.completed', 'task.shipped ', 'TASK.SHIPPED', 'claim.created', 'task.*']) {
+    const r = validateAgentDefinition({ ...OK_DEF, trigger_spec: { event: bad } }, OPTS);
+    assert.equal(r.ok, false, `"${bad}" must be refused`);
+    assert.ok(hasCode(r, 'trigger_event_unwired'), `"${bad}" → ${JSON.stringify(codes(r))}`);
+  }
+});
+
+await test('the refusal NAMES the offending event and the catalog', () => {
+  const r = validateAgentDefinition({ ...OK_DEF, trigger_spec: { event: 'task.completed' } }, OPTS);
+  const msg = r.errors.find((e) => e.code === 'trigger_event_unwired').message;
+  assert.ok(msg.includes('task.completed'), `message must name the offender: ${msg}`);
+  assert.ok(msg.includes('task.shipped'), `message must name what IS wired: ${msg}`);
+});
+
+await test('an event trigger with no event name is refused', () => {
+  for (const spec of [{}, { event: '' }, { event: '   ' }, { event: null }, { event: 42 }]) {
+    const r = validateAgentDefinition({ ...OK_DEF, trigger_spec: spec }, OPTS);
+    assert.equal(r.ok, false, `${JSON.stringify(spec)} must be refused`);
+    assert.ok(
+      hasCode(r, 'trigger_event_missing') || hasCode(r, 'trigger_event_unwired'),
+      `${JSON.stringify(spec)} → ${JSON.stringify(codes(r))}`,
+    );
+  }
+});
+
+await test('an on-demand definition needs no event at all', () => {
+  const r = validateAgentDefinition(
+    { ...OK_DEF, trigger_type: 'on-demand', trigger_spec: {} }, OPTS,
+  );
+  assert.equal(r.ok, true, JSON.stringify(r.errors));
+});
+
+await test('an on-demand definition carrying an UNWIRED event is still refused', () => {
+  // Fails closed on the event NAME wherever it appears. An inert `event:` key on
+  // an on-demand agent is either a typo'd trigger_type or dead config; both are
+  // bugs the author should be shown rather than have silently accepted.
+  const r = validateAgentDefinition(
+    { ...OK_DEF, trigger_type: 'on-demand', trigger_spec: { event: 'task.completed' } }, OPTS,
+  );
+  assert.equal(r.ok, false);
+  assert.ok(hasCode(r, 'trigger_event_unwired'));
+});
+
+await test('an on-demand definition carrying a WIRED event is accepted', () => {
+  const r = validateAgentDefinition(
+    { ...OK_DEF, trigger_type: 'on-demand', trigger_spec: { event: 'task.shipped' } }, OPTS,
+  );
+  assert.equal(r.ok, true, JSON.stringify(r.errors));
+});
+
+// --- THE TRIGGER TYPE -------------------------------------------------------
+
+await test('TRIGGER_TYPES is the v1 pair the DB CHECK also pins', () => {
+  assert.deepEqual(TRIGGER_TYPES, ['event', 'on-demand']);
+});
+
+await test('an unknown trigger type is refused', () => {
+  for (const bad of ['cron', 'webhook', 'Event', 'on demand', '', null, undefined, 7, {}]) {
+    const r = validateAgentDefinition({ ...OK_DEF, trigger_type: bad }, OPTS);
+    assert.equal(r.ok, false, `${JSON.stringify(bad)} must be refused`);
+    assert.ok(hasCode(r, 'trigger_type_unknown'), `${JSON.stringify(bad)} → ${JSON.stringify(codes(r))}`);
+  }
+});
+
+await test('a non-object trigger_spec is refused rather than coerced', () => {
+  for (const bad of ['task.shipped', 42, [], true]) {
+    const r = validateAgentDefinition({ ...OK_DEF, trigger_spec: bad }, OPTS);
+    assert.equal(r.ok, false, `${JSON.stringify(bad)} must be refused`);
+    assert.ok(hasCode(r, 'trigger_spec_not_object'), `${JSON.stringify(bad)} → ${JSON.stringify(codes(r))}`);
+  }
+});
+
+// --- THE PERSONA ------------------------------------------------------------
+
+await test('a missing or empty persona is refused', () => {
+  for (const bad of [undefined, null, '', '   ', 42, {}]) {
+    const r = validateAgentDefinition({ ...OK_DEF, persona: bad }, OPTS);
+    assert.equal(r.ok, false, `${JSON.stringify(bad)} must be refused`);
+    assert.ok(hasCode(r, 'persona_missing'), `${JSON.stringify(bad)} → ${JSON.stringify(codes(r))}`);
+  }
+});
+
+await test('an oversized persona is refused at the same bound the DB CHECK holds', () => {
+  const r = validateAgentDefinition({ ...OK_DEF, persona: 'x'.repeat(32769) }, OPTS);
+  assert.equal(r.ok, false);
+  assert.ok(hasCode(r, 'persona_too_long'));
+  // ...and exactly at the bound it is fine.
+  assert.equal(validateAgentDefinition({ ...OK_DEF, persona: 'x'.repeat(32768) }, OPTS).ok, true);
+});
+
+// --- THE NAME ---------------------------------------------------------------
+
+await test('a name that could not be a filename / URL segment / CLI arg is refused', () => {
+  for (const bad of ['Historian', '1historian', 'the historian', 'his/torian', '-historian', '', 'a'.repeat(65)]) {
+    const r = validateAgentDefinition({ ...OK_DEF, name: bad }, OPTS);
+    assert.equal(r.ok, false, `"${bad}" must be refused`);
+    assert.ok(hasCode(r, 'name_invalid'), `"${bad}" → ${JSON.stringify(codes(r))}`);
+  }
+  assert.equal(validateAgentDefinition({ ...OK_DEF, name: 'a'.repeat(64) }, OPTS).ok, true);
+});
+
+// --- THE MODEL TIER ---------------------------------------------------------
+
+await test('model_tier defaults to `default` when absent, and rejects an unknown tier', () => {
+  assert.deepEqual(MODEL_TIERS, ['default', 'routine']);
+  const { model_tier: _omit, ...noTier } = OK_DEF;
+  const r = validateAgentDefinition(noTier, OPTS);
+  assert.equal(r.ok, true, JSON.stringify(r.errors));
+  assert.equal(r.value.model_tier, 'default');
+
+  // spawn.js's resolveModel() deliberately DEGRADES an unknown tier to the default
+  // tier at fire time; that is a runtime safety net, not a licence to author one.
+  const bad = validateAgentDefinition({ ...OK_DEF, model_tier: 'main' }, OPTS);
+  assert.equal(bad.ok, false);
+  assert.ok(hasCode(bad, 'model_tier_unknown'));
+});
+
+await test('there is no `main` tier — an agent is a subagent, never the main session', () => {
+  assert.equal(MODEL_TIERS.includes('main'), false);
+});
+
+// --- THE SCOPE WALL ---------------------------------------------------------
+
+await test('scope exceeding the allowed modules is refused, naming the offenders', () => {
+  const r = validateAgentDefinition(
+    { ...OK_DEF, scope_modules: ['agents', 'government', 'lifecycle'] },
+    { authorRank: 'archon', allowedModules: ['agents'] },
+  );
+  assert.equal(r.ok, false);
+  assert.ok(hasCode(r, 'scope_out_of_bounds'));
+  const msg = r.errors.find((e) => e.code === 'scope_out_of_bounds').message;
+  assert.ok(msg.includes('government') && msg.includes('lifecycle'), `must name the offenders: ${msg}`);
+  assert.ok(!msg.includes("'agents'"), 'must not accuse the module that WAS allowed');
+});
+
+await test('scope FAILS CLOSED when the caller supplies no allowed-module set', () => {
+  // The dangerous default. An empty allowlist must mean "nothing is in scope",
+  // never "everything is" — the same rule goal-scope-check's empty_scope holds.
+  for (const opts of [{ authorRank: 'archon' }, { authorRank: 'archon', allowedModules: [] }, undefined]) {
+    const r = validateAgentDefinition(OK_DEF, opts);
+    assert.equal(r.ok, false, `${JSON.stringify(opts)} must fail closed`);
+    assert.ok(hasCode(r, 'scope_out_of_bounds'), `${JSON.stringify(opts)} → ${JSON.stringify(codes(r))}`);
+  }
+});
+
+await test('an empty scope_modules is allowed — it grants nothing', () => {
+  const r = validateAgentDefinition({ ...OK_DEF, scope_modules: [] }, { authorRank: 'archon', allowedModules: [] });
+  assert.equal(r.ok, true, JSON.stringify(r.errors));
+  assert.deepEqual(r.value.scope_modules, []);
+});
+
+await test('a non-array / non-string scope is refused rather than coerced', () => {
+  for (const bad of ['agents', 42, {}, ['agents', 7], ['agents', '']]) {
+    const r = validateAgentDefinition({ ...OK_DEF, scope_modules: bad }, OPTS);
+    assert.equal(r.ok, false, `${JSON.stringify(bad)} must be refused`);
+    assert.ok(hasCode(r, 'scope_modules_invalid'), `${JSON.stringify(bad)} → ${JSON.stringify(codes(r))}`);
+  }
+});
+
+await test('a scope_path that escapes the tree is refused', () => {
+  for (const bad of ['../../etc/passwd', '/etc/passwd', 'modules/../../..', 'C:\\Windows']) {
+    const r = validateAgentDefinition({ ...OK_DEF, scope_paths: [bad] }, OPTS);
+    assert.equal(r.ok, false, `"${bad}" must be refused`);
+    assert.ok(hasCode(r, 'scope_paths_invalid'), `"${bad}" → ${JSON.stringify(codes(r))}`);
+  }
+  assert.equal(validateAgentDefinition({ ...OK_DEF, scope_paths: ['modules/agents/'] }, OPTS).ok, true);
+});
+
+// --- THE RANK WALL (ADR 0016 — authority is the author's LIVE rank) ---------
+
+await test('RANK_ORDER is the ladder low→high, and the scope floor is Metic', () => {
+  assert.deepEqual(RANK_ORDER, ['xenos', 'thetes', 'metic', 'archon']);
+  assert.equal(SCOPE_RANK_FLOOR, 'metic');
+});
+
+await test('a sub-Metic author may not scope an agent onto a PROTECTED module', () => {
+  const opts = { allowedModules: ['agents', 'government'], protectedModules: ['government'] };
+  for (const rank of ['xenos', 'thetes']) {
+    const r = validateAgentDefinition({ ...OK_DEF, scope_modules: ['government'] }, { ...opts, authorRank: rank });
+    assert.equal(r.ok, false, `${rank} must not reach a protected module`);
+    assert.ok(hasCode(r, 'scope_protected_rank'), `${rank} → ${JSON.stringify(codes(r))}`);
+  }
+  // Metic+ clear the floor.
+  for (const rank of ['metic', 'archon']) {
+    const r = validateAgentDefinition({ ...OK_DEF, scope_modules: ['government'] }, { ...opts, authorRank: rank });
+    assert.equal(r.ok, true, `${rank} should clear the floor: ${JSON.stringify(r.errors)}`);
+  }
+});
+
+await test('an UNKNOWN author rank fails CLOSED against a protected module', () => {
+  // A file cannot grant authority (ADR 0016). If the caller could not name a live
+  // rank, the definition has no authority to reach a protected module.
+  const opts = { allowedModules: ['government'], protectedModules: ['government'] };
+  for (const rank of [undefined, null, '', 'admin', 'ARCHON']) {
+    const r = validateAgentDefinition({ ...OK_DEF, scope_modules: ['government'] }, { ...opts, authorRank: rank });
+    assert.equal(r.ok, false, `${JSON.stringify(rank)} must fail closed`);
+    assert.ok(hasCode(r, 'scope_protected_rank'), `${JSON.stringify(rank)} → ${JSON.stringify(codes(r))}`);
+  }
+});
+
+await test('an unknown rank is NOT fatal when no protected module is in scope', () => {
+  // The rank wall guards protected scope only; an ordinary agent does not need a
+  // resolved rank to be structurally valid.
+  const r = validateAgentDefinition(OK_DEF, { authorRank: 'nonsense', allowedModules: ['agents'] });
+  assert.equal(r.ok, true, JSON.stringify(r.errors));
+});
+
+// --- NEVER CRASH THE BOOT ---------------------------------------------------
+
+await test('a non-object definition is refused, not thrown on', () => {
+  for (const bad of [null, undefined, 'historian', 42, [], true]) {
+    let r;
+    assert.doesNotThrow(() => { r = validateAgentDefinition(bad, OPTS); }, `${JSON.stringify(bad)} threw`);
+    assert.equal(r.ok, false);
+    assert.ok(hasCode(r, 'not_an_object'), `${JSON.stringify(bad)} → ${JSON.stringify(codes(r))}`);
+  }
+});
+
+await test('a CIRCULAR trigger_spec is refused, not thrown on', () => {
+  // The size check is over the serialized spec, and JSON.stringify THROWS on a
+  // cycle. A definition file cannot express one, but a db-sourced object can —
+  // and this validator is the thing standing between that and the boot.
+  const spec = { event: 'task.shipped' };
+  spec.self = spec;
+  let r;
+  assert.doesNotThrow(() => { r = validateAgentDefinition({ ...OK_DEF, trigger_spec: spec }, OPTS); });
+  assert.equal(r.ok, false);
+  assert.ok(hasCode(r, 'trigger_spec_unserializable'), JSON.stringify(codes(r)));
+});
+
+await test('an oversized trigger_spec is refused at the DB CHECK bound', () => {
+  const r = validateAgentDefinition(
+    { ...OK_DEF, trigger_spec: { event: 'task.shipped', pad: 'x'.repeat(9000) } }, OPTS,
+  );
+  assert.equal(r.ok, false);
+  assert.ok(hasCode(r, 'trigger_spec_too_long'));
+});
+
+await test('a hostile getter cannot escape the validator', () => {
+  // trigger_spec is PARAMETERS, never payload — and a throwing accessor must
+  // become a refusal, not an exception into the loader.
+  const hostile = { name: 'historian', persona: 'x', trigger_type: 'event' };
+  Object.defineProperty(hostile, 'trigger_spec', { get() { throw new Error('boom'); }, enumerable: true });
+  let r;
+  assert.doesNotThrow(() => { r = validateAgentDefinition(hostile, OPTS); });
+  assert.equal(r.ok, false);
+});
+
+await test('EVERY error carries a code, a field and a human message', () => {
+  const r = validateAgentDefinition(
+    { name: 'BAD NAME', trigger_type: 'cron', trigger_spec: 'nope', scope_modules: ['government'] },
+    { authorRank: 'xenos', allowedModules: ['agents'] },
+  );
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.length >= 4, `expected the whole list, got ${JSON.stringify(codes(r))}`);
+  for (const e of r.errors) {
+    assert.equal(typeof e.code, 'string', JSON.stringify(e));
+    assert.equal(typeof e.field, 'string', JSON.stringify(e));
+    assert.ok(e.message && e.message.length > 10, `message too thin: ${JSON.stringify(e)}`);
+  }
+});
+
+await test('validation reports ALL faults at once, not just the first', () => {
+  // An author fixing a definition file should not have to re-run four times.
+  const r = validateAgentDefinition({ name: 'X', persona: '', trigger_type: 'cron' }, OPTS);
+  for (const code of ['name_invalid', 'persona_missing', 'trigger_type_unknown']) {
+    assert.ok(hasCode(r, code), `${code} missing from ${JSON.stringify(codes(r))}`);
+  }
+});
+
+await test('the validator never MUTATES the definition it was handed', () => {
+  const def = { ...OK_DEF, trigger_spec: { event: 'task.shipped' } };
+  const before = JSON.stringify(def);
+  validateAgentDefinition(def, OPTS);
+  assert.equal(JSON.stringify(def), before);
+});
+
+console.log(`\nagents_validate: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/tests/rank_tier_single_source.mjs

@@ -116,6 +116,17 @@ const STATIC_LADDER_FILES = [
   // which holds it against catalog.RANK_ORDER and holds the whole browser parser
   // equal to the server one.
   'modules/hall-ui/public/government.js',
+  // task 1002487: the pure agent-definition validator applies the ADR 0043
+  // sub-Metic floor to an agent's declared scope, so it needs the ladder to
+  // compare against. It is one of the "dependency-free" cases this array exists
+  // for, and for a sharper reason than the browser statics above: its whole
+  // contract is to be checkable with NO database, and the doorway it would
+  // otherwise import (src/module-api.js) eagerly requires ./bongos/pool at load.
+  // Deriving the ladder from api.LIVE_RANK_LADDER would therefore drag a
+  // Postgres pool into a validator that must run in a bare unit test — so the
+  // copy is pinned here instead, which is what makes it provable rather than
+  // merely allowed.
+  'modules/agents/lib/validate.js',
 ];
 test('static ladder copies carry the exact canonical ladder', () => {
   for (const rel of STATIC_LADDER_FILES) {