@bongos/core 1.17.0

package/src/bongos/goal-scope-check.js

@@ -0,0 +1,120 @@
+// goal-scope-check.js — the PURE scope wall for goal-authored tasks (BV1.R59, ADR 0086 §3).
+//
+// Phase 3 of the goal-scoped work hierarchy. A goal is a shared, module-scoped
+// workspace; joining it grants a member BOUNDED authority to author their own
+// tasks (POST /goals/:id/tasks — BV1.R60 / the "G07" create gate). This module
+// is the gate's decision core: given a goal's `scope_modules`, a candidate
+// task's `touches[]`, and the author's rank, it answers "may this member author
+// this task here?" with a single `check(...) -> { ok, reason }`.
+//
+// TWO independent walls, BOTH must pass (ADR 0086 §6, "ordered + fail-closed"):
+//
+//   1. SCOPE-SUBSET — every `touches[]` element must be CONTAINED WITHIN the
+//      goal's territory (the union of its modules' globs, resolved via
+//      module-scope-map G01). This bounds *everyone*, regardless of rank: a goal
+//      member can only author work inside the goal's modules.
+//
+//   2. PROTECTED-PATH — a sub-Metic member (xenos/thetes) may not author a task
+//      touching the permission/ship-grade/deploy/migration core, even when that
+//      path is *inside* the goal's scope (an Archon may scope a goal to a
+//      protected module). This delegates to checkPermissionPaths — the SINGLE
+//      source of the protected roster (permission-path-check.js, SEC #863) — so
+//      this wall can never drift from the pre-push hook / grader / main-audit.
+//      Metic+ are unaffected (they clear the rank floor).
+//
+// WHY `matchOne` AND NOT `touchesOverlap` FOR THE SUBSET TEST.
+//   path-match.js exports both. `touchesOverlap(a,b)` is SYMMETRIC — true if
+//   either side is a prefix of the other — which is the right tool for "do two
+//   claims collide?" but the WRONG tool for "is this touch inside the goal?".
+//   Under symmetric overlap a task touching `src/` would "overlap" a goal that
+//   owns only `src/preview-server.js` and slip through — a scope hole. The
+//   subset test needs DIRECTIONAL containment ("is the touch equal to, or under,
+//   a goal glob?"), which is exactly `matchOne(touch, goalGlobs) !== null`.
+//
+// PURE + dependency-free of Express/DB (only sibling pure modules) so the create
+// gate, fitness checks, and unit tests all run identical logic in isolation.
+
+'use strict';
+
+const { matchOne } = require('./path-match');
+const { globsForModules } = require('./module-scope-map');
+const { checkPermissionPaths } = require('./permission-path-check');
+
+function clean(arr) {
+  return Array.isArray(arr) ? arr.filter(Boolean) : [];
+}
+
+function deny(code, reason, details) {
+  return { ok: false, code, reason, details: details ?? null };
+}
+
+// Is one task touch contained within the goal's territory? Exact path match or a
+// goal-glob directory-prefix covering the touch (directional — see header).
+function isCovered(touch, goalGlobs) {
+  return matchOne(touch, goalGlobs || []) !== null;
+}
+
+// Wall 1 — scope subset. Pure: { ok, out_of_scope[], goal_globs[] }.
+// `ok` is true iff every cleaned touch is covered by the goal's resolved globs.
+// An empty/unknown module set resolves to zero globs → nothing is covered.
+function scopeSubset(goalScopeModules, touches) {
+  const goalGlobs = globsForModules(clean(goalScopeModules));
+  const outOfScope = clean(touches).filter((p) => !isCovered(p, goalGlobs));
+  return { ok: outOfScope.length === 0, out_of_scope: outOfScope, goal_globs: goalGlobs };
+}
+
+// Wall 2 — the protected-path delegate. Thin wrapper over checkPermissionPaths
+// (the one protected-roster source). Pure: { ok, protected_hits[], findings[] }.
+// ok=false ONLY when the author is sub-Metic AND a touch hits a protected path.
+// Unknown ranks fail OPEN here by design (checkPermissionPaths) — the live rank
+// is supplied by the authenticated route; the post-push audit owns the dishonest
+// case. Metic+ always pass.
+function protectedPathBlock(touches, builderRank) {
+  const r = checkPermissionPaths({ changedFiles: clean(touches), builderRank });
+  return {
+    ok: !r.hardFail,
+    protected_hits: r.protectedHits,
+    findings: r.findings,
+    builderRank: r.builderRank,
+  };
+}
+
+// The combined gate the create route calls. Ordered + fail-closed:
+//   empty scope → empty touches → unknown scope → scope-subset → protected-path.
+// Returns { ok, code, reason, details }. `reason` is human-facing (route surfaces
+// it); `code` is the machine token; `details` carries the offending paths/hits.
+function check(goalScopeModules, touches, builderRank) {
+  const modules = clean(goalScopeModules);
+  if (modules.length === 0) {
+    return deny('empty_scope', 'This goal has no scope_modules — a scopeless goal cannot authorize any task.');
+  }
+
+  const t = clean(touches);
+  if (t.length === 0) {
+    return deny('empty_touches', "This task declares no touches[] — its blast radius can't be checked against the goal scope.");
+  }
+
+  const subset = scopeSubset(modules, t);
+  if (subset.goal_globs.length === 0) {
+    return deny('unknown_scope',
+      `None of the goal's scope_modules (${modules.join(', ')}) resolve to any module territory.`,
+      { modules });
+  }
+  if (!subset.ok) {
+    return deny('out_of_scope',
+      `${subset.out_of_scope.length} path(s) fall outside the goal's module scope: ${subset.out_of_scope.join(', ')}.`,
+      { out_of_scope: subset.out_of_scope });
+  }
+
+  const prot = protectedPathBlock(t, builderRank);
+  if (!prot.ok) {
+    const hits = prot.protected_hits.map((h) => h.file);
+    return deny('protected_path',
+      `Builder rank '${builderRank}' is below Metic and may not author a task touching protected path(s): ${hits.join(', ')} (ADR 0016, SEC #863). An Archon must own this work.`,
+      { protected_hits: prot.protected_hits });
+  }
+
+  return { ok: true, code: 'ok', reason: null, details: null };
+}
+
+module.exports = { check, scopeSubset, protectedPathBlock, isCovered };

