@bongos/core 1.19.511 → 1.19.513

package/tests/provisioning_recommendations.mjs

@@ -0,0 +1,448 @@
+// tests/provisioning_recommendations.mjs — the rule-based recommendation engine
+// (BV1.R17, task 1002336; goal 1000046 criteria `proj-module-select`,
+// `proj-governance-reco`, `proj-invite-builders`). Decision record: ADR 0239.
+//
+// Four things are pinned here:
+//
+//   1. Each rule fires on its condition and NOT otherwise — the whole claim of a
+//      rule engine, and the thing a table quietly breaks when a fourth row lands.
+//   2. Skipping the interview yields the stated defaults, and an off-vocabulary
+//      answer is read as no answer. Criterion `proj-detail-interview` splits on
+//      exactly this ("completing it produces tailored recommendations; skipping
+//      produces sensible defaults"), and R18 (task 1002337) proves it live.
+//   3. Table integrity — every module a rule names is a real OPT-IN module on
+//      disk, every governance rule names a preset that exists, and every team
+//      shape in the interview's own vocabulary has a rule. The ADR 0237 idiom: a
+//      pure file declares, and this test is the link back to the live catalog.
+//   4. The read surface — GET /provisioning/recommendations is public, needs no
+//      database, and hands back the same bundle shape the starter-bundles route
+//      serves, so a recommendation and a preselect can never name different
+//      modules.
+//
+// DB-free: the route is a pure read, so nothing here touches Postgres or the
+// network beyond a loopback listener on port 0.
+//
+// Run:  node --test --test-reporter=tap tests/provisioning_recommendations.mjs
+
+import { test, before, after } from 'node:test';
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+// ESM named imports off the CJS module on purpose: knip cannot trace a
+// createRequire() import, so a test-only export would read as dead code and move
+// the knip ratchet (see the repo's knip learning).
+import {
+  TEAM_SHAPE_RULES,
+  GOVERNANCE_PRESETS,
+  GOVERNANCE_RULES,
+  GOVERNANCE_DEFAULT,
+  INVITE_RULES,
+  INVITE_DEFAULT,
+  recommendationsForDetails,
+} from '../modules/provisioning/recommendations.js';
+import {
+  ALWAYS_ON_CORE,
+  HUB_ONLY_MODULES,
+  bundleForProjectType,
+} from '../modules/provisioning/starter-bundles.js';
+
+const require = createRequire(import.meta.url);
+
+// Stub the doorway in require.cache BEFORE the route file loads (the
+// access_requests_invite pattern): the route destructures `pool` at require time,
+// and a real pg pool would hold the event loop open long after the assertions
+// pass. Nothing here needs a database — the route under test is a pure read, and
+// this stub is also the assertion that proves it.
+const apiPath = require.resolve('../src/module-api.js');
+const realApi = require(apiPath);
+require.cache[apiPath].exports = {
+  ...realApi,
+  pool: { async query() { throw new Error('the recommendations route must not touch the database'); } },
+};
+
+const provisioning = require('../modules/provisioning/provisioning.js');
+
+const MODULES_DIR = fileURLToPath(new URL('../modules', import.meta.url));
+
+// Every module key on disk, with the manifest's `default` — the live catalog as
+// the loader discovers it (src/module-loader/loader.js scans exactly this).
+function manifestsOnDisk() {
+  const out = new Map();
+  for (const ent of fs.readdirSync(MODULES_DIR, { withFileTypes: true })) {
+    if (!ent.isDirectory()) continue;
+    const manifestPath = path.join(MODULES_DIR, ent.name, 'module.json');
+    if (!fs.existsSync(manifestPath)) continue;
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    out.set(manifest.key, manifest);
+  }
+  return out;
+}
+
+// ── the rules fire on their condition, and not otherwise ────────────────────
+
+test('an open community adds somewhere to gather to a bundle that lacks one', () => {
+  // Arrange — the research bundle is `agents` alone (ADR 0237 §4), so the rule
+  // has something to actually change.
+  const answers = { type: 'research', team_shape: 'community' };
+
+  // Act
+  const recs = recommendationsForDetails(answers);
+
+  // Assert
+  assert.deepEqual(recs.bundle.bundle, ['agents', 'discord']);
+  assert.equal(recs.bundle.adjustments.length, 1);
+  assert.equal(recs.bundle.adjustments[0].module, 'discord');
+  assert.equal(recs.bundle.adjustments[0].effect, 'add');
+  assert.equal(recs.bundle.adjustments[0].rule, 'a-community-needs-somewhere-to-gather');
+  assert.ok(recs.bundle.adjustments[0].reason.length > 0, 'an adjustment always says why');
+});
+
+test('a small team adds the shared build environment', () => {
+  // Arrange
+  const answers = { type: 'research', team_shape: 'small-team' };
+
+  // Act
+  const recs = recommendationsForDetails(answers);
+
+  // Assert
+  assert.deepEqual(recs.bundle.bundle, ['agents', 'dev-box']);
+  assert.deepEqual(recs.bundle.adjustments.map((a) => a.module), ['dev-box']);
+});
+
+test('a solo builder drops the shared build environment from the bundle', () => {
+  // Arrange — the business bundle is `agents` + `dev-box`, so the removal bites.
+  const answers = { type: 'business', team_shape: 'solo' };
+
+  // Act
+  const recs = recommendationsForDetails(answers);
+
+  // Assert
+  assert.deepEqual(recs.bundle.bundle, ['agents']);
+  assert.equal(recs.bundle.adjustments.length, 1);
+  assert.equal(recs.bundle.adjustments[0].effect, 'remove');
+  assert.equal(recs.bundle.adjustments[0].module, 'dev-box');
+});
+
+test('a rule does not fire for a team shape it does not name', () => {
+  // Arrange — `solo` removes dev-box; `community` must leave it exactly alone.
+  const answers = { type: 'business', team_shape: 'community' };
+
+  // Act
+  const recs = recommendationsForDetails(answers);
+
+  // Assert
+  assert.ok(recs.bundle.bundle.includes('dev-box'), 'the solo removal did not leak onto another shape');
+  assert.deepEqual(recs.bundle.adjustments.map((a) => a.rule), ['a-community-needs-somewhere-to-gather']);
+});
+
+test('a rule whose module the bundle already carries records no adjustment', () => {
+  // The game bundle already contains `discord`, so the community rule has nothing
+  // to change. An adjustment list is a DELTA — claiming a change that did not
+  // happen is a reason the owner cannot check against the picker in front of them.
+  // Arrange
+  const answers = { type: 'game', team_shape: 'community' };
+
+  // Act
+  const recs = recommendationsForDetails(answers);
+
+  // Assert
+  assert.deepEqual(recs.bundle.bundle, [...bundleForProjectType('game').bundle], 'the bundle is untouched');
+  assert.deepEqual(recs.bundle.adjustments, [], 'and nothing is claimed');
+});
+
+test('a removal rule whose module is absent records no adjustment', () => {
+  // Arrange — `non-profit` is `discord` alone, so solo\'s dev-box removal is a no-op.
+  const answers = { type: 'non-profit', team_shape: 'solo' };
+
+  // Act
+  const recs = recommendationsForDetails(answers);
+
+  // Assert
+  assert.deepEqual(recs.bundle.bundle, ['discord']);
+  assert.deepEqual(recs.bundle.adjustments, []);
+});
+
+test('each team shape maps to its own governance preset and invite seek', () => {
+  // Arrange
+  const expected = {
+    solo: { preset: 'owner-only', seeking: null },
+    'small-team': { preset: 'trusted-team', seeking: { kind: 'top-builders', limit: 3 } },
+    community: { preset: 'open-contribution', seeking: { kind: 'top-builders', limit: 5 } },
+  };
+
+  // Act + Assert
+  for (const [shape, want] of Object.entries(expected)) {
+    const recs = recommendationsForDetails({ type: 'not-sure', team_shape: shape });
+    assert.equal(recs.governance.preset, want.preset, `${shape} → ${want.preset}`);
+    assert.deepEqual(recs.invites.seeking, want.seeking, `${shape} → its own invite seek`);
+    assert.ok(recs.governance.reason.length > 0, 'the preset always says why it was picked');
+  }
+});
+
+// ── skipping the interview, and answers that are not answers ────────────────
+
+test('skipping the interview returns the type bundle unchanged, the narrowest governance and no invites', () => {
+  // Arrange — a declared type but no interview answer at all: the supported path
+  // (ADR 0182 D4), not a gap.
+  const answers = { type: 'game' };
+
+  // Act
+  const recs = recommendationsForDetails(answers);
+
+  // Assert
+  assert.equal(recs.teamShape, null);
+  assert.equal(recs.tailored, false, 'nothing here came from an answer the owner gave');
+  assert.deepEqual(recs.bundle.bundle, [...bundleForProjectType('game').bundle]);
+  assert.deepEqual(recs.bundle.adjustments, []);
+  assert.equal(recs.governance.preset, GOVERNANCE_DEFAULT.preset);
+  assert.equal(recs.governance.reason, GOVERNANCE_DEFAULT.reason);
+  assert.deepEqual(recs.invites.suggested, []);
+  assert.equal(recs.invites.seeking, null);
+  assert.equal(recs.invites.reason, INVITE_DEFAULT.reason);
+});
+
+test('answering the interview marks the recommendation tailored', () => {
+  // Arrange + Act
+  const answered = recommendationsForDetails({ type: 'game', team_shape: 'solo' });
+  const skipped = recommendationsForDetails({ type: 'game' });
+
+  // Assert — the machine-readable half of criterion `proj-detail-interview`.
+  assert.equal(answered.tailored, true);
+  assert.equal(skipped.tailored, false);
+});
+
+test('an off-vocabulary team shape is read as no answer, not as a new rule', () => {
+  // A value that was never in the vocabulary — or has since left it — must land
+  // on the defaults, exactly as normalizeProjectDetail drops it on the way in.
+  // Inventing an answer nobody gave is the failure this file exists to prevent.
+  for (const shape of [null, undefined, '', 'guild', 'SOLO', 'small team', 42, {}, ['solo']]) {
+    // Act
+    const recs = recommendationsForDetails({ type: 'business', team_shape: shape });
+
+    // Assert
+    assert.equal(recs.teamShape, null, `${JSON.stringify(shape)} → no answer`);
+    assert.equal(recs.tailored, false);
+    assert.deepEqual(recs.bundle.adjustments, [], 'no rule fires on a value nobody chose');
+    assert.equal(recs.governance.preset, GOVERNANCE_DEFAULT.preset);
+  }
+});
+
+test('a call with no answers at all recommends the always-on core and nothing else', () => {
+  // Act — the signed-out wizard's very first ask, before any question is answered.
+  for (const input of [undefined, null, {}, 'nonsense', []]) {
+    const recs = recommendationsForDetails(input);
+
+    // Assert
+    assert.equal(recs.type, null, 'never guesses a type');
+    assert.deepEqual(recs.bundle.bundle, [], 'nothing is preselected on a guess');
+    assert.deepEqual(recs.bundle.modules, [...ALWAYS_ON_CORE]);
+    assert.equal(recs.governance.preset, GOVERNANCE_DEFAULT.preset);
+    assert.equal(recs.invites.seeking, null);
+  }
+});
+
+test('an unknown project type recommends the core, even when the interview was answered', () => {
+  // Arrange — the stale seeded vocabulary (ADR 0237 §2) is the realistic caller.
+  const answers = { type: 'saas-tool', team_shape: 'community' };
+
+  // Act
+  const recs = recommendationsForDetails(answers);
+
+  // Assert — the type is refused, but the ANSWER the owner actually gave still counts.
+  assert.equal(recs.type, null);
+  assert.equal(recs.teamShape, 'community');
+  assert.deepEqual(recs.bundle.bundle, ['discord'], 'the community rule applies to an empty bundle');
+  assert.equal(recs.governance.preset, 'open-contribution');
+});
+
+// ── the recommendation is a preview, and the invites are a seam ─────────────
+
+test('governance is a named preview and is never applied', () => {
+  // The governance module is planned and unbuilt (goal 1000030), which criterion
+  // `proj-governance-reco` states outright. Flip this pin when R25 (task 1002344)
+  // fits the presets to the real module.
+  for (const shape of [...provisioning.PROJECT_DETAIL_VOCAB.team_shape, null]) {
+    // Act
+    const recs = recommendationsForDetails({ type: 'game', team_shape: shape });
+
+    // Assert
+    assert.equal(recs.governance.applied, false, 'a recommendation, never a setting');
+    assert.ok(recs.governance.label, 'carries owner-facing copy');
+    assert.ok(recs.governance.preview, 'and one sentence of what it feels like');
+  }
+});
+
+test('invites are a seam: the suggested list is empty and the seek says what to look for', () => {
+  // Ranking builders means querying the leaderboard, which lives in the `economy`
+  // module this pure file may not import (the one-way rule, ADR 0083). R28 (task
+  // 1002347) owns the lookup; the engine only states what it should look for.
+  // Arrange
+  const answers = { type: 'business', team_shape: 'small-team' };
+
+  // Act
+  const recs = recommendationsForDetails(answers);
+
+  // Assert
+  assert.deepEqual(recs.invites.suggested, []);
+  assert.equal(recs.invites.seeking.kind, 'top-builders');
+  assert.equal(typeof recs.invites.seeking.limit, 'number');
+  assert.ok(recs.invites.reason.length > 0);
+});
+
+test('a caller may mutate the result without corrupting the declaration', () => {
+  // Arrange
+  const first = recommendationsForDetails({ type: 'game', team_shape: 'small-team' });
+
+  // Act — the picker sorts and splices what it is handed.
+  first.bundle.bundle.push('not-a-module');
+  first.bundle.modules.length = 0;
+  first.invites.seeking.limit = 999;
+
+  // Assert
+  const second = recommendationsForDetails({ type: 'game', team_shape: 'small-team' });
+  assert.deepEqual(second.bundle.bundle, ['dev-box', 'discord']);
+  assert.deepEqual(second.bundle.modules, [...ALWAYS_ON_CORE, 'dev-box', 'discord']);
+  assert.equal(second.invites.seeking.limit, 3);
+});
+
+// ── table integrity ─────────────────────────────────────────────────────────
+
+test('every module a rule names is a real opt-in module in the catalog', () => {
+  // Arrange
+  const manifests = manifestsOnDisk();
+
+  // Act + Assert
+  for (const rule of TEAM_SHAPE_RULES) {
+    const manifest = manifests.get(rule.module);
+    assert.ok(manifest, `rule ${rule.id} names '${rule.module}', which is not a module on disk`);
+    assert.notEqual(manifest.default, true, `rule ${rule.id} names always-on '${rule.module}' — a toggle that toggles nothing`);
+    assert.ok(!ALWAYS_ON_CORE.includes(rule.module), `rule ${rule.id} names a core module`);
+    assert.ok(!HUB_ONLY_MODULES.includes(rule.module), `rule ${rule.id} names hub-only '${rule.module}'`);
+  }
+});
+
+test('every team shape the interview can return has a governance rule and an invite rule', () => {
+  // Arrange — the interview's own vocabulary is the source of truth. A fourth
+  // answer added there must not be silently unhandled here.
+  const vocab = provisioning.PROJECT_DETAIL_VOCAB.team_shape;
+
+  // Act + Assert
+  for (const shape of vocab) {
+    assert.ok(GOVERNANCE_RULES.some((r) => r.teamShape === shape), `no governance rule for '${shape}'`);
+    assert.ok(INVITE_RULES.some((r) => r.teamShape === shape), `no invite rule for '${shape}'`);
+  }
+  for (const rule of [...TEAM_SHAPE_RULES, ...GOVERNANCE_RULES, ...INVITE_RULES]) {
+    assert.ok(vocab.includes(rule.teamShape), `a rule names '${rule.teamShape}', which the interview cannot return`);
+  }
+});
+
+test('every governance rule names a preset that exists, and the default does too', () => {
+  // Act + Assert
+  for (const rule of [...GOVERNANCE_RULES, GOVERNANCE_DEFAULT]) {
+    const preset = GOVERNANCE_PRESETS[rule.preset];
+    assert.ok(preset, `no preset '${rule.preset}'`);
+    assert.ok(preset.label && preset.preview, `preset '${rule.preset}' is missing owner-facing copy`);
+  }
+});
+
+test('the rule tables carry exactly one row per shape, so no rule can shadow another', () => {
+  // Act + Assert — GOVERNANCE_RULES and INVITE_RULES are resolved by `find`, so a
+  // duplicate row would be dead code that reads as live.
+  for (const [name, table] of [['governance', GOVERNANCE_RULES], ['invite', INVITE_RULES]]) {
+    const shapes = table.map((r) => r.teamShape);
+    assert.equal(new Set(shapes).size, shapes.length, `duplicate team shape in the ${name} table`);
+  }
+  const ruleIds = TEAM_SHAPE_RULES.map((r) => r.id);
+  assert.equal(new Set(ruleIds).size, ruleIds.length, 'duplicate bundle rule id');
+});
+
+// ── the read surface ────────────────────────────────────────────────────────
+
+// Mount the real router. The route under test is a pure read, so it needs no
+// session gate and no res.fail helper — which is itself the point of the
+// assertions below.
+const express = require('express');
+const buildProvisioningRouter = require('../modules/provisioning/routes/provisioning.js');
+const app = express();
+app.use('/api/bongos', buildProvisioningRouter());
+
+let server;
+let port;
+before(async () => {
+  server = http.createServer(app);
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  port = server.address().port;
+});
+after(async () => { await new Promise((resolve) => server.close(resolve)); });
+
+function get(pathname) {
+  return new Promise((resolve, reject) => {
+    http.get({ host: '127.0.0.1', port, path: pathname }, (res) => {
+      let body = '';
+      res.on('data', (c) => { body += c; });
+      res.on('end', () => {
+        let parsed = null;
+        try { parsed = JSON.parse(body); } catch { /* non-JSON */ }
+        resolve({ status: res.statusCode, body: parsed, raw: body });
+      });
+    }).on('error', reject);
+  });
+}
+
+test('GET /provisioning/recommendations is public and answers with no session', async () => {
+  // Act
+  const res = await get('/api/bongos/provisioning/recommendations?type=game&team_shape=community');
+
+  // Assert
+  assert.equal(res.status, 200, `readable with no session (got ${res.status} ${res.raw})`);
+  const recs = res.body.recommendations;
+  assert.equal(recs.type, 'game');
+  assert.equal(recs.teamShape, 'community');
+  assert.equal(recs.tailored, true);
+  assert.ok(Array.isArray(recs.bundle.modules));
+  assert.ok(recs.governance.preset);
+  assert.ok(Array.isArray(recs.invites.suggested));
+});
+
+test('the route serves exactly what the engine returns', async () => {
+  // Arrange
+  const expected = recommendationsForDetails({ type: 'business', team_shape: 'solo' });
+
+  // Act
+  const res = await get('/api/bongos/provisioning/recommendations?type=business&team_shape=solo');
+
+  // Assert
+  assert.deepEqual(res.body.recommendations, expected, 'a script and the wizard read one answer');
+});
+
+test('the route reads the same bundle shape the starter-bundles route serves', async () => {
+  // ADR 0237 §5's promise: a recommendation and a preselect can never name
+  // different modules, because both resolve through bundleForProjectType.
+  // Act
+  const [bundles, recs] = await Promise.all([
+    get('/api/bongos/provisioning/starter-bundles'),
+    get('/api/bongos/provisioning/recommendations?type=research'),
+  ]);
+
+  // Assert — no interview answer, so the recommendation IS the preselect.
+  const preset = bundles.body.bundles.find((b) => b.type === 'research');
+  const recommended = recs.body.recommendations.bundle;
+  assert.deepEqual(recommended.core, preset.core);
+  assert.deepEqual(recommended.bundle, preset.bundle);
+  assert.deepEqual(recommended.modules, preset.modules);
+  assert.equal(recommended.label, preset.label);
+});
+
+test('the route answers the defaults for missing or unusable query values', async () => {
+  // Act + Assert — an owner who skipped the step must get a 200 with the
+  // defaults, never a 400: skipping is a supported answer (ADR 0182 D4).
+  for (const query of ['', '?type=', '?team_shape=guild', '?type=saas-tool', '?type[]=game&team_shape[]=solo']) {
+    const res = await get(`/api/bongos/provisioning/recommendations${query}`);
+    assert.equal(res.status, 200, `${query || '(no query)'} → 200, got ${res.status} ${res.raw}`);
+    assert.ok(res.body.recommendations, 'and a recommendation, not an error envelope');
+  }
+});

