@bongos/core 1.25.20 → 1.25.22

package/modules/provisioning/project-facts.js

@@ -0,0 +1,55 @@
+// modules/provisioning/project-facts.js — THE PROJECT'S OWN FACTS, CARRIED FROM THE HUB
+// INTO THE PROJECT (task 1005129, goal 1000106).
+//
+// WHY. The startup flow asks where the project is, where its builders are, whether minors
+// are on board, what entity stands behind it and how it means to reward people
+// (planet-physics.js). Until now none of it crossed to the project, so a genesis session
+// working the legalize stage had to derive the rules from scratch — and once wrote a
+// policy line into the bylaws that the founder never chose. The owner: "we should know
+// the implications of the options we lay out to the user … have that carry throughout
+// the rest of the project setup."
+//
+// WHAT CROSSES, and only that: the answers a genesis stage reads — FACT_KEYS — plus the
+// soft-limit RULES (soft-limits.js) that speak to rewards, as the declarative data they
+// already are. The project evaluates those rules against ITS OWN editable copy of the
+// facts (modules/onboarding/project-facts.js), so a fact changed later re-checks every
+// note at once instead of leaving an old resolution standing. Soft limits stay facts,
+// never policy: each carries `enforced: false`. The ENFORCED pay-type gates are not
+// carried — the project's own lifecycle module holds and enforces them.
+//
+// HOW. One companion env line (SETTINGS_COMPANION_ENV, provisioning.js): base64url JSON
+// { facts, rules }, or '' when the founder answered none of them (a project made before
+// the startup flow, or a skip) — the project then says "not answered" rather than
+// guessing. src/branding.js maps it onto the SERVER-ONLY founding.projectFacts.
+//
+// PURE — requires only soft-limits.js.
+
+'use strict';
+
+const { SOFT_LIMIT_RULES } = require('./soft-limits');
+
+// The answers that cross. Keep it to what a stage reads (the task's own rule): the
+// legalize stage reads all six; nothing else about the project leaves the hub.
+const FACT_KEYS = Object.freeze(['home_country', 'home_region', 'builder_geography', 'minors_on_board', 'entity', 'reward_intents']);
+
+// The soft-limit rules a reward choice is shaped by: every rule naming a reward option.
+const REWARD_RULES = Object.freeze(SOFT_LIMIT_RULES.filter((r) => r.options.some((o) => o.startsWith('reward_intents'))));
+
+// projectFacts(detail) — PURE. The answered FACT_KEYS of a normalized project detail
+// (provisioning.js projectDetail); an unanswered key is left out, never null-filled.
+function projectFacts(detail) {
+  const d = detail && typeof detail === 'object' ? detail : {};
+  const out = {};
+  for (const k of FACT_KEYS) if (d[k] !== undefined && d[k] !== null) out[k] = d[k];
+  return out;
+}
+
+// projectFactsEnv(detail) — PURE. The companion line's value, or '' when nothing was answered.
+function projectFactsEnv(detail) {
+  const facts = projectFacts(detail);
+  if (!Object.keys(facts).length) return '';
+  const rules = REWARD_RULES.map(({ id, when, options, effect, reason }) => ({ id, when, options, effect, reason }));
+  return Buffer.from(JSON.stringify({ facts, rules }), 'utf8').toString('base64url');
+}
+
+module.exports = { REWARD_RULES, projectFactsEnv };

package/modules/provisioning/project-refusal.js

