@bongos/core 1.19.355 → 1.19.357

package/tests/provisioning_settings_apply.mjs

@@ -0,0 +1,372 @@
+// tests/provisioning_settings_apply.mjs
+//
+// The LIVE-PUSH half of the platform->instance settings channel (task 1003140,
+// goal 1000058). Task 1003139 made a NEW instance read platform_visibility /
+// joinability from the web.env the runner writes; this is the part that makes
+// CHANGING one on an already-running instance take effect: PATCH /settings now
+// enqueues a 'settings-apply' intent for an ACTIVE instance, and the runner
+// patches the instance's web.env in place + restarts it.
+//
+// Covers (the task's done-when, web-tier side):
+//   • the ENQUEUE — an active co-tenant / standalone instance queues 'settings-apply'
+//     AFTER the row is written (the runner reads the row, so the write must come first)
+//   • a save that changes NOTHING writes nothing and restarts nothing — unless it is
+//     the owner re-kick after a retired push (error_note), the domain route's F19 shape
+//   • the STATE GATE — pre-active / snagged / offline states store the value, queue
+//     nothing, and say plainly when it takes effect
+//   • the SHAPE REFUSAL — a dedicated droplet is refused honestly (stored, no push)
+//   • the open-slot arbitration — foreign intent → 409 intent_conflict with
+//     recorded:true; an identical PENDING push is idempotent; a RUNNING one conflicts;
+//     an enqueue that THROWS still answers "saved" (never a 500 denying the write)
+//   • the response is a RECEIPT: `saved` + `push` {queued, restart, reachable, message}
+//     on every branch — it says the restart happens, never that the value is live,
+//     with no wall-clock or duration promises (the F16 rule)
+//   • INTENT_ACTIONS ↔ migration provisioning_010 lockstep; a pending push is
+//     superseded by a teardown (the 1002691 class)
+//
+// DB-free: data-access fns are stubbed on the cached module object (the
+// provisioning_domain_attach.mjs pattern). No network beyond localhost.
+//
+// Run:  node tests/provisioning_settings_apply.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import http from 'node:http';
+
+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}`); }
+}
+
+// No wall-clock or duration promise anywhere a receipt is rendered (F16).
+const PROMISE = /shortly|briefly|minute|second|soon\b/i;
+
+console.log('the module slice — constants, the migration, the enqueue classifier:');
+
+t("INTENT_ACTIONS includes 'settings-apply' (lockstep with the provisioning_010 CHECK)", () => {
+  assert.ok(provisioning.INTENT_ACTIONS.includes('settings-apply'));
+  const sql = readFileSync(new URL('../modules/provisioning/migrations/provisioning_010_settings_apply.sql', import.meta.url), 'utf8');
+  const m = /CHECK \(action IN \(([^)]*)\)\)/.exec(sql);
+  assert.ok(m, 'the migration widens the action CHECK');
+  const inSql = m[1].split(',').map((s) => s.trim().replace(/^'|'$/g, '')).sort();
+  assert.deepEqual(inSql, [...provisioning.INTENT_ACTIONS].sort(), 'the CHECK and INTENT_ACTIONS carry the same set');
+  assert.match(sql, /INSERT INTO schema_migrations \(version\) VALUES \('provisioning_010_settings_apply'\)/, 'self-registers');
+});
+
+t('SETTINGS_APPLY_FROM is exactly {active} — the provision intent cannot stand in (PROVISION_ENQUEUE_FROM excludes active)', () => {
+  assert.deepEqual([...provisioning.SETTINGS_APPLY_FROM], ['active']);
+  assert.ok(!provisioning.PROVISION_ENQUEUE_FROM.has('active'), 'the premise the gate rests on');
+});
+
+t('SETTINGS_APPLY_SHAPES is the reachable pair — dedicated is out, and the set is a subset of HOSTING_SHAPES', () => {
+  assert.deepEqual([...provisioning.SETTINGS_APPLY_SHAPES].sort(), ['co-tenant', 'standalone']);
+  for (const s of provisioning.SETTINGS_APPLY_SHAPES) assert.ok(provisioning.HOSTING_SHAPES.includes(s), s);
+  assert.ok(!provisioning.SETTINGS_APPLY_SHAPES.has('dedicated'));
+});
+
+await ta('enqueueSettingsApply: a fresh intent → created:true; the INSERT carries the settings-apply action', async () => {
+  const calls = [];
+  const db = { query: async (sql, params) => { calls.push({ sql, params }); return { rows: [{ id: 1, action: params[1], state: 'pending' }] }; } };
+  const r = await provisioning.enqueueSettingsApply(db, 18, 'api:self');
+  assert.equal(r.created, true);
+  assert.equal(r.conflict, undefined);
+  assert.match(calls[0].sql, /INSERT INTO provisioning_intents/);
+  assert.deepEqual(calls[0].params, [18, 'settings-apply', 'api:self']);
+});
+
+await ta('enqueueSettingsApply: an identical PENDING push already open → created:false, no conflict (it carries this change)', async () => {
+  const db = { query: async (sql) => {
+    if (/INSERT/.test(sql)) { const e = new Error('dup'); e.code = '23505'; throw e; }
+    return { rows: [{ id: 5, action: 'settings-apply', state: 'pending' }] };
+  } };
+  const r = await provisioning.enqueueSettingsApply(db, 18, 'api:self');
+  assert.equal(r.created, false);
+  assert.equal(r.conflict, undefined);
+  assert.equal(r.intent.id, 5);
+});
+
+await ta('enqueueSettingsApply: a RUNNING push, or any other action holding the slot → conflict (it may have read the row already)', async () => {
+  for (const open of [{ action: 'settings-apply', state: 'running' }, { action: 'teardown', state: 'pending' }, { action: 'domain-attach', state: 'running' }]) {
+    const db = { query: async (sql) => {
+      if (/INSERT/.test(sql)) { const e = new Error('dup'); e.code = '23505'; throw e; }
+      return { rows: [{ id: 5, ...open }] };
+    } };
+    const r = await provisioning.enqueueSettingsApply(db, 18, 'api:self');
+    assert.equal(r.created, false, JSON.stringify(open));
+    assert.equal(r.conflict, 'open_intent', JSON.stringify(open));
+    assert.equal(r.intent.action, open.action, 'names the real blocker');
+  }
+});
+
+await ta('enqueueTeardown supersedes a PENDING settings push (a push into a project about to be torn down is dead work — the 1002691 class)', async () => {
+  const calls = [];
+  const db = { query: async (sql, params) => {
+    calls.push(sql);
+    if (/UPDATE provisioning_intents/.test(sql)) return { rows: [{ id: 5 }] };
+    return { rows: [{ id: 6, action: 'teardown', state: 'pending', instance_id: params[0] }] };
+  } };
+  const r = await provisioning.enqueueTeardown(db, 18, 'api:self');
+  assert.equal(r.created, true);
+  assert.equal(r.superseded, true, 'the queued push was cancelled so the teardown could take the slot');
+  assert.match(calls[0], /action IN \('provision', 'settings-apply'\) AND state = 'pending'/, 'pending-only, and only the two supersedable actions');
+});
+
+// ── the route, over a real mounted router (stubbed data access) ─────────────────
+let instance = null;
+let updateCalls = [];
+let enqueueCalls = [];
+let enqueueResult = null;      // what enqueueSettingsApply reports (null → created:true)
+let enqueueThrows = null;      // an Error to throw from enqueueSettingsApply
+let events = [];
+provisioning.getInstanceById = async (_db, id) => (instance ? { ...instance, id } : null);
+provisioning.updateInstanceSettings = async (_db, id, patch) => {
+  updateCalls.push({ id, patch, enqueuedSoFar: enqueueCalls.length });
+  instance = { ...instance, settings: { ...(instance.settings || {}), ...patch } };
+  return { ...instance, id };
+};
+provisioning.enqueueSettingsApply = async (_db, id, requestedBy) => {
+  enqueueCalls.push({ id, requestedBy });
+  if (enqueueThrows) throw enqueueThrows;
+  return enqueueResult || { intent: { id: 9, action: 'settings-apply', state: 'pending' }, created: true };
+};
+provisioning.recordEvent = async (_db, e) => { events.push(e); };
+provisioning.getOpenIntent = async () => null;
+provisioning.getLatestOAuthManifestForInstance = async () => null;
+
+const api = require('../src/module-api.js');
+let builder = { id: 7, github_login: 'owner', rank: 'thetes' };
+api.requireBuilder = (req, _res, next) => { req.builder = builder; next(); };
+api.requirePermission = () => (_req, _res, next) => next();
+api.branding = () => ({ domains: { publicOrigin: 'https://cb.test' }, identity: { productName: 'Cloud Bongos' } });
+api.logger = () => ({ error() {}, warn() {}, info() {}, debug() {} });
+
+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 patch(path, body) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const req = http.request(`${base}${path}`, {
+      method: 'PATCH',
+      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);
+  });
+}
+
+const ACTIVE = { owner_builder_id: 7, slug: 'spike', status: 'active', hosting_shape: 'standalone', domain: 'spike.cloudbongos.com', settings: {} };
+function reset({ inst, as } = {}) {
+  instance = inst !== undefined ? inst : { ...ACTIVE };
+  builder = as || { id: 7, github_login: 'owner', rank: 'thetes' };
+  updateCalls = [];
+  enqueueCalls = [];
+  enqueueResult = null;
+  enqueueThrows = null;
+  events = [];
+}
+// every receipt carries the same four keys, and never a duration promise
+function receiptShape(push, { queued, restart, reachable }) {
+  assert.deepEqual(Object.keys(push).sort(), ['message', 'queued', 'reachable', 'restart'], 'one receipt shape on every branch');
+  assert.equal(push.queued, queued, 'queued');
+  assert.equal(push.restart, restart, 'restart');
+  assert.equal(push.reachable, reachable, 'reachable');
+  assert.doesNotMatch(push.message, PROMISE, `no wall-clock/duration promise: ${push.message}`);
+}
+
+console.log('\nPATCH /provisioning/instances/:id/settings — the enqueue:');
+
+await ta('ACTIVE standalone: the row is written FIRST, then a settings-apply intent queues; the receipt says a restart is coming', async () => {
+  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.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');
+  assert.deepEqual(enqueueCalls, [{ id: 18, requestedBy: 'api:self' }]);
+  receiptShape(r.body.push, { queued: true, restart: true, reachable: true });
+  assert.match(r.body.push.message, /restart/i, 'the surface SAYS a restart happens (owner decision 2026-08-19)');
+  assert.match(r.body.push.message, /keeps its current setting/i, 'a receipt, not a claim the value is live');
+});
+
+await ta('ACTIVE co-tenant queues too; the Archon override names WHICH archon on the event and the intent', async () => {
+  reset({ inst: { ...ACTIVE, hosting_shape: 'co-tenant', owner_builder_id: 7 }, as: { id: 999, github_login: 'archon', rank: 'archon' } });
+  const r = await patch('/provisioning/instances/18/settings', { joinability: 'open' });
+  assert.equal(r.status, 200, r.raw);
+  assert.equal(r.body.push.queued, true);
+  assert.deepEqual(enqueueCalls, [{ id: 18, requestedBy: 'api:archon:999' }], 'the force-teardown convention: api:archon:<id>');
+  assert.equal(events[0].actor, 'api:archon:999');
+});
+
+await ta('an identical PENDING push already open → 200, queued:false, "already queued … will carry this change"', async () => {
+  reset();
+  enqueueResult = { intent: { id: 5, action: 'settings-apply', state: 'pending' }, created: false };
+  const r = await patch('/provisioning/instances/18/settings', { joinability: 'invite_only' });
+  assert.equal(r.status, 200, r.raw);
+  receiptShape(r.body.push, { queued: false, restart: true, reachable: true });
+  assert.match(r.body.push.message, /already queued/i);
+  assert.equal(updateCalls.length, 1, 'the value is still saved');
+});
+
+await ta('the open slot held by OTHER work → 409 intent_conflict with recorded:true (the change IS saved)', async () => {
+  for (const open of [{ action: 'teardown', state: 'pending' }, { action: 'settings-apply', state: 'running' }]) {
+    reset();
+    enqueueResult = { intent: { id: 5, ...open }, created: false, conflict: 'open_intent' };
+    const r = await patch('/provisioning/instances/18/settings', { joinability: 'open' });
+    assert.equal(r.status, 409, `${open.action}: ${r.raw}`);
+    assert.equal(r.body.error.code, 'intent_conflict');
+    assert.equal(r.body.error.details.action, open.action, 'names the real blocker');
+    assert.equal(r.body.error.details.state, open.state);
+    assert.equal(r.body.error.details.recorded, true, 'the row was written before the slot was contested');
+    assert.match(r.body.error.message, /saved/i);
+    assert.equal(updateCalls.length, 1, `${open.action}: stored`);
+  }
+});
+
+await ta('an enqueue that THROWS still answers 200 "saved" — never a 500 that denies a durable write', async () => {
+  reset();
+  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.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/);
+  assert.match(r.body.push.message, /send it again/i, 'tells the owner the recovery');
+});
+
+console.log('\na save that changes nothing:');
+
+await ta('same values as already stored → no write, no event, no intent, "No change"', async () => {
+  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.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');
+  receiptShape(r.body.push, { queued: false, restart: false, reachable: true });
+  assert.match(r.body.push.message, /No change/);
+});
+
+await ta('the default sent explicitly on an empty row is also "no change" (effective, not stored, is what counts)', async () => {
+  reset();
+  const r = await patch('/provisioning/instances/18/settings', { joinability: 'apply' });
+  assert.equal(r.status, 200, r.raw);
+  assert.equal(updateCalls.length, 0);
+  assert.equal(enqueueCalls.length, 0);
+  assert.match(r.body.push.message, /No change/);
+});
+
+await ta('the owner re-kick: same values re-sent while a retired push left its error_note → the push re-queues, nothing re-written (F19 shape)', async () => {
+  reset({ inst: { ...ACTIVE, settings: { platform_visibility: 'gated' }, error_note: 'could not apply the settings on spike: …' } });
+  const r = await patch('/provisioning/instances/18/settings', { platform_visibility: 'gated' });
+  assert.equal(r.status, 200, r.raw);
+  assert.equal(updateCalls.length, 0, 'the value is unchanged');
+  assert.equal(events.length, 0);
+  assert.deepEqual(enqueueCalls.map((c) => c.id), [18], 'the push is re-kicked');
+  receiptShape(r.body.push, { queued: true, restart: true, reachable: true });
+});
+
+console.log('\nthe state gate — store, queue nothing, say when it takes effect:');
+
+await ta('requested / provisioning: stored, NO intent (standup writes the same values), message says so', async () => {
+  for (const status of ['requested', 'provisioning']) {
+    reset({ inst: { ...ACTIVE, status } });
+    const r = await patch('/provisioning/instances/18/settings', { platform_visibility: 'gated' });
+    assert.equal(r.status, 200, `${status}: ${r.raw}`);
+    assert.equal(updateCalls.length, 1, `${status}: stored`);
+    assert.equal(enqueueCalls.length, 0, `${status}: no push`);
+    receiptShape(r.body.push, { queued: false, restart: false, reachable: true });
+    assert.match(r.body.push.message, /standing up/i, status);
+  }
+});
+
+await ta('error (a snagged standup): stored, NO intent, and the message does not promise a standup that is not happening', async () => {
+  reset({ inst: { ...ACTIVE, status: 'error', error_note: 'DNS preflight failed' } });
+  const r = await patch('/provisioning/instances/18/settings', { platform_visibility: 'gated' });
+  assert.equal(r.status, 200, r.raw);
+  assert.equal(updateCalls.length, 1);
+  assert.equal(enqueueCalls.length, 0);
+  receiptShape(r.body.push, { queued: false, restart: false, reachable: true });
+  assert.match(r.body.push.message, /stopped partway/i);
+  assert.match(r.body.push.message, /next time the project is stood up/i);
+  assert.doesNotMatch(r.body.push.message, /finishes standing up/i, 'nothing is finishing — the card says "we stopped trying"');
+});
+
+await ta('torn_down / tearing_down: stored, NO intent (nothing to restart), message says the project is offline', async () => {
+  for (const status of ['torn_down', 'tearing_down']) {
+    reset({ inst: { ...ACTIVE, status } });
+    const r = await patch('/provisioning/instances/18/settings', { joinability: 'open' });
+    assert.equal(r.status, 200, `${status}: ${r.raw}`);
+    assert.equal(updateCalls.length, 1);
+    assert.equal(enqueueCalls.length, 0, `${status}: no push`);
+    receiptShape(r.body.push, { queued: false, restart: false, reachable: true });
+    assert.match(r.body.push.message, /offline/i, status);
+  }
+});
+
+console.log('\nthe shape refusal — a dedicated droplet is refused honestly:');
+
+await ta('ACTIVE dedicated: stored, NO intent, reachable:false, restart:true (a restart IS what applies it — just not by us), and the copy names the real difference', async () => {
+  reset({ inst: { ...ACTIVE, hosting_shape: 'dedicated' } });
+  const r = await patch('/provisioning/instances/18/settings', { platform_visibility: 'gated' });
+  assert.equal(r.status, 200, r.raw);
+  assert.equal(updateCalls.length, 1, 'the platform record is still the truth');
+  assert.equal(enqueueCalls.length, 0, 'never queue a push that cannot land');
+  receiptShape(r.body.push, { queued: false, restart: true, reachable: false });
+  assert.match(r.body.push.message, /doesn.t manage/i, 'what differs: the platform does not manage that machine');
+  assert.match(r.body.push.message, /can.t be restarted from here/i);
+  assert.doesNotMatch(r.body.push.message, /own server/i, '"its own server" is the hub\'s label for STANDALONE too — which is pushable');
+  assert.doesNotMatch(r.body.push.message, /web\.env/, 'no file the owner has never seen');
+});
+
+console.log('\nthe walls that did not move:');
+
+await ta("another builder's PATCH → 404; nothing stored, nothing queued", async () => {
+  reset({ as: { id: 8, github_login: 'stranger', rank: 'thetes' } });
+  const r = await patch('/provisioning/instances/18/settings', { joinability: 'open' });
+  assert.equal(r.status, 404, r.raw);
+  assert.equal(updateCalls.length, 0);
+  assert.equal(enqueueCalls.length, 0);
+});
+
+await ta('an off-vocabulary value → 400 before anything is written or queued', async () => {
+  reset();
+  const r = await patch('/provisioning/instances/18/settings', { joinability: 'whenever' });
+  assert.equal(r.status, 400, r.raw);
+  assert.equal(updateCalls.length, 0);
+  assert.equal(enqueueCalls.length, 0);
+});
+
+server.close();
+console.log(`\nprovisioning_settings_apply: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/provisioning_settings_env.mjs

