@bongos/core 1.19.316 → 1.19.317

package/modules/lifecycle/db-grade.js

@@ -0,0 +1,233 @@
+// modules/lifecycle/db-grade.js — applyGrade — writes the grader result and promotes completed→confirmed.
+//
+// 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 4561-4773 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, withTx } = api;
+const seams = api;
+const { logGradeAttempt } = require('./db-analytics.js');
+const { mostRecentClaimHolderId } = require('./db-shared.js');
+
+// applyGrade — V3.R18 (#209). Writes the subagent grader result to task_grades
+// and, if the grade passed, promotes completed→confirmed + awards credits.
+//
+// Inputs (the route handler validates + scores the subagent JSON before
+// calling this, so we accept a pre-built grade-result):
+//   taskId       — number
+//   builderId    — current authenticated builder (must own the task's most-
+//                  recent claim; the route handler enforces this)
+//   gradeResult  — { score, passed, threshold, grader_kind, grader_version,
+//                    rubric_scores, signals, notes_md, issues }
+//
+// Returns: { taskId, taskTitle, taskStatus, creditsAwarded, justUnlocked,
+//            grade: {score, passed, ...} }.
+//
+// Idempotent: the task_grades row is upsert-on-task_id (a re-grade overwrites);
+// credit_log is guarded by an existence check on (task_id, 'task.confirmed').
+
+async function applyGrade({ taskId, builderId, gradeResult, committedFiles = null, diffHash = null }, deps = {}) {
+  // committedFiles (touches[] cleanup [3/8] / task 878): the real committed
+  // changed-files for this ship, computed client-side by ship.js. Threaded to
+  // evaluateAfterShip so the prefix-keyed shipper badges reflect the actual
+  // diff rather than the predicted touches[]. Optional — null/absent falls back
+  // to touches[] inside evaluateAfterShip.
+  // #871 test seam (mirrors confirmTask's #538 seam): a caller-supplied pool is
+  // honored ONLY under NODE_ENV==='test' so tests/grade_attribution.mjs can drive
+  // the txn with a SQL-aware fakeClient. Production callers omit deps → module pool.
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const result = await withTx(async (client) => {
+    const { rows: taskRows } = await client.query(
+      `SELECT id, title, status, credits_reward, kind FROM tasks WHERE id = $1 FOR UPDATE`,
+      [taskId]
+    );
+    if (taskRows.length === 0) {
+      throw Object.assign(new Error('task not found'), { code: 'TASK_NOT_FOUND' });
+    }
+    const task = taskRows[0];
+
+    // The grade can only land while the task is at `completed` (just shipped
+    // and awaiting grading) or `confirmed` (already promoted by a prior grade
+    // pass — re-grading is allowed and writes a fresh row, but it does not
+    // re-award credits or re-evaluate achievements). At `shipped`/`backlog`/
+    // `active`/`ready`/`blocked`/`abandoned` the grade has no lifecycle target,
+    // so we refuse.
+    if (!['completed', 'confirmed'].includes(task.status)) {
+      throw Object.assign(new Error(`task is at ${task.status}; grade only applies at completed/confirmed`), {
+        code: 'TASK_NOT_GRADABLE',
+        current_status: task.status,
+      });
+    }
+
+    // SECURITY (#871 — mirrors the #661 confirmTask fix): credit + attribute the
+    // builder who actually DID the work — the task's most-recent claim holder —
+    // NEVER the caller of this endpoint. Before this fix applyGrade set
+    // tasks.shipped_by and the credit_log row to `builderId` (req.builder.id from
+    // the route), so a builder who POSTed a fabricated passing grade on ANOTHER
+    // builder's `completed` task captured both the ship attribution AND the
+    // drachmae. POST /tasks/:id/grade now also gates to the claim holder/Archon,
+    // but we fix the attribution here too: defense-in-depth, and it is the
+    // CORRECT behaviour for the Archon `--regrade` path where the caller is not
+    // the worker. Fall back to the caller only if the task has no claim at all
+    // (degenerate — e.g. status set directly via SQL) so a legit grade is never
+    // refused.
+    const creditedBuilderId = (await mostRecentClaimHolderId(client, taskId)) ?? builderId;
+
+    // Upsert the grade row. The subagent's issues[] is embedded into the
+    // signals jsonb so /me + the public dashboard can surface structured
+    // failure detail without a schema change. (task_grades has no `issues`
+    // column.)
+    const signalsForRow = {
+      ...(gradeResult.signals || {}),
+      issues: gradeResult.issues || [],
+    };
+    await client.query(
+      `INSERT INTO task_grades
+         (task_id, score, passed, threshold, grader_kind, grader_version,
+          rubric_scores, signals, notes_md, diff_hash)
+       VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb, $8::jsonb, $9, $10)
+       ON CONFLICT (task_id) DO UPDATE SET
+         score          = EXCLUDED.score,
+         passed         = EXCLUDED.passed,
+         threshold      = EXCLUDED.threshold,
+         grader_kind    = EXCLUDED.grader_kind,
+         grader_version = EXCLUDED.grader_version,
+         rubric_scores  = EXCLUDED.rubric_scores,
+         signals        = EXCLUDED.signals,
+         notes_md       = EXCLUDED.notes_md,
+         diff_hash      = EXCLUDED.diff_hash,
+         graded_at      = now()`,
+      [
+        taskId,
+        gradeResult.score,
+        gradeResult.passed,
+        gradeResult.threshold,
+        gradeResult.grader_kind,
+        gradeResult.grader_version,
+        JSON.stringify(gradeResult.rubric_scores || {}),
+        JSON.stringify(signalsForRow),
+        gradeResult.notes_md ?? null,
+        diffHash ?? null,
+      ]
+    );
+
+    let finalStatus = task.status;
+    let creditsAwarded = 0;
+    let creditsRaw = 0;
+    let creditsMultiplier = 1.0;
+    let ideaBonus = null; // { ideaBonusAwarded, bonusBuilderId, ideaId } | null
+    let netNegativeBonus = 0;
+    let subtractorUnlocks = [];
+    let justUnlocked = [];
+    // Credit allocation + gamification carved to modules/economy/ (BV1.R77 / ADR
+    // 0093 §1-2): resolve the `reward` kernel port ONCE; every credit/achievement
+    // write below runs inside this same txn via the resolved provider. The
+    // state-machine SQL (FOR UPDATE, task_grades upsert, UPDATE tasks status,
+    // claim-holder lookup, logGradeAttempt) stays here in the lifecycle.
+    const reward = seams.resolveOptional('reward');
+    if (gradeResult.passed && task.status === 'completed') {
+      await client.query(
+        `UPDATE tasks
+            SET status = 'confirmed',
+                shipped_by = COALESCE(shipped_by, $2),
+                updated_at = now()
+          WHERE id = $1 AND status = 'completed'`,
+        [taskId, creditedBuilderId]
+      );
+      finalStatus = 'confirmed';
+
+      // V3.R93 (#354): reward simplification. A ship whose diff removed more
+      // lines than it added earns a small flat bonus, written as its own
+      // credit_log row (reason='ship.net_negative') with a self-describing
+      // description. Idempotent on (task_id, reason) so a re-grade is a no-op.
+      // diff_stats arrives via gradeResult.signals (ship.js decorates it).
+      //
+      // Awarded BEFORE the achievement evaluators so the Subtractor achievement
+      // (which counts the builder's net-negative ships) sees the current ship's
+      // bonus row in this same transaction.
+      const nn = await reward.awardNetNegativeBonus(
+        client, creditedBuilderId, taskId, gradeResult.signals?.diff_stats
+      );
+      netNegativeBonus = nn.bonus;
+      subtractorUnlocks = nn.justUnlocked;
+
+      // ADR 0120 "pay on land": the per-task credit + idea-promotion bonus are
+      // NO LONGER awarded at grader-confirm. They land at the confirmed→shipped
+      // flip (shipTask → awardLandingCredit, keyed 'task.shipped'), so a task
+      // that strands at 'confirmed' pays nothing until its code is on `main`.
+      // The net-negative (simplification) bonus above STAYS here — it derives
+      // from grade-time diff_stats that only exist at grade time, so it cannot
+      // move to shipTask (and is outside ADR 0120's two named reward writes).
+      // creditsAwarded/creditsRaw/creditsMultiplier/ideaBonus stay 0/null at
+      // confirm for a stable return contract; the credit lands at ship. The
+      // credit-crossing achievement evaluator (evaluateAfterCreditAward) moves
+      // with the credit to shipTask's reconcile; here we still fire the
+      // ship/subtractor unlocks that DON'T depend on the per-task credit.
+      const shipUnlocks = await reward.evaluateAfterShip(client, creditedBuilderId, taskId, committedFiles);
+      justUnlocked = [...subtractorUnlocks, ...shipUnlocks];
+
+      // task 1679: state-based safety net. The granular evaluators above are
+      // boundary-/path-sensitive — breaking-the-100c-bar only fires when a
+      // per-task confirm credit crosses 100 (the session cost-plus reward never
+      // hits it), and streaks key off current_streak. reconcile re-checks every
+      // achievement against current state and unlocks any straggler. It is
+      // idempotent: anything the granular calls just unlocked is visible in this
+      // txn, so reconcile's alreadyUnlocked guard skips it (no dup awards).
+      // SAVEPOINT-wrapped so it can never fail the grade-confirm.
+      if (reward && reward.reconcileBuilderAchievements) {
+        await client.query('SAVEPOINT ach_reconcile');
+        try {
+          const reconciled = await reward.reconcileBuilderAchievements(client, creditedBuilderId, { taskId });
+          await client.query('RELEASE SAVEPOINT ach_reconcile');
+          if (reconciled.length) justUnlocked = [...justUnlocked, ...reconciled];
+        } catch (_) {
+          await client.query('ROLLBACK TO SAVEPOINT ach_reconcile');
+        }
+      }
+    }
+    // !passed → task_grades row written above; task stays at completed; no
+    // credits, no achievements. Builder can manual-confirm via /confirm if the
+    // grade was wrong.
+
+    return {
+      taskId,
+      taskTitle: task.title,
+      taskStatus: finalStatus,
+      creditedBuilderId, // #871: the builder credited/attributed (claim holder, not caller)
+      creditsAwarded,
+      creditsRaw,
+      creditsMultiplier,
+      ideaBonus, // V3.R27 (#247): { ideaBonusAwarded, bonusBuilderId, ideaId } | null
+      netNegativeBonus,
+      advanceToMerge: finalStatus === 'confirmed',
+      justUnlocked,
+      grade: {
+        score: gradeResult.score,
+        passed: gradeResult.passed,
+        threshold: gradeResult.threshold,
+        rubric_scores: gradeResult.rubric_scores || {},
+        notes_md: gradeResult.notes_md ?? null,
+        issues: gradeResult.issues || [],
+      },
+    };
+  }, { pool: activePool });
+
+  // 6D.6 (ADR 0027): record this grade ATTEMPT in the append-only log so
+  // re-grade thrash is countable (task_grades is upsert-unique). Post-commit +
+  // best-effort: logGradeAttempt uses a pooled connection and swallows its own
+  // errors, so it can never roll back or block the grade that just committed.
+  await logGradeAttempt({ taskId, builderId, passed: gradeResult.passed, score: gradeResult.score });
+
+  return result;
+}
+
+module.exports = {
+  applyGrade,
+};

