@bongos/core 1.19.533 → 1.19.535

package/tests/project_catalog_routes.mjs

@@ -0,0 +1,213 @@
+// tests/project_catalog_routes.mjs — WHEN the catalog projection is re-taken (task 1003576,
+// ADR 0246). The wiring half; tests/project_catalog_bridge.mjs owns WHAT it writes.
+//
+// The R18 proof's finding was not "the write is wrong" but "the write happens ONCE, at
+// provision time, for one hosting shape". So the assertions here are about CALL SITES:
+// every provisioning write that can change what the map shows must re-take the picture.
+//
+//   POST   /provisioning/instances               — the project joins the catalog at birth
+//   PATCH  /provisioning/instances/:id/detail    — the description that publishes it, AND
+//                                                  the clearing that un-publishes it
+//   PATCH  /provisioning/instances/:id/settings  — the join door the orb is drawn from
+//   POST   /provisioning/instances/:id/domain    — the origin the row is KEYED on
+//
+// …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.
+//
+// DB-free: the real router over loopback, data access and the bridge stubbed on the cached
+// module objects (the provisioning_settings.mjs pattern).
+//
+// Run:  node --test --test-reporter=tap tests/project_catalog_routes.mjs
+
+import assert from 'node:assert/strict';
+import { test, after, beforeEach } from 'node:test';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+const provisioning = require('../modules/provisioning/provisioning.js');
+const catalogBridge = require('../modules/provisioning/catalog-bridge.js');
+const api = require('../src/module-api.js');
+
+const OWNER = { id: 7, github_login: 'owner', rank: 'thetes' };
+const BASE_ROW = Object.freeze({
+  id: 18, slug: 'spike-harbor', domain: 'spike-harbor.cloudbongos.test',
+  hosting_shape: 'standalone', status: 'active', owner_builder_id: 7,
+  description: null, type: 'research', settings: { visibility: 'public' },
+  released_domains: [], cost_estimate_usd: 0,
+});
+
+let instance = { ...BASE_ROW };
+// Every catalog projection the routes ask for, in order.
+let published = [];
+
+provisioning.getInstanceById = async (_db, id) => (instance ? { ...instance, id } : null);
+provisioning.getInstanceBySlug = async (_db, slug) => (instance && instance.slug === slug ? { ...instance } : null);
+provisioning.getInstanceByDomain = async () => null;
+provisioning.createInstance = async (_db, req) => {
+  instance = { ...BASE_ROW, slug: req.slug, domain: req.domain || null, description: req.description || null };
+  return { instance: { ...instance }, created: true };
+};
+provisioning.updateInstanceDetail = async (_db, id, patch) => {
+  instance = { ...instance, ...patch };
+  return { ...instance, id };
+};
+provisioning.updateInstanceSettings = async (_db, id, patch) => {
+  instance = { ...instance, settings: { ...(instance.settings || {}), ...patch } };
+  return { ...instance, id };
+};
+provisioning.updateInstanceDomain = async (_db, id, domain) => {
+  instance = { ...instance, domain };
+  return { ...instance, id };
+};
+provisioning.recordEvent = async () => {};
+provisioning.getOpenIntent = async () => null;
+provisioning.enqueueIntent = async () => ({ intent: { id: 1, action: 'provision', state: 'pending' }, created: true });
+provisioning.enqueueSettingsApply = async () => ({ intent: { id: 2, action: 'settings-apply', state: 'pending' }, created: true });
+provisioning.getLatestOAuthManifestForInstance = async () => null;
+
+// THE BRIDGE ITSELF is stubbed: this file asserts that the routes call it, with which row,
+// and how often. What it then writes is pinned in tests/project_catalog_bridge.mjs.
+catalogBridge.publishInstanceToCatalog = async (_db, row, opts = {}) => {
+  published.push({ row: row ? { ...row } : null, ...opts });
+  return { published: true };
+};
+
+// Destructured off the doorway at route-module load — stub before requiring the router.
+api.requireBuilder = (req, _res, next) => { req.builder = OWNER; next(); };
+api.requirePermission = () => (_req, _res, next) => next();
+api.branding = () => ({ domains: { publicOrigin: 'https://cb.test', instanceBase: 'cloudbongos.test' },
+  identity: { productName: 'Cloud Bongos' } });
+
+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`;
+after(() => server.close());
+
+function call(method, path, body) {
+  return new Promise((resolve, reject) => {
+    const payload = body === undefined ? null : JSON.stringify(body);
+    const req = http.request(`${base}${path}`, {
+      method,
+      headers: payload ? { '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 }); });
+    });
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+beforeEach(() => { instance = { ...BASE_ROW }; published = []; });
+
+test('CREATE catalogues the project at birth, whatever its hosting shape', async () => {
+  // The wizard hard-codes hosting_shape 'standalone', which is exactly the shape
+  // shouldFederate() refused — so this is the call that ends "never catalogued at all".
+  const res = await call('POST', '/provisioning/instances', {
+    slug: 'spike-harbor', hosting_shape: 'standalone', description: 'A harbour for spikes.',
+  });
+  assert.equal(res.status, 201);
+  assert.equal(published.length, 1);
+  assert.equal(published[0].row.slug, 'spike-harbor');
+  assert.equal(published[0].row.description, 'A harbour for spikes.');
+});
+
+test('CREATE catalogues even when the owner SKIPS the description', async () => {
+  // Skipping is the supported default: the row exists, the publish gate keeps it dark
+  // matter, and PATCH …/detail is the way back onto the map. The row has to be there for
+  // that way back to reach anything.
+  const res = await call('POST', '/provisioning/instances', { slug: 'spike-harbor', hosting_shape: 'standalone' });
+  assert.equal(res.status, 201);
+  assert.equal(published.length, 1);
+  assert.equal(published[0].row.description, null);
+});
+
+test('the DETAIL write re-takes the projection with the row it just saved', async () => {
+  // THE bug: a description added after provisioning never reached the catalog.
+  const res = await call('PATCH', '/provisioning/instances/18/detail', { description: 'A harbour for spikes.' });
+  assert.equal(res.status, 200);
+  assert.equal(published.length, 1);
+  assert.equal(published[0].row.description, 'A harbour for spikes.',
+    'the UPDATED row, not the one read at the top of the handler');
+});
+
+test('CLEARING the description also re-takes it, so the project leaves the map', async () => {
+  instance = { ...BASE_ROW, description: 'A harbour for spikes.' };
+  const res = await call('PATCH', '/provisioning/instances/18/detail', { description: '   ' });
+  assert.equal(res.status, 200);
+  assert.equal(published.length, 1);
+  assert.equal(published[0].row.description, null, 'normalizeDescription made it a real null');
+});
+
+test('a detail write that only answers the interview still re-takes it', async () => {
+  // team_shape does not move the publish gate, but the projection is cheap and one call site
+  // per write is the invariant — a conditional here is how the next field gets forgotten.
+  const res = await call('PATCH', '/provisioning/instances/18/detail', { detail: { team_shape: 'solo' } });
+  assert.equal(res.status, 200);
+  assert.equal(published.length, 1);
+});
+
+test('the SETTINGS write re-takes the projection when the join door changes', async () => {
+  const res = await call('PATCH', '/provisioning/instances/18/settings', { visibility: 'stealth' });
+  assert.equal(res.status, 200);
+  assert.equal(published.length, 1);
+  assert.equal(published[0].row.settings.visibility, 'stealth');
+});
+
+test('a settings save that changes NOTHING writes nothing to the catalog', async () => {
+  // The same rule the restart follows: a whole-form save or a retried request must not
+  // bounce a live project, and it must not churn the catalog row either.
+  const res = await call('PATCH', '/provisioning/instances/18/settings', { visibility: 'public' });
+  assert.equal(res.status, 200);
+  assert.equal(published.length, 0);
+});
+
+test('the DOMAIN write re-keys the row and RETIRES the address it moved off', async () => {
+  // The catalog is keyed on origin, so a re-point both moves the project and abandons an
+  // origin — one left `active` would keep drawing an orb at a hostname it no longer answers on.
+  const res = await call('POST', '/provisioning/instances/18/domain', { domain: 'harbour.example.com' });
+  assert.equal(res.status, 200);
+  assert.equal(published.length, 1);
+  assert.equal(published[0].row.domain, 'harbour.example.com');
+  assert.equal(published[0].retireOrigin, 'spike-harbor.cloudbongos.test');
+});
+
+test('re-sending the SAME address is a no-op and re-takes nothing', async () => {
+  const res = await call('POST', '/provisioning/instances/18/domain', { domain: 'spike-harbor.cloudbongos.test' });
+  assert.equal(res.status, 200);
+  assert.equal(res.body.changed, false);
+  assert.equal(published.length, 0);
+});
+
+test('a catalog hiccup can never turn a saved change into a failure', async () => {
+  // Every call site runs AFTER the durable write, so a hub that is unreachable must not
+  // make the owner believe their description was lost. The bridge swallows its own errors;
+  // the `.catch(() => {})` at each call site is the second belt, and this is what proves it —
+  // a bridge that breaks its contract entirely and throws still leaves a 200 and a saved row.
+  const saved = catalogBridge.publishInstanceToCatalog;
+  catalogBridge.publishInstanceToCatalog = async () => { throw new Error('hub unreachable'); };
+  try {
+    const res = await call('PATCH', '/provisioning/instances/18/detail', { description: 'A harbour.' });
+    assert.equal(res.status, 200);
+    assert.equal(res.body.description, 'A harbour.');
+  } finally {
+    catalogBridge.publishInstanceToCatalog = saved;
+  }
+});

package/tests/project_join_door.mjs

@@ -0,0 +1,166 @@
+// tests/project_join_door.mjs — the composed join/apply door (BV1.R12, task
+// 1002331): every visibility state × every join grant × every joinability, plus
+// the derived dark-matter lock and the fail-closed edges.
+//
+// The matrix is written out rather than sampled because the whole point of ADR
+// 0182 D6 is that two knobs must never negotiate — "the stricter of the two always
+// wins, and neither can widen the other" is a claim about all 27 cells, and the
+// bug it prevents (an owner setting `private` on the map while the public
+// application endpoint keeps taking applications) is invisible in any one of them.
+//
+// ESM `import` on purpose, not createRequire: knip does not credit a CJS module's
+// exports to a test that reaches them through require().
+//
+// Run:  node --test tests/project_join_door.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import {
+  JOIN_DOORS, DOOR_RANK, PROJECT_JOIN_GRANTS,
+  strictestDoor, visibilityCeiling, projectJoinDoor, effectiveJoinDoor,
+} from '../src/bongos/project-door.js';
+
+const VISIBILITIES = ['public', 'private', 'stealth'];
+const JOINABILITIES = ['open', 'apply', 'invite_only'];
+
+const door = (visibility, joinGrant, joinability, publishable) =>
+  projectJoinDoor({ visibility, joinGrant, joinability, publishable });
+
+// ── the vocabulary itself ────────────────────────────────────────────────────
+
+test('the door vocabulary is ordered widest → strictest, and the rank IS that order', () => {
+  assert.deepEqual(JOIN_DOORS, ['open', 'apply', 'invite_only', 'locked']);
+  assert.deepEqual(DOOR_RANK, { open: 0, apply: 1, invite_only: 2, locked: 3 });
+  assert.deepEqual(PROJECT_JOIN_GRANTS, ['view', 'apply', 'full']);
+});
+
+test('strictestDoor never widens, and an unknown door name is the strictest there is', () => {
+  assert.equal(strictestDoor('open', 'apply'), 'apply');
+  assert.equal(strictestDoor('invite_only', 'open'), 'invite_only');
+  assert.equal(strictestDoor('locked', 'open'), 'locked');
+  assert.equal(strictestDoor('open', 'open'), 'open');
+  assert.equal(strictestDoor('open', 'whatever'), 'locked', 'a value the table does not carry cannot widen the door');
+});
+
+// ── the visibility ceiling (ADR 0182 D6's table) ─────────────────────────────
+
+test('visibilityCeiling: public defers to the grant, every other state sets its own', () => {
+  assert.equal(visibilityCeiling('public', 'full'), 'open');
+  assert.equal(visibilityCeiling('public', 'apply'), 'apply');
+  assert.equal(visibilityCeiling('public', 'view'), 'invite_only');
+  assert.equal(visibilityCeiling('private', 'full'), 'apply', 'private accepts applications, never a self-join');
+  assert.equal(visibilityCeiling('stealth', 'full'), 'invite_only', 'stealth refuses the application at the door');
+});
+
+test('visibilityCeiling fails closed on anything it cannot read', () => {
+  assert.equal(visibilityCeiling('unlisted', 'full'), 'invite_only', 'a fourth enum value is never a planet');
+  assert.equal(visibilityCeiling(undefined, 'full'), 'invite_only');
+  assert.equal(visibilityCeiling('public', 'FULL'), 'invite_only', 'a grant this core cannot read is not the wide door');
+  assert.equal(visibilityCeiling('public', undefined), 'invite_only');
+});
+
+// ── the full matrix ──────────────────────────────────────────────────────────
+
+test('public: the join grants exactly what the owner set — until joinability narrows it', () => {
+  // grant `full` is the "does not narrow" value, so a public project runs the
+  // door its joinability already ran: this is what makes the default a no-op.
+  assert.equal(door('public', 'full', 'open'), 'open');
+  assert.equal(door('public', 'full', 'apply'), 'apply');
+  assert.equal(door('public', 'full', 'invite_only'), 'invite_only');
+  // grant `apply`: a self-join is off the table even where enrolment is open.
+  assert.equal(door('public', 'apply', 'open'), 'apply');
+  assert.equal(door('public', 'apply', 'apply'), 'apply');
+  assert.equal(door('public', 'apply', 'invite_only'), 'invite_only');
+  // grant `view`: the project is on the map to be looked at; joining is by invite.
+  assert.equal(door('public', 'view', 'open'), 'invite_only');
+  assert.equal(door('public', 'view', 'apply'), 'invite_only');
+  assert.equal(door('public', 'view', 'invite_only'), 'invite_only');
+});
+
+test('private: invite-only with applications queued — the grant is a PUBLIC join\'s, and does not reach here', () => {
+  for (const grant of PROJECT_JOIN_GRANTS) {
+    assert.equal(door('private', grant, 'open'), 'apply', `grant ${grant} cannot widen private into a self-join`);
+    assert.equal(door('private', grant, 'apply'), 'apply', 'a private project queues the application for its owner');
+    assert.equal(door('private', grant, 'invite_only'), 'invite_only');
+  }
+});
+
+test('stealth: no application is accepted, whatever the other two knobs say', () => {
+  for (const grant of PROJECT_JOIN_GRANTS) {
+    for (const joinability of JOINABILITIES) {
+      assert.equal(door('stealth', grant, joinability), 'invite_only',
+        `stealth + ${grant} + ${joinability} still refuses at the door`);
+    }
+  }
+});
+
+test('ADR 0182 D6, cell by cell: neither knob can widen the other', () => {
+  let cells = 0;
+  for (const visibility of VISIBILITIES) {
+    for (const grant of PROJECT_JOIN_GRANTS) {
+      for (const joinability of JOINABILITIES) {
+        const answer = door(visibility, grant, joinability);
+        const ceiling = visibilityCeiling(visibility, grant);
+        assert.ok(DOOR_RANK[answer] >= DOOR_RANK[ceiling], 'the visibility ceiling is never widened');
+        assert.ok(DOOR_RANK[answer] >= DOOR_RANK[joinability], 'the joinability policy is never widened');
+        assert.equal(answer, strictestDoor(ceiling, joinability), 'the answer IS the stricter of the two');
+        cells++;
+      }
+    }
+  }
+  assert.equal(cells, 27, 'every state × grant × policy cell is asserted');
+});
+
+// ── dark matter ──────────────────────────────────────────────────────────────
+
+test('dark matter locks the door outright — there is nothing to knock on', () => {
+  for (const visibility of VISIBILITIES) {
+    for (const grant of PROJECT_JOIN_GRANTS) {
+      for (const joinability of JOINABILITIES) {
+        assert.equal(door(visibility, grant, joinability, false), 'locked');
+      }
+    }
+  }
+});
+
+test('publishable is a TRI-state: only an explicit false locks, and no verdict decides nothing', () => {
+  assert.equal(door('public', 'full', 'open', true), 'open', 'a met publish bar opens nothing on its own');
+  assert.equal(door('public', 'full', 'open', null), 'open', 'no verdict → the three stored knobs answer alone');
+  assert.equal(door('public', 'full', 'open', undefined), 'open');
+  assert.equal(door('public', 'full', 'open'), 'open', 'an absent argument is no verdict, never a lock');
+});
+
+test('a door surface holding no inputs at all is refused, not opened — and not mis-explained', () => {
+  assert.equal(projectJoinDoor(), 'invite_only');
+  assert.equal(projectJoinDoor({}), 'invite_only');
+  assert.equal(door('public', 'full', 'whenever'), 'invite_only',
+    'an unreadable policy closes to invite-only, never to `locked` — that word claims the project is unpublished');
+});
+
+// ── the live reader ──────────────────────────────────────────────────────────
+
+test('effectiveJoinDoor composes the resolved pack with the admission reader', () => {
+  const pack = (project) => () => ({ project });
+  assert.equal(effectiveJoinDoor({
+    branding: pack({ visibility: 'public', joinGrant: 'full' }), joinabilityMode: () => 'apply',
+  }), 'apply');
+  assert.equal(effectiveJoinDoor({
+    branding: pack({ visibility: 'stealth', joinGrant: 'full' }), joinabilityMode: () => 'open',
+  }), 'invite_only', 'an open stealth project still refuses everything (ADR 0182 D6)');
+  assert.equal(effectiveJoinDoor({
+    branding: pack({ visibility: 'public', joinGrant: 'apply' }), joinabilityMode: () => 'open',
+  }), 'apply', 'a grant narrows a project whose enrolment is open');
+});
+
+test('effectiveJoinDoor fails closed when the pack will not load', () => {
+  const boom = () => { throw new Error('pack unreadable'); };
+  assert.equal(effectiveJoinDoor({ branding: boom, joinabilityMode: () => 'open' }), 'invite_only');
+  assert.equal(effectiveJoinDoor({ branding: () => ({}), joinabilityMode: () => 'open' }), 'invite_only',
+    'a pack with no project block is unknown policy, not an open door');
+});
+
+test('effectiveJoinDoor passes a publish verdict through when its caller holds one', () => {
+  const pack = () => ({ project: { visibility: 'public', joinGrant: 'full' } });
+  assert.equal(effectiveJoinDoor({ branding: pack, joinabilityMode: () => 'open', publishable: false }), 'locked');
+  assert.equal(effectiveJoinDoor({ branding: pack, joinabilityMode: () => 'open', publishable: true }), 'open');
+});

package/tests/project_join_door_route.mjs

@@ -0,0 +1,206 @@
+// tests/project_join_door_route.mjs — the composed door AT THE ROUTE (BV1.R12,
+// task 1002331): every visibility state × every join grant, driven through the
+// real public POST /access-requests against a scripted pool.
+//
+// tests/project_join_door.mjs pins the decision; this pins that the DOOR ACTUALLY
+// RUNS IT — the gap R12 exists to close was a correct policy nothing consulted.
+// So the REAL composer is wired in (only `branding` and the joinability reader are
+// stubbed), and every case asserts the query count too: a refused application must
+// cost no DB work and, per ADR 0182 D6, must never be stored.
+//
+// The doorway is stubbed in require.cache BEFORE the route loads — the route
+// destructures pool/validators at require time (the access_requests_invite pattern).
+//
+// Run:  node --test tests/project_join_door_route.mjs
+
+import assert from 'node:assert/strict';
+import { test, before, after } from 'node:test';
+import http from 'node:http';
+import { createRequire } from 'node:module';
+import { effectiveJoinDoor } from '../src/bongos/project-door.js';
+
+const require = createRequire(import.meta.url);
+const express = require('express');
+
+const apiPath = require.resolve('../src/module-api.js');
+const realApi = require(apiPath);
+
+let calls = [];
+let script = [];
+// The policy this project runs — the three knobs the platform pushes into the
+// instance's branding pack, exactly as src/branding.js resolves them.
+let policy = { visibility: 'public', joinGrant: 'full', joinability: 'apply' };
+let publishable;
+
+const pool = {
+  async query(sql, params) {
+    calls.push({ sql, params });
+    if (!script.length) throw new Error(`unscripted query: ${sql.trim().slice(0, 40)}`);
+    const next = script.shift();
+    if (next instanceof Error) throw next;
+    return next;
+  },
+};
+require.cache[apiPath].exports = {
+  ...realApi,
+  pool,
+  // The REAL composition, over a stubbed pack + admission reader. Nothing about
+  // the decision is faked here — only where its three inputs come from.
+  projectJoinDoor: () => effectiveJoinDoor({
+    branding: () => ({ project: { visibility: policy.visibility, joinGrant: policy.joinGrant } }),
+    joinabilityMode: () => policy.joinability,
+    publishable,
+  }),
+  requireBuilder: (req, _res, next) => { req.builder = { id: 42, github_login: 'archon' }; next(); },
+  requirePermission: () => (_req, _res, next) => next(),
+};
+
+const buildAccessRequestsRouter = require('../modules/onboarding/routes/access-requests.js');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+
+const app = express();
+app.use(express.json());
+app.use(attachFail);
+app.use('/api/gds', buildAccessRequestsRouter());
+
+let server, port;
+before(async () => {
+  server = http.createServer(app);
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  port = server.address().port;
+});
+after(async () => { await new Promise((r) => server.close(r)); });
+
+function post(pathname, body) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const req = http.request({
+      host: '127.0.0.1', port, path: pathname, method: 'POST',
+      headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) },
+    }, (res) => {
+      let data = '';
+      res.on('data', (c) => { data += c; });
+      res.on('end', () => resolve({ status: res.statusCode, json: data ? JSON.parse(data) : null }));
+    });
+    req.on('error', reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+const none = { rows: [] };
+const filed = [none, none, { rows: [{ id: 9, github_login: 'octocat', status: 'pending' }] }];
+
+// Knock on the door as a stranger under one policy, and say what happened.
+async function knock(next, { publishable: verdict } = {}) {
+  policy = next;
+  publishable = verdict;
+  script = [...filed];
+  calls = [];
+  const r = await post('/api/gds/access-requests', { github_login: 'octocat' });
+  return { status: r.status, code: r.json?.error?.code || null, filed: calls.length > 0, queries: calls.length };
+}
+
+const GRANTS = ['view', 'apply', 'full'];
+const REFUSED = { invite_only: 403, open_enrollment: 409, not_published: 403 };
+
+// ── public: the join grants exactly what the owner set ───────────────────────
+
+test('public + grant full: the door runs whatever joinability runs — the default changes nothing', async () => {
+  assert.deepEqual(await knock({ visibility: 'public', joinGrant: 'full', joinability: 'apply' }),
+    { status: 201, code: null, filed: true, queries: 3 });
+  assert.deepEqual(await knock({ visibility: 'public', joinGrant: 'full', joinability: 'open' }),
+    { status: 409, code: 'open_enrollment', filed: false, queries: 0 });
+  assert.deepEqual(await knock({ visibility: 'public', joinGrant: 'full', joinability: 'invite_only' }),
+    { status: 403, code: 'invite_only', filed: false, queries: 0 });
+});
+
+test('public + grant apply: the application is filed even where enrolment is open', async () => {
+  const r = await knock({ visibility: 'public', joinGrant: 'apply', joinability: 'open' });
+  assert.deepEqual(r, { status: 201, code: null, filed: true, queries: 3 },
+    'the grant narrowed a self-join into a request — the knob nothing used to read');
+});
+
+test('public + grant view: the project is there to be looked at; joining is by invite', async () => {
+  for (const joinability of ['open', 'apply', 'invite_only']) {
+    const r = await knock({ visibility: 'public', joinGrant: 'view', joinability });
+    assert.deepEqual(r, { status: 403, code: 'invite_only', filed: false, queries: 0 }, `joinability ${joinability}`);
+  }
+});
+
+// ── private: invite-only, with applications queued for the owner ─────────────
+
+test('private: the application queues for the owner, and no grant re-opens a self-join', async () => {
+  for (const joinGrant of GRANTS) {
+    assert.deepEqual(await knock({ visibility: 'private', joinGrant, joinability: 'open' }),
+      { status: 201, code: null, filed: true, queries: 3 }, `grant ${joinGrant} on an open-enrolment private project`);
+    assert.deepEqual(await knock({ visibility: 'private', joinGrant, joinability: 'apply' }),
+      { status: 201, code: null, filed: true, queries: 3 }, `grant ${joinGrant}`);
+  }
+});
+
+test('private + invite_only: the stricter knob still wins', async () => {
+  assert.deepEqual(await knock({ visibility: 'private', joinGrant: 'full', joinability: 'invite_only' }),
+    { status: 403, code: 'invite_only', filed: false, queries: 0 });
+});
+
+// ── stealth: no application is accepted, and none is stored ──────────────────
+
+test('stealth: every combination is refused at the door, before any query', async () => {
+  for (const joinGrant of GRANTS) {
+    for (const joinability of ['open', 'apply', 'invite_only']) {
+      const r = await knock({ visibility: 'stealth', joinGrant, joinability });
+      assert.deepEqual(r, { status: 403, code: 'invite_only', filed: false, queries: 0 },
+        `stealth + ${joinGrant} + ${joinability}`);
+    }
+  }
+});
+
+test('the refusal never says WHICH knob closed the door — stealth is indistinguishable from the other two', async () => {
+  const stealth = await knock({ visibility: 'stealth', joinGrant: 'full', joinability: 'apply' });
+  const viewOnly = await knock({ visibility: 'public', joinGrant: 'view', joinability: 'apply' });
+  const inviteOnly = await knock({ visibility: 'public', joinGrant: 'full', joinability: 'invite_only' });
+  assert.deepEqual(stealth, viewOnly, 'a stealth project answers exactly as a look-only public one');
+  assert.deepEqual(stealth, inviteOnly, 'and exactly as an ordinary invite-only one (ADR 0182 D2a)');
+});
+
+// ── dark matter ──────────────────────────────────────────────────────────────
+
+test('dark matter: locked outright, whatever the three stored knobs say', async () => {
+  for (const visibility of ['public', 'private', 'stealth']) {
+    const r = await knock({ visibility, joinGrant: 'full', joinability: 'open' }, { publishable: false });
+    assert.deepEqual(r, { status: 403, code: 'not_published', filed: false, queries: 0 }, visibility);
+  }
+});
+
+test('the locked refusal names the PROJECT\'s state, not the applicant\'s — nothing they can retry', async () => {
+  policy = { visibility: 'public', joinGrant: 'full', joinability: 'apply' };
+  publishable = false;
+  script = [];
+  calls = [];
+  const r = await post('/api/gds/access-requests', { github_login: 'octocat' });
+  assert.equal(r.status, 403);
+  assert.match(r.json.error.message, /isn’t published yet/);
+  assert.doesNotMatch(r.json.error.message, /sign in|invite/i, 'it offers no way in, because there is none yet');
+});
+
+// ── the refusal costs nothing, and reveals nothing ───────────────────────────
+
+test('every refusal answers before the body is even validated — no applicant lookup, no oracle', async () => {
+  for (const [code, status] of Object.entries(REFUSED)) {
+    const closed = code === 'not_published'
+      ? { policy: { visibility: 'public', joinGrant: 'full', joinability: 'apply' }, verdict: false }
+      : code === 'open_enrollment'
+        ? { policy: { visibility: 'public', joinGrant: 'full', joinability: 'open' }, verdict: undefined }
+        : { policy: { visibility: 'stealth', joinGrant: 'full', joinability: 'apply' }, verdict: undefined };
+    policy = closed.policy;
+    publishable = closed.verdict;
+    script = [];
+    calls = [];
+    // A body that would 400 on a working door: the refusal must come first.
+    const r = await post('/api/gds/access-requests', { github_login: 'not a login!' });
+    assert.equal(r.status, status, code);
+    assert.equal(r.json.error.code, code);
+    assert.equal(calls.length, 0, `${code} consulted the database`);
+  }
+});