@bongos/core 1.19.159 → 1.19.161

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.159",
-  "core_contract": "1.19.159",
-  "source_commit": "bb03edbdf692de7f7e5a0f93e86cb6b9b8c47804",
+  "core_version": "1.19.161",
+  "core_contract": "1.19.161",
+  "source_commit": "206359b5cf85472d7b4def6050a2766f001569ea",
   "source_ref": "HEAD",
-  "built_at": "2026-08-16T16:34:56.328Z",
+  "built_at": "2026-08-16T16:41:02.340Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 305,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1257,
+    "functional_verbatim": 1259,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1583,
-  "tree_sha256": "12635cda248f239af4ee99dedef72a321b7af7a827734f397701b7fc4f6a7794",
+  "file_count": 1585,
+  "tree_sha256": "67b93c7d90a238fa234b0e809aee4545bf5190f1cd5f86513a294c4adb4244db",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -3479,6 +3479,11 @@
       "mode": "0000644",
       "sha256": "6c57608d1eae4159e967f9b471b20cb4c518c2b4acdf9d5ab88cad2afaf7c197"
     },
+    {
+      "path": "modules/ideas/templates.js",
+      "mode": "0000644",
+      "sha256": "d2816db988207f9f2c9305971ebca9bcd87d62e594facaea115d9f6db4b5d9f0"
+    },
     {
       "path": "modules/lifecycle/CLAUDE.md",
       "mode": "0000644",
@@ -4192,12 +4197,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "a5c34ddb4aced104656a9e6210d64de0326743b6f66fda7992a44a95378e42c3"
+      "sha256": "8bd2f7c052801d8b86e46c98ea962ecb4b23164a82ae96282e9789fb64da10c9"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "2b3da2ee3ca98ac2af38a25c4608e5755cd0953427afc818b96773082ec7d9db"
+      "sha256": "113553d6b43e63c5c34c77934179cb762626a81c13d63865e02de74c8c361633"
     },
     {
       "path": "public-docs/index.html",
@@ -5792,7 +5797,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "7d48fba3da62904e7f98a55a4617fa4c67d47e9184f83eb3c5ddbb1ca973efd3"
+      "sha256": "9c0be130573a1045b0a96d8db4b8ede624b304cdb5095c209fbec1c9c0d1248c"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -6904,6 +6909,11 @@
       "mode": "0000644",
       "sha256": "07cacc97990f0e775342f8b30171c87128e0acb1abd38d64c683c3f257927ebd"
     },
