@bongos/core 1.25.20 → 1.25.22

package/modules/onboarding/project-facts.js

@@ -0,0 +1,318 @@
+'use strict';
+
+// modules/onboarding/project-facts.js — WHAT THE PROJECT KNOWS ABOUT ITSELF, AND WHAT EACH
+// REWARD OPTION REALLY MEANS FOR IT (task 1005129, goal 1000106).
+//
+// WHY. Working the legalize stage, a genesis session wrote a policy line into a project's
+// bylaws ("§3 limits paid work to the US for now") that the founder never chose: the
+// platform already knew the rules but never said them at the point of choice, and the
+// project never knew where it was. The owner: "we should know the implications of the
+// options we lay out to the user … and make them aware when they are selecting."
+//
+// TWO HALVES.
+//   1. THE FACTS. The startup flow's answers (where the project is, where its builders
+//      are, minors, entity, reward intent) arrive from the hub ONCE as founding.projectFacts
+//      (modules/provisioning/project-facts.js), together with the reward soft-limit rules as
+//      data. They land here as the project's OWN EDITABLE COPY (project_settings FACTS_KEY),
+//      not a frozen snapshot: a project that starts solo in one country and later has
+//      builders in three is normal. An answer never given reads "not answered" — so does
+//      every fact on a project not created through the hub — and nothing here guesses.
+//   2. THE OPTIONS AT THE POINT OF CHOICE. legalizeOptions states, for every pay type, what
+//      it REQUIRES and what is CLOSED, read from the two tables that already hold the rules
+//      and never written fresh by a session:
+//        enforced   the lifecycle module's pay-type gates (the server refuses a pay term
+//                   whose gate is open; eu_labour can never be cleared). Through the
+//                   `lifecycle.payTypeGates` port, met/missing only.
+//        facts      the hub's soft limits, evaluated against THIS project's current facts.
+//                   Advice with a reason, `enforced: false`: nobody refuses anything for them.
+//      The two are kept apart in the answer, never merged into one list, so advice is never
+//      shown as a wall and a wall never as advice. A BLOCKED OPTION IS SHOWN with its reason,
+//      not hidden — a founder with EU contributors must see that EU pay cannot be switched on.
+//      Changing a fact re-reads every option at once; setFacts says which options it changed.
+//
+// THE STANDING RULE this exists to make possible: an agent may EXPLAIN a rule; it must not
+// INVENT one. A session that finds itself deriving a policy line has found something the
+// platform failed to model — it says so, and leaves the line to the founder.
+//
+// THE BOUNDARY. Core through ../../src/module-api.js (project settings, branding, ports);
+// the lifecycle module through its port only. The soft-limit rules are carried as data from
+// the hub, so this file never reaches into the provisioning module either.
+
+const FACTS_KEY = 'project.facts';
+const FACT_KEYS = Object.freeze(['home_country', 'home_region', 'builder_geography', 'minors_on_board', 'entity', 'reward_intents']);
+const GEOGRAPHY = Object.freeze(['us-only', 'us-eu', 'global', 'not-sure']);
+const REWARD_INTENTS = Object.freeze(['non-monetary', 'cash', 'equity', 'future-payouts']);
+const FACT_LABELS = Object.freeze({
+  home_country: 'Where the project is based',
+  home_region: 'Its state or province',
+  builder_geography: 'Where its builders are',
+  minors_on_board: 'Whether builders under 18 take part',
+  entity: 'What stands behind it (a company, a group, a person)',
+  reward_intents: 'How it means to reward people',
+});
+
+// Which startup reward intent speaks to which pay type, so a soft limit on the intent is
+// shown beside the pay type it is about. A pay type with no intent carries no soft limits.
+const INTENT_FOR_PAY_TYPE = Object.freeze({
+  cash: 'cash', equity: 'equity', non_monetary: 'non-monetary', credit_pool: 'future-payouts',
+});
+const EXTRA_LABELS = Object.freeze({ eu_labour: 'Paying builders in the EU' });
+
+const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
+
+// ── pure: one fact checked ───────────────────────────────────────────────────
+
+// checkFact(key, value, facts) → { ok, value } or { ok:false, reason }. null un-answers.
+function checkFact(key, value, facts = {}) {
+  if (!FACT_KEYS.includes(key)) return { ok: false, reason: 'unknown_fact', key };
+  if (value === null) return { ok: true, value: null };
+  const bad = { ok: false, reason: 'bad_fact', key };
+  switch (key) {
+    case 'home_country': return typeof value === 'string' && /^[A-Z]{2}$/.test(value) ? { ok: true, value } : bad;
+    case 'home_region': {
+      if (typeof value !== 'string' || !/^[A-Z]{2}-[A-Z0-9]{1,3}$/.test(value)) return bad;
+      const country = facts.home_country;
+      return country && !value.startsWith(`${country}-`) ? { ok: false, reason: 'region_not_in_country', key } : { ok: true, value };
+    }
+    case 'builder_geography': return GEOGRAPHY.includes(value) ? { ok: true, value } : bad;
+    case 'minors_on_board': return typeof value === 'boolean' ? { ok: true, value } : bad;
+    case 'entity': return typeof value === 'string' && /^[a-z][a-z0-9-]{1,39}$/.test(value) ? { ok: true, value } : bad;
+    case 'reward_intents': {
+      if (!Array.isArray(value) || !value.every((v) => REWARD_INTENTS.includes(v))) return bad;
+      return { ok: true, value: REWARD_INTENTS.filter((v) => value.includes(v)) };
+    }
+    default: return bad;
+  }
+}
+
+// ── pure: the soft-limit rules, evaluated here ───────────────────────────────
+
+// The hub's rule shape (modules/provisioning/soft-limits.js): an absent answer never
+// matches, not even `lacks` — "never said" is not "said no".
+function conditionHolds(facts, key, test) {
+  if (!Object.prototype.hasOwnProperty.call(facts, key) || facts[key] == null) return false;
+  const v = facts[key];
+  if (test && Array.isArray(test.in)) return test.in.includes(v);
+  if (test && 'has' in test) return Array.isArray(v) && v.includes(test.has);
+  if (test && 'lacks' in test) return Array.isArray(v) && !v.includes(test.lacks);
+  return false;
+}
+
+function factNotesFor(intent, facts, rules) {
+  if (!intent) return [];
+  const out = [];
+  for (const r of rules || []) {
+    if (!isObj(r) || !Array.isArray(r.options) || !isObj(r.when)) continue;
+    if (!r.options.includes(`reward_intents:${intent}`) && !r.options.includes('reward_intents')) continue;
+    if (!Object.entries(r.when).every(([k, t]) => conditionHolds(facts, k, t))) continue;
+    out.push({ effect: String(r.effect), reason: String(r.reason), rule: String(r.id), enforced: false });
+  }
+  return out;
+}
+
+// legalizeOptions({ facts, rules, gates, labels }) — PURE. Every reward option the legalize
+// stage offers, with what it requires (enforced) and what the project's facts say about it
+// (not enforced), in two separate lists. `gates` null means this project runs no pay-rules
+// module: then nothing is enforced here, and the answer says so rather than inventing rules.
+function legalizeOptions({ facts = {}, rules = [], gates = null, labels = {} } = {}) {
+  const names = { ...EXTRA_LABELS, ...labels };
+  const types = gates ? gates.map((g) => g.pay_type) : Object.keys(INTENT_FOR_PAY_TYPE);
+  const options = types.map((payType) => {
+    const g = gates ? gates.find((x) => x.pay_type === payType) : null;
+    let enforced = null;
+    let status = 'no_rules_module';
+    if (g && g.never) {
+      enforced = { never: true, cleared: false, requires: [], missing: [],
+        reason: 'The server refuses this pay type, and it cannot be switched on yet.' };
+      status = 'closed';
+    } else if (g) {
+      const requires = (g.requirements || []).map((r) => ({ requirement: r.requirement, label: r.label, met: !!r.met }));
+      enforced = { never: false, cleared: !!g.cleared, requires, missing: requires.filter((r) => !r.met).map((r) => r.label),
+        reason: g.cleared ? 'Every requirement is on file; the server allows it.' : 'The server refuses it until every requirement below is on file.' };
+      status = g.cleared ? 'open' : 'needs_setup';
+    }
+    const notes = factNotesFor(INTENT_FOR_PAY_TYPE[payType], facts, rules);
+    return {
+      pay_type: payType,
+      label: names[payType] || payType,
+      status,
+      enforced,
+      // Facts, not policy (soft-limits.js): advice with its reason, refused by nobody.
+      facts: notes,
+      advised_against: notes.some((n) => n.effect === 'grey' || n.effect === 'hide'),
+    };
+  });
+  return options;
+}
+
+// What changed for the options when the facts changed: the founder is told, so an old
+// decision is never left standing silently on a fact that moved.
+function optionChanges(before, after) {
+  const key = (o) => JSON.stringify([o.status, o.facts.map((n) => n.rule)]);
+  const was = new Map(before.map((o) => [o.pay_type, o]));
+  return after.filter((o) => !was.has(o.pay_type) || key(was.get(o.pay_type)) !== key(o)).map((o) => {
+    const prev = was.get(o.pay_type);
+    const had = new Set(prev ? prev.facts.map((n) => n.rule) : []);
+    const has = new Set(o.facts.map((n) => n.rule));
+    return {
+      pay_type: o.pay_type, label: o.label,
+      new_notes: o.facts.filter((n) => !had.has(n.rule)).map((n) => n.reason),
+      gone_notes: prev ? prev.facts.filter((n) => !has.has(n.rule)).map((n) => n.reason) : [],
+    };
+  });
+}
+
+// ── the hub's marker and the stored copy ─────────────────────────────────────
+
+// factsMarker(founding) — PURE. founding.projectFacts → { facts, rules } or null.
+function factsMarker(founding) {
+  const raw = isObj(founding) ? founding.projectFacts : null;
+  if (typeof raw !== 'string' || !raw.trim()) return null;
+  try {
+    const m = JSON.parse(Buffer.from(raw.trim(), 'base64url').toString('utf8'));
+    if (!isObj(m) || !isObj(m.facts)) return null;
+    const facts = {};
+    for (const k of FACT_KEYS) {
+      const c = checkFact(k, m.facts[k], m.facts);
+      if (m.facts[k] != null && c.ok) facts[k] = c.value;
+    }
+    return { facts, rules: Array.isArray(m.rules) ? m.rules : [] };
+  } catch (_) {
+    return null;
+  }
+}
+
+function readStored(raw) {
+  if (!raw) return null;
+  try {
+    const s = JSON.parse(raw);
+    if (!isObj(s) || !isObj(s.facts)) return null;
+    return { facts: s.facts, origin: isObj(s.origin) ? s.origin : {}, rules: Array.isArray(s.rules) ? s.rules : [], updated_at: s.updated_at || null };
+  } catch (_) {
+    return null;
+  }
+}
+
+function depsOf(deps = {}) {
+  const api = () => require('../../src/module-api');
+  return {
+    get: deps.getSetting || ((k) => api().projectSettings.get(k)),
+    set: deps.setSetting || ((k, v, by) => api().projectSettings.set(k, v, by)),
+    marker: Object.prototype.hasOwnProperty.call(deps, 'factsMarker') ? deps.factsMarker
+      : (() => { try { return factsMarker(api().branding().founding); } catch (_) { return null; } })(),
+    gates: deps.payGates !== undefined ? deps.payGates : (() => { try { return api().resolveOptional('lifecycle.payTypeGates'); } catch (_) { return null; } })(),
+    now: deps.now || (() => new Date()),
+  };
+}
+
+// The stored copy, seeded ONCE from the hub's marker. The project's copy wins from then on:
+// a later edit here is never overwritten by what was said at creation.
+async function loadStored(d) {
+  const row = await d.get(FACTS_KEY);
+  const stored = readStored(row && row.value);
+  if (stored) return stored;
+  if (!d.marker) return { facts: {}, origin: {}, rules: [], updated_at: null };
+  const seeded = {
+    facts: d.marker.facts,
+    origin: Object.fromEntries(Object.keys(d.marker.facts).map((k) => [k, 'carried_over'])),
+    rules: d.marker.rules,
+    updated_at: d.now().toISOString(),
+  };
+  await d.set(FACTS_KEY, JSON.stringify(seeded), null);
+  return seeded;
+}
+
+// shapeFacts(stored) — PURE. Every fact, answered or not, in one constant shape.
+function shapeFacts(stored) {
+  const facts = FACT_KEYS.map((key) => {
+    const has = stored.facts[key] != null;
+    return {
+      key, label: FACT_LABELS[key],
+      value: has ? stored.facts[key] : null,
+      answered: has,
+      // carried_over until the founder confirms or edits it here; founder after.
+      origin: has ? (stored.origin[key] || 'founder') : null,
+    };
+  });
+  return { facts, unanswered: facts.filter((f) => !f.answered).map((f) => f.key), updated_at: stored.updated_at };
+}
+
+async function gatesOf(d) {
+  if (!d.gates || typeof d.gates.readGates !== 'function') return { gates: null, labels: {} };
+  return { gates: await d.gates.readGates(), labels: d.gates.labels || {} };
+}
+
+// readFacts(deps) → { facts, unanswered, updated_at }
+async function readFacts(deps = {}) {
+  return shapeFacts(await loadStored(depsOf(deps)));
+}
+
+// readOptions(deps) → the legalize stage's options, with the facts they were read against.
+async function readOptions(deps = {}) {
+  const d = depsOf(deps);
+  const stored = await loadStored(d);
+  const { gates, labels } = await gatesOf(d);
+  return {
+    ...shapeFacts(stored),
+    rules_module: !!gates,
+    options: legalizeOptions({ facts: stored.facts, rules: stored.rules, gates, labels }),
+    // The two kinds of statement, named for whoever shows them.
+    explain: {
+      enforced: 'Enforced: the server refuses this until the requirement is on file.',
+      facts: 'A fact about your project, not a rule: nobody refuses anything for it.',
+    },
+  };
+}
+
+// setFacts(patch, by, deps) — the founder edits the project's own copy. Each key in the
+// patch is set (or un-answered with null); the rest stay. Answers the new facts and every
+// option whose notes changed, so nothing decided on the old facts is left silently.
+async function setFacts(patch, by, deps = {}) {
+  if (!isObj(patch)) return { ok: false, reason: 'bad_fact' };
+  const d = depsOf(deps);
+  const stored = await loadStored(d);
+  const next = { ...stored.facts };
+  const origin = { ...stored.origin };
+  for (const key of Object.keys(patch)) {
+    const c = checkFact(key, patch[key], { ...next, ...patch });
+    if (!c.ok) return c;
+    if (c.value === null) { delete next[key]; delete origin[key]; } else { next[key] = c.value; origin[key] = 'founder'; }
+  }
+  if (next.home_region && next.home_country && !next.home_region.startsWith(`${next.home_country}-`)) {
+    return { ok: false, reason: 'region_not_in_country', key: 'home_region' };
+  }
+  const { gates, labels } = await gatesOf(d);
+  const before = legalizeOptions({ facts: stored.facts, rules: stored.rules, gates, labels });
+  const after = legalizeOptions({ facts: next, rules: stored.rules, gates, labels });
+  const saved = { facts: next, origin, rules: stored.rules, updated_at: d.now().toISOString() };
+  await d.set(FACTS_KEY, JSON.stringify(saved), by == null ? null : by);
+  return { ok: true, ...shapeFacts(saved), options: after, changed: optionChanges(before, after) };
+}
+
+// optionsMarkdown(read) — PURE. The options as plain text, for an AI session working the
+// legalize stage with the founder (the CLI's `genesis options`). It explains; it decides nothing.
+function optionsMarkdown(r) {
+  const lines = ['# Reward options for this project', '',
+    'Read from the platform\'s own rules. Explain these; never add a rule of your own. If something here looks missing, say so to the founder instead of writing a policy line.', ''];
+  const said = r.facts.filter((f) => f.answered);
+  lines.push('## What the project has said about itself', '');
+  for (const f of said) lines.push(`- ${f.label}: ${Array.isArray(f.value) ? f.value.join(', ') : String(f.value)}${f.origin === 'carried_over' ? ' (from project creation, not yet confirmed)' : ''}`);
+  for (const k of r.unanswered) lines.push(`- ${FACT_LABELS[k]}: not answered`);
+  lines.push('');
+  if (!r.rules_module) lines.push('This project runs no pay-rules module, so nothing below is enforced by the server.', '');
+  for (const o of r.options) {
+    lines.push(`## ${o.label}`);
+    if (o.enforced && o.enforced.never) lines.push(`- Closed (enforced): ${o.enforced.reason}`);
+    else if (o.enforced) {
+      lines.push(`- ${o.enforced.cleared ? 'Allowed (enforced)' : 'Not yet allowed (enforced)'}: ${o.enforced.reason}`);
+      for (const q of o.enforced.requires) lines.push(`  - ${q.met ? '[on file]' : '[missing]'} ${q.label}`);
+    }
+    for (const n of o.facts) lines.push(`- Fact, not a rule: ${n.reason}`);
+    lines.push('');
+  }
+  return lines.join('\n').trimEnd() + '\n';
+}
+
+module.exports = {
+  FACTS_KEY, factsMarker, readFacts, readOptions, setFacts, optionsMarkdown,
+};

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