@@ -12,11 +12,11 @@
 // branding pack, so the runner now writes them there at standup and src/branding.js
 // resolves them onto project.*.
 //
-// NOT covered here because it is NOT built: pushing a CHANGED setting to an
-// already-running instance (the branding pack is memoized + deep-frozen for the
-// process lifetime, so that needs a re-write + restart — the deferred
-// 'settings-apply' intent). These tests assert the standup leg only, and one of them
-// pins that the generated file does not CLAIM the push exists.
+// The LIVE-PUSH leg — a CHANGED setting reaching an already-running instance via
+// the 'settings-apply' intent (task 1003140) — is covered by
+// tests/provisioning_settings_apply.mjs (route + module) and
+// tests/provision_settings_apply.mjs (runner). These tests assert the standup leg,
+// and one of them pins that the generated file names the push truthfully.
 //
 // DB-free and hermetic: pure builders + a child process with env set. No network.
 //
@@ -79,11 +79,20 @@ t('every emitted key is in SETTINGS_VOCAB — the two lists cannot drift', () =>
 
 console.log('\nThe generated file tells the truth about what it is:');
 
-t('it does NOT claim a live push exists — that intent is not built', () => {
+t('it names the live push by the intent the runner actually dispatches (task 1003140)', () => {
   const s = provisioning.settingsEnvLines({}, 'X');
-  assert.doesNotMatch(s, /settings-apply/,
-    'no comment may name an intent action the runner cannot dispatch');
-  assert.match(s, /next provision run/i, 'it says when a change actually takes effect');
+  assert.match(s, /settings-apply/, 'the comment may name the intent only because INTENT_ACTIONS carries it');
+  assert.ok(provisioning.INTENT_ACTIONS.includes('settings-apply'), 'lockstep: the named action is dispatchable');
+  assert.match(s, /restarts this service/i, 'it says plainly that applying a change restarts the instance');
+  assert.doesNotMatch(s, /not built yet|next provision run/i, 'the old "not built" disclaimer is gone with the gap');
+});
+
+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 vars = provisioning.settingsEnvVars(row, 'CLOUDBONGOS');
+  assert.deepEqual(vars, { CLOUDBONGOS_PLATFORM_VISIBILITY: 'gated', CLOUDBONGOS_JOINABILITY: 'open' });
+  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');
 });
 
 console.log('\nwebEnvBody — the settings ride the real per-instance env file:');
@@ -106,6 +115,14 @@ t('the neutral pack ships today\'s behavior, so an un-pushed instance is unchang
   assert.equal(pack.project.joinability, 'apply');
 });
 
