@bongos/core 1.19.744 → 1.19.745

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.744",
-  "core_contract": "1.19.744",
-  "source_commit": "a1c9e8b6b38e48c9f3a6040ff29b76ee3457b808",
+  "core_version": "1.19.745",
+  "core_contract": "1.19.745",
+  "source_commit": "35769e9ee6c0bd162dcd30f6360cf22a69adc5e6",
   "source_ref": "HEAD",
-  "built_at": "2026-09-15T15:04:25.874Z",
+  "built_at": "2026-09-15T15:42:00.191Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 479,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2107,
+    "functional_verbatim": 2109,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2611,
-  "tree_sha256": "4cfb37d1d47bb997d911c6ae24958d363737b154c725bfb76fb65f3e71c92449",
+  "file_count": 2613,
+  "tree_sha256": "8ee268f754cacf633cc6358ef765b30b214928f4d38914cbbc0788b580835e83",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2492,7 +2492,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "8f98164df753a9a4a8c77ade44d450eeb65eee2987dcc5b46d0d251f2a62d399"
+      "sha256": "68cb61e401d3e601932f1db71ef88346adad1f2474c862143a224ed354ba0615"
     },
     {
       "path": "docs/modules-contract.md",
@@ -6229,6 +6229,11 @@
       "mode": "0000644",
       "sha256": "f4562bd90fdae26c5f7c51851bd2ad7752535bd0dcfb62dd567c11e76330c42b"
     },
