@bongos/core 1.19.296 → 1.19.297

package/modules/ideas/routes/inbox.js

@@ -593,6 +593,160 @@ module.exports = function buildInboxRouter() {
     });
   }, { errorCode: 'idea_unspark_failed' }));
 
+  // POST /inbox/:id/develop — DEVELOP A SPARK INTO A FULL IDEA
+  // (task 1002922 / BV1.R146, goal 1000062).
+  //
+  // The pickup half of the handoff R144 and R145 set up: the author consented by
+  // marking the spark, the queue made it findable, and now another builder fills
+  // in the five template fields and the thought becomes a Full Idea.
+  //
+  // OPEN TO ANY BUILDER, INCLUDING THE AUTHOR. Cross-builder development is the
+  // entire point, so there is no author check here — the mirror image of R144,
+  // where the gate was the whole feature. The consent was already given and is
+  // already recorded (this row is a spark BECAUSE its author said so), and
+  // re-asking for it would make the queue unpickable. Self-development is
+  // likewise legal: an author may mark a thought and come back to it themselves.
+  //
+  // ONLY A SPARK CAN BE DEVELOPED, and "only once" is enforced by the DATABASE,
+  // not by this handler. developSpark's UPDATE carries `AND grade = 'spark'`, so
+  // two builders picking the same spark off the queue at the same instant cannot
+  // both succeed — the second matches zero rows. The pre-read below exists ONLY
+  // to tell a 404 apart from a 409 and to give a useful message; it is not the
+  // guard, and it deliberately does not try to be.
+  //
+  // WHAT THIS ROUTE DELIBERATELY DOES NOT DO: pay the stream-2 "Full Idea passed"
+  // credit. Capture and resubmit both fire it, but on those paths the recipient
+  // is unambiguously the author. Here there are two people, and choosing between
+  // them is R147's job (task 1002923 — "karma for a ratified Full Idea, scaled by
+  // completeness and SPLIT WITH THE SPARK AUTHOR"). Firing it here would not just
+  // pre-empt that decision, it would corrupt it: awardIdeaFullPassCredit's
+  // idempotency predicate is (builder_id, `idea.credit.full_pass:<id>`), so a
+  // payment to the DEVELOPER does not block a later payment to the AUTHOR — one
+  // idea would pay twice. The credit is idempotent per idea+builder, so R147 can
+  // still pay it at the right time, to the right people, in the right shares.
+  //
+  // The board window IS opened, because it is recipient-agnostic (it takes an
+  // idea and a score, not a builder) and without it a developed Full Idea could
+  // never reach ratification — the handoff would dead-end one step from done.
+  // Fail-open like every other caller of that port.
+  //
+  // rank: any-builder — development is the pickup, and the author's mark is the
+  // consent. Deliberately NOT pinned in route-rank-check: there is no gate here
+  // to protect, and pinning it would only assert that an open route stays open.
+  router.post('/inbox/:id/develop', api.requireBuilder, api.asyncHandler('POST /inbox/:id/develop', async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_id', positiveInt: true });
+    if (id === null) return;
+    if (validateOrRespond(req, res, {
+      field_values: { required: true, type: 'object' },
+      template_key: { type: 'string', maxLength: 64 },
+    })) return;
+
+    const idea = await inbox.getIdea(id);
+    if (!idea) return res.fail('idea_not_found', 404);
+    if (idea.grade !== 'spark') {
+      return res.fail('not_a_spark', 409, {
+        grade: idea.grade,
+        ...(idea.developed_by ? { developed_by: idea.developed_by } : {}),
+        reason: idea.grade === 'full'
+          ? 'this idea has already been developed into a Full Idea'
+          : 'only a Big Idea Spark can be developed — its author has to mark it first, which is what makes developing it fair',
+      });
+    }
+    // A SPARK IS NOT NECESSARILY STILL DEVELOPABLE. Triage writes
+    // idea_inbox.status and never touches ideas_grades, so an idea a triager
+    // discarded, merged or promoted keeps grade='spark' forever. Developing one
+    // would resurrect content the triage flow already decided was dead — and
+    // worse, open a fresh board ratification window for it. The R144 mark and the
+    // R145 queue both require status='open'; this is the same rule on the write.
+    // (developSpark's predicate carries it too, for the mid-request race.)
+    if (idea.status !== 'open') {
+      return res.fail('idea_not_open', 409, {
+        status: idea.status,
+        reason: 'this idea is no longer open, so it is not awaiting development',
+      });
+    }
+
+    // Same validation the capture and resubmit paths use, against the same
+    // template declaration — a developed Full Idea is a Full Idea, and must not
+    // be held to a looser standard just because someone else wrote it.
+    const templateKey = req.body.template_key ?? idea.template_key ?? undefined;
+    let v;
+    try {
+      v = validateFieldValues(req.body.field_values, templateKey ? { templateKey } : undefined);
+    } catch (validationErr) {
+      api.logger('ideas').error(`POST /inbox/:id/develop validation threw: ${validationErr && validationErr.message}`);
+      return res.fail('invalid_field_values', 400, { errors: [{ field: null, reason: 'unvalidatable' }] });
+    }
+    if (!v.ok) return res.fail('invalid_field_values', 400, { errors: v.errors, template_key: templateKey ?? null });
+
+    const row = await inbox.developSpark(id, {
+      developedBy: req.builder.id,
+      ...(templateKey ? { templateKey } : {}),
+      fieldValues: req.body.field_values,
+      completenessScore: completenessScore(req.body.field_values, templateKey ? { templateKey } : undefined),
+    });
+    // Zero rows means the guard fired: somebody else developed this spark between
+    // the read above and this write. Their work stands; this caller is told so
+    // rather than silently overwriting it.
+    if (!row) {
+      // The guard fired between the read above and the write. THREE causes now,
+      // and guessing would misinform: another developer got there first, or a
+      // triager closed the idea. One extra read on a rare path buys an honest
+      // answer instead of a plausible one.
+      const now = await inbox.getIdea(id);
+      if (now && now.status !== 'open') {
+        return res.fail('idea_not_open', 409, {
+          status: now.status,
+          reason: 'a triager closed this idea while you were developing it',
+        });
+      }
+      return res.fail('spark_already_developed', 409, {
+        ...(now && now.developed_by ? { developed_by: now.developed_by } : {}),
+        reason: 'another builder developed this spark first — their version stands',
+      });
+    }
+
+    const out = {
+      ...idea,
+      grade: row.grade,
+      template_key: row.template_key,
+      field_values: row.field_values,
+      completeness_score: row.completeness_score,
+      developed_by: row.developed_by,
+      developed_at: row.developed_at,
+    };
+
+    let board_window;
+    try {
+      const government = api.resolveOptional && api.resolveOptional('government');
+      if (government && government.openBoardWindowForIdea) {
+        const w = await government.openBoardWindowForIdea({ ideaId: id, completenessScore: row.completeness_score });
+        if (w && w.opened && w.item) board_window = { item_id: w.item.id, closes_at: w.item.closes_at };
+        else if (w && w.reason === 'below_bar') {
+          // The same honest feedback the resubmit path gives: which section is
+          // thinnest, computed from what was just written. Derived, never stored.
+          const flag = weakestSectionPayload(req.body.field_values, templateKey ? { templateKey } : undefined);
+          if (flag) out.rejection = flag;
+        }
+      }
+    } catch (boardErr) {
+      // Fail-open, like every other caller of this port: the development landed
+      // and must not be rolled back because the board could not be told.
+      api.logger('ideas').error(`develop: board-window open failed (development intact, window skipped): ${boardErr && boardErr.message}`);
+    }
+
+    return res.json({
+      idea: out,
+      developed: true,
+      // Named explicitly so a caller never has to compare two ids to find out,
+      // and so the R147 split reads its two parties off one response.
+      author_id: idea.captured_by ?? null,
+      developer_id: row.developed_by,
+      self_developed: idea.captured_by != null && String(idea.captured_by) === String(row.developed_by),
+      ...(board_window ? { board_window } : {}),
+    });
+  }, { errorCode: 'idea_develop_failed' }));
+
   // Metic+ (#360 / ADR 0018): idea triage (promote/discard/merge) shapes the
   // backlog. Criterion C2 assigns triage to Metic, so this widened from
   // archon-only to metic+archon when the three-rank model went live. Any

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.296",
+  "version": "1.19.297",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.296",
+      "version": "1.19.297",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.296",
+  "version": "1.19.297",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

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,10 @@ 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)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.296'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.297'; // 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');