@bongos/core 1.25.19 → 1.25.21

package/modules/lifecycle/home-city.js

@@ -370,14 +370,28 @@ function shapeCity(raw, viewer) {
   };
 }
 
+// readFoundingDistrict() — while the project is founding, which government-district
+// buildings are not raised yet (task 1005112): the onboarding port's own answer, the one
+// /me carries. null when not founding, the module is off, or the read fails, which
+// draws the district whole, exactly as before.
+async function readFoundingDistrict(resolve = api.resolveOptional) {
+  try {
+    const onboarding = resolve('onboarding');
+    const f = onboarding && typeof onboarding.foundingModeFor === 'function' ? await onboarding.foundingModeFor() : null;
+    return f && f.active === true && f.unbuilt && typeof f.unbuilt === 'object' ? { stage: f.stage, unbuilt: f.unbuilt } : null;
+  } catch (_) {
+    return null;
+  }
+}
+
 // The GET /home/city handler, injectable so a test drives it with no express.
-function homeCityHandler({ log, read = readCity } = {}) {
+function homeCityHandler({ log, read = readCity, founding = readFoundingDistrict } = {}) {
   return async function homeCityRoute(req, res) {
     try {
       const viewer = req.builder ? { id: req.builder.id, rank: req.builder.rank } : null;
-      const raw = await read({ weeks: req.query && req.query.weeks, viewer });
+      const [raw, district] = await Promise.all([read({ weeks: req.query && req.query.weeks, viewer }), founding()]);
       res.set('Cache-Control', 'private, max-age=60');
-      res.json(shapeCity(raw, viewer));
+      res.json({ ...shapeCity(raw, viewer), founding: district });
     } catch (err) {
       if (log) log.error('GET /home/city', err);
       res.fail('home_city_failed', { status: 500, message: 'internal error' });

package/modules/onboarding/founding-mode.js

@@ -50,6 +50,48 @@ const WAKES = Object.freeze({
 });
 const WAKES_WHEN_ALIVE = Object.freeze(['collab', 'roster']);
 
+// THE GOVERNMENT DISTRICT RISES WITH GENESIS (task 1005112; V3 spec, task-cleanup
+// answer 1: "Genesis is the founding of the government district"). Home's city draws
+// the district as nine civic buildings (city-draw.js CIVIC_SLOTS, keyed as below). While
+// a project is founding, a building stands only once the stage that raises it is behind;
+// until then its plot is a marked-out foundation. Same rule and same shape as WAKES, so
+// the server decides and every presentation (the city, the genesis card) reads it.
+// Every stage raises something, so no stage ends the sense of progress; automation, the
+// project running itself, rises when the project comes alive.
+const BUILDS = Object.freeze({
+  scope: Object.freeze(['planning']),
+  strategize: Object.freeze(['release']),
+  charter: Object.freeze(['charter', 'people']),
+  legalize: Object.freeze(['treasury']),
+  legislation: Object.freeze(['rules', 'review', 'disputes']),
+});
+const BUILDS_WHEN_ALIVE = Object.freeze(['automation']);
+
+// unbuiltBuildings(stage) — PURE. { buildingKey: raisingStage } for every district
+// building not yet raised at this stage (the asleepRooms rule), or null for no stage.
+function unbuiltBuildings(stage) {
+  const at = STAGES.indexOf(stage);
+  if (at < 0) return null;
+  const out = {};
+  for (const [raising, keys] of Object.entries(BUILDS)) {
+    if (STAGES.indexOf(raising) >= at) for (const k of keys) out[k] = raising;
+  }
+  for (const k of BUILDS_WHEN_ALIVE) out[k] = 'alive';
+  return out;
+}
+
+// What finishing a stage that opens no room gives the founder, in a sentence (task
+// 1005112). Three stages wake no sidebar room since tasks 1005046 and 1005199, and a
+// founder must never be told nothing happens: this is said on the stage's row instead.
+// Each line is true today: the charter puts the government in force, legalize settles
+// how contributors are rewarded, and legislation's pass is what brings the project to
+// life, which opens every room. A stage that wakes rooms says those instead.
+const EARNS = Object.freeze({
+  charter: 'Puts your government in force',
+  legalize: 'Settles how contributors are rewarded',
+  legislation: 'Brings the project to life: every room opens',
+});
+
 // The project_settings keys. Namespaced 'founding.' like 'mingle.' and 'attention.'.
 const KEYS = Object.freeze({
   ACTIVE: 'founding.active',
@@ -118,6 +160,8 @@ function shapeFoundingMode(rows, now = new Date()) {
     stage_count: STAGES.length - 1,
     day: dayOf(rows.startedAt, now),
     asleep,
+    // The government district's buildings not yet raised (task 1005112), keyed like CIVIC_SLOTS.
+    unbuilt: unbuiltBuildings(stage),
     // Who closing the current stage is waiting on (spec D7) — display names, at most
     // five, from the government module's genesis-stage sitting (task 1004429). null
     // when the stage is not sitting, nobody is left to vote, or the read is missing.
@@ -226,5 +270,5 @@ async function setFoundingMode({ active, stage } = {}, builderId = null, deps =
 module.exports = {
   STAGES, WAKES, WAKES_WHEN_ALIVE, KEYS, stageAtKey,
   dayOf, shapeFoundingMode, waitingOnFromGovernment,
-  foundingModeFor, setFoundingMode,
+  foundingModeFor, setFoundingMode, EARNS, BUILDS, BUILDS_WHEN_ALIVE,
 };

package/modules/onboarding/genesis-home.js

@@ -194,6 +194,8 @@ function shapeGenesis({ mode, plan, tasks = {}, board = {}, stageAt = {}, boardR
       plate: info.plate,
       done_when: info.done_when,
       wakes: fm.WAKES[key] || [],
+      earns: (fm.WAKES[key] || []).length ? null : (fm.EARNS[key] || null), // task 1005112
+      raises: fm.BUILDS[key] || [], // task 1005112: the district buildings this stage raises
       days,
       minutes,
       due,
@@ -393,7 +395,10 @@ async function savePlan(body, builderId, deps = {}) {
 // Never refuses the plan — the plan is saved first, and a choice that cannot be filed
 // says why in `state`:
 //   none          no government was picked
-//   in_force      the constitution already reads as that form (Monarchy at birth)
+//   in_force      the constitution already reads as that form (Monarchy at birth):
+//                 nothing is filed, `message` says so and `complete` is true
+//   adopted       filed AND decided in the same call: the founder is the board's only
+//                 member under first_ratifier (task 1005130), so it is in force now
 //   sitting       filed; `item_id`, and `one_vote_decides` when one yes carries it
 //   needs_council Foundation, which needs a council rank before it can seat anyone
 //   not_filed     anything else (`reason`), or no government module to file it with
@@ -409,16 +414,25 @@ async function applyGovernmentChoice(form, builderId, s) {
   }
   if (out && out.ok) {
     const snap = (out.item && out.item.constitution) || {};
+    // task 1005130: the founder is the board's only member, so choosing it WAS their
+    // one yes — it is in force now, and saying "in the Board Room" would be untrue.
+    if (out.decided && out.decided.closed && out.decided.outcome === 'passed') {
+      const name = out.reads_as ? out.reads_as.name : form;
+      return { state: 'adopted', form, item_id: out.item ? String(out.item.id) : null, complete: true,
+        message: `${name} is in force now. As the board's only member, choosing it was your one yes.` };
+    }
     return {
       state: 'sitting',
       form,
       item_id: out.item ? String(out.item.id) : null,
       one_vote_decides: snap.pass_rule === 'first_ratifier',
       reads_as: out.reads_as ? out.reads_as.name : null,
+      message: out.what_happens_next || null, // task 1005130: what happens next, in words
     };
   }
   const reason = (out && out.reason) || 'charter_failed';
-  if (reason === 'no_change') return { state: 'in_force', form };
+  // task 1005130: already in force is said plainly and counts as done, never silent.
+  if (reason === 'no_change') return { state: 'in_force', form, complete: true, message: out.message || null };
   if (reason === 'council_needs_a_rank') return { state: 'needs_council', form };
   return { state: 'not_filed', form, reason };
 }

package/modules/onboarding/guide-handoff.js

@@ -0,0 +1,109 @@
+'use strict';
+
+// modules/onboarding/guide-handoff.js — THE GUIDE'S ANSWERS, ARRIVED (task 1005274, goal
+// 1000106). The founder talked with the start-a-project guide before signing up; the hub
+// stamped what came out of it on the new project (modules/provisioning/guide-handoff.js),
+// and it reached this instance as one web.env line, mapped by src/branding.js onto the
+// server-only founding.guideHandoff (base64url JSON { scope, markdown }).
+//
+// Here it lands, once, in the two places a later reader already looks:
+//   * The Genesis scope interview: each carried answer is written as ORIGIN carried_over
+//     through genesis-work's own if-empty write, so it never replaces anything the founder
+//     already typed, and the interview shows it as carried over and editable (any edit by
+//     the founder makes it theirs). Only the questions the hub's explicit map answered are
+//     written; the rest stay empty.
+//   * The hand-off file: kept in project_settings (HANDOFF_KEY) and served at the top of
+//     GET /founding/context, the read `npx bongos genesis context` prints and the project
+//     context scaffold (docs/project-context.template.md) tells every session to run first.
+//     So the founder's own AI meets it in its first session without being told where.
+//
+// WHEN: lazily, on the first genesis read (routes/genesis-work.js), not at boot — the
+// founding-birth.js reasoning: by then the database is up and the founder is seated. NOT
+// tied to genesis being switched on: a paused project still keeps its founder's words.
+// ONCE: the hand-off file's presence is the done-mark, written LAST, so a run that fails
+// half-way is retried and the if-empty writes make the retry harmless. No marker (a project
+// whose founder never used the guide, or one made before this shipped): resolves without
+// touching the database.
+
+const HANDOFF_KEY = 'founding.guide_handoff';
+
+// handoffMarker(founding) — PURE. founding.guideHandoff → { scope, markdown } or null.
+function handoffMarker(founding) {
+  const raw = founding && typeof founding === 'object' ? founding.guideHandoff : null;
+  if (typeof raw !== 'string' || !raw.trim()) return null;
+  try {
+    const h = JSON.parse(Buffer.from(raw.trim(), 'base64url').toString('utf8'));
+    if (!h || typeof h.markdown !== 'string' || !h.markdown.trim()) return null;
+    const scope = h.scope && typeof h.scope === 'object' && !Array.isArray(h.scope) ? h.scope : {};
+    return { scope, markdown: h.markdown };
+  } catch (_) {
+    return null;
+  }
+}
+
+function markerFrom(deps) {
+  if (Object.prototype.hasOwnProperty.call(deps, 'marker')) return deps.marker;
+  try { return handoffMarker(require('../../src/module-api').branding().founding); } catch (_) { return null; }
+}
+
+const settingsOf = (deps) => ({
+  get: deps.getSetting || require('../../src/module-api').projectSettings.get,
+  set: deps.setSetting || require('../../src/module-api').projectSettings.set,
+});
+
+// carryOver(deps) → what it did: { ran:false, reason } or { ran:true, carried:[ids], kept:[ids] }.
+//   carried  questions now holding the guide's words
+//   kept     questions the founder had already answered, left alone
+async function carryOver(deps = {}) {
+  const marker = markerFrom(deps);
+  if (!marker) return { ran: false, reason: 'no_handoff' };
+  const { get, set } = settingsOf(deps);
+  const done = await get(HANDOFF_KEY);
+  if (done && done.value) return { ran: false, reason: 'already' };
+  const work = require('./genesis-work');
+  const carried = [];
+  const kept = [];
+  for (const [question, text] of Object.entries(marker.scope)) {
+    if (typeof text !== 'string' || !text.trim()) continue;
+    const r = await work.setAnswer('scope', question, { state: 'answered', text, origin: 'carried_over' }, null, deps, { ifEmpty: true });
+    if (r.ok === false) continue;   // a question this core no longer asks: skipped, never invented
+    (r.changed ? carried : kept).push(question);
+  }
+  await set(HANDOFF_KEY, marker.markdown, null);
+  return { ran: true, carried, kept };
+}
+
+// ensureHandoff(deps) — the once-per-process door the reads call. Never throws: a hand-off
+// hiccup must never fail the read that triggered it; a failed run is retried next read.
+let once = null;
+function ensureHandoff(deps = {}) {
+  if (deps.fresh) return carryOver(deps).catch(() => ({ ran: false, reason: 'error' }));
+  if (once) return once;
+  const p = carryOver(deps).then((r) => r, (err) => {
+    once = null;
+    try { require('../../src/module-api').logger('onboarding').error('[onboarding] guide hand-off failed', err); } catch (_) { /* no logger */ }
+    return { ran: false, reason: 'error' };
+  });
+  once = p;
+  return p;
+}
+
+// readHandoff(deps) → the hand-off file's markdown, or null. No marker, no read: a project
+// whose founder never used the guide never touches the database for it.
+async function readHandoff(deps = {}) {
+  if (!markerFrom(deps)) return null;
+  const row = await settingsOf(deps).get(HANDOFF_KEY);
+  return row && typeof row.value === 'string' && row.value.trim() ? row.value : null;
+}
+
+// withHandoff(context, markdown) — PURE. The planning read with the hand-off file first:
+// it is where the project started, and the founder's own answers below it are their
+// latest word.
+function withHandoff(context, markdown) {
+  if (!markdown) return { ...context, handoff: null };
+  const said = context.markdown ? `\n---\n\n${context.markdown}` : '';
+  return { ...context, handoff: markdown, markdown: `${markdown.trimEnd()}\n${said}` };
+}
+
+
+module.exports = { HANDOFF_KEY, handoffMarker, carryOver, ensureHandoff, readHandoff, withHandoff };

package/modules/onboarding/routes/genesis-work.js

@@ -12,6 +12,7 @@
 
 const api = require('../../../src/module-api');
 const work = require('../genesis-work');
+const handoff = require('../guide-handoff');   // the start-a-project guide's answers, carried in once (task 1005274)
 
 const REFUSALS = {
   unknown_stage: 404, unknown_question: 404, bad_door: 400, bad_state: 400, bad_origin: 400,
@@ -37,13 +38,16 @@ module.exports = function mountGenesisWorkRoutes(router, deps = {}) {
   const stage = (req) => String(req.params.stage);
   const q = (req) => String(req.params.question);
 
-  // The read path for every door and for AI sessions planning a goal or task.
-  router.get('/founding/work', api.requireBuilder, handle(async () => ({ stages: await work.readAll(deps) })));
-  router.get('/founding/context', api.requireBuilder, handle(() => work.readContext(deps)));
-  router.get('/founding/work/:stage', api.requireBuilder, handle((req) => work.readStage(stage(req), deps)));
+  // The read path for every door and for AI sessions planning a goal or task. Each first
+  // lands the guide's hand-off if one is waiting (../guide-handoff.js), so the scope
+  // interview opens with the carried-over answers and the context leads with the file.
+  const arrived = (fn) => async (req) => { await handoff.ensureHandoff(deps); return fn(req); };
+  router.get('/founding/work', api.requireBuilder, handle(arrived(async () => ({ stages: await work.readAll(deps) }))));
+  router.get('/founding/context', api.requireBuilder, handle(arrived(async () => handoff.withHandoff(await work.readContext(deps), await handoff.readHandoff(deps)))));
+  router.get('/founding/work/:stage', api.requireBuilder, handle(arrived((req) => work.readStage(stage(req), deps))));
   // The stage's document (task 1005115): its record read as one named page, editable
   // through the writes below at any time, without reopening the stage.
-  router.get('/founding/work/:stage/document', api.requireBuilder, handle((req) => work.readDocument(stage(req), deps)));
+  router.get('/founding/work/:stage/document', api.requireBuilder, handle(arrived((req) => work.readDocument(stage(req), deps))));
   router.get('/founding/work/:stage/assist', api.requireBuilder, handle(async (req) => {
     const prompt = work.assistPrompt(stage(req));
     return prompt ? { prompt } : { ok: false, reason: 'unknown_stage' };

package/modules/platform-identity/module.json

@@ -16,6 +16,6 @@
     "migrations": true,
     "pollers": ["code-sweep", "visibility-pull", "guild-totals"]
   },
-  "provides": ["platform-identity.hub", "project.publishGate", "project.catalog"],
+  "provides": ["platform-identity.hub", "project.publishGate", "project.catalog", "platform-identity.projectMembershipKind"],
   "consumes": ["ideas.capture"]
 }

package/modules/platform-identity/project-standing.js

@@ -0,0 +1,49 @@
+// modules/platform-identity/project-standing.js — "what is this person's standing on this
+// project?", for the WORDING of a refusal only (task 1004162, ADR 0407 §6).
+//
+// Published as the port `platform-identity.projectMembershipKind` so provisioning can tell a
+// stranger (who keeps the 404 that confirms nothing) from someone already connected to the
+// project (who is told what to do next), without importing this module (ADR 0083).
+//
+// IT NEVER ADMITS ANYONE, and must never be read to. A `member` row is written at every hub
+// sign-in, including the device flow any GitHub user can start (ADR 0328 amendment), so no
+// answer here is a grant. Admission is provisioning's own grant row (ADR 0407 §1-3).
+//
+// Answers, most specific first:
+//   'owner' | 'member' | 'visitor' — a membership the hub itself witnessed (signin_verified_at)
+//   'pending'                      — a live invitation from the project (inside its 30 days)
+//   'applied'                      — no row, but this person asked to join inside the
+//                                    application window and the project took the request
+//   null                           — none of these: a stranger
+'use strict';
+
+const api = require('../../src/module-api');
+const { isNumericGithubId } = require('./platform-identity');
+const { APPLICATION_ECHO_WINDOW_DAYS } = require('./application-echo');
+
+const KINDS = Object.freeze(['owner', 'member', 'visitor', 'pending', 'applied']);
+
+async function projectMembershipKind(clientId, githubId, { pool = api.pool } = {}) {
+  const client = String(clientId || '');
+  if (!client || !isNumericGithubId(githubId)) return null;
+  const { rows } = await pool.query(
+    `SELECT m.membership_kind
+       FROM platform_identity_project_memberships m
+      WHERE m.client_id = $1 AND m.github_id = $2::bigint
+        AND (   (m.membership_kind <> 'pending' AND m.signin_verified_at IS NOT NULL)
+             OR (m.membership_kind = 'pending' AND m.joined_at > now() - make_interval(days => $3::int)))
+      LIMIT 1`,
+    [client, String(githubId), api.inviteExpiry.INVITE_EXPIRY_DAYS],
+  );
+  if (rows[0] && KINDS.includes(rows[0].membership_kind)) return rows[0].membership_kind;
+  const { rows: asked } = await pool.query(
+    `SELECT 1 FROM platform_identity_application_echoes
+      WHERE github_id = $1::bigint AND client_id = $2
+        AND applied_at > now() - make_interval(days => $3::int)
+      LIMIT 1`,
+    [String(githubId), client, APPLICATION_ECHO_WINDOW_DAYS],
+  );
+  return asked.length ? 'applied' : null;
+}
+
+module.exports = { projectMembershipKind };

package/modules/platform-identity/routes/my-projects.js

@@ -27,6 +27,7 @@ const api = require('../../../src/module-api');
 const pi = require('../platform-identity');
 const projectStats = require('../project-stats');
 const applicationEcho = require('../application-echo');
+const projectStanding = require('../project-standing');
 const guilds = require('../guilds');
 const { isMintedPersonKey } = require('../account-logins');
 const guildEngagements = require('../guild-engagements');
@@ -159,6 +160,13 @@ async function applicationVouchHeaders(client, builder) {
 }
 
 module.exports = function myProjectsRoutes() {
+  // PROVIDES port `platform-identity.projectMembershipKind` (task 1004162, ADR 0407 §6): a
+  // person's standing on one project, so provisioning can word a REFUSAL — never admit.
+  if (!api.hasProvider('platform-identity.projectMembershipKind')) {
+    api.registerProvider('platform-identity.projectMembershipKind', {
+      projectMembershipKind: (clientId, githubId) => projectStanding.projectMembershipKind(clientId, githubId, { pool: api.pool }),
+    });
+  }
   const router = express.Router();
 
   // rank: any-builder — the caller's OWN cross-project memberships (own data).

package/modules/provisioning/grants.js

@@ -0,0 +1,126 @@
+// modules/provisioning/grants.js — the owner-made grant to help run a hosted project, and its
+// ONLY writer (task 1004161, ADR 0407).
+//
+// Why it exists: a sign-in on the hub writes a `member` membership row for any GitHub user,
+// the device flow included, so membership can never admit anyone to a project's hosting
+// (ADR 0328 amendment). A grant is the one thing that can: a row in
+// `provisioning_project_grants` (migration provisioning_039) that only the project's OWNER
+// creates, from their own hub session. Nothing a visitor sends, nothing a project reports at
+// check-in, and no sign-in reaches this file.
+//
+// Every INSERT and UPDATE of that table lives here; tests/provisioning_project_grants.mjs
+// fails if another file writes it. Who may call which function is decided by the routes
+// (routes/grants.js); this file holds the data rules that must hold whoever calls.
+'use strict';
+
+const GRANT_LEVELS = Object.freeze(['operate']);
+const MAX_LIVE_GRANTS = 25;
+
+const GRANT_COLUMNS = `g.id, g.instance_id, g.grantee_builder_id, g.level, g.granted_by_builder_id,
+  g.granted_at, g.revoked_at, g.revoked_by_builder_id`;
+
+// The live grant one person holds on one project, or null. Read on every request a
+// grant-admitting route serves (ADR 0016: authority is read fresh, never cached), so a revoke
+// binds on the grantee's very next request.
+async function liveGrant(db, instanceId, builderId) {
+  const { rows } = await db.query(
+    `SELECT ${GRANT_COLUMNS} FROM provisioning_project_grants g
+      WHERE g.instance_id = $1 AND g.grantee_builder_id = $2 AND g.revoked_at IS NULL
+      LIMIT 1`,
+    [instanceId, builderId],
+  );
+  return rows[0] || null;
+}
+
+// The project's live grants, with who each one names — the owner's "People with access" list.
+async function listLiveGrants(db, instanceId) {
+  const { rows } = await db.query(
+    `SELECT ${GRANT_COLUMNS}, b.github_login, b.display_name, b.avatar_url
+       FROM provisioning_project_grants g
+       JOIN builders b ON b.id = g.grantee_builder_id
+      WHERE g.instance_id = $1 AND g.revoked_at IS NULL
+      ORDER BY g.granted_at, g.id`,
+    [instanceId],
+  );
+  return rows;
+}
+
+// The ACTIVE hub builder a GitHub login names, or null. The owner names a person by login;
+// the grant stores the builder id, so a later login rename cannot move the grant to someone else.
+async function findGranteeByLogin(db, login) {
+  const { rows } = await db.query(
+    `SELECT id, github_login, display_name, avatar_url FROM builders
+      WHERE lower(github_login) = lower($1) AND status IS DISTINCT FROM 'inactive'
+      LIMIT 1`,
+    [login],
+  );
+  return rows[0] || null;
+}
+
+// Make a grant. Returns { grant } on success or { refused: code } — never throws for a rule.
+// Rules held here: a known level only; never the project's own owner; at most MAX_LIVE_GRANTS
+// live grants per project; one live grant per person (an existing one is returned as is).
+// The count and the insert run under the project row's lock, so two requests cannot both
+// take the 25th place.
+async function grantProjectAccess(db, { instanceId, granteeBuilderId, level = 'operate', grantedByBuilderId }) {
+  if (!GRANT_LEVELS.includes(level)) return { refused: 'bad_level' };
+  const client = typeof db.connect === 'function' ? await db.connect() : db;
+  const owned = client !== db;
+  try {
+    await client.query('BEGIN');
+    const { rows: inst } = await client.query(
+      'SELECT id, owner_builder_id FROM provisioning_instances WHERE id = $1 FOR UPDATE', [instanceId]);
+    if (!inst[0]) { await client.query('ROLLBACK'); return { refused: 'instance_not_found' }; }
+    if (String(inst[0].owner_builder_id) === String(granteeBuilderId)) {
+      await client.query('ROLLBACK');
+      return { refused: 'grantee_is_owner' };
+    }
+    const existing = await liveGrant(client, instanceId, granteeBuilderId);
+    if (existing) { await client.query('ROLLBACK'); return { grant: existing, created: false }; }
+    const { rows: n } = await client.query(
+      `SELECT count(*)::int AS n FROM provisioning_project_grants
+        WHERE instance_id = $1 AND revoked_at IS NULL`, [instanceId]);
+    if (n[0].n >= MAX_LIVE_GRANTS) { await client.query('ROLLBACK'); return { refused: 'grant_limit' }; }
+    const { rows } = await client.query(
+      `INSERT INTO provisioning_project_grants (instance_id, grantee_builder_id, level, granted_by_builder_id)
+       VALUES ($1, $2, $3, $4)
+       RETURNING id, instance_id, grantee_builder_id, level, granted_by_builder_id, granted_at, revoked_at, revoked_by_builder_id`,
+      [instanceId, granteeBuilderId, level, grantedByBuilderId],
+    );
+    await client.query('COMMIT');
+    return { grant: rows[0], created: true };
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    if (owned) client.release();
+  }
+}
+
+// Revoke one live grant of this project. Returns the revoked row, or null when there is no
+// such live grant (already revoked, another project's id, or none). A stamp, never a delete.
+async function revokeProjectAccess(db, { instanceId, grantId, revokedByBuilderId }) {
+  const { rows } = await db.query(
+    `UPDATE provisioning_project_grants
+        SET revoked_at = now(), revoked_by_builder_id = $3
+      WHERE id = $1 AND instance_id = $2 AND revoked_at IS NULL
+      RETURNING id, instance_id, grantee_builder_id, level, granted_by_builder_id, granted_at, revoked_at, revoked_by_builder_id`,
+    [grantId, instanceId, revokedByBuilderId],
+  );
+  return rows[0] || null;
+}
+
+// One grant of this project by id, live or not — the revoke route reads it to decide who may
+// revoke (the grantee may revoke their own).
+async function getGrant(db, instanceId, grantId) {
+  const { rows } = await db.query(
+    `SELECT ${GRANT_COLUMNS} FROM provisioning_project_grants g WHERE g.id = $1 AND g.instance_id = $2`,
+    [grantId, instanceId],
+  );
+  return rows[0] || null;
+}
+
+module.exports = {
+  GRANT_LEVELS, MAX_LIVE_GRANTS,
+  liveGrant, listLiveGrants, findGranteeByLogin, grantProjectAccess, revokeProjectAccess, getGrant,
+};

package/modules/provisioning/guide-handoff.js

@@ -0,0 +1,65 @@
+'use strict';
+
+// modules/provisioning/guide-handoff.js — THE GUIDE'S ANSWERS RIDE INTO THE NEW PROJECT
+// (task 1005274, goal 1000106). A founder who talked with the start-a-project guide
+// (modules/front-door-guide) should never be asked the same thing twice. The creation
+// page pre-fills itself from the plan; this file carries the rest across to the new
+// project, whose database this process cannot reach — the birth marker's path exactly
+// (birth.js, modules/onboarding/founding-birth.js):
+//
+//   1. The create request says `from_guide: true` (the page sends it only when it
+//      pre-filled from a plan). The route asks the guide, through the
+//      `front-door-guide.handoff` port, for the CALLER's own newest attached plan — never a
+//      plan named by the request, so nobody can carry someone else's words in.
+//   2. stampGuideHandoff writes the reserved write-once settings key `guide_handoff`
+//      ({ scope, markdown }) on the row this request JUST made.
+//   3. The companion GUIDE_HANDOFF carries it into the instance's web.env as one
+//      base64url line; src/branding.js maps it onto the server-only founding.guideHandoff,
+//      and modules/onboarding/guide-handoff.js writes it once: the scope answers as
+//      carried over (never over the founder's own) and the hand-off file.
+//
+// No guide, no flag, no port (an instance without the guide) or no plan: nothing is
+// stamped and the companion goes out empty, so a visitor who never used the guide sees
+// exactly what they saw before.
+
+const KEY = 'guide_handoff';
+const MAX_BYTES = 24000;   // the stored JSON; handoff.js already bounds the markdown
+
+const storedOf = (row) => (row && row.settings && typeof row.settings === 'object' && !Array.isArray(row.settings) ? row.settings : {});
+
+// cleanHandoff(h) — PURE. The port's answer reduced to exactly { scope, markdown }, or null.
+function cleanHandoff(h) {
+  if (!h || typeof h !== 'object' || typeof h.markdown !== 'string' || !h.markdown.trim()) return null;
+  const scope = {};
+  if (h.scope && typeof h.scope === 'object') {
+    for (const [k, v] of Object.entries(h.scope)) if (/^[a-z_]{1,40}$/.test(k) && typeof v === 'string' && v.trim()) scope[k] = v;
+  }
+  const out = { scope, markdown: h.markdown };
+  return Buffer.byteLength(JSON.stringify(out)) <= MAX_BYTES ? out : null;
+}
+
+// guideHandoffEnv(row) — PURE. The companion line's value: base64url JSON, or '' for none.
+function guideHandoffEnv(row) {
+  const h = cleanHandoff(storedOf(row)[KEY]);
+  return h ? Buffer.from(JSON.stringify(h), 'utf8').toString('base64url') : '';
+}
+
+// stampGuideHandoff(db, instanceId, builderId, { name, resolve }) — the create route's
+// call, on the row it just made. Returns true when a hand-off was stamped. Write-once.
+async function stampGuideHandoff(db, instanceId, builderId, { name = '', resolve } = {}) {
+  const port = (resolve || require('../../src/module-api').resolveOptional)('front-door-guide.handoff');
+  if (typeof port !== 'function') return false;
+  const h = cleanHandoff(await port(builderId, { name }));
+  if (!h) return false;
+  await db.query(
+    `UPDATE provisioning_instances
+        SET settings = COALESCE(settings, '{}'::jsonb) || jsonb_build_object($2::text, $3::jsonb)
+      WHERE id = $1 AND NOT (COALESCE(settings, '{}'::jsonb) ? $2::text)`,
+    [instanceId, KEY, JSON.stringify(h)],
+  );
+  return true;
+}
+
+const GUIDE_COMPANION_ENV = Object.freeze({ GUIDE_HANDOFF: guideHandoffEnv });
+
+module.exports = { KEY, GUIDE_COMPANION_ENV, stampGuideHandoff };

package/modules/provisioning/migrations/provisioning_038_render_promote.sql

@@ -0,0 +1,43 @@
+-- provisioning_038_render_promote.sql — a person promotes what ran on the sandbox to the
+-- live app, and every promotion is recorded (task 1005290, ADR 0406 §2).
+--
+-- WHY. Once a project has a sandbox, finished work lands on the sandbox only: the live
+-- Render service stops deploying on every merge, and moves only when a person presses
+-- promote. That press queues a `render-promote` intent carrying the owner's borrowed key
+-- (ADR 0327 §2), and the runner records the promotion BEFORE it asks Render to deploy, so
+-- nothing reaches the live app through Bongos without a row here saying who, which change,
+-- and what came of it.
+--
+-- Additive and namespaced (ADR 0083): one new action on the intent CHECK, one new table.
+-- Idempotent — safe to re-run.
+
+BEGIN;
+
+ALTER TABLE provisioning_intents DROP CONSTRAINT IF EXISTS provisioning_intents_action_check;
+ALTER TABLE provisioning_intents ADD CONSTRAINT provisioning_intents_action_check
+  CHECK (action IN ('provision', 'teardown', 'oauth-manifest', 'domain-attach',
+                    'settings-apply', 'restart', 'disconnect', 'core-upgrade',
+                    'core-upgrade-preflight', 'repo-private', 'render-standup',
+                    'render-promote'));
+
+CREATE TABLE IF NOT EXISTS provisioning_promotions (
+  id                bigserial PRIMARY KEY,
+  instance_id       bigint NOT NULL REFERENCES provisioning_instances(id) ON DELETE CASCADE,
+  commit_id         text NOT NULL,
+  commit_message    text,
+  from_commit_id    text,
+  sandbox_deploy_id text,
+  render_deploy_id  text,
+  requested_by      text,
+  state             text NOT NULL DEFAULT 'started' CHECK (state IN ('started', 'sent', 'failed')),
+  error             text,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  updated_at        timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS ix_provisioning_promotions_instance ON provisioning_promotions (instance_id, created_at DESC);
+
+COMMENT ON TABLE provisioning_promotions IS
+  'Every promotion of a sandbox change to a project''s live Render app (task 1005290, ADR 0406): who asked, which commit, from which, and what Render answered. Written by the runner before it deploys.';
+
+COMMIT;

package/modules/provisioning/migrations/provisioning_039_project_grants.sql

@@ -0,0 +1,40 @@
+-- provisioning_039_project_grants.sql — an owner-made grant to help run a hosted project
+-- (task 1004161, ADR 0407). Landed as provisioning_038 beside render_promote's 038; renumbered
+-- by task 1004162 so the series has one migration per number. Every statement is IF NOT EXISTS,
+-- so a database that already ran it under the old name runs it again harmlessly.
+--
+-- WHY. A hosted project's provisioning routes admitted only its owner (or an archon).
+-- ADR 0328 Phase 2 would have admitted a `member` row of platform_identity_project_memberships,
+-- but the hub writes that row at every sign-in — the device flow any GitHub user can start
+-- included — so it is not a grant (ADR 0328 amendment, ADR 0407). This table is the grant:
+-- made on purpose by the project's owner from their own hub session, stored apart from every
+-- sign-in and check-in path, with one writer (modules/provisioning/grants.js).
+--
+-- A revoke is a stamp, never a delete, so the record survives. One LIVE grant per person per
+-- project (the partial unique index); granting again after a revoke makes a new row. Deleting
+-- the project row (disconnect) takes its grants with it.
+--
+-- `level` is a closed list. 'operate' is the only level (ADR 0407 §3); a second one is an ADR
+-- amendment and a new migration, never a free string.
+--
+-- Additive and namespaced (ADR 0083): no down-migration, idempotent — safe to re-run.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS provisioning_project_grants (
+  id                     bigserial PRIMARY KEY,
+  instance_id            bigint NOT NULL REFERENCES provisioning_instances(id) ON DELETE CASCADE,
+  grantee_builder_id     bigint NOT NULL REFERENCES builders(id) ON DELETE CASCADE,
+  level                  text   NOT NULL CHECK (level IN ('operate')),
+  granted_by_builder_id  bigint NOT NULL REFERENCES builders(id),
+  granted_at             timestamptz NOT NULL DEFAULT now(),
+  revoked_at             timestamptz,
+  revoked_by_builder_id  bigint REFERENCES builders(id),
+  CHECK ((revoked_at IS NULL) = (revoked_by_builder_id IS NULL))
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS ux_provisioning_project_grants_live
+  ON provisioning_project_grants (instance_id, grantee_builder_id)
+  WHERE revoked_at IS NULL;
+
+COMMIT;