+    {
+      "path": "modules/provisioning/migrations/provisioning_015_domain_unique.sql",
+      "mode": "0000644",
+      "sha256": "136b0b7e0485c1602a403767863137da0536e058b8913228d3a3e5a6ad56f512"
+    },
     {
       "path": "modules/provisioning/module.json",
       "mode": "0000644",
@@ -6257,7 +6262,7 @@
     {
       "path": "modules/provisioning/provisioning.js",
       "mode": "0000644",
-      "sha256": "9e6d1356fa046f97f3141c353302637dad2deed4c2460d124c8d7636b0ff0065"
+      "sha256": "b3a1261dbdefd526a93d75c8f46a7b896f2331292b41a919a73dde1ffba45eed"
     },
     {
       "path": "modules/provisioning/rate-limit.js",
@@ -6282,7 +6287,7 @@
     {
       "path": "modules/provisioning/routes/provisioning.js",
       "mode": "0000644",
-      "sha256": "eac6fb471e91a08d2c1003f4245140b2a995ae892140d625c116143a4a6610e1"
+      "sha256": "a3812af0cc12dfafff47c1b9b03edea6ef61f1f4728acead1628d0b1a1669432"
     },
     {
       "path": "modules/provisioning/starter-bundles.js",
@@ -7542,12 +7547,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "7d86631d2cad28001db3920822fd96bb638cede683d627fe0101445320c12d7e"
+      "sha256": "c5eabd4e0de92c43d27602e996ffeaeef177349bb4ed045a208578785b8af8be"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "d4c3e36f1af2829fc4bc7d9b6dc29be667c75e6d5fd870855398bc5e13380ddc"
+      "sha256": "d9ddaa7b2fa408cceb8cdc0540ad523f0d64da3ec91a9420f73058088585dee9"
     },
     {
       "path": "public-docs/index.html",
@@ -9347,7 +9352,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "6cec169dc7c62404bb81e3b7fc00506de07048b3a0ce2ef59f892d467b9e0c3b"
+      "sha256": "96b3c84f00546eba7a57b31eba4a96acf0d6285c3715a1370d3527242e4d161b"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12009,6 +12014,11 @@
       "mode": "0000644",
       "sha256": "62ea8ffc2c21c351289dc7f96cab38fcd5824afba1fed0df7a545cd5df9e396c"
     },
+    {
+      "path": "tests/provisioning_domain_unique.mjs",
+      "mode": "0000644",
+      "sha256": "d1c9456ad442caf2485c5c38e5bad98ef6c834589e405eade59cbeffec534ea0"
+    },
     {
       "path": "tests/provisioning_github_app_routes.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -1962,5 +1962,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.742 with no explicit bump. run 34984876076. (task 1002620)
   1.19.744 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.743 with no explicit bump. run 34985887902. (task 1002620)
+  1.19.745 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.744 with no explicit bump. run 34990123950. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/provisioning/migrations/provisioning_015_domain_unique.sql

@@ -0,0 +1,46 @@
+-- provisioning_015_domain_unique.sql — database uniqueness on an instance's
+-- ADDRESS, closing the read-then-write race both write paths still carry
+-- (task 1002901; source idea 1000722, the task 1002704 review).
+--
+-- THE GAP. `slug` has carried `UNIQUE` since provisioning_001_tables.sql:35;
+-- `domain` was declared plainly at :49 and never constrained. Both address write
+-- paths enforce uniqueness in APPLICATION code with an unguarded read-then-write:
+-- the create route calls getInstanceByDomain and then INSERTs, and the
+-- domain-attach route calls getInstanceByDomain and then updateInstanceDomain.
+-- Two concurrent requests interleaving between the read and the write both pass
+-- their check, and one address ends up held by two instances.
+--
+-- WHY IT MATTERS MORE NOW. Task 1002704 put the domain write on the HOT PATH:
+-- auto-assign stamps defaultDomainForSlug(slug, apex) on EVERY creation, so the
+-- race is no longer an occasional bring-your-own step — it is every project
+-- anyone creates. Working area 1's done-when is that any new user can create a
+-- project; two projects answering at one hostname is that promise breaking under
+-- exactly the concurrency a growing platform produces.
+--
+-- THE APPLICATION CHECKS STAY. This index is a BACKSTOP, not a replacement: the
+-- read-then-write checks produce the good error message ("That address is
+-- already held by another instance"), and this makes the guarantee real when two
+-- requests interleave. The routes map this index's 23505 onto that same
+-- `domain_taken` 409, so a caller cannot tell which layer caught it.
+--
+-- WHY PARTIAL — `status <> 'torn_down'` IS LOAD-BEARING, NOT A TIDY-UP.
+-- A torn-down instance KEEPS its domain by design (ADR 0181 Decision 2: the
+-- revive path re-uses that exact hostname, and task 1002897 automates only the
+-- DNS-park and Caddy-removal legs while confirming that retention). An
+-- UNCONDITIONAL unique index would therefore permanently block re-creating a
+-- project at an address that was once torn down — a worse bug than the race it
+-- closes. The partial form mirrors the ux_provisioning_intents_open precedent at
+-- provisioning_001_tables.sql:129.
+--
+-- WHY lower(domain). It matches getInstanceByDomain's existing lookup
+-- (`WHERE lower(domain) = $1`), so the index and the application check agree on
+-- what "the same address" means. Without it, 'Mercury.cloudbongos.com' and
+-- 'mercury.cloudbongos.com' would be two rows to the index and one address to
+-- every reader.
+--
+-- SAFE TO CREATE. Re-verified live against the fleet at claim time (2026-09-15):
+-- 23 instances, 6 rows fall under this predicate, all distinct, no case
+-- variants. `IF NOT EXISTS` keeps the migration idempotent across re-runs.
+CREATE UNIQUE INDEX IF NOT EXISTS ux_provisioning_instances_domain
+  ON provisioning_instances (lower(domain))
+  WHERE domain IS NOT NULL AND status <> 'torn_down';

package/modules/provisioning/provisioning.js

@@ -781,6 +781,23 @@ async function getInstanceBySlug(db, slug) {
   return rows[0] || null;
 }
 
+// The partial unique index provisioning_015 puts on lower(domain) — the database
+// backstop behind both address write paths' read-then-write check (task 1002901).
+// Named once, here, so the migration that CREATES it and the predicate that
+// RECOGNIZES it cannot drift: a rename in one and not the other would leave
+// isDomainTaken() silently never matching. The test reads the .sql and pins both.
+const DOMAIN_UNIQUE_INDEX = 'ux_provisioning_instances_domain';
+
+// Did this error come from two requests racing for one address? The slug UNIQUE
+// and the domain index share error code 23505, so the code alone cannot tell them
+// apart — `constraint` is what names which one actually fired. Both address write
+// paths check uniqueness in application code first and produce the good message;
+// this predicate is how the clash that slips through that window still answers
+// `domain_taken` instead of surfacing as a raw 500 (task 1002901).
+function isDomainTaken(e) {
+  return !!e && e.code === '23505' && e.constraint === DOMAIN_UNIQUE_INDEX;
+}
+
 // The instance currently holding `domain` (case-insensitive), if any — backs the
 // domain-attach route's uniqueness check so one owner's address can never silently
 // shadow another's (task 1002692). Caller normalizes; matching is defensive anyway.
@@ -1073,11 +1090,21 @@ async function createInstance(db, { ownerBuilderId, slug, targetRef, hostingShap
     );
     return { instance: rows[0], created: true };
   } catch (e) {
-    // 23505 = unique_violation on the slug UNIQUE constraint.
+    // 23505 = unique_violation, and since provisioning_015 TWO indexes raise it here
+    // — slug UNIQUE and ux_provisioning_instances_domain. Resolve by SLUG FIRST,
+    // whichever one Postgres named. That order is load-bearing: an idempotent
+    // re-request duplicates the slug AND the <slug>.<apex> address auto-assign
+    // stamped on the first one (task 1002704), so it violates BOTH and Postgres
+    // reports only the index it checked first. Branching on `e.constraint` would
+    // turn that re-request into a 409 whenever the domain index won the race — a
+    // coin-flip bug that appears only once an address is assigned.
     if (e && e.code === '23505') {
       const existing = await getInstanceBySlug(db, slug);
       if (existing) return { instance: existing, created: false };
     }
+    // No row under this slug, so a 23505 can only be the domain index: a real race
+    // for an address taken between the route's check and this INSERT. It propagates
+    // as-is, and the route maps it via isDomainTaken() onto the same domain_taken 409.
     throw e;
   }
 }
@@ -1453,6 +1480,8 @@ module.exports = {
   normalizeDescription, normalizeProjectDetail, projectDetailPatch, projectDetail,
   // pure — GitHub App Manifest flow (task 2080)
   githubAppName, buildGithubAppManifest, manifestPostUrl, publicGithubApp,
+  // pure — the address race's database backstop (task 1002901, provisioning_015)
+  DOMAIN_UNIQUE_INDEX, isDomainTaken,
   // data access
   isProvisionedHostname,
   getInstanceById, getInstanceBySlug, getInstanceByDomain, listInstancesForOwner, listAllInstances,

package/modules/provisioning/routes/provisioning.js

@@ -416,9 +416,7 @@ module.exports = function provisioningRoutes() {
         // never silently shadow another's.
         if (domain) {
           const holder = await provisioning.getInstanceByDomain(pool, domain);
-          if (holder && holder.slug !== slug) {
-            return res.fail('domain_taken', { status: 409, message: 'That address is already held by another instance.' });
-          }
+          if (holder && holder.slug !== slug) return res.fail('domain_taken', { status: 409, message: 'That address is already held by another instance.' });
         }
       }
       const { instance, created } = await provisioning.createInstance(pool, {
@@ -522,6 +520,8 @@ module.exports = function provisioningRoutes() {
         ...(modulesIgnored ? { modules_ignored: modulesIgnored } : {}),
       });
     } catch (err) {
+      // Another instance took the address between the check above and the INSERT (task 1002901).
+      if (provisioning.isDomainTaken(err)) return res.fail('domain_taken', { status: 409, message: 'That address is already held by another instance.' });
       log.error('[provisioning] POST /provisioning/instances', err);
       res.fail('request_failed', { status: 500, message: 'internal error' });
     }
@@ -1170,9 +1170,7 @@ module.exports = function provisioningRoutes() {
       const releasing = current && current !== assignedDefault
         && provisioning.DOMAIN_RELEASE_FROM.has(inst.status) ? current : null;
       const holder = await provisioning.getInstanceByDomain(pool, domain);
-      if (holder && String(holder.id) !== String(inst.id)) {
-        return res.fail('domain_taken', { status: 409, message: 'That address is already in use by another instance.' });
-      }
+      if (holder && String(holder.id) !== String(inst.id)) return res.fail('domain_taken', { status: 409, message: 'That address is already in use by another instance.' });
       if (!provisioning.DOMAIN_ATTACH_FROM.has(inst.status)) {
         return res.fail('domain_not_attachable', { status: 409,
           message: `Instance is '${inst.status}' — an address can be attached once it settles ('active') or before standup ('requested').`,
@@ -1229,6 +1227,8 @@ module.exports = function provisioningRoutes() {
       res.json({ ok: true, changed: true, queued, domain, replaced: releasing,
         message: MESSAGES[`${queued ? 'queued' : 'recorded'}:${releasing ? 'repoint' : 'first'}`] });
     } catch (err) {
+      // Same race on the attach side: the index refuses the UPDATE, so nothing is recorded and nothing is enqueued.
+      if (provisioning.isDomainTaken(err)) return res.fail('domain_taken', { status: 409, message: 'That address is already in use by another instance.' });
       log.error('[provisioning] POST /provisioning/instances/:id/domain', err);
       res.fail('domain_attach_failed', { status: 500, message: 'internal error' });
     }

package/package-lock.json

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

package/package.json

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

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.744'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.745'; // 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/provisioning_domain_unique.mjs

@@ -0,0 +1,274 @@
+// tests/provisioning_domain_unique.mjs
+//
+// The database backstop behind an instance's ADDRESS (task 1002901; source idea
+// 1000722, the task 1002704 review).
+//
+// Both address write paths enforced uniqueness in application code with an
+// unguarded read-then-write — getInstanceByDomain, then INSERT (create) or
+// updateInstanceDomain (attach). Two concurrent requests interleaving between the
+// read and the write both passed, and one address ended up held by two instances.
+// provisioning_015 adds the partial unique index that makes the guarantee real;
+// these tests hold the four things that index changed.
+//
+// Covers:
+//   • the migration — partial on status <> 'torn_down' (ADR 0181 Decision 2 keeps
+//     a torn-down instance's address for the revive path, so an UNCONDITIONAL
+//     index would permanently block re-creating there), keyed on lower(domain) to
+//     match getInstanceByDomain, and idempotent
+//   • DOMAIN_UNIQUE_INDEX / isDomainTaken — the predicate that tells the domain
+//     index's 23505 apart from the slug UNIQUE's, which share the error code
+//   • createInstance's SLUG-FIRST resolution — the ordering that keeps an
+//     idempotent re-request idempotent when it violates BOTH indexes at once
+//   • both routes translating the index's refusal into the same domain_taken 409
+//     the read-then-write check produces
+//
+// DB-free: the service slice drives the REAL createInstance through a fake `db`
+// that throws like Postgres; the routes run over the real mounted router with
+// data-access fns stubbed (the provisioning_domain_attach.mjs pattern). No network.
+//
+// Run:  node tests/provisioning_domain_unique.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const provisioning = require('../modules/provisioning/provisioning.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// A unique_violation shaped like the one `pg` raises: the code alone cannot say
+// WHICH index fired, which is the whole reason isDomainTaken reads `constraint`.
+function uniqueViolation(constraint) {
+  return Object.assign(new Error(`duplicate key value violates unique constraint "${constraint}"`),
+    { code: '23505', constraint });
+}
+const DOMAIN_VIOLATION = () => uniqueViolation('ux_provisioning_instances_domain');
+const SLUG_VIOLATION = () => uniqueViolation('provisioning_instances_slug_key');
+
+console.log('\nthe migration — provisioning_015_domain_unique.sql:');
+
+const MIGRATION = fs.readFileSync(
+  path.resolve('modules/provisioning/migrations/provisioning_015_domain_unique.sql'), 'utf8');
+
+t('creates the index this module names in code — one spelling, not two', () => {
+  assert.match(MIGRATION, new RegExp(`CREATE UNIQUE INDEX IF NOT EXISTS ${provisioning.DOMAIN_UNIQUE_INDEX}\\b`),
+    'the migration and DOMAIN_UNIQUE_INDEX must agree, or isDomainTaken silently never matches');
+});
+
+t('is PARTIAL on status <> torn_down — a torn-down address is kept for the revive path (ADR 0181 D2)', () => {
+  assert.match(MIGRATION, /WHERE\s+domain IS NOT NULL AND status <> 'torn_down'/,
+    'an unconditional index would permanently block re-creating a project at a torn-down address');
+});
+
+t('is keyed on lower(domain) so the index and getInstanceByDomain mean the same address', () => {
+  assert.match(MIGRATION, /ON provisioning_instances \(lower\(domain\)\)/);
+});
+
+t('is idempotent — IF NOT EXISTS, so a re-run is a no-op', () => {
+  assert.match(MIGRATION, /IF NOT EXISTS/);
+});
+
+console.log('\nisDomainTaken — telling two 23505s apart:');
+
+t('the domain index firing is a domain clash', () => {
+  assert.equal(provisioning.isDomainTaken(DOMAIN_VIOLATION()), true);
+});
+
+t('the SLUG unique firing is NOT — same error code, different index, different answer', () => {
+  assert.equal(provisioning.isDomainTaken(SLUG_VIOLATION()), false,
+    'mapping a slug clash to domain_taken would tell an owner the wrong thing is taken');
+});
+
+t('a 23505 naming no constraint is not assumed to be ours', () => {
+  assert.equal(provisioning.isDomainTaken(Object.assign(new Error('x'), { code: '23505' })), false);
+});
+
+t('any other error code is not a clash — not even one naming our index', () => {
+  // A 23503 (foreign-key violation) can name this index in `constraint` too, so the
+  // predicate must read BOTH fields; matching on the name alone would map an
+  // unrelated database fault onto a 409 that tells the caller the wrong thing.
+  assert.equal(provisioning.isDomainTaken(
+    Object.assign(new Error('fk'), { code: '23503', constraint: 'ux_provisioning_instances_domain' })), false);
+  assert.equal(provisioning.isDomainTaken(new Error('boom')), false);
+});
+
+t('null / undefined never throw — the predicate runs inside a catch', () => {
+  assert.equal(provisioning.isDomainTaken(null), false);
+  assert.equal(provisioning.isDomainTaken(undefined), false);
+});
+
+console.log('\ncreateInstance — SLUG-FIRST resolution (the coin-flip bug this ordering prevents):');
+
+// The real createInstance, driven through a fake db: the INSERT throws like
+// Postgres, and the SELECT the catch falls back to answers for the slug.
+function fakeDb({ insertThrows, slugRow }) {
+  const calls = [];
+  return {
+    calls,
+    query: async (sql, params) => {
+      calls.push(sql.trim().split('\n')[0]);
+      if (/^INSERT INTO provisioning_instances/.test(sql.trim())) throw insertThrows;
+      if (/SELECT \* FROM provisioning_instances WHERE slug = \$1/.test(sql)) {
+        return { rows: slugRow ? [{ ...slugRow, slug: params[0] }] : [] };
+      }
+      return { rows: [] };
+    },
+  };
+}
+
+await ta('a re-request violating BOTH indexes stays idempotent when Postgres names the DOMAIN one', async () => {
+  // Auto-assign stamps <slug>.<apex> on every creation (task 1002704), so an
+  // idempotent re-request duplicates the slug AND its address. Postgres reports
+  // only the index it checked first; branching on e.constraint would turn the
+  // re-request into a 409 whenever the domain index won that race.
+  const db = fakeDb({ insertThrows: DOMAIN_VIOLATION(), slugRow: { id: 18, owner_builder_id: 7 } });
+  const out = await provisioning.createInstance(db, { ownerBuilderId: 7, slug: 'mercury', domain: 'mercury.example.com' });
+  assert.equal(out.created, false, 'a re-request is not a new project');
+  assert.equal(out.instance.id, 18, 'and it returns the EXISTING row, not an error');
+});
+
+await ta('the same re-request is idempotent when Postgres names the SLUG one (unchanged behaviour)', async () => {
+  const db = fakeDb({ insertThrows: SLUG_VIOLATION(), slugRow: { id: 18, owner_builder_id: 7 } });
+  const out = await provisioning.createInstance(db, { ownerBuilderId: 7, slug: 'mercury', domain: 'mercury.example.com' });
+  assert.equal(out.created, false);
+  assert.equal(out.instance.id, 18);
+});
+
+await ta('a REAL address race — domain taken, slug free — propagates for the route to map', async () => {
+  const db = fakeDb({ insertThrows: DOMAIN_VIOLATION(), slugRow: null });
+  await assert.rejects(
+    () => provisioning.createInstance(db, { ownerBuilderId: 7, slug: 'venus', domain: 'mercury.example.com' }),
+    (e) => provisioning.isDomainTaken(e),
+    'no row under this slug means the clash can only be the address');
+});
+
+await ta('an unrelated database error is never swallowed as a re-request', async () => {
+  const db = fakeDb({ insertThrows: Object.assign(new Error('connection terminated'), { code: '57P01' }), slugRow: null });
+  await assert.rejects(
+    () => provisioning.createInstance(db, { ownerBuilderId: 7, slug: 'venus' }),
+    /connection terminated/);
+});
+
+// ── route slice ────────────────────────────────────────────────────────────
+let instance = null;
+let createThrows = null;
+let updateThrows = null;
+let updateCalls = [];
+let enqueueCalls = [];
+
+provisioning.getInstanceById = async (_db, id) => (instance ? { ...instance, id } : null);
+provisioning.getInstanceByDomain = async () => null;   // the check PASSES — the race is after it
+provisioning.getInstanceBySlug = async () => null;
+provisioning.createInstance = async () => { if (createThrows) throw createThrows; return { instance: { id: 1 }, created: true }; };
+provisioning.updateInstanceDomain = async (_db, id, domain, releasing = null) => {
+  updateCalls.push({ id, domain, releasing });
+  if (updateThrows) throw updateThrows;
+  return { ...instance, id, domain };
+};
+provisioning.enqueueIntent = async (_db, id, action) => { enqueueCalls.push({ id, action }); return { intent: { id: 9, action, state: 'pending' }, created: true }; };
+provisioning.getOpenIntent = async () => null;
+provisioning.recordEvent = async () => {};
+
+const api = require('../src/module-api.js');
+api.requireBuilder = (req, _res, next) => { req.builder = { id: 7, github_login: 'owner' }; next(); };
+api.requirePermission = () => (_req, _res, next) => next();
+api.branding = () => ({
+  domains: { publicOrigin: 'https://cb.test', instanceBase: 'cb.test' },
+  identity: { productName: 'Cloud Bongos' },
+});
+
+// Both routes are rate-limited per builder and every test here posts as builder
+// 7, so the real cap would throttle the suite rather than the behaviour under
+// test (the provisioning_domain_attach.mjs precedent).
+const rateLimit = require('../modules/provisioning/rate-limit.js');
+const realMakeAskRateLimiter = rateLimit.makeAskRateLimiter;
+rateLimit.makeAskRateLimiter = (opts = {}) => realMakeAskRateLimiter({ ...opts, max: 10_000 });
+
+const express = require('express');
+const provisioningRoutes = require('../modules/provisioning/routes/provisioning.js');
+const app = express();
+app.use(express.json());
+app.use((_req, res, next) => {
+  res.fail = (code, opts, details) => {
+    const status = typeof opts === 'number' ? opts : (opts && opts.status) || 400;
+    res.status(status).json({ error: { code, ...(typeof opts === 'object' ? opts : {}), ...(details || {}) } });
+  };
+  next();
+});
+app.use('/api/bongos', provisioningRoutes());
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+
+function post(p, body = {}) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const req = http.request(`${base}${p}`, { method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) } }, (res) => {
+      let d = ''; res.on('data', (c) => { d += c; });
+      res.on('end', () => { let j = null; try { j = JSON.parse(d); } catch { /* non-JSON */ } resolve({ status: res.statusCode, body: j, raw: d }); });
+    });
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
+
+function reset() { instance = null; createThrows = null; updateThrows = null; updateCalls = []; enqueueCalls = []; }
+
+console.log('\nPOST /provisioning/instances — the index refusing a raced creation:');
+
+await ta('the index catching the race answers domain_taken 409, not a raw 500', async () => {
+  reset();
+  createThrows = DOMAIN_VIOLATION();
+  const res = await post('/provisioning/instances', { slug: 'venus', domain: 'mercury.example.com', no_address: false });
+  assert.equal(res.status, 409, res.raw);
+  assert.equal(res.body.error.code, 'domain_taken',
+    'the caller must not be able to tell which layer caught it — only the timing differs');
+});
+
+await ta('any OTHER failure is still the honest 500 — the mapping is narrow', async () => {
+  reset();
+  createThrows = Object.assign(new Error('connection terminated'), { code: '57P01' });
+  const res = await post('/provisioning/instances', { slug: 'venus', domain: 'mercury.example.com' });
+  assert.equal(res.status, 500, res.raw);
+  assert.equal(res.body.error.code, 'request_failed');
+});
+
+console.log('\nPOST /provisioning/instances/:id/domain — the index refusing a raced attach:');
+
+await ta('the index catching the race answers domain_taken 409, and nothing is queued', async () => {
+  reset();
+  instance = { owner_builder_id: 7, slug: 'spike', status: 'active', hosting_shape: 'standalone', domain: null };
+  updateThrows = DOMAIN_VIOLATION();
+  const res = await post('/provisioning/instances/18/domain', { domain: 'mercury.example.com' });
+  assert.equal(res.status, 409, res.raw);
+  assert.equal(res.body.error.code, 'domain_taken');
+  assert.equal(enqueueCalls.length, 0,
+    'the UPDATE was refused, so nothing was recorded — an attach intent would wire an address this instance does not hold');
+});
+
+await ta('any OTHER failure on attach is still the honest 500', async () => {
+  reset();
+  instance = { owner_builder_id: 7, slug: 'spike', status: 'active', hosting_shape: 'standalone', domain: null };
+  updateThrows = Object.assign(new Error('connection terminated'), { code: '57P01' });
+  const res = await post('/provisioning/instances/18/domain', { domain: 'mercury.example.com' });
+  assert.equal(res.status, 500, res.raw);
+  assert.equal(res.body.error.code, 'domain_attach_failed');
+});
+
+server.close();
+rateLimit.makeAskRateLimiter = realMakeAskRateLimiter;
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);