@bongos/core 1.19.541 → 1.19.542

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.541",
-  "core_contract": "1.19.541",
-  "source_commit": "0f2805ada935b696e72031342663a4193c5c802d",
+  "core_version": "1.19.542",
+  "core_contract": "1.19.542",
+  "source_commit": "ec461e927a5fe4bb98053989f04853aa378878ee",
   "source_ref": "HEAD",
-  "built_at": "2026-09-04T16:58:05.057Z",
+  "built_at": "2026-09-04T17:03:11.236Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 441,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2000,
+    "functional_verbatim": 2002,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2465,
-  "tree_sha256": "281153bdf107ee76f439badeb13dc3cbd70393ce4b70d52084e542a9581684f8",
+  "file_count": 2467,
+  "tree_sha256": "15eb33889177142913c49676b48a92f947cc04ace14b1cc1b0055e773f996645",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -2647,7 +2647,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "263a5d16f7cd22a3b6a193a4cff05994a8fcf7a0522b561ba802392c3328b4f2"
+      "sha256": "f5af0c300e59c22fcfeaafba88b00bd39f65afb2f51529efb0981a898aebb766"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5952,7 +5952,7 @@
     {
       "path": "modules/platform-identity/project-catalog.js",
       "mode": "0000644",
-      "sha256": "2f83a6c37f3cabb5ef04d20f0d6e92a39218528bad214a5e61e07eb3bba1468e"
+      "sha256": "6021d893691000a164d7d16e6f24b5bd91215c6dcb252557f0ffcd5d1d467e32"
     },
     {
       "path": "modules/platform-identity/project-stats.js",
@@ -6037,7 +6037,7 @@
     {
       "path": "modules/provisioning/catalog-bridge.js",
       "mode": "0000644",
-      "sha256": "35a3c70ebe49b37a18044d6756d97b9caea87917a9fdbe0198fa05be25f5457a"
+      "sha256": "dae214682f6115b3a4e11ac3bcd120460b07c2a517155ba0b7ec690f1db9f3ea"
     },
     {
       "path": "modules/provisioning/migrations/provisioning_001_tables.sql",
@@ -6112,13 +6112,18 @@
     {
       "path": "modules/provisioning/module.json",
       "mode": "0000644",
-      "sha256": "c451d94736219198d10d1bb8837ff9aecd6d4f90f8bf46790deba38f0d2168ec"
+      "sha256": "6c19e18cd65ed87e3af53835af179bbe0a937e38456056fe49711c8b31b3e081"
     },
     {
       "path": "modules/provisioning/onboard-plan.js",
       "mode": "0000644",
       "sha256": "31f14cbf3d649c25f1f17c508ae19be2f39d9e1991fde17cdce08cb15837ffa1"
     },
+    {
+      "path": "modules/provisioning/pollers/catalog-backfill.js",
+      "mode": "0000644",
+      "sha256": "bf4a392ce4c545feb246b818ad2b37dd5e92050538d5202fb8980941d0ec52c9"
+    },
     {
       "path": "modules/provisioning/pollers/liveness-sweep.js",
       "mode": "0000644",
@@ -6147,7 +6152,7 @@
     {
       "path": "modules/provisioning/routes/provisioning.js",
       "mode": "0000644",
-      "sha256": "00585a2de10a05c814fb0c1ad3cd6b564096b70b7729695b54953ab98c75601b"
+      "sha256": "c6cfd3a1d0b4f39c4d23d65e1587ec50276aa4180ab48c520b4c22fdb6cf0a6c"
     },
     {
       "path": "modules/provisioning/starter-bundles.js",
@@ -7407,12 +7412,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "d1edde947ae28592c6bb37d8a935cc2c2c9c9ca45c9064c1579c8128d313e5ae"
+      "sha256": "3292c34b3bdbd992383b7d539a5cc5e1734ac78aff6ca476db6d3e558a60db32"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "1f416b6226afeec3bb285d65c4d2bede292e7ad63c04a5701c54d7c59324c634"
+      "sha256": "0e83db7f6c2b6d6310d2f20810817be1e483f774d64def7852895c2f85eff047"
     },
     {
       "path": "public-docs/index.html",
@@ -9097,7 +9102,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "c9da65f8915d9cc8bb519797fb741a9644421066fbb97b29bb1d270fa874c1b4"
+      "sha256": "980c4fd7007ae4d60c95392644476ef440e9d0e0a1eaa3aa4f19f4f3bd5cb69c"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9587,7 +9592,7 @@
     {
       "path": "tests/catalog_only_client.mjs",
       "mode": "0000644",
-      "sha256": "2eb721978e016514ef53cf5083dbbc5d38a2db57cd75786fdd6b6a12e5488dff"
+      "sha256": "cf03bbcb60691dadd4f7c9f4faf4122df6dea099f9ce3137b514b416cab3a5e8"
     },
     {
       "path": "tests/category_advisory_guard.mjs",
@@ -11324,6 +11329,11 @@
       "mode": "0000644",
       "sha256": "6a7a223a678b56333befaed017429e5b9d8a81e4405efae72a23355902517d9d"
     },
+    {
+      "path": "tests/project_catalog_backfill.mjs",
+      "mode": "0000644",
+      "sha256": "079b8e54e94a6c1576a02735ee9ea9f27baaaa266115fa21eafa51ba7c17c565"
+    },
     {
       "path": "tests/project_catalog_bridge.mjs",
       "mode": "0000644",
@@ -11332,7 +11342,7 @@
     {
       "path": "tests/project_catalog_routes.mjs",
       "mode": "0000644",
-      "sha256": "afef4620252bc212b4326863abb021e8cd6033e258345e44cf78e97fc3b28b63"
+      "sha256": "e8f3b09a5c06aa1d760b7605d6c40ba7b818594286a1bd6bb9496f222b7fc8e8"
     },
     {
       "path": "tests/project_door_ui.mjs",

package/docs/module-api-changelog.md

@@ -1531,5 +1531,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.539 with no explicit bump. run 33895602533. (task 1002620)
   1.19.541 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.540 with no explicit bump. run 33897974683. (task 1002620)
+  1.19.542 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.541 with no explicit bump. run 33898437821. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/platform-identity/project-catalog.js

@@ -165,6 +165,29 @@ async function retireOwnedProject({ origin, ownerGithubId }, { pool = defaultPoo
   return rows[0] || null;
 }
 
+// WHICH of these origins does the map already carry? The one question a BACKFILL has to ask
+// and `publish` cannot answer (task 1003581). ADR 0246's projection is write-triggered, so an
+// instance that predates it has no row until its owner happens to save something — and the
+// only way to heal that is to re-project, which without this read would mean re-projecting
+// EVERY instance at every boot and churning every row's updated_at forever.
+//
+// Deliberately UNFILTERED by owner and by status: "is there a row at this origin" is the
+// question, so a hand-seeded row (owner NULL) or a hidden one counts as present and the
+// backfill leaves it exactly where it is. Origins in, origins out — the catalog still learns
+// no other module's schema, which is ADR 0246's reason for keeping the port narrow. PURE of
+// side effects; one indexed lookup however many origins are asked about.
+async function catalogedOrigins(origins, { pool = defaultPool } = {}) {
+  const list = [...new Set((Array.isArray(origins) ? origins : [origins])
+    .map((o) => String(o || '').replace(/\/+$/, ''))
+    .filter(Boolean))];
+  if (!list.length) return [];
+  const { rows } = await pool.query(
+    'SELECT origin FROM platform_identity_projects WHERE origin = ANY($1::text[])',
+    [list],
+  );
+  return rows.map((r) => r.origin);
+}
+
 // ONE control-plane project, projected into the catalog: the identity row first, then the map
 // row, then (on a re-point) the address it left. Both writes are claim-gated, so `claimed`
 // tells the caller whether the map actually carries this project — a false is a refusal, not
@@ -184,10 +207,13 @@ async function publishControlPlaneProject(entry, { retireOrigin = null, pool = d
 // module.json. The `project.publishGate` precedent, and for the same reason: provisioning is
 // the plane that OWNS these projects and may not import this module (the ADR 0083 one-way
 // rule), while this module owns the catalog's tables. One definition, reached through the
-// switchboard. `publish` is deliberately the only verb — a consumer maps its own row onto the
-// entry shape, so the catalog never learns another module's schema.
+// switchboard. `publish` writes; `catalogued` is the one READ a consumer needs — "which of
+// these origins are already on the map" — added by the backfill (task 1003581) because
+// healing history without it means re-writing every row at every boot. Both speak only in
+// origins and the entry shape, so the catalog still never learns another module's schema.
 const projectCatalogPort = Object.freeze({
   publish: (entry, opts) => publishControlPlaneProject(entry, opts),
+  catalogued: (origins) => catalogedOrigins(origins),
 });
 
 module.exports = {
@@ -197,6 +223,7 @@ module.exports = {
   upsertCatalogOnlyClient,
   upsertOwnedProject,
   retireOwnedProject,
+  catalogedOrigins,
   publishControlPlaneProject,
   projectCatalogPort,
 };

package/modules/provisioning/catalog-bridge.js

@@ -44,18 +44,31 @@ const CATALOG_HIDDEN_STATES = new Set(['tearing_down', 'torn_down']);
 // SAME row rather than orphaning it). The door comes from `effectiveSettings`, never the raw
 // jsonb, so an off-vocabulary stored value resolves to today's behaviour exactly as it does
 // on every other surface.
+// The two halves of the projection that do NOT need the owner, split out so a caller that only
+// wants the address can have it without a database read (task 1003581 — the backfill's presence
+// check runs on every owner manage-page load, and resolving an owner just to build a string was
+// a query per read forever). `catalogEntryForInstance` derives both from these, so there is
+// still exactly ONE definition of each. Both PURE.
+function catalogOriginForInstance(row) {
+  return row && row.slug && row.domain ? `https://${row.domain}` : null;
+}
+function catalogStatusForInstance(row) {
+  return CATALOG_HIDDEN_STATES.has(row && row.status) ? 'hidden' : 'active';
+}
+
 function catalogEntryForInstance(row, { ownerGithubId } = {}) {
-  if (!row || !row.slug || !row.domain) return null;
+  const origin = catalogOriginForInstance(row);
+  if (!origin) return null;
   const owner = Number(ownerGithubId);
   if (!Number.isFinite(owner) || owner <= 0) return null;
   return {
     clientId: row.slug,
-    origin: `https://${row.domain}`,
+    origin,
     name: row.slug,
     description: row.description || null,
     type: row.type || null,
     visibility: effectiveSettings(row).visibility,
-    status: CATALOG_HIDDEN_STATES.has(row.status) ? 'hidden' : 'active',
+    status: catalogStatusForInstance(row),
     ownerGithubId: owner,
   };
 }
@@ -98,8 +111,59 @@ async function publishInstanceToCatalog(db, row, { retireOrigin = null } = {}) {
   }
 }
 
+// The origin a BACKFILL would put this instance's catalog row at, or null when it should not
+// have one. PURE, and composed from the projection's own two halves rather than a second copy
+// of its rules: no address means nothing to key a row on, and 'hidden' means the row would
+// exist only to be invisible — writing that for a torn-down project that was NEVER catalogued
+// is churn, not repair. A project the owner is still standing up ('requested' / 'provisioning'
+// / 'error') IS backfillable — ADR 0246: the map is a directory of projects, not an uptime
+// board. Deliberately says nothing about the OWNER, so the presence check it feeds costs no
+// database read; a missing owner identity is `publishInstanceToCatalog`'s own refusal.
+function backfillOriginForInstance(row) {
+  const origin = catalogOriginForInstance(row);
+  return origin && catalogStatusForInstance(row) === 'active' ? origin : null;
+}
+
+// Project ONE instance ONLY IF the map does not already carry it (task 1003581).
+//
+// WHY IT EXISTS. ADR 0246 made the catalog row a projection re-taken at every write that can
+// change it — but a write-triggered projection has no opinion about HISTORY. Every instance
+// that existed before that ADR landed has no `platform_identity_projects` row and no
+// `platform_identity_sso_clients` row, so `POST /projects/invite` answers 404 `unknown_project`
+// and its owner cannot invite anyone into a project they own. This is the repair, and it is
+// deliberately conditional: re-projecting an instance that is already on the map would churn
+// its `updated_at` on every owner page-load and every boot.
+//
+// SAFE ON A ROW SOMEONE ELSE HOLDS. "Already catalogued" is asked of the ORIGIN alone, so a
+// hand-seeded row (owner NULL, unclaimable by ADR 0246's claim rule 2) counts as present and
+// is never written to. Best-effort like every other call site: it never throws, and it reports
+// why it did nothing.
+//
+// THE ALREADY-HEALED CASE COSTS ONE QUERY — the presence read, and nothing else. That is why
+// the order below is address → map → owner rather than owner first: this rides an owner's
+// manage-page read forever, long after the one boot that repaired the instance, so the steady
+// state has to be the cheap one. The owner lookup happens inside `publishInstanceToCatalog`,
+// i.e. only when there is actually a row to write.
+async function healInstanceCatalog(db, row) {
+  const catalog = api.resolveOptional('project.catalog');
+  if (!catalog || typeof catalog.catalogued !== 'function') return { healed: false, reason: 'no_catalog' };
+  const origin = backfillOriginForInstance(row);
+  if (!origin) return { healed: false, reason: 'not_backfillable' };
+  try {
+    const present = await catalog.catalogued([origin]);
+    if (present.includes(origin)) return { healed: false, reason: 'already_catalogued' };
+    const out = await publishInstanceToCatalog(db, row);
+    return { healed: !!out.published, reason: out.published ? null : out.reason };
+  } catch (err) {
+    log.error({ err: err.message, slug: row && row.slug }, 'catalog heal failed (non-fatal)');
+    return { healed: false, reason: 'error' };
+  }
+}
+
 module.exports = {
   CATALOG_HIDDEN_STATES,
   catalogEntryForInstance,
+  backfillOriginForInstance,
   publishInstanceToCatalog,
+  healInstanceCatalog,
 };

package/modules/provisioning/module.json

@@ -12,7 +12,7 @@
   "contributes": {
     "routes": ["provisioning"],
     "migrations": true,
-    "pollers": ["liveness-sweep"]
+    "pollers": ["liveness-sweep", "catalog-backfill"]
   },
   "provides": ["provisioning.instanceState", "provisioning.projectPlanets", "provisioning.projectOwnedBy"],
   "consumes": []

package/modules/provisioning/pollers/catalog-backfill.js

@@ -0,0 +1,134 @@
+'use strict';
+
+// modules/provisioning/pollers/catalog-backfill.js — THE ONE-SHOT REPAIR OF HISTORY behind
+// ADR 0246's catalog projection (task 1003581). The loader's startModulePollers requires this
+// file and calls start(deps) at boot for the ENABLED module only — the liveness-sweep shape.
+//
+// WHY. ADR 0246 made the hub catalog row a PROJECTION of the provisioning row, re-taken at
+// every write that can change it. A write-triggered projection is correct going forward and
+// says nothing about the past: every instance that existed before that ADR landed has no
+// catalog row and gets one only if its owner happens to edit its detail, its settings or its
+// address. Until then `POST /projects/invite` resolves nothing and answers 404
+// `unknown_project`, so **an owner cannot invite anyone into a project they own** — which is
+// what blocked the C6 / BV1.R30 proof on live. This sweep is how the fleet heals itself on the
+// next core upgrade, with nobody hand-running SQL.
+//
+// ONE-SHOT, NOT A CADENCE. Ongoing correctness is already the four write call sites' job, plus
+// the owner-read self-heal in routes/provisioning.js; a repeating sweep would find nothing on
+// every tick after the first. It runs once, a few seconds after boot, and stops.
+//
+// IT IS THE SAME REPAIR THE OWNER READ DOES, asked in one question instead of N. Both paths
+// share `backfillOriginForInstance` (what is projectable) and `publishInstanceToCatalog` (the
+// write, with ADR 0246's two claim rules inside its own statements), so they cannot drift; only
+// the shape of the presence question differs — the sweep hands the whole fleet's origins to
+// `catalogued` at once. In particular the hand-seeded catalog rows (owner_github_id NULL) come
+// back as PRESENT and are never written.
+//
+// SAFE TO RUN EVERY START: idempotent (an instance already on the map is skipped, not
+// re-written), bounded (SWEEP_LIMIT), logged through the module logger, and it never throws —
+// `healInstanceCatalog` swallows its own errors and the tick has its own catch, because a hub
+// hiccup must never take the boot.
+
+const api = require('../../../src/module-api');
+const provisioning = require('../provisioning');
+const bridge = require('../catalog-bridge');
+
+const log = api.logger('provisioning');
+
+// A few seconds after boot: late enough that the route mounts have registered the
+// `project.catalog` port, early enough that an owner opening their manage page finds the
+// repair already done.
+const FIRST_SWEEP_DELAY_MS = Number(process.env.PROVISIONING_CATALOG_BACKFILL_MS) || 15_000;
+// Runaway guard, not an expected limit — the whole point is that this is a finite backlog.
+const SWEEP_LIMIT = 500;
+// Keep the one-line account readable on a big fleet.
+const MAX_NAMES_SHOWN = 8;
+
+let timer = null;
+let started = false;
+
+// The per-sweep disposition line, PURE so its wording is unit-tested without a sweep:
+//   [catalog-backfill] 22 instances: 5 projected (mercury, lars-test) · 1 already · 16 skipped
+function formatSweepLine({ considered = 0, projected = 0, already = 0, skipped = 0, refused = 0, names = [] } = {}) {
+  const shown = names.slice(0, MAX_NAMES_SHOWN).join(', ');
+  const more = names.length > MAX_NAMES_SHOWN ? `, +${names.length - MAX_NAMES_SHOWN} more` : '';
+  const detail = names.length ? ` (${shown}${more})` : '';
+  const refusedPart = refused ? ` · ${refused} refused` : '';
+  return `[catalog-backfill] ${considered} instances: ${projected} projected${detail}`
+    + ` · ${already} already · ${skipped} skipped${refusedPart}`;
+}
+
+// ONE pass over the fleet, projecting every instance the map does not already carry.
+// Exported + dependency-injected (pool, log) so the tests drive it directly — the timer is
+// only a schedule.
+//
+// THE PRESENCE QUESTION IS ASKED ONCE, for the whole fleet. Calling the per-instance heal in a
+// loop would be a round trip per row — the N+1 shape — where `catalogued` was built to take a
+// list. It shares the heal path's rules rather than its composition: `backfillOriginForInstance`
+// decides what is projectable and `publishInstanceToCatalog` does the write, so the two paths
+// cannot disagree about either. What remains per-row is one primary-key owner lookup inside the
+// write, and only for a row actually being repaired — once in that instance's lifetime.
+async function sweepOnce(deps = {}) {
+  const db = deps.pool || api.pool;
+  const emit = deps.log || ((line) => log.info(line));
+  // No hub, no map to be on — the `publishVerdict` precedent. Nothing to say, nothing to do.
+  const catalog = api.resolveOptional('project.catalog');
+  if (!catalog || typeof catalog.catalogued !== 'function') return { considered: 0, skipped: 0, reason: 'no_catalog' };
+
+  const rows = (await provisioning.listAllInstances(db)).slice(0, SWEEP_LIMIT);
+  const candidates = rows
+    .map((row) => ({ row, origin: bridge.backfillOriginForInstance(row) }))
+    .filter((c) => c.origin);
+  const out = {
+    considered: rows.length, projected: 0, already: 0,
+    skipped: rows.length - candidates.length, refused: 0, names: [],
+  };
+  if (!candidates.length) return out;
+
+  let present;
+  try {
+    present = new Set(await catalog.catalogued(candidates.map((c) => c.origin)));
+  } catch (err) {
+    log.error({ err: err && err.message ? err.message : String(err) }, 'catalog backfill: the map could not be read');
+    return { ...out, reason: 'error' };
+  }
+
+  for (const { row, origin } of candidates) {
+    if (present.has(origin)) { out.already++; continue; }
+    const result = await bridge.publishInstanceToCatalog(db, row);
+    if (result.published) { out.projected++; out.names.push(row.slug); }
+    else if (result.reason === 'origin_held' || result.reason === 'error') out.refused++;
+    else out.skipped++;
+  }
+  // A fleet with nothing to repair says nothing — a control plane that has already healed
+  // should not print an empty account at every restart.
+  if (out.projected || out.refused) emit(formatSweepLine(out));
+  return out;
+}
+
+// Arm the one-shot sweep. Idempotent (a second call is a no-op) and kill-switched by
+// PROVISIONING_CATALOG_BACKFILL_DISABLED=1. The timer is unref'd so it never holds the
+// process open, and the tick's own catch means a failure is a log line, never a dead boot.
+function start(deps = {}) {
+  if (process.env.PROVISIONING_CATALOG_BACKFILL_DISABLED === '1') return;
+  if (started) return;
+  started = true;
+  timer = setTimeout(() => {
+    sweepOnce(deps).catch((e) => log.error({ err: e && e.message ? e.message : String(e) }, 'catalog backfill sweep crashed'));
+  }, FIRST_SWEEP_DELAY_MS);
+  if (timer.unref) timer.unref();
+}
+
+function stop() {
+  started = false;
+  if (timer) { clearTimeout(timer); timer = null; }
+}
+
+module.exports = {
+  start,
+  stop,
+  // exported for tests
+  sweepOnce,
+  formatSweepLine,
+  SWEEP_LIMIT,
+};

package/modules/provisioning/routes/provisioning.js

@@ -14,6 +14,8 @@
 //     POST   /provisioning/instances               — request a new instance
 //     GET    /provisioning/instances               — list the caller's instances
 //     GET    /provisioning/instances/:id           — read one of the caller's instances
+//                                                     (also SELF-HEALS its catalog projection,
+//                                                      task 1003581 — see the handler)
 //     POST   /provisioning/instances/:id/teardown  — request teardown of one's own
 //   Archon-scoped (requireRank('archon') — the fleet, the /boxes precedent):
 //     GET    /provisioning/fleet                    — the full instance roster
@@ -653,6 +655,14 @@ module.exports = function provisioningRoutes() {
       if (instanceAccessDenied(inst, req.builder)) {
         return res.fail('instance_not_found', 404);
       }
+      // SELF-HEAL THE CATALOG PROJECTION (task 1003581). ADR 0246's projection is
+      // write-triggered, so an instance older than it has no catalog row and its owner's
+      // invites 404 until they happen to save something. This own-scoped read — the manage
+      // page, past the access gate above — is the moment to close that. Conditional and
+      // best-effort: an instance already on the map costs ONE presence read and no write,
+      // which is the steady state this rides in forever, and it never throws, so it can
+      // never turn a read into a failure.
+      await catalogBridge.healInstanceCatalog(pool, inst).catch(() => {});
       const open = await provisioning.getOpenIntent(pool, id);
       // The GitHub-App leg's truth rides the same read (task 1003235), so the done
       // panel recovers it from server state after a reload — not from sessionStorage.

package/package-lock.json

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

package/package.json

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

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

@@ -227,10 +227,14 @@ test('mounting the projects routes registers the `project.catalog` port', async
   assert.ok(Object.isFrozen(catalog.projectCatalogPort), 'a consumer must not be able to re-point the port');
 });
 
-test('the port declares the catalog write and nothing else', () => {
-  // One verb. A consumer maps its own row onto the entry shape, so the catalog never learns
-  // another module’s schema and no module gets a general-purpose handle on these tables.
-  assert.deepEqual(Object.keys(catalog.projectCatalogPort), ['publish']);
+test('the port declares the catalog write, one presence read, and nothing else', () => {
+  // Two verbs, and the reason for the ceiling is unchanged: a consumer maps its own row onto
+  // the entry shape and asks about ORIGINS, so the catalog never learns another module's
+  // schema and no module gets a general-purpose handle on these tables. `catalogued` arrived
+  // with the backfill (task 1003581) because healing history without a presence read means
+  // re-writing every catalog row at every boot. Anything wider than these two is a new
+  // decision, and this list is where it has to be made.
+  assert.deepEqual(Object.keys(catalog.projectCatalogPort).sort(), ['catalogued', 'publish']);
 });
 
 test('the module manifest DECLARES the port it registers', async () => {

package/tests/project_catalog_backfill.mjs

@@ -0,0 +1,402 @@
+// tests/project_catalog_backfill.mjs — THE REPAIR OF HISTORY behind ADR 0246 (task 1003581).
+//
+// The bug: ADR 0246's catalog projection is WRITE-TRIGGERED. Its four call sites are all
+// provisioning writes (create, the detail answers, the settings door, a re-pointed address),
+// so every instance that existed BEFORE that ADR landed has no catalog row and gets one only
+// if its owner happens to save something. Until then `POST /projects/invite` resolves nothing
+// and answers 404 `unknown_project` — an owner cannot invite anyone into a project they own,
+// which is what halted the C6 / BV1.R30 proof on live.
+//
+// What this file pins:
+//   1. THE REPAIR — an instance the map does not carry is projected, through the SAME
+//      projection the write paths use.
+//   2. IT IS IDEMPOTENT. An instance already on the map is skipped, not re-written: a heal
+//      that wrote unconditionally would churn every row's updated_at at every boot and on
+//      every owner page-load, which is the reason the port grew a READ at all.
+//   3. IT REFUSES THE SAME THINGS THE PROJECTION REFUSES — no address, no owner identity, and
+//      a reclaimed instance whose row would exist only to be hidden.
+//   4. THE HAND-SEEDED ROWS STAY UNCLAIMABLE (ADR 0246's two claim rules). An origin the map
+//      already holds is never written, whoever owns it — and if it somehow were, the upsert's
+//      own ON CONFLICT … WHERE refuses.
+//   5. A STEALTH PROJECT REACHES THE MAP ANONYMOUSLY. The backfill puts rows on the map that
+//      were never there, so D2a has to hold for what it adds.
+//
+// DB-free: a recording fake hub standing in for the `project.catalog` port, a recording fake
+// pool for the owner lookup, the real bridge/poller/catalog for everything else.
+//
+// Run:  node --test --test-reporter=tap tests/project_catalog_backfill.mjs
+
+import assert from 'node:assert/strict';
+import { test, beforeEach } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const api = require('../src/module-api.js');
+const bridge = require('../modules/provisioning/catalog-bridge.js');
+const backfill = require('../modules/provisioning/pollers/catalog-backfill.js');
+const provisioning = require('../modules/provisioning/provisioning.js');
+const catalog = require('../modules/platform-identity/project-catalog.js');
+const feed = require('../modules/platform-identity/projects-feed.js');
+
+// A live standalone instance from before ADR 0246: fully projectable, and on the map only if
+// something puts it there. Instance 18's shape — the one whose owner could not invite anyone.
+const STANDALONE = Object.freeze({
+  id: 18, slug: 'spike-harbor', domain: 'spike-harbor.cloudbongos.test',
+  hosting_shape: 'standalone', status: 'active', owner_builder_id: 42,
+  description: 'A harbour for spikes.', type: 'research',
+  settings: { visibility: 'public' },
+});
+const ORIGIN = 'https://spike-harbor.cloudbongos.test';
+
+// The owner lookup the projection makes, and nothing else. Records every statement so a test
+// can assert what the repair did — and did not — ask the database.
+function fakePool(githubIdByBuilder = { 42: 9001 }) {
+  const calls = [];
+  return {
+    calls,
+    query: async (text, params = []) => {
+      calls.push({ text: String(text), params });
+      if (/FROM builders/i.test(String(text))) {
+        const gid = githubIdByBuilder[String(params[0])];
+        return { rows: gid ? [{ github_id: gid }] : [] };
+      }
+      return { rows: [] };
+    },
+  };
+}
+
+// A recording fake pool with queued responses, for asserting a statement's SHAPE.
+function mockPool(responses = []) {
+  const calls = [];
+  let i = 0;
+  return {
+    calls,
+    query: async (text, params) => {
+      calls.push({ text: String(text), params: params || [] });
+      return responses[i++] || { rows: [], rowCount: 0 };
+    },
+  };
+}
+
+// The fake hub: `origins` is what the map already carries. Registered from INSIDE the first
+// test rather than at import, because the port registry is process-global and single-provider
+// — the "no hub at all" case can only be observed before anything registers one.
+const hub = { origins: new Set(), publishes: [], reads: [], claimed: true, throws: false };
+
+function registerHub() {
+  api.registerProvider('project.catalog', {
+    publish: async (entry, opts) => {
+      if (hub.throws) throw new Error('hub unreachable');
+      hub.publishes.push({ entry, opts });
+      if (hub.claimed) hub.origins.add(entry.origin);
+      return { claimed: hub.claimed };
+    },
+    catalogued: async (origins) => {
+      hub.reads.push(origins);
+      return origins.filter((o) => hub.origins.has(o));
+    },
+  });
+}
+
+// ── 0. the seam, FIRST, for the reason above ──────────────────────────────────────────────
+
+test('with NO catalog provider the repair is an honest no-op, on both paths', async () => {
+  // platform-identity is hub-only (`default: false`). An instance running provisioning
+  // without it has no map to be repaired onto, and the honest answer is a reason, never an
+  // error — the `publishVerdict` precedent.
+  assert.equal(api.hasProvider('project.catalog'), false, 'nothing has registered one yet');
+  assert.deepEqual(await bridge.healInstanceCatalog(fakePool(), STANDALONE),
+    { healed: false, reason: 'no_catalog' });
+
+  // And the boot sweep does not even list the fleet: a vanilla control plane pays nothing
+  // for a repair that has no destination.
+  const pool = fakePool();
+  const out = await backfill.sweepOnce({ pool });
+  assert.equal(out.reason, 'no_catalog');
+  assert.equal(out.considered, 0);
+  assert.equal(pool.calls.length, 0);
+
+  registerHub(); // every test below runs against the hub
+});
+
+beforeEach(() => {
+  hub.origins = new Set();
+  hub.publishes = [];
+  hub.reads = [];
+  hub.claimed = true;
+  hub.throws = false;
+});
+
+// ── 1. the repair, and 2. its idempotence ─────────────────────────────────────────────────
+
+test('an instance the map does not carry is PROJECTED — the pre-ADR-0246 instance heals', async () => {
+  // Arrange — the map is empty, exactly as it was for every instance older than the ADR.
+  const pool = fakePool();
+
+  // Act
+  const out = await bridge.healInstanceCatalog(pool, STANDALONE);
+
+  // Assert — one publish, carrying the SAME projection the four write call sites hand over:
+  // slug as both name and client_id, the owner's github id for attribution.
+  assert.equal(out.healed, true);
+  assert.equal(hub.publishes.length, 1);
+  assert.equal(hub.publishes[0].entry.origin, ORIGIN);
+  assert.equal(hub.publishes[0].entry.clientId, 'spike-harbor');
+  assert.equal(hub.publishes[0].entry.ownerGithubId, 9001);
+  assert.equal(hub.publishes[0].entry.status, 'active');
+});
+
+test('a SECOND heal writes NOTHING — the repair is idempotent, not a re-write', async () => {
+  // The property that lets this run on every owner page-load and at every boot. Without it
+  // the heal would churn every catalog row's updated_at forever.
+  const pool = fakePool();
+  await bridge.healInstanceCatalog(pool, STANDALONE);
+  assert.equal(hub.publishes.length, 1);
+
+  const second = await bridge.healInstanceCatalog(pool, STANDALONE);
+  assert.deepEqual(second.reason, 'already_catalogued');
+  assert.equal(second.healed, false);
+  assert.equal(hub.publishes.length, 1, 'the map was asked, and nothing was written');
+  assert.deepEqual(hub.reads.at(-1), [ORIGIN]);
+});
+
+test('the ALREADY-HEALED case costs one presence read and NO owner lookup', async () => {
+  // This is the steady state: every owner manage-page load, forever, long after the one boot
+  // that repaired the instance. Resolving the owner just to build an origin string would be a
+  // second query per read for the rest of the instance's life, so the order is address → map
+  // → owner, and the owner lookup lives inside the write.
+  hub.origins = new Set([ORIGIN]);
+  const pool = fakePool();
+  const out = await bridge.healInstanceCatalog(pool, STANDALONE);
+  assert.equal(out.reason, 'already_catalogued');
+  assert.equal(hub.reads.length, 1);
+  assert.deepEqual(pool.calls, [], 'the builders table is not touched to answer "is it there"');
+});
+
+test('a hub whose port predates the presence read is a no-op, not a crash', async () => {
+  // The port is versioned only by its shape. An older platform-identity registers `publish`
+  // alone, and the heal must notice rather than call undefined — the same fail-closed reading
+  // `resolveOptional` gets when there is no hub at all.
+  const saved = api.resolveOptional('project.catalog').catalogued;
+  const port = api.resolveOptional('project.catalog');
+  delete port.catalogued;
+  try {
+    assert.deepEqual(await bridge.healInstanceCatalog(fakePool(), STANDALONE),
+      { healed: false, reason: 'no_catalog' });
+    assert.equal((await backfill.sweepOnce({ pool: fakePool() })).reason, 'no_catalog');
+    assert.equal(hub.publishes.length, 0);
+  } finally {
+    port.catalogued = saved;
+  }
+});
+
+test('a claim the hub REFUSES is reported, not pretended', async () => {
+  // ADR 0246 claim rule 2: an origin someone else's row already holds is refused. The heal
+  // must carry that through rather than answering "healed".
+  hub.claimed = false;
+  const out = await bridge.healInstanceCatalog(fakePool(), STANDALONE);
+  assert.equal(out.healed, false);
+  assert.equal(out.reason, 'origin_held');
+});
+
+test('a hub that throws is SWALLOWED — a repair may never break the read it rides on', async () => {
+  hub.throws = true;
+  const out = await bridge.healInstanceCatalog(fakePool(), STANDALONE);
+  assert.equal(out.healed, false);
+  assert.equal(out.reason, 'error');
+});
+
+// ── 3. the refusals — the same ones the projection already makes ──────────────────────────
+
+test('a RECLAIMED instance is never backfilled — a hidden row is churn, not repair', async () => {
+  // The projection maps tearing_down/torn_down → 'hidden'. Creating a row for a project that
+  // was never on the map, purely so it can be invisible, repairs nothing.
+  for (const status of ['tearing_down', 'torn_down']) {
+    const out = await bridge.healInstanceCatalog(fakePool(), { ...STANDALONE, status });
+    assert.equal(out.reason, 'not_backfillable', `${status} must not be backfilled`);
+  }
+  assert.equal(hub.publishes.length, 0);
+  assert.equal(hub.reads.length, 0, 'the hub is not even asked about a row we would not write');
+});
+
+test('an instance still standing up IS backfilled — the map is a directory, not an uptime board', async () => {
+  // ADR 0246: 'requested', 'provisioning' and 'error' are all "the owner is standing this up".
+  // Live instance 20 `walk-lantern` sits at 'error' with a domain and an owner, and its owner
+  // is as unable to invite anyone as instance 18's was.
+  for (const status of ['requested', 'provisioning', 'error']) {
+    hub.origins = new Set();
+    const out = await bridge.healInstanceCatalog(fakePool(), { ...STANDALONE, status });
+    assert.equal(out.healed, true, `${status} is a project that exists`);
+  }
+});
+
+test('an instance with NO ADDRESS asks the hub nothing at all', async () => {
+  // The catalog is keyed on origin, so there is nothing to ask about. Answered from the row
+  // alone — no round trip is spent discovering what the projection already knows.
+  const pool = fakePool();
+  const out = await bridge.healInstanceCatalog(pool, { ...STANDALONE, domain: null });
+  assert.equal(out.reason, 'not_backfillable');
+  assert.equal(hub.reads.length, 0);
+  assert.equal(pool.calls.length, 0);
+});
+
+test('an owner with no github identity is refused by the WRITE, not written un-refreshable', async () => {
+  // The hub's claim rule compares owners, so a row stamped with a null owner could never be
+  // refreshed. It is `publishInstanceToCatalog`'s own refusal — which is also why the owner is
+  // looked up there and not before the presence check.
+  const out = await bridge.healInstanceCatalog(fakePool({}), STANDALONE);
+  assert.equal(out.healed, false);
+  assert.equal(out.reason, 'no_owner_identity');
+  assert.equal(hub.publishes.length, 0);
+});
+
+// ── 4. the hand-seeded rows stay exactly where they are ───────────────────────────────────
+
+test('an origin the map ALREADY holds is left alone, whoever owns it', async () => {
+  // The three hand-seeded catalog rows carry owner_github_id NULL and no provisioning row.
+  // "Is there a row at this origin" is deliberately not an ownership question, so a backfill
+  // that happened to meet one skips it instead of trying — and ADR 0246's consequence that
+  // those rows are an owner data decision, never a code change, survives this task.
+  hub.origins = new Set([ORIGIN]);
+  const out = await bridge.healInstanceCatalog(fakePool(), STANDALONE);
+  assert.equal(out.reason, 'already_catalogued');
+  assert.equal(hub.publishes.length, 0);
+});
+
+test('the presence read filters on ORIGIN alone — never on owner, never on status', async () => {
+  // If it filtered on owner, a hand-seeded row (owner NULL) would read as ABSENT and the
+  // backfill would try to claim it at every boot. If it filtered on status, a hidden row
+  // would too. Both are the same mistake, and this is where it would be made.
+  const pool = mockPool([{ rows: [{ origin: ORIGIN }] }]);
+  const out = await catalog.catalogedOrigins([ORIGIN, `${ORIGIN}/`], { pool });
+  assert.deepEqual(out, [ORIGIN]);
+  const { text, params } = pool.calls[0];
+  assert.match(text, /WHERE origin = ANY\(\$1::text\[\]\)/);
+  assert.doesNotMatch(text, /owner_github_id/);
+  assert.doesNotMatch(text, /\bstatus\b/);
+  assert.deepEqual(params, [[ORIGIN]], 'a trailing slash is the same origin, asked once');
+});
+
+test('an empty ask issues no statement', async () => {
+  const pool = mockPool();
+  assert.deepEqual(await catalog.catalogedOrigins([], { pool }), []);
+  assert.equal(pool.calls.length, 0);
+});
+
+test('the backfill writes through the SAME claim-gated upsert — a NULL owner can never match', async () => {
+  // The belt behind the read: even if the map answered "absent" for a row it holds, the
+  // upsert's own ON CONFLICT … WHERE is what refuses. `NULL = anything` is NULL, i.e. not
+  // true, so a hand-seeded row cannot be claimed by an instance at its address.
+  const pool = mockPool([{ rows: [] }]);
+  const out = await catalog.upsertOwnedProject({
+    clientId: 'spike-harbor', origin: ORIGIN, name: 'spike-harbor',
+    description: 'A harbour for spikes.', visibility: 'public', status: 'active', ownerGithubId: 9001,
+  }, { pool });
+  assert.match(pool.calls[0].text,
+    /WHERE\s+platform_identity_projects\.owner_github_id\s*=\s*EXCLUDED\.owner_github_id/);
+  assert.equal(out, null, 'a refused claim answers null, not a row');
+});
+
+// ── 5. the boot sweep ─────────────────────────────────────────────────────────────────────
+
+// The live fleet's shape in miniature: one repairable, one already on the map, one reclaimed,
+// one with no address, one whose owner has no github identity.
+const FLEET = Object.freeze([
+  { ...STANDALONE },
+  { ...STANDALONE, id: 31, slug: 'mercury', domain: 'mercury.cloudbongos.test' },
+  { ...STANDALONE, id: 34, slug: 'testing', domain: 'testing.cloudbongos.test', status: 'torn_down' },
+  { ...STANDALONE, id: 13, slug: 'charter', domain: null },
+  { ...STANDALONE, id: 9, slug: 'test2', domain: 'test2.cloudbongos.test', owner_builder_id: 77 },
+]);
+
+provisioning.listAllInstances = async () => FLEET.map((r) => ({ ...r }));
+
+test('the boot sweep projects exactly the instances the map does not carry', async () => {
+  // Arrange — mercury is already on the map, as instance 18 became on live the moment a
+  // sibling task wrote its detail.
+  hub.origins = new Set(['https://mercury.cloudbongos.test']);
+
+  // Act
+  const out = await backfill.sweepOnce({ pool: fakePool(), log: () => {} });
+
+  // Assert
+  assert.equal(out.considered, 5);
+  assert.equal(out.projected, 1, 'only spike-harbor is both repairable and absent');
+  assert.deepEqual(out.names, ['spike-harbor']);
+  assert.equal(out.already, 1, 'mercury');
+  assert.equal(out.skipped, 3, 'torn down · no address · no owner identity');
+  assert.equal(hub.publishes.length, 1);
+});
+
+test('the sweep asks the map ONCE for the whole fleet — never a round trip per instance', async () => {
+  // `catalogued` takes a list because this is the caller it was built for. A per-row loop here
+  // would be a presence read per instance at every boot, which is the N+1 the batch exists to
+  // avoid — and the origins asked about are exactly the backfillable ones, no more.
+  await backfill.sweepOnce({ pool: fakePool(), log: () => {} });
+  assert.equal(hub.reads.length, 1);
+  assert.deepEqual(hub.reads[0], [
+    'https://spike-harbor.cloudbongos.test',
+    'https://mercury.cloudbongos.test',
+    'https://test2.cloudbongos.test',
+  ]);
+});
+
+test('a fleet with nothing backfillable asks the map nothing', async () => {
+  const saved = provisioning.listAllInstances;
+  provisioning.listAllInstances = async () => [{ ...STANDALONE, status: 'torn_down' }];
+  try {
+    const out = await backfill.sweepOnce({ pool: fakePool(), log: () => {} });
+    assert.equal(out.considered, 1);
+    assert.equal(out.skipped, 1);
+    assert.equal(hub.reads.length, 0);
+  } finally {
+    provisioning.listAllInstances = saved;
+  }
+});
+
+test('a SECOND sweep writes nothing — safe to run at every single boot', async () => {
+  const deps = { pool: fakePool(), log: () => {} };
+  const first = await backfill.sweepOnce(deps);
+  assert.equal(first.projected, 2);
+
+  const second = await backfill.sweepOnce(deps);
+  assert.equal(second.projected, 0);
+  assert.equal(second.already, 2);
+  assert.equal(hub.publishes.length, 2, 'the two projected by the FIRST sweep, and no more');
+});
+
+test('the sweep says nothing when there was nothing to repair', async () => {
+  // A control plane that has already healed must not print an account at every restart.
+  hub.origins = new Set(['https://mercury.cloudbongos.test', ORIGIN]);
+  const lines = [];
+  await backfill.sweepOnce({ pool: fakePool(), log: (l) => lines.push(l) });
+  assert.deepEqual(lines, []);
+});
+
+test('the disposition line names what it repaired', async () => {
+  assert.equal(
+    backfill.formatSweepLine({ considered: 22, projected: 2, already: 1, skipped: 19, names: ['mercury', 'lars-test'] }),
+    '[catalog-backfill] 22 instances: 2 projected (mercury, lars-test) · 1 already · 19 skipped',
+  );
+  assert.match(backfill.formatSweepLine({ considered: 1, refused: 1 }), / · 1 refused$/);
+});
+
+// ── 6. what the repair puts on the map is still redactable (D2a) ──────────────────────────
+
+test('a STEALTH instance the backfill adds is on the map ANONYMOUSLY — the row names nothing', async () => {
+  // The backfill's whole job is putting rows on the map that were never there, so the
+  // anonymisation has to hold for what it adds, not only for what the write paths added.
+  const pool = fakePool();
+  await bridge.healInstanceCatalog(pool, { ...STANDALONE, settings: { visibility: 'stealth' } });
+  const entry = catalog.normalizeEntry(hub.publishes[0].entry);
+  assert.equal(entry.visibility, 'stealth');
+
+  const wire = feed.feedShapeFor({
+    origin: entry.origin, name: entry.name, description: entry.description,
+    type: entry.type, visibility: entry.visibility, status: entry.status,
+  });
+  for (const field of ['origin', 'name', 'description', 'type']) {
+    assert.equal(wire[field], null, `${field} must not leave the server for a black hole`);
+  }
+  assert.deepEqual(Object.keys(wire).filter((k) => wire[k] !== null).sort(), ['orb', 'state']);
+});

package/tests/project_catalog_routes.mjs

@@ -14,6 +14,12 @@
 // …and one negative: a settings save that changes nothing must not write to the catalog
 // either, for the same reason it does not restart the project.
 //
+// Task 1003581 adds the FIFTH call site, and it is a READ: `GET /provisioning/instances/:id`
+// self-heals the projection, because a write-triggered projection says nothing about the
+// instances that existed BEFORE ADR 0246 landed — their owners' invites 404 until they happen
+// to save something. Two pins: the owner's own read reaches the heal, and a REFUSED read never
+// does (the repair may only ever ride an own-scoped request).
+//
 // DB-free: the real router over loopback, data access and the bridge stubbed on the cached
 // module objects (the provisioning_settings.mjs pattern).
 //
@@ -40,6 +46,8 @@ const BASE_ROW = Object.freeze({
 let instance = { ...BASE_ROW };
 // Every catalog projection the routes ask for, in order.
 let published = [];
+// Every self-heal the READ path asks for (task 1003581).
+let healed = [];
 
 provisioning.getInstanceById = async (_db, id) => (instance ? { ...instance, id } : null);
 provisioning.getInstanceBySlug = async (_db, slug) => (instance && instance.slug === slug ? { ...instance } : null);
@@ -72,6 +80,10 @@ catalogBridge.publishInstanceToCatalog = async (_db, row, opts = {}) => {
   published.push({ row: row ? { ...row } : null, ...opts });
   return { published: true };
 };
+catalogBridge.healInstanceCatalog = async (_db, row) => {
+  healed.push(row ? { ...row } : null);
+  return { healed: true };
+};
 
 // Destructured off the doorway at route-module load — stub before requiring the router.
 api.requireBuilder = (req, _res, next) => { req.builder = OWNER; next(); };
@@ -115,7 +127,7 @@ function call(method, path, body) {
   });
 }
 
-beforeEach(() => { instance = { ...BASE_ROW }; published = []; });
+beforeEach(() => { instance = { ...BASE_ROW }; published = []; healed = []; });
 
 test('CREATE catalogues the project at birth, whatever its hosting shape', async () => {
   // The wizard hard-codes hosting_shape 'standalone', which is exactly the shape
@@ -212,6 +224,42 @@ test('a catalog hiccup can never turn a saved change into a failure', async () =
   }
 });
 
+test('the OWNER READ self-heals the projection, with the row it just read (task 1003581)', async () => {
+  // The repair for every instance older than ADR 0246: its owner opens the manage page and
+  // the project catalogues itself, instead of waiting for them to save something they had no
+  // reason to change. Conditional and best-effort — what it then does is pinned in
+  // tests/project_catalog_backfill.mjs.
+  const res = await call('GET', '/provisioning/instances/18');
+  assert.equal(res.status, 200);
+  assert.equal(healed.length, 1);
+  assert.equal(healed[0].slug, 'spike-harbor');
+  assert.equal(published.length, 0, 'a read is not a write — only the heal path runs');
+});
+
+test('a REFUSED read heals NOTHING — the repair only ever rides an own-scoped request', async () => {
+  // instanceAccessDenied answers 404 for someone else's instance, and the heal must sit
+  // BEHIND that gate: an unauthenticated or wrong-owner read must never make the platform
+  // write a catalog row on a stranger's behalf.
+  instance = { ...BASE_ROW, owner_builder_id: 99 };
+  const res = await call('GET', '/provisioning/instances/18');
+  assert.equal(res.status, 404);
+  assert.equal(healed.length, 0);
+});
+
+test('a heal that throws can never turn the manage read into a failure', async () => {
+  // Same rule as every other call site: the repair is best-effort, and the owner's page must
+  // load whether or not the hub answered.
+  const saved = catalogBridge.healInstanceCatalog;
+  catalogBridge.healInstanceCatalog = async () => { throw new Error('hub unreachable'); };
+  try {
+    const res = await call('GET', '/provisioning/instances/18');
+    assert.equal(res.status, 200);
+    assert.equal(res.body.instance.slug, 'spike-harbor');
+  } finally {
+    catalogBridge.healInstanceCatalog = saved;
+  }
+});
+
 test('mounting the routes registers the `provisioning.projectOwnedBy` port (task 1003580)', async () => {
   // The OTHER direction of the same seam: the catalog write travels provisioning → hub, and
   // this ownership read travels hub → provisioning, so the hub's invite door can own-scope a