@bongos/core 1.19.316 → 1.19.317

package/modules/lifecycle/db-goals.js

@@ -0,0 +1,763 @@
+// modules/lifecycle/db-goals.js — goals, goal membership, membership requests + goal scope/visibility/successor.
+//
+// Carved out of modules/lifecycle/db.js by task 1003204 (goal 1000079, the R03
+// de-monolith plan) — a STRUCTURAL move, not a rewrite: the code below is the
+// original db.js lines 657-1373 unchanged. db.js remains the facade that
+// re-exports every name, so every existing db call site is unchanged.
+//
+// THE BOUNDARY (ADR 0093 §1): this file reaches core ONLY through the published
+// doorway ../../src/module-api.js — never a core internal, never a sibling module.
+
+'use strict';
+
+const api = require('../../src/module-api');
+const { pool } = api;
+const doneWhen = require('./done-when.js');
+const { deriveRequiredRank, highestRank } = require('./db-rank-authz.js');
+
+// -------------------------------------------------------------------------
+// Goals (ADR 0086 §2 / BV1.R56 — task 1510)
+//
+// The shared, module-scoped tier between versions and criteria. Membership
+// (goal_members) is what later grants bounded task authoring within the goal's
+// `scope_modules` wall (R57 adds routes/goals.js; R58 the /status rollup). These
+// are the pure SQL helpers + their unit tests only — NO route references a goal
+// yet, so OTB behaves identically.
+//
+// Each accepts the #538 deps.pool seam (honored ONLY under NODE_ENV==='test')
+// so the suite can drive them with a SQL-aware fake — same posture as
+// abandonTask / createOverrideRequest.
+// -------------------------------------------------------------------------
+
+// Shared column list so every goal read/return shapes a row identically.
+
+const GOAL_COLS =
+  'id, version_id, title, description, scope_modules, status, visibility, created_by, succeeded_by_goal_id, sort_order, created_at, updated_at';
+
+// Shared column list for a goal_membership_requests row (task 1951 / ADR 0112) —
+// the invite / join-request queue behind private goals. Every helper below shapes
+// a row identically, the GOAL_COLS precedent.
+const MEMBERSHIP_REQUEST_COLS =
+  'id, goal_id, builder_id, kind, status, note, created_by, resolved_by, created_at, resolved_at, updated_at';
+
+
+// The creator is the goal's OWNER (created_by — the fixed authority, task 1735)
+// and lands in the member list as a 'lead' (rendered "manager" in the hall): the
+// member-insert CTE rides in the same statement so goal + owner-membership land
+// atomically. createdBy NULL (system-attributed, e.g. the migration-160 default
+// goals) inserts no member — those goals have no owner; Archons act as one.
+
+async function createGoal(
+  { versionId, title, description = null, scopeModules = [], status = 'open', createdBy = null },
+  deps = {}
+) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `WITH next_order AS (
+       SELECT COALESCE(MAX(sort_order) + 1, 0) AS n FROM goals WHERE version_id = $1
+     ), g AS (
+       INSERT INTO goals (version_id, title, description, scope_modules, status, created_by, sort_order)
+            SELECT $1, $2, $3, $4, $5, $6, next_order.n FROM next_order
+       RETURNING ${GOAL_COLS}
+     ), first_lead AS (
+       INSERT INTO goal_members (goal_id, builder_id, membership_kind)
+       SELECT g.id, $6::bigint, 'lead' FROM g WHERE $6::bigint IS NOT NULL
+     )
+     SELECT * FROM g`,
+    [versionId, title, description, scopeModules, status, createdBy]
+  );
+  return rows[0];
+}
+
+
+async function getGoal(id, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `SELECT ${GOAL_COLS} FROM goals WHERE id = $1`,
+    [id]
+  );
+  return rows[0] ?? null;
+}
+
+// getGoalDependencies (task 1761) — the prerequisite goals THIS goal is blocked by:
+// the goal->goal edges in the polymorphic `dependencies` table (migration 163),
+// read as "from is blocked until to is done". Each carries its satisfied state — a
+// goal dependency is satisfied when the target goal is 'achieved' (migration 163's
+// done-ness for a goal). The hall (goals-page + roadmap) shows these and greys/locks
+// an open goal with any unsatisfied dep. Scope is goal->goal only (a goal depending
+// on a task/criterion is not a modeled pattern). deps.pool test seam.
+async function getGoalDependencies(goalId, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `SELECT g.id, g.title, g.status, g.version_id,
+            (g.status = 'achieved') AS satisfied
+       FROM dependencies d
+       JOIN goals g ON g.id = d.to_id
+      WHERE d.from_kind = 'goal' AND d.from_id = $1 AND d.to_kind = 'goal'
+      ORDER BY g.id`,
+    [goalId]
+  );
+  return rows;
+}
+
+// listGoals — optional version_id / status filters (NULL = no filter), ordered
+// by the owner's WITHIN-version priority (sort_order, task 1760), falling back
+// to created_at/id so a fresh instance and prod agree on row order pre-reorder.
+
+// `limit` is optional and defaults to unbounded — the goal board reads every goal.
+// A caller that only needs the first N (the orphan advisory wants 5 candidates)
+// passes it so Postgres does the truncating instead of shipping the whole version's
+// goals to be discarded in JS (task 1002539).
+async function listGoals({ versionId = null, status = null, limit = null } = {}, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `SELECT ${GOAL_COLS}
+       FROM goals
+      WHERE ($1::text IS NULL OR version_id = $1)
+        AND ($2::text IS NULL OR status = $2)
+      ORDER BY version_id, sort_order, created_at, id
+      LIMIT $3::int`,
+    [versionId, status, limit]
+  );
+  return rows;
+}
+
+// reorderGoals — Archon drag-to-reorder (task 1760). orderedIds is the new
+// relative order for a SCOPED SUBSET of versionId's goals — the caller (hall
+// UI) only ever renders a status-filtered slice (roadmap excludes archived;
+// the Goals page defaults to open-only), so demanding the version's COMPLETE
+// goal set here would fail-closed on every version that has ever archived a
+// goal (the goal the client never rendered, and so could never round-trip).
+// Every id must still belong to THIS version, appear once (fail-closed on a
+// cross-version id or a duplicate — SET_MISMATCH), and be non-empty; any
+// goal in the version NOT named in orderedIds (e.g. an archived one hidden
+// from the view that dragged) keeps its RELATIVE order, appended after the
+// reordered slice — reordering a subset never disturbs a goal the client
+// didn't even see. Returns the reordered rows (the touched subset only).
+
+async function reorderGoals({ versionId, orderedIds }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows: existing } = await activePool.query(
+    `SELECT id FROM goals WHERE version_id = $1 ORDER BY sort_order, created_at, id`,
+    [versionId]
+  );
+  const existingIds = existing.map((r) => String(r.id));
+  const existingSet = new Set(existingIds);
+  const wantedIds = orderedIds.map(String);
+  if (wantedIds.length === 0 || new Set(wantedIds).size !== wantedIds.length || !wantedIds.every((id) => existingSet.has(id))) {
+    const err = new Error('ordered_ids must be a duplicate-free list of this version\'s goal ids');
+    err.code = 'SET_MISMATCH';
+    throw err;
+  }
+  const wantedSet = new Set(wantedIds);
+  const remainder = existingIds.filter((id) => !wantedSet.has(id));
+  const finalOrder = [...orderedIds, ...remainder.map(Number)];
+  const { rows } = await activePool.query(
+    `UPDATE goals g
+        SET sort_order = data.ord, updated_at = now()
+       FROM (SELECT unnest($1::bigint[]) AS id, unnest($2::int[]) AS ord) AS data
+      WHERE g.id = data.id
+      RETURNING ${GOAL_COLS.split(', ').map((c) => `g.${c}`).join(', ')}`,
+    [finalOrder, finalOrder.map((_, i) => i)]
+  );
+  const byId = new Map(rows.map((r) => [String(r.id), r]));
+  return orderedIds.map((id) => byId.get(String(id))).filter(Boolean);
+}
+
+// setGoalStatus — the open -> achieved -> archived lifecycle move (R63/R64 wire
+// the auto-achieve + archive/reopen on top). Bumps updated_at. Returns null if
+// the goal id is unknown.
+
+async function setGoalStatus({ goalId, status }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `UPDATE goals
+        SET status = $2, updated_at = now()
+      WHERE id = $1
+      RETURNING ${GOAL_COLS}`,
+    [goalId, status]
+  );
+  return rows[0] ?? null;
+}
+
+// achieveGoalIfComplete — the auto-achieve half of the criterion-confirm flow
+// (ADR 0086 §6 / BV1.R63). Called after a criterion is confirmed (satisfied=true):
+// if that criterion's goal is still `open` AND every criterion under the goal is
+// now satisfied (with ≥1), flip the goal open→achieved. Conservative + idempotent —
+// it never touches an achieved/archived goal (reopen/archive is the R64 lifecycle
+// move), and an empty goal (no criteria) is never auto-achieved. Returns
+// { achieved, goal }: `goal` is the (possibly updated) row, or null for an unknown
+// id. Honours the #538 deps.pool test seam (NODE_ENV==='test' only), like its
+// siblings, so the flip logic is unit-testable with a fake client.
+
+async function achieveGoalIfComplete({ goalId }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const goal = await getGoal(goalId, deps);
+  // Only an OPEN goal can auto-achieve. An already achieved/archived goal is left
+  // exactly as-is — re-confirming a criterion must not churn its status.
+  if (!goal || goal.status !== 'open') return { achieved: false, goal: goal ?? null };
+  const { rows } = await activePool.query(
+    `SELECT count(*)::int                              AS total,
+            count(*) FILTER (WHERE NOT satisfied)::int AS unsatisfied
+       FROM done_when_criteria
+      WHERE goal_id = $1`,
+    [goalId]
+  );
+  const total = rows[0]?.total ?? 0;
+  const unsatisfied = rows[0]?.unsatisfied ?? 0;
+  // Need ≥1 criterion and zero unsatisfied — confirming the LAST one is the
+  // trigger. An empty goal stays open (nothing could complete it).
+  if (total === 0 || unsatisfied > 0) return { achieved: false, goal };
+  const updated = await setGoalStatus({ goalId, status: 'achieved' }, deps);
+  return { achieved: true, goal: updated };
+}
+
+// addGoalMember — join. Upserts on the (goal_id, builder_id) PK so a re-join is
+// not a duplicate-key error, and the conflict arm PRESERVES the stored
+// membership_kind (task 1002689): overwriting it let POST /goals/:id/join (always
+// 'member') and a POST /goals/:id/members re-add silently demote a lead —
+// including the owner's row — bypassing authorizeMembershipKindChange's
+// owner-only-demotion guards. Changes go through PATCH
+// /goals/:id/members/:builderId only (the acceptMembershipRequestAndAddMember
+// precedent). membershipKind defaults to 'member'.
+
+// THE COLUMN IS `membership_kind` (task 1003013, ADR 0177 — ADR 0174 reserves the
+// other word for the three crafts). The legacy column still EXISTS for one
+// release, kept in lockstep by core_220's trigger so a rolled-back deploy still
+// reads a schema it understands: write the new name only, step 2 drops the old.
+//
+// ARRIVING AS A MEMBER CLOSES ANY PENDING ASK (task 1002888 / idea 1000688).
+// The membership write used to be a bare upsert that never looked at
+// goal_membership_requests, so a builder's pending row SURVIVED their arrival by
+// any other route — the goal flips to public and they self-join, or an Archon
+// adds them directly. The stale row lingered in the owner/manager inbox, a later
+// approve resolved a request for an existing member, and a later deny stamped
+// 'rejected' on someone who is in fact a member. Harmless to access control,
+// wrong in the audit trail.
+//
+// BOTH kinds are cancelled, not just 'request'. The partial-unique index
+// (core_188: one pending row per goal+builder, either direction) means there is
+// at most ONE pending row to close, and a stale pending INVITE is the same bug
+// mirrored — the invitee could later decline an invitation to a goal they are
+// already in, stamping 'rejected' on a member. 'cancelled' is the right terminal
+// state (core_188: "withdrawn/rescinded"); 'accepted' stays reserved for an
+// accept/approve flow that actually ran, so the inbox history never claims a
+// decision nobody made. resolvedBy is the ACTOR — the joiner themselves on
+// /join, the adding owner/manager/Archon on /members.
+//
+// One CTE, not two queries — the acceptMembershipRequestAndAddMember precedent:
+// the cancel commits with the membership write or not at all, so an error
+// between them can't leave the pair half-applied. The two arms are independent
+// (Postgres runs a data-modifying CTE to completion whether or not the primary
+// query reads it), and both see the same snapshot.
+
+async function addGoalMember({ goalId, builderId, membershipKind = 'member', resolvedBy = null }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `WITH added AS (
+       INSERT INTO goal_members (goal_id, builder_id, membership_kind)
+            VALUES ($1, $2, $3)
+       ON CONFLICT (goal_id, builder_id) DO UPDATE SET membership_kind = goal_members.membership_kind
+       RETURNING goal_id, builder_id, membership_kind, joined_at
+     ), cancelled AS (
+       UPDATE goal_membership_requests
+          SET status = 'cancelled', resolved_by = $4, resolved_at = now(), updated_at = now()
+        WHERE goal_id = $1 AND builder_id = $2 AND status = 'pending'
+       RETURNING id
+     )
+     SELECT goal_id, builder_id, membership_kind, joined_at FROM added`,
+    [goalId, builderId, membershipKind, resolvedBy]
+  );
+  return rows[0];
+}
+
+// removeGoalMember — leave. Returns { removed } so the (later) route can 404 a
+// non-member leave without a second lookup.
+
+async function removeGoalMember({ goalId, builderId }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rowCount } = await activePool.query(
+    `DELETE FROM goal_members WHERE goal_id = $1 AND builder_id = $2`,
+    [goalId, builderId]
+  );
+  return { removed: rowCount > 0 };
+}
+
+
+async function listGoalMembers(goalId, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  // Builder identity rides along (task 1734: the hall Goals page renders member
+  // names + lead badges) — additive columns, so every existing consumer that
+  // reads only {goal_id, builder_id, membership_kind} is untouched.
+  const { rows } = await activePool.query(
+    `SELECT gm.goal_id, gm.builder_id, gm.membership_kind, gm.joined_at,
+            b.github_login, b.display_name, b.avatar_url, b.rank
+       FROM goal_members gm
+       LEFT JOIN builders b ON b.id = gm.builder_id
+      WHERE gm.goal_id = $1
+      ORDER BY gm.joined_at, gm.builder_id`,
+    [goalId]
+  );
+  return rows;
+}
+
+// listCriteriaForGoal — the done_when_criteria re-parented under a goal (R56
+// backfilled every criterion under its version's default goal). Powers the
+// "linked criteria" half of GET /goals/:id; projection matches done-when.js's
+// listCriteria so the hall renders goal + version criteria identically.
+
+async function listCriteriaForGoal(goalId, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  // task 1002164: carry the linked-task counts so the caller can derive the
+  // "met — pending review" state the hall renders. The counts are aggregated
+  // ONCE, over only this goal's criteria (the `counts` CTE narrows on the `crit`
+  // CTE before grouping), rather than per-row correlated subqueries — one pass
+  // over the idx_task_criteria_criterion range instead of 2N lookups. The
+  // criterion columns are still listed explicitly so the projection this read
+  // already feeds (the version-criteria view, the task-create suggester) is
+  // unchanged apart from the two additive count columns.
+  const { rows } = await activePool.query(
+    `WITH crit AS (
+       SELECT id, version_id, criterion_id, criterion_md, satisfied, sort_order, goal_id
+         FROM done_when_criteria
+        WHERE goal_id = $1
+     ),
+     counts AS (
+       SELECT tc.criterion_id,
+              count(*)::int                                        AS linked_tasks,
+              -- task 1002651 (migration 017's family): abandoned is a terminal
+              -- state (deliberately cut), not pending work — it must not hold a
+              -- criterion's "met — pending review" flip hostage forever.
+              count(*) FILTER (WHERE t.status NOT IN ('shipped', 'abandoned'))::int AS unshipped_tasks
+         FROM task_criteria tc
+         JOIN tasks t ON t.id = tc.task_id
+        WHERE tc.criterion_id IN (SELECT id FROM crit)
+        GROUP BY tc.criterion_id
+     )
+     SELECT c.id, c.version_id, c.criterion_id, c.criterion_md, c.satisfied,
+            c.sort_order, c.goal_id,
+            COALESCE(n.linked_tasks, 0)    AS linked_tasks,
+            COALESCE(n.unshipped_tasks, 0) AS unshipped_tasks
+       FROM crit c
+       LEFT JOIN counts n ON n.criterion_id = c.id
+      ORDER BY sort_order, id`,
+    [goalId]
+  );
+  return rows.map((r) => ({
+    ...r,
+    pending_review: doneWhen.isPendingReview({
+      satisfied: r.satisfied, linked: r.linked_tasks, unshipped: r.unshipped_tasks,
+    }),
+  }));
+}
+
+// isGoalMember — is this builder a member of this goal? The membership predicate
+// behind the bounded-authority gates (BV1.R64 ask-to-widen; the R60 authoring
+// gate reuses the same idea). Returns a plain boolean.
+
+async function isGoalMember({ goalId, builderId }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `SELECT 1 FROM goal_members WHERE goal_id = $1 AND builder_id = $2 LIMIT 1`,
+    [goalId, builderId]
+  );
+  return rows.length > 0;
+}
+
+// getGoalMember — one membership row incl. membership_kind, or null. The
+// lead-authority read behind PATCH /goals/:id/members/:builderId (task 1735): the
+// route needs the actor's and the target's membership_kind, not just the
+// isGoalMember boolean.
+
+async function getGoalMember({ goalId, builderId }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `SELECT goal_id, builder_id, membership_kind, joined_at
+       FROM goal_members
+      WHERE goal_id = $1 AND builder_id = $2`,
+    [goalId, builderId]
+  );
+  return rows[0] ?? null;
+}
+
+// setGoalMembershipKind — apply a membership change with the owner guard IN the statement
+// (task 1735): the goal OWNER (goals.created_by) is the fixed authority, so a
+// demotion never applies to the owner's row even if two requests race past the
+// route's pure gate (the attachParent "re-check atomically" posture). Returns
+// the updated row, or null when nothing changed — no such member, or the guard
+// blocked an owner demotion — which the route answers as a conflict.
+
+async function setGoalMembershipKind({ goalId, builderId, membershipKind }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `UPDATE goal_members gm
+        SET membership_kind = $3
+      WHERE gm.goal_id = $1 AND gm.builder_id = $2
+        AND ($3 = 'lead'
+             OR gm.builder_id IS DISTINCT FROM
+                (SELECT g.created_by FROM goals g WHERE g.id = $1))
+     RETURNING goal_id, builder_id, membership_kind, joined_at`,
+    [goalId, builderId, membershipKind]
+  );
+  return rows[0] ?? null;
+}
+
+// transferGoalOwnership — reassign the goal's owner (task 1735): created_by
+// moves to the new owner and the new owner's membership row is upserted to
+// 'lead' (manager) in the SAME statement, so the goal can never point at an
+// owner who isn't in its member list. The OLD owner keeps their lead row —
+// "drops to manager" — exactly the handoff semantics the route promises. The
+// route gates WHO may call this (owner | Archon, target Metic+); this helper
+// just performs the move. Returns the updated goal row, or null for unknown id.
+
+async function transferGoalOwnership({ goalId, newOwnerId }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `WITH g AS (
+       UPDATE goals
+          SET created_by = $2, updated_at = now()
+        WHERE id = $1
+       RETURNING ${GOAL_COLS}
+     ), new_owner_member AS (
+       INSERT INTO goal_members (goal_id, builder_id, membership_kind)
+       SELECT g.id, $2, 'lead' FROM g
+       ON CONFLICT (goal_id, builder_id) DO UPDATE SET membership_kind = 'lead'
+     )
+     SELECT * FROM g`,
+    [goalId, newOwnerId]
+  );
+  return rows[0] ?? null;
+}
+
+// listActiveClaimsForTasks — which of these tasks hold an active claim right
+// now (claims.released_at IS NULL — the claims-table convention; there is no
+// status column). Feeds the conflict detector's claim-aware severity
+// (goal-conflicts.js, task 1736). Holder identity rides along so the hall can
+// name who to talk to.
+
+async function listActiveClaimsForTasks(taskIds, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const ids = (taskIds || []).map(Number).filter(Number.isFinite);
+  if (ids.length === 0) return [];
+  const { rows } = await activePool.query(
+    `SELECT c.id AS claim_id, c.task_id, c.builder_id, c.claimed_at,
+            b.github_login
+       FROM claims c
+       LEFT JOIN builders b ON b.id = c.builder_id
+      WHERE c.task_id = ANY($1::bigint[]) AND c.released_at IS NULL
+      ORDER BY c.claimed_at, c.id`,
+    [ids]
+  );
+  return rows;
+}
+
+// requestClaimRelease — the flag-for-release resolution action (task 1736): a
+// goal owner/manager asks the holder of a task's ACTIVE claim to wrap up or
+// release. A soft nudge, not an eviction — nothing about the claim's validity
+// changes; the flag surfaces on the holder's own claim reads
+// (getActiveClaimsForBuilder → /me). Idempotent: re-flagging refreshes
+// requester/time/note. Returns the flagged claim row, or null when the task
+// holds no active claim (the route answers 409).
+
+async function requestClaimRelease({ taskId, requestedBy, note = null }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `UPDATE claims
+        SET release_requested_by = $2,
+            release_requested_at = now(),
+            release_requested_note = $3
+      WHERE task_id = $1 AND released_at IS NULL
+     RETURNING id AS claim_id, task_id, builder_id,
+               release_requested_by, release_requested_at, release_requested_note`,
+    [taskId, requestedBy, note]
+  );
+  return rows[0] ?? null;
+}
+
+// rescopeTaskTouches — the rescope resolution action (task 1736): a goal
+// owner/manager rewrites a task's DECLARED touches[] at PLANNING time, with the
+// ADR 0049 advisory semantics (git merge stays the authoritative collision
+// detector; this only reshapes the planning-time conflict view). This is NOT
+// the mid-claim drift-expand removed in task 879 — the route refuses a task
+// with an active claim, so touches are never rewritten under a working session.
+//
+// The ADR 0084 floor stays honest: the rank floor was auto-derived from touches
+// at CREATE, so rewriting touches re-derives it and RATCHETS requires_rank UP
+// in the same UPDATE if the new blast radius demands more (the
+// updateTaskSecuritySensitive precedent — never lowered; an Archon can PATCH it
+// down explicitly). The caller passes the task row's current facts
+// (securitySensitive, currentRequiresRank) it already fetched for containment.
+// Returns { id, touches, requires_rank }, or null for an unknown task.
+
+async function rescopeTaskTouches({ taskId, touches, securitySensitive = false, currentRequiresRank = 'xenos' }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const cleaned = Array.from(new Set((touches || []).map((p) => String(p || '').trim()).filter(Boolean)));
+  const floor = deriveRequiredRank(cleaned, securitySensitive === true);
+  const effectiveRank = highestRank(currentRequiresRank ?? 'xenos', floor);
+  const { rows } = await activePool.query(
+    `UPDATE tasks SET touches = $2, requires_rank = $3, updated_at = now()
+      WHERE id = $1
+     RETURNING id, touches, requires_rank`,
+    [taskId, cleaned, effectiveRank]
+  );
+  return rows[0] ?? null;
+}
+
+// addGoalScopeModules — the "ask to widen" mutation (ADR 0086 §4 / BV1.R64). Adds
+// module key(s) to a goal's scope_modules, set-union + deduped (existing keys and
+// repeats collapse), so widening is idempotent. The route — not this helper — is
+// where the wall is enforced: scope is NEVER self-granted, so a protected module
+// can only be added by an Archon, and only a member/Archon may widen at all. This
+// helper just performs the append once that gate has passed. Returns the updated
+// goal row, or null for an unknown id.
+
+async function addGoalScopeModules({ goalId, modules }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `UPDATE goals
+        SET scope_modules = COALESCE((
+              SELECT array_agg(DISTINCT m ORDER BY m)
+                FROM unnest(scope_modules || $2::text[]) AS m
+            ), '{}'),
+            updated_at = now()
+      WHERE id = $1
+      RETURNING ${GOAL_COLS}`,
+    [goalId, modules]
+  );
+  return rows[0] ?? null;
+}
+
+// setGoalSuccessor — the rescope carry-forward link (ADR 0086 §6 / BV1.R64). Stamps
+// an (achieved) goal's succeeded_by_goal_id to point at the new-version goal that
+// continues it, so the version→version lineage is queryable. Bumps updated_at.
+// Returns the updated row, or null if the goal id is unknown.
+
+async function setGoalSuccessor({ goalId, successorId }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `UPDATE goals
+        SET succeeded_by_goal_id = $2, updated_at = now()
+      WHERE id = $1
+      RETURNING ${GOAL_COLS}`,
+    [goalId, successorId]
+  );
+  return rows[0] ?? null;
+}
+
+// -------------------------------------------------------------------------
+// Private goals: visibility + the invite / join-request queue (task 1951 / ADR
+// 0112). The query layer only — the routes (task 1952) hold the authorization
+// wall (owner|manager|Archon for invites/approvals; the invitee for accepting).
+// -------------------------------------------------------------------------
+
+// setGoalVisibility — flip a goal public|private (ADR 0112). 'public' is the
+// migration default = today's open-join; 'private' means non-members can't
+// self-join (they are invited or request+approved). Bumps updated_at. Returns
+// the updated goal row, or null for an unknown id. The route gates WHO may call
+// this (authorizeGoalManagement: owner|manager|Archon); this helper just writes.
+async function setGoalVisibility({ goalId, visibility }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `UPDATE goals
+        SET visibility = $2, updated_at = now()
+      WHERE id = $1
+      RETURNING ${GOAL_COLS}`,
+    [goalId, visibility]
+  );
+  return rows[0] ?? null;
+}
+
+// createMembershipRequest — open a pending invite (kind='invite', a manager asks
+// builder_id in) or join-request (kind='request', the builder asks to join). The
+// partial-unique index (one pending row per goal+builder) means a duplicate ask
+// raises 23505; we surface it as a typed PENDING_EXISTS the route maps to 409 (the
+// access_requests precedent). createdBy is who opened it. Returns the new row.
+async function createMembershipRequest({ goalId, builderId, kind, createdBy = null, note = null }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  try {
+    const { rows } = await activePool.query(
+      `INSERT INTO goal_membership_requests (goal_id, builder_id, kind, created_by, note)
+            VALUES ($1, $2, $3, $4, $5)
+       RETURNING ${MEMBERSHIP_REQUEST_COLS}`,
+      [goalId, builderId, kind, createdBy, note]
+    );
+    return rows[0];
+  } catch (err) {
+    if (err && err.code === '23505') {
+      const e = new Error('a pending membership request already exists for this builder on this goal');
+      e.code = 'PENDING_EXISTS';
+      throw e;
+    }
+    throw err;
+  }
+}
+
+// getMembershipRequest — one request row by id, or null. The route reads it to
+// check kind + goal_id + status + builder_id before authorizing a resolve.
+async function getMembershipRequest(id, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `SELECT ${MEMBERSHIP_REQUEST_COLS} FROM goal_membership_requests WHERE id = $1`,
+    [id]
+  );
+  return rows[0] ?? null;
+}
+
+// resolveMembershipRequest — close a pending request. status is one of
+// 'accepted' | 'rejected' | 'cancelled'. The WHERE status='pending' guard makes
+// it atomic + idempotent: a lost race (already resolved / gone) returns null, so
+// the route never double-adds a member off a re-submitted resolve. resolvedBy is
+// who closed it. The membership add itself is the route's job (addGoalMember on
+// accept/approve). Returns the updated row, or null when nothing was pending.
+async function resolveMembershipRequest({ id, status, resolvedBy = null }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `UPDATE goal_membership_requests
+        SET status = $2, resolved_by = $3, resolved_at = now(), updated_at = now()
+      WHERE id = $1 AND status = 'pending'
+     RETURNING ${MEMBERSHIP_REQUEST_COLS}`,
+    [id, status, resolvedBy]
+  );
+  return rows[0] ?? null;
+}
+
+// acceptMembershipRequestAndAddMember — the ACCEPT/APPROVE half done ATOMICALLY
+// (task 1952 review fix). Resolving a request to 'accepted' and adding the
+// member used to be two separate queries: an error between them left an
+// 'accepted' row with no membership — unrecoverable, since the row is no longer
+// pending and can't be re-accepted. One CTE makes them a single statement: the
+// member INSERT feeds off the SAME UPDATE (the createGoal / transferGoalOwnership
+// atomic-CTE precedent), so either both land or neither does. The UPDATE's
+// WHERE status='pending' keeps it idempotent — a lost race (already resolved /
+// gone) resolves nothing, adds nobody, and returns null. On the (near-impossible,
+// since the create routes reject an existing member) membership conflict the
+// existing membership_kind is PRESERVED, so an approve never silently demotes a
+// manager.
+// Returns { request, member } or null.
+async function acceptMembershipRequestAndAddMember({ id, resolvedBy = null }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `WITH resolved AS (
+       UPDATE goal_membership_requests
+          SET status = 'accepted', resolved_by = $2, resolved_at = now(), updated_at = now()
+        WHERE id = $1 AND status = 'pending'
+       RETURNING ${MEMBERSHIP_REQUEST_COLS}
+     ), added AS (
+       INSERT INTO goal_members (goal_id, builder_id, membership_kind)
+       SELECT goal_id, builder_id, 'member' FROM resolved
+       ON CONFLICT (goal_id, builder_id) DO UPDATE SET membership_kind = goal_members.membership_kind
+       RETURNING goal_id, builder_id, membership_kind, joined_at
+     )
+     SELECT (SELECT to_jsonb(r) FROM resolved r) AS request,
+            (SELECT to_jsonb(a) FROM added a)    AS member`,
+    [id, resolvedBy]
+  );
+  const request = rows[0] && rows[0].request;
+  if (!request) return null;   // nothing was pending — no resolve, no member added
+  return { request, member: rows[0].member };
+}
+
+// listInboxFor — the home-page inbox (task 1954) for one builder, three buckets:
+//   • invitations     — pending invites addressed to ME (accept/decline), with the
+//                        goal + who invited me.
+//   • joinRequests    — pending join-requests on goals I OWN or MANAGE
+//                        (goals.created_by = me OR a goal_members 'lead' row for me),
+//                        with the goal + the asker's identity + their note (approve/deny).
+//   • myPendingRequests — my own outstanding join-requests (so I can see/withdraw them).
+// Requests only ever exist on private goals someone made private, so an
+// owner/manager always exists — a request never lands in nobody's inbox. Archons
+// can still approve any request via the route; the inbox stays scoped to what a
+// builder owns/manages so it doesn't drown an Archon in every goal's queue.
+async function listInboxFor(builderId, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const [invitations, joinRequests, myPendingRequests] = await Promise.all([
+    activePool.query(
+      `SELECT r.id, r.goal_id, r.kind, r.status, r.note, r.created_at,
+              g.title AS goal_title, g.version_id, g.visibility,
+              ib.github_login AS invited_by_login, ib.display_name AS invited_by_name,
+              ib.avatar_url AS invited_by_avatar
+         FROM goal_membership_requests r
+         JOIN goals g ON g.id = r.goal_id
+         LEFT JOIN builders ib ON ib.id = r.created_by
+        WHERE r.kind = 'invite' AND r.status = 'pending' AND r.builder_id = $1
+        ORDER BY r.created_at, r.id`,
+      [builderId]
+    ),
+    activePool.query(
+      `SELECT r.id, r.goal_id, r.builder_id, r.kind, r.status, r.note, r.created_at,
+              g.title AS goal_title, g.version_id, g.visibility,
+              b.github_login, b.display_name, b.avatar_url, b.rank
+         FROM goal_membership_requests r
+         JOIN goals g ON g.id = r.goal_id
+         LEFT JOIN builders b ON b.id = r.builder_id
+        WHERE r.kind = 'request' AND r.status = 'pending'
+          AND (g.created_by = $1
+               OR EXISTS (SELECT 1 FROM goal_members gm
+                           WHERE gm.goal_id = g.id AND gm.builder_id = $1 AND gm.membership_kind = 'lead'))
+        ORDER BY r.created_at, r.id`,
+      [builderId]
+    ),
+    activePool.query(
+      `SELECT r.id, r.goal_id, r.status, r.note, r.created_at,
+              g.title AS goal_title, g.version_id, g.visibility
+         FROM goal_membership_requests r
+         JOIN goals g ON g.id = r.goal_id
+        WHERE r.kind = 'request' AND r.status = 'pending' AND r.builder_id = $1
+        ORDER BY r.created_at, r.id`,
+      [builderId]
+    ),
+  ]);
+  return {
+    invitations: invitations.rows,
+    joinRequests: joinRequests.rows,
+    myPendingRequests: myPendingRequests.rows,
+  };
+}
+
+// listPendingRequestsForGoal — the goals-page manager view (task 1953): every
+// pending row on a goal, BOTH kinds (invites the goal has outstanding + join-
+// requests awaiting approval), with the counterpart builder's identity. Ordered
+// kind-then-time so invites and requests group predictably.
+async function listPendingRequestsForGoal(goalId, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `SELECT r.id, r.goal_id, r.builder_id, r.kind, r.status, r.note, r.created_at,
+            b.github_login, b.display_name, b.avatar_url, b.rank
+       FROM goal_membership_requests r
+       LEFT JOIN builders b ON b.id = r.builder_id
+      WHERE r.goal_id = $1 AND r.status = 'pending'
+      ORDER BY r.kind, r.created_at, r.id`,
+    [goalId]
+  );
+  return rows;
+}
+
+module.exports = {
+  acceptMembershipRequestAndAddMember,
+  achieveGoalIfComplete,
+  addGoalMember,
+  addGoalScopeModules,
+  createGoal,
+  createMembershipRequest,
+  getGoal,
+  getGoalDependencies,
+  getGoalMember,
+  getMembershipRequest,
+  isGoalMember,
+  listActiveClaimsForTasks,
+  listCriteriaForGoal,
+  listGoalMembers,
+  listGoals,
+  listInboxFor,
+  listPendingRequestsForGoal,
+  removeGoalMember,
+  reorderGoals,
+  requestClaimRelease,
+  rescopeTaskTouches,
+  resolveMembershipRequest,
+  setGoalMembershipKind,
+  setGoalStatus,
+  setGoalSuccessor,
+  setGoalVisibility,
+  transferGoalOwnership,
+};