@bongos/core 1.19.64 → 1.19.65

package/modules/provisioning/module.json

@@ -8,6 +8,7 @@
   "origin": "Off the Boats (the first Cloud Bongos instance, amazonprimea.com)",
   "license": "AGPL-3.0",
   "maintainer": "Off the Boats maintainers",
+  "maintenance": { "status": "core-maintained" },
   "contributes": {
     "routes": ["provisioning"],
     "migrations": true

package/modules/security/module.json

@@ -4,6 +4,7 @@
   "description": "The red-team / vulnerability-report intake and the bounty payout system (rank-gated Metic+): the /builder-redteam skill files a report, the Archon dashboard adjudicates (confirm/dispute/fix/link-fix), and the env-aware bounty table sets the per-severity drachmae payout. A core-domain module carved out of the GDS core in BV1.R79 (ADR 0093 §1; 02-module-map §5 — security-the-FEATURE, NOT security-the-property, which stays kernel). default-on because every instance can take red-team reports. Registers the `security` kernel PORT the core /public/bounty-table resolves for the payout schedule. Also owns the scan-before-install surface (goal 1000055): the artifact-scan engine (quarantine/manifest/mirror) and the security_tool_scans record — POST Metic+, GET every rank.",
   "coreVersion": "^1.8.0",
   "default": true,
+  "maintenance": { "status": "core-maintained" },
   "contributes": { "routes": ["reports", "scans"], "migrations": true },
   "provides": ["security"],
   "consumes": []

package/modules/sessions/module.json

@@ -4,6 +4,7 @@
   "description": "The session-records corpus + its data plane (POST /sessions upload, the Archon-gated cross-builder /sessions/search + /sessions/:id deep-dive), the BFG 'read-the-room' cross-builder scorer (ADR 0026 §6B), and the session-pulse / stale-claim heartbeat helpers. A core-domain module carved out of the GDS core in BV1.R82 (ADR 0093 §1); default-on because every instance records its builders' sessions for the BFG. Like the memory module, sessions registers no port — core never calls back into it: the ship-time digest write is an HTTP POST to the module's own /sessions route, and the only outward dependency is the economy `reward` kernel PORT it resolves (session token reward + sumCreditsForTasks) at upload time.",
   "coreVersion": "^1.10.0",
   "default": true,
+  "maintenance": { "status": "core-maintained" },
   "contributes": { "routes": ["sessions"], "pollers": ["session-reward-reconcile"] },
   "provides": [],
   "consumes": []

package/modules/status-ui/module.json

@@ -4,6 +4,7 @@
   "description": "The public build-status dashboard served at status.<apex> (status.amazonprimea.com) — the live up/down banner, version-progress rollups, cost summary, recent ships, leaderboard, and the ecosystem fingerprint, all polling the read-only /api/gds/public/* surface every 60s. A WEB-SURFACE core-domain module carved out of the GDS core in BV1.R84 (ADR 0093 §1; 02-module-map §6 — a web surface is first-class). default-on: a Cloud Bongos instance ships its status page like it ships its hall. Registers no port and contributes no routes — it declares a webSurface (host prefix + static dir) the loader hands serve-internal, which serves the module's public/ dir on the matching host exactly as it served public-status/ before. The public read endpoints it renders stay SHARED core in routes/public.js (the hall + the off-box mirror read them too).",
   "coreVersion": "^1.11.0",
   "default": true,
+  "maintenance": { "status": "core-maintained" },
   "contributes": {
     "webSurfaces": [
       { "host": "status.", "dir": "public" }

package/package-lock.json

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

package/package.json

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

@@ -34,7 +34,10 @@
 //     because a brand-new module is never on the ALLOWLIST until it is
 //     accepted (§6); that omission must not read as "denied content." Also
 //     requires the manifest to declare an AGPL-3.0 license (inbound = outbound,
-//     ADR 0107 §4 — no CLA). On a pass, `--sign-off "Name <email>"` records a
+//     ADR 0107 §4 — no CLA) and a `maintenance` posture (ADR 0107 §7 / ADR
+//     0166 — core-maintained, or maintained by a named maintainer; a module
+//     already deprecated/orphaned cannot be submitted INTO the catalog).
+//     On a pass, `--sign-off "Name <email>"` records a
 //     lightweight DCO-style affirmation (own work, licensed AGPL-3.0 — never a
 //     copyright-assignment CLA) to modules/<key>/.upstream-signoff.json.
 //
@@ -54,7 +57,8 @@ const path = require('node:path');
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 const MODULES_DIR = path.join(REPO_ROOT, 'modules');
 
-const { validateManifest, assertValidManifest, KEY_RE } = require('../../src/module-loader/manifest-schema');
+const { validateManifest, assertValidManifest, KEY_RE, SUNSET_STATUSES } = require('../../src/module-loader/manifest-schema');
+const { parseVersion, cmp } = require('../../src/module-loader/semver');
 const loader = require('../../src/module-loader/loader');
 const { resolveModules, MODULE_REGISTRY, NEUTRAL_PATH, INSTANCE_PATH } = require('../../src/modules');
 // The public-mirror publish boundary (ADR 0098) — REUSED, never re-typed, for
@@ -115,6 +119,11 @@ function buildManifest(key, { core = coreVersion() } = {}) {
     origin: 'TODO: the instance/project this module was built in',
     license: 'AGPL-3.0',
     maintainer: 'TODO: who to credit/contact if this module is upstreamed',
+    // Upkeep posture (ADR 0107 §7 / ADR 0166). Scaffolded as `maintained`
+    // because a brand-new module's author IS its maintainer — the honest
+    // default. Change it to `core-maintained` only if the core team has agreed
+    // to own it, and to `deprecated`/`orphaned` (with a path) when that changes.
+    maintenance: { status: 'maintained' },
     contributes: { routes: [key] },
   };
 }
@@ -191,13 +200,51 @@ kernel seams (\`api.registerProvider\` / \`api.resolve\` / \`api.on\` / \`api.em
 `;
 }
 
+// Has the core advanced past a deprecated module's declared removal version?
+// `removeAfter: "1.12.0"` means "may be deleted once core is ABOVE 1.12.0".
+function isPastRemoveAfter(maintenance, core) {
+  const after = maintenance && maintenance.removeAfter;
+  const a = parseVersion(after);
+  const c = parseVersion(core);
+  return !!(a && c && cmp(c, a) > 0);
+}
+
+// One line of "who do I chase about this?" for a row, from its maintenance block
+// (ADR 0166). Shared by cmdUpgrade and upgrade.js's real-bump pre-flight so both
+// surfaces say the same thing about the same module.
+function formatMaintenanceHint(row = {}) {
+  const m = row.maintenance;
+  if (!m || !m.status) {
+    return 'no maintenance declared — nobody is on the hook for this module (ADR 0166: declare a `maintenance` block)';
+  }
+  const parts = [`maintenance: ${m.status}`];
+  if (m.status === 'maintained') parts.push(`maintainer ${row.maintainer || '(unnamed!)'}`);
+  if (m.status === 'core-maintained') parts.push('core-maintained — fixing this is the core\'s job');
+  if (m.successor) parts.push(`superseded by "${m.successor}"`);
+  if (m.removeAfter) parts.push(`removable after core ${m.removeAfter}`);
+  if (m.note) parts.push(m.note);
+  return parts.join('; ');
+}
+
 // Decide compatibility from rows (pure — tests drive it with injected rows).
-// A row: { key, coreVersion, enabled, satisfied }. BLOCKING = an enabled module
-// that does not satisfy the core (fail-closed). A disabled mismatch is a warning.
+// A row: { key, coreVersion, enabled, satisfied, maintenance?, maintainer? }.
+//
+// BLOCKING = an enabled module that does not satisfy the core (fail-closed).
+// WARNINGS = a DISABLED mismatch. These are not cosmetic: an accepted catalog
+// module ships `default: false` (ADR 0107 §6), so EVERY rotted catalog entry
+// lands in this bucket. Dropping warnings on the floor is exactly how "the
+// catalog fills with silently-broken entries" happens (ADR 0107 §7) — every
+// caller must surface them, even though none of them block.
+// DEPRECATIONS = modules whose own manifest says they are on the way out;
+// EXPIRED = deprecated modules the core has already advanced past `removeAfter`
+// (they are due for deletion, not just a label).
 function evaluateUpgrade({ rows = [], errors = [], core } = {}) {
   const blocking = rows.filter((r) => r.enabled && !r.satisfied);
   const warnings = rows.filter((r) => !r.enabled && !r.satisfied);
-  return { ok: blocking.length === 0, blocking, warnings, rows, errors, core };
+  const deprecations = rows.filter((r) => r.maintenance && SUNSET_STATUSES.includes(r.maintenance.status));
+  const expired = deprecations.filter((r) => isPastRemoveAfter(r.maintenance, core));
+  const undeclared = rows.filter((r) => !r.maintenance || !r.maintenance.status);
+  return { ok: blocking.length === 0, blocking, warnings, deprecations, expired, undeclared, rows, errors, core };
 }
 
 // ---------------------------------------------------------------------------
@@ -261,12 +308,20 @@ function gatherUpgrade({ modulesDir = MODULES_DIR, core = coreVersion(), env = p
   try { enabled = resolveModules({ neutral, instance, env, envPrefix: prefix, registry }); }
   catch { /* a malformed config shouldn't crash the pre-check; treat all as disabled */ }
 
+  // Maintenance posture travels with the row (ADR 0166) so both the pre-check
+  // printout and the real bump can say WHO owns a module that no longer fits —
+  // an incompatibility with no owner named is the orphaning failure itself.
+  const upkeep = (manifest) => ({
+    maintenance: (manifest && manifest.maintenance) || null,
+    maintainer: (manifest && manifest.maintainer) || null,
+  });
+
   const rows = [];
   for (const { key, manifest } of loaded) {
-    rows.push({ key, coreVersion: manifest.coreVersion, enabled: enabled[key] === true, satisfied: true });
+    rows.push({ key, coreVersion: manifest.coreVersion, enabled: enabled[key] === true, satisfied: true, ...upkeep(manifest) });
   }
   for (const { key, manifest, reason } of skippedFull) {
-    rows.push({ key, coreVersion: manifest ? manifest.coreVersion : null, enabled: enabled[key] === true, satisfied: false, reason });
+    rows.push({ key, coreVersion: manifest ? manifest.coreVersion : null, enabled: enabled[key] === true, satisfied: false, reason, ...upkeep(manifest) });
   }
   rows.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
   return { rows, errors, core };
@@ -320,6 +375,29 @@ function checkModulePublishability(key, { modulesDir = MODULES_DIR } = {}) {
           'AGPL-3.0 (inbound = outbound, ADR 0107 §4)',
       });
     }
+
+    // ADR 0107 §7 / ADR 0166 — the maintenance gate. Acceptance into the shared
+    // catalog is a commitment to keep the module true as the core advances, so
+    // the module must SAY who is committing before it can be filed for review.
+    // The shape is already schema-validated above (a `maintained` module must
+    // name a maintainer; a sunset one must state its path); what this adds is
+    // that the block cannot simply be absent. Refusing here — at submit time —
+    // is what keeps the catalog from filling with entries nobody owns.
+    const maint = manifestRaw.maintenance;
+    if (!maint || !maint.status) {
+      findings.push({
+        kind: 'maintenance',
+        detail: 'module.json declares no `maintenance.status` — an upstreamed module must state its upkeep ' +
+          'posture (ADR 0107 §7): "core-maintained" (the core team owns it) or "maintained" with a named ' +
+          '`maintainer`. A module nobody owns rots silently as the core advances.',
+      });
+    } else if (SUNSET_STATUSES.includes(maint.status)) {
+      findings.push({
+        kind: 'maintenance',
+        detail: `module.json declares maintenance.status "${maint.status}" — a module already on its way out ` +
+          'cannot be submitted INTO the catalog. Upstream a maintained module, or its successor.',
+      });
+    }
   }
 
   // Classify every file AS IF it already lived at its canonical modules/<key>/
@@ -428,13 +506,28 @@ function cmdUpgrade(_args, { log = console.log, errlog = console.error, gather =
     const state = r.enabled ? 'enabled' : 'disabled';
     let note = '';
     if (!r.satisfied) {
+      // A DISABLED mismatch is harmless to THIS boot, but it is not harmless to
+      // the catalog — it is a rotted entry with an owner who needs telling
+      // (ADR 0166). Name that owner right here rather than shrugging at it.
       note = `  — coreVersion ${r.coreVersion || '(none)'} not satisfied by core ${verdict.core}` +
-        (r.enabled ? ' — will NOT mount' : ' (disabled, harmless)');
+        (r.enabled ? ' — will NOT mount' : ' — disabled, so it does not block this boot, but it is BROKEN if enabled') +
+        `\n      ↳ ${formatMaintenanceHint(r)}`;
     }
     log(`  ${mark} ${r.key.padEnd(18)} ${String(r.coreVersion || '').padEnd(10)} ${state}${note}`);
   }
   for (const e of data.errors) errlog(`  ! ${e.dir}: ${(e.errors || []).join('; ')}`);
 
+  // Deprecation roll-up (ADR 0166) — separate from compatibility: a module can
+  // satisfy the core perfectly and still be on its way out.
+  for (const d of verdict.deprecations) {
+    const overdue = verdict.expired.includes(d);
+    errlog(`  ${overdue ? '✗' : '!'} ${d.key}: ${d.maintenance.status}${overdue ? ` — PAST removeAfter ${d.maintenance.removeAfter} (core is ${verdict.core}); it is due for removal` : ''}`);
+    errlog(`      ↳ ${formatMaintenanceHint(d)}`);
+  }
+  if (verdict.undeclared.length) {
+    errlog(`  ! ${verdict.undeclared.length} module(s) declare no \`maintenance\` block — nobody is on the hook for them as the core advances (ADR 0166): ${verdict.undeclared.map((r) => r.key).join(', ')}`);
+  }
+
   if (!verdict.ok) {
     errlog(`\nREFUSING: ${verdict.blocking.length} enabled module(s) incompatible with core ${verdict.core}: ${verdict.blocking.map((b) => b.key).join(', ')}.`);
     errlog(`Widen each module's coreVersion to a range that includes ${verdict.core} (or hold the core upgrade) before proceeding.`);
@@ -459,7 +552,7 @@ function cmdCheck(args, { log = console.log, errlog = console.error, check = che
 
   log(`bongos module check — upstreaming pre-check for "${key}"`);
   if (result.ok) {
-    log('  ✓ AGPL/publish pre-check passed — no denied content, license is AGPL-3.0.');
+    log('  ✓ AGPL/publish pre-check passed — no denied content, license is AGPL-3.0, upkeep is declared.');
   } else {
     for (const f of result.findings) errlog(`  ✗ ${f.kind}: ${f.detail}`);
   }
@@ -582,6 +675,7 @@ async function main(argv) {
 module.exports = {
   main, cmdNew, cmdUpgrade, cmdCheck, cmdSubmit, printHelp,
   scaffoldModule, gatherUpgrade, evaluateUpgrade, buildManifest,
+  formatMaintenanceHint, isPastRemoveAfter,
   checkModulePublishability, recordSignOff, readSignOff, DCO_STATEMENT,
   listModuleFiles, packageModuleForSubmission,
   routeTemplate, claudeMdTemplate, titleize, camel, coreVersion,

package/scripts/gds/upgrade.js

@@ -141,18 +141,59 @@ function vendorTarball({ instanceDir, fromTgz, targetVersion }, fsImpl = fs) {
 
 // Lightweight module-compat pre-check reusing module.js against the TARGET core version. Best-effort:
 // a vanilla consumer has no modules/ (trivially OK); any failure downgrades to a warning, never blocks
-// the MVP bump. Returns { ok, blocking:[], note }.
+// the MVP bump. Returns { ok, blocking:[], warnings:[], deprecations:[], expired:[], note }.
+//
+// WARNINGS ARE NOT OPTIONAL OUTPUT (ADR 0166 / task 1001773). This function used to return only
+// `blocking`, so a DISABLED module whose coreVersion the target no longer satisfies vanished from the
+// bump entirely. That is precisely the catalog-rot case ADR 0107 §7 names: an accepted catalog module
+// ships `default: false` (§6), so EVERY rotted catalog entry is disabled by construction and every one
+// of them was invisible here. The bump still doesn't BLOCK on them — a disabled module breaks nothing
+// at boot — but it must SAY so, with the maintainer named, or the incompatibility is discovered by
+// whoever next tries to enable it.
 function preflightModules({ instanceDir, targetVersion }, deps = {}) {
+  const empty = { blocking: [], warnings: [], deprecations: [], expired: [] };
   const modulesDir = path.join(instanceDir, 'modules');
-  if (!fs.existsSync(modulesDir)) return { ok: true, blocking: [], note: 'no modules/ — nothing to pre-check' };
+  if (!fs.existsSync(modulesDir)) return { ok: true, ...empty, note: 'no modules/ — nothing to pre-check' };
   try {
     const mod = deps.moduleLib || require('./module');
     const data = mod.gatherUpgrade({ modulesDir, core: targetVersion });
     const verdict = mod.evaluateUpgrade(data);
-    return { ok: verdict.ok, blocking: verdict.blocking || [], note: verdict.ok ? 'all enabled modules satisfy the target' : 'incompatible enabled module(s)' };
+    const rotted = (verdict.warnings || []).length;
+    const note = !verdict.ok
+      ? 'incompatible enabled module(s)'
+      : rotted
+        ? `all enabled modules satisfy the target, but ${rotted} disabled module(s) do NOT`
+        : 'all enabled modules satisfy the target';
+    return {
+      ok: verdict.ok,
+      blocking: verdict.blocking || [],
+      warnings: verdict.warnings || [],
+      deprecations: verdict.deprecations || [],
+      expired: verdict.expired || [],
+      note,
+    };
   } catch (e) {
-    return { ok: true, blocking: [], note: `module pre-check skipped (${e.message})` };
+    return { ok: true, ...empty, note: `module pre-check skipped (${e.message})` };
+  }
+}
+
+// Print the non-blocking half of the module pre-check: rotted-but-disabled modules and
+// self-declared deprecations, each with its maintenance hint so the reader knows who to chase.
+// Split out of runUpgrade so it is testable without driving a whole bump.
+function reportModulePreflight(mods, targetVersion, { log = console.log, err = console.error, hint } = {}) {
+  const fmt = hint || ((row) => { try { return require('./module').formatMaintenanceHint(row); } catch { return ''; } });
+  const lines = [];
+  for (const w of mods.warnings || []) {
+    lines.push(`  ! module "${w.key}" is DISABLED here, so it does not block this bump — but its coreVersion ${w.coreVersion || '(none)'} is not satisfied by core ${targetVersion}: enabling it would silently fail to mount.`);
+    lines.push(`      ↳ ${fmt(w)}`);
+  }
+  for (const d of mods.deprecations || []) {
+    const overdue = (mods.expired || []).includes(d);
+    lines.push(`  ! module "${d.key}" is ${d.maintenance.status}${overdue ? ` and PAST its removeAfter ${d.maintenance.removeAfter} (core ${targetVersion}) — it is due for removal` : ''}.`);
+    lines.push(`      ↳ ${fmt(d)}`);
   }
+  for (const l of lines) err(l);
+  return lines;
 }
 
 function npmInstall(instanceDir, run = spawnSync) {
@@ -582,6 +623,10 @@ async function runUpgrade(opts, deps = {}) {
   }
   const mods = preflightModules({ instanceDir, targetVersion }, deps);
   log(`  ✓ pre-flight: ${mods.note}`);
+  // Surface the non-blocking findings (rotted-but-disabled + deprecated modules) BEFORE the
+  // blocking check returns, so they are reported on a refused bump too — a refusal is exactly
+  // when someone is reading this output (ADR 0166).
+  (deps.reportModulePreflight || reportModulePreflight)(mods, targetVersion, { log, err });
   if (!mods.ok) return { ok: false, error: `module pre-check failed: ${mods.blocking.map((b) => b.key).join(', ')} incompatible with core ${targetVersion}` };
 
   // 1b. mandatory post-restart health check (audit H9 / task 1002222, finding F5). A bump that
@@ -822,7 +867,7 @@ async function main(argv = process.argv.slice(2)) {
 module.exports = {
   runUpgrade, parseArgs, main, rollback,
   versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin, restorePin,
-  vendorTarball, gitTreeClean, preflightModules, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, pollHealth,
+  vendorTarball, gitTreeClean, preflightModules, reportModulePreflight, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, pollHealth,
   readManifest, resolveReferenceManifest, verifyInstalledPin, // task 1002216 (audit H8) — integrity-pin verification
   CORE_PKG, ARTIFACT,
 };

package/src/bongos/routes/modules.js

@@ -99,6 +99,10 @@ function listModules() {
       origin: manifest.origin || null,
       license: manifest.license || null,
       maintainer: manifest.maintainer || null,
+      // Upkeep posture (ADR 0107 §7 / ADR 0166) — the catalog's job is to show
+      // who keeps a module true as the core advances, so a deprecated or
+      // unowned entry reads as such instead of looking like any other module.
+      maintenance: manifest.maintenance || null,
     };
   }).sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
 }

package/src/module-api.js

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

package/src/module-loader/manifest-schema.js

@@ -18,6 +18,15 @@
 //     "origin":       "…",              // OPTIONAL. Origin instance/project this module was built in.
 //     "license":      "…",              // OPTIONAL. e.g. "AGPL-3.0" — the license this module is offered under.
 //     "maintainer":   "…",              // OPTIONAL. Who to credit/contact if this module is upstreamed.
+//     "maintenance": {                  // OPTIONAL. Upkeep posture (ADR 0107 §7 / ADR 0166) — who keeps
+//       "status": "maintained",         //   REQUIRED in-block: core-maintained | maintained | deprecated | orphaned.
+//       "since":  "1.8.0",              //   OPTIONAL. Core version the status took effect.
+//       "removeAfter": "1.12.0",        //   OPTIONAL. Core version after which it may be deleted.
+//       "successor":   "econ-v2",       //   OPTIONAL. Module key that replaces it.
+//       "note":        "…"              //   OPTIONAL. The deprecation path in one sentence.
+//     },                                //   this module true as the core advances, and what happens if
+//                                       //   nobody does. `maintained` needs a named `maintainer`;
+//                                       //   `deprecated`/`orphaned` need a `successor` or a `note`.
 //     "contributes": {                  // REQUIRED object (may be empty). What the module mounts:
 //       "routes":      ["box"],         //   route-factory keys (mounted behind kernel-composed auth)
 //       "rooms":       ["WorldRoom"],   //   Colyseus room classes (realtime seam)
@@ -40,7 +49,7 @@
 // validateManifest(obj) -> { valid, errors[], manifest } — pure, no I/O.
 // assertValidManifest(obj) throws on the first failure (loader convenience).
 
-const { isValidRange } = require('./semver');
+const { isValidRange, parseVersion } = require('./semver');
 
 const KEY_RE = /^[a-z][a-z0-9-]*$/;
 
@@ -54,6 +63,23 @@ const ALLOWED_CONTRIBUTES = [...ARRAY_OF_STRING_KEYS, 'webSurfaces', 'migrations
 // Top-level attribution fields (ADR 0107 §2) — optional, portable strings.
 const ATTRIBUTION_KEYS = ['author', 'origin', 'license', 'maintainer'];
 
+// The `maintenance` block (ADR 0107 §7, decided in ADR 0166). A module pinned to
+// an old coreVersion rots as the core advances, so every module states — in the
+// manifest, where the upgrade pre-check can read it — WHO keeps it true and what
+// happens if nobody does. The four statuses are the whole policy:
+//   core-maintained  the core team owns it; a core change that breaks it is the
+//                    core's problem to fix before shipping.
+//   maintained       a named `maintainer` owns it (required — an unnamed owner
+//                    IS the orphaning failure this field exists to prevent).
+//   deprecated       on the way out; needs a path (`successor` and/or `note`),
+//                    optionally a `removeAfter` core version.
+//   orphaned         nobody owns it. Still needs a `note`/`successor` so the
+//                    next reader knows the situation, not just the label.
+const MAINTENANCE_STATUSES = ['core-maintained', 'maintained', 'deprecated', 'orphaned'];
+const MAINTENANCE_KEYS = ['status', 'since', 'removeAfter', 'successor', 'note'];
+// Statuses that describe a module on its way out — these owe a deprecation path.
+const SUNSET_STATUSES = ['deprecated', 'orphaned'];
+
 const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
 const isStr = (v) => typeof v === 'string' && v.length > 0;
 const isStrArray = (v) => Array.isArray(v) && v.every(isStr);
@@ -93,6 +119,44 @@ function validateManifest(obj) {
     if (k in obj && !isStr(obj[k])) E(`${k}: must be a non-empty string when present`);
   }
 
+  // --- optional maintenance block (ADR 0107 §7 / ADR 0166) ---
+  // Closed key set (like contributes) so a typo'd "removeafter" fails loud rather
+  // than silently declaring no removal date at all.
+  if ('maintenance' in obj) {
+    const m = obj.maintenance;
+    if (!isObj(m)) {
+      E('maintenance: must be an object (e.g. { "status": "maintained" })');
+    } else {
+      for (const k of Object.keys(m)) {
+        if (!MAINTENANCE_KEYS.includes(k)) E(`maintenance.${k}: unknown key (allowed: ${MAINTENANCE_KEYS.join(', ')})`);
+      }
+      if (!isStr(m.status)) E(`maintenance.status: required — one of ${MAINTENANCE_STATUSES.join(', ')}`);
+      else if (!MAINTENANCE_STATUSES.includes(m.status)) {
+        E(`maintenance.status: "${m.status}" is not one of ${MAINTENANCE_STATUSES.join(', ')}`);
+      }
+      for (const k of ['since', 'removeAfter']) {
+        if (k in m && !parseVersion(m[k])) E(`maintenance.${k}: must be an exact core version "X.Y.Z" when present`);
+      }
+      if ('successor' in m && (!isStr(m.successor) || !KEY_RE.test(m.successor))) {
+        E('successor: must be a module key (lowercase kebab-case) when present');
+      }
+      if ('note' in m && !isStr(m.note)) E('maintenance.note: must be a non-empty string when present');
+
+      // The two rules that make the block load-bearing rather than decorative:
+      // a "maintained" module must NAME its maintainer, and a module on its way
+      // out must state the path out. Everything else above is shape-checking.
+      if (m.status === 'maintained' && !isStr(obj.maintainer)) {
+        E('maintenance.status "maintained" requires a named top-level `maintainer` (ADR 0166) — use "orphaned" if nobody owns it');
+      }
+      if (SUNSET_STATUSES.includes(m.status) && !isStr(m.successor) && !isStr(m.note)) {
+        E(`maintenance.status "${m.status}" requires a deprecation path — a "successor" module key and/or a "note" (ADR 0166)`);
+      }
+      if ('removeAfter' in m && !SUNSET_STATUSES.includes(m.status)) {
+        E(`maintenance.removeAfter only applies to a ${SUNSET_STATUSES.join('/')} module (status is "${m.status}")`);
+      }
+    }
+  }
+
   // --- contributes (required object) ---
   if (!isObj(obj.contributes)) {
     E('contributes: required object (use {} if the module contributes nothing)');
@@ -152,4 +216,7 @@ function assertValidManifest(obj, label = 'module.json') {
   return obj;
 }
 
-module.exports = { validateManifest, assertValidManifest, KEY_RE, ALLOWED_CONTRIBUTES, ARRAY_OF_STRING_KEYS, ATTRIBUTION_KEYS };
+module.exports = {
+  validateManifest, assertValidManifest, KEY_RE, ALLOWED_CONTRIBUTES, ARRAY_OF_STRING_KEYS, ATTRIBUTION_KEYS,
+  MAINTENANCE_STATUSES, MAINTENANCE_KEYS, SUNSET_STATUSES,
+};

package/tests/module_cli.mjs

@@ -418,3 +418,129 @@ test('`bongos module submit` is documented in help / dispatches to module.js sub
   assert.ok(lines.some((l) => /module submit/.test(l)));
   assert.equal(await mod.main(['node', 'module.js', 'submit']), 2, 'no key => usage error');
 });
+
+// ---------------------------------------------------------------------------
+// Maintenance & deprecation policy (ADR 0107 §7 / ADR 0166, task 1001773)
+// ---------------------------------------------------------------------------
+
+test('evaluateUpgrade: sorts self-declared deprecations, and flags the ones the core has passed removeAfter', () => {
+  const v = mod.evaluateUpgrade({
+    core: '1.13.0',
+    rows: [
+      { key: 'healthy', coreVersion: '^1.0.0', enabled: true, satisfied: true, maintenance: { status: 'core-maintained' } },
+      { key: 'sunset', coreVersion: '^1.0.0', enabled: false, satisfied: true, maintenance: { status: 'deprecated', successor: 'newer', removeAfter: '1.12.0' } },
+      { key: 'sunset-later', coreVersion: '^1.0.0', enabled: false, satisfied: true, maintenance: { status: 'deprecated', note: 'going', removeAfter: '1.20.0' } },
+      { key: 'nobody', coreVersion: '^1.0.0', enabled: false, satisfied: true, maintenance: { status: 'orphaned', note: 'unowned' } },
+    ],
+  });
+  assert.equal(v.ok, true, 'a deprecation is not a compatibility failure — it must not block a bump');
+  assert.deepEqual(v.deprecations.map((d) => d.key), ['sunset', 'sunset-later', 'nobody']);
+  assert.deepEqual(v.expired.map((d) => d.key), ['sunset'], 'core 1.13.0 is past removeAfter 1.12.0 but not 1.20.0');
+  assert.deepEqual(v.undeclared, []);
+});
+
+test('evaluateUpgrade: a module with no maintenance block is reported as undeclared (nobody is on the hook)', () => {
+  const v = mod.evaluateUpgrade({
+    core: '1.0.0',
+    rows: [
+      { key: 'owned', coreVersion: '^1.0.0', enabled: true, satisfied: true, maintenance: { status: 'core-maintained' } },
+      { key: 'orphan-risk', coreVersion: '^1.0.0', enabled: false, satisfied: true },
+    ],
+  });
+  assert.deepEqual(v.undeclared.map((r) => r.key), ['orphan-risk']);
+  assert.equal(v.ok, true, 'an undeclared posture is a reporting gap, not a compatibility failure');
+});
+
+test('formatMaintenanceHint: names the owner, or says plainly that there is none', () => {
+  assert.match(mod.formatMaintenanceHint({ key: 'x' }), /no maintenance declared/);
+  assert.match(
+    mod.formatMaintenanceHint({ key: 'x', maintainer: 'Ada <ada@example.com>', maintenance: { status: 'maintained' } }),
+    /maintainer Ada <ada@example\.com>/,
+  );
+  assert.match(mod.formatMaintenanceHint({ key: 'x', maintenance: { status: 'maintained' } }), /unnamed!/);
+  const sunset = mod.formatMaintenanceHint({ key: 'x', maintenance: { status: 'deprecated', successor: 'y', removeAfter: '1.12.0', note: 'use y' } });
+  assert.match(sunset, /superseded by "y"/);
+  assert.match(sunset, /removable after core 1\.12\.0/);
+});
+
+test('gatherUpgrade: carries each module\'s maintenance posture onto its row', () => {
+  loader._reset();
+  const root = tmpModulesRoot();
+  mod.scaffoldModule({ key: 'econ', modulesDir: root, core: '1.0.0' });
+  const data = mod.gatherUpgrade({ modulesDir: root, core: '1.0.0', env: {}, neutral: {}, instance: {}, prefix: 'CLOUDBONGOS' });
+  const row = data.rows.find((r) => r.key === 'econ');
+  assert.equal(row.maintenance.status, 'maintained', 'the scaffolder stamps an honest default');
+  assert.ok(row.maintainer, 'the maintainer travels with the row so the hint can name them');
+  loader._reset();
+});
+
+test('cmdUpgrade: a DISABLED incompatible module is reported with its owner, not silently dropped', () => {
+  // The catalog-rot case: an accepted module ships default:false (ADR 0107 §6), so
+  // every rotted catalog entry is disabled by construction. Exit stays 0 — it breaks
+  // nothing at boot — but it must be visible and attributed.
+  const lines = [];
+  const sink = { log: (s) => lines.push(String(s)), errlog: (s) => lines.push(String(s)) };
+  const code = mod.cmdUpgrade([], {
+    ...sink,
+    gather: () => ({
+      core: '2.0.0',
+      errors: [],
+      rows: [{
+        key: 'stale-catalog-entry', coreVersion: '^1.0.0', enabled: false, satisfied: false,
+        maintainer: 'Ada <ada@example.com>', maintenance: { status: 'maintained' },
+      }],
+    }),
+  });
+  assert.equal(code, 0, 'a disabled mismatch must not block');
+  const out = lines.join('\n');
+  assert.match(out, /stale-catalog-entry/);
+  assert.match(out, /BROKEN if enabled/);
+  assert.match(out, /maintainer Ada <ada@example\.com>/, 'the owner is named so someone can be told');
+});
+
+test('cmdUpgrade: reports an expired deprecation and modules with no declared upkeep', () => {
+  const lines = [];
+  const sink = { log: (s) => lines.push(String(s)), errlog: (s) => lines.push(String(s)) };
+  const code = mod.cmdUpgrade([], {
+    ...sink,
+    gather: () => ({
+      core: '1.13.0',
+      errors: [],
+      rows: [
+        { key: 'sunset', coreVersion: '^1.0.0', enabled: false, satisfied: true, maintenance: { status: 'deprecated', successor: 'newer', removeAfter: '1.12.0' } },
+        { key: 'unowned', coreVersion: '^1.0.0', enabled: false, satisfied: true },
+      ],
+    }),
+  });
+  assert.equal(code, 0);
+  const out = lines.join('\n');
+  assert.match(out, /sunset: deprecated/);
+  assert.match(out, /PAST removeAfter 1\.12\.0/);
+  assert.match(out, /declare no `maintenance` block/);
+  assert.match(out, /unowned/);
+});
+
+test('checkModulePublishability: refuses a module that declares no maintenance posture', () => {
+  const root = tmpModulesRoot();
+  const { dir } = mod.scaffoldModule({ key: 'unowned', modulesDir: root, core: '1.0.0' });
+  const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'module.json'), 'utf8'));
+  delete manifest.maintenance;
+  fs.writeFileSync(path.join(dir, 'module.json'), JSON.stringify(manifest, null, 2));
+  const r = mod.checkModulePublishability('unowned', { modulesDir: root });
+  assert.equal(r.ok, false, 'acceptance is a commitment to upkeep — it must be stated');
+  assert.ok(r.findings.some((f) => f.kind === 'maintenance' && /core-maintained/.test(f.detail)), JSON.stringify(r.findings));
+});
+
+test('checkModulePublishability: refuses a module that is ALREADY deprecated or orphaned', () => {
+  const root = tmpModulesRoot();
+  for (const status of ['deprecated', 'orphaned']) {
+    const key = `sunset-${status}`;
+    const { dir } = mod.scaffoldModule({ key, modulesDir: root, core: '1.0.0' });
+    const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'module.json'), 'utf8'));
+    manifest.maintenance = { status, note: 'on the way out' };
+    fs.writeFileSync(path.join(dir, 'module.json'), JSON.stringify(manifest, null, 2));
+    const r = mod.checkModulePublishability(key, { modulesDir: root });
+    assert.equal(r.ok, false, `${status} must not be submittable INTO the catalog`);
+    assert.ok(r.findings.some((f) => f.kind === 'maintenance' && /way out/.test(f.detail)));
+  }
+});