@bongos/core 1.19.296 → 1.19.298

package/scripts/gds/spark.js

@@ -19,7 +19,17 @@
 // are one mental model, and a queue nobody can read is not a pickup surface. The
 // queue is readable by ANY builder: the author's mark is already the consent.
 //
+// --develop is the PICKUP (task 1002922 / BV1.R146): fill in the five template
+// fields and the spark becomes a Full Idea, in place, with the original author
+// preserved and you recorded as its developer. Open to any builder — the author's
+// mark was the consent. The five fields are prose, so they come from a JSON file
+// rather than five shell flags; --template prints the shape to fill in. The hall
+// form (R152) and conversational authoring (R155) are the richer surfaces; this
+// is the terminal path, and all three hit the same route.
+//
 // Usage:
+//   node scripts/gds/spark.js --template       # print the five fields to fill in
+//   node scripts/gds/spark.js --develop 123 --fields-file idea.json
 //   node scripts/gds/spark.js --list           # the spark queue: what awaits development
 //   node scripts/gds/spark.js --list --limit 10
 //   node scripts/gds/spark.js 123              # mark idea 123 as a spark
@@ -30,7 +40,12 @@
 //   1  api / network error, or the server refused (not yours / not a quick idea)
 //   2  bad invocation
 
+const fs = require('node:fs/promises');
 const { cliClient, requireSession, hasFlag, arg, hallBase } = require('./cli-lib');
+// A CLI may reach into its own domain module — the capture.js / autonomy-gate.js
+// precedent. Pure and DB-free: this only reads the R141 template declaration so
+// the prompt below cannot drift from what the server validates against.
+const { BASE_TEMPLATE } = require('../../modules/ideas/templates');
 
 // The server's refusals, in the ideator's own words. Anything unmapped falls
 // through to the raw envelope — a new server-side rule should be visible, not
