@bongos/core 1.25.21 → 1.25.23

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

@@ -12,7 +12,8 @@
 // The index has three CLIENT-SIDE layers (task 2178 scope):
 //   1. Pages — read live from the sidebar shell.js rendered, so rank + module
 //      gating come for free and can never drift from the nav. A hidden nav item
-//      is a hidden destination. (Cosmetic only; the server still gates each page.)
+//      is a hidden destination, and so is a room asleep while the project is
+//      founding. (Cosmetic only; the server still gates each page.)
 //   2. Sections — the sub-destinations of the four pages that have them. These
 //      cannot be read from another page's DOM, so they are declared below and
 //      held to the real ids by tests/hall_palette.mjs.
@@ -145,9 +146,15 @@
   var searchCache = {};   // query (trimmed+lowercased) -> raw hits[], this OPEN only
 
   function esc(s) { return window.OTB.escapeHtml(s); }
+  // A nav item the sidebar does not show is not a destination: hidden by its gate, or
+  // asleep while the project is founding (task 1005285). The sleeping mark is the
+  // shell's, stamped from the server's /me.founding_mode.asleep, never decided here,
+  // and the server refuses the page as well (src/bongos/founding-page-gate.js).
+  function offered(el) {
+    return !!(el && !el.hidden && !(el.classList && el.classList.contains('nav-item--asleep')));
+  }
   function visible(id) {
-    var el = document.getElementById(id);
-    return !!(el && !el.hidden);
+    return offered(document.getElementById(id));
   }
 
   // Pages, straight from the rendered sidebar. Skips the external API-docs link's
@@ -160,7 +167,7 @@
   function pageEntries() {
     var out = [];
     document.querySelectorAll('#app-sidebar .nav-item').forEach(function (a) {
-      if (a.hidden) return;
+      if (!offered(a)) return;
       var label = (a.querySelector('.nav-item__label') || {}).textContent || '';
       if (!label) return;
       out.push({

package/modules/hall-ui/records/founding-mode.md

@@ -29,3 +29,9 @@ work-founding.states.json renders an ordinary hall page with a founding /me (kit
 - The genesis home, the stage tasks and the "what's this?" destination belong to PS08 (task 1004423). The band links home until then.
 - The founding mark belongs to PS10 (task 1004424).
 - Starting founding on a new project and moving its stage is `setFoundingMode`, on the onboarding port, and PS08 drives it. Nothing in this task writes it.
+
+## The classic hall wears all three genesis behaviours (task 1005285)
+
+Since task 1005112 an asleep room is **hidden, not dimmed**, and its page is refused (`src/bongos/founding-page-gate.js` redirects home with `?asleep=<room>&opens=<stage>`, and the shell says which stage opens it); the "cosmetic, nothing enforced" line above is history. The owner asked (2026-11-13) that the classic hall get the same three genesis behaviours as the game. Two were already shared code: the stage checklist (done / open / locked, and what a locked task waits on, from `shapeGenesis`) and Copy prompt on each open task are the Home banner card `genesis-home.js`, which both views load. The gap was the **jump list**: `palette.js` skipped only a nav item with the `hidden` attribute, so Ctrl/Cmd-K still offered Tasks, Goals, Sky, Collab and Builders, and the Tasks tabs, while they slept. It now treats `.nav-item--asleep` (the shell's mark, stamped from `/me.founding_mode.asleep`) as not a destination, for pages and for their sections; it never works out which rooms sleep itself. `tests/hall_palette.mjs` holds it against the real `shapeFoundingMode`.
+
+**To walk it:** `node scripts/hall-preview/server.js --fixture-me --founding scope` (the `hall-preview-founding` launch entry). `/me.founding_mode` is the real `shapeFoundingMode`, `GET /founding/genesis` the real `shapeGenesis` over `scripts/hall-preview/fixtures/founding__genesis__tasks.json`, and a sleeping room's page answers through the real `foundingPageGate`.

package/modules/lifecycle/kickoff-checklist.js

@@ -159,7 +159,7 @@ const GENESIS_STEPS = Object.freeze({
   ],
   legalize: [
     { title: 'Decide how contributors are rewarded and who can be paid',
-      description: 'Genesis stage 4 (legalize). Whether builders earn credits, money or nothing, and the limits that apply (age, country, the entity behind the project). When it is done, the Economy wakes.' },
+      description: 'Genesis stage 4 (legalize). Whether builders earn credits, money or nothing, and the limits that apply (age, country, the entity behind the project). Run `npx bongos genesis options` first: it lists every reward option with what the server enforces and the facts about this project beside it (`npx bongos genesis facts` shows and changes those facts). Explain those rules to the founder; never write a rule of your own into a document. If a rule seems missing, say so and leave the line to the founder. When it is done, the Economy wakes.' },
   ],
   legislation: [
     { title: 'Set the voting rules: who votes and how many must agree',

package/modules/lifecycle/routes/pay-type-gates.js

@@ -24,9 +24,14 @@ module.exports = function buildPayTypeGatesRouter() {
   // The `lifecycle.payTypeGates` port (task 1004910): core's module-sale payouts ask it
   // whether module_share is cleared (licence, takedown contact, payee onboarding) before
   // a rule, a sale or a share moves. hasProvider-guarded so a rebuilt router never
-  // registers it twice.
+  // registers it twice. Genesis's legalize stage (task 1005129) reads every gate through
+  // it too, met/missing only, so the founder sees what a pay type needs as they choose.
   if (!api.hasProvider('lifecycle.payTypeGates')) {
-    api.registerProvider('lifecycle.payTypeGates', { refuseUnclearedGates: gates.refuseUnclearedGates });
+    api.registerProvider('lifecycle.payTypeGates', {
+      refuseUnclearedGates: gates.refuseUnclearedGates,
+      readGates: async () => (await gates.readGates()).map(gates.withoutEvidence),
+      labels: require('../pay-terms').PAY_TYPE_LABELS,
+    });
   }
 
   // rank: any-builder for met/missing (the same pay information `GET /pay-terms` shows, no person's

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/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/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)
@@ -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

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),
   };