@@ -0,0 +1,107 @@
+// modules/provisioning/project-refusal.js — what a person the project gate REFUSED is told
+// (task 1004162, ADR 0407 §6, replacing ADR 0328 decision 3).
+//
+// Called only after requireProjectOwner has already said no. It can never admit: it never
+// calls next() and never sets req.project. It only picks the wording of the refusal, so that
+// someone already connected to the project gets a next step instead of a dead end, while a
+// stranger still learns nothing.
+//
+//   no connection at all                         → 404 instance_not_found (as before)
+//   holds a grant, route not open to grantees    → 403 owner_only
+//   'visitor' (the project knows them)           → 403 project_membership_required + how to apply
+//   'pending' (the project invited them)         → 403 project_membership_required + accept it
+//   'applied' (asked to join inside 30 days)     → 403 project_membership_required + it's with the owner
+//   'member' / 'owner' row, PUBLIC project       → 403 project_access_required (ask the owner)
+//   'member' / 'owner' row, private or stealth   → 404 — a `member` row can be had by anyone who
+//                                                  runs the device flow (ADR 0328 amendment), so
+//                                                  it is no evidence they may learn a closed
+//                                                  project's id belongs to it.
+//
+// Any doubt — the standing port missing, throwing, or answering something unknown, or the
+// grant read failing — is the 404: on doubt, say less.
+'use strict';
+
+const api = require('../../src/module-api');
+const provisioning = require('./provisioning');
+const grants = require('./grants');
+
+const log = api.logger('provisioning');
+
+const STANDING_PORT = 'platform-identity.projectMembershipKind';
+const HOSTING_IS_SEPARATE = 'Managing its hosting is something the project’s owner gives separately.';
+
+function notFound(res) {
+  return res.fail('instance_not_found', 404);
+}
+
+function projectOrigin(inst) {
+  return inst.domain ? `https://${inst.domain}` : null;
+}
+
+// The project's join door, as its owner set it: only a PUBLIC project may confirm itself to a
+// person whose only link is a sign-in.
+function isPublicProject(inst) {
+  try {
+    return provisioning.effectiveSettings(inst).visibility === 'public';
+  } catch {
+    return false;
+  }
+}
+
+async function refuseProject(req, res, inst) {
+  let grant = null;
+  try {
+    grant = await grants.liveGrant(api.pool, inst.id, req.builder.id);
+  } catch (err) {
+    log.error(`[provisioning] ${req.method} ${req.path} — refusal grant read`, err);
+    return notFound(res);
+  }
+  if (grant) {
+    return res.fail('owner_only', { status: 403, message: 'Only the project’s owner can do this.' });
+  }
+
+  const port = api.resolveOptional(STANDING_PORT);
+  if (!port || typeof port.projectMembershipKind !== 'function') return notFound(res);
+  let kind;
+  try {
+    kind = await port.projectMembershipKind(inst.slug, req.builder.github_id);
+  } catch (err) {
+    log.error(`[provisioning] ${req.method} ${req.path} — standing read`, err);
+    return notFound(res);
+  }
+
+  const origin = projectOrigin(inst);
+  switch (kind) {
+    case 'visitor':
+      return res.fail('project_membership_required', {
+        status: 403,
+        message: `You’re not a member of this project yet. Ask to join it, and its owner decides. ${HOSTING_IS_SEPARATE}`,
+        details: { apply: origin
+          ? { state: 'can_apply', method: 'POST', path: '/api/bongos/my-projects/join', body: { origin } }
+          : { state: 'can_apply' } },
+      });
+    case 'pending':
+      return res.fail('project_membership_required', {
+        status: 403,
+        message: `This project has invited you. Sign in to it to accept. ${HOSTING_IS_SEPARATE}`,
+        details: { apply: { state: 'invited', sign_in: origin } },
+      });
+    case 'applied':
+      return res.fail('project_membership_required', {
+        status: 403,
+        message: `You’ve asked to join this project, and its owner decides. ${HOSTING_IS_SEPARATE}`,
+        details: { apply: { state: 'applied' } },
+      });
+    case 'member':
+    case 'owner':
+      if (!isPublicProject(inst)) return notFound(res);
+      return res.fail('project_access_required', {
+        status: 403,
+        message: 'Only the project’s owner, and people the owner has given access, can manage its hosting. Ask the owner to give you access.',
+      });
+    default:
+      return notFound(res);
+  }
+}
+
+module.exports = { refuseProject };

package/modules/provisioning/provisioning.js

