@bongos/core 1.19.444 → 1.19.446

package/tests/backfill_subagent_rewards.mjs

@@ -0,0 +1,308 @@
+// tests/backfill_subagent_rewards.mjs
+//
+// Unit tests for the subagent cost-plus backfill planner (task 1003436, ADR 0054).
+//
+// This script decides who gets paid real credits, so the whole decision table is
+// pure and pinned here with no DB: which sessions are payable, which are refused
+// and WHY, and — the part that actually protects the ledger — that the classes
+// which cannot be trusted (pre-de-dup-fix inflated rows, unrecoverable sessions,
+// the ADR 0173 legacy class) never reach the mint.
+//
+// Run:  node tests/backfill_subagent_rewards.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const {
+  CLASSES, DEDUP_FIX_AT, classifySession, buildBackfillPlan, renderReport,
+} = require('../scripts/gds/backfill-subagent-rewards.js');
+const {
+  computeSessionTokenReward, sessionTrueCostUsd, awardSessionTokenReward,
+} = require('../modules/economy/credits.js');
+
+const { test, summary } = makeRunner();
+
+const AFTER = '2026-08-25T00:00:00Z';  // safely after the de-dup cutoff
+const BEFORE = '2026-08-20T00:00:00Z'; // safely before it
+const OPTS = { cutoffMs: Date.parse(DEDUP_FIX_AT), marginPct: 20, usdPeg: 1 };
+
+// 1M opus input tokens = $5.00 interactive (PRICES.opus.input = $5/M).
+const OPUS_1M = { 'claude-opus-4-8': { input: 1_000_000 } };
+
+function row(over = {}) {
+  return {
+    session_id: 'sess-aaaaaaaa',
+    builder_id: 7,
+    model_usage: OPUS_1M,
+    total_tokens: 1_000_000,
+    subagent_usd: 3.0,
+    subagent_recorded_at: AFTER,
+    has_pre_split_cost_row: false,
+    has_folded_usage: false, // pre-1003435 digest: model_usage is interactive-only
+    paid: 6, // round(5.00 x 1.20) — what the subagent-blind reward paid
+    legacy_rows: 0,
+    ...over,
+  };
+}
+
+// =========================================================================
+// classifySession — the decision table
+// =========================================================================
+
+await test('payable: owed is priced on interactive + subagent, minus what was paid', () => {
+  const r = classifySession(row(), OPTS);
+  assert.equal(r.klass, CLASSES.PAYABLE);
+  assert.equal(r.interactiveUsd, 5.0);
+  assert.equal(r.subagentUsd, 3.0);
+  assert.equal(r.trueCostUsd, 8.0);
+  assert.equal(r.owed, 10);  // round(8.00 x 1.20) = 9.6 -> 10
+  assert.equal(r.paid, 6);
+  assert.equal(r.delta, 4);
+});
+
+await test('payable: the interactive side comes from the SAME function the reward books from', () => {
+  // If these ever diverge the backfill would silently re-price what was already
+  // paid instead of only adding the missing leg.
+  const r = classifySession(row(), OPTS);
+  const { trueCostUsd } = sessionTrueCostUsd(OPUS_1M, 1_000_000);
+  assert.equal(r.interactiveUsd, trueCostUsd);
+  assert.equal(r.owed, computeSessionTokenReward(trueCostUsd + 3.0, 20, 1).drachmae);
+});
+
+await test('up_to_date: a session already paid its full worth mints nothing', () => {
+  const r = classifySession(row({ paid: 10 }), OPTS);
+  assert.equal(r.klass, CLASSES.UP_TO_DATE);
+  assert.equal(r.delta, 0);
+});
+
+await test('overpaid: paid ABOVE its worth is reported, never clawed back', () => {
+  const r = classifySession(row({ paid: 25 }), OPTS);
+  assert.equal(r.klass, CLASSES.OVERPAID);
+  assert.equal(r.excess, 15);
+  assert.equal(r.delta, 0, 'a negative delta must never become a mint');
+});
+
+await test('pre_dedup_fix: an inflated cost row is NEVER paid from', () => {
+  // Rows written before task 1003217 price one API call once per transcript line
+  // (~2.22x). Paying from them would overpay, so they are refused by DATE.
+  const r = classifySession(row({ subagent_recorded_at: BEFORE }), OPTS);
+  assert.equal(r.klass, CLASSES.PRE_DEDUP_FIX);
+  assert.equal(r.delta, 0);
+});
+
+await test('--since moves the trust cutoff (a machine on an older core keeps writing inflated rows)', () => {
+  const late = { ...OPTS, cutoffMs: Date.parse('2026-08-28T00:00:00Z') };
+  assert.equal(classifySession(row(), late).klass, CLASSES.PRE_DEDUP_FIX);
+  assert.equal(classifySession(row(), OPTS).klass, CLASSES.PAYABLE);
+});
+
+await test('no_subagent_record: no cost row means unrecoverable — never guessed at', () => {
+  const r = classifySession(row({ subagent_usd: null, subagent_recorded_at: null }), OPTS);
+  assert.equal(r.klass, CLASSES.NO_SUBAGENT_RECORD);
+  assert.equal(r.delta, 0);
+  assert.equal(r.subagentUsd, undefined, 'no invented figure');
+});
+
+await test('pre_split: a legacy single `session` row lumps both legs and cannot be separated', () => {
+  const r = classifySession(
+    row({ subagent_usd: null, subagent_recorded_at: null, has_pre_split_cost_row: true }), OPTS
+  );
+  assert.equal(r.klass, CLASSES.PRE_SPLIT);
+  assert.equal(r.delta, 0);
+});
+
+// -------------------------------------------------------------------------
+// The double-count guard. This is the one that would actually mint bad money:
+// after task 1003435 the digest folds the subagents subtree INTO model_usage, so
+// adding the cost_log subagent row on top pays the same leg twice.
+// -------------------------------------------------------------------------
+
+await test('already_folded: a post-1003435 digest already prices the subagent leg — never topped up', () => {
+  const r = classifySession(row({ has_folded_usage: true }), OPTS);
+  assert.equal(r.klass, CLASSES.ALREADY_FOLDED);
+  assert.equal(r.delta, 0, 'adding the cost row here would DOUBLE-COUNT and overpay');
+});
+
+await test('already_folded is decided BEFORE any money is computed', () => {
+  // A large subagent row must not be able to leak a figure into the plan via a
+  // field that later code reads.
+  const r = classifySession(row({ has_folded_usage: true, subagent_usd: 500 }), OPTS);
+  assert.equal(r.klass, CLASSES.ALREADY_FOLDED);
+  assert.equal(r.owed, undefined);
+  assert.equal(r.subagentUsd, undefined);
+});
+
+await test('the guard keys on the DATA, not a date — a re-uploaded old session is caught too', () => {
+  // A session that shipped before the fix but whose SessionEnd digest was
+  // re-uploaded after it has folded model_usage AND an old subagent cost row.
+  // The date would say "payable"; the counters say "already whole".
+  const r = classifySession(
+    row({ has_folded_usage: true, subagent_recorded_at: BEFORE }), OPTS
+  );
+  assert.equal(r.klass, CLASSES.ALREADY_FOLDED);
+});
+
+await test('a folded session never reaches the mint, and is reported', () => {
+  const plan = buildBackfillPlan([
+    row({ session_id: 's1' }),                            // +4
+    row({ session_id: 's2', has_folded_usage: true }),    // excluded
+  ], { since: DEDUP_FIX_AT, marginPct: 20, usdPeg: 1 });
+  assert.equal(plan.grandTotal, 4, 'only the un-folded session is paid');
+  assert.equal(plan.counts[CLASSES.ALREADY_FOLDED], 1);
+  assert.match(renderReport(plan).text, /already_folded/);
+});
+
+await test('legacy: the reward_basis=0 class ADR 0173 declined is never folded in here', () => {
+  const r = classifySession(row({ legacy_rows: 2 }), OPTS);
+  assert.equal(r.klass, CLASSES.LEGACY);
+  assert.equal(r.delta, 0);
+});
+
+await test('legacy wins over payable — the class is decided before any money is computed', () => {
+  const r = classifySession(row({ legacy_rows: 1, subagent_usd: 100 }), OPTS);
+  assert.equal(r.klass, CLASSES.LEGACY);
+  assert.equal(r.owed, undefined);
+});
+
+// =========================================================================
+// buildBackfillPlan — grouping + the grand total the owner signs off on
+// =========================================================================
+
+await test('the plan groups payables by builder and totals them', () => {
+  const plan = buildBackfillPlan([
+    row({ session_id: 's1', builder_id: 7 }),                       // +4
+    row({ session_id: 's2', builder_id: 7, subagent_usd: 10 }),     // owed round(15x1.2)=18, -6 => +12
+    row({ session_id: 's3', builder_id: 9 }),                       // +4
+    row({ session_id: 's4', builder_id: 9, legacy_rows: 1 }),       // not paid
+    row({ session_id: 's5', builder_id: 9, subagent_recorded_at: BEFORE }), // not paid
+  ], { since: DEDUP_FIX_AT, marginPct: 20, usdPeg: 1 });
+
+  assert.equal(plan.totalCandidates, 5);
+  assert.equal(plan.plans.length, 2);
+  assert.deepEqual(plan.plans.map((p) => [p.builderId, p.toMint]), [[7, 16], [9, 4]]);
+  assert.equal(plan.grandTotal, 20);
+  assert.equal(plan.counts[CLASSES.PAYABLE], 3);
+  assert.equal(plan.counts[CLASSES.LEGACY], 1);
+  assert.equal(plan.counts[CLASSES.PRE_DEDUP_FIX], 1);
+});
+
+await test('the plan reports what it does NOT settle (ADR 0173 objected to a silent partial)', () => {
+  const plan = buildBackfillPlan([
+    row({ session_id: 's1', subagent_usd: 7.5, subagent_recorded_at: BEFORE }),
+    row({ session_id: 's2', paid: 25 }),
+  ], { since: DEDUP_FIX_AT, marginPct: 20, usdPeg: 1 });
+  assert.equal(plan.unpaidSubagentUsd, 7.5, 'inflated-but-real spend is surfaced, not hidden');
+  assert.equal(plan.overpaidExcess, 15, 'correcting in one direction only is stated');
+  assert.equal(plan.grandTotal, 0);
+});
+
+await test('an empty ledger plans nothing and totals zero', () => {
+  const plan = buildBackfillPlan([], { since: DEDUP_FIX_AT, marginPct: 20, usdPeg: 1 });
+  assert.equal(plan.grandTotal, 0);
+  assert.equal(plan.plans.length, 0);
+  assert.match(renderReport(plan).text, /NOTHING PAYABLE/);
+});
+
+await test('the report leads with the grand total and names every refusal reason', () => {
+  const plan = buildBackfillPlan([row(), row({ session_id: 's2', legacy_rows: 1 })],
+    { since: DEDUP_FIX_AT, marginPct: 20, usdPeg: 1 });
+  const { text, total } = renderReport(plan, { loginFor: (id) => (id === 7 ? 'jaxri' : null) });
+  assert.equal(total, 4);
+  assert.match(text, /GRAND TOTAL to mint: 4 credits/);
+  assert.match(text, /jaxri: \+4/);
+  for (const k of [CLASSES.PRE_DEDUP_FIX, CLASSES.NO_SUBAGENT_RECORD, CLASSES.PRE_SPLIT, CLASSES.LEGACY]) {
+    assert.ok(text.includes(k), `the report must name the ${k} class`);
+  }
+});
+
+// =========================================================================
+// The mint path — idempotency + the forward-path invariant.
+//
+// These are the properties that keep a backfill from corrupting the ledger, so
+// they are asserted against the REAL writer with a fake client, not described.
+// =========================================================================
+
+function fakeClient(ledgerRows) {
+  const queries = [];
+  const responses = [...ledgerRows];
+  return {
+    queries,
+    async query(sql, params) {
+      queries.push({ sql, params });
+      return { rows: responses.shift() || [] };
+    },
+  };
+}
+const ledger = (paid = 0, legacy = 0) => [{ paid, legacy }];
+
+await test('the mint goes through the real reward writer, so extraCostUsd raises the basis', async () => {
+  const client = fakeClient([ledger(6, 0), [{ id: 1 }]]);
+  const res = await awardSessionTokenReward(client, 7, 'sess-aaaaaaaa', OPUS_1M, 1_000_000, 3.0);
+  assert.equal(res.awarded, true);
+  assert.equal(res.trueCostUsd, 8.0, 'interactive $5 + recovered subagent $3');
+  assert.equal(res.drachmae, 4, 'books only the INCREMENT over what was paid');
+  const insert = client.queries[1];
+  assert.match(insert.sql, /session\.token_reward/);
+  assert.match(insert.sql, /ON CONFLICT \(session_id, reward_basis\)/);
+  // reward_basis is the CUMULATIVE owed total — the last positional.
+  assert.equal(insert.params[insert.params.length - 1], 10);
+  assert.equal(insert.params[1], 4, 'delta booked = owed - paid');
+});
+
+await test('re-running the backfill is a no-op — the watermark, not a private reason key', async () => {
+  // Second run: the ledger now shows the topped-up total, so owed - paid = 0.
+  const client = fakeClient([ledger(10, 0)]);
+  const res = await awardSessionTokenReward(client, 7, 'sess-aaaaaaaa', OPUS_1M, 1_000_000, 3.0);
+  assert.equal(res.awarded, false);
+  assert.equal(res.drachmae, 0);
+  assert.equal(res.settled, 'up_to_date');
+  assert.equal(client.queries.length, 1, 'SELECT only — no second INSERT');
+});
+
+await test('FORWARD PATH: a later ship in a backfilled session books only its own increment', async () => {
+  // The reason the backfill is written under the NORMAL reason rather than its
+  // own key: the watermark reads reason='session.token_reward', so a private key
+  // would be invisible to it and the next ship would pay the subagent leg AGAIN.
+  // Here the next ship uploads a digest whose model_usage now INCLUDES the
+  // subagent tokens (task 1003435) — $8 of usage, already backfilled to 10.
+  const eight = { 'claude-opus-4-8': { input: 1_600_000 } }; // 1.6M x $5/M = $8.00
+  const client = fakeClient([ledger(10, 0)]);
+  const res = await awardSessionTokenReward(client, 7, 'sess-aaaaaaaa', eight, 1_600_000);
+  assert.equal(res.trueCostUsd, 8.0);
+  assert.equal(res.awarded, false, 'must NOT re-pay the leg the backfill settled');
+  assert.equal(client.queries.length, 1);
+});
+
+await test('a backfill can never clawback: a smaller basis books nothing, never a negative row', async () => {
+  const client = fakeClient([ledger(99, 0)]);
+  const res = await awardSessionTokenReward(client, 7, 'sess-aaaaaaaa', OPUS_1M, 1_000_000, 3.0);
+  assert.equal(res.awarded, false);
+  assert.equal(res.drachmae, 0);
+  assert.equal(client.queries.length, 1, 'no INSERT — the ledger is append-only');
+});
+
+await test('the legacy refusal still bites at the writer, not only in the planner', async () => {
+  const client = fakeClient([ledger(3, 1)]); // one reward_basis=0 row
+  const res = await awardSessionTokenReward(client, 7, 'sess-legacy', OPUS_1M, 1_000_000, 3.0);
+  assert.equal(res.awarded, false);
+  assert.equal(res.settled, 'legacy', 'ADR 0173 class is refused twice over');
+});
+
+await test('extraCostUsd defaults to 0, so every pre-existing call site is unchanged', async () => {
+  const client = fakeClient([ledger(0, 0), [{ id: 9 }]]);
+  const res = await awardSessionTokenReward(client, 7, 'sess-plain', OPUS_1M, 1_000_000);
+  assert.equal(res.trueCostUsd, 5.0);
+  assert.equal(res.drachmae, 6);
+});
+
+await test('a negative, infinite or garbage extraCostUsd cannot inflate a payout', async () => {
+  for (const bad of [-100, NaN, Infinity, -Infinity, 'lots', null, undefined]) {
+    const client = fakeClient([ledger(0, 0), [{ id: 1 }]]);
+    const res = await awardSessionTokenReward(client, 7, 'sess-x', OPUS_1M, 1_000_000, bad);
+    assert.equal(res.trueCostUsd, 5.0, `extraCostUsd ${String(bad)} must be treated as 0`);
+  }
+});
+
+summary();