@bongos/core 1.19.936 → 1.19.938

package/modules/government/board.js

@@ -1041,6 +1041,36 @@ async function latestRejectionForIdea(ideaId) {
   });
 }
 
+// ── BV2.R17's read: did the board CARRY this idea? (task 1004096) ───────────
+//
+// The ratification half of the ideator surface turns a Full Idea into a goal,
+// and spec decision 9 is that the ideator RECOMMENDS while the board DECIDES.
+// The ideas module holds the author's recommendation on its own grade row, so
+// without this read "the board decides" would be a sentence in a comment: the
+// only fact stopping a ratification from being one person's opinion is that a
+// sitting actually closed `passed`.
+//
+// Null means "no passing decision on record", which the caller must treat as a
+// refusal and never as an absence it may work around. A returned item, an item
+// still open, and an idea that never reached the board all read the same here,
+// on purpose — none of them is a mandate, and distinguishing them would invite a
+// caller to accept one of them.
+//
+// Frozen, like latestRejectionForIdea, so a caller cannot decorate the record of
+// a decision and pass it on as though the board had said more than it did.
+async function boardPassForIdea(ideaId) {
+  const id = Number(ideaId);
+  if (!Number.isFinite(id) || id <= 0) return null;
+  const row = await db.getLatestPassedItem('full_idea', id);
+  if (!row) return null;
+  return Object.freeze({
+    item_id: row.item_id,
+    outcome: 'passed',
+    opened_at: row.opened_at,
+    closed_at: row.closed_at,
+  });
+}
+
 // ── the summons: what is waiting on THIS member's vote (task 1003271) ───────
 //
 // THE PROBLEM THIS EXISTS TO FIX. Nine items sat open for two days with zero