package/tests/provisioning_settings.mjs

@@ -164,11 +164,14 @@ await ta('owner reads DEFAULTS (public / apply) on a row with empty settings —
   reset();
   const r = await get('/provisioning/instances/18/settings');
   assert.equal(r.status, 200, r.raw);
-  assert.deepEqual(r.body.settings, { platform_visibility: 'public', joinability: 'apply' });
+  assert.deepEqual(r.body.settings, { platform_visibility: 'public', joinability: 'apply', visibility: 'public' });
   // the planet rides beside the settings (task 1003347): no default — null = the platform's own pick
   assert.deepEqual(r.body.planet, { planet_template: null, planet_accent: null, card_backdrop: null });
   assert.deepEqual(r.body.options, {
     platform_visibility: ['public', 'gated'], joinability: ['open', 'apply', 'invite_only'],
+    // the join door (task 1002324, ADR 0182 D1) — the third policy axis, offered
+    // to the form the same way as its two neighbours
+    visibility: ['public', 'private', 'stealth'],
     planet_template: [...provisioning.PLANET_TEMPLATES], planet_accent: ['sea', 'terracotta', 'gold-soft', 'sun-lit', 'accent'],
     // the card's backdrop (task 1003352) is the same kind of key: platform-drawn,
     // closed list, no default, no push — so it rides the same vocab
@@ -181,14 +184,14 @@ await ta('a stored planet reads back; a name that left the vocabulary reads null
   const r = await get('/provisioning/instances/18/settings');
   assert.equal(r.status, 200, r.raw);
   assert.deepEqual(r.body.planet, { planet_template: 'bead-obsidian-tint', planet_accent: null, card_backdrop: null });
-  assert.deepEqual(r.body.settings, { platform_visibility: 'public', joinability: 'apply' }, 'the planet is not a setting: the policy read is untouched');
+  assert.deepEqual(r.body.settings, { platform_visibility: 'public', joinability: 'apply', visibility: 'public' }, 'the planet is not a setting: the policy read is untouched');
 });
 
 await ta('stored keys overlay the defaults', async () => {
   reset({ inst: { owner_builder_id: 7, slug: 'spike', status: 'active', settings: { joinability: 'invite_only' } } });
   const r = await get('/provisioning/instances/18/settings');
   assert.equal(r.status, 200, r.raw);
-  assert.deepEqual(r.body.settings, { platform_visibility: 'public', joinability: 'invite_only' });
+  assert.deepEqual(r.body.settings, { platform_visibility: 'public', joinability: 'invite_only', visibility: 'public' });
 });
 
 await ta('ANOTHER builder\'s GET → 404 (no existence leak)', async () => {
@@ -216,7 +219,7 @@ await ta('owner changes one key — merged, returned effective, audited api:self
   reset();
   const r = await patch('/provisioning/instances/18/settings', { joinability: 'open' });
   assert.equal(r.status, 200, r.raw);
-  assert.deepEqual(r.body.saved, { platform_visibility: 'public', joinability: 'open' }, 'the SAVED value — the response never claims the instance runs it (task 1003140)');
+  assert.deepEqual(r.body.saved, { platform_visibility: 'public', joinability: 'open', visibility: 'public' }, 'the SAVED value — the response never claims the instance runs it (task 1003140)');
   assert.equal(r.body.push.queued, true, 'an active co-tenant gets the live push (task 1003140)');
   assert.deepEqual(updateCalls, [{ id: 18, patch: { joinability: 'open' } }], 'exactly the sent key, nothing else');
   assert.equal(events.length, 1);
@@ -229,7 +232,7 @@ await ta('owner changes both keys in one call', async () => {
   reset();
   const r = await patch('/provisioning/instances/18/settings', { platform_visibility: 'gated', joinability: 'invite_only' });
   assert.equal(r.status, 200, r.raw);
-  assert.deepEqual(r.body.saved, { platform_visibility: 'gated', joinability: 'invite_only' });
+  assert.deepEqual(r.body.saved, { platform_visibility: 'gated', joinability: 'invite_only', visibility: 'public' });
 });
 
 await ta('the OWN-SCOPE WALL: another builder\'s PATCH → 404 and the write path is never reached', async () => {
@@ -257,6 +260,62 @@ await ta('an off-vocabulary value → 400 validation_failed (nothing written)',
   assert.equal(updateCalls.length, 0);
 });
 
+// ── the join door (BV1.R05, task 1002324) ────────────────────────────────────
+// ADR 0182 D1's STORED axis — Public / Private / Stealth — reaching the owner on
+// the same own-scoped channel as its two neighbours. What these pin: the server,
+// not the form, decides a value is legal; a fourth state cannot be picked because
+// dark matter is DERIVED (D2); and the door is a POLICY, so it rides the push.
+console.log('\nPATCH /provisioning/instances/:id/settings — the join door (task 1002324):');
+
+await ta('the owner sets the door to stealth — stored, echoed effective, audited, and pushed like the policy it is', async () => {
+  reset();
+  const r = await patch('/provisioning/instances/18/settings', { visibility: 'stealth' });
+  assert.equal(r.status, 200, r.raw);
+  assert.deepEqual(r.body.saved, { platform_visibility: 'public', joinability: 'apply', visibility: 'stealth' });
+  assert.deepEqual(updateCalls, [{ id: 18, patch: { visibility: 'stealth' } }], 'exactly the sent key, nothing else');
+  assert.equal(events[0].actor, 'api:self');
+  assert.match(events[0].detail, /visibility=stealth/);
+  // ADR 0182 D6 makes the door the CEILING joinability may only narrow, and D1/D5
+  // put that authority on the instance — so it must ride web.env + the restart,
+  // not the planet's draw-only channel.
+  assert.equal(r.body.push.queued, true, 'the door is a policy the instance obeys — it pushes');
+  assert.equal(r.body.push.restart, true, 'and a restart is what applies it');
+});
+
+await ta('each of the three states is accepted', async () => {
+  for (const value of ['public', 'private', 'stealth']) {
+    reset({ inst: { owner_builder_id: 7, slug: 'spike', status: 'active', hosting_shape: 'co-tenant', settings: { visibility: value === 'public' ? 'stealth' : 'public' } } });
+    const r = await patch('/provisioning/instances/18/settings', { visibility: value });
+    assert.equal(r.status, 200, `${value}: ${r.raw}`);
+    assert.equal(r.body.saved.visibility, value);
+  }
+});
+
+await ta('a fourth state is refused server-side — dark matter is DERIVED, never picked (ADR 0182 D2)', async () => {
+  for (const bogus of ['unlisted', 'dark-matter', 'gated', 'hidden', '']) {
+    reset();
+    const r = await patch('/provisioning/instances/18/settings', { visibility: bogus });
+    assert.equal(r.status, 400, `${JSON.stringify(bogus)} must be refused: ${r.raw}`);
+    assert.equal(r.body.error.code, 'validation_failed');
+    assert.equal(updateCalls.length, 0, 'nothing written on a refused value');
+  }
+});
+
+await ta('the OWN-SCOPE WALL holds for the door: another builder\'s PATCH → 404, nothing written', async () => {
+  reset({ as: { id: 8, github_login: 'stranger', rank: 'thetes' } });
+  const r = await patch('/provisioning/instances/18/settings', { visibility: 'private' });
+  assert.equal(r.status, 404, r.raw);
+  assert.equal(r.body.error.code, 'instance_not_found', 'no existence leak');
+  assert.equal(updateCalls.length, 0);
+  assert.equal(events.length, 0);
+});
+
+await ta('an unknown project → 404 for the door too, archon included', async () => {
+  reset({ inst: null, as: { id: 999, github_login: 'archon', rank: 'archon' } });
+  const r = await patch('/provisioning/instances/999/settings', { visibility: 'private' });
+  assert.equal(r.status, 404, r.raw);
+});
+
 await ta('an unknown key → 400 (strict: a typo fails loudly, never silently dropped)', async () => {
   reset();
   const r = await patch('/provisioning/instances/18/settings', { joinabilty: 'open' });
@@ -272,7 +331,7 @@ await ta('the owner picks a planet: saved, echoed as `planet`, audited — and N
   const r = await patch('/provisioning/instances/18/settings', { planet_template: 'bead-obsidian-tint', planet_accent: 'sea' });
   assert.equal(r.status, 200, r.raw);
   assert.deepEqual(r.body.planet, { planet_template: 'bead-obsidian-tint', planet_accent: 'sea', card_backdrop: null });
-  assert.deepEqual(r.body.saved, { platform_visibility: 'public', joinability: 'apply' }, 'the policy half is untouched');
+  assert.deepEqual(r.body.saved, { platform_visibility: 'public', joinability: 'apply', visibility: 'public' }, 'the policy half is untouched');
   assert.deepEqual(updateCalls, [{ id: 18, patch: { planet_template: 'bead-obsidian-tint', planet_accent: 'sea' } }]);
   assert.equal(r.body.push.queued, false);
   assert.equal(r.body.push.restart, false, 'an active co-tenant would get a push for a POLICY change — never for the planet');

package/tests/provisioning_settings_apply.mjs

@@ -212,7 +212,7 @@ await ta('ACTIVE standalone: the row is written FIRST, then a settings-apply int
   reset();
   const r = await patch('/provisioning/instances/18/settings', { platform_visibility: 'gated' });
   assert.equal(r.status, 200, r.raw);
-  assert.deepEqual(r.body.saved, { platform_visibility: 'gated', joinability: 'apply' }, 'the SAVED (requested) value — never `settings`, which a form would render as live');
+  assert.deepEqual(r.body.saved, { platform_visibility: 'gated', joinability: 'apply', visibility: 'public' }, 'the SAVED (requested) value — never `settings`, which a form would render as live');
   assert.equal(r.body.settings, undefined);
   assert.deepEqual(updateCalls.map((c) => c.patch), [{ platform_visibility: 'gated' }]);
   assert.equal(updateCalls[0].enqueuedSoFar, 0, 'the runner reads the row — the write must precede the intent');
@@ -261,7 +261,7 @@ await ta('an enqueue that THROWS still answers 200 "saved" — never a 500 that
   enqueueThrows = new Error('db down');
   const r = await patch('/provisioning/instances/18/settings', { joinability: 'open' });
   assert.equal(r.status, 200, r.raw);
-  assert.deepEqual(r.body.saved, { platform_visibility: 'public', joinability: 'open' });
+  assert.deepEqual(r.body.saved, { platform_visibility: 'public', joinability: 'open', visibility: 'public' });
   assert.equal(updateCalls.length, 1, 'the write landed');
   receiptShape(r.body.push, { queued: false, restart: true, reachable: true });
   assert.match(r.body.push.message, /Saved, but the restart could not be queued/);
@@ -274,7 +274,7 @@ await ta('same values as already stored → no write, no event, no intent, "No c
   reset({ inst: { ...ACTIVE, settings: { platform_visibility: 'gated', joinability: 'open' } } });
   const r = await patch('/provisioning/instances/18/settings', { platform_visibility: 'gated', joinability: 'open' });
   assert.equal(r.status, 200, r.raw);
-  assert.deepEqual(r.body.saved, { platform_visibility: 'gated', joinability: 'open' });
+  assert.deepEqual(r.body.saved, { platform_visibility: 'gated', joinability: 'open', visibility: 'public' });
   assert.equal(updateCalls.length, 0, 'nothing written (no updated_at reshuffle)');
   assert.equal(events.length, 0, 'no "settings changed" event for a change that is not one');
   assert.equal(enqueueCalls.length, 0, 'a whole-form save must not bounce a live project');

package/tests/provisioning_settings_env.mjs

@@ -55,7 +55,9 @@ t('a row with NO stored settings emits today\'s behavior EXPLICITLY, never nothi
   // an instance must never have to infer a policy from an absent variable
   assert.equal(v.CLOUDBONGOS_PLATFORM_VISIBILITY, 'public');
   assert.equal(v.CLOUDBONGOS_JOINABILITY, 'apply');
-  assert.equal(linesOf(provisioning.settingsEnvLines({}, 'X')).length, 2, 'both keys always present');
+  // the join door rides the same transport (task 1002324, ADR 0182 D1)
+  assert.equal(v.CLOUDBONGOS_VISIBILITY, 'public');
+  assert.equal(linesOf(provisioning.settingsEnvLines({}, 'X')).length, 3, 'every policy key always present');
 });
 
 t('an off-vocabulary stored value falls back to the default, never reaches the instance', () => {
@@ -94,11 +96,11 @@ t('it names the live push by the intent the runner actually dispatches (task 100
 });
 
 t('settingsEnvVars is the single source both legs derive from — same keys, same values as the lines', () => {
-  const row = { settings: { platform_visibility: 'gated', joinability: 'open' } };
+  const row = { settings: { platform_visibility: 'gated', joinability: 'open', visibility: 'stealth' } };
   const vars = provisioning.settingsEnvVars(row, 'CLOUDBONGOS');
-  assert.deepEqual(vars, { CLOUDBONGOS_PLATFORM_VISIBILITY: 'gated', CLOUDBONGOS_JOINABILITY: 'open' });
+  assert.deepEqual(vars, { CLOUDBONGOS_PLATFORM_VISIBILITY: 'gated', CLOUDBONGOS_JOINABILITY: 'open', CLOUDBONGOS_VISIBILITY: 'stealth' });
   assert.deepEqual(varsOf(provisioning.settingsEnvLines(row, 'CLOUDBONGOS')), vars, 'the standup lines ARE the vars');
-  assert.deepEqual(provisioning.settingsEnvVars({}, 'X'), { X_PLATFORM_VISIBILITY: 'public', X_JOINABILITY: 'apply' }, 'defaults, explicitly');
+  assert.deepEqual(provisioning.settingsEnvVars({}, 'X'), { X_PLATFORM_VISIBILITY: 'public', X_JOINABILITY: 'apply', X_VISIBILITY: 'public' }, 'defaults, explicitly');
 });
 
 console.log('\nwebEnvBody — the settings ride the real per-instance env file:');
@@ -131,12 +133,12 @@ t('clientBranding\'s project fallbacks are DEFAULT_SETTINGS, key for key — the
 
 t('the env override resolves onto project.* in a real process', () => {
   const read = (env) => JSON.parse(execFileSync(process.execPath, ['-e',
-    "const b=require('./src/branding.js');const r=(b.branding||b)();console.log(JSON.stringify({v:r.project.platformVisibility,j:r.project.joinability}))"],
+    "const b=require('./src/branding.js');const r=(b.branding||b)();console.log(JSON.stringify({v:r.project.platformVisibility,j:r.project.joinability,d:r.project.visibility}))"],
     { cwd: ROOT, encoding: 'utf8', env: { ...process.env, ...env } }));
-  assert.deepEqual(read({}), { v: 'public', j: 'apply' }, 'no env → the pack default');
+  assert.deepEqual(read({}), { v: 'public', j: 'apply', d: 'public' }, 'no env → the pack default');
   assert.deepEqual(
-    read({ CLOUDBONGOS_PLATFORM_VISIBILITY: 'gated', CLOUDBONGOS_JOINABILITY: 'invite_only' }),
-    { v: 'gated', j: 'invite_only' },
+    read({ CLOUDBONGOS_PLATFORM_VISIBILITY: 'gated', CLOUDBONGOS_JOINABILITY: 'invite_only', CLOUDBONGOS_VISIBILITY: 'stealth' }),
+    { v: 'gated', j: 'invite_only', d: 'stealth' },
     'the web.env the runner writes is what the instance reads');
 });