+    {
+      "path": "tests/idea_templates.mjs",
+      "mode": "0000644",
+      "sha256": "3360dcfcccd6ada6375124108a2570d84172977046aa47e1704d4be303ad41f3"
+    },
     {
       "path": "tests/idea_triage.mjs",
       "mode": "0000644",

package/modules/ideas/templates.js

@@ -0,0 +1,137 @@
+// modules/ideas/templates.js — the Full Idea template declarations (task 1002917,
+// BV1.R141, goal 1000062).
+//
+// THIS FILE IS WHAT 'base-v1' MEANS. ideas_001_grades.sql stores `field_values`
+// jsonb against a `template_key` and deliberately declares nothing about shape —
+// its header says "R141 declares what 'base-v1' means". This is that declaration:
+// the five base fields, in the owner's own wording from the Holy Workshop Trinity
+// brief, in the order they display.
+//
+// THE TEMPLATE IS DATA, READ BY BOTH VALIDATION AND SCORING. Capture (R143)
+// validates a submitted `field_values` against a template with
+// `validateFieldValues`; the deterministic completeness scorer (R142) walks the
+// same declaration (`fields`, each field's `substanceMin`) instead of hard-coding
+// five names of its own. Swapping the template changes what both accept — no
+// migration, no code change in either consumer. That property is the task's
+// done-when, and tests/idea_templates.mjs proves it by injecting a different
+// registry and watching validation follow it.
+//
+// DISPLAY ORDER COMES FROM HERE, NEVER FROM THE ROW. jsonb does not preserve key
+// order (the schema comment calls this out), so any renderer that iterates
+// Object.keys(field_values) shows the five fields in whatever order Postgres
+// chose. `fieldOrder(template)` is the one legal source of order.
+//
+// THE PER-PROJECT SEAM, NOT THE FEATURE (owner philosophy, recorded on goal
+// 1000062: the best possible simple base, already designed to be altered).
+// Every function takes an optional `registry`, defaulting to the built-in one.
+// A project-defined template (R156, a spike — deliberately NOT built here) will
+// resolve its own registry and pass it through; nothing below cares where a
+// registry came from. No customization UI, no config plumbing — just the seam.
+//
+// Same-module import: DEFAULT_TEMPLATE_KEY and the payload cap live in inbox.js
+// (declared there for the route validators, mirroring the DB constraints) — one
+// source, so this file can never drift from what the store accepts.
+
+'use strict';
+
+const { DEFAULT_TEMPLATE_KEY, FIELD_VALUES_MAX } = require('./inbox');
+
+// The five base fields, verbatim from the owner's brief. `key` is the stable
+// snake_case identity `field_values` is stored under (renaming a label is free;
+// renaming a key is a data migration — that is why they differ). `substanceMin`
+// is the character floor the R142 scorer treats as "this field was actually
+// answered, not padded past" — declared here as data so the scorer stays
+// template-agnostic; validation deliberately does NOT enforce it (a thin answer
+// is a scoring problem, not a capture error — scoring never blocks capture).
+const BASE_TEMPLATE = Object.freeze({
+  key: 'base-v1',
+  label: 'Full Idea',
+  fields: Object.freeze([
+    Object.freeze({ key: 'purpose',     label: 'Purpose of Idea',                                          required: true, substanceMin: 40 }),
+    Object.freeze({ key: 'big_picture', label: 'What does the Big Picture look like',                      required: true, substanceMin: 40 }),
+    Object.freeze({ key: 'why_had',     label: 'Why did you have the Idea',                                required: true, substanceMin: 40 }),
+    Object.freeze({ key: 'why_matters', label: 'Why does the Idea Matter',                                 required: true, substanceMin: 40 }),
+    Object.freeze({ key: 'fit',         label: 'How does the Idea Fit into the big picture of the project', required: true, substanceMin: 40 }),
+  ]),
+});
+
+// The built-in registry. One entry today; a second built-in template would be
+// added here. Frozen so a consumer can never mutate the base declaration into
+// a de-facto fork — a different shape is a different registry (the seam above).
+const BUILTIN_TEMPLATES = Object.freeze({
+  [BASE_TEMPLATE.key]: BASE_TEMPLATE,
+});
+
+// Sanity pin, not a runtime branch: the store's default key and this file's
+// base declaration are two statements of the same fact, and requiring them to
+// agree at load time turns a rename-drift into a boot failure instead of a
+// silent "every new row validates against a template that does not exist".
+if (BASE_TEMPLATE.key !== DEFAULT_TEMPLATE_KEY) {
+  throw new Error(`templates: BASE_TEMPLATE.key (${BASE_TEMPLATE.key}) !== inbox DEFAULT_TEMPLATE_KEY (${DEFAULT_TEMPLATE_KEY})`);
+}
+
+// Resolve a template by key. Null for an unknown key — the caller decides
+// whether that is a 400 (capture) or a render-as-raw fallback (display).
+function templateFor(key, registry = BUILTIN_TEMPLATES) {
+  if (typeof key !== 'string' || !key) return null;
+  return registry[key] || null;
+}
+
+// The one legal source of field display order (see header). Returns key order
+// as DECLARED, never as stored.
+function fieldOrder(template) {
+  return template.fields.map((f) => f.key);
+}
+
+// Validate a submitted field_values object against a template. PURE — no DB, no
+// clock — so capture (R143) can 400 with named fields before any query runs, and
+// the tests exercise every path without a harness.
+//
+// Returns { ok, template, errors } where each error is { field, reason }:
+//   unknown_template — templateKey resolves to nothing in the registry
+//   not_an_object    — field_values is not a plain object
+//   unknown_field    — a key the template does not declare (refused, never
+//                      silently stored: an unknown key in jsonb is invisible
+//                      debt the scorer and renderer would each trip on later)
+//   not_a_string     — a declared field carrying a non-string value
+//   missing_required — a required field absent or blank (whitespace = blank)
+//   too_large        — serialized payload over the store's byte cap (mirrored
+//                      from inbox.js so the refusal is a named 400 here rather
+//                      than a constraint-violation 500 there)
+//
+// Substance (substanceMin) is deliberately NOT validated — thin answers score
+// low (R142); they do not fail capture.
+function validateFieldValues(fieldValues, { templateKey = DEFAULT_TEMPLATE_KEY, registry = BUILTIN_TEMPLATES } = {}) {
+  const template = templateFor(templateKey, registry);
+  if (!template) return { ok: false, template: null, errors: [{ field: null, reason: 'unknown_template' }] };
+  if (!fieldValues || typeof fieldValues !== 'object' || Array.isArray(fieldValues)) {
+    return { ok: false, template, errors: [{ field: null, reason: 'not_an_object' }] };
+  }
+  const errors = [];
+  const declared = new Set(fieldOrder(template));
+  for (const key of Object.keys(fieldValues)) {
+    if (!declared.has(key)) errors.push({ field: key, reason: 'unknown_field' });
+    else if (typeof fieldValues[key] !== 'string') errors.push({ field: key, reason: 'not_a_string' });
+  }
+  for (const f of template.fields) {
+    if (!f.required) continue;
+    const v = fieldValues[f.key];
+    if (typeof v !== 'string' || v.trim() === '') {
+      // a non-string already carries not_a_string above; don't double-report it
+      if (typeof v !== 'string' && v !== undefined) continue;
+      errors.push({ field: f.key, reason: 'missing_required' });
+    }
+  }
+  if (errors.length === 0 && Buffer.byteLength(JSON.stringify(fieldValues), 'utf8') > FIELD_VALUES_MAX) {
+    errors.push({ field: null, reason: 'too_large' });
+  }
+  return { ok: errors.length === 0, template, errors };
+}
+
+module.exports = {
+  BASE_TEMPLATE,
+  BUILTIN_TEMPLATES,
+  templateFor,
+  fieldOrder,
+  validateFieldValues,
+};

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.159",
+  "version": "1.19.161",
   "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/src/module-api.js

@@ -745,8 +745,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.157 with no explicit bump. run 31958753412. (task 1002620)
 //   1.19.159 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.158 with no explicit bump. run 31958999646. (task 1002620)
+//   1.19.160 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.159 with no explicit bump. run 31959145128. (task 1002620)
+//   1.19.161 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.160 with no explicit bump. run 31959299652. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.159'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.161'; // 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_templates.mjs

@@ -0,0 +1,139 @@
+// tests/idea_templates.mjs
+//
+// task 1002917 (BV1.R141, goal 1000062) — the Full Idea base template.
+//
+// The claim these tests protect: THE TEMPLATE IS DATA. Validation follows the
+// declaration, order comes from the declaration, and swapping the registry
+// changes what is accepted with no code change — that is the task's done-when,
+// and the "swap" test at the bottom is the proof (the R156 per-project seam).
+//
+// Pure module — no DB, no doorway, no harness. inbox.js is required transitively
+// (templates.js reads DEFAULT_TEMPLATE_KEY / FIELD_VALUES_MAX from it), and it
+// destructures `pool` off the doorway at require time without querying, so a
+// bare require is safe here the same way tests/idea_grades.mjs relies on.
+//
+// Run:  node tests/idea_templates.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const T = require('../modules/ideas/templates.js');
+const { DEFAULT_TEMPLATE_KEY } = require('../modules/ideas/inbox.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.error(`  FAIL ${name}\n    ${err.message}`); }
+}
+
+// A complete, well-formed base payload — reused across tests.
+const FULL = {
+  purpose: 'A concrete purpose, written out.',
+  big_picture: 'What the world looks like once this exists.',
+  why_had: 'The observation that sparked it.',
+  why_matters: 'Why anyone should spend hours on it.',
+  fit: 'Where it sits in the project arc.',
+};
+
+// ── the declaration ─────────────────────────────────────────────────────────
+
+test('base-v1 declares exactly the five owner fields, in brief order', () => {
+  assert.equal(T.BASE_TEMPLATE.key, DEFAULT_TEMPLATE_KEY, 'the base key IS the store default');
+  assert.deepEqual(T.fieldOrder(T.BASE_TEMPLATE),
+    ['purpose', 'big_picture', 'why_had', 'why_matters', 'fit']);
+  for (const f of T.BASE_TEMPLATE.fields) {
+    assert.ok(f.label && f.required === true, `${f.key} carries a label and is required`);
+    assert.ok(Number.isInteger(f.substanceMin) && f.substanceMin > 0,
+      `${f.key} declares the substance floor the R142 scorer reads`);
+  }
+});
+
+test('the declaration is frozen — a consumer cannot fork it in place', () => {
+  assert.throws(() => { T.BASE_TEMPLATE.fields.push({ key: 'rogue' }); });
+  assert.throws(() => { 'use strict'; T.BUILTIN_TEMPLATES['base-v1'] = null; });
+});
+
+test('templateFor: base key resolves, unknown/blank/non-string do not', () => {
+  assert.equal(T.templateFor('base-v1'), T.BASE_TEMPLATE);
+  assert.equal(T.templateFor('no-such-template'), null);
+  assert.equal(T.templateFor(''), null);
+  assert.equal(T.templateFor(null), null);
+});
+
+// ── validation follows the declaration ──────────────────────────────────────
+
+test('a complete five-field payload validates', () => {
+  const r = T.validateFieldValues(FULL);
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.errors, []);
+  assert.equal(r.template, T.BASE_TEMPLATE);
+});
+
+test('an unknown field is refused, never silently stored', () => {
+  const r = T.validateFieldValues({ ...FULL, budget: 'not a base field' });
+  assert.equal(r.ok, false);
+  assert.deepEqual(r.errors, [{ field: 'budget', reason: 'unknown_field' }]);
+});
+
+test('a missing or blank required field is named, per field', () => {
+  const { fit, ...four } = FULL;
+  let r = T.validateFieldValues(four);
+  assert.deepEqual(r.errors, [{ field: 'fit', reason: 'missing_required' }]);
+  r = T.validateFieldValues({ ...FULL, purpose: '   ' });
+  assert.deepEqual(r.errors, [{ field: 'purpose', reason: 'missing_required' }]);
+});
+
+test('a non-string value is refused once, not double-reported', () => {
+  const r = T.validateFieldValues({ ...FULL, why_had: 42 });
+  assert.deepEqual(r.errors, [{ field: 'why_had', reason: 'not_a_string' }]);
+});
+
+test('a non-object payload and an unknown template are structured refusals', () => {
+  assert.deepEqual(T.validateFieldValues(null).errors, [{ field: null, reason: 'not_an_object' }]);
+  assert.deepEqual(T.validateFieldValues([]).errors, [{ field: null, reason: 'not_an_object' }]);
+  const r = T.validateFieldValues(FULL, { templateKey: 'nope' });
+  assert.deepEqual(r.errors, [{ field: null, reason: 'unknown_template' }]);
+  assert.equal(r.template, null);
+});
+
+test('a payload over the store byte cap is a named refusal, not a DB 500', () => {
+  const r = T.validateFieldValues({ ...FULL, purpose: 'x'.repeat(40000) });
+  assert.deepEqual(r.errors, [{ field: null, reason: 'too_large' }]);
+});
+
+test('substance is scored, not gated: a thin answer still validates', () => {
+  const thin = Object.fromEntries(Object.keys(FULL).map((k) => [k, 'ok']));
+  assert.equal(T.validateFieldValues(thin).ok, true,
+    'scoring never blocks capture — substanceMin is the scorer\'s, not the validator\'s');
+});
+
+// ── the done-when: swap the registry, behaviour follows (the R156 seam) ─────
+
+test('a different registry changes what is accepted — no code change', () => {
+  const custom = {
+    'econ-v1': {
+      key: 'econ-v1',
+      label: 'Economics Idea',
+      fields: [
+        { key: 'market', label: 'The market', required: true, substanceMin: 20 },
+        { key: 'unit_econ', label: 'Unit economics', required: false, substanceMin: 20 },
+      ],
+    },
+  };
+  const opts = { templateKey: 'econ-v1', registry: custom };
+  // the custom shape validates…
+  assert.equal(T.validateFieldValues({ market: 'builders paying for modules' }, opts).ok, true);
+  // …the BASE fields are now the unknown ones…
+  const r = T.validateFieldValues({ purpose: 'base field' }, opts);
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.some((e) => e.field === 'purpose' && e.reason === 'unknown_field'));
+  // …and order comes from the new declaration
+  assert.deepEqual(T.fieldOrder(custom['econ-v1']), ['market', 'unit_econ']);
+  // the built-in registry is untouched by any of it
+  assert.equal(T.validateFieldValues(FULL).ok, true);
+});
+
+console.log(`\nidea_templates: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);