+t('clientBranding\'s project fallbacks are DEFAULT_SETTINGS, key for key — the read-back cannot drift from the platform default (task 1003140)', () => {
+  const { clientBranding } = require('../src/branding.js');
+  const published = clientBranding({}).project;
+  const camel = (k) => k.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+  for (const [k, v] of Object.entries(provisioning.DEFAULT_SETTINGS)) assert.equal(published[camel(k)], v, k);
+  assert.equal(Object.keys(published).length, Object.keys(provisioning.DEFAULT_SETTINGS).length, 'same key set');
+});
+
 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}))"],

package/tests/provisioning_teardown_intent.mjs

@@ -65,11 +65,12 @@ function fakeIntentDb(seed = []) {
       }
       if (/UPDATE provisioning_intents/.test(sql) && /state = 'error'/.test(sql)) {
         // The supersede's guard must live in the SQL itself: pending-only (a running
-        // provision is the runner's mid-flight work) and provision-only (an open
-        // teardown is left alone for the idempotent path).
-        assert.match(sql, /action = 'provision' AND state = 'pending'/);
+        // intent is the runner's mid-flight work) and provision-or-settings-push only
+        // (task 1003140 widened it: a queued push into a project about to be torn
+        // down is dead work; an open teardown is left alone for the idempotent path).
+        assert.match(sql, /action IN \('provision', 'settings-apply'\) AND state = 'pending'/);
         const hit = rows.filter((r) =>
-          String(r.instance_id) === String(params[0]) && r.action === 'provision' && r.state === 'pending');
+          String(r.instance_id) === String(params[0]) && (r.action === 'provision' || r.action === 'settings-apply') && r.state === 'pending');
         for (const r of hit) { r.state = 'error'; r.last_error = 'superseded: teardown requested'; }
         return { rows: hit.map((r) => ({ id: r.id })) };
       }

