@bongos/core 1.19.543 → 1.19.545

package/scripts/gds/box.js

@@ -177,6 +177,25 @@ async function resolveBuilder(pool, ref) {
 // A short, DNS-safe-ish suffix from the current time (CLI context — Date is fine).
 // ---- provision -------------------------------------------------------------
 
+// Pure: renders the /etc/otb/box.env content cloud-init bakes onto a box (task
+// 1002466). Split out of cmdProvision so GDS_BASE — and the named-tunnel block
+// baked in beside it — can be unit-tested without DB/DO/Cloudflare.
+//
+// GDS_BASE is the FULL api base (origin + /api/gds), matching what
+// infra/box-report-*.sh already derive from the session file when the env var is
+// absent (`"$GDS_BASE/box/host-keys"` with no further path inserted) — every box
+// used to get this only as a fallback derived on-box; baking it explicitly closes
+// the one on-box script (box-source-fetch.sh, out-of-repo) that skips that
+// derivation entirely and hardcodes a different instance's origin instead.
+function buildBoxEnv({ apiOrigin, namedTunnel }) {
+  let env = `# /etc/otb/box.env — baked by box.js provision\nGDS_BASE=${String(apiOrigin).replace(/\/+$/, '')}/api/gds\n`;
+  if (namedTunnel) {
+    const { token, hostname, credential, previewHostname } = namedTunnel;
+    env += `# named tunnel (#771/#774, ADR 0038)\nBOX_TUNNEL_TOKEN=${token}\nBOX_TERMINAL_HOSTNAME=${hostname}\nBOX_TERMINAL_CREDENTIAL=${credential}\nBOX_PREVIEW_HOSTNAME=${previewHostname}\n`;
+  }
+  return env;
+}
+
 async function cmdProvision(pool, boxes, boxOnboard, ref, { apply }) {
   const builder = await resolveBuilder(pool, ref);
   if (!builder) return fail(`no builder matches "${ref}"`);
@@ -272,7 +291,13 @@ async function cmdProvision(pool, boxes, boxOnboard, ref, { apply }) {
   // (setTerminalAccess): the builder reads them from the hall, with no token placed
   // on the box and no box-side reporter (the quick-tunnel fallback that caused the
   // #771/#774 chicken-and-egg). ADR 0016 holds — no credential funneled into a box.
-  let boxEnv = '';
+  // GDS_BASE (task 1002466 — see buildBoxEnv above for the shape/why): a box was
+  // never actually bare here EXCEPT the one on-box script that skips the
+  // session-file fallback (box-source-fetch.sh, out-of-repo on the control-plane
+  // — see the cross-repo blocker filed alongside this fix). Baking it explicitly
+  // closes that gap for every future box regardless of which script forgets it.
+  const apiOrigin = process.env.GDS_PUBLIC_ORIGIN || instanceConfig.defaultApiBase();
+  let boxEnv = buildBoxEnv({ apiOrigin });
   let terminalHostname = null;
   let terminalCredential = null;
   if (namedTunnelEnabled()) {
@@ -286,7 +311,10 @@ async function cmdProvision(pool, boxes, boxOnboard, ref, { apply }) {
       // + DNS for the live game preview. Bake its hostname so the box's
       // box-preview command can show the builder their URL (no DB row needed — the
       // host is deterministic; box-game-preview.service serves :3000 behind it).
-      boxEnv = `# /etc/otb/box.env — baked by box.js provision (#771/#774, ADR 0038 named tunnel)\nBOX_TUNNEL_TOKEN=${token}\nBOX_TERMINAL_HOSTNAME=${th}\nBOX_TERMINAL_CREDENTIAL=${terminalCredential}\nBOX_PREVIEW_HOSTNAME=${ph}\n`;
+      boxEnv = buildBoxEnv({
+        apiOrigin,
+        namedTunnel: { token, hostname: th, credential: terminalCredential, previewHostname: ph },
+      });
       console.log(`  ✓ named tunnel ready — ${th}`);
       console.log(`  ✓ live game preview — https://${ph} (ADR 0044)`);
       // The rule PUT is the ONLY thing that proves edit scope. Report its real
@@ -330,6 +358,12 @@ async function cmdProvision(pool, boxes, boxOnboard, ref, { apply }) {
     builder: { id: builder.id, github_login: builder.github_login, rank: builder.rank },
     // The instance's OWN public origin (task 1002428) — a hardcoded founder host
     // here would point every newly provisioned box at the wrong instance.
+    //
+    // defaultApiBase(), deliberately NOT resolveApiBase() (task 1002466): a box
+    // belongs to the SERVER it was provisioned on, not to whichever instance this
+    // operator's own CLI session happens to be signed into right now — the two can
+    // differ (an operator provisioning boxes across instances) and the box must
+    // still call home to itself, not to the operator's other login.
     api_base: process.env.GDS_PUBLIC_ORIGIN || instanceConfig.defaultApiBase(),
   }, null, 2);
 
@@ -1265,4 +1299,4 @@ async function main() {
 
 if (require.main === module) main();
 
-module.exports = { cmdProvision, deprovisionOne, parkOne, cmdSweepIdle, cmdSweepDormant, deleteWithRetry, cmdReconcileDrift, runDnsHook, runDnsHookBlackhole, markErrorUnlessDestroyed, resolveBoxInfraDir, boxInfraCandidates, readCloudInit, BOX_INFRA_TEMPLATE };
+module.exports = { cmdProvision, deprovisionOne, parkOne, cmdSweepIdle, cmdSweepDormant, deleteWithRetry, cmdReconcileDrift, runDnsHook, runDnsHookBlackhole, markErrorUnlessDestroyed, resolveBoxInfraDir, boxInfraCandidates, readCloudInit, buildBoxEnv, BOX_INFRA_TEMPLATE };

package/scripts/gds/spike-task-map.js

@@ -139,24 +139,160 @@ function buildSynthetic({ nodes, goals, density, seed = 1003282 }) {
   return tasks;
 }
 
+// depIdsOf — the dependency ids on one row of a real dump, whatever the API called
+// them. This is load-bearing and was WRONG until task 1003477: `GET /tasks?include=deps`
+// answers with `blocked_by` (an array of {id,title,status,goal_id,satisfied} — see
+// db.attachTaskDepSummaries), and this loader only ever looked for `dependencies`/`deps`.
+// A real dump therefore parsed as a corpus with ZERO edges, and every --from number
+// would have described an empty graph while looking perfectly plausible — the exact
+// failure a spike must not have, because nothing about the output says "no edges here
+// because the field was misnamed". All three spellings are accepted now, and each may
+// hold bare ids or objects carrying one.
+function depIdsOf(row) {
+  // First NON-EMPTY array wins, not the first field present: a dump carrying both an
+  // empty `blocked_by` and a populated `dependencies` would otherwise read as edgeless,
+  // which is the same silent zero this function was written to stop.
+  const raw = [row.blocked_by, row.dependencies, row.deps]
+    .find((v) => Array.isArray(v) && v.length > 0) || [];
+  return raw
+    .map((d) => Number(d && typeof d === 'object' ? d.id : d))
+    .filter(Number.isFinite);
+}
+
 // loadReal — the same shape from a real `GET /tasks?include=deps` dump, so the next
 // session with DB access can replace every synthetic number in the verdict with a
 // measured one by re-running with --from.
+//
+// GOALS: a task with no goal does NOT share a bucket with the other ungoaled tasks —
+// "no goal" is not a goal they have in common, and pooling them would silently turn
+// every dependency between two ungoaled tasks into a WITHIN-goal edge, understating
+// the one number this loader exists to produce. Each gets its own bucket instead;
+// `goalId: null` marks them so census() can report them apart from real goals.
 function loadReal(file) {
   const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
   const rows = Array.isArray(raw) ? raw : (raw.tasks || raw.rows || []);
   const goalIndex = new Map();
+  let nextBucket = 0;
   return rows.map((r) => {
-    const g = r.goal_id == null ? '__none__' : String(r.goal_id);
-    if (!goalIndex.has(g)) goalIndex.set(g, goalIndex.size);
+    const gid = r.goal_id == null || r.goal_id === '' ? null : String(r.goal_id);
+    let bucket;
+    if (gid === null) {
+      bucket = nextBucket++;                      // ungoaled: a bucket of one
+    } else {
+      if (!goalIndex.has(gid)) goalIndex.set(gid, nextBucket++);
+      bucket = goalIndex.get(gid);
+    }
     return {
       id: Number(r.id),
-      goal: goalIndex.get(g),
-      deps: (r.dependencies || r.deps || []).map(Number).filter(Number.isFinite),
+      goal: bucket,
+      goalId: gid,
+      deps: depIdsOf(r),
     };
   });
 }
 
+// census — THE TWO NUMBERS task 1003477 exists to measure, plus the three that decide
+// what they mean. ADR 0227 deferred items 3 (the goal graph) and 4 (the dependency
+// forest) on a SYNTHETIC density sweep and said the live corpus must settle them.
+//
+//   with_dependency_pct — the share of tasks carrying at least one dependency row.
+//                         Item 4's question: is there a forest, or is the corpus
+//                         confetti? Note this is OUT-degree (what a task waits on),
+//                         not the degree-0 count the table's `isol%` reports — a task
+//                         that only BLOCKS others declares no row of its own but is
+//                         still drawn, so the two numbers differ and mean different
+//                         things.
+//   cross_goal_pct      — the share of dependency edges whose two ends sit in
+//                         different goals. Item 3's question: does the goal graph
+//                         have EDGES, or is it forty disconnected dots?
+//
+// And what turns those into a verdict: how many goals are left with no cross-goal edge
+// at all (isolated dots a node-link layout has nothing to say about), how many separate
+// components the forest breaks into, and how big the typical one is — a forest of 128
+// four-node trees is a drill-down, not a map, however many edges it contains.
+function census(tasks) {
+  const byId = new Map(tasks.map((t) => [t.id, t]));
+  const edges = [];
+  let withDep = 0;
+  for (const t of tasks) {
+    const live = t.deps.filter((d) => byId.has(d));
+    if (t.deps.length > 0) withDep += 1;
+    for (const d of live) edges.push([t.id, d]);
+  }
+
+  let crossGoal = 0;
+  let touchingUngoaled = 0;
+  const goalPairs = new Set();
+  const goalsWithEdge = new Set();
+  for (const [a, b] of edges) {
+    const ga = byId.get(a).goalId;
+    const gb = byId.get(b).goalId;
+    if (ga === null || gb === null) { touchingUngoaled += 1; continue; }
+    if (ga === gb) continue;
+    crossGoal += 1;
+    goalPairs.add(`${ga}>${gb}`);
+    goalsWithEdge.add(ga);
+    goalsWithEdge.add(gb);
+  }
+
+  const realGoals = new Set(tasks.map((t) => t.goalId).filter((g) => g !== null));
+  const ungoaled = tasks.filter((t) => t.goalId === null).length;
+
+  // The forest: only the tasks with an edge in either direction, and how it breaks up.
+  const degree = new Map(tasks.map((t) => [t.id, 0]));
+  for (const [a, b] of edges) {
+    degree.set(a, degree.get(a) + 1);
+    degree.set(b, degree.get(b) + 1);
+  }
+  const connected = tasks.filter((t) => degree.get(t.id) > 0).map((t) => t.id);
+  const comp = components(connected, edges);
+  const sizes = componentSizes(connected, edges);
+  const median = sizes.length ? sizes[Math.floor(sizes.length / 2)] : 0;
+
+  // THE DRILL-DOWN, which is the shape item 4 is actually scoped as ("queried when a
+  // goal is opened") — not the whole-corpus forest. Per goal: the tasks with an edge
+  // whose OTHER end sits in the same goal. Its WORST case is the number that decides
+  // the item, because a drill-down has to survive its biggest goal, not its median one.
+  const perGoal = new Map();
+  for (const [a, b] of edges) {
+    const ga = byId.get(a).goalId;
+    if (ga === null || ga !== byId.get(b).goalId) continue;
+    if (!perGoal.has(ga)) perGoal.set(ga, new Set());
+    perGoal.get(ga).add(a);
+    perGoal.get(ga).add(b);
+  }
+  const perGoalSizes = [...perGoal.values()].map((v) => v.size).sort((x, y) => y - x);
+  const perGoalMax = perGoalSizes[0] || 0;
+  const perGoalMedian = perGoalSizes.length ? perGoalSizes[Math.floor(perGoalSizes.length / 2)] : 0;
+
+  const pct = (n, d) => (d ? Number(((n / d) * 100).toFixed(2)) : 0);
+  return {
+    tasks: tasks.length,
+    edges: edges.length,
+    with_dependency: withDep,
+    with_dependency_pct: pct(withDep, tasks.length),
+    connected: connected.length,
+    connected_pct: pct(connected.length, tasks.length),
+    cross_goal: crossGoal,
+    cross_goal_pct: pct(crossGoal, edges.length),
+    edges_touching_ungoaled: touchingUngoaled,
+    goals: realGoals.size,
+    ungoaled_tasks: ungoaled,
+    goal_pairs: goalPairs.size,
+    goals_with_cross_goal_edge: goalsWithEdge.size,
+    goals_isolated: realGoals.size - goalsWithEdge.size,
+    goals_isolated_pct: pct(realGoals.size - goalsWithEdge.size, realGoals.size),
+    forest_components: comp.count,
+    forest_largest: comp.largest,
+    forest_median_component: median,
+    per_goal_forests: perGoalSizes.length,
+    per_goal_largest: perGoalMax,
+    per_goal_median: perGoalMedian,
+    // The drill-down clears the bar only if its BIGGEST goal still fits labels.
+    per_goal_largest_labels: inkBudget(perGoalMax || 1).fits_with_label,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // graph views — the literal ask, and the two shapes it could become
 // ---------------------------------------------------------------------------
@@ -223,7 +359,11 @@ function viewsOf(tasks) {
 
 // weakly-connected components, ignoring edge direction — a reader does not perceive
 // arrow direction when deciding "are these two blobs the same thing".
-function components(nodes, edges) {
+// componentSizes — the same union-find, returning the raw sizes largest-first. Split
+// out because "how many components" and "how big is the typical one" are different
+// questions: 128 components says a view is fragmented, but only the MEDIAN size says
+// whether each fragment is a readable little tree or a hairball of its own (census()).
+function componentSizes(nodes, edges) {
   const idx = new Map(nodes.map((n, i) => [n, i]));
   const parent = nodes.map((_, i) => i);
   const find = (x) => { while (parent[x] !== x) { parent[x] = parent[parent[x]]; x = parent[x]; } return x; };
@@ -238,7 +378,11 @@ function components(nodes, edges) {
     const r = find(i);
     sizes.set(r, (sizes.get(r) || 0) + 1);
   }
-  const all = [...sizes.values()].sort((a, b) => b - a);
+  return [...sizes.values()].sort((a, b) => b - a);
+}
+
+function components(nodes, edges) {
+  const all = componentSizes(nodes, edges);
   return { count: all.length, largest: all[0] || 0, singletons: all.filter((s) => s === 1).length };
 }
 
@@ -658,11 +802,34 @@ function measure(label, view, { render: doRender, file, radius = 3 } = {}) {
   };
 }
 
+// printCensus — the two gating numbers first and in words, because a reader who
+// stops after the first screen must still leave with the answer ADR 0227 asked for.
+function printCensus(c) {
+  const cg = c.goals_with_cross_goal_edge;
+  console.log('live corpus census — the numbers ADR 0227 items 3 and 4 wait on');
+  console.log(`  corpus                     ${c.tasks} tasks, ${c.goals} goals`
+    + (c.ungoaled_tasks ? `, ${c.ungoaled_tasks} task(s) with no goal` : ''));
+  console.log(`  Q1 tasks with a dependency ${c.with_dependency} (${c.with_dependency_pct}%)  → item 4, the dependency forest`);
+  console.log(`  Q2 cross-goal edges        ${c.cross_goal} of ${c.edges} (${c.cross_goal_pct}%)  → item 3, the goal graph`);
+  if (c.edges_touching_ungoaled) {
+    console.log(`     (${c.edges_touching_ungoaled} edge(s) touch a task with no goal and are counted as neither)`);
+  }
+  console.log(`  goal graph shape           ${c.goal_pairs} distinct goal pairs; ${cg} goal(s) carry an edge, `
+    + `${c.goals_isolated} isolated (${c.goals_isolated_pct}%)`);
+  console.log(`  forest shape               ${c.connected} tasks with any edge (${c.connected_pct}%) in `
+    + `${c.forest_components} components; largest ${c.forest_largest}, median ${c.forest_median_component}`);
+  console.log(`  per-goal drill-down        ${c.per_goal_forests} goal(s) have one; largest ${c.per_goal_largest}, `
+    + `median ${c.per_goal_median} — worst case ${c.per_goal_largest_labels ? 'still carries labels' : 'CANNOT carry labels'}`);
+  console.log('');
+}
+
 function main() {
   const results = [];
+  let realCensus = null;
 
   if (FROM) {
     const tasks = loadReal(path.resolve(REPO_ROOT, FROM));
+    realCensus = census(tasks);
     const v = viewsOf(tasks);
     results.push(measure('real', v.A, { render: RENDER, file: path.join(OUT_DIR, 'real-a-every-task.png') }));
     results.push(measure('real', v.B, { render: RENDER, file: path.join(OUT_DIR, 'real-b-dependency-forest.png') }));
@@ -688,13 +855,14 @@ function main() {
   }
 
   if (AS_JSON) {
-    process.stdout.write(`${JSON.stringify({ canvas: [CANVAS_W, CANVAS_H], nodes: N_TASKS, goals: N_GOALS, results }, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify({ canvas: [CANVAS_W, CANVAS_H], nodes: N_TASKS, goals: N_GOALS, census: realCensus, results }, null, 2)}\n`);
     return;
   }
 
   const pad = (s, n) => String(s).padEnd(n);
   const rpad = (s, n) => String(s).padStart(n);
-  console.log(`task-network-map spike — ${N_TASKS} tasks over ${N_GOALS} goals, drawn at ${CANVAS_W}×${CANVAS_H}`);
+  if (realCensus) printCensus(realCensus);
+  console.log(`task-network-map spike — ${realCensus ? realCensus.tasks : N_TASKS} tasks over ${realCensus ? realCensus.goals : N_GOALS} goals, drawn at ${CANVAS_W}×${CANVAS_H}`);
   console.log(`ink floor: a legible dot needs ${MIN_DOT_PITCH}px of pitch; a label needs ${MIN_LABEL_W}×${MIN_LABEL_H}px `
     + `(${inkBudget(1).labels_that_fit} labels fit on this canvas, total)`);
   console.log('');
@@ -725,6 +893,7 @@ if (require.main === module) main();
 // alpha-blend bug would quietly corrupt the evidence rather than fail loudly.
 // Exported = coverable; see tests/spike_task_map.mjs.
 module.exports = {
-  buildSynthetic, viewsOf, components, layout, crossingCount, inkBudget, mulberry32,
+  buildSynthetic, loadReal, depIdsOf, census, viewsOf, components, componentSizes,
+  layout, crossingCount, inkBudget, mulberry32,
   crc32, chunk, writePng, canvas, goalColor, render,
 };

package/src/bongos/serve-internal.js

@@ -1033,7 +1033,7 @@ function mountInternalSurfaces(app) {
   // any-builder and scoped to the caller by the SERVER (GET /help-requests/for-me
   // derives crafts from the viewer's own profile), so signed-in is the right floor.
   const SIGNEDIN_BUILDERS_PAGE_RE =
-    /^\/builders\/(?:work|pair|settings|atlas|modules|goals|roadmap|copy-desk|ideas|collab|primer(?:\.md)?|diagrams)(?:\.html)?\/?$/;
+    /^\/builders\/(?:work|pair|settings|atlas|modules|goals|roadmap|copy-desk|studio|ideas|collab|primer(?:\.md)?|diagrams)(?:\.html)?\/?$/;
   // The diagram image assets under /builders/diagrams/ ride the same tier as the
   // page that embeds them.
   const SIGNEDIN_BUILDERS_PREFIX_RE = /^\/builders\/diagrams\//;

package/src/module-api.js

@@ -49,7 +49,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.543'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.545'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/box_env.mjs

@@ -0,0 +1,64 @@
+// tests/box_env.mjs
+//
+// task 1002466 — a provisioned box's cloud-init baked NO GDS_BASE, so any on-box
+// script that (unlike infra/box-report-*.sh) doesn't fall back to deriving it from
+// the session file's api_base had nothing telling it which instance to talk to.
+// box.js now bakes GDS_BASE explicitly via the pure buildBoxEnv() helper, split
+// out of cmdProvision so this can be pinned without DB/DO/Cloudflare.
+//
+// Pure + hermetic: buildBoxEnv takes plain inputs and returns a string. No DB, no
+// network, no droplet.
+//
+// Run:  node tests/box_env.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const box = require('../scripts/gds/box.js');
+
+const { test, summary } = makeRunner();
+
+await test('bakes GDS_BASE as the FULL api base (origin + /api/gds) — matches box-report-*.sh, not box-heartbeat.sh\'s bare-origin BASE', () => {
+  const env = box.buildBoxEnv({ apiOrigin: 'https://cloudbongos.com' });
+  assert.match(env, /^GDS_BASE=https:\/\/cloudbongos\.com\/api\/gds$/m);
+});
+
+await test('strips a trailing slash off the origin before appending /api/gds', () => {
+  const env = box.buildBoxEnv({ apiOrigin: 'https://cloudbongos.com/' });
+  assert.match(env, /^GDS_BASE=https:\/\/cloudbongos\.com\/api\/gds$/m);
+  assert.ok(!env.includes('//api/gds'), 'must not double the slash');
+});
+
+await test('no named tunnel: box.env carries GDS_BASE and nothing else', () => {
+  const env = box.buildBoxEnv({ apiOrigin: 'https://cloudbongos.com' });
+  assert.ok(!/BOX_TUNNEL_TOKEN|BOX_TERMINAL_HOSTNAME|BOX_TERMINAL_CREDENTIAL|BOX_PREVIEW_HOSTNAME/.test(env));
+});
+
+await test('named tunnel: box.env carries GDS_BASE AND all four tunnel vars', () => {
+  const env = box.buildBoxEnv({
+    apiOrigin: 'https://cloudbongos.com',
+    namedTunnel: {
+      token: 'tok123', hostname: 'term-alice.example.com',
+      credential: 'cred456', previewHostname: 'sandbox-alice.example.com',
+    },
+  });
+  assert.match(env, /^GDS_BASE=https:\/\/cloudbongos\.com\/api\/gds$/m);
+  assert.match(env, /^BOX_TUNNEL_TOKEN=tok123$/m);
+  assert.match(env, /^BOX_TERMINAL_HOSTNAME=term-alice\.example\.com$/m);
+  assert.match(env, /^BOX_TERMINAL_CREDENTIAL=cred456$/m);
+  assert.match(env, /^BOX_PREVIEW_HOSTNAME=sandbox-alice\.example\.com$/m);
+});
+
+await test('every line is a clean KEY=VALUE (or a comment) — no leftover template gaps', () => {
+  const env = box.buildBoxEnv({
+    apiOrigin: 'https://cloudbongos.com',
+    namedTunnel: { token: 't', hostname: 'h', credential: 'c', previewHostname: 'p' },
+  });
+  for (const line of env.split('\n').filter(Boolean)) {
+    assert.ok(/^#/.test(line) || /^[A-Z_]+=\S+$/.test(line), `unexpected line shape: ${line}`);
+  }
+});
+
+summary();

package/tests/hall_nav.mjs

@@ -149,7 +149,12 @@ test('sidebar groups read by audience, in order', () => {
   // pages followed by the two CRAFT surfaces side by side: the ideator's queue and
   // the artist's. Same reasoning as copy-desk for why it is here rather than Docs
   // (a place you act, not reference material) or You (its subject is the project).
-  assert.deepEqual(nav[0].items.map((i) => i.id), ['home', 'roadmap', 'goals', 'work', 'ideas', 'copy-desk'],
+  // task 1003117 (R06 of goal 1000074): 'studio' — the Studio, artist mode —
+  // joins the same group AFTER copy-desk, so the two artist surfaces (the calm
+  // room and the flag table) sit side by side, both with the project's own work
+  // rather than in Docs (reference) or You (a person). Pinning the order keeps a
+  // new tab in the hall's most valuable nav real estate a reviewed decision.
+  assert.deepEqual(nav[0].items.map((i) => i.id), ['home', 'roadmap', 'goals', 'work', 'ideas', 'copy-desk', 'studio'],
     'the unlabeled group is the project itself (task 1002425 order)');
   assert.deepEqual(nav[1].items.map((i) => i.id), ['standing', 'profile'], 'You = your own numbers');
   // People (task 1002577): the /scouting directory graduated into the hall.

package/tests/hall_page_gate_map.mjs

@@ -52,6 +52,11 @@ const ORACLE = {
   // every rank by design, and collab's reads (task 1003172) are scoped to the
   // caller by the server — so for all three, sign-in IS the whole gate.
   '/builders/copy-desk': 'requireBuilderPage',
+  // task 1003117 (R06 of goal 1000074): the Studio (artist mode) — open to every
+  // rank like copy-desk (an artist is a craft, not a rank), so sign-in is the
+  // whole gate, and its two reads (GET /tasks, GET /copy-desk/queue) already gate
+  // themselves server-side.
+  '/builders/studio': 'requireBuilderPage',
   '/builders/ideas': 'requireBuilderPage',
   '/builders/collab': 'requireBuilderPage',
   // task 1002710: the orientation reading rooms moved DOWN to this tier from

package/tests/hall_studio_world.mjs

@@ -0,0 +1,143 @@
+// tests/hall_studio_world.mjs — the Studio (artist mode), R06 of goal 1000074
+// (task 1003117). The surface's load-bearing invariants, pinned so a later edit
+// cannot quietly turn the calm room back into a form or a write path.
+//
+// hall_audit.mjs already holds this page to the universal rules (style.css +
+// shell.js present, no colour literal, no page-declared pack var, no bespoke
+// pager/chart, no sideways-scroll style). hall_nav.mjs pins the nav entry and
+// hall_page_gate_map.mjs the sign-in gate. What is left, and lives here, is what
+// only the Studio must be true: it writes nothing, it gates nothing, it is a
+// room and not a table, and it IS the artist mode it claims to be.
+//
+// Pure file-read (no DB/network) — runs in the DB-free unit gate.
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HALL = path.join(ROOT, 'modules/hall-ui/public');
+const read = (f) => fs.readFileSync(path.join(HALL, f), 'utf8');
+
+const HTML = read('studio.html');
+// Comments legitimately mention markup (e.g. "the page's one <h1>"), so strip
+// them before counting tags — the invariant is about the rendered DOM, not prose.
+const HTML_NC = HTML.replace(/<!--[\s\S]*?-->/g, '');
+const JS = read('studio.js');
+const CSS = read('studio.css');
+
+test('the Studio writes NOTHING — the goal\'s no-live-CMS rule, at the surface', () => {
+  // Every craft act (coach the grader, remake copy, propose wording) happens on
+  // the surface that owns it (the task record, the copy desk) as a claimed,
+  // graded, shipped task. This room only READS and ROUTES. A POST/PATCH/DELETE
+  // here would be the live-CMS write path the goal forbids (criterion
+  // artist-edits-land-as-tasks) — so it must not exist.
+  const writes = JS.match(/\.request\(\s*['"](POST|PATCH|PUT|DELETE)['"]/g) || [];
+  assert.deepEqual(writes, [], `studio.js must issue no writes; found ${writes.join(', ')}`);
+});
+
+test('the reviews read is bounded and correct', () => {
+  // Review requests (cascade.js) are filed at backlog, discipline artist. They sit
+  // there until dismissed and cascade files one per qualifying ship, so the read
+  // MUST carry a limit cap — the unbounded-read shape modules/hall-ui/CLAUDE.md
+  // flags as a repeat bug. Assert the actual bound, not just the filter, so the
+  // test name does not overclaim.
+  assert.match(JS, /\/tasks\?discipline=artist&status=backlog&limit=\$\{REVIEW_LIMIT\}/, 'the backlog artist read carries a limit cap');
+  assert.match(JS, /const REVIEW_LIMIT = \d+;/, 'the cap is a named, finite constant');
+  assert.match(JS, /source === 'cascade'/, 'and rows are filtered to the cascade (review) source');
+});
+
+test('the copy-desk read is best-effort — the room degrades, never errors', () => {
+  // An instance without the copy-desk module 404s /copy-desk/queue; the Studio
+  // must fall back to reviews alone, so the flags loader returns [] on !ok rather
+  // than throwing or blanking the room.
+  assert.match(JS, /copy-desk\/queue\?status=open/, 'flags come from the open copy-desk queue');
+  assert.match(JS, /if \(!res\.ok\) return \[\];/, 'a failed queue read yields no flags, not an error');
+});
+
+test('it is artist mode — the room declares the mode marker', () => {
+  // The social-mode pattern (shell.js applySocial): the mode rides an attribute
+  // on the document root, set here statically so entering the room IS entering
+  // the mode with no paint flash. Losing it makes this just another page.
+  assert.match(HTML, /<html[^>]*\bdata-artist="on"/, 'the page declares data-artist="on" on <html>');
+});
+
+test('one <main>, one <h1> — the greeting is it', () => {
+  // one-header-main-h1, checked here in the static markup so every state (incl.
+  // the no-JS fallback) keeps the single heading.
+  const h1s = HTML_NC.match(/<h1\b/g) || [];
+  assert.equal(h1s.length, 1, 'exactly one <h1>');
+  assert.match(HTML_NC, /<h1[^>]*id="studio-greet"/, 'the greeting is the page h1');
+});
+
+test('a room, not a table — no tabular markup', () => {
+  // The criterion is explicit: "rather than another table of rows". The copy
+  // desk is the table; the Studio must not become a second one.
+  assert.ok(!/<table\b/.test(HTML_NC) && !/<table\b/.test(JS), 'the Studio renders no <table>');
+});
+
+test('the accent is spent only where the rule allows', () => {
+  // DESIGN.md's One Warm Thing Rule: the accent lights the pressable (the primary
+  // action, .btn-accent, which the shell owns) or the LIVE. The one warm thing
+  // this sheet paints is the ambient lamp (an accent wash), documented as the
+  // room's live light; nothing else in studio.css may fill from the accent.
+  const accentFills = CSS.match(/background:\s*[^;]*var\(--accent\)[^;]*;/g) || [];
+  assert.ok(accentFills.length <= 1, `studio.css spends the accent on at most the lamp; found ${accentFills.length}`);
+});
+
+// Boot the real shell.js under a DOM stub (the hall_nav.mjs pattern) whose
+// #nav-studio records classList toggles, so applyCraftEmphasis is tested for
+// what it DOES, not just that it exists.
+function bootShell() {
+  const src = fs.readFileSync(path.join(HALL, 'shell.js'), 'utf8');
+  const makeEl = () => {
+    const classes = new Set();
+    return {
+      dataset: {}, style: {}, title: '', textContent: '', hidden: false, _classes: classes,
+      set innerHTML(_v) {}, get innerHTML() { return ''; },
+      classList: {
+        add: (c) => classes.add(c), remove: (c) => classes.delete(c),
+        toggle: (c, on) => { const want = on === undefined ? !classes.has(c) : !!on; if (want) classes.add(c); else classes.delete(c); return want; },
+        contains: (c) => classes.has(c),
+      },
+      setAttribute() {}, getAttribute() { return null; }, removeAttribute() {},
+      addEventListener() {}, querySelectorAll() { return []; }, appendChild() {}, focus() {},
+    };
+  };
+  const els = new Map();
+  const getEl = (id) => { if (!els.has(id)) els.set(id, makeEl()); return els.get(id); };
+  const document = {
+    body: { dataset: { page: 'studio' } },
+    documentElement: getEl('__html__'),
+    getElementById: getEl,
+    querySelectorAll() { return []; },
+    createElement() { return makeEl(); },
+    addEventListener() {}, dispatchEvent() {}, get cookie() { return ''; }, set cookie(_v) {},
+  };
+  const location = { hostname: 'builders.cloudbongos.com', origin: 'https://builders.cloudbongos.com', pathname: '/studio', hash: '', assign() {}, replace() {} };
+  const window = {
+    __BRANDING__: {}, __MODULES__: { enabled: {} },
+    BongosClient: { createClient: () => ({ request: () => new Promise(() => {}) }) },
+    matchMedia: () => ({ matches: false, addEventListener() {} }),
+    localStorage: { getItem() { return null; }, setItem() {} },
+    requestAnimationFrame() {}, scrollTo() {}, location, addEventListener() {},
+  };
+  const sandbox = { window, document, location, console, setTimeout, clearTimeout, CustomEvent: class {} };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  vm.runInContext(src, sandbox, { filename: 'shell.js' });
+  return { applyAccess: window.OTBShell.applyAccess, navStudio: () => getEl('nav-studio') };
+}
+
+test('the Studio nav entry is warmed only for an artist-craft builder', () => {
+  const { applyAccess, navStudio } = bootShell();
+
+  applyAccess({ authed: true, rank: 'archon', builder: { display_name: 'Artist A', preferred_disciplines: ['artist', 'ideator'] } });
+  assert.ok(navStudio()._classes.has('nav-item--craft'), 'an artist-craft builder gets the warmed entry');
+
+  applyAccess({ authed: true, rank: 'archon', builder: { display_name: 'Eng E', preferred_disciplines: ['engineer'] } });
+  assert.ok(!navStudio()._classes.has('nav-item--craft'), 'and a non-artist builder does not (the class is toggled off)');
+});