@@ -1127,6 +1157,7 @@ module.exports = {
   closeItem,
   maybeCloseAfterVote,
   latestRejectionForIdea,
+  boardPassForIdea,
   validateProposedConstitution,
   proposeAmendment,
   boardRoomView,

package/modules/government/db.js

@@ -610,6 +610,38 @@ async function getLatestReturnedItemWithObjection(subjectType, subjectId) {
   return rows[0] || null;
 }
 
+// BV2.R17's read (task 1004096): the most recent PASSED item for a subject.
+//
+// The mirror of getLatestReturnedItemWithObjection above, and the reason it
+// exists separately rather than as a `outcome` parameter on that one: the
+// returned read exists to carry an OBJECTION back to an author and joins the
+// votes table to find it, while this one exists to answer a single yes/no —
+// "did the board carry this?" — and must not depend on any vote row existing.
+// A passed item commonly has NO votes at all (a zero-vote sitting passes under
+// the absence rules, ADR 0175 §3), so the LEFT JOIN that is merely defensive
+// there would be load-bearing here, which is a good sign the two are different
+// questions.
+//
+// Ordering is closed_at DESC, id DESC: an idea returned once and resubmitted can
+// have several closed items, and it is the latest decision that stands.
+//
+// Served by the partial index `government_board_items_passed_by_subject`
+// (government_018), the mirror of government_006's index for the returned read.
+// It needs its own: the table only grows, government_003's two indexes both key
+// on OPEN items and government_008's keys on closed_at alone for the whole-board
+// history feed, so none of them helps a lookup filtered by subject.
+async function getLatestPassedItem(subjectType, subjectId) {
+  const { rows } = await pool.query(
+    `SELECT id AS item_id, closed_at, opened_at, constitution AS decided_under
+       FROM government_board_items
+      WHERE subject_type = $1 AND subject_id = $2 AND outcome = 'passed'
+      ORDER BY closed_at DESC, id DESC
+      LIMIT 1`,
+    [subjectType, subjectId],
+  );
+  return rows[0] || null;
+}
+
 // The expiry sweep's read (R11): every OPEN item whose deadline has passed, on
 // the database clock, oldest deadline first. Served by the partial index
 // government_board_items_open_by_deadline (government_003 built it for exactly
@@ -728,6 +760,7 @@ module.exports = {
   getIdeaCompleteness,
   getExpiredOpenBoardItems,
   getLatestReturnedItemWithObjection,
+  getLatestPassedItem,
   createAmendment,
   getAmendment,
   listOpenBoardItems,

package/modules/government/migrations/government_018_passed_items_index.sql

@@ -0,0 +1,31 @@
+-- government_018_passed_items_index.sql — index the passed-item lookup
+-- (task 1004096 / BV2.R17; a grader efficiency finding, and right — exactly as
+-- government_006 was for the sibling read one outcome over).
+--
+-- `getLatestPassedItem` answers "did the board CARRY this subject?" and runs on
+-- every Full-Idea→goal ratification. It is the mirror of
+-- `getLatestReturnedItemWithObjection`, and it inherits that read's problem in
+-- full: `government_board_items` only grows — one row per window, and a
+-- returned idea can be resubmitted without bound — while the table's two
+-- OPEN-item indexes (`government_003`) both key on `closed_at IS NULL` and the
+-- one closed-item index (`government_008`) keys on `closed_at` alone, for the
+-- whole-board history feed. None of them helps a lookup that filters by
+-- subject. Without this, a ratification scans historical volume that scales
+-- with every sitting the project has ever held.
+--
+-- Partial on outcome='passed' — the only outcome this read asks for — and keyed
+-- (subject_type, subject_id, closed_at DESC) to match the query's WHERE and
+-- ORDER BY exactly, the government_006 shape. Two narrow partial indexes rather
+-- than one wider index over `outcome`: each read asks for exactly one outcome
+-- and never ranges across them, so a shared index would be larger and no more
+-- useful to either.
+--
+-- Additive, idempotent, no rows touched — safe on any database state.
+
+BEGIN;
+
+CREATE INDEX IF NOT EXISTS government_board_items_passed_by_subject
+  ON government_board_items (subject_type, subject_id, closed_at DESC)
+  WHERE outcome = 'passed';
+
+COMMIT;

package/modules/government/routes/government.js

@@ -103,6 +103,13 @@ const governmentPort = {
   // resubmit path in modules/ideas resolves this to show what was objected to
   // and to check whether the flagged section actually changed.
   latestRejectionForIdea: board.latestRejectionForIdea,
+  // BV2.R17 (task 1004096): the record of the board having CARRIED an idea, or
+  // null. The ideas module's ratification path resolves this to check the one
+  // fact that makes turning a Full Idea into a goal a board decision rather
+  // than a ratifier's preference. Read-only, like every other entry here — there
+  // is no counterpart that records an outcome, and there must never be one: an
+  // outcome is written by a close, never by the module reading it.
+  boardPassForIdea: board.boardPassForIdea,
 };
 
 function registerSeams() {

package/modules/hall-ui/public/deploy.js

@@ -6,7 +6,7 @@
 // pipeline and the ONLY act that makes shipped work visible to users — and it was
 // reachable from exactly one place, a shell on the control-plane box holding an ssh key.
 // An agent could not close the loop either: the permission classifier blocks a mutating
-// `sudo -u lars` over ssh by design. So the one gate that is the owner's to hold was the
+// `sudo -u <app user>` over ssh by design. So the one gate that is the owner's to hold was the
 // one gate with no instrument. This page is the instrument.
 //
 // WHY THE PROJECTS ARE HERE AND NOT IN THEIR OWN HALLS. The obvious shape — each owner

package/modules/ideas/inbox.js

@@ -848,4 +848,15 @@ module.exports = {
   parseProposalBody: ratify.parseProposalBody,
   KARMA_RATIFY_DELTA: ratify.KARMA_RATIFY_DELTA,
   KARMA_RATIFY_REASON: ratify.KARMA_RATIFY_REASON,
+  // Full-Idea → GOAL ratification, the goal half beside it (task 1004096 /
+  // BV2.R17); see ratify.js on why the two halves are not symmetrical.
+  //
+  // ONLY THE TRANSACTION IS RE-EXPORTED. `composeGoalFromFullIdea` and
+  // `GOAL_SHAPE_BY_TEMPLATE` are deliberately NOT on the facade: nothing outside
+  // ratify.js calls either, and a re-export no caller needs is an unused export
+  // the dead-code ratchet counts. The facade's job is to keep the ~20 callers of
+  // the pre-carve surface working, not to publish everything a new file declares
+  // — anything that wants the pure composer requires ./ratify directly, as the
+  // test does.
+  ratifyFullIdeaAsGoal: ratify.ratifyFullIdeaAsGoal,
 };

package/modules/ideas/migrations/ideas_010_goal_ratification.sql

@@ -0,0 +1,103 @@
+-- ideas_010_goal_ratification.sql — the durable record of a Full Idea having
+-- been ratified INTO A GOAL (task 1004096 / BV2.R17, spec R23 in
+-- docs/specs/bongos-v2-ideator-surface.md; spec decision 9).
+--
+-- WHAT THIS TABLE IS FOR. The ratification writes a goal and a done-when
+-- criterion into the LIFECYCLE tables and flips the idea to `promoted`. Those
+-- rows are the outcome; none of them records the ACT. Afterwards the goal looks
+-- exactly like a goal someone scoped in a planning session, and the idea looks
+-- exactly like an idea that became a task. Nothing left says who ratified it,
+-- under which board decision, with what scope, or what the author had
+-- recommended — and "a thought is never lost between having it and learning what
+-- it caused" (criterion `ideator-nothing-is-lost`) is not met by an outcome with
+-- no provenance. This is the `criterion_proposal_audit` argument (migration 042)
+-- applied to the goal half.
+--
+-- `idea_id` IS UNIQUE, AND THAT IS THE IDEMPOTENCY. The transaction also refuses
+-- an idea whose status is no longer `open`, which catches the ordinary second
+-- attempt; this constraint is what catches the two-concurrent-ratifications race
+-- the status check cannot, because both would read `open` before either wrote.
+-- The second INSERT trips 23505 and its whole transaction rolls back, so the
+-- outcome is one goal, never two.
+--
+-- `recommendation_at_filing` IS PROVENANCE, NOT AN INPUT. It stores what the
+-- AUTHOR recommended (ideas_009) beside what the BOARD chose, so the two can be
+-- compared after the fact — how often does the board agree with the ideator? —
+-- without that ever having influenced the ratification. NULL is first-class and
+-- permanent here for the same reason it is on ideas_grades: every Full Idea
+-- filed before BV2.R13 shipped carries no recommendation, there is no backfill,
+-- and inventing one would put a scope opinion in an author's mouth. Nothing may
+-- branch on this column.
+--
+-- FOREIGN KEYS POINT AT CORE TABLES, which is allowed and is what the module's
+-- own precedent does: ideas_002 references `tasks(id)`, ideas_005 references
+-- `builders(id)`. The namespacing rule (ADR 0083 §Decision #5) is about which
+-- tables a module may CREATE and ALTER, not about what its own rows may point
+-- at.
+--
+-- NONE OF THE FOUR FKs CASCADES, and that is the deliberate part. An audit row
+-- exists to say what happened; a cascade would delete the record of a
+-- ratification along with the goal it produced, which is precisely when someone
+-- wants to read it. `criterion_proposal_audit` (migration 042) takes the same
+-- posture on the same reasoning. The consequence is accepted: a hard DELETE of a
+-- ratified goal is refused while its audit row stands, and that refusal is
+-- correct — goals are archived, not deleted.
+--
+-- `scope_modules` is stored as text[] matching `goals.scope_modules`, because
+-- WHICH WALL the goal was given is part of what was decided — a ratification
+-- that admitted a protected module is an Archon act and the row has to say so
+-- even after someone later widens or narrows the live goal.
+--
+-- Module migrations are ADDITIVE and NAMESPACED. There is no down-migration.
+-- Idempotent: safe to re-run.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS ideas_goal_ratifications (
+  id                      bigserial PRIMARY KEY,
+  idea_id                 bigint NOT NULL REFERENCES idea_inbox(id),
+  goal_id                 bigint NOT NULL REFERENCES goals(id),
+  criterion_id            bigint NOT NULL REFERENCES done_when_criteria(id),
+  board_item_id           bigint,
+  target_version          text   NOT NULL,
+  scope_modules           text[] NOT NULL DEFAULT '{}',
+  recommendation_at_filing text,
+  proposed_by             bigint REFERENCES builders(id),
+  ratified_by             bigint NOT NULL REFERENCES builders(id),
+  notes_md                text   NOT NULL DEFAULT '',
+  ratified_at             timestamptz NOT NULL DEFAULT now()
+);
+
+-- One ratification per idea — see the header. Added separately and guarded so it
+-- still lands on an instance where the table was created before this clause
+-- existed.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'ideas_goal_ratifications_idea_uniq'
+  ) THEN
+    ALTER TABLE ideas_goal_ratifications
+      ADD CONSTRAINT ideas_goal_ratifications_idea_uniq UNIQUE (idea_id);
+  END IF;
+END $$;
+
+-- Mirrors ideas_grades_recommendation_chk one table over: the vocabulary is
+-- closed, and NULL means "the author did not say".
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'ideas_goal_ratifications_recommendation_chk'
+  ) THEN
+    ALTER TABLE ideas_goal_ratifications
+      ADD CONSTRAINT ideas_goal_ratifications_recommendation_chk
+      CHECK (recommendation_at_filing IS NULL OR recommendation_at_filing IN ('goal', 'criterion'));
+  END IF;
+END $$;
+
+-- "What did this goal come from" — the read the goal surface will want when it
+-- shows a goal's origin. The idea direction is already served by the unique
+-- constraint's index.
+CREATE INDEX IF NOT EXISTS ideas_goal_ratifications_goal_idx
+  ON ideas_goal_ratifications (goal_id);
+
+COMMIT;

package/modules/ideas/module.json

@@ -10,6 +10,7 @@
   "contributes": {
     "routes": [
       "inbox",
+      "ratify-goal",
       "blockers"
     ],
     "pollers": [

package/modules/ideas/ratify.js

@@ -13,7 +13,9 @@
 // Archon ratifies it into a version's scope. Keeping it beside the triage
 // writes made the two look like the same kind of act. They are not.
 
-const { pool } = require('../../src/module-api');
+const api = require('../../src/module-api');
+const { pool } = api;
+const { templateFor, fieldOrder } = require('./templates');
 
 // -------------------------------------------------------------------------
 // Criterion-proposal ratification (V3.R31 / #252)
@@ -203,9 +205,294 @@ async function ratifyCriterionProposal(ideaId, ratifierId, { notesMd = '' } = {}
   }
 }
 
+// -------------------------------------------------------------------------
+// THE GOAL HALF (task 1004096 / BV2.R17, spec R23, criterion
+// `ideator-full-idea-shapes-the-space`)
+//
+// The criterion half above turns a `criterion-proposal` — an idea filed as JSON,
+// explicitly to become a ring inside an existing well — into a
+// `done_when_criteria` row. This half turns a FULL IDEA, filed as five prose
+// answers by someone who was thinking rather than scoping, into a GOAL: a
+// gravity well of its own, with the "what does a successful implementation look
+// like" answer as its first done-when criterion.
+//
+// THE TWO HALVES ARE NOT SYMMETRICAL, and reading them as if they were is the
+// mistake to avoid:
+//
+//   • THE SUBJECT DIFFERS. The criterion half parses `body_md` as JSON the
+//     proposer wrote FOR ratification. This half reads a graded Full Idea's
+//     `field_values` — prose written to express a thought, which nobody wrote
+//     with a goal row in mind. So the shape has to be DERIVED, and which answer
+//     becomes which part of the goal is a decision recorded below.
+//
+//   • THE AUTHORITY DIFFERS. A criterion proposal is one Metic's suggestion and
+//     one ratifier's judgement; there is no board in it. A Full Idea has already
+//     been through the Board Room (`government.openBoardWindowForIdea` fires when
+//     its grade lands), and spec decision 9 is that the ideator RECOMMENDS while
+//     the BOARD DECIDES. So this half is GATED on a passed sitting, and the
+//     author's own `recommendation` is read for the audit row only.
+//
+//   • NOBODY IS PAID HERE. The criterion half awards KARMA_RATIFY_DELTA to the
+//     proposer, because nothing else ever will. A Full Idea's author was already
+//     paid at the board CLOSE — karma by `awardAuthorRatifyKarma` and credit by
+//     `awardIdeaGovernancePassCredit`, both inside the close transaction. Paying
+//     again on the ratification would pay twice for one thought, and the second
+//     payment would be invisible beside the first. This is why there is no karma
+//     INSERT below, and it is a decision rather than an omission.
+
+// WHICH ANSWER BECOMES WHICH PART OF THE GOAL, per template vintage.
+//
+// THIS IS RATIFICATION POLICY, NOT TEMPLATE SHAPE, which is why it lives here
+// and not as two more keys inside the declarations in templates.js. Those
+// declarations are FROZEN — a vintage is never edited, because `substanceMin`
+// feeds `completeness_score` and that feeds credits — and "this field supplies a
+// goal's done-when" is a statement about what ratification does with an answer,
+// not about what the question is or what it costs to answer it.
+//
+// `base-v1` IS DELIBERATELY ABSENT, and that is the honest answer rather than a
+// gap. Its five questions are Purpose / Big Picture / Why did you have it / Why
+// does it matter / How does it fit — an argument for a thought, with no answer
+// anywhere in it describing a finished implementation. A goal needs a done-when
+// criterion to be achievable at all (ADR 0263's close gate reads them, so a goal
+// born without one holds its version open forever), and there is nothing in a
+// base-v1 filing to write one FROM. Picking its closest-sounding field would be
+// inventing a success criterion on the author's behalf — the never-invent-a-field
+// rule, and the one place in this file where it bites. A base-v1 Full Idea is
+// refused with TEMPLATE_HAS_NO_GOAL_SHAPE, naming the vintage; its author can
+// resubmit against the current questions, which is what the resubmit path is for.
+//
+// ADDING A VINTAGE MEANS ADDING AN ENTRY HERE. Nothing falls back — an unmapped
+// template refuses, rather than guessing at a key that happens to exist.
+const GOAL_SHAPE_BY_TEMPLATE = Object.freeze({
+  // The five questions a Full Idea is asked today (BASE_V2_TEMPLATE). The
+  // mapping is the one the proof task (BV2.R25) states: scope from "scope it as
+  // best as you can here", done-when from "what does a successful
+  // implementation of the idea look like".
+  'base-v2': Object.freeze({ doneWhenField: 'success' }),
+});
+
+// composeGoalFromFullIdea — the five answers → the goal's prose + its first
+// criterion. PURE: no DB, no clock, no doorway, so the route can refuse before
+// opening a transaction and a test can exercise every branch with no harness.
+//
+// EVERY ANSWER LANDS IN THE DESCRIPTION, including the one that also becomes the
+// criterion. The done-when is a one-line gate a version-close reads; the
+// description is what a builder opening the goal actually reads, and dropping
+// the success answer from it to avoid "duplication" would take the clearest
+// statement of the goal's purpose out of the one place someone looks for it.
+//
+// ORDER COMES FROM `fieldOrder`, never from Object.keys(field_values) — jsonb
+// does not preserve key order, so iterating the stored row shows the five
+// answers in whatever order Postgres chose (templates.js' own header says so).
+// LABELS come from the declaration too, so a v1 row would render under v1
+// labels if a v1 shape were ever declared.
+function composeGoalFromFullIdea({ ideaId, templateKey, fieldValues } = {}) {
+  const template = templateFor(templateKey);
+  if (!template) return { ok: false, reason: 'unknown_template', template_key: templateKey ?? null };
+  const shape = Object.hasOwn(GOAL_SHAPE_BY_TEMPLATE, templateKey) ? GOAL_SHAPE_BY_TEMPLATE[templateKey] : null;
+  if (!shape) return { ok: false, reason: 'template_has_no_goal_shape', template_key: templateKey };
+  if (!fieldValues || typeof fieldValues !== 'object' || Array.isArray(fieldValues)) {
+    return { ok: false, reason: 'field_values_missing' };
+  }
+
+  const doneWhen = fieldValues[shape.doneWhenField];
+  if (typeof doneWhen !== 'string' || doneWhen.trim() === '') {
+    // A Full Idea cannot normally reach here with a blank required field —
+    // validateFieldValues refuses that at capture. It is checked anyway because
+    // the alternative is a goal whose only criterion is an empty string, which
+    // the close gate would read as satisfiable by nothing.
+    return { ok: false, reason: 'done_when_answer_missing', field: shape.doneWhenField };
+  }
+
+  const sections = [];
+  for (const key of fieldOrder(template)) {
+    const field = template.fields.find((f) => f.key === key);
+    const value = fieldValues[key];
+    // A field the stored row simply does not carry is SKIPPED, not rendered as an
+    // empty heading. Only required fields are guaranteed present, and a heading
+    // with nothing under it reads as a question the author declined to answer
+    // rather than one the template added later.
+    if (typeof value !== 'string' || value.trim() === '') continue;
+    sections.push(`### ${field.label}\n\n${value.trim()}`);
+  }
+  if (sections.length === 0) return { ok: false, reason: 'field_values_empty' };
+
+  // The provenance line is FIRST and is prose, not a machine key: the durable
+  // machine record is the ideas_goal_ratifications row. This is so a builder
+  // opening the goal learns, without asking anyone, that its scope is somebody's
+  // thought and where to go and read it whole.
+  const origin = `> Ratified from Full Idea [#${ideaId}](/idea/${ideaId}) — its five answers, as written.`;
+  return {
+    ok: true,
+    description: [origin, ...sections].join('\n\n'),
+    criterionMd: doneWhen.trim(),
+    doneWhenField: shape.doneWhenField,
+  };
+}
+
+// ratifyFullIdeaAsGoal — the whole act, in one transaction.
+//
+// a. lock the idea + its grade row      e. write the ideas_goal_ratifications row
+// b. check the board carried it         f. COMMIT
+// c. compose the goal's prose
+// d. create the goal + its criterion (through the `lifecycle` port)
+//
+// WHAT THE CALLER DECIDES AND WHAT IT DOES NOT. `targetVersion`, `scopeModules`
+// and `admitReason` are the BOARD'S choices, stated by the ratifier: no prose
+// answer can supply which version a goal belongs to or which modules it may
+// touch, and guessing either would be the system deciding scope — the exact
+// thing spec decision 9 puts in the board's hands. What the caller may NOT do is
+// decide whether the create is allowed: `actorRank` is passed through to the
+// lifecycle port, which applies every gate POST /goals applies.
+//
+// THE AUTHOR'S `recommendation` IS READ AND NEVER BRANCHED ON. It is copied into
+// the audit row beside what the board chose, so "how often does the board agree
+// with the ideator" is answerable later. A ratification of an idea whose author
+// recommended 'criterion' is NOT refused here — the board may well have decided
+// the thought was bigger than its author thought, and refusing would make the
+// recommendation a decision, which is the one thing it is not.
+async function ratifyFullIdeaAsGoal(
+  ideaId, ratifierId,
+  { targetVersion, scopeModules = [], admitReason = null, actorRank = null, notesMd = '' } = {}
+) {
+  const id = Number(ideaId);
+  if (!Number.isFinite(id)) throw { code: 'BAD_ID' };
+  const rid = Number(ratifierId);
+  if (!Number.isFinite(rid)) throw { code: 'BAD_RATIFIER' };
+  if (!targetVersion || typeof targetVersion !== 'string') throw { code: 'TARGET_VERSION_REQUIRED' };
+
+  // BOTH PORTS RESOLVE BEFORE THE TRANSACTION OPENS, and both FAIL CLOSED. An
+  // instance without the lifecycle module cannot hold goals at all; an instance
+  // without government has no board, and "the board decided" cannot be true
+  // where there is no board. A missing authority system is a denial, never an
+  // admission (the requirePermission posture).
+  const lifecycle = api.resolveOptional && api.resolveOptional('lifecycle');
+  if (!lifecycle || typeof lifecycle.createRatifiedGoal !== 'function') {
+    throw { code: 'NO_LIFECYCLE', detail: 'This instance cannot create goals — the lifecycle module is not mounted.' };
+  }
+  const government = api.resolveOptional && api.resolveOptional('government');
+  if (!government || typeof government.boardPassForIdea !== 'function') {
+    throw { code: 'NO_BOARD', detail: 'This instance has no Board Room, so a Full Idea cannot be ratified.' };
+  }
+
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+
+    // a. Read + lock the idea and its grade row together. LEFT JOIN, the module's
+    //    standing rule: an idea with no grade row reads as 'quick', and that is a
+    //    refusal below rather than a missing row here. FOR UPDATE names the idea
+    //    table explicitly — a bare FOR UPDATE over an outer join is not lockable
+    //    in Postgres, and locking the idea is what serialises two ratifiers.
+    const { rows: ideaRows } = await client.query(
+      `SELECT i.id, i.title, i.kind, i.status, i.captured_by,
+              COALESCE(g.grade, 'quick') AS grade,
+              g.template_key, g.field_values, g.recommendation
+         FROM idea_inbox i
+         LEFT JOIN ideas_grades g ON g.idea_id = i.id
+        WHERE i.id = $1
+        FOR UPDATE OF i`,
+      [id]
+    );
+    if (ideaRows.length === 0) throw { code: 'IDEA_NOT_FOUND' };
+    const idea = ideaRows[0];
+    if (idea.grade !== 'full') throw { code: 'NOT_A_FULL_IDEA', grade: idea.grade };
+    if (idea.status !== 'open') throw { code: 'IDEA_NOT_OPEN', status: idea.status };
+
+    // b. The board gate. Spec decision 9 in one statement: without a sitting that
+    //    closed `passed`, this is a ratifier's preference and not a decision.
+    //    Read through the port, outside its own transaction (a closed item is
+    //    terminal, so there is nothing here for a lock to protect).
+    const pass = await government.boardPassForIdea(id);
+    if (!pass) throw { code: 'BOARD_HAS_NOT_PASSED' };
+
+    // c. Compose. Pure, and its refusals are the caller's 400s.
+    const composed = composeGoalFromFullIdea({
+      ideaId: idea.id, templateKey: idea.template_key, fieldValues: idea.field_values,
+    });
+    if (!composed.ok) throw { code: 'CANNOT_COMPOSE_GOAL', reason: composed.reason, ...composed };
+
+    // d. The goal + its first criterion, through the port, on THIS client.
+    //    `criterionRef` is derived from the idea, so UNIQUE (version_id,
+    //    criterion_id) is a second guard against a double ratification onto the
+    //    same version — the `proposal-<idea_id>` trick, one half over.
+    //
+    //    created_by IS THE RATIFIER, NOT THE AUTHOR, and that is a security
+    //    decision rather than a credit one. createGoal makes created_by the
+    //    goal's owner AND inserts a 'lead' membership row, and goal leads author
+    //    tasks inside the scope wall. Filing an idea is open to every rank, so
+    //    owning the goal your idea became would turn "have a thought that the
+    //    board likes" into a grant of authority nobody reviewed. The author's
+    //    claim on the thought is preserved where claims belong — the audit row
+    //    below, and the origin line in the description.
+    const made = await lifecycle.createRatifiedGoal({
+      versionId: targetVersion,
+      title: idea.title,
+      description: composed.description,
+      scopeModules,
+      createdBy: rid,
+      criterionMd: composed.criterionMd,
+      criterionRef: `idea-${idea.id}`,
+      admitReason,
+      actorRank,
+    }, { client });
+    if (!made.ok) throw { code: made.code, status: made.status, ...made };
+
+    // e. Mark the idea promoted. promoted_to_task_id stays NULL — a goal is not
+    //    a task, the same reading the criterion half takes.
+    await client.query(
+      `UPDATE idea_inbox
+          SET status              = 'promoted',
+              promoted_to_task_id = NULL,
+              reviewed_at         = now()
+        WHERE id = $1`,
+      [idea.id]
+    );
+
+    // f. The audit row — who ratified what, under which decision, with what the
+    //    author had recommended beside it.
+    const { rows: auditRows } = await client.query(
+      `INSERT INTO ideas_goal_ratifications
+         (idea_id, goal_id, criterion_id, board_item_id, target_version,
+          scope_modules, recommendation_at_filing, proposed_by, ratified_by, notes_md)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+       RETURNING id, ratified_at`,
+      [
+        idea.id, made.goal.id, made.criterion.id, pass.item_id, targetVersion,
+        Array.isArray(scopeModules) ? scopeModules : [],
+        idea.recommendation ?? null,
+        idea.captured_by, rid, notesMd || '',
+      ]
+    );
+
+    await client.query('COMMIT');
+    return {
+      goal: made.goal,
+      criterion: made.criterion,
+      admitted: made.admitted,
+      audit_id: auditRows[0].id,
+      ratified_at: auditRows[0].ratified_at,
+      board_item_id: pass.item_id,
+      // Reported back so a caller can see what the author had recommended and
+      // what the board did with it, without a second read. NULL stays NULL.
+      recommendation_at_filing: idea.recommendation ?? null,
+      done_when_from: composed.doneWhenField,
+      proposer_id: idea.captured_by,
+    };
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
 module.exports = {
   KARMA_RATIFY_DELTA,
   KARMA_RATIFY_REASON,
   parseProposalBody,
   ratifyCriterionProposal,
+  GOAL_SHAPE_BY_TEMPLATE,
+  composeGoalFromFullIdea,
+  ratifyFullIdeaAsGoal,
 };