package/src/bongos/hierarchy-config.js

@@ -0,0 +1,189 @@
+// src/bongos/hierarchy-config.js — the work-hierarchy tier preset (BV1.R55, ADR 0086 §1).
+//
+// The ADR 0062 core/host pattern applied to the WORK MODEL. The goal-scoped work
+// hierarchy is six tiers — Project → Version → Goal → Criteria → Task → Sub-task —
+// but the tier SET is host-configurable: an instance may relabel tiers, enable/
+// disable them, and choose which tier carries scope / membership / criteria. This
+// module is the loader + validator + accessor for that preset; it mirrors
+// src/modules.js (which bakes the MODULE_REGISTRY in code and reads only the
+// per-instance toggles from config/modules.json).
+//
+// WHY the canonical tier set is BAKED here (not a config/*.neutral.json like
+// branding/modules): the six-tier model is METHODOLOGY CORE — the same for every
+// instance — so it is code, the single source, and cannot drift from a data file.
+// config/hierarchy.json carries only an instance's OVERRIDES (labels, enable/
+// disable, role assignment), resolved over this default. A fresh instance with no
+// file gets the canonical six tiers.
+//
+// v1 "editable" = owner-set labels, enable/disable, and which tier owns scope/
+// membership/criteria (ADR 0086 §1). Adding/removing/reordering tiers — fully
+// arbitrary custom tier graphs — is explicitly DEFERRED; an override naming a tier
+// key outside the standard set is rejected.
+//
+// Downstream: the goal entity (BV1.R56+) and the /status rollup (BV1.R58) read the
+// resolved tiers + roles from here; goal routes (BV1.R57) use scopeTier()/
+// membershipTier() to know which tier carries scope_modules + members.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveInstanceRoot } = require('../instance-config');
+
+// ADR 0108 §1: config/hierarchy.json is host content; resolveInstanceRoot()
+// returns the repo root today, so this is byte-identical for the live instance.
+const INSTANCE_PATH = path.join(resolveInstanceRoot(), 'config', 'hierarchy.json');
+
+// The canonical six-tier work model. `roles` names which tier carries scope
+// (scope_modules), membership (members), and criteria (the done-when tier) — the
+// three the ADR §1 calls out. Containment is the array order (Project ⊃ … ⊃ Sub-task).
+const DEFAULT_HIERARCHY = Object.freeze({
+  tiers: Object.freeze([
+    Object.freeze({ key: 'project', label: 'Project', enabled: true }),
+    Object.freeze({ key: 'version', label: 'Version', enabled: true }),
+    Object.freeze({ key: 'goal', label: 'Goal', enabled: true }),
+    Object.freeze({ key: 'criteria', label: 'Criteria', enabled: true }),
+    Object.freeze({ key: 'task', label: 'Task', enabled: true }),
+    Object.freeze({ key: 'subtask', label: 'Sub-task', enabled: true }),
+  ]),
+  roles: Object.freeze({ scope: 'goal', membership: 'goal', criteria: 'criteria' }),
+});
+
+const ROLE_KEYS = ['scope', 'membership', 'criteria'];
+const STANDARD_KEYS = DEFAULT_HIERARCHY.tiers.map((t) => t.key);
+
+const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
+
+function deepFreeze(h) {
+  h.tiers.forEach((t) => Object.freeze(t));
+  Object.freeze(h.tiers);
+  Object.freeze(h.roles);
+  return Object.freeze(h);
+}
+
+// Validate an instance OVERRIDE object (the config/hierarchy.json shape). Throws
+// with a clear message; pure. Overrides may set per-tier label/enabled (keyed by
+// an existing standard tier) and reassign roles — nothing else in v1.
+function validateOverrides(instance) {
+  if (!isObj(instance)) throw new Error('hierarchy: config must be a JSON object');
+  if (instance.tiers !== undefined) {
+    if (!Array.isArray(instance.tiers)) throw new Error('hierarchy: `tiers` must be an array of {key,label?,enabled?} overrides');
+    const seen = new Set();
+    for (const t of instance.tiers) {
+      if (!isObj(t) || typeof t.key !== 'string' || !t.key.trim()) throw new Error('hierarchy: each tier override needs a non-empty string `key`');
+      if (!STANDARD_KEYS.includes(t.key)) {
+        throw new Error(`hierarchy: unknown tier "${t.key}" — v1 allows overriding the standard set only (${STANDARD_KEYS.join(', ')}); arbitrary tier graphs are deferred (ADR 0086 §1)`);
+      }
+      if (seen.has(t.key)) throw new Error(`hierarchy: duplicate tier override "${t.key}"`);
+      seen.add(t.key);
+      if (t.label !== undefined && (typeof t.label !== 'string' || !t.label.trim())) throw new Error(`hierarchy: tier "${t.key}" label must be a non-empty string`);
+      if (t.enabled !== undefined && typeof t.enabled !== 'boolean') throw new Error(`hierarchy: tier "${t.key}" enabled must be a boolean`);
+    }
+  }
+  if (instance.roles !== undefined) {
+    if (!isObj(instance.roles)) throw new Error('hierarchy: `roles` must be an object {scope,membership,criteria}');
+    for (const k of Object.keys(instance.roles)) {
+      if (!ROLE_KEYS.includes(k)) throw new Error(`hierarchy: unknown role "${k}" (roles: ${ROLE_KEYS.join(', ')})`);
+      if (typeof instance.roles[k] !== 'string' || !instance.roles[k].trim()) throw new Error(`hierarchy: role "${k}" must name a tier (a non-empty string)`);
+    }
+  }
+}
+
+// Validate a fully-resolved hierarchy (post-merge): every role names an ENABLED
+// tier that exists. Throws; pure.
+function validateResolved(h) {
+  const byKey = new Map(h.tiers.map((t) => [t.key, t]));
+  for (const role of ROLE_KEYS) {
+    const target = h.roles[role];
+    if (!target) throw new Error(`hierarchy: role "${role}" is unset`);
+    const tier = byKey.get(target);
+    if (!tier) throw new Error(`hierarchy: role "${role}" → "${target}" names no tier (tiers: ${[...byKey.keys()].join(', ')})`);
+    if (!tier.enabled) throw new Error(`hierarchy: role "${role}" → "${target}" is a disabled tier — the tier carrying ${role} must be enabled`);
+  }
+}
+
+// Pure resolver: merge an instance override onto DEFAULT_HIERARCHY, validate, freeze.
+// `instance` null/undefined → the canonical default. Overrides match by tier key
+// and may set label/enabled; standard order + key set are preserved (v1).
+function resolveHierarchy(instance) {
+  if (instance == null) return deepFreeze(clone(DEFAULT_HIERARCHY));
+  validateOverrides(instance);
+  const ovByKey = new Map((instance.tiers || []).map((t) => [t.key, t]));
+  const tiers = DEFAULT_HIERARCHY.tiers.map((d) => {
+    const ov = ovByKey.get(d.key) || {};
+    return {
+      key: d.key,
+      label: typeof ov.label === 'string' && ov.label.trim() ? ov.label.trim() : d.label,
+      enabled: typeof ov.enabled === 'boolean' ? ov.enabled : d.enabled,
+    };
+  });
+  const roles = { ...DEFAULT_HIERARCHY.roles, ...(isObj(instance.roles) ? instance.roles : {}) };
+  const resolved = { tiers, roles };
+  validateResolved(resolved);
+  return deepFreeze(resolved);
+}
+
+function clone(h) {
+  return { tiers: h.tiers.map((t) => ({ ...t })), roles: { ...h.roles } };
+}
+
+function readJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch (e) { if (e.code === 'ENOENT') return null; throw e; }
+}
+
+// Disk loader: config/hierarchy.json (optional) resolved over the default. A
+// GDS_HIERARCHY_FILE env path overrides the instance file (mirrors modules.js's
+// GDS_MODULES_FILE, so one checkout can run two instances). The `_note` key in the
+// file is documentation and ignored by the resolver.
+function loadHierarchy({ instancePath, env = process.env } = {}) {
+  let ip = instancePath;
+  if (ip === undefined) ip = env.GDS_HIERARCHY_FILE ? path.resolve(resolveInstanceRoot(), env.GDS_HIERARCHY_FILE) : INSTANCE_PATH;
+  const raw = readJson(ip);
+  return resolveHierarchy(raw);
+}
+
+// Resolved singleton (lazy, so require-time never crashes tooling), like modules().
+let _cached = null;
+const hierarchy = () => (_cached ||= loadHierarchy());
+const _resetForTests = () => { _cached = null; };
+
+const tiers = (h = hierarchy()) => h.tiers;
+const tierKeys = (h = hierarchy()) => h.tiers.map((t) => t.key);
+const tier = (key, h = hierarchy()) => h.tiers.find((t) => t.key === key) || null;
+const enabledTiers = (h = hierarchy()) => h.tiers.filter((t) => t.enabled);
+const roleTier = (role, h = hierarchy()) => h.roles[role] || null;
+const scopeTier = (h = hierarchy()) => h.roles.scope;
+const membershipTier = (h = hierarchy()) => h.roles.membership;
+const criteriaTier = (h = hierarchy()) => h.roles.criteria;
+
+// CLIENT-SAFE projection — tier labels + roles are all safe to expose. The hall/
+// status front-ends read this to render the work tree with the instance's labels.
+function clientHierarchy(h = hierarchy()) {
+  return {
+    tiers: h.tiers.map((t) => ({ key: t.key, label: t.label, enabled: t.enabled })),
+    roles: { ...h.roles },
+  };
+}
+
+module.exports = {
+  DEFAULT_HIERARCHY,
+  STANDARD_KEYS,
+  ROLE_KEYS,
+  validateOverrides,
+  validateResolved,
+  resolveHierarchy,
+  loadHierarchy,
+  hierarchy,
+  tiers,
+  tierKeys,
+  tier,
+  enabledTiers,
+  roleTier,
+  scopeTier,
+  membershipTier,
+  criteriaTier,
+  clientHierarchy,
+  INSTANCE_PATH,
+  _resetForTests,
+};

