@bongos/core 1.19.936 → 1.19.937

package/modules/lifecycle/goal-from-idea.js

@@ -0,0 +1,131 @@
+'use strict';
+
+// modules/lifecycle/goal-from-idea.js — creating the GOAL a ratified Full Idea
+// becomes, inside somebody else's transaction (task 1004096 / BV2.R17, spec R23,
+// goal 1000095, criterion `ideator-full-idea-shapes-the-space`).
+//
+// WHY THIS LIVES IN LIFECYCLE AND NOT IN modules/ideas. `goals`, `versions` and
+// `done_when_criteria` are this module's tables, and the ideas module may not
+// import lifecycle (the one-way module rule, ADR 0083). The alternative was to
+// widen the `lifecycle` port with four primitives — getVersion, createGoal,
+// createCriterion, authorizeGoalCreate — and let the ideas module compose them.
+// That is the shape to avoid: composing them IS the policy, and the policy is
+// "may a goal be created here, by this rank, with this scope", which is a
+// lifecycle judgement. Handing a caller the four pieces hands them four chances
+// to leave one out, and the one most easily left out is the gate.
+//
+// SO THIS IS ONE PORT CALL THAT EITHER CREATES BOTH ROWS OR NAMES ITS REFUSAL.
+// The ideas module supplies the DATA a ratification carries (title, the five
+// answers, the version and scope the board chose) and the actor's live rank; it
+// never gets to decide whether the create is allowed.
+//
+// IT RUNS IN THE CALLER'S TRANSACTION (`deps.client`, required — see below), for
+// the ensureMaintenanceGoal reason: a goal committed on its own connection would
+// survive a rolled-back ratification as an empty goal nobody asked for, pointing
+// at an idea still sitting `open` in the inbox.
+//
+// EVERY GATE POST /goals APPLIES IS APPLIED HERE, and that is the point of the
+// file rather than a courtesy. `idea.ratify`'s floor is METIC (ADR 0157 lowered
+// it from archon), while `POST /goals` refuses a protected-`scope_modules` goal
+// to anyone below Archon and refuses to grow a BUILDING version's goal set at
+// all without a named Archon admission. A ratification path that skipped either
+// would be a Metic-reachable way around both — the scope wall and the R03 gate
+// would still be in the code and no longer in the way of anything.
+
+const api = require('../../src/module-api');
+const db = require('./db.js');
+const { authorizeGoalCreate } = require('./routes/goal-route-authz.js');
+
+const { isModuleKey, scopeIncludesProtected, moduleKeys } = api.moduleScopeMap;
+
+// A typed refusal, never a throw: the caller is inside a transaction it has to
+// roll back itself, and an exception thrown across a port is the thing that
+// makes a rollback easy to forget. `status` travels with the refusal so the
+// route renders it without a second mapping table.
+function refuse(code, status, extra = {}) {
+  return { ok: false, code, status, ...extra };
+}
+
+// createRatifiedGoal — the goal + its first done-when criterion, in the caller's
+// transaction, or a named refusal.
+//
+// `criterionMd` is REQUIRED and is not a convenience. The criterion is what makes
+// the created row a goal in this project's sense rather than an empty container:
+// ADR 0263's close gate reads done-when criteria, so a goal born with none can
+// never be achieved and holds its version open forever. BV2.R17's whole claim is
+// that a Full Idea's "what does a successful implementation look like" answer IS
+// that criterion — so the two rows are one act, and this function will not make
+// the first without the second.
+//
+// `criterionRef` is the stable `criterion_id` text. The caller derives it from
+// the source idea (`idea-<n>`), which makes the UNIQUE (version_id,
+// criterion_id) constraint a second, database-level guard against ratifying the
+// same idea twice onto the same version — the `proposal-<idea_id>` trick
+// ratifyCriterionProposal already uses, for the same reason.
+async function createRatifiedGoal(
+  { versionId, title, description = null, subtitle = null, scopeModules = [], createdBy = null,
+    criterionMd, criterionRef, admitReason = null, actorRank = null },
+  deps = {}
+) {
+  if (!deps.client) {
+    // Not a policy refusal — a programming error, and one whose consequence is a
+    // half-committed ratification. It throws rather than returning, because no
+    // caller can sensibly handle it and none should try.
+    throw new Error('createRatifiedGoal requires deps.client — it must run in the ratification transaction');
+  }
+  if (typeof title !== 'string' || !title.trim()) return refuse('TITLE_REQUIRED', 400);
+  if (typeof criterionMd !== 'string' || !criterionMd.trim()) return refuse('CRITERION_REQUIRED', 400);
+  if (typeof criterionRef !== 'string' || !criterionRef.trim()) return refuse('CRITERION_REF_REQUIRED', 400);
+
+  const scope = Array.isArray(scopeModules) ? scopeModules : [];
+  // Fail closed on an unknown module key, POST /goals' first gate: a scope wall
+  // that can name a module which does not exist is not a wall.
+  const unknown = scope.filter((k) => !isModuleKey(k));
+  if (unknown.length) return refuse('UNKNOWN_MODULE', 400, { unknown, valid: moduleKeys() });
+  // The two RANK gates. `actorRank` is the caller's LIVE rank read (ADR 0016) —
+  // never a value a request body carried — and an absent rank denies, because a
+  // rank we were not told is not a rank we may assume.
+  if (scopeIncludesProtected(scope) && actorRank !== 'archon') {
+    return refuse('ARCHON_REQUIRED_FOR_PROTECTED_SCOPE', 403, { scope_modules: scope });
+  }
+  const reason = typeof admitReason === 'string' ? admitReason.trim() || null : null;
+  // Refused by RANK before the version is fetched, the POST /goals ordering: a
+  // Metic must not learn whether the override would have worked.
+  if (reason !== null && actorRank !== 'archon') {
+    return refuse('ARCHON_REQUIRED_FOR_ADMISSION', 403);
+  }
+
+  // FOR UPDATE, so a version freeze committing between this read and this
+  // transaction's COMMIT cannot leave the goal and its criterion on a version
+  // that closed underneath them (getVersion's own note explains why a plain read
+  // is not enough under READ COMMITTED).
+  const version = await db.getVersion(versionId, { client: deps.client, forUpdate: true });
+  const decision = authorizeGoalCreate({ version, override: reason !== null });
+  if (!decision.ok) {
+    return refuse(decision.body.error, decision.status, { message: decision.body.message, version_status: decision.body.status });
+  }
+
+  const goal = await db.createGoal({
+    versionId,
+    title: title.trim(),
+    subtitle,
+    description,
+    scopeModules: scope,
+    createdBy,
+    // The admission row is written ONLY when the override actually opened the
+    // gate — `overrideApplied`, not "a reason was supplied". A reason on a
+    // planning version changed nothing and must not be filed as a skipped gate.
+    admission: decision.overrideApplied ? { admittedBy: createdBy, reason } : null,
+  }, { client: deps.client });
+
+  const criterion = await db.createCriterion({
+    versionId,
+    criterionId: criterionRef.trim(),
+    criterionMd,
+    goalId: goal.id,
+  }, { client: deps.client });
+
+  return { ok: true, goal, criterion, admitted: decision.overrideApplied };
+}
+
+module.exports = { createRatifiedGoal };