@@ -39,6 +54,24 @@ const REFUSALS = {
   not_your_idea: (d) =>
     'That idea is not yours to mark. The spark mark is the author\'s consent to have their\n'
     + 'idea developed, so only the builder who filed it can give or withdraw it.',
+  not_a_spark: (d) =>
+    d.grade === 'full'
+      ? `That idea has already been developed into a Full Idea${d.developed_by ? ` (by builder ${d.developed_by})` : ''}.\n`
+        + 'A spark can only be developed once.'
+      : 'That idea is not a Big Idea Spark, so it is not available to develop.\n'
+        + 'Its author has to mark it first — that mark is what makes developing it fair.',
+  spark_already_developed: () =>
+    'Another builder developed this spark first, moments ago. Their version stands.\n'
+    + 'Run --list to see what else is waiting.',
+  invalid_field_values: (d) => {
+    const errs = Array.isArray(d) ? d : (d.errors || []);
+    const lines = ['That is not a complete Full Idea yet:'];
+    for (const e of errs) {
+      lines.push(`  - ${e.field || '(the whole set)'}: ${String(e.reason || '').replace(/_/g, ' ')}`);
+    }
+    lines.push('Run --template to see the five fields and re-run with the file fixed.');
+    return lines.join('\n');
+  },
   not_a_quick_idea: (d) =>
     `That idea is already a Full Idea (grade=${d.grade || 'full'}). It carries the developed\n`
     + 'picture the spark mark asks for — there is nothing to hand off.',
@@ -104,10 +137,89 @@ async function listQueue() {
   console.log(renderQueue(r.data || {}));
 }
 
+// The five fields, printed as a fill-in-the-blanks JSON skeleton. Read from the
+// R141 declaration rather than restated, so it cannot drift from what the server
+// validates — and it names the substance floor, because "present but three words"
+// is the failure the scorer actually punishes.
+function templateSkeleton() {
+  const lines = ['The five fields of a Full Idea (template ' + BASE_TEMPLATE.key + '):', ''];
+  for (const f of BASE_TEMPLATE.fields) {
+    lines.push(`  ${f.key}`);
+    lines.push(`    ${f.label}`);
+    if (f.substanceMin) lines.push(`    at least ~${f.substanceMin} characters of real content — padding scores nothing`);
+  }
+  lines.push('');
+  lines.push('Write them into a JSON file, then develop a spark with it:');
+  lines.push('');
+  lines.push('  ' + JSON.stringify(Object.fromEntries(BASE_TEMPLATE.fields.map((f) => [f.key, '...'])), null, 2).replace(/\n/g, '\n  '));
+  lines.push('');
+  lines.push('  node scripts/gds/spark.js --develop <idea-id> --fields-file <that-file.json>');
+  return lines.join('\n');
+}
+
+// What the developer is told once it lands. The completeness score is the number
+// the R147 credit split and the board bar both read, so it is the headline.
+function renderDeveloped(data) {
+  const { idea, author_id, developer_id, self_developed, board_window } = data || {};
+  const lines = [];
+  lines.push(`Idea ${idea.id} is now a Full Idea — completeness ${idea.completeness_score ?? 'unscored'}/100.`);
+  lines.push(`  ${hallBase()}/#/idea/${idea.id}`);
+  lines.push(self_developed
+    ? '  You had the thought and you developed it.'
+    : `  The thought stays credited to builder ${author_id}; you are recorded as its developer (${developer_id}).`);
+  if (board_window) {
+    lines.push(`  A board ratification window is open until ${board_window.closes_at}.`);
+  } else if (idea.rejection) {
+    lines.push(`  Not yet at the bar — thinnest section: ${idea.rejection.section_key}.`);
+    if (idea.rejection.reason_md) lines.push(`    ${idea.rejection.reason_md}`);
+  }
+  return lines.join('\n');
+}
+
+async function developSpark(ideaId) {
+  const file = arg('--fields-file');
+  if (!file) {
+    console.error('--develop needs --fields-file <path.json> (the five fields).');
+    console.error('Run: node scripts/gds/spark.js --template');
+    process.exit(2);
+  }
+  let fieldValues;
+  try {
+    fieldValues = JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch (err) {
+    console.error(`could not read ${file} as JSON: ${err.message}`);
+    process.exit(2);
+  }
+  const api = await cliClient();
+  const templateKey = arg('--template-key');
+  const r = await api.inbox.postInboxIdDevelop({
+    id: ideaId,
+    body: { field_values: fieldValues, ...(templateKey ? { template_key: templateKey } : {}) },
+  });
+  if (!r.ok) {
+    console.error(explain(r.status, r.data));
+    process.exit(1);
+  }
+  console.log(renderDeveloped(r.data));
+}
+
 async function main() {
   await requireSession();
 
+  if (hasFlag('--template')) {
+    console.log(templateSkeleton());
+    return;
+  }
   if (hasFlag('--list')) return listQueue();
+  const developIdRaw = arg('--develop');
+  if (developIdRaw != null) {
+    const devId = Number(developIdRaw);
+    if (!Number.isInteger(devId) || devId <= 0) {
+      console.error('usage: node scripts/gds/spark.js --develop <idea-id> --fields-file <path.json>');
+      process.exit(2);
+    }
+    return developSpark(devId);
+  }
 
   const positional = process.argv.slice(2).filter((a) => !a.startsWith('-'));
   const id = Number(positional[0]);
@@ -116,6 +228,8 @@ async function main() {
   if (!Number.isInteger(id) || id <= 0) {
     console.error('usage: node scripts/gds/spark.js <idea-id> [--undo]');
     console.error('       node scripts/gds/spark.js --list [--limit N]');
+    console.error('       node scripts/gds/spark.js --develop <idea-id> --fields-file <path.json>');
+    console.error('       node scripts/gds/spark.js --template');
     process.exit(2);
   }
 
@@ -141,11 +255,11 @@ async function main() {
   }
 }
 
-// explain() and renderQueue() are exported because both are pinned by tests —
-// explain against the real envelope shape, renderQueue for the empty case and the
-// hall-link form. REFUSALS stays private: it is the message table, reachable
-// through explain(), and a third export would be dead surface.
-module.exports = { explain, renderQueue };
+// The four renderers are exported because each is pinned by a test — explain
+// against the real envelope shape, and the three renderers for the shapes a
+// human actually reads. REFUSALS stays private: it is the message table,
+// reachable through explain(), and a fifth export would be dead surface.
+module.exports = { explain, renderQueue, renderDeveloped, templateSkeleton };
 
 if (require.main === module) {
   main().catch((err) => {

package/src/module-api.js

@@ -1019,8 +1019,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.294 with no explicit bump. run 32590508145. (task 1002620)
 //   1.19.296 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.295 with no explicit bump. run 32591155887. (task 1002620)
+//   1.19.297 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.296 with no explicit bump. run 32592502621. (task 1002620)
+//   1.19.298 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.297 with no explicit bump. run 32597859474. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.296'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.298'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/idea_credit_split.mjs

@@ -0,0 +1,224 @@
+// tests/idea_credit_split.mjs
+//
+// task 1002923 (BV1.R147, goal 1000062; ADR 0185) — the spark-handoff credit
+// split: 70% developer / 30% spark author, on both ideator streams.
+//
+// The three properties that are REAL BUGS if missed, asserted first:
+//   1. the total is CONSERVED under rounding (round(3.5)+round(1.5) = 6 from a
+//      5-credit payout is the naive mistake);
+//   2. a SELF-DEVELOPED idea collapses to ONE payee — two rows for one builder
+//      would be silently UNDER-paid, because the idempotency predicate is
+//      (builder_id, reason) and the second insert is refused;
+//   3. zero-value rows are DROPPED, not booked as 0-credit ledger noise.
+//
+// Then the two streams end-to-end against a stub client, and the develop route
+// actually paying (the gap R146 deliberately left open).
+//
+// Run:  node tests/idea_credit_split.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const credits = require('../modules/economy/credits.js');
+const { splitIdeaCredit, IDEA_DEVELOPER_SHARE, IDEA_FULL_PASS_CREDIT, IDEA_TASK_SHIP_BASE } = credits;
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.error(`  FAIL ${name}\n    ${err.message}`); }
+}
+
+const sum = (ps) => ps.reduce((n, p) => n + p.delta, 0);
+
+// --- property 1: the total is conserved ---------------------------------
+
+await test('the split CONSERVES the total at every payout size', () => {
+  for (let total = 1; total <= 120; total += 1) {
+    const ps = splitIdeaCredit(total, { authorId: 9, developedBy: 42 });
+    assert.equal(sum(ps), total, `total ${total} must not gain or lose a credit`);
+  }
+});
+
+await test('a 5-credit payout splits 4/1, not 4/2 — the rounding trap', () => {
+  const ps = splitIdeaCredit(5, { authorId: 9, developedBy: 42 });
+  assert.equal(sum(ps), 5);
+  const dev = ps.find((p) => p.role === 'developer');
+  const author = ps.find((p) => p.role === 'spark_author');
+  assert.equal(dev.delta, 4, 'round(5 * 0.70) = 4');
+  assert.equal(author.delta, 1, 'the author gets the REMAINDER, not round(1.5)=2');
+});
+
+await test('the developer gets the larger share, and it tracks the constant', () => {
+  assert.equal(IDEA_DEVELOPER_SHARE, 0.70, 'the owner decision, 2026-08-22');
+  const ps = splitIdeaCredit(100, { authorId: 9, developedBy: 42 });
+  assert.equal(ps.find((p) => p.role === 'developer').delta, 70);
+  assert.equal(ps.find((p) => p.role === 'spark_author').delta, 30);
+});
+
+// --- property 2: self-development collapses -----------------------------
+
+await test('a SELF-developed idea is ONE payee at the full amount', () => {
+  const ps = splitIdeaCredit(5, { authorId: 9, developedBy: 9 });
+  assert.equal(ps.length, 1, 'two rows for one builder would be silently under-paid');
+  assert.equal(ps[0].delta, 5);
+  assert.equal(ps[0].builderId, 9);
+  assert.equal(ps[0].role, 'author_developer');
+});
+
+await test('string/number id mismatch still counts as the same person', () => {
+  // captured_by and developed_by come back from pg as strings on a bigint column.
+  const ps = splitIdeaCredit(5, { authorId: '9', developedBy: 9 });
+  assert.equal(ps.length, 1, 'a type difference must not become a phantom second payee');
+});
+
+await test('an UNDEVELOPED idea pays its author everything', () => {
+  const ps = splitIdeaCredit(5, { authorId: 9, developedBy: null });
+  assert.deepEqual(ps, [{ builderId: 9, delta: 5, role: 'author' }]);
+});
+
+// --- property 3: no zero rows -------------------------------------------
+
+await test('a 1-credit payout pays the developer 1 and books NOTHING for the author', () => {
+  const ps = splitIdeaCredit(1, { authorId: 9, developedBy: 42 });
+  assert.equal(sum(ps), 1);
+  assert.equal(ps.length, 1, 'a 0-credit ledger row reads like a payment that was not made');
+  assert.equal(ps[0].role, 'developer');
+});
+
+await test('a zero or negative payout pays nobody', () => {
+  assert.deepEqual(splitIdeaCredit(0, { authorId: 9, developedBy: 42 }), []);
+  assert.deepEqual(splitIdeaCredit(-5, { authorId: 9, developedBy: 42 }), []);
+});
+
+await test('no author means no payment at all', () => {
+  assert.deepEqual(splitIdeaCredit(5, { authorId: null, developedBy: 42 }), []);
+});
+
+// --- stream 2, end to end ----------------------------------------------
+
+// A stub client that records every INSERT and answers the parties lookup.
+function stubClient({ authorId, developedBy, alreadyPaid = [] }) {
+  const inserts = [];
+  return {
+    inserts,
+    query: async (sql, params = []) => {
+      if (/FROM idea_inbox i/i.test(sql) && /developed_by/i.test(sql)) {
+        return { rows: [{ captured_by: authorId, developed_by: developedBy }] };
+      }
+      if (/FROM ideas_task_lineage/i.test(sql)) {
+        return { rows: [{ idea_id: '77', captured_by: authorId, grade: 'full', completeness: 100, developed_by: developedBy }] };
+      }
+      if (/INSERT INTO credit_log/i.test(sql)) {
+        const [builderId, , delta, reason] = params;
+        if (alreadyPaid.some((a) => String(a.builderId) === String(builderId) && a.reason === reason)) {
+          return { rowCount: 0 };
+        }
+        inserts.push({ builderId, delta, reason, description: params[4] });
+        return { rowCount: 1 };
+      }
+      return { rows: [], rowCount: 0 };
+    },
+  };
+}
+
+const ON = { ideatorCredit: true };
+
+await test('stream 2: a developed Full Idea pays BOTH parties under one reason key', async () => {
+  const c = stubClient({ authorId: '9', developedBy: '42' });
+  const r = await credits.awardIdeaFullPassCredit(c, { ideaId: 77, authorId: '9', completenessScore: 100, config: ON });
+  assert.equal(r.credited, IDEA_FULL_PASS_CREDIT, 'the whole payout is booked, split across two rows');
+  assert.equal(c.inserts.length, 2);
+  // One reason key for both — which is exactly why the idempotency predicate
+  // must include builder_id, or the second payee would be refused.
+  assert.equal(new Set(c.inserts.map((i) => i.reason)).size, 1);
+  assert.equal(c.inserts.find((i) => i.builderId === '42').delta, 4);
+  assert.equal(c.inserts.find((i) => i.builderId === '9').delta, 1);
+  assert.match(c.inserts.find((i) => i.builderId === '42').description, /developer/);
+  assert.match(c.inserts.find((i) => i.builderId === '9').description, /spark author/);
+});
+
+await test('stream 2: the PARTIES come from the DB, not from the caller', async () => {
+  // A caller naming the wrong author cannot redirect the money — the whole
+  // reason R146 could not safely pay.
+  const c = stubClient({ authorId: '9', developedBy: '42' });
+  await credits.awardIdeaFullPassCredit(c, { ideaId: 77, authorId: '999', completenessScore: 100, config: ON });
+  assert.ok(!c.inserts.some((i) => i.builderId === '999'), 'the caller-supplied author is ignored when the row is readable');
+  assert.deepEqual(c.inserts.map((i) => i.builderId).sort(), ['42', '9']);
+});
+
+await test('stream 2: an undeveloped Full Idea still pays its author the full 5', async () => {
+  const c = stubClient({ authorId: '9', developedBy: null });
+  const r = await credits.awardIdeaFullPassCredit(c, { ideaId: 77, authorId: '9', completenessScore: 100, config: ON });
+  assert.equal(r.credited, IDEA_FULL_PASS_CREDIT);
+  assert.equal(c.inserts.length, 1);
+  assert.equal(c.inserts[0].builderId, '9');
+  assert.equal(c.inserts[0].delta, IDEA_FULL_PASS_CREDIT);
+});
+
+await test('stream 2: a PARTIALLY booked split completes on a re-run, never double-pays', async () => {
+  const reason = 'idea.credit.full_pass:77';
+  // The developer's row landed; the author's did not (a crash between inserts).
+  const c = stubClient({ authorId: '9', developedBy: '42', alreadyPaid: [{ builderId: '42', reason }] });
+  const r = await credits.awardIdeaFullPassCredit(c, { ideaId: 77, authorId: '9', completenessScore: 100, config: ON });
+  assert.equal(c.inserts.length, 1, 'only the missing row is written');
+  assert.equal(c.inserts[0].builderId, '9');
+  assert.equal(r.credited, 1, 'credited reports only what was NEWLY booked');
+});
+
+await test('stream 2: a fully booked split reports already_paid and writes nothing', async () => {
+  const reason = 'idea.credit.full_pass:77';
+  const c = stubClient({ authorId: '9', developedBy: '42', alreadyPaid: [{ builderId: '42', reason }, { builderId: '9', reason }] });
+  const r = await credits.awardIdeaFullPassCredit(c, { ideaId: 77, authorId: '9', completenessScore: 100, config: ON });
+  assert.equal(c.inserts.length, 0);
+  assert.equal(r.credited, 0);
+  assert.equal(r.reason, 'already_paid');
+});
+
+await test('stream 2: below the bar nobody is paid, developed or not', async () => {
+  const c = stubClient({ authorId: '9', developedBy: '42' });
+  const r = await credits.awardIdeaFullPassCredit(c, { ideaId: 77, authorId: '9', completenessScore: 10, config: ON });
+  assert.equal(r.credited, 0);
+  assert.equal(r.reason, 'below_bar');
+  assert.equal(c.inserts.length, 0);
+});
+
+await test('stream 2: the lane can still be switched off entirely', async () => {
+  const c = stubClient({ authorId: '9', developedBy: '42' });
+  const r = await credits.awardIdeaFullPassCredit(c, { ideaId: 77, authorId: '9', completenessScore: 100, config: { ideatorCredit: false } });
+  assert.equal(r.reason, 'ideator_lane_off');
+  assert.equal(c.inserts.length, 0);
+});
+
+// --- stream 1, end to end ----------------------------------------------
+
+await test('stream 1: a task shipped under a DEVELOPED idea splits the same way', async () => {
+  const c = stubClient({ authorId: '9', developedBy: '42' });
+  const r = await credits.awardIdeaTaskShipCredit(c, { taskId: 100, config: ON });
+  assert.equal(r.credited, IDEA_TASK_SHIP_BASE, 'a 100% full idea pays the full base, split');
+  assert.equal(c.inserts.length, 2);
+  assert.equal(sum(c.inserts.map((i) => ({ delta: i.delta }))), IDEA_TASK_SHIP_BASE);
+  assert.equal(c.inserts.find((i) => i.builderId === '42').delta, 4);
+  assert.equal(c.inserts.find((i) => i.builderId === '9').delta, 1);
+  // Same rule, so the same wording — one rule to explain, not two.
+  assert.match(c.inserts.find((i) => i.builderId === '42').description, /stream 1/);
+  assert.match(c.inserts.find((i) => i.builderId === '42').description, /developer/);
+});
+
+await test('stream 1: an undeveloped idea is unchanged — the author gets it all', async () => {
+  const c = stubClient({ authorId: '9', developedBy: null });
+  const r = await credits.awardIdeaTaskShipCredit(c, { taskId: 100, config: ON });
+  assert.equal(r.credited, IDEA_TASK_SHIP_BASE);
+  assert.equal(c.inserts.length, 1);
+  assert.equal(c.inserts[0].builderId, '9');
+});
+
+await test('stream 1: the per-(idea,task) reason key still scopes idempotency', async () => {
+  const c = stubClient({ authorId: '9', developedBy: '42' });
+  await credits.awardIdeaTaskShipCredit(c, { taskId: 100, config: ON });
+  for (const i of c.inserts) assert.equal(i.reason, 'idea.credit.task_ship:77:100');
+});
+
+console.log(`\nidea_credit_split: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);