@bongos/core 1.21.175 → 1.21.177

package/tests/served_paths_shipped.mjs

@@ -2,7 +2,7 @@
 //
 // GUARD (task 2078): every static asset serve-internal.js reads at runtime from the
 // core tree MUST be included in the packaged core — i.e. isPublishable() per
-// scripts/gds/publish-manifest.js. A standalone instance runs the PACKAGED core
+// scripts/bongos/publish-manifest.js. A standalone instance runs the PACKAGED core
 // (@bongos/core, ADR 0108), so a served path the publish boundary EXCLUDES is
 // simply absent on the box and 404s.
 //
@@ -27,7 +27,7 @@ import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const { isPublishable } = require('../scripts/gds/publish-manifest.js');
+const { isPublishable } = require('../scripts/bongos/publish-manifest.js');
 
 const SERVE_INTERNAL = path.join(ROOT, 'src/bongos/serve-internal.js');
 
@@ -136,7 +136,7 @@ test('every ROOT-served asset ships in the core package (isPublishable)', () =>
     [],
     `serve-internal.js reads these from ROOT but the publish boundary EXCLUDES them, so the ` +
       `packaged core (@bongos/core) omits them and a standalone 404s (task 2078): ${offenders.join(', ')}. ` +
-      `Fix: add each to PUBLISH_ALLOWLIST in scripts/gds/publish-manifest.js (or, if truly host-only, ` +
+      `Fix: add each to PUBLISH_ALLOWLIST in scripts/bongos/publish-manifest.js (or, if truly host-only, ` +
       `document it in INTENTIONALLY_UNSHIPPED in this test).`
   );
 });

package/tests/session_506_regression.mjs

@@ -20,7 +20,7 @@ import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
-const ev = require('../scripts/gds/session-eval.js');
+const ev = require('../scripts/bongos/session-eval.js');
 const fixture = require('./fixtures/session-506-digest.json');
 
 let passed = 0;

package/tests/session_accessibility.mjs