package/modules/lifecycle/db-overrides.js

@@ -0,0 +1,181 @@
+// modules/lifecycle/db-overrides.js — the grader override-request flow (builder asks an Archon to confirm anyway).
+//
+// 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 4401-4560 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, withTx } = api;
+const { mostRecentClaimHolderId } = require('./db-shared.js');
+
+// task override requests — V3.R74 (#293). Rare path: a builder whose ship was
+// rejected by the subagent grader (task stays at 'completed', no credits)
+// believes the grader was wrong and asks an Archon to confirm anyway.
+
+
+async function createOverrideRequest({ taskId, requesterId, rationale }) {
+  const { rows: taskRows } = await pool.query(
+    `SELECT id, status FROM tasks WHERE id = $1`,
+    [taskId]
+  );
+  if (taskRows.length === 0) {
+    throw Object.assign(new Error('task not found'), { code: 'TASK_NOT_FOUND' });
+  }
+  if (taskRows[0].status !== 'completed') {
+    throw Object.assign(new Error('task not in completed state'), {
+      code: 'TASK_NOT_COMPLETED',
+      currentStatus: taskRows[0].status,
+    });
+  }
+  try {
+    const { rows } = await pool.query(
+      `INSERT INTO task_override_requests (task_id, requested_by_builder_id, rationale)
+       VALUES ($1, $2, $3)
+       RETURNING id, task_id, requested_by_builder_id, rationale, status, created_at`,
+      [taskId, requesterId, rationale]
+    );
+    return rows[0];
+  } catch (err) {
+    // uniq_task_override_requests_open_per_task — one open request per task.
+    if (err && err.code === '23505') {
+      throw Object.assign(new Error('open request already exists for this task'), {
+        code: 'OPEN_REQUEST_EXISTS',
+      });
+    }
+    throw err;
+  }
+}
+
+
+async function listOverrideRequests({ status = 'open', limit = 50 } = {}) {
+  const { rows } = await pool.query(
+    `SELECT r.id, r.task_id, r.requested_by_builder_id, r.rationale, r.status,
+            r.decided_by_builder_id, r.decided_at, r.decision_note, r.created_at,
+            t.title AS task_title, t.status AS task_status, t.version_id, t.credits_reward,
+            b.github_login AS requester_login, b.display_name AS requester_display_name
+       FROM task_override_requests r
+       JOIN tasks t ON t.id = r.task_id
+       JOIN builders b ON b.id = r.requested_by_builder_id
+      WHERE r.status = $1
+      ORDER BY r.created_at DESC
+      LIMIT $2`,
+    [status, limit]
+  );
+  return rows;
+}
+
+
+async function decideOverrideRequest({ requestId, archonId, decision, note }, deps = {}) {
+  if (decision !== 'approve' && decision !== 'deny') {
+    throw Object.assign(new Error('bad decision'), { code: 'BAD_DECISION' });
+  }
+  // `deps.pool` is a TEST-ONLY injection seam (#538) — honored ONLY when
+  // NODE_ENV==='test' (not merely "not production"), so an unset NODE_ENV in a
+  // prod-like box can't accidentally activate it, and a future route that
+  // naively forwarded a caller-supplied pool could never swap the DB connection
+  // in prod (hacker review #538). It lets tests drive the txn with a fakeClient
+  // (same pattern as credit_grant.mjs). Production callers omit it → module pool.
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  return withTx(async (client) => {
+    // RETURNING requested_by_builder_id so the approve path doesn't re-read the
+    // row it just locked (#538): the work was the ORIGINAL REQUESTER's, and both
+    // the credit AND the ship attribution must go to them.
+    const { rows } = await client.query(
+      `UPDATE task_override_requests
+          SET status = $1,
+              decided_by_builder_id = $2,
+              decided_at = now(),
+              decision_note = $3
+        WHERE id = $4 AND status = 'open'
+        RETURNING id, task_id, status, requested_by_builder_id`,
+      [decision === 'approve' ? 'approved' : 'denied', archonId, note ?? null, requestId]
+    );
+    if (rows.length === 0) {
+      throw Object.assign(new Error('request not open'), { code: 'REQUEST_NOT_OPEN' });
+    }
+    const row = rows[0];
+
+    let confirmResult = null;
+    if (decision === 'approve') {
+      // BOTH the credit AND the ship attribution (shipped_by, which drives the
+      // builders' hall + peer-vote feed) go to the builder who actually DID the
+      // work — the task's most-recent claim holder — never the approving Archon.
+      //
+      // (#538: previously shipped_by fell to the Archon via
+      // COALESCE(shipped_by, archonId), misattributing the ship even though the
+      // credit was routed correctly. That fix attributed everything to the
+      // override REQUESTER. SR-16 / #996 tightens it once more: with the new
+      // ownership gate on POST /tasks/:id/override-request the requester is
+      // already the claim holder OR an Archon, so resolving the CLAIM HOLDER
+      // here — the same attribution source applyGrade/confirmTask use via
+      // getLastClaimHolder — keeps the credit on the worker even when an Archon
+      // files the request on a builder's behalf. Falls back to the requester
+      // only when the task has no claim on record at all, so a legitimate
+      // degenerate edge — e.g. status set directly via SQL — is never refused.)
+      const creditedBuilderId = (await mostRecentClaimHolderId(client, row.task_id)) ?? row.requested_by_builder_id;
+      // requested_by_builder_id is NOT NULL in the schema, so this can only be
+      // null in a degenerate state. Rather than silently fall back to archonId —
+      // which would re-create the exact misattribution #538 fixed — refuse the
+      // approval if there is neither a claim holder nor a requester to credit.
+      // Rolls back so the override stays open for inspection.
+      if (creditedBuilderId == null) {
+        throw Object.assign(
+          new Error(`override request ${requestId} has no claim holder or requester to credit`),
+          { code: 'OVERRIDE_NO_REQUESTER' }
+        );
+      }
+
+      // Flip the task completed→confirmed and attribute the ship to the
+      // requester. Inlined here (rather than calling confirmTask) because
+      // confirmTask opens its own client/transaction; we want one atomic step.
+      const { rows: taskRows } = await client.query(
+        `UPDATE tasks
+            SET status = 'confirmed',
+                shipped_by = COALESCE(shipped_by, $2),
+                updated_at = now()
+          WHERE id = $1 AND status = 'completed'
+          RETURNING id, title, credits_reward, kind`,
+        [row.task_id, creditedBuilderId]
+      );
+      if (taskRows.length === 0) {
+        // Task was raced to another terminal state (e.g. someone manually
+        // confirmed it between the request and the decision). The approval row
+        // still stands as the audit signal; we just don't double-flip the task.
+        // creditedBuilderId is included for a consistent return shape so callers
+        // can always destructure it from confirmResult without a guard (#538).
+        confirmResult = { taskFlipped: false, creditsAwarded: 0, ideaBonus: null, creditedBuilderId };
+      } else {
+        // ADR 0120 "pay on land": the override-approval path flips the task
+        // completed→confirmed and attributes shipped_by to the claim holder
+        // (above), but the per-task credit + idea bonus now wait for the land
+        // (shipTask → awardLandingCredit, keyed 'task.shipped'). A stranded
+        // override-confirmed task pays nothing until its code is on `main`.
+        // creditsAwarded/ideaBonus stay in the return shape (0 / null) for a
+        // stable contract; thetes graduation was already ship-time (#704).
+        confirmResult = { taskFlipped: true, creditsAwarded: 0, ideaBonus: null, creditedBuilderId };
+      }
+    }
+
+    return { request: row, confirmResult };
+  }, { pool: activePool });
+}
+
+// Credit allocation carved into modules/economy/credits.js (BV1.R77 / ADR 0093
+// §§1-2): KIND_MULTIPLIERS / IDEA_BONUS_FRACTION / REWARD_MARGIN_PCT,
+// computeSessionTokenReward, applyKindMultiplier, insertMultipliedConfirmCredit,
+// maybeAwardIdeaPromotionBonus, awardSessionTokenReward, and the net-negative
+// (Subtractor) bonus all left this monolith. The lifecycle above (applyGrade /
+// confirmTask / decideOverrideRequest / upsertSessionRecordWithReward) resolves
+// them through the `reward` kernel port, passing its own tx client.
+
+module.exports = {
+  createOverrideRequest,
+  decideOverrideRequest,
+  listOverrideRequests,
+};