package/tests/search_index_poller.mjs

@@ -0,0 +1,161 @@
+// tests/search_index_poller.mjs — the recall index keeps itself, and says so
+// (task 1003162).
+//
+// The outage this guards: /recall returned `index_empty` on live for words that
+// demonstrably existed in the corpus, because NOTHING ran the ingesters. ADR 0060
+// claims a deploy hook and a nightly timer; both are box-side, and neither could be
+// shown to have ever run.
+//
+// Everything here is pure or dependency-injected — no database, no child process,
+// no clock. The sweep is driven with a fake pool and a fake execFile so the
+// DECISIONS are tested, not the plumbing.
+//
+// Run:  node tests/search_index_poller.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const poller = require('../modules/memory/pollers/search-index.js');
+const { describeIndex, describeIngest, sweep } = poller;
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.error(`  FAIL ${name}\n    ${err.message}`); }
+}
+
+const NOW = Date.parse('2026-08-25T12:00:00Z');
+const daysAgo = (d) => new Date(NOW - d * 86400000).toISOString();
+const quietLog = { log() {}, error() {} };
+const okExec = (_p, _a, _o, cb) => cb(null, '', '');
+
+// --- READING THE INDEX ------------------------------------------------------
+
+await test('an EMPTY index is an alarm, and says recall returns nothing AT ANY RANK', async () => {
+  const d = describeIndex({ chunks: 0, now: NOW });
+  assert.equal(d.level, 'alarm');
+  assert.equal(d.state, 'empty');
+  // Rank-independence is the whole reason `index_empty` is diagnostic: it rules
+  // out "nothing visible to YOU", which is what made the live report trustworthy.
+  assert.match(d.message, /any rank/i);
+});
+
+await test('an UNREADABLE count is an alarm — unknown is not healthy', async () => {
+  for (const bad of [NaN, undefined, null, -1, 'lots']) {
+    const d = describeIndex({ chunks: bad, now: NOW });
+    assert.equal(d.level, 'alarm', `${bad} must not read as healthy`);
+    assert.equal(d.state, 'unreadable');
+  }
+});
+
+await test('a populated, fresh index is ok and says how much it holds', async () => {
+  const d = describeIndex({ chunks: 4812, lastIngestedAt: daysAgo(1), now: NOW });
+  assert.equal(d.level, 'ok');
+  assert.match(d.message, /4812/);
+});
+
+await test('a populated but WEEK-OLD index warns — the sweep may have stopped', async () => {
+  const d = describeIndex({ chunks: 4812, lastIngestedAt: daysAgo(9), now: NOW });
+  assert.equal(d.level, 'warn');
+  assert.equal(d.state, 'stale');
+  assert.equal(d.age_days, 9);
+});
+
+await test('staleness is not guessed when nothing says when it last ran', async () => {
+  const d = describeIndex({ chunks: 10, lastIngestedAt: null, now: NOW });
+  assert.equal(d.level, 'ok', 'an unknown age must not be reported as stale');
+  assert.equal(d.age_days, null);
+});
+
+// --- READING THE INGESTERS' EXIT CODES --------------------------------------
+
+await test('a NON-ZERO exit is an alarm carrying the TAIL of stderr', async () => {
+  // Task 1002859 made a partial ingest exit non-zero and NAME every skipped
+  // source — at the end of its output. A head-clip would drop exactly that.
+  const d = describeIngest({
+    name: 'search-ingest-md', code: 1,
+    stderr: ['noise', 'noise', 'noise', 'noise', 'noise', 'noise', 'skipped: docs/adr/0060.md (NUL byte)'].join('\n'),
+  });
+  assert.equal(d.ok, false);
+  assert.equal(d.level, 'alarm');
+  assert.match(d.message, /skipped: docs\/adr\/0060\.md/, 'the last line is the one that matters');
+});
+
+await test('a KILLED ingester is reported as killed, not as a clean failure', async () => {
+  const d = describeIngest({ name: 'search-ingest-db', code: null, signal: 'SIGTERM' });
+  assert.equal(d.ok, false);
+  assert.match(d.message, /KILLED by SIGTERM/);
+  assert.match(d.message, /partially written/, 'a half-written index is the real risk');
+});
+
+await test('exit 0 is ok', async () => {
+  assert.equal(describeIngest({ name: 'x', code: 0 }).ok, true);
+});
+
+// --- THE SWEEP --------------------------------------------------------------
+
+function fakePool(seq) {
+  let i = 0;
+  return { query: async () => ({ rows: [seq[Math.min(i++, seq.length - 1)]] }) };
+}
+
+await test('the sweep runs BOTH ingesters — one failing must not skip the other', async () => {
+  const called = [];
+  const exec = (_p, args, _o, cb) => {
+    called.push(args[0].split('/').pop());
+    cb(args[0].includes('md') ? Object.assign(new Error('x'), { code: 1 }) : null, '', 'boom');
+  };
+  const r = await sweep({ pool: fakePool([{ chunks: 0, last: null }]), log: quietLog, execFileImpl: exec, now: NOW });
+  assert.deepEqual(called, ['search-ingest-md.js', 'search-ingest-db.js']);
+  assert.equal(r.results.length, 2);
+  assert.equal(r.results[0].ok, false);
+  assert.equal(r.results[1].ok, true, 'the db ingest still ran after the md ingest failed');
+});
+
+await test('the sweep reports the AFTER count — exit 0 that wrote nothing is a failure shape', async () => {
+  // The precise trap: an ingester can exit 0 and leave the table empty. Without
+  // an after-picture that reads as success.
+  const r = await sweep({
+    pool: fakePool([{ chunks: 0, last: null }, { chunks: 0, last: null }]),
+    log: quietLog, execFileImpl: okExec, now: NOW,
+  });
+  assert.equal(r.after.state, 'empty', 'still empty after a "successful" ingest');
+  assert.equal(r.after.level, 'alarm');
+});
+
+await test('a healthy sweep still SPEAKS — silence must not be the healthy state', async () => {
+  // The reconciler's lesson: a sweep that only logs on failure is
+  // indistinguishable from a sweep that is not running at all.
+  const lines = [];
+  await sweep({
+    pool: fakePool([{ chunks: 4812, last: daysAgo(1) }]),
+    log: { log: (m) => lines.push(m), error: (m) => lines.push(m) },
+    execFileImpl: okExec, now: NOW,
+  });
+  assert.ok(lines.length >= 2, 'a healthy sweep leaves a disposition line');
+  assert.ok(lines.some((l) => /4812/.test(l)), 'and says what it found');
+});
+
+await test('a DB read failure never throws out of the sweep', async () => {
+  const r = await sweep({
+    pool: { query: async () => { throw new Error('connection refused'); } },
+    log: quietLog, execFileImpl: okExec, now: NOW,
+  });
+  assert.equal(r.health.state, 'unreadable');
+  assert.equal(r.health.level, 'alarm');
+});
+
+await test('the poller is declared in the memory manifest — a file nothing loads is dormant', async () => {
+  // The exact failure goal 1000076 hit five times: a surface that exists, is
+  // documented, and is never wired.
+  const manifest = require('../modules/memory/module.json');
+  assert.ok(
+    (manifest.contributes.pollers || []).includes('search-index'),
+    'modules/memory/module.json must declare the poller for the loader to start it',
+  );
+});
+
+console.log(`\nsearch_index_poller: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);