@@ -167,7 +167,7 @@ test('jargon: multi-token and punctuated terms still anchor', () => {
 });
 
 test('terminal-first: only counted when the subject HAS a click-path', () => {
-  const withUi = acc.countTerminalWhereUiExists(['run `node scripts/gds/api-key.js` to set your api key']);
+  const withUi = acc.countTerminalWhereUiExists(['run `node scripts/bongos/api-key.js` to set your api key']);
   assert.equal(withUi.count, 1);
   assert.match(withUi.evidence, /Settings/, 'the evidence names where the button is');
 

package/tests/session_caps.mjs

@@ -245,7 +245,7 @@ console.log(`\n${passed} passed, ${failed} failed`);
 // the loop down while fetch's handles were still closing. run-unit-tests.js reads
 // the exit code, so a fully-passing suite reported FAILED in every Windows
 // baseline, which trains builders to wave off real failures as environmental.
-// Setting the code and letting the loop drain is the same cure scripts/gds/
+// Setting the code and letting the loop drain is the same cure scripts/bongos/
 // CLAUDE.md documents for the CLI scripts (cliExit) and tests/cli_exit_no_abort.mjs
 // guards for api.js. The closeAllConnections() above is the other half: a hard
 // exit MASKS a leaked handle, so removing it without releasing the sockets would

package/tests/session_cost.mjs

@@ -10,7 +10,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 const require = createRequire(import.meta.url);
-const sc = require('../scripts/gds/session-cost.js');
+const sc = require('../scripts/bongos/session-cost.js');
 
 const M = 1_000_000;
 function line(model, usage) {

package/tests/session_digest.mjs

@@ -12,7 +12,7 @@ import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
-const sd = require('../scripts/gds/session-digest.js');
+const sd = require('../scripts/bongos/session-digest.js');
 
 let passed = 0;
 let failed = 0;
@@ -77,7 +77,7 @@ test('parseHookInput: partial payload (only session_id) leaves the rest for fall
 //
 // NUL is built with String.fromCharCode(0) so this FILE stays plain ASCII: a
 // literal NUL in the source would make git and grep treat it as binary.
-const ship = require('../scripts/gds/ship.js');
+const ship = require('../scripts/bongos/ship.js');
 const NUL = String.fromCharCode(0);
 const hasNul = (v) => typeof v === 'string' && v.indexOf(NUL) !== -1;
 

package/tests/session_eval.mjs

@@ -1,7 +1,7 @@
 // tests/session_eval.mjs
 //
 // Unit tests for the BFG session-inefficiency analysis engine (6D.3, ADR 0027)
-// — the PURE classify / compute / detect functions in scripts/gds/session-eval.js.
+// — the PURE classify / compute / detect functions in scripts/bongos/session-eval.js.
 // Includes a #506-SHAPED fixture (mostly GDS plumbing + tool errors, a tiny real
 // edit) that must come out "wasteful" with the expected footguns — a preview of
 // the dedicated #506-corpus regression gate (6D.5).
@@ -12,7 +12,7 @@ import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
-const ev = require('../scripts/gds/session-eval.js');
+const ev = require('../scripts/bongos/session-eval.js');
 
 let passed = 0;
 let failed = 0;
@@ -36,7 +36,7 @@ test('classifyTurn: Edit/Write → work', () => {
 });
 
 test('classifyTurn: Bash driving GDS plumbing → ceremony', () => {
-  assert.equal(ev.classifyTurn({ role: 'assistant', tools: ['Bash'], snippet: 'node scripts/gds/claim.js 540' }), 'ceremony');
+  assert.equal(ev.classifyTurn({ role: 'assistant', tools: ['Bash'], snippet: 'node scripts/bongos/claim.js 540' }), 'ceremony');
   assert.equal(ev.classifyTurn({ role: 'assistant', tools: ['Bash'], snippet: 'git commit -m fix' }), 'ceremony');
   assert.equal(ev.classifyTurn({ role: 'assistant', tools: ['Bash'], snippet: 'running the grade' }), 'ceremony');
 });
@@ -90,13 +90,13 @@ test('interpretCorpusSearch: empty --min-karma mining pass is benign (no qualifi
 function fixture506() {
   return [
     // claim plumbing (ceremony) — big context tokens
-    { role: 'assistant', tools: ['Bash'], snippet: 'node scripts/gds/claim.js 506', in: 6000, out: 200, cache_read: 0, cache_creation: 0 },
+    { role: 'assistant', tools: ['Bash'], snippet: 'node scripts/bongos/claim.js 506', in: 6000, out: 200, cache_read: 0, cache_creation: 0 },
     { role: 'user', tool_results: 1 }, // clean result
     // the actual one-line edit (work) — small
     { role: 'assistant', tools: ['Edit'], snippet: 'tweak welcome copy line', in: 400, out: 60 },
     { role: 'user', tool_results: 1 },
     // ship → API enum error (#514 class)
-    { role: 'assistant', tools: ['Bash'], snippet: 'node scripts/gds/ship.js 506 --kind chore', in: 3000, out: 150 },
+    { role: 'assistant', tools: ['Bash'], snippet: 'node scripts/bongos/ship.js 506 --kind chore', in: 3000, out: 150 },
     { role: 'user', tool_results: 1, tool_errors: 1, snippet: 'error: bad_kind — kind must be one of: feature, bug' },
     // recovery: guess again
     { role: 'assistant', tools: ['Bash'], snippet: 'retry with kind=feature', in: 2500, out: 120 },
@@ -127,7 +127,7 @@ function fixtureCacheMarathon() {
     { role: 'user', tool_results: 1 },
     // …drowned in many small ceremony turns (claim/ship/git/status churn)
     ...Array.from({ length: 8 }, (_, k) => ([
-      { role: 'assistant', tools: ['Bash'], snippet: `node scripts/gds/status.js step ${k}`, in: 300, out: 40, cache_read: 0, cache_creation: 0 },
+      { role: 'assistant', tools: ['Bash'], snippet: `node scripts/bongos/status.js step ${k}`, in: 300, out: 40, cache_read: 0, cache_creation: 0 },
       { role: 'user', tool_results: 1 },
     ])).flat(),
   ];

package/tests/session_index.mjs

@@ -10,7 +10,7 @@ import path from 'node:path';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const GEN = path.join(ROOT, 'scripts', 'gds', 'gen-session-index.js');
+const GEN = path.join(ROOT, 'scripts', 'bongos', 'gen-session-index.js');
 const gen = require(GEN); // require.main-guarded → importing runs no main()
 
 function run(args) {

package/tests/session_records.mjs

@@ -1,7 +1,7 @@
 // tests/session_records.mjs
 //
 // Unit tests for the BFG session-inefficiency evaluator's upload path (6D.1,
-// ADR 0027). Covers the two PURE functions in scripts/gds/ship.js that do the
+// ADR 0027). Covers the two PURE functions in scripts/bongos/ship.js that do the
 // real work client-side: scrubSecrets (ADR 0022 redaction) and
 // buildSessionDigest (transcript -> compact metadata digest). The network
 // upload + ship orchestration around them is best-effort + degradable and is
@@ -20,7 +20,7 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 
 const require = createRequire(import.meta.url);
-const { scrubSecrets, snippetOf, buildSessionDigest, resolveTranscriptPath, encodeProjectPath } = require('../scripts/gds/ship.js');
+const { scrubSecrets, snippetOf, buildSessionDigest, resolveTranscriptPath, encodeProjectPath } = require('../scripts/bongos/ship.js');
 
 // Secret-shaped fakes built at runtime — see the NOTE above.
 const FAKE = {
@@ -256,7 +256,7 @@ test('resolveTranscriptPath tolerates a null/absent projectDirs list', () => {
 //
 // Claude Code encodes the project dir by replacing every NON-ALPHANUMERIC char
 // with '-' (the rule already documented + implemented in
-// scripts/gds/onboarding-config.js). ship.js replaced only '/' and '.', so on
+// scripts/bongos/onboarding-config.js). ship.js replaced only '/' and '.', so on
 // Windows — where the separator is '\', the drive carries ':', and paths often
 // contain spaces — it produced a path that cannot exist, the transcript was
 // never found, no session_record was written, and the cost-plus reward could
@@ -303,7 +303,7 @@ function fixture() {
         usage: { input_tokens: 100, output_tokens: 50, cache_read_input_tokens: 10, cache_creation_input_tokens: 5 },
         content: [
           { type: 'text', text: 'Let me claim the task and run the grader.' },
-          { type: 'tool_use', name: 'Bash', input: { command: 'node scripts/gds/claim.js 540' } },
+          { type: 'tool_use', name: 'Bash', input: { command: 'node scripts/bongos/claim.js 540' } },
         ],
       },
     },

package/tests/session_rename_fallback.mjs

@@ -29,7 +29,7 @@ import { spawnSync } from 'node:child_process';
 const REPO_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 const require = createRequire(import.meta.url);
 const ic = require(path.join(REPO_ROOT, 'src', 'instance-config.js'));
-const lib = require(path.join(REPO_ROOT, 'scripts', 'gds', 'cli-lib.js'));
+const lib = require(path.join(REPO_ROOT, 'scripts', 'bongos', 'cli-lib.js'));
 const auth = require(path.join(REPO_ROOT, 'src', 'bongos', 'auth.js'));
 
 const read = (rel) => fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8');
@@ -66,7 +66,7 @@ function inSandbox(body) {
       }
       const fs=require('node:fs'), path=require('node:path');
       const ic=require(R+'/src/instance-config.js');
-      const lib=require(R+'/scripts/gds/cli-lib.js');
+      const lib=require(R+'/scripts/bongos/cli-lib.js');
       const CFG=path.dirname(ic.configPath('x'));
       const w=(name,obj)=>{fs.mkdirSync(CFG,{recursive:true});fs.writeFileSync(path.join(CFG,name),JSON.stringify(obj,null,2));};
       const has=(name)=>fs.existsSync(path.join(CFG,name));

package/tests/session_reward_on_land.mjs

@@ -21,9 +21,10 @@
 // upsertSessionRecordWithReward / awardDeferredSessionRewardForTask call
 // api.withTx(fn), so we patch api.withTx to hand fn our fake client, and register
 // the REAL economy `reward` port so the real awardSessionTokenReward SQL runs
-// against the fake (the confirm_attribution.mjs pattern). A guarded real-DB
-// block then proves the actual uniq_credit_session_token_reward_basis partial
-// index enforces exactly-once end-to-end, and that a costlier later ship tops up.
+// against the fake (the confirm_attribution.mjs pattern). The real-DB half —
+// the actual uniq_credit_session_token_reward_basis partial index enforcing
+// exactly-once end-to-end, and a costlier later ship topping up — lives in
+// tests/session_reward_on_land_db.mjs (INTEGRATION set; task 1004861).
 //
 // Run:  node tests/session_reward_on_land.mjs
 
@@ -231,153 +232,10 @@ await test('awardDeferredSessionRewardForTask: non-numeric id → immediate no-o
 });
 
 // =========================================================================
-// (4) REAL-DB — the actual uniq_credit_session_token_reward partial index
-//     enforces exactly-once across the two triggers. Guarded on DATABASE_URL
-//     (env.sh sets it); skipped cleanly otherwise.
+// The REAL-DB cases moved to tests/session_reward_on_land_db.mjs (task 1004861) — an
+// INTEGRATION-set file, so a database lane runs them and a setup failure reds
+// instead of reading as SKIP. This file stays DB-free and in the unit gate.
 // =========================================================================
 
-if (process.env.DATABASE_URL) {
-  const pool = api.pool;
-  const suffix = `srol_${Date.now()}_${Math.floor(Math.random() * 1e6)}`;
-  const ctx = { builderId: null, versionId: `ver_${suffix}`, taskId: null };
-  let setupOk = false;
-  try {
-    const b = await pool.query(
-      `INSERT INTO builders (github_id, github_login, display_name) VALUES ($1,$2,$3) RETURNING id`,
-      [`gh_${suffix}`, `login_${suffix}`, `Test ${suffix}`]
-    );
-    ctx.builderId = Number(b.rows[0].id);
-    await pool.query(
-      `INSERT INTO versions (id, name, track, status) VALUES ($1,$2,'internal','planning')`,
-      [ctx.versionId, `V ${suffix}`]
-    );
-    const tk = await pool.query(
-      `INSERT INTO tasks (version_id, title, status) VALUES ($1,$2,'shipped') RETURNING id`,
-      [ctx.versionId, `shipped task ${suffix}`]
-    );
-    ctx.taskId = Number(tk.rows[0].id);
-    setupOk = true;
-  } catch (e) {
-    console.log(`  SKIP  real-DB block (setup failed: ${e.message})`);
-  }
-
-  if (setupOk) {
-    const rewardRows = (sessionId) => pool.query(
-      `SELECT delta FROM credit_log WHERE session_id = $1 AND reason = 'session.token_reward'`,
-      [sessionId]
-    );
-    try {
-      await test('real-DB: awardDeferredSessionRewardForTask books once + is idempotent (partial index)', async () => {
-        const sid = `sess-deferred-${suffix}`;
-        await pool.query(
-          `INSERT INTO session_records (session_id, builder_id, task_ids, total_tokens, model_usage)
-           VALUES ($1, $2, ARRAY[$3]::bigint[], $4, $5::jsonb)`,
-          [sid, ctx.builderId, ctx.taskId, 5000, JSON.stringify(MODEL_USAGE)]
-        );
-
-        const first = await db.awardDeferredSessionRewardForTask(ctx.taskId);
-        assert.equal(first.awarded, 1, 'first land books the reward');
-        let rows = (await rewardRows(sid)).rows;
-        assert.equal(rows.length, 1, 'exactly one session.token_reward row');
-        assert.ok(rows[0].delta > 0, 'a positive drachmae payout landed');
-
-        const mirror = await pool.query(
-          `SELECT token_reward_drachmae FROM session_records WHERE session_id = $1`, [sid]
-        );
-        assert.ok(Number(mirror.rows[0].token_reward_drachmae) > 0, 'the drachmae is mirrored onto the row');
-
-        const second = await db.awardDeferredSessionRewardForTask(ctx.taskId);
-        assert.equal(second.awarded, 0, 're-firing the land event is a no-op');
-        rows = (await rewardRows(sid)).rows;
-        assert.equal(rows.length, 1, 'the partial-unique index held — still exactly one row, no double payout');
-      });
-
-      // task 1002474 — the whole point of the watermark: a session that keeps
-      // spending after its first ship must be paid the difference, and the real
-      // (session_id, reward_basis) index must permit exactly that second row while
-      // still refusing a duplicate at the same basis.
-      await test('real-DB: a costlier later ship TOPS UP, and the top-up is itself idempotent', async () => {
-        const sid = `sess-topup-${suffix}`;
-        await pool.query(
-          `INSERT INTO session_records (session_id, builder_id, task_ids, total_tokens, model_usage)
-           VALUES ($1, $2, ARRAY[$3]::bigint[], $4, $5::jsonb)`,
-          [sid, ctx.builderId, ctx.taskId, 5000, JSON.stringify(MODEL_USAGE)]
-        );
-        await db.awardDeferredSessionRewardForTask(ctx.taskId);
-        const afterFirst = (await rewardRows(sid)).rows;
-        assert.equal(afterFirst.length, 1, 'the first ship books one row');
-        const firstPaid = Number(afterFirst[0].delta);
-
-        // The session keeps working and gets much more expensive, then ships again.
-        const bigger = {};
-        for (const [model, usage] of Object.entries(MODEL_USAGE)) {
-          bigger[model] = Object.fromEntries(
-            Object.entries(usage).map(([k, v]) => [k, Number(v) * 40])
-          );
-        }
-        await pool.query(
-          `UPDATE session_records SET model_usage = $2::jsonb WHERE session_id = $1`,
-          [sid, JSON.stringify(bigger)]
-        );
-
-        const topup = await db.awardDeferredSessionRewardForTask(ctx.taskId);
-        assert.equal(topup.awarded, 1, 'the grown session books a second row');
-        const afterTopup = (await rewardRows(sid)).rows;
-        assert.equal(afterTopup.length, 2, 'the (session_id, reward_basis) index PERMITS the increment');
-        const total = afterTopup.reduce((n, r) => n + Number(r.delta), 0);
-        assert.ok(total > firstPaid, 'the builder is now paid more than the first ship alone');
-        assert.ok(
-          afterTopup.every((r) => Number(r.delta) > 0),
-          'every row is a positive credit — a top-up never claws back'
-        );
-
-        // Re-firing at the SAME (unchanged) cost must add nothing.
-        const again = await db.awardDeferredSessionRewardForTask(ctx.taskId);
-        assert.equal(again.awarded, 0, 'no further payment when nothing changed');
-        assert.equal(
-          (await rewardRows(sid)).rows.length, 2,
-          'the index still refuses a duplicate at the same basis — exactly-once per level'
-        );
-      });
-
-      await test('real-DB: upsertSessionRecordWithReward DEFERS when the task is not shipped', async () => {
-        const sid = `sess-upload-defer-${suffix}`;
-        // A task id that is not status=shipped (nonexistent id → gate finds nothing).
-        const out = await db.upsertSessionRecordWithReward({
-          sessionId: sid, builderId: ctx.builderId, taskIds: [999_000_000 + Math.floor(Math.random() * 1000)],
-          totalTokens: 5000, modelUsage: MODEL_USAGE,
-        });
-        assert.equal(out.tokenReward.awarded, false, 'no landed task → deferred');
-        assert.equal(out.tokenReward.deferred, true);
-        assert.equal((await rewardRows(sid)).rows.length, 0, 'no reward row booked at upload');
-      });
-
-      await test('real-DB: upsertSessionRecordWithReward AWARDS when a task is already shipped', async () => {
-        const sid = `sess-upload-award-${suffix}`;
-        const out = await db.upsertSessionRecordWithReward({
-          sessionId: sid, builderId: ctx.builderId, taskIds: [ctx.taskId],
-          totalTokens: 5000, modelUsage: MODEL_USAGE,
-        });
-        assert.equal(out.tokenReward.awarded, true, 'a shipped task in the session → award at upload');
-        assert.ok(out.tokenReward.drachmae > 0);
-        assert.equal((await rewardRows(sid)).rows.length, 1, 'exactly one reward row');
-      });
-    } finally {
-      // FK-safe teardown (credit_log + session_records → builder; tasks → version).
-      try {
-        await pool.query(`DELETE FROM credit_log WHERE builder_id = $1`, [ctx.builderId]);
-        await pool.query(`DELETE FROM session_records WHERE builder_id = $1`, [ctx.builderId]);
-        await pool.query(`DELETE FROM tasks WHERE version_id = $1`, [ctx.versionId]);
-        await pool.query(`DELETE FROM versions WHERE id = $1`, [ctx.versionId]);
-        await pool.query(`DELETE FROM builders WHERE id = $1`, [ctx.builderId]);
-      } catch (e) {
-        console.log(`  WARN  real-DB teardown left rows (${e.message})`);
-      }
-    }
-  }
-} else {
-  console.log('  SKIP  real-DB block (no DATABASE_URL)');
-}
-
 // -------------------------------------------------------------------------
 summary();

package/tests/session_reward_on_land_db.mjs

@@ -0,0 +1,191 @@
+// tests/session_reward_on_land_db.mjs — the REAL-DATABASE half of tests/session_reward_on_land.mjs (task 1004861).
+//
+// ADR 0120 pay-on-land, session-token half: the real uniq_credit_session_token_reward_basis
+// partial index enforces exactly-once across the upload and land triggers, and a costlier
+// later ship tops up.
+//
+// The DB-free half (fake client, both trigger orders) stays in session_reward_on_land.mjs.
+//
+// WHY ITS OWN FILE. These cases used to sit at the bottom of session_reward_on_land.mjs behind a
+// DATABASE_URL guard, and ANY setup error was reported as "SKIP" — so when the fixture
+// started colliding with versions_one_planning_idx (the seeds already hold the one
+// 'planning' slot) the block went silent instead of red, and the file was in no lane
+// that supplies a database anyway. Split out, it sits in the INTEGRATION set; the
+// DB-free half stays in the unit gate. It SKIPS only when no Postgres is reachable —
+// a reachable database whose setup then fails is a FAIL.
+//
+// Run:  DATABASE_URL=... node tests/session_reward_on_land_db.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 seams = require('../src/module-seams.js');
+if (!seams.hasProvider('reward')) seams.registerProvider('reward', require('../modules/economy/reward.js'));
+const api = require('../src/module-api.js');
+const db = require('../modules/sessions/db.js');
+
+const { test, summary } = makeRunner();
+
+// Opus 110k input tokens → $0.55 true cost → $0.55 × 1.20 = 1 drachma. A non-zero
+// payout is what lets the idempotency SELECT + INSERT run at all.
+const MODEL_USAGE = { 'claude-opus-4-8': { input: 110_000 } };
+
+const pool = api.pool;
+try {
+  if (!process.env.DATABASE_URL) throw Object.assign(new Error('no DATABASE_URL'), { code: 'NO_DATABASE_URL' });
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`session_reward_on_land_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+const suffix = `srol_${Date.now()}_${Math.floor(Math.random() * 1e6)}`;
+const ctx = { builderId: null, versionId: `ver_${suffix}`, taskId: null };
+let setupOk = false;
+
+await test('real-DB: fixture setup', async () => {
+  // The version is 'building', not 'planning': at most one version may plan
+  // (versions_one_planning_idx, core_233) and the seeds already hold that slot.
+  const b = await pool.query(
+    `INSERT INTO builders (github_id, github_login, display_name) VALUES ($1,$2,$3) RETURNING id`,
+    [`gh_${suffix}`, `login_${suffix}`, `Test ${suffix}`]
+  );
+  ctx.builderId = Number(b.rows[0].id);
+  await pool.query(
+    `INSERT INTO versions (id, name, track, status) VALUES ($1,$2,'internal','building')`,
+    [ctx.versionId, `V ${suffix}`]
+  );
+  const tk = await pool.query(
+    `INSERT INTO tasks (version_id, title, status, discipline) VALUES ($1,$2,'shipped','engineer') RETURNING id`,
+    [ctx.versionId, `shipped task ${suffix}`]
+  );
+  ctx.taskId = Number(tk.rows[0].id);
+  setupOk = true;
+});
+
+{ // its own block so the teardown below runs even when setup failed halfway
+  const rewardRows = (sessionId) => pool.query(
+    `SELECT delta FROM credit_log WHERE session_id = $1 AND reason = 'session.token_reward'`,
+    [sessionId]
+  );
+  try {
+    if (setupOk) {
+      await test('real-DB: awardDeferredSessionRewardForTask books once + is idempotent (partial index)', async () => {
+        const sid = `sess-deferred-${suffix}`;
+        await pool.query(
+          `INSERT INTO session_records (session_id, builder_id, task_ids, total_tokens, model_usage)
+           VALUES ($1, $2, ARRAY[$3]::bigint[], $4, $5::jsonb)`,
+          [sid, ctx.builderId, ctx.taskId, 5000, JSON.stringify(MODEL_USAGE)]
+        );
+
+        const first = await db.awardDeferredSessionRewardForTask(ctx.taskId);
+        assert.equal(first.awarded, 1, 'first land books the reward');
+        let rows = (await rewardRows(sid)).rows;
+        assert.equal(rows.length, 1, 'exactly one session.token_reward row');
+        assert.ok(rows[0].delta > 0, 'a positive drachmae payout landed');
+
+        const mirror = await pool.query(
+          `SELECT token_reward_drachmae FROM session_records WHERE session_id = $1`, [sid]
+        );
+        assert.ok(Number(mirror.rows[0].token_reward_drachmae) > 0, 'the drachmae is mirrored onto the row');
+
+        const second = await db.awardDeferredSessionRewardForTask(ctx.taskId);
+        assert.equal(second.awarded, 0, 're-firing the land event is a no-op');
+        rows = (await rewardRows(sid)).rows;
+        assert.equal(rows.length, 1, 'the partial-unique index held — still exactly one row, no double payout');
+      });
+
+      // task 1002474 — the whole point of the watermark: a session that keeps
+      // spending after its first ship must be paid the difference, and the real
+      // (session_id, reward_basis) index must permit exactly that second row while
+      // still refusing a duplicate at the same basis.
+      await test('real-DB: a costlier later ship TOPS UP, and the top-up is itself idempotent', async () => {
+        const sid = `sess-topup-${suffix}`;
+        await pool.query(
+          `INSERT INTO session_records (session_id, builder_id, task_ids, total_tokens, model_usage)
+           VALUES ($1, $2, ARRAY[$3]::bigint[], $4, $5::jsonb)`,
+          [sid, ctx.builderId, ctx.taskId, 5000, JSON.stringify(MODEL_USAGE)]
+        );
+        await db.awardDeferredSessionRewardForTask(ctx.taskId);
+        const afterFirst = (await rewardRows(sid)).rows;
+        assert.equal(afterFirst.length, 1, 'the first ship books one row');
+        const firstPaid = Number(afterFirst[0].delta);
+
+        // The session keeps working and gets much more expensive, then ships again.
+        const bigger = {};
+        for (const [model, usage] of Object.entries(MODEL_USAGE)) {
+          bigger[model] = Object.fromEntries(
+            Object.entries(usage).map(([k, v]) => [k, Number(v) * 40])
+          );
+        }
+        await pool.query(
+          `UPDATE session_records SET model_usage = $2::jsonb WHERE session_id = $1`,
+          [sid, JSON.stringify(bigger)]
+        );
+
+        const topup = await db.awardDeferredSessionRewardForTask(ctx.taskId);
+        assert.equal(topup.awarded, 1, 'the grown session books a second row');
+        const afterTopup = (await rewardRows(sid)).rows;
+        assert.equal(afterTopup.length, 2, 'the (session_id, reward_basis) index PERMITS the increment');
+        const total = afterTopup.reduce((n, r) => n + Number(r.delta), 0);
+        assert.ok(total > firstPaid, 'the builder is now paid more than the first ship alone');
+        assert.ok(
+          afterTopup.every((r) => Number(r.delta) > 0),
+          'every row is a positive credit — a top-up never claws back'
+        );
+
+        // Re-firing at the SAME (unchanged) cost must add nothing.
+        const again = await db.awardDeferredSessionRewardForTask(ctx.taskId);
+        assert.equal(again.awarded, 0, 'no further payment when nothing changed');
+        assert.equal(
+          (await rewardRows(sid)).rows.length, 2,
+          'the index still refuses a duplicate at the same basis — exactly-once per level'
+        );
+      });
+
+      await test('real-DB: upsertSessionRecordWithReward DEFERS when the task is not shipped', async () => {
+        const sid = `sess-upload-defer-${suffix}`;
+        // A task id that is not status=shipped (nonexistent id → gate finds nothing).
+        const out = await db.upsertSessionRecordWithReward({
+          sessionId: sid, builderId: ctx.builderId, taskIds: [999_000_000 + Math.floor(Math.random() * 1000)],
+          totalTokens: 5000, modelUsage: MODEL_USAGE,
+        });
+        assert.equal(out.tokenReward.awarded, false, 'no landed task → deferred');
+        assert.equal(out.tokenReward.deferred, true);
+        assert.equal((await rewardRows(sid)).rows.length, 0, 'no reward row booked at upload');
+      });
+
+      await test('real-DB: upsertSessionRecordWithReward AWARDS when a task is already shipped', async () => {
+        const sid = `sess-upload-award-${suffix}`;
+        const out = await db.upsertSessionRecordWithReward({
+          sessionId: sid, builderId: ctx.builderId, taskIds: [ctx.taskId],
+          totalTokens: 5000, modelUsage: MODEL_USAGE,
+        });
+        assert.equal(out.tokenReward.awarded, true, 'a shipped task in the session → award at upload');
+        assert.ok(out.tokenReward.drachmae > 0);
+        assert.equal((await rewardRows(sid)).rows.length, 1, 'exactly one reward row');
+      });
+    }
+  } finally {
+    // FK-safe teardown (credit_log + session_records → builder; tasks → version).
+    if (ctx.builderId != null) {
+      try {
+        await pool.query(`DELETE FROM credit_log WHERE builder_id = $1`, [ctx.builderId]);
+        await pool.query(`DELETE FROM session_records WHERE builder_id = $1`, [ctx.builderId]);
+        await pool.query(`DELETE FROM tasks WHERE version_id = $1`, [ctx.versionId]);
+        await pool.query(`DELETE FROM versions WHERE id = $1`, [ctx.versionId]);
+        await pool.query(`DELETE FROM builders WHERE id = $1`, [ctx.builderId]);
+      } catch (e) {
+        console.log(`  WARN  real-DB teardown left rows (${e.message})`);
+      }
+    }
+  }
+}
+
+await pool.end().catch(() => {});
+summary();