@bongos/core 1.19.414 → 1.19.416

package/tests/own_scope_guard.mjs

@@ -0,0 +1,472 @@
+// tests/own_scope_guard.mjs
+//
+// THE OWN-SCOPE STRUCTURAL GUARD — "an own-scoped route takes its subject from
+// the authenticated session, never from the request" (goal 1000045, criterion
+// own-scope-held-by-a-test; task 1003343).
+//
+// WHY THIS EXISTS. The 2026-08-28 account-security audit found the hole CLOSED:
+// no route on main derives acting identity from a URL, query, body or header
+// parameter. But it was closed BY CONSTRUCTION — held by convention and code
+// review, with nothing in CI to stop a future edit reopening it. One module
+// already held the line structurally (modules/memory, tests/memory_isolation.mjs)
+// and that guard covered exactly one file — and sits in the INTEGRATION set, so
+// it never runs in the DB-free PR lane. This file generalises it to every
+// own-scoped surface and lives in the lane that actually executes (task 1002282:
+// a proof that never runs is not a gate).
+//
+// THE MECHANISM — how an own-scoped route is told apart from a legitimate
+// cross-owner one, which takes an identifier DELIBERATELY and is rank-gated
+// instead (PATCH /builders/:id/rank, the /boxes/:builderId fleet routes,
+// POST /government/assignments, the goals membership routes, release-on-behalf):
+//
+//   1. An explicit INVENTORY of own-scoped surface FILES, one stated reason
+//      each. A blanket grep across all routes would break the cross-owner ones;
+//      the inventory is what keeps the guard off them entirely.
+//   2. Inside an inventoried file, THE ROUTE'S OWN DECLARED PATH decides. A
+//      route that means to act on somebody else NAMES them in its path
+//      (`:builderId`). A route whose path names no builder is own-scoped, full
+//      stop — that is the route's own public promise to its callers, it cannot
+//      be forgotten (you cannot declare a route without a path), and it is
+//      exactly the promise this guard enforces.
+//   3. A path that DOES name a builder is a cross-owner route, and is allowed
+//      only via a per-route exemption carrying a stated reason AND a required
+//      GATE PATTERN THE GUARD VERIFIES IS PRESENT. The exemption does not
+//      exempt — it substitutes a different, checked obligation. Drop the gate
+//      and the route fails here even though it is on the exemption list.
+//   4. A DISCOVERY BACKSTOP over every route file in the repo: any file that
+//      declares a `/me`-mounted route must be in the inventory. `/me` is
+//      unambiguous — nothing cross-owner is ever mounted there — so a future
+//      own-scoped surface cannot appear without either joining the inventory or
+//      failing this test.
+//
+// Rejected alternatives, and why: a marker/annotation convention (`@own-scoped`)
+// is invisible to the guard exactly when the author forgets it, which is the
+// failure mode we exist to catch. An allowlist of exempt ROUTES with no gate
+// check is a free pass — the greenest fix for a red build becomes "add a line to
+// the allowlist". Detecting the adjacent rank gate ALONE cannot work either:
+// rank is a PRIVILEGE dimension, not an OWNERSHIP one (a cross-owner route can
+// be metic-gated and a self route archon-gated), which is precisely why
+// src/bongos/route-rank-check.js cannot catch an own-scoped route growing an
+// override parameter. Here the gate check is used only where ownership has
+// already been established from the path.
+//
+// DB-free by construction: this reads source text. No Postgres, no server.
+//
+// Run:  node tests/own_scope_guard.mjs
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+
+const here = path.dirname(url.fileURLToPath(import.meta.url));
+const repo = path.join(here, '..');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// ===========================================================================
+// The inventory — own-scoped surfaces, one stated reason each.
+// ===========================================================================
+
+const OWN_SCOPED_SURFACES = [
+  {
+    file: 'src/bongos/routes/me.js',
+    why: 'the /me aggregator: identity, rank, credits, streak, claims and prefs for the CALLER. Every slice keys on req.builder.id.',
+    crossOwner: [],
+  },
+  {
+    file: 'modules/builder-settings/routes/settings.js',
+    why: 'the per-builder preference domain (wandering, skill, sound, render, model-allocation, display name) carved out of /me — read and write, all keyed on req.builder.id.',
+    crossOwner: [],
+  },
+  {
+    file: 'modules/platform-identity/routes/profile.js',
+    why: "the builder's OWN cross-project profile controls (hide flag, handle, bio/links) — all keyed on req.builder.github_id.",
+    crossOwner: [],
+  },
+  {
+    file: 'modules/memory/routes/memory.js',
+    why: 'per-builder memory (ADR 0024 §4). The self endpoints are own-scoped; the five cross-builder endpoints name their target in the path and are gate-verified below.',
+    crossOwner: [
+      {
+        path: '/memory/builders/:builderId/files',
+        gate: /requirePermission\(\s*['"]memory\.read\.any['"]\s*\)/,
+        why: 'forensic LIST of another builder\'s memory metadata — permission-gated on the memory.read.any atom and audit-logged.',
+      },
+      {
+        path: '/memory/builders/:builderId/file',
+        gate: /requirePermission\(\s*['"]memory\.read\.any['"]\s*\)/,
+        why: 'forensic READ of another builder\'s memory file — permission-gated on the memory.read.any atom and audit-logged.',
+      },
+      {
+        path: '/memory/bfg/builders/:builderId/files',
+        gate: /requireBfgPrincipal/,
+        why: 'the BFG session-analysis LIST — gated on the BFG principal identity, stricter than any rank (ADR 0026 §6C).',
+      },
+      {
+        path: '/memory/bfg/builders/:builderId/file',
+        gate: /requireBfgPrincipal/,
+        why: 'the BFG session-analysis READ — gated on the BFG principal identity.',
+      },
+      {
+        path: '/memory/builders/:builderId/bfg-write',
+        gate: /requireBfgPrincipal/,
+        why: 'the BFG cross-builder WRITE — gated on the BFG principal identity plus a kill switch.',
+      },
+    ],
+  },
+];
+
+// Floors that keep this guard from going quietly vacuous (a regex that stops
+// matching would otherwise "pass" by checking nothing).
+const MIN_OWN_SCOPED_ROUTES_TOTAL = 28;
+const MIN_OWN_SCOPED_ROUTES_PER_FILE = 3;
+
+// ===========================================================================
+// Machinery
+// ===========================================================================
+
+/**
+ * Blank out comments while preserving every byte offset and newline, so route
+ * indices and line numbers stay true. Comment prose talks ABOUT req.body.builder
+ * constantly; only real code may be judged.
+ */
+function blankComments(src) {
+  const out = src.split('');
+  let i = 0;
+  let state = 'code'; // code | line | block | sq | dq | tpl
+  while (i < src.length) {
+    const c = src[i];
+    const d = src[i + 1];
+    if (state === 'code') {
+      if (c === '/' && d === '/') { out[i] = ' '; out[i + 1] = ' '; i += 2; state = 'line'; continue; }
+      if (c === '/' && d === '*') { out[i] = ' '; out[i + 1] = ' '; i += 2; state = 'block'; continue; }
+      if (c === "'") { state = 'sq'; i++; continue; }
+      if (c === '"') { state = 'dq'; i++; continue; }
+      if (c === '`') { state = 'tpl'; i++; continue; }
+      i++; continue;
+    }
+    if (state === 'line') {
+      if (c === '\n') { state = 'code'; i++; continue; }
+      out[i] = ' '; i++; continue;
+    }
+    if (state === 'block') {
+      if (c === '*' && d === '/') { out[i] = ' '; out[i + 1] = ' '; i += 2; state = 'code'; continue; }
+      if (c !== '\n') out[i] = ' ';
+      i++; continue;
+    }
+    // inside a string literal — kept verbatim (literals are evidence, see below)
+    if (c === '\\') { i += 2; continue; }
+    if ((state === 'sq' && c === "'") || (state === 'dq' && c === '"') || (state === 'tpl' && c === '`')) { state = 'code'; i++; continue; }
+    i++;
+  }
+  return out.join('');
+}
+
+/**
+ * Does this identifier NAME A BUILDER — i.e. is it a subject selector rather
+ * than a payload field? This is the guard's contract, so it is a written list,
+ * not a vibe: anything containing "builder" or "owner", plus the explicit set of
+ * other ways one account points at another. Deliberately NOT here: `handle`,
+ * `display_name`, `anthropic_user_id` — payload the caller sets on THEMSELVES.
+ */
+const SUBJECT_NAMES = new Set([
+  'githubid', 'githublogin', 'githubuser', 'githubuserid', 'login',
+  'actas', 'asbuilder', 'onbehalf', 'onbehalfof', 'impersonate', 'impersonateas',
+  'targetid', 'targetlogin', 'targetbuilder', 'subject', 'subjectid',
+  'accountid', 'memberid', 'principal', 'principalid',
+]);
+function namesABuilder(name) {
+  const k = String(name).toLowerCase().replace(/[_-]/g, '');
+  if (k.includes('builder') || k.includes('owner')) return true;
+  return SUBJECT_NAMES.has(k);
+}
+
+const REQUEST_CONTAINERS = 'body|query|params|headers';
+const ROUTE_DECL = /\brouter\.(get|post|put|patch|delete|all)\(\s*(['"`])([^'"`\n]+)\2/g;
+const HANDLER_START = /(?:async\s*)?\(\s*_?req\s*,/;
+
+/** Split a route file into { verb, routePath, decl, body, line } records. */
+function parseRoutes(code) {
+  const decls = [...code.matchAll(ROUTE_DECL)];
+  return decls.map((m, i) => {
+    const start = m.index;
+    const end = i + 1 < decls.length ? decls[i + 1].index : code.length;
+    const window = code.slice(start, end);
+    const hIdx = window.search(HANDLER_START);
+    return {
+      verb: m[1],
+      routePath: m[3],
+      line: code.slice(0, start).split('\n').length,
+      // the middleware chain (where the gates live) vs the handler (where the
+      // subject is read). When the handler can't be located, both halves fall
+      // back to the whole window — conservative, never silently narrower.
+      decl: hIdx >= 0 ? window.slice(0, hIdx) : window,
+      body: hIdx >= 0 ? window.slice(hIdx) : window,
+    };
+  });
+}
+
+/**
+ * Every way this route pulls a named thing out of the request, as a flat list of
+ * { how, name } — direct reads, optional chaining, destructuring, aliases of a
+ * container, rest elements, literal bracket access, computed access (judged by
+ * the string literals in the route's array literals, which is where a copy-these
+ * -fields loop keeps its key list), and header lookups via req.get().
+ */
+function requestReads(routeBody) {
+  const reads = [];
+  const containerRe = String.raw`req\s*\??\.\s*(?:${REQUEST_CONTAINERS})`;
+
+  // Aliases: `const body = req.body` / `const { a, ...rest } = req.query`.
+  const aliases = new Set();
+  for (const m of routeBody.matchAll(new RegExp(String.raw`(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*${containerRe}\b`, 'g'))) {
+    aliases.add(m[1]);
+  }
+  // Re-derived on every use: the destructuring pass below can discover MORE
+  // aliases (rest elements), and each later pass must see them.
+  const containers = () => `(?:${containerRe}${aliases.size ? `|\\b(?:${[...aliases].join('|')})` : ''})`;
+
+  // Destructuring — `const { builder_id } = req.body`. A rest element becomes an
+  // alias itself: an object spread off the request IS the request.
+  for (const m of routeBody.matchAll(new RegExp(String.raw`(?:const|let|var)\s*\{([^}]*)\}\s*=\s*${containers()}\b`, 'g'))) {
+    for (const part of m[1].split(',')) {
+      const rest = part.match(/\.\.\.\s*([A-Za-z_$][\w$]*)/);
+      if (rest) { aliases.add(rest[1]); continue; }
+      const key = part.split(':')[0].split('=')[0].trim();
+      if (key) reads.push({ how: 'destructured from the request', name: key });
+    }
+  }
+
+  // Direct member reads — `req.query.builder_id`, `body?.owner`.
+  for (const m of routeBody.matchAll(new RegExp(String.raw`${containers()}\s*\??\.\s*([A-Za-z_$][\w$]*)`, 'g'))) {
+    reads.push({ how: 'read from the request', name: m[1] });
+  }
+
+  // Literal bracket access — `req.body['builder_id']`. Exact, so judged exactly.
+  for (const m of routeBody.matchAll(new RegExp(String.raw`${containers()}\s*\[\s*(['"])([^'"]+)\1`, 'g'))) {
+    reads.push({ how: 'read from the request', name: m[2] });
+  }
+
+  // Variable bracket access — `req.body[k]`. The key is unknowable statically, so
+  // the string literals in the route's ARRAY literals are the candidate key set:
+  // that is exactly how the copy-these-fields loops in these files are written.
+  // Scoped to array literals so ordinary message/error strings can't false-positive.
+  if (new RegExp(String.raw`${containers()}\s*\[\s*[A-Za-z_$]`).test(routeBody)) {
+    for (const arr of routeBody.matchAll(/\[([^\][]*)\]/g)) {
+      for (const m of arr[1].matchAll(/(['"])([A-Za-z_][\w-]*)\1/g)) {
+        reads.push({ how: 'a candidate computed request key', name: m[2] });
+      }
+    }
+  }
+
+  // Header lookups by name.
+  for (const m of routeBody.matchAll(/\breq\s*\.\s*get\(\s*(['"])([^'"]+)\1/g)) {
+    reads.push({ how: 'read from a request header', name: m[2] });
+  }
+
+  return reads;
+}
+
+/** The `:name` segments a route declares — the route saying out loud what it takes. */
+function pathParams(routePath) {
+  return [...routePath.matchAll(/:([A-Za-z_][\w]*)/g)].map((m) => m[1]);
+}
+
+// ===========================================================================
+// Self-tests — the machinery above is the guard, so it gets proved too.
+// ===========================================================================
+
+console.log('guard machinery:');
+
+t('blankComments erases comment prose but keeps offsets and string literals', () => {
+  const src = "const a = 1; // req.body.builder_id\n/* req.query.owner */ const s = 'builder_id';\n";
+  const out = blankComments(src);
+  assert.equal(out.length, src.length, 'offsets must be preserved');
+  assert.ok(!/req\.body\.builder_id/.test(out), 'line comments must be erased');
+  assert.ok(!/req\.query\.owner/.test(out), 'block comments must be erased');
+  assert.ok(/'builder_id'/.test(out), 'string literals are evidence and must survive');
+});
+
+t('namesABuilder separates subject selectors from self-payload fields', () => {
+  for (const n of ['builder_id', 'builderId', 'owner', 'target_builder', 'github_id', 'githubLogin', 'as_builder', 'login']) {
+    assert.equal(namesABuilder(n), true, `${n} names a builder`);
+  }
+  for (const n of ['handle', 'display_name', 'bio', 'links', 'limit', 'anthropic_user_id', 'anthropic_email', 'files', 'path', 'hide_stats', 'preferred_disciplines', 'user-agent']) {
+    assert.equal(namesABuilder(n), false, `${n} is self-payload, not a subject`);
+  }
+});
+
+t('requestReads sees direct, optional-chained, destructured and aliased reads', () => {
+  const reads = (s) => requestReads(s).map((r) => r.name);
+  assert.ok(reads('const x = req.query.builder_id;').includes('builder_id'));
+  assert.ok(reads('const x = req.body?.owner;').includes('owner'));
+  assert.ok(reads('const { builder_id, y } = req.body;').includes('builder_id'));
+  assert.ok(reads('const b = req.body;\nconst v = b.builder_id;').includes('builder_id'));
+  assert.ok(reads('const { a, ...rest } = req.body;\nconst v = rest.owner_id;').includes('owner_id'));
+  assert.ok(reads("const v = req.body['builder_id'];").includes('builder_id'));
+  assert.ok(reads("for (const k of ['builder_id']) f[k] = req.body[k];").includes('builder_id'));
+  assert.ok(reads("const v = req.get('x-builder-id');").includes('x-builder-id'));
+  // ...but an ordinary message string is not a candidate key: no bracket read, no scan.
+  assert.ok(!reads("return res.fail('builder_not_found', 404);").includes('builder_not_found'));
+});
+
+// ===========================================================================
+// The guard
+// ===========================================================================
+
+console.log('\nown-scope guard (every own-scoped route keys on the session):');
+
+let totalOwnScoped = 0;
+let totalCrossOwner = 0;
+
+for (const surface of OWN_SCOPED_SURFACES) {
+  const abs = path.join(repo, surface.file);
+  const raw = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : null;
+
+  t(`${surface.file} — inventoried own-scoped surface exists and declares routes`, () => {
+    assert.ok(raw !== null, `${surface.file} is in the own-scoped inventory but does not exist — update the inventory or restore the file`);
+    const rawDecls = (raw.match(/\brouter\.(?:get|post|put|patch|delete|all)\(/g) || []).length;
+    const parsed = parseRoutes(blankComments(raw)).length;
+    assert.ok(parsed > 0, 'no routes parsed — the route-declaration regex has rotted');
+    assert.equal(parsed, rawDecls, `parsed ${parsed} routes but the file declares ${rawDecls} — the guard is not seeing every route`);
+  });
+  if (raw === null) continue;
+
+  const code = blankComments(raw);
+  const routes = parseRoutes(code);
+  const exemptions = surface.crossOwner || [];
+  const usedExemptions = new Set();
+  let ownScopedHere = 0;
+
+  for (const r of routes) {
+    const id = `${surface.file}:${r.line} ${r.verb.toUpperCase()} ${r.routePath}`;
+    const subjectParams = pathParams(r.routePath).filter(namesABuilder);
+
+    if (subjectParams.length > 0) {
+      // Cross-owner: names its target in the path. Allowed only with a stated
+      // reason AND a gate the guard confirms is really there.
+      totalCrossOwner++;
+      t(`${id} — cross-owner route is exempted with a reason AND carries its gate`, () => {
+        const ex = exemptions.find((e) => e.path === r.routePath);
+        assert.ok(
+          ex,
+          `takes a builder from the path (:${subjectParams.join(', :')}) but is not on the cross-owner exemption list for this file. `
+          + 'If it is deliberately cross-owner, add it with a stated reason and the gate that protects it; otherwise it must not name a builder.'
+        );
+        usedExemptions.add(ex.path);
+        assert.ok(ex.why && ex.why.length > 20, 'a cross-owner exemption must carry a stated reason');
+        // The exemption is only as strong as what it demands, so the demand
+        // itself is constrained: it must name a real privilege atom, not a
+        // regex that matches anything the author happens to have written.
+        assert.match(
+          ex.gate.source, /require(?:Permission|Rank|BfgPrincipal|Archon)/,
+          'a cross-owner exemption must require a real gate (requirePermission / requireRank / requireBfgPrincipal / requireArchon)'
+        );
+        assert.ok(
+          ex.gate.test(r.decl),
+          `the exemption requires ${ex.gate} on the middleware chain and it is NOT there — a cross-owner route without its gate is the hole this guard exists to catch`
+        );
+      });
+      continue;
+    }
+
+    // Own-scoped: the path names no builder, so the subject can only be the session.
+    ownScopedHere++;
+    totalOwnScoped++;
+
+    t(`${id} — own-scoped route never takes its subject from the request`, () => {
+      const offenders = requestReads(r.body).filter((x) => namesABuilder(x.name));
+      assert.equal(
+        offenders.length, 0,
+        `${offenders.map((o) => `"${o.name}" (${o.how})`).join(', ')} — this route's path names no builder, so its subject MUST come from req.builder. `
+        + 'If it is genuinely meant to act on someone else, name them in the path, gate it, and add a cross-owner exemption.'
+      );
+    });
+
+    t(`${id} — own-scoped route derives its subject from the authenticated session`, () => {
+      assert.ok(/\brequireBuilder\b/.test(r.decl), 'an own-scoped route must sit behind requireBuilder');
+      const readsSession = /\breq\s*\.\s*builder\b/.test(r.body) || /\bassertSelf\s*\(\s*req\b/.test(r.body);
+      const ignoresRequest = /\(\s*_req\s*,/.test(r.body);
+      assert.ok(
+        readsSession || ignoresRequest,
+        'neither reads req.builder nor declares its request unused (_req) — it is scoped to nobody, which is not own-scope'
+      );
+    });
+  }
+
+  t(`${surface.file} — contributes a real number of own-scoped routes (not vacuous)`, () => {
+    assert.ok(
+      ownScopedHere >= MIN_OWN_SCOPED_ROUTES_PER_FILE,
+      `only ${ownScopedHere} own-scoped routes found (floor ${MIN_OWN_SCOPED_ROUTES_PER_FILE}) — either routes moved out or the parser stopped seeing them`
+    );
+  });
+
+  t(`${surface.file} — every listed cross-owner exemption still names a real route`, () => {
+    const stale = exemptions.filter((e) => !usedExemptions.has(e.path)).map((e) => e.path);
+    assert.equal(stale.length, 0, `stale exemption(s) for route(s) that no longer exist: ${stale.join(', ')} — an exemption for a deleted route silently widens the guard`);
+  });
+}
+
+// ===========================================================================
+// Discovery backstop + lane proof
+// ===========================================================================
+
+console.log('\ncoverage (the guard cannot be dodged by adding a new file, or parked out of CI):');
+
+function routeFiles() {
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) { if (e.name !== 'node_modules') walk(p); }
+      else if (e.name.endsWith('.js')) out.push(p);
+    }
+  };
+  walk(path.join(repo, 'src'));
+  walk(path.join(repo, 'modules'));
+  return out;
+}
+
+t('every file in the repo that mounts a /me route is in the own-scoped inventory', () => {
+  const inventory = new Set(OWN_SCOPED_SURFACES.map((s) => s.file.split('/').join(path.sep)));
+  const missing = [];
+  for (const abs of routeFiles()) {
+    const code = blankComments(fs.readFileSync(abs, 'utf8'));
+    const declaresMe = parseRoutes(code).some((r) => r.routePath === '/me' || r.routePath.startsWith('/me/'));
+    if (!declaresMe) continue;
+    const rel = path.relative(repo, abs);
+    if (!inventory.has(rel)) missing.push(rel.split(path.sep).join('/'));
+  }
+  assert.equal(
+    missing.length, 0,
+    `these files mount /me routes but are not in OWN_SCOPED_SURFACES: ${missing.join(', ')}. `
+    + 'Nothing cross-owner is ever mounted at /me, so add them to the inventory.'
+  );
+});
+
+t('the guard checks a real number of own-scoped routes overall', () => {
+  assert.ok(
+    totalOwnScoped >= MIN_OWN_SCOPED_ROUTES_TOTAL,
+    `only ${totalOwnScoped} own-scoped routes checked (floor ${MIN_OWN_SCOPED_ROUTES_TOTAL})`
+  );
+  assert.ok(totalCrossOwner > 0, 'no cross-owner route was exercised — the gate-verification path is untested');
+});
+
+t('this guard runs in the DB-free unit lane (it is not parked as integration or known-failing)', () => {
+  const runner = fs.readFileSync(path.join(repo, 'scripts', 'gds', 'run-unit-tests.js'), 'utf8');
+  assert.ok(
+    !/own_scope_guard/.test(runner),
+    'own_scope_guard is named in run-unit-tests.js — if it landed in INTEGRATION or KNOWN_FAILING it would stop gating anything (task 1002282)'
+  );
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/projects_hub.mjs

@@ -16,6 +16,7 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
 
 const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HUB = fs.readFileSync(path.join(ROOT, 'public-landing', 'projects.html'), 'utf8');
@@ -1403,31 +1404,41 @@ test('the joinability in-flight line shares the visibility section’s push pred
 /* ── the planets and the field (task 1003319) — the map's orbs as the landing's
    chrome objects in the project's accent, a per-project template with a
    deterministic default walk, and the field brought to the world. ── */
-test('the planet templates: nine names, the walk changes shape and style each step, the catalog and the migration agree', () => {
-  const list = (SCRIPT.match(/var ORB_TEMPLATES = \[([^\]]*)\]/) || [, ''])[1];
-  const names = [...list.matchAll(/'([a-z-]+)'/g)].map((m) => m[1]);
-  assert.equal(names.length, 9);
-  assert.equal(new Set(names).size, 9, 'nine distinct templates');
-  for (const t of names) assert.match(t, /^(blob|pair|bead)-(tint|wash|chrome)$/);
-  for (let i = 1; i < names.length; i++) {
-    const [s0, y0] = names[i - 1].split('-');
-    const [s1, y1] = names[i].split('-');
-    assert.ok(s0 !== s1 && y0 !== y1, `walk step ${i} changes both shape and style`);
+const TEMPLATE_RE = /^(blob|pair|bead)-(tint|wash|chrome|(frost|gold|obsidian)-(tint|wash|plain))$/;
+const partsOf = (t) => { const p = t.split('-'); return p.length === 3 ? p : [p[0], 'chrome', p[1]]; };
+
+test('the planet templates: shape × material × style; the walk changes all three each step; the catalog and the migration agree (tasks 1003319, 1003337)', () => {
+  const walkList = (SCRIPT.match(/var ORB_WALK = \[([^\]]*)\]/) || [, ''])[1];
+  const walk = [...walkList.matchAll(/'([a-z-]+)'/g)].map((m) => m[1]);
+  assert.equal(walk.length, 12);
+  assert.equal(new Set(walk).size, 12, 'twelve distinct walk positions');
+  for (const t of walk) assert.match(t, TEMPLATE_RE);
+  for (let i = 0; i < walk.length; i++) {
+    const [s0, m0, y0] = partsOf(walk[(i + walk.length - 1) % walk.length]);
+    const [s1, m1, y1] = partsOf(walk[i]);
+    assert.ok(s0 !== s1 && m0 !== m1 && y0 !== y1, `walk step ${i} changes shape, material and style (wrapping)`);
   }
-  const pi = fs.readFileSync(path.join(ROOT, 'modules', 'platform-identity', 'platform-identity.js'), 'utf8');
-  const server = [...((pi.match(/const PROJECT_TEMPLATES = \[([\s\S]*?)\];/) || [, ''])[1]).matchAll(/'([a-z-]+)'/g)].map((m) => m[1]);
-  assert.deepEqual(server, names, 'the hub and the catalog walk the same list in the same order');
-  const mig = fs.readFileSync(path.join(ROOT, 'modules', 'platform-identity', 'migrations', 'platform_identity_012_project_template.sql'), 'utf8');
-  for (const t of names) assert.ok(mig.includes(`'${t}'`), `migration 012 names ${t}`);
+  const P = createRequire(import.meta.url)('../modules/platform-identity/platform-identity.js');
+  assert.deepEqual(P.PROJECT_TEMPLATE_WALK, walk, 'the hub and the catalog walk the same list in the same order');
+  // the client's full set is built from the same grammar the server builds it from
+  assert.match(SCRIPT, /var ORB_SHAPES = \['blob', 'pair', 'bead'\], ORB_MATERIALS = \['frost', 'gold', 'obsidian'\];/);
+  assert.match(SCRIPT, /ORB_SHAPES\.forEach\(function \(s\) \{ \['tint', 'wash', 'chrome'\]\.forEach\(function \(y\) \{ ORB_TEMPLATES\.push\(s \+ '-' \+ y\); \}\); \}\);/);
+  assert.match(SCRIPT, /ORB_SHAPES\.forEach\(function \(s\) \{ ORB_MATERIALS\.forEach\(function \(m\) \{ \['tint', 'wash', 'plain'\]\.forEach\(function \(y\) \{ ORB_TEMPLATES\.push\(s \+ '-' \+ m \+ '-' \+ y\); \}\); \}\); \}\);/);
+  assert.equal(P.PROJECT_TEMPLATES.length, 36);
+  for (const t of P.PROJECT_TEMPLATES) assert.match(t, TEMPLATE_RE);
+  for (const t of walk) assert.ok(P.PROJECT_TEMPLATES.includes(t), `the walk's ${t} is a valid name`);
+  const mig = fs.readFileSync(path.join(ROOT, 'modules', 'platform-identity', 'migrations', 'platform_identity_013_project_template_materials.sql'), 'utf8');
+  for (const t of P.PROJECT_TEMPLATES) assert.ok(mig.includes(`'${t}'`), `migration 013 names ${t}`);
 });
 
 test('the walk assigns the template by canonical position beside the accent; a curated template wins; the platform is the pair in chrome', () => {
-  assert.match(SCRIPT, /function assignAccents[\s\S]*?p\._acc = ORB_ACCENTS\[i % ORB_ACCENTS\.length\];\s*p\._tpl = ORB_TEMPLATES\[i % ORB_TEMPLATES\.length\];/,
+  assert.match(SCRIPT, /function assignAccents[\s\S]*?p\._acc = ORB_ACCENTS\[i % ORB_ACCENTS\.length\];\s*p\._tpl = ORB_WALK\[i % ORB_WALK\.length\];/,
     'one walk, two assignments');
-  assert.match(SCRIPT, /function templateOf\(p\) \{\s*return ORB_TEMPLATES\.indexOf\(p\.template\) !== -1 \? p\.template : \(p\._tpl \|\| ORB_TEMPLATES\[0\]\);/,
+  assert.match(SCRIPT, /function templateOf\(p\) \{\s*return ORB_TEMPLATES\.indexOf\(p\.template\) !== -1 \? p\.template : \(p\._tpl \|\| ORB_WALK\[0\]\);/,
     'a curated name wins; an unknown name is not a choice');
   assert.match(SCRIPT, /_acc: ORB_ACCENTS\[slugAccent\(inst\.slug\)\], _tpl: slugTemplate\(inst\.slug\)/, 'an owned-only entry walks by its slug');
-  assert.match(SCRIPT, /var tpl = templateOf\(p\), tplParts = tpl\.split\('-'\);\s*a\.setAttribute\('data-template', tpl\);\s*a\.setAttribute\('data-shape', tplParts\[0\]\);\s*a\.setAttribute\('data-style', tplParts\[1\]\);/,
+  assert.match(SCRIPT, /function slugTemplate\(slug\) \{ return ORB_WALK\[slugHash\(slug\) % ORB_WALK\.length\]; \}/, 'by the walk, not the whole set');
+  assert.match(SCRIPT, /var tpl = templateOf\(p\), tplParts = tpl\.split\('-'\);\s*a\.setAttribute\('data-template', tpl\);\s*a\.setAttribute\('data-shape', tplParts\[0\]\);\s*a\.setAttribute\('data-material', tplParts\.length === 3 \? tplParts\[1\] : 'chrome'\);\s*a\.setAttribute\('data-style', tplParts\[tplParts\.length - 1\]\);/,
     'the orb carries its template as data attributes; the sheet does the rest');
   assert.match(HUB, /<a class="worldOrb" id="selfOrb" href="\/" data-shape="pair" data-style="chrome" data-template="pair-chrome"/, 'the platform is its own mark');
 });
@@ -1455,6 +1466,43 @@ test("the planet is the landing's object on the landing's crop maths: the three
   assert.match(COSMOS, /--plate-bongos-cut:url\(\/assets\/world\/r2-bongos-chrome-a-cut\.webp\);/);
 });
 
+test('the materials (task 1003337): a whole object per plate, the crop recomputed from the cutout\'s alpha box; every plate ships with alpha and a sidecar', () => {
+  // the boxes measured from the shipped cutouts (alpha >= 16 on the 2048² plate); the sheet
+  // pads each side by 1.5% and derives zoom = 1/width, px/py = -u0/-v0 × zoom (square plates)
+  const BBOX = { 'frost-blob': { u0:0.168, u1:0.8223, v0:0.2495, v1:0.7642 }, 'frost-pair': { u0:0.0591, u1:0.9409, v0:0.2764, v1:0.7231 }, 'frost-bead': { u0:0.1685, u1:0.8066, v0:0.1738, v1:0.8198 }, 'gold-blob': { u0:0.1274, u1:0.8584, v0:0.1035, v1:0.9019 }, 'gold-pair': { u0:0.0552, u1:0.9458, v0:0.2739, v1:0.7383 }, 'gold-bead': { u0:0.0542, u1:0.9478, v0:0.0542, v1:0.9434 }, 'obsidian-blob': { u0:0.1885, u1:0.8018, v0:0.1177, v1:0.8979 }, 'obsidian-pair': { u0:0.0249, u1:0.9707, v0:0.3096, v1:0.7158 }, 'obsidian-bead': { u0:0.1416, u1:0.854, v0:0.1431, v1:0.8535 } };
+  const MARGIN = 0.015;
+  const f5 = (n) => { const s = n.toFixed(5); return s.replace(/^(-?)0\./, '$1.').replace(/\.?0+$/, '') || '0'; };
+  for (const [key, b] of Object.entries(BBOX)) {
+    const [material, shape] = key.split('-');
+    const U0 = Math.max(0, b.u0 - MARGIN), U1 = Math.min(1, b.u1 + MARGIN), V0 = Math.max(0, b.v0 - MARGIN), V1 = Math.min(1, b.v1 + MARGIN);
+    const w = U1 - U0, h = V1 - V0, zoom = 1 / w;
+    const rule = `.worldOrb[data-material="${material}"][data-shape="${shape}"]{--tpl-src:var(--plate-${material}-${shape}-cut);--tpl-ar:${f5(w / h)};--tpl-zoom:${f5(zoom)};--tpl-px:${f5(-U0 * zoom)};--tpl-py:${f5(-V0 * zoom)};}`;
+    assert.ok(COSMOS.includes(rule), `the ${key} crop follows from its box: ${rule}`);
+    assert.ok(COSMOS.includes(`--plate-${material}-${shape}-cut:url(/assets/world/r3-${material}-${shape}-cut.webp);`), `the ${key} plate token`);
+    const file = path.join(ROOT, 'public-landing', 'assets', 'world', `r3-${material}-${shape}-cut.webp`);
+    assert.ok(fs.existsSync(file), `${key}: the cutout ships`);
+    assert.ok(fs.existsSync(file + '.json'), `${key}: with its sidecar`);
+    const head = fs.readFileSync(file).subarray(0, 40).toString('latin1');
+    assert.ok(head.startsWith('RIFF') && head.includes('WEBP') && /ALPH|VP8X/.test(head), `${key}: WebP with an alpha chunk`);
+  }
+  assert.match(COSMOS, /\.worldOrb\[data-style="plain"\]\{--tpl-ink:transparent;--tpl-blend:normal;\}/, 'plain is the material as rendered');
+  // the material rules carry two attributes so they outrank the one-attribute chrome crops
+  assert.ok(COSMOS.indexOf('.worldOrb[data-material="frost"][data-shape="blob"]') > COSMOS.indexOf('.worldOrb[data-shape="bead"]{'), 'the materials follow the chrome crops');
+});
+
+test('the field carries a rendered backdrop (task 1003337): one token, cover, a slow transform drift, the plate and its sidecar on disk', () => {
+  assert.match(COSMOS, /--field-plate:url\(\/assets\/world\/r3-space-nebula\.jpg\);/, 'the pick is one token');
+  assert.match(COSMOS, /\.field \.ground\{position:absolute;inset:-4%;background:var\(--sky-bg\) var\(--field-plate\) center\/cover no-repeat;\}/);
+  assert.match(COSMOS, /@media \(prefers-reduced-motion:no-preference\)\{\s*\.field \.ground\{animation:groundDrift 90s ease-in-out infinite alternate;\}/, 'the drift only runs where motion is welcome');
+  assert.match(COSMOS, /@keyframes groundDrift\{from\{transform:translate3d\([^)]*\) scale\(1\.02\);\}to\{transform:translate3d\([^)]*\) scale\(1\.06\);\}\}/, 'transform only');
+  const plate = path.join(ROOT, 'public-landing', 'assets', 'world', 'r3-space-nebula.jpg');
+  assert.ok(fs.existsSync(plate) && fs.existsSync(plate + '.json'), 'the plate and its sidecar ship');
+  const side = JSON.parse(fs.readFileSync(plate + '.json', 'utf8'));
+  assert.equal(side.kind, 'backdrop');
+  assert.match(side.prompt, /pure black/i, 'a text-free plate on black');
+  assert.doesNotMatch(COSMOS, /\.field \.ground::after\{content:""/, 'nothing drawn over the plate');
+});
+
 test('the style is a blend on a masked colour layer; the accent never paints the box; the ring and the spotlight follow the silhouette', () => {
   assert.match(COSMOS, /\.worldOrb \.disc::before\{content:"";position:absolute;inset:0;\s*background-image:linear-gradient\(var\(--tpl-ink\),var\(--tpl-ink\)\),var\(--tpl-src\);/);
   assert.match(COSMOS, /background-blend-mode:var\(--tpl-blend\),normal;\s*-webkit-mask-image:var\(--tpl-src\);mask-image:var\(--tpl-src\);/, 'the mask is the plate itself');
@@ -1502,9 +1550,11 @@ test('the kit proves the field path: the fixture carries a curated template and
   const fixture = JSON.parse(fs.readFileSync(path.join(ROOT, 'modules', 'ui-design', 'kit', 'fixtures', 'featured.json'), 'utf8'));
   const otb = fixture.projects.find((p) => p.origin === 'https://amazonprimea.com');
   assert.equal(otb.template, 'bead-wash');
+  assert.equal(fixture.projects.find((p) => p.origin === 'https://demo.cloudbongos.com').template, 'pair-gold-wash', 'a material template rides the wire (task 1003337)');
   assert.ok(fixture.projects.every((p) => 'template' in p), 'the wire never drops the key');
   const states = JSON.parse(fs.readFileSync(path.join(ROOT, 'public-landing', 'projects.states.json'), 'utf8'));
   const attrs = states.states['in-map'].expect.attr.map((a) => a.join(' '));
   assert.ok(attrs.includes('#selfOrb data-template pair-chrome'));
   assert.ok(attrs.some((a) => a.includes('amazonprimea.com') && a.endsWith('data-template bead-wash')), 'the curated template reaches the orb');
+  assert.ok(attrs.some((a) => a.includes('demo.cloudbongos.com') && a.endsWith('data-material gold')), 'the material reaches the orb as its own attribute');
 });