package/src/bongos/live-channel.js

@@ -0,0 +1,145 @@
+// GDS live-update channel — the in-process relay between Postgres NOTIFY and
+// the builders-hall live stream. See docs/adr/0030-builders-hall-live-updates.md
+// (original WebSocket transport) and docs/adr/0069-hall-live-channel-sse-decouple.md
+// (R55: transport moved to SSE so the hall is live on a game-less boot).
+//
+// One dedicated long-lived pg Client holds a LISTEN on the 'gds_live' channel
+// (the triggers in migration 066 fire the matching NOTIFY). Every notification
+// fans out to the set of subscribers — in practice the hall's SSE endpoint
+// (src/bongos/routes/live.js), which writes a `nudge` event to each connected hall
+// tab's EventSource. (Before R55 the subscriber was the Colyseus
+// BuildersHallRoom; the relay itself is transport-agnostic and unchanged.) We
+// deliberately do NOT use the shared pool: LISTEN must stay pinned to a single
+// connection for the life of the subscription, and a pooled client gets
+// recycled out from under us.
+//
+// Lifecycle: lazy. The connection opens on the first subscriber and closes when
+// the last one leaves, so an idle hall (nobody watching) holds zero extra DB
+// connections. Connection errors schedule a bounded reconnect as long as there
+// is still at least one subscriber waiting.
+
+const { Client } = require('pg');
+const { instanceDbName } = require('./pool');
+
+const CHANNEL = 'gds_live';
+
+/** @type {Set<(payload: object|null) => void>} */
+const subscribers = new Set();
+
+let client = null;        // the live LISTEN client, or null when disconnected
+let connecting = false;   // guard against concurrent connect attempts
+let reconnectTimer = null;
+let reconnectDelayMs = 2000;  // backoff before re-LISTEN; test-tunable via _setReconnectDelay
+
+// Mirror the GDS pool's peer-auth socket config so this LISTEN client targets the
+// exact same socket + database (PGHOST/PGDATABASE env overrides honored for
+// non-droplet environments). The DB-name default resolves through pool.js's
+// instanceDbName() — the SINGLE source for the instance's configured db.database
+// (from the branding pack) — instead of a second hardcoded "amazonprimea" literal
+// (ADR 0062 §5). A non-OTB instance LISTENs on its OWN DB, and there is one place
+// to change the default.
+function pgConfig() {
+  return {
+    host: process.env.PGHOST || '/var/run/postgresql',
+    database: process.env.PGDATABASE || instanceDbName(),
+  };
+}
+
+// The LISTEN client is built through a factory so tests can inject a fake
+// (mirrors the deps.pool seam in src/db.js). Prod always uses a real pg.Client.
+let clientFactory = () => new Client(pgConfig());
+// Test-only injection seam. Refuses to swap the factory under NODE_ENV=production
+// so no server-side require can intercept/suppress the NOTIFY fan-out in prod.
+function _setClientFactory(fn) {
+  if (process.env.NODE_ENV === 'production') return;
+  clientFactory = fn || (() => new Client(pgConfig()));
+}
+// Test-only seam: shrink the reconnect backoff so a test can exercise the
+// reconnect path without a multi-second real-time wait (mirrors _setClientFactory;
+// refuses under NODE_ENV=production so prod always uses the 2s backoff).
+function _setReconnectDelay(ms) {
+  if (process.env.NODE_ENV === 'production') return;
+  reconnectDelayMs = Number.isFinite(ms) && ms >= 0 ? ms : 2000;
+}
+
+function broadcast(payload) {
+  for (const fn of subscribers) {
+    // One bad/closed subscriber must not break the fan-out to the others.
+    try { fn(payload); } catch (_err) { /* swallow — its own close handler cleans up */ }
+  }
+}
+
+function scheduleReconnect() {
+  if (client) {
+    const dead = client;
+    client = null;
+    dead.removeAllListeners();
+    dead.end().catch(() => {});
+  }
+  if (reconnectTimer || subscribers.size === 0) return;
+  reconnectTimer = setTimeout(() => {
+    reconnectTimer = null;
+    if (subscribers.size > 0) ensureConnected();
+  }, reconnectDelayMs);
+  if (reconnectTimer.unref) reconnectTimer.unref();  // don't keep the process alive
+}
+
+async function ensureConnected() {
+  if (client || connecting || subscribers.size === 0) return;
+  connecting = true;
+  const c = clientFactory();
+  c.on('error', (err) => {
+    console.error('[live] LISTEN client error:', err.message);
+    scheduleReconnect();
+  });
+  c.on('notification', (msg) => {
+    if (msg.channel !== CHANNEL) return;
+    let payload = null;
+    try { payload = msg.payload ? JSON.parse(msg.payload) : null; } catch (_e) { payload = null; }
+    broadcast(payload);
+  });
+  try {
+    await c.connect();
+    await c.query(`LISTEN ${CHANNEL}`);
+    client = c;
+    console.log('[live] LISTEN gds_live active');
+  } catch (err) {
+    console.error('[live] LISTEN connect failed:', err.message);
+    c.removeAllListeners();
+    await c.end().catch(() => {});
+    scheduleReconnect();
+  } finally {
+    connecting = false;
+  }
+}
+
+// Register a callback to receive every nudge. Returns an unsubscribe function.
+// The first subscriber opens the LISTEN connection; the last to leave closes it.
+function subscribe(fn) {
+  subscribers.add(fn);
+  ensureConnected();
+  return function unsubscribe() {
+    subscribers.delete(fn);
+    if (subscribers.size === 0 && client) {
+      const dead = client;
+      client = null;
+      dead.removeAllListeners();
+      dead.end().catch(() => {});
+    }
+  };
+}
+
+// Test/introspection seam.
+function _state() {
+  return { subscribers: subscribers.size, connected: !!client };
+}
+
+// _setClientFactory is a test-only seam — keep it OFF the public surface in
+// production so no server-side require can reach it at all (defence in depth
+// alongside the NODE_ENV guard inside the function itself).
+module.exports = {
+  subscribe,
+  _state,
+  CHANNEL,
+  ...(process.env.NODE_ENV === 'production' ? {} : { _setClientFactory, _setReconnectDelay }),
+};