@bongos/core 1.17.0

package/tests/day_cycle.mjs

@@ -0,0 +1,197 @@
+// tests/day_cycle.mjs
+//
+// The pure math behind the #639 time-of-day lighting. No Phaser, no DOM — the
+// fx/lighting.js glue is a thin shell over these functions, so getting the
+// math right here is most of the feature.
+//
+// Run:  node tests/day_cycle.mjs
+
+import { strict as assert } from 'node:assert';
+import {
+  DEFAULT_PERIOD_MS,
+  KEYFRAMES,
+  SKY_PHASES,
+  wrap01,
+  phaseFromClock,
+  lerpColor,
+  bracket,
+  tintAt,
+  parseSkyOverride,
+} from '../modules/game/public/game/fx/dayCycle.js';
+
+let passed = 0;
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  ok  ${name}`);
+    passed++;
+  } catch (e) {
+    console.error(`  FAIL ${name}: ${e.message}`);
+    process.exitCode = 1;
+  }
+}
+
+const chan = (c) => [(c >> 16) & 0xff, (c >> 8) & 0xff, c & 0xff];
+
+// ---------- wrap01 -------------------------------------------------------
+
+test('wrap01 maps any real into [0,1)', () => {
+  assert.equal(wrap01(0), 0);
+  assert.equal(wrap01(0.5), 0.5);
+  assert.equal(wrap01(1), 0);
+  assert.ok(Math.abs(wrap01(1.25) - 0.25) < 1e-9);
+  assert.ok(Math.abs(wrap01(-0.25) - 0.75) < 1e-9);
+  assert.ok(Math.abs(wrap01(-2.1) - 0.9) < 1e-9);
+});
+
+// ---------- phaseFromClock ----------------------------------------------
+
+test('phaseFromClock is 0 at the epoch and 0.5 at half a period', () => {
+  assert.equal(phaseFromClock(0), 0);
+  assert.equal(phaseFromClock(DEFAULT_PERIOD_MS / 2), 0.5);
+});
+
+test('phaseFromClock wraps each period', () => {
+  assert.equal(phaseFromClock(DEFAULT_PERIOD_MS), 0);
+  assert.ok(Math.abs(phaseFromClock(DEFAULT_PERIOD_MS * 1.25) - 0.25) < 1e-9);
+});
+
+test('phaseFromClock is deterministic — shared across clients by construction', () => {
+  const now = 1_700_000_123_456;
+  assert.equal(phaseFromClock(now), phaseFromClock(now));
+  // Two clients a few seconds apart see ~the same phase (period is minutes).
+  const skew = phaseFromClock(now + 3000) - phaseFromClock(now);
+  assert.ok(Math.abs(skew) < 0.01, `3s skew tiny: ${skew}`);
+});
+
+test('phaseFromClock guards a non-positive period', () => {
+  assert.equal(phaseFromClock(1234, 0), 0);
+  assert.equal(phaseFromClock(1234, -5), 0);
+});
+
+// ---------- lerpColor ----------------------------------------------------
+
+test('lerpColor returns the endpoints at f=0 and f=1', () => {
+  assert.equal(lerpColor(0x000000, 0xffffff, 0), 0x000000);
+  assert.equal(lerpColor(0x000000, 0xffffff, 1), 0xffffff);
+});
+
+test('lerpColor blends channel-by-channel at the midpoint', () => {
+  // (0,128,255) is the per-channel midpoint of black and 0x00ffff... use a
+  // clean case: midpoint of 0x000000 and 0x804020 is (64,32,16).
+  assert.deepEqual(chan(lerpColor(0x000000, 0x804020, 0.5)), [64, 32, 16]);
+});
+
+test('lerpColor clamps f outside [0,1]', () => {
+  assert.equal(lerpColor(0x102030, 0xa0b0c0, -1), 0x102030);
+  assert.equal(lerpColor(0x102030, 0xa0b0c0, 2), 0xa0b0c0);
+});
+
+// ---------- bracket / tintAt --------------------------------------------
+
+test('tintAt hits each keyframe exactly at its phase', () => {
+  for (const kf of KEYFRAMES) {
+    const { color, alpha } = tintAt(kf.t);
+    assert.equal(color, kf.color, `${kf.name}@${kf.t} color`);
+    assert.ok(Math.abs(alpha - kf.alpha) < 1e-9, `${kf.name}@${kf.t} alpha`);
+  }
+});
+
+test('high noon is fully transparent (base art at full strength)', () => {
+  assert.equal(tintAt(SKY_PHASES.midday).alpha, 0);
+  // The whole noon plateau holds at alpha 0.
+  assert.equal(tintAt(0.45).alpha, 0);
+  assert.equal(tintAt(0.50).alpha, 0);
+});
+
+test('golden hour is the warm hero state', () => {
+  const t = tintAt(SKY_PHASES.golden);
+  const [r, g, b] = chan(t.color);
+  assert.ok(r > g && g > b, `amber: r>g>b got ${r},${g},${b}`);
+  assert.ok(t.alpha > 0.3, `visible: ${t.alpha}`);
+  assert.equal(t.name, 'golden');
+});
+
+test('night is a dark blue-dominant tint', () => {
+  const [r, g, b] = chan(tintAt(0).color);
+  assert.ok(b > r && b > g, `blue-dominant: ${r},${g},${b}`);
+  assert.ok(tintAt(0).alpha > 0.5, 'strong');
+});
+
+test('the wrap segment interpolates nightfall → deep night across midnight', () => {
+  // phase 0.94 sits between the 0.88 nightfall keyframe and the 0.00 deep-night
+  // keyframe (read circularly). Alpha must land strictly between the two.
+  const { alpha } = tintAt(0.94);
+  assert.ok(alpha > 0.64 && alpha < 0.72, `between nightfall and deep night: ${alpha}`);
+});
+
+test('bracket picks the wrap segment for late-night phases', () => {
+  const b = bracket(0.95);
+  assert.equal(b.from.t, 0.88);
+  assert.equal(b.to.t, 0.00);
+  assert.ok(b.f > 0 && b.f < 1);
+});
+
+test('tintAt is continuous and total over the whole cycle (no gaps/throws)', () => {
+  let prev = tintAt(0);
+  for (let i = 1; i <= 1000; i++) {
+    const p = i / 1000;
+    const cur = tintAt(p);
+    assert.ok(cur.alpha >= 0 && cur.alpha <= 1, `alpha in range @${p}`);
+    // No discontinuous jump bigger than the largest keyframe-to-keyframe step.
+    assert.ok(Math.abs(cur.alpha - prev.alpha) < 0.05, `smooth @${p}`);
+    prev = cur;
+  }
+});
+
+test('tintAt wraps: phase 1.0 equals phase 0.0', () => {
+  assert.deepEqual(tintAt(1.0), tintAt(0.0));
+  assert.deepEqual(tintAt(1.5), tintAt(0.5));
+});
+
+// ---------- parseSkyOverride --------------------------------------------
+
+test('parseSkyOverride: absent / blank => null (run the live clock)', () => {
+  assert.equal(parseSkyOverride(null), null);
+  assert.equal(parseSkyOverride(undefined), null);
+  assert.equal(parseSkyOverride(''), null);
+  assert.equal(parseSkyOverride('   '), null);
+});
+
+test('parseSkyOverride: mood names (case-insensitive) => their phase', () => {
+  assert.equal(parseSkyOverride('golden'), SKY_PHASES.golden);
+  assert.equal(parseSkyOverride('NIGHT'), SKY_PHASES.night);
+  assert.equal(parseSkyOverride('Dusk'), SKY_PHASES.dusk);
+});
+
+test('parseSkyOverride: raw fractions, wrapped into [0,1)', () => {
+  assert.equal(parseSkyOverride('0.68'), 0.68);
+  assert.equal(parseSkyOverride('0'), 0);
+  assert.ok(Math.abs(parseSkyOverride('1.25') - 0.25) < 1e-9);
+});
+
+test('parseSkyOverride: garbage => null', () => {
+  assert.equal(parseSkyOverride('banana'), null);
+  assert.equal(parseSkyOverride('NaN'), null);
+});
+
+// ---------- data sanity --------------------------------------------------
+
+test('KEYFRAMES are sorted, valid colours, alphas in [0,1]', () => {
+  for (let i = 0; i < KEYFRAMES.length; i++) {
+    const kf = KEYFRAMES[i];
+    assert.ok(kf.t >= 0 && kf.t < 1, `t in [0,1): ${kf.t}`);
+    assert.ok(kf.alpha >= 0 && kf.alpha <= 1, `alpha in [0,1]: ${kf.alpha}`);
+    assert.ok(Number.isInteger(kf.color) && kf.color >= 0 && kf.color <= 0xffffff, 'color 24-bit');
+    if (i > 0) assert.ok(kf.t > KEYFRAMES[i - 1].t, `strictly ascending @${i}`);
+  }
+});
+
+test('SKY_PHASES all resolve into [0,1) and round-trip through tintAt', () => {
+  for (const [name, p] of Object.entries(SKY_PHASES)) {
+    assert.ok(p >= 0 && p < 1, `${name} phase in range`);
+    assert.doesNotThrow(() => tintAt(p), `${name} tints`);
+  }
+});
+
+console.log(`\nday_cycle: ${passed} passed`);

package/tests/dependencies_migration.mjs

@@ -0,0 +1,77 @@
+// tests/dependencies_migration.mjs
+//
+// Static shape guard for migration 163 (the polymorphic dependency edge) + the
+// db.js repoint, in the style of migration_allocation.mjs: no live DB, assert the
+// SQL TEXT so a future edit can't silently drop the table shape, the additive
+// backfill, the three promotion triggers, or the task-only filter on the repointed
+// task-dependency CRUD. The runtime behaviour of the CTE + triggers is proven
+// against real Postgres at deploy; this pins the contract.
+//
+// Run:  node tests/dependencies_migration.mjs
+
+import { strict as assert } from 'node:assert';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { makeRunner } from './helpers.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, '..');
+const read = (...p) => readFileSync(join(repoRoot, ...p), 'utf8');
+
+const mig = read('migrations', '163_polymorphic_dependencies.sql');
+const migN = mig.replace(/\s+/g, ' ');
+// the task-dependency CRUD + the claim-gate slice carved to the lifecycle module at BV1.R86.
+const dbSrc = read('modules', 'lifecycle', 'db.js');
+
+const { test, summary } = makeRunner();
+
+await test('163 creates `dependencies` with the 4-col PK, kind CHECKs, and no-self-dep', () => {
+  assert.match(mig, /CREATE TABLE IF NOT EXISTS dependencies/);
+  assert.match(mig, /from_kind\s+text\s+NOT NULL CHECK \(from_kind IN \('task', 'goal', 'criterion'\)\)/);
+  assert.match(mig, /to_kind\s+text\s+NOT NULL CHECK \(to_kind\s+IN \('task', 'goal', 'criterion'\)\)/);
+  assert.match(mig, /PRIMARY KEY \(from_kind, from_id, to_kind, to_id\)/);
+  assert.match(mig, /CONSTRAINT no_self_dep CHECK \(NOT \(from_kind = to_kind AND from_id = to_id\)\)/);
+});
+
+await test('163 indexes both edge directions', () => {
+  assert.match(mig, /idx_dependencies_from ON dependencies \(from_kind, from_id\)/);
+  assert.match(mig, /idx_dependencies_to\s+ON dependencies \(to_kind, to_id\)/);
+});
+
+await test('163 backfills task->task edges via SELECT (additive, replay-safe — not literal VALUES)', () => {
+  assert.match(migN, /INSERT INTO dependencies \(from_kind, from_id, to_kind, to_id, created_at\) SELECT 'task', td\.task_id, 'task', td\.depends_on_task_id/);
+  assert.match(migN, /FROM task_dependencies td ON CONFLICT DO NOTHING/);
+  // it must NOT drop the legacy table — migration 021 still seeds it on fresh bringup.
+  assert.ok(!/DROP TABLE\s+(IF EXISTS\s+)?task_dependencies/i.test(mig), 'must not drop task_dependencies');
+});
+
+await test('163 defines the shared predicate + three promotion triggers on the three tables', () => {
+  assert.match(mig, /CREATE OR REPLACE FUNCTION task_is_fully_unblocked\(p_task_id bigint\)/);
+  assert.match(migN, /CREATE TRIGGER trg_promote_dependents_on_ship AFTER UPDATE OF status ON tasks/);
+  assert.match(migN, /CREATE TRIGGER trg_promote_dependents_on_crit_satisfy AFTER UPDATE OF satisfied ON done_when_criteria/);
+  assert.match(migN, /CREATE TRIGGER trg_promote_dependents_on_goal_achieve AFTER UPDATE OF status ON goals/);
+});
+
+await test('163 bumps the migration counter floor to >= 164 and records itself', () => {
+  assert.match(mig, /UPDATE migration_counter SET next_number = GREATEST\(next_number, 164\)/);
+  assert.match(mig, /INSERT INTO schema_migrations \(version\) VALUES \('163_polymorphic_dependencies'\)/);
+});
+
+await test('db.js: task-dependency CRUD repoints onto `dependencies`, filtered to from_kind/to_kind = task', () => {
+  assert.match(dbSrc, /FROM dependencies d/);
+  assert.match(dbSrc, /WHERE d\.from_kind = 'task' AND d\.to_kind = 'task'/);
+  assert.match(dbSrc, /INSERT INTO dependencies \(from_kind, from_id, to_kind, to_id\)/);
+  assert.match(dbSrc, /VALUES \('task', \$1, 'task', \$2\)/);
+  // no code path still reads/writes the legacy join table (comments may mention it).
+  assert.ok(!/(FROM|INTO|DELETE FROM)\s+task_dependencies/.test(dbSrc), 'no SQL still targets task_dependencies');
+});
+
+await test('db.js: the claim gate + batch resolve via unsatisfiedDeps (the old unshippedDependencies is gone)', () => {
+  assert.ok(!/unshippedDependencies/.test(dbSrc), 'unshippedDependencies fully replaced');
+  assert.match(dbSrc, /const unmetDeps = await unsatisfiedDeps\(taskId, client\)/, 'single-claim gate');
+  assert.match(dbSrc, /const unmet = await unsatisfiedDeps\(t\.id, client\)/, 'batch gate');
+  assert.match(dbSrc, /!\(d\.kind === 'task' && batchIdSet\.has\(Number\(d\.id\)\)\)/, 'batch-internal filter is task-kind-only');
+});
+
+summary();

package/tests/dependencies_polymorphic.mjs

@@ -0,0 +1,212 @@
+// tests/dependencies_polymorphic.mjs
+//
+// DB-free unit guard for the polymorphic dependency edge (ADR 0086 §5, BV1.R62 /
+// task 1516): the claim-gate resolver `unsatisfiedDeps`, the generalized cycle
+// check `findCycle` + its task-only bigint[] wrapper `findDependencyCycle`,
+// `addDependency`'s synchronous input validation, the batch task-kind-only filter,
+// and a pure-JS reproduction of the promotion/gate predicate. The recursive CTE +
+// plpgsql triggers themselves get their RUNTIME proof against live Postgres at
+// deploy (migrate.sh + verify-gds-only-schema.sh); there is no local DB, so these
+// tests pin the SQL TEXT + bound params + the JS glue exactly — the same posture as
+// goal_tier.mjs / migration_allocation.mjs.
+//
+// Run:  node tests/dependencies_polymorphic.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const db = require('../modules/lifecycle/db.js');
+const { unsatisfiedDeps, findCycle, findDependencyCycle, addDependency } = db;
+
+const { test, summary } = makeRunner();
+
+// Minimal SQL-recording fake (client OR executor): returns canned rows by matcher.
+function fake(handler) {
+  const queries = [];
+  const norm = (s) => String(s).replace(/\s+/g, ' ').trim();
+  return {
+    queries,
+    query: async (sql, params) => {
+      queries.push({ sql: norm(sql), params });
+      return (handler ? handler(norm(sql), params) : null) || { rows: [] };
+    },
+  };
+}
+const last = (f) => f.queries[f.queries.length - 1];
+
+// ============================ unsatisfiedDeps ============================
+
+await test('unsatisfiedDeps: one query, bound to the task id, resolving own + goal + criterion gating', async () => {
+  const unmet = [
+    { kind: 'task', id: 10, title: 'dep task', state: 'active' },
+    { kind: 'goal', id: 20, title: 'dep goal', state: 'open' },
+    { kind: 'criterion', id: 30, title: 'dep crit', state: 'unsatisfied' },
+  ];
+  const fc = fake((s) => (/WITH gating AS/.test(s) ? { rows: unmet } : null));
+  const out = await unsatisfiedDeps(5, fc);
+  assert.deepEqual(out, unmet, 'returns the unmet rows unchanged');
+  const q = last(fc);
+  assert.deepEqual(q.params, [5], 'bound to the task id only');
+  // the three FROM-sources of the gating CTE (own + inherited goal + inherited criteria)
+  assert.match(q.sql, /from_kind = 'task' AND d\.from_id = t\.id/);
+  assert.match(q.sql, /from_kind = 'goal' AND d\.from_id = t\.goal_id/);
+  assert.match(q.sql, /from_kind = 'criterion' AND d\.from_id IN \( SELECT tc\.criterion_id FROM task_criteria/);
+  // the three done-ness resolutions
+  assert.match(q.sql, /JOIN tasks x ON g\.to_kind = 'task'/);
+  assert.match(q.sql, /x\.status <> 'shipped'/);
+  assert.match(q.sql, /JOIN done_when_criteria x ON g\.to_kind = 'criterion'/);
+  assert.match(q.sql, /x\.satisfied = false/);
+  assert.match(q.sql, /JOIN goals x ON g\.to_kind = 'goal'/);
+  assert.match(q.sql, /x\.status <> 'achieved'/);
+});
+
+await test('unsatisfiedDeps: a fully-satisfied task returns [] (claimable)', async () => {
+  const fc = fake(() => ({ rows: [] }));
+  assert.deepEqual(await unsatisfiedDeps(5, fc), []);
+});
+
+await test('unsatisfiedDeps: a cross-goal block surfaces the unachieved goal (done-when #5)', async () => {
+  const fc = fake((s) => (/WITH gating AS/.test(s) ? { rows: [{ kind: 'goal', id: 99, title: 'other goal', state: 'open' }] } : null));
+  const out = await unsatisfiedDeps(5, fc);
+  assert.deepEqual(out, [{ kind: 'goal', id: 99, title: 'other goal', state: 'open' }]);
+});
+
+// ============================ findCycle ============================
+
+await test('findCycle: a self-edge short-circuits without querying', async () => {
+  const fc = fake(() => { throw new Error('should not query'); });
+  assert.deepEqual(await findCycle('task', 7, 'task', 7, fc), ['task:7', 'task:7']);
+  assert.equal(fc.queries.length, 0);
+});
+
+await test('findCycle: seeds at `to`, searches for `from`, walks the graph by (kind,id)', async () => {
+  const fc = fake((s) => (/WITH RECURSIVE walk/.test(s) ? { rows: [{ path: ['goal:2', 'task:9', 'task:1'] }] } : null));
+  const path = await findCycle('task', 1, 'goal', 2, fc);
+  assert.deepEqual(path, ['goal:2', 'task:9', 'task:1']);
+  assert.deepEqual(last(fc).params, ['goal', 2, 'task', 1], 'params: toKind, toId, fromKind, fromId');
+  assert.match(last(fc).sql, /JOIN walk w ON d\.from_kind = w\.kind AND d\.from_id = w\.id/);
+});
+
+await test('findCycle: no path returns null (safe to add the edge)', async () => {
+  const fc = fake(() => ({ rows: [] }));
+  assert.equal(await findCycle('task', 1, 'task', 2, fc), null);
+});
+
+await test('findDependencyCycle: task-only wrapper maps a pure-task path back to bigint[]', async () => {
+  const fc = fake((s) => (/WITH RECURSIVE walk/.test(s) ? { rows: [{ path: ['task:2', 'task:5', 'task:1'] }] } : null));
+  assert.deepEqual(await findDependencyCycle(1, 2, fc), [2, 5, 1], 'historical bigint[] shape preserved');
+});
+
+await test('findDependencyCycle: a cycle through a non-task node keeps that node as a kind:id token', async () => {
+  const fc = fake((s) => (/WITH RECURSIVE walk/.test(s) ? { rows: [{ path: ['task:2', 'goal:3', 'task:1'] }] } : null));
+  assert.deepEqual(await findDependencyCycle(1, 2, fc), [2, 'goal:3', 1]);
+});
+
+await test('findDependencyCycle: self-dep short-circuits to [id, id]', async () => {
+  const fc = fake(() => { throw new Error('no query'); });
+  assert.deepEqual(await findDependencyCycle(7, 7, fc), [7, 7]);
+});
+
+// ===================== addDependency input validation =====================
+// (NODE_NOT_FOUND / CYCLE / INSERT touch the module pool and are exercised against
+//  live Postgres at deploy; the synchronous validation throws first, no DB needed.)
+
+await test('addDependency: rejects an unknown kind before touching the DB', async () => {
+  await assert.rejects(() => addDependency('bogus', 1, 'task', 2), (e) => e.code === 'BAD_KIND');
+});
+
+await test('addDependency: rejects a self-edge before touching the DB', async () => {
+  await assert.rejects(() => addDependency('goal', 4, 'goal', 4), (e) => e.code === 'SELF_DEP');
+});
+
+// ============== pure-JS reproduction of task_is_fully_unblocked ==============
+// Mirrors the migration's SQL predicate (own + goal + criterion gating; done =
+// shipped|satisfied|achieved) so the promotion/gate LOGIC is pinned even though the
+// SQL itself runs only against live Postgres.
+function isFullyUnblocked(task, edges, done, openBlockers = new Set()) {
+  const gating = edges.filter((e) =>
+    (e.from.kind === 'task' && e.from.id === task.id) ||
+    (e.from.kind === 'goal' && task.goalId != null && e.from.id === task.goalId) ||
+    (e.from.kind === 'criterion' && task.criteria.includes(e.from.id)));
+  // V4.R15 / task 953: an open blocker linked via task_blockers also keeps the
+  // task blocked, regardless of dep done-ness (mirrors migration 176).
+  if (openBlockers.has(task.id)) return false;
+  return gating.every((e) => done.has(`${e.to.kind}:${e.to.id}`));
+}
+
+await test('predicate: a task with own + goal + criterion deps unblocks only when ALL are done', () => {
+  const task = { id: 1, goalId: 50, criteria: [60] };
+  const edges = [
+    { from: { kind: 'task', id: 1 }, to: { kind: 'task', id: 10 } },            // own
+    { from: { kind: 'goal', id: 50 }, to: { kind: 'goal', id: 70 } },           // inherited via goal
+    { from: { kind: 'criterion', id: 60 }, to: { kind: 'criterion', id: 80 } }, // inherited via criterion
+  ];
+  assert.equal(isFullyUnblocked(task, edges, new Set()), false, 'nothing done -> blocked');
+  assert.equal(isFullyUnblocked(task, edges, new Set(['task:10', 'goal:70'])), false, 'one still open -> blocked');
+  assert.equal(isFullyUnblocked(task, edges, new Set(['task:10', 'goal:70', 'criterion:80'])), true, 'all done -> unblocked');
+});
+
+await test('predicate: no gating edges is trivially unblocked; a NULL goal_id ignores goal-inherited edges', () => {
+  assert.equal(isFullyUnblocked({ id: 9, goalId: null, criteria: [] }, [], new Set()), true);
+  const edges = [{ from: { kind: 'goal', id: 50 }, to: { kind: 'goal', id: 70 } }];
+  assert.equal(isFullyUnblocked({ id: 9, goalId: null, criteria: [] }, edges, new Set()), true, 'NULL goal_id -> no goal-inherited gating');
+});
+
+await test('predicate: an open blocker keeps a task blocked even when ALL deps are done (V4.R15 / idea 226)', () => {
+  // idea 226: task #859 sat in backlog, fully dep-satisfied, but linked to an
+  // OPEN operator-cutover blocker. Dep-ship promotion must NOT flip it to ready.
+  const task = { id: 859, goalId: null, criteria: [] };
+  const edges = [
+    { from: { kind: 'task', id: 859 }, to: { kind: 'task', id: 855 } },
+    { from: { kind: 'task', id: 859 }, to: { kind: 'task', id: 856 } },
+  ];
+  const allDepsDone = new Set(['task:855', 'task:856']);
+  assert.equal(isFullyUnblocked(task, edges, allDepsDone), true, 'deps done, no blocker -> unblocked');
+  assert.equal(
+    isFullyUnblocked(task, edges, allDepsDone, new Set([859])),
+    false,
+    'deps done BUT open blocker -> stays blocked (gate-bypass closed)',
+  );
+});
+
+// ============== migration 176 pins the open-blocker clause in the SQL ==============
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+await test('migration 176: task_is_fully_unblocked excludes tasks with an open blocker', () => {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const sql = readFileSync(join(here, '..', 'migrations', '176_promotion_respects_open_blockers.sql'), 'utf8')
+    .replace(/\s+/g, ' ');
+  assert.match(sql, /CREATE OR REPLACE FUNCTION task_is_fully_unblocked/, 'redefines the shared predicate');
+  // the new fail-closed clause: no open blocker linked via task_blockers
+  assert.match(sql, /FROM task_blockers tb JOIN blockers b ON b\.id = tb\.blocker_id/);
+  assert.match(sql, /tb\.task_id = p_task_id/);
+  assert.match(sql, /b\.status = 'open'/);
+});
+
+// ============== batch claim: task-kind-only internal filter (R1) ==============
+const batchExternal = (unmet, batchIds) =>
+  unmet.filter((d) => !(d.kind === 'task' && batchIds.has(Number(d.id))));
+
+await test('batch filter: only an in-batch TASK dep is internal; goal/criterion deps are always external', () => {
+  const batch = new Set([10, 11]);
+  const unmet = [
+    { kind: 'task', id: 10, title: 't', state: 'ready' },        // internal -> filtered out
+    { kind: 'task', id: 99, title: 't', state: 'ready' },        // external task
+    { kind: 'goal', id: 10, title: 'g', state: 'open' },         // SAME numeric id as a batch task, but a GOAL -> external
+    { kind: 'criterion', id: 11, title: 'c', state: 'unsatisfied' },
+  ];
+  const ext = batchExternal(unmet, batch);
+  assert.deepEqual(
+    ext.map((d) => `${d.kind}:${d.id}`),
+    ['task:99', 'goal:10', 'criterion:11'],
+    'a goal/criterion sharing a numeric id with a batch task must NOT be filtered (R1)',
+  );
+});
+
+// -------------------------------------------------------------------------
+summary();

package/tests/deploy_instance.mjs

@@ -0,0 +1,78 @@
+// tests/deploy_instance.mjs
+//
+// ADR 0108 §4 (configurable-root W4 / task 1884) — the consumer-instance deploy flow. Pins the
+// SHAPE of scripts/deploy/deploy-instance.sh via its --dry-run (prints each step, executes nothing):
+//   git pull → npm ci → migrate (core's three-root migrate.sh) → restart platform-server → /healthz;
+// and asserts it never `git reset --hard` (the pre-split model it replaces). No droplet / no core
+// install needed — --dry-run runs anywhere.
+//
+// Run:  node tests/deploy_instance.mjs
+
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync, existsSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const SCRIPT = join(ROOT, 'scripts', 'deploy', 'deploy-instance.sh');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+function dryRun(env = {}) {
+  const dir = mkdtempSync(join(tmpdir(), 'w4-inst-'));
+  try {
+    return execFileSync('bash', [SCRIPT, '--dry-run'], {
+      encoding: 'utf8',
+      env: { ...process.env, INSTANCE_DIR: dir, ...env },
+    });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+t('deploy-instance.sh exists and is executable', () => {
+  assert.ok(existsSync(SCRIPT), 'script present');
+  assert.ok(statSync(SCRIPT).mode & 0o111, 'script is executable');
+});
+
+t('dry-run prints the npm-ci flow in order and exits 0', () => {
+  const out = dryRun({ PORT: '3002' });
+  const steps = ['git pull --ff-only origin main', 'npm ci --omit=dev', 'migrate.sh', 'deploy-instance complete'];
+  let last = -1;
+  for (const s of steps) {
+    const at = out.indexOf(s);
+    assert.ok(at !== -1, `dry-run must mention "${s}"`);
+    assert.ok(at > last, `"${s}" must appear after the previous step`);
+    last = at;
+  }
+});
+
+t('dry-run NEVER runs `git reset --hard` (the pre-split model it replaces)', () => {
+  const out = dryRun();
+  // Every executed/echoed step is prefixed "==> ". Assert no such line is a git-reset.
+  const echoed = out.split('\n').filter((l) => l.startsWith('==> '));
+  assert.ok(!echoed.some((l) => /git reset --hard/.test(l)), 'no deploy step may hard-reset the tree');
+});
+
+t('with no INSTANCE_SERVICE, dry-run prints the platform-server boot command', () => {
+  const out = dryRun({ PORT: '3009' });
+  assert.match(out, /platform-server\.js/, 'points at the core platform-server entrypoint');
+  assert.match(out, /PORT=3009/, 'threads the configured port');
+});
+
+t('with INSTANCE_SERVICE set, dry-run restarts the unit but executes no curl/systemctl', () => {
+  const out = dryRun({ INSTANCE_SERVICE: 'mercury' });
+  assert.match(out, /systemctl restart mercury/, 'restarts the configured unit');
+  // dry-run must not actually poll healthz (guarded behind the non-dry branch)
+  assert.ok(!/\/healthz: 200/.test(out), 'no real healthz probe in a dry run');
+});
+
+console.log(`\ndeploy_instance: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);