package/modules/lifecycle/lifecycle.js

@@ -19,6 +19,7 @@
 const db = require('./db');
 const classifier = require('./task-classifier');
 const goalSuggest = require('./goal-suggest');
+const goalFromIdea = require('./goal-from-idea');
 const helpRequests = require('./help-requests');
 const taskRecommendations = require('./task-recommendations');
 const activity = require('./activity');
@@ -66,6 +67,19 @@ module.exports = {
   // lifecycle tables and the ideas module may not import lifecycle (ADR 0083).
   ensureMaintenanceGoal: (...a) => db.ensureMaintenanceGoal(...a),
   currentBuildingVersionId: (...a) => db.currentBuildingVersionId(...a),
+  // createRatifiedGoal (task 1004096 / BV2.R17): the GOAL a ratified Full Idea
+  // becomes, plus the done-when criterion its "what does a successful
+  // implementation look like" answer supplies — both rows, in the ideas module's
+  // ratification transaction, or one named refusal.
+  //
+  // ONE CALL RATHER THAN FOUR PRIMITIVES, deliberately. The ideas module could
+  // have been handed getVersion + createGoal + createCriterion +
+  // authorizeGoalCreate and left to compose them, but composing them IS the
+  // goal-creation policy — the scope wall, the rank gates, the R03 building-
+  // version gate — and that policy is a lifecycle judgement. `idea.ratify`'s
+  // floor is Metic, so a caller free to leave the gate out would be a
+  // Metic-reachable way around it. See modules/lifecycle/goal-from-idea.js.
+  createRatifiedGoal: (...a) => goalFromIdea.createRatifiedGoal(...a),
 
   // --- work-tracking READS the staying-core read routes resolve --------------
   // public.js (the status surface): version/ship feed + grade trend.

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.936",
+  "version": "1.19.937",
   "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

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.936'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.937'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/government_seed.mjs

@@ -42,6 +42,7 @@ const NON_GRANT_MIGRATIONS = new Set([
   'government_007_amendments.sql',                 // R14 amendment proposals table (task 1003027)
   'government_008_closed_items_index.sql',         // R16 closed-history index (task 1003029)
   'government_017_board_section_keys_v2.sql',      // BV2.R06 board section_key CHECK widening (task 1004085)
+  'government_018_passed_items_index.sql',         // BV2.R17 passed-item lookup index (task 1004096)
 ]);
 
 // Permission keys RENAMED after the grant migrations that first granted them.