@@ -25,7 +25,7 @@ const { normalizeModuleSelection, effectiveModules } = require('./starter-bundle
 const { PLANET_PHYSICS_QUESTIONS, canonicalAnswer } = require('./planet-physics');
 const { softLimitsFor } = require('./soft-limits'); const { demoView } = require('./demo'); const { isTestProject, TEST_COMPANION_ENV } = require('./test-project');   // the demo marker's owner view (task 1004420); the test mark (task 1005036)
 const { dnsResolves, recordDnsResolved, lookupAnswers } = require('./dns-resolves');   // has the platform's lookup seen the address answer (task 1004505)
-const { LOOK_SETTINGS_VOCAB, LOOK_DEFAULTS, LOOK_COMPANION_ENV } = require('./look'); const { BIRTH_COMPANION_ENV } = require('./birth'); const { GUIDE_COMPANION_ENV } = require('./guide-handoff'); // born into genesis (task 1004506); the guide's hand-off (task 1005274)
+const { LOOK_SETTINGS_VOCAB, LOOK_DEFAULTS, LOOK_COMPANION_ENV } = require('./look'); const { BIRTH_COMPANION_ENV } = require('./birth'); const { GUIDE_COMPANION_ENV } = require('./guide-handoff'); const { projectFactsEnv } = require('./project-facts'); // born into genesis (task 1004506); the guide's hand-off (task 1005274)
 
 // ---------------------------------------------------------------------------
 // Constants (mirror the CHECK constraints in provisioning_001_tables.sql)
@@ -66,7 +66,7 @@ const PROJECT_TYPES = ['game', 'research', 'business', 'non-profit', 'not-sure']
 // 'disconnect' (task 1003249, migration provisioning_016): the owner's true delete — ./disconnect.js.
 // 'core-upgrade' (task 1003159, ADR 0293): move this instance's core pin — the owner's
 // deploy door. The web tier only QUEUES it; the control-plane runner performs it.
-const INTENT_ACTIONS = ['provision', 'teardown', 'oauth-manifest', 'domain-attach', 'settings-apply', 'restart', 'disconnect', 'core-upgrade', 'core-upgrade-preflight', 'repo-private', 'render-standup'];
+const INTENT_ACTIONS = ['provision', 'teardown', 'oauth-manifest', 'domain-attach', 'settings-apply', 'restart', 'disconnect', 'core-upgrade', 'core-upgrade-preflight', 'repo-private', 'render-standup', 'render-promote'];
 // Every state a teardown can be asked for — i.e. everything except the one
 // state where there is provably nothing left to release. DERIVED from
 // INSTANCE_STATES on purpose (task 1003042, walk finding N5): the old hand-kept
@@ -514,6 +514,9 @@ function settingsEnvVars(row, prefix) {
 // project that has been strict since it stood up.
 const SETTINGS_COMPANION_ENV = Object.freeze({
   ARTIST_GATE_SINCE: (row) => artistGateStrictSince(row) || '', ...LOOK_COMPANION_ENV, ...BIRTH_COMPANION_ENV, ...TEST_COMPANION_ENV, ...GUIDE_COMPANION_ENV, // + accent, logo (look.js); birth, demo box (birth.js); test mark (test-project.js); the guide's hand-off (guide-handoff.js)
+  // The project's own facts — where it is, where its builders are, minors, entity, reward intent — and
+  // the reward soft-limit rules, so genesis can state an option's implications (task 1005129, project-facts.js).
+  PROJECT_FACTS: (row) => projectFactsEnv(projectDetail(row)),
 });
 
 // The web.env block the runner writes at STANDUP (task 1003139): a comment that
@@ -1192,7 +1195,7 @@ async function enqueueTeardown(db, instanceId, requestedBy) {
     `UPDATE provisioning_intents
         SET state = 'error', last_error = 'superseded: teardown requested', borrowed_key_enc = NULL,
             updated_at = now(), resolved_at = now()
-      WHERE instance_id = $1 AND action IN ('provision', 'settings-apply', 'restart', 'repo-private', 'render-standup') AND state = 'pending'
+      WHERE instance_id = $1 AND action IN ('provision', 'settings-apply', 'restart', 'repo-private', 'render-standup', 'render-promote') AND state = 'pending'
         AND NOT EXISTS (SELECT 1 FROM provisioning_instances WHERE id = $1 AND hosting_shape = 'control-plane') RETURNING id`,
     [instanceId]
   );

package/modules/provisioning/render-lookup.js

@@ -65,4 +65,39 @@ async function lookupRender(key, { ownerId = null, fetchImpl = globalThis.fetch
   return { workspaces, services };
 }
 
-module.exports = { lookupRender, RenderLookupError, RENDER_API };
+// WHAT IS WAITING TO GO LIVE (task 1005290, ADR 0406 §2; the ADR 0406 §11 amendment widens
+// ADR 0348 by exactly this): the owner's two recorded services — their live app and its
+// sandbox — and the deploys of each. GET only, the same key rules as above, every service
+// asserted to carry the workspace. Nothing here can promote; promoting is the runner's
+// (scripts/bongos/provision-render-promote.js), on a key lent with the press.
+const COMMIT_RE = /^[0-9a-f]{7,40}$/;
+const SERVED = ['live', 'deactivated'];
+function shapeDeploy(d) {
+  const c = (d && d.commit) || {};
+  return {
+    deploy_id: d.id,
+    commit_id: COMMIT_RE.test(String(c.id || '')) ? c.id : null,
+    short: String(c.id || '').slice(0, 7),
+    message: String(c.message || '').split('\n')[0].slice(0, 200),
+    at: (c.createdAt || d.createdAt) || null,
+    status: d.status || null,
+  };
+}
+async function lookupPromotion(key, { ownerId, liveServiceId, sandboxServiceId, fetchImpl = globalThis.fetch }) {
+  for (const id of [liveServiceId, sandboxServiceId]) {
+    const s = await get(`/services/${encodeURIComponent(id)}`, key, fetchImpl);
+    if (!s || s.ownerId !== ownerId) throw new RenderLookupError('render_owner_mismatch', 'Render answered from another workspace, so nothing was shown.');
+  }
+  const deploys = async (id, n) => unwrap(await get(`/services/${encodeURIComponent(id)}/deploys?limit=${n}`, key, fetchImpl), 'deploy').map(shapeDeploy);
+  const live = await deploys(liveServiceId, 10);
+  const sandbox = await deploys(sandboxServiceId, 30);
+  const liveNow = live.find((d) => d.status === 'live') || null;
+  // Waiting = what served on the sandbox since the change live runs, newest first. If live's
+  // change is not in the sandbox's list (older than it reaches), everything listed waits.
+  const served = sandbox.filter((d) => SERVED.includes(d.status) && d.commit_id);
+  const at = liveNow ? served.findIndex((d) => d.commit_id === liveNow.commit_id) : -1;
+  const waiting = (at === -1 ? served : served.slice(0, at)).filter((d, i, all) => all.findIndex((x) => x.commit_id === d.commit_id) === i);
+  return { live: liveNow, waiting };
+}
+
+module.exports = { lookupRender, lookupPromotion, RenderLookupError, RENDER_API };

package/modules/provisioning/render-promote.js

@@ -0,0 +1,80 @@
+// modules/provisioning/render-promote.js — the web tier's half of PROMOTE: a person moves
+// what ran on the project's sandbox to its live app (task 1005290; ADR 0406 §2, ADR 0327).
+//
+// WHY. Finished work lands on the sandbox (it follows `main`); the live app moves only
+// when a person presses promote — the project law "Land only. Ask before going live". This
+// file queues that press (a `render-promote` intent holding the owner's encrypted key, and
+// the chosen change on the row, in ONE statement), reads back the record of promotions,
+// and shapes what the owner is told. It never calls Render: the read-only look at what is
+// waiting is render-lookup.js (ADR 0348 as widened by ADR 0406 §11), and the promotion
+// itself is the runner's (scripts/bongos/provision-render-promote.js).
+'use strict';
+
+const COMMIT_RE = /^[0-9a-f]{7,40}$/;
+
+// Why this project cannot promote right now, in the owner's words, or null.
+function noPromoteReason(inst) {
+  const h = (inst && inst.app_host) || {};
+  if (!inst || inst.status === 'torn_down' || inst.status === 'tearing_down') return 'This project has been removed.';
+  if (h.platform !== 'render' || !h.serviceId) return 'Your app is not set up on Render, so there is nothing to promote to.';
+  if (!h.sandbox || !h.sandbox.serviceId || ['removed', 'left', 'failed'].includes(h.sandbox.state)) return 'This project has no sandbox, so there is nothing to promote from. Add one first.';
+  return null;
+}
+
+// Queue a promotion. Returns { intent } or { conflict: 'open_intent', intent }.
+async function enqueuePromote(db, instanceId, { keyEnc, commitId, expectLiveCommit, requestedBy }) {
+  await require('./control-plane-guard').assertIntentAllowed(db, instanceId, 'render-promote');
+  const ask = { state: 'requested', commitId, expectLiveCommit: expectLiveCommit || null, requestedBy: requestedBy == null ? null : String(requestedBy), requestedAt: new Date().toISOString(), error: null };
+  try {
+    const { rows } = await db.query(
+      `WITH i AS (
+         INSERT INTO provisioning_intents (instance_id, action, requested_by, state, borrowed_key_enc)
+         VALUES ($1, 'render-promote', $2, 'pending', $3) RETURNING *
+       ), u AS (
+         UPDATE provisioning_instances SET app_host = app_host || jsonb_build_object('promote', $4::jsonb)
+          WHERE id = $1 RETURNING id
+       )
+       SELECT i.id, i.instance_id, i.action, i.state, i.created_at FROM i`,
+      [instanceId, 'api:self', keyEnc, JSON.stringify(ask)]);
+    return { intent: rows[0] };
+  } catch (e) {
+    if (e && e.code === '23505') {
+      const { rows } = await db.query(
+        `SELECT id, action, state FROM provisioning_intents
+          WHERE instance_id = $1 AND state IN ('pending', 'running') ORDER BY created_at DESC LIMIT 1`, [instanceId]);
+      return { conflict: 'open_intent', intent: rows[0] || { action: 'unknown', state: 'open' } };
+    }
+    throw e;
+  }
+}
+
+// The project's recent promotions, newest first: what went live, when, by whose press.
+async function listPromotions(db, instanceId, limit = 5) {
+  const { rows } = await db.query(
+    `SELECT commit_id, commit_message, from_commit_id, state, error, created_at
+       FROM provisioning_promotions WHERE instance_id = $1 ORDER BY created_at DESC LIMIT $2`, [instanceId, limit]);
+  return (rows || []).filter((r) => r && r.commit_id).map((r) => ({
+    commit: String(r.commit_id).slice(0, 7),
+    message: r.commit_message || null,
+    from: r.from_commit_id ? String(r.from_commit_id).slice(0, 7) : null,
+    state: r.state,
+    error: r.state === 'failed' ? (r.error || 'It did not go through.') : null,
+    at: r.created_at instanceof Date ? r.created_at.toISOString() : r.created_at,
+  }));
+}
+
+// What the owner is told about promoting: whether they can, whether the live app still
+// deploys every merge, and where the last press stands.
+function promoteView(inst) {
+  const h = (inst && inst.app_host) || {};
+  const why = noPromoteReason(inst);
+  const p = h.promote || null;
+  return {
+    can: !why,
+    reason: why,
+    live_follows_main: h.liveAutoDeploy !== 'off',
+    last: p ? { state: p.state, commit: p.commitId ? String(p.commitId).slice(0, 7) : null, error: p.state === 'failed' ? (p.error || null) : null } : null,
+  };
+}
+
+module.exports = { noPromoteReason, enqueuePromote, listPromotions, promoteView, COMMIT_RE };

package/modules/provisioning/render-sandbox.js

@@ -18,6 +18,7 @@ const { appStatus } = require('./app-status');
 // The sandbox's own database starts EMPTY: the platform cannot know an app's tables, so
 // the fake data is the app's own seed, run when it sees BONGOS_SANDBOX=1 (the starter's
 // half, task 1005291). Said to the owner plainly rather than promised.
+const SANDBOX_PAGE = '/__bongos/sandbox';
 const READY_DB_NOTE = 'It has its own database, separate from your live data. It starts empty: your app fills it with test data when it runs as a sandbox.';
 
 // Why a project cannot have a sandbox right now, in the owner's words, or null.
@@ -52,6 +53,11 @@ function sandboxStatus(inst, { now = Date.now() } = {}) {
     retry: undefined,
     plan: 'free',
     follows: 'main',
+    // The sandbox's own page (src/sandbox, task 1005291): what it refused, and what it cannot catch.
+    // The path is src/sandbox's PAGE; a module may not require core (ADR 0083), so it is
+    // spelled here once and pinned equal by tests/sandbox_gate.mjs. The key rides only this
+    // owner-only read.
+    safety_page: s.url ? s.url + SANDBOX_PAGE + (/^[0-9a-f]{48}$/.test(String(sb.pageKey || '')) ? `?key=${sb.pageKey}` : '') : null,
     database: { state: sb.database || 'none', note: sb.dbNote || (sb.database === 'ready' ? READY_DB_NOTE : null) },
     can_add: sb.state === 'failed' && !noSandboxReason(inst),
   };

package/modules/provisioning/route-helpers.js

@@ -1,34 +1,72 @@
-// modules/provisioning/route-helpers.js — the one owner-or-archon gate every own-scoped
+// modules/provisioning/route-helpers.js — the one gate every own-scoped
 // /provisioning/instances/:id route mounts (task 1004159, ADR 0328 decision 2). It replaced
 // three hand-written copies of the same rule, and the three routes that had only the owner
-// half of it (teardown, domain, github-app).
+// half of it (teardown, domain, github-app). Since task 1004161 (ADR 0407) a route may also
+// admit a person the project's OWNER granted access to, by opting in — never by default.
 'use strict';
 
 const api = require('../../src/module-api');
 const { failFrom } = require('./public-refusal');
+const grants = require('./grants');
+const { refuseProject } = require('./project-refusal');
 
 const log = api.logger('provisioning');
 
+// The grant levels a route may opt into. One today (ADR 0407 §3).
+const GRANTEE_LEVELS = Object.freeze(['operate']);
+
 function isProjectOwner(inst, builder) {
   return String(inst.owner_builder_id) === String(builder.id);
 }
 
-// The audit actor for a request the gate admitted: the owner acts as themselves, and an
-// archon on someone else's project is named, so the override never reads as the owner's act.
+// Which door admitted this request: 'owner' · 'grantee' · 'archon'. Set by the gate; for a
+// request the gate did not see, decided from the row the old way (owner, else archon).
+function projectDoor(req) {
+  if (req.projectDoor) return req.projectDoor;
+  return isProjectOwner(req.project, req.builder) ? 'owner' : 'archon';
+}
+
+// The audit actor for a request the gate admitted: the owner acts as themselves, and a grantee
+// or an archon is named, so neither ever reads as the owner's act (ADR 0407 §4).
 function projectActor(req) {
-  return isProjectOwner(req.project, req.builder) ? 'api:self' : `api:archon:${req.builder.id}`;
+  const door = projectDoor(req);
+  if (door === 'owner') return 'api:self';
+  return `api:${door}:${req.builder.id}`;
+}
+
+// The same, in words, for an event's detail line: "owner", "grantee <login>", "archon <login>".
+function projectActorLabel(req) {
+  const door = projectDoor(req);
+  return door === 'owner' ? 'owner' : `${door} ${req.builder.github_login || req.builder.id}`;
+}
+
+// What a grantee is shown of the project read (ADR 0407 §3): everything the owner sees except
+// the owner's own hosting bill and the GitHub App steps, which act on the owner's GitHub
+// account. The owner and an archon get the body unchanged.
+function grantedView(req, body) {
+  if (projectDoor(req) !== 'grantee') return body;
+  const { owner_monthly_usd, github_install, ...instance } = body.instance || {};
+  return { ...body, instance, github_app: null, github_setup: null };
 }
 
-// requireProjectOwner(loadFn, { archonOverride }) — mounted after requireBuilder, and spelled
-// in the route's own middleware list so route-rank-check.js can see it (ADR 0328 §4). Loads
-// the row with the caller's loader (`loadFn(id)`) and admits its owner or, by default, an
-// archon. That is a plain RANK test on purpose: `provisioning.fleet.manage` floors at metic
-// (ADR 0157), so gating on it would widen every route it guards.
+// requireProjectOwner(loadFn, { archonOverride, grantee }) — mounted after requireBuilder, and
+// spelled in the route's own middleware list so route-rank-check.js can see it (ADR 0328 §4).
+// Loads the row with the caller's loader (`loadFn(id)`) and admits, in this order:
+//   1. its owner;
+//   2. when the route opts in with `grantee: 'operate'`, a person holding a LIVE grant of that
+//      level on this project — read from provisioning_project_grants on every request, never a
+//      membership row (ADR 0407 §§1-3);
+//   3. by default, an archon — a plain RANK test on purpose: `provisioning.fleet.manage`
+//      floors at metic (ADR 0157), so gating on it would widen every route it guards.
 //
 // A missing row and someone else's row are the same 404, and the gate runs before the
 // handler's body validator, so a stranger cannot tell a real id from a malformed request.
-// The loaded row rides on `req.project`.
-function requireProjectOwner(loadFn, { archonOverride = true } = {}) {
+// A grant read that fails DENIES (the opaque 500), never falls through to admit.
+// The loaded row rides on `req.project`; the door that admitted it on `req.projectDoor`.
+function requireProjectOwner(loadFn, { archonOverride = true, grantee = null } = {}) {
+  if (grantee !== null && !GRANTEE_LEVELS.includes(grantee)) {
+    throw new Error(`requireProjectOwner: unknown grantee level ${grantee}`);
+  }
   return async function projectOwnerGate(req, res, next) {
     const id = api.parseId(req, res); // sends 400 bad_id + returns null on failure
     if (!id) return;
@@ -39,12 +77,28 @@ function requireProjectOwner(loadFn, { archonOverride = true } = {}) {
       log.error(`[provisioning] ${req.method} ${req.path} — project load`, err);
       return failFrom(res, err, 'instance_read_failed');
     }
-    const admitted = !!inst
-      && (isProjectOwner(inst, req.builder) || (archonOverride && req.builder.rank === 'archon'));
-    if (!admitted) return res.fail('instance_not_found', 404);
+    if (!inst) return res.fail('instance_not_found', 404);
+    let door = null;
+    if (isProjectOwner(inst, req.builder)) door = 'owner';
+    if (!door && grantee) {
+      let grant;
+      try {
+        grant = await grants.liveGrant(api.pool, inst.id, req.builder.id);
+      } catch (err) {
+        log.error(`[provisioning] ${req.method} ${req.path} — grant read`, err);
+        return failFrom(res, err, 'instance_read_failed');
+      }
+      if (grant && grant.level === grantee) door = 'grantee';
+    }
+    if (!door && archonOverride && req.builder.rank === 'archon') door = 'archon';
+    // Refused. The WORDING depends on who is asking (task 1004162, ADR 0407 §6): a stranger
+    // still gets the 404, someone already connected to the project gets a next step. That
+    // file can only refuse — it never calls next() and never sets req.project.
+    if (!door) return refuseProject(req, res, inst);
     req.project = inst;
+    req.projectDoor = door;
     return next();
   };
 }
 
-module.exports = { requireProjectOwner, projectActor, isProjectOwner };
+module.exports = { requireProjectOwner, projectActor, projectActorLabel, grantedView, isProjectOwner };

package/modules/provisioning/routes/env-manifest.js

@@ -25,10 +25,23 @@ const { pool, validateOrRespond } = api;
 const provisioning = require('../provisioning');
 const envManifest = require('../env-manifest');
 const { failFrom } = require('../public-refusal');
-const { requireProjectOwner } = require('../route-helpers');
+const { requireProjectOwner, projectActor, projectActorLabel } = require('../route-helpers');
 
 const log = api.logger('provisioning');
 const loadInstance = (id) => provisioning.getInstanceById(pool, id);
+// All four routes also admit a person the owner granted 'operate' access (task 1004161,
+// ADR 0407 §3): a variable NAME changes no running behaviour, and this list exists for the
+// builder sessions that help run the project to read and keep current.
+const GRANTEE = { grantee: 'operate' };
+
+// Every change to the list is an audit row naming who made it, so a grantee's change never
+// reads as the owner's (ADR 0407 §4). Best-effort: the change is already saved.
+function recordManifestChange(req, what) {
+  return provisioning.recordEvent(pool, {
+    instanceId: req.project.id, ownerBuilderId: req.project.owner_builder_id, event: 'env-manifest',
+    detail: `${what} by ${projectActorLabel(req)}`, actor: projectActor(req),
+  }).catch(() => {});
+}
 
 // The `:varId` path segment. parseId reads `:id`, which is the PROJECT here, so the
 // declaration's id is parsed separately. A non-numeric id is a 400 naming the field
@@ -91,7 +104,7 @@ module.exports = function buildEnvManifestRouter() {
 
   // GET — the declared surface. This is the route a BUILDER SESSION reads to learn which
   // variables a project has, which is the whole reason the manifest exists.
-  router.get('/provisioning/instances/:id/env-manifest', api.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
+  router.get('/provisioning/instances/:id/env-manifest', api.requireBuilder, requireProjectOwner(loadInstance, GRANTEE), async (req, res) => {
     try {
       const inst = req.project;
       const vars = await envManifest.listEnvVars(pool, inst.id);
@@ -113,7 +126,7 @@ module.exports = function buildEnvManifestRouter() {
 
   // POST — declare a variable, or re-declare one that exists (an edit, not a duplicate:
   // see ../env-manifest.js's declareEnvVar).
-  router.post('/provisioning/instances/:id/env-manifest', api.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
+  router.post('/provisioning/instances/:id/env-manifest', api.requireBuilder, requireProjectOwner(loadInstance, GRANTEE), async (req, res) => {
     if (refusesValue(req, res)) return;   // before the strict validator — see refusesValue
     if (validateOrRespond(req, res, {
       name: { required: true, type: 'string', maxLength: envManifest.ENV_NAME_MAX },
@@ -131,6 +144,7 @@ module.exports = function buildEnvManifestRouter() {
         environments: req.body.environments,
         required: req.body.required,
       });
+      await recordManifestChange(req, `${created ? 'declared' : 're-declared'} ${row.name}`);
       res.status(created ? 201 : 200).json({ ok: true, created, env_var: row, values_held: false });
     } catch (err) {
       log.error('[provisioning] POST /provisioning/instances/:id/env-manifest', err);
@@ -140,7 +154,7 @@ module.exports = function buildEnvManifestRouter() {
 
   // PATCH — edit one declaration. Merge-patch: an omitted field is left alone, so the
   // hall can fix a description without restating the environments.
-  router.patch('/provisioning/instances/:id/env-manifest/:varId', api.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
+  router.patch('/provisioning/instances/:id/env-manifest/:varId', api.requireBuilder, requireProjectOwner(loadInstance, GRANTEE), async (req, res) => {
     if (refusesValue(req, res)) return;   // before the strict validator — see refusesValue
     if (validateOrRespond(req, res, {
       name: { type: 'string', maxLength: envManifest.ENV_NAME_MAX },
@@ -157,6 +171,7 @@ module.exports = function buildEnvManifestRouter() {
       // Not that project's declaration → the same 404 a missing one gets, so a guessed id
       // never confirms what another project declares.
       if (!row) return res.fail('env_var_not_found', 404);
+      await recordManifestChange(req, `edited ${row.name}`);
       res.json({ ok: true, env_var: row, values_held: false });
     } catch (err) {
       log.error('[provisioning] PATCH /provisioning/instances/:id/env-manifest/:varId', err);
@@ -167,13 +182,14 @@ module.exports = function buildEnvManifestRouter() {
   // DELETE — remove one declaration. Nothing outside this table is affected: the value,
   // wherever it lives, is untouched, and the response says so rather than letting an
   // owner believe removing the name removed the secret.
-  router.delete('/provisioning/instances/:id/env-manifest/:varId', api.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
+  router.delete('/provisioning/instances/:id/env-manifest/:varId', api.requireBuilder, requireProjectOwner(loadInstance, GRANTEE), async (req, res) => {
     try {
       const inst = req.project;
       const varId = parseVarId(req, res);
       if (!varId) return;
       const removed = await envManifest.removeEnvVar(pool, inst.id, varId);
       if (!removed) return res.fail('env_var_not_found', 404);
+      await recordManifestChange(req, `removed declaration ${varId}`);
       res.json({ ok: true, removed: true,
         message: 'Declaration removed. The variable\'s value, wherever you keep it, is untouched — this platform never had it.' });
     } catch (err) {