@@ -12,10 +12,12 @@
 
 const api = require('../../../src/module-api');
 const work = require('../genesis-work');
+const facts = require('../project-facts');
 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,
+  unknown_fact: 400, bad_fact: 400, region_not_in_country: 400,
   empty_answer: 400, not_a_choice: 400, answer_too_long: 400, page_too_long: 400, link_too_long: 400, bad_link: 400,
 };
 
@@ -89,4 +91,18 @@ module.exports = function mountGenesisWorkRoutes(router, deps = {}) {
   // Un-answer: back to empty, which is not the same as skipped.
   router.delete('/founding/work/:stage/answers/:question', api.requireBuilder, owns,
     handle((req) => work.clearAnswer(stage(req), q(req), req.builder.id, deps)));
+
+  // The project's own facts and the legalize stage's options (task 1005129, ../project-facts.js):
+  // any builder reads them; the facts are the owner's to change, like every genesis write.
+  router.get('/founding/facts', api.requireBuilder, handle(() => facts.readFacts(deps)));
+  router.put('/founding/facts', api.requireBuilder, owns,
+    (req, res, next) => {
+      if (api.validateOrRespond(req, res, { facts: { type: 'object', required: true } })) return;
+      next();
+    },
+    handle((req) => facts.setFacts(req.body.facts, req.builder.id, deps)));
+  router.get('/founding/legalize/options', api.requireBuilder, handle(async () => {
+    const r = await facts.readOptions(deps);
+    return { ...r, markdown: facts.optionsMarkdown(r) };
+  }));
 };

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/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;

package/modules/provisioning/module.json

@@ -24,7 +24,8 @@
       "render-standup",
       "look",
       "demo",
-      "github-setup"
+      "github-setup",
+      "grants"
     ],
     "migrations": true,
     "pollers": [