@bongos/core 1.19.513 → 1.19.515

package/modules/platform-identity/projects-feed.js

@@ -0,0 +1,142 @@
+// modules/platform-identity/projects-feed.js — THE public projects feed: WHO is on
+// the map, and WHAT each row is allowed to say (R06, task 1002325; ADR 0182 D1/D2a/D3).
+// The in-repo lever the orbs page reads. The publish-gate.js precedent — one question,
+// one file, so no two surfaces can answer it differently.
+//
+// THREE ANSWERS, and they belong together because each is only safe given the others:
+//
+//   • WHO — `listPublicProjects`. A project is on the map iff `status = 'active' AND
+//     publishable`, the derived identity gate, taken from publishableSql() so this feed
+//     and the curation list read ONE definition. It used to be `featured = true`, which
+//     made Archon curation load-bearing for visibility at all: an owner could set their
+//     project public and see nothing happen (ADR 0182 D3). `featured` keeps the only job
+//     D3 leaves it — RANKING among rows already on the map. Dark matter is excluded HERE,
+//     in SQL, because a client-side filter ships the husk to anyone who opens a network tab.
+//
+//   • WHAT IT DRAWS AS — `orbForState`, the ADR 0182 D1 mapping:
+//        public → planet   (identified, anyone may join)
+//        private → star    (identified, no self-join, applications accepted)
+//        stealth → black hole (ANONYMOUS, no self-join, applications refused)
+//     Three surfaces render it — this feed, Explore (R07, task 1002326) and the static
+//     orbs site (R09, task 1002328) — and the last is a different repo. A mapping copied
+//     into each is a mapping that drifts.
+//
+//   • WHAT IT MAY SAY — `feedShapeFor`, the D2a privacy boundary in code: a stealth
+//     project exposes EXISTENCE, never IDENTITY. Redaction is server-side because the
+//     naive version sends the row and lets the orbs page hide it, which leaks the whole
+//     project to anyone who opens the network tab — and that page is a static site
+//     outside this repo, so we could not enforce it there even in principle.
+//
+// TWO DELIBERATE FAIL-CLOSED CHOICES, because this is a privacy boundary, not a
+// rendering detail:
+//   1. AN UNKNOWN STATE DRAWS AS A BLACK HOLE. A fourth enum value added later and not
+//      mapped here would otherwise ship its project's name as a planet.
+//   2. THE STEALTH SHAPE IS AN ALLOW-LIST, NOT A DENY-LIST — everything is nulled except
+//      the two keys a black hole may carry, so a column added to the feed next year is
+//      anonymous without anyone remembering to come back here. A deny-list of "the
+//      identifying fields" is correct exactly until the feed grows.
+//
+// WHY ITS OWN FILE. The account-visibility.js / publish-gate.js reason: platform-identity.js
+// sits at the file-size ratchet. The caller-facing symbols (listPublicProjects, feedShapeFor,
+// orbForState, isStealthProject, ORB_BY_STATE) are re-exported there so the module's public
+// surface is unchanged; orbStateOf, FALLBACK_PROJECT_STATE and STEALTH_ANONYMOUS_KEEPS are
+// this file's own internals and are reached only from here and its test.
+// Proof: ../../tests/visible_projects_feed.mjs
+'use strict';
+
+const { pool: defaultPool } = require('../../src/module-api');
+const { publishableSql } = require('./publish-gate');
+
+// ADR 0182 D1's mapping, and the only copy of it in the repo. The three words are locked
+// by goal 1000046's `proj-visibility-states` criterion, not chosen here.
+const ORB_BY_STATE = Object.freeze({
+  public: 'planet',
+  private: 'star',
+  stealth: 'black-hole',
+});
+
+// What an unrecognised (or absent) stored value is treated as — the ANONYMOUS state,
+// deliberately. A project whose door we cannot read is one whose name we must not publish.
+const FALLBACK_PROJECT_STATE = 'stealth';
+
+// The ONLY keys a black hole may carry; everything else on the row is nulled. No stable
+// per-project key appears here on purpose: an id, a slug or a hash of the origin would
+// each let an observer who kept yesterday's public feed name the project that went stealth
+// today. Black holes are interchangeable, which is the whole point of the metaphor.
+const STEALTH_ANONYMOUS_KEEPS = Object.freeze(['state', 'orb']);
+
+// The stored join door, normalised to a state this file knows. Never echoes an
+// unvalidated value onto the wire.
+function orbStateOf(visibility) {
+  const v = String(visibility ?? '').trim();
+  return Object.prototype.hasOwnProperty.call(ORB_BY_STATE, v) ? v : FALLBACK_PROJECT_STATE;
+}
+
+// The render type for a state — the one mapping R07 and R09 both read. PURE.
+function orbForState(state) {
+  return ORB_BY_STATE[orbStateOf(state)];
+}
+
+// Is this row anonymous on the map? Exported so the feed route can keep a stealth
+// project's origin out of the per-project enrichment fetches entirely — asking its own
+// public API for its builders' avatars would both put identity on the wire and tell that
+// project it was being enumerated.
+function isStealthProject(project) {
+  return orbStateOf(project?.visibility) === 'stealth';
+}
+
+// ONE catalog row → the public wire row. Spends `visibility` deriving `state` + `orb` (it
+// never doubles it on the wire), then either passes the identified row through or rebuilds
+// it from the allow-list above. The redaction NULLS rather than DELETES: the feed's
+// standing contract is that an unanswerable value is null and never absent, because
+// JSON.stringify drops the absent one and a client would read `undefined` on some rows and
+// null on others. A redacted row is a full-width row that says nothing. PURE.
+function feedShapeFor(project) {
+  const { visibility, ...rest } = project || {};
+  const state = orbStateOf(visibility);
+  const shaped = { ...rest, state, orb: ORB_BY_STATE[state] };
+  if (state !== 'stealth') return shaped;
+  const anonymous = {};
+  for (const key of Object.keys(shaped)) {
+    anonymous[key] = STEALTH_ANONYMOUS_KEEPS.includes(key) ? shaped[key] : null;
+  }
+  return anonymous;
+}
+
+// The feed's hard ceiling. Until R06 the listing was bounded by an Archon choosing to
+// feature a project; the swap to `publishable` replaced that human bound with self-service,
+// on a route that is public, CORS-open, unauthenticated AND drives one outbound stats fetch
+// per row. A cap is the cheap half of that trade — the honest half is pagination, which is
+// its own task; this constant only stops the tail from being unbounded meanwhile. Set far
+// above the live catalog, so it truncates nothing today.
+const PUBLIC_FEED_MAX_PROJECTS = 500;
+
+// Every project ON THE MAP, in the public projection (no owner_github_id, no status).
+// `visibility` is projected because feedShapeFor() derives each row's state + orb from it;
+// it is spent there and never reaches the wire. created_at is the LISTED date — when the
+// hub first catalogued the row, not when the project began (task 1002778). updated_at may
+// sort but never projects: feature toggles and client re-registration bump it, so as a
+// public "last updated" it would lie. `description` is the publish BAR, spent in the
+// predicate, never a card field.
+async function listPublicProjects({ pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `SELECT origin, name, tagline, art_url, type, template, created_at, visibility
+       FROM platform_identity_projects
+      WHERE status = 'active' AND ${publishableSql()}
+      ORDER BY featured DESC, updated_at DESC
+      LIMIT ${PUBLIC_FEED_MAX_PROJECTS}`,
+  );
+  return rows;
+}
+
+module.exports = {
+  ORB_BY_STATE,
+  FALLBACK_PROJECT_STATE,
+  STEALTH_ANONYMOUS_KEEPS,
+  orbStateOf,
+  orbForState,
+  isStealthProject,
+  feedShapeFor,
+  PUBLIC_FEED_MAX_PROJECTS,
+  listPublicProjects,
+};

package/modules/platform-identity/routes/projects.js

@@ -1,7 +1,14 @@
 // modules/platform-identity/routes/projects.js — the hub projects catalog + the
 // curated public Explore showcase (ADR 0141 §5, task #1002110).
 //
-//   GET   /projects/featured   — PUBLIC Explore listing (featured + active only)
+//   GET   /projects/featured   — PUBLIC projects feed: every project on the map
+//                                (active + publishable), each carrying its `state`
+//                                and `orb` render type, stealth rows anonymised
+//                                server-side, dark matter excluded (ADR 0182 D2a/D3).
+//                                The PATH keeps the old word: it is a rank:public,
+//                                CORS-open URL that a static site and other origins
+//                                already fetch, and renaming it would break them for
+//                                nothing. `featured` now only RANKS the feed.
 //   GET   /projects            — Archon: full curation list (+ featured flags, the stored
 //                                join door, and the DERIVED publish verdict — ADR 0182)
 //   POST  /projects            — Archon: create / update a catalog entry
@@ -141,13 +148,20 @@ module.exports = function projectsRoutes() {
     }
   });
 
-  // The PUBLIC Explore showcase — featured + active projects only, public projection.
-  // CORS-enabled cross-origin read (a status page / the apex fetches it pre-auth).
+  // The PUBLIC projects feed — every project ON THE MAP (active + publishable),
+  // public projection. CORS-enabled cross-origin read (a status page / the apex /
+  // the static orbs site fetches it pre-auth).
   router.use('/projects/featured', corsPublicGet('/projects/featured'));
-  // rank: public — a curated public showcase; no auth by design.
+  // rank: public — the public map of projects; no auth by design.
   router.get('/projects/featured', async (_req, res) => {
     try {
-      const projects = await pi.listFeaturedProjects({ pool });
+      const projects = await pi.listPublicProjects({ pool });
+      // A stealth project is on the map ANONYMOUSLY (ADR 0182 D2a), so its origin
+      // is kept out of both enrichments below: asking its own public API for its
+      // builders and their avatars would put identity on the wire, and tell that
+      // project it was being enumerated. feedShapeFor() redacts the row either
+      // way — this is the half that never makes the request at all.
+      const identified = projects.filter((p) => !pi.isStealthProject(p));
       // Builders + tags come from each project's OWN public API, because the
       // apex catalog does not know them and the membership tables would report
       // zero for every hand-wired project (task 1002771; see project-stats.js).
@@ -156,7 +170,7 @@ module.exports = function projectsRoutes() {
       // listing — a broken stats fetch cannot take the catalog down with it.
       let stats = {};
       try {
-        stats = await projectStats.getProjectStats(projects.map((p) => p.origin));
+        stats = await projectStats.getProjectStats(identified.map((p) => p.origin));
       } catch (err) {
         console.error('[platform-identity] project stats enrichment failed (non-fatal):', err.message);
       }
@@ -168,7 +182,7 @@ module.exports = function projectsRoutes() {
       // a failed read leaves every project on the platform's own pick.
       let planets = {};
       try {
-        planets = await api.resolveOptional('provisioning.projectPlanets', async () => ({}))(projects.map((p) => hostOfOrigin(p.origin)));
+        planets = await api.resolveOptional('provisioning.projectPlanets', async () => ({}))(identified.map((p) => hostOfOrigin(p.origin)));
       } catch (err) {
         log.warn('project planets enrichment failed (non-fatal):', err.message);
       }
@@ -183,8 +197,13 @@ module.exports = function projectsRoutes() {
       // catalog's; a project that did not answer carries the ONE shared null
       // shape, so the wire never drops a key. art_url is catalog text an Archon
       // typed — scheme-checked here, and again on the client, before it is a src.
+      // feedShapeFor() is the LAST thing each row passes through, deliberately: it
+      // derives `state` + `orb` from the stored door and, for a stealth project,
+      // rebuilds the row from an allow-list of the two keys a black hole may carry
+      // (ADR 0182 D2a). Redacting any earlier would be silently undone by the
+      // spreads above.
       res.json({
-        projects: projects.map((p) => ({
+        projects: projects.map((p) => pi.feedShapeFor({
           ...p,
           art_url: projectStats.httpUrl(p.art_url, 2048),
           ...(stats[p.origin] || projectStats.NULL_STATS),

package/modules/platform-identity/tests/platform-identity.mjs

@@ -261,17 +261,21 @@ await ta('upsertProject carries the planet template, COALESCE-preserved; an unkn
   for (const t of P.PROJECT_TEMPLATES.slice(0, 9)) assert.ok(mig12.includes(`'${t}'`), `migration 012 named ${t}`);
   // and the public projection carries it, so the sky can read a curated choice
   const pool3 = mockPool([{ rows: [] }]);
-  await P.listFeaturedProjects({ pool: pool3 });
+  await P.listPublicProjects({ pool: pool3 });
   const sel = (pool3.calls[0].text.match(/SELECT([\s\S]*?)FROM/i) || [, ''])[1];
-  assert.match(sel, /\btemplate\b/, 'the featured projection carries the template');
+  assert.match(sel, /\btemplate\b/, 'the public projection carries the template');
 });
 
-await ta('listFeaturedProjects returns a PUBLIC projection (featured+active only, no owner/status)', async () => {
+await ta('listPublicProjects returns a PUBLIC projection (on-the-map only, no owner/status)', async () => {
   const pool = mockPool([{ rows: [{ origin: 'https://p', name: 'Proj', tagline: 't', art_url: null, created_at: '2026-08-01T00:00:00Z' }] }]);
-  const out = await P.listFeaturedProjects({ pool });
+  const out = await P.listPublicProjects({ pool });
   assert.equal(out.length, 1);
   const c = pool.calls[0];
-  assert.match(c.text, /WHERE featured = true AND status = 'active'/);
+  // R06 (task 1002325) replaced the `featured = true` gate with the derived publish
+  // gate: a project is on the map iff it is active AND publishable (ADR 0182 D3).
+  // The full predicate + the stealth redaction are pinned by tests/visible_projects_feed.mjs.
+  assert.match(c.text, /WHERE status = 'active' AND /);
+  assert.ok(c.text.includes(P.publishableSql()), 'the map predicate is the shared gate');
   // Pin the SELECT LIST itself, not the whole query — an ORDER BY mention must
   // not satisfy a projection guard, and SELECT * must never sneak owner/status
   // onto a CORS-open rank:public route.

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.513",
+  "version": "1.19.515",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.513",
+      "version": "1.19.515",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.513",
+  "version": "1.19.515",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/src/module-api.js

@@ -45,7 +45,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.513'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.515'; // 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/government_seed.mjs

@@ -182,3 +182,38 @@ test('migration objects are all governance_-namespaced (ADR 0083 §5)', () => {
     }
   }
 });
+
+// THE GAP THE DRIFT GUARD ABOVE CANNOT SEE (found by the task 1003177 grader).
+//
+// The union model is a regex over `SELECT '<rank>', unnest(ARRAY[…])`. It reads
+// the KEYS and never looks at the table those keys are inserted INTO — so a new
+// grant migration copied from a `governance_*` sibling passes it while writing to
+// `governance_role_permissions (role_key, …)`, the PRE-rename names.
+//
+// government_001_rename_from_governance renamed that table to
+// `government_rank_permissions` and its `role_key` column to `rank_key`, with no
+// compatibility shim. Migrations apply in filename order, so on any database —
+// a fresh install included — a `government_*`-prefixed file writes AFTER the
+// rename and must use the new names or error at apply time. The permission would
+// then never resolve, and its routes would 403 for every rank, Archon included.
+//
+// Scoped to the `government_`-prefixed files on purpose: the historical
+// `governance_*` migrations legitimately name the pre-rename tables (they ran
+// before the rename, and renaming an applied migration re-runs it — the standing
+// rule in modules/government/CLAUDE.md).
+test('a post-rename grant migration writes to the RENAMED table, not the old one', () => {
+  const postRename = grantSqlByFile.filter(([f]) => f.startsWith('government_'));
+  assert.ok(postRename.length > 0, 'there is at least one government_-prefixed grant migration');
+
+  for (const [file, sql] of postRename) {
+    const ddl = sql.replace(/^\s*--.*$/gm, '');   // a comment may CITE the old name
+    assert.ok(!/governance_role_permissions/.test(ddl),
+      `${file}: writes to governance_role_permissions — renamed to government_rank_permissions by government_001`);
+    assert.ok(!/\brole_key\b/.test(ddl),
+      `${file}: names the role_key column — renamed to rank_key by government_001`);
+    if (/INSERT INTO/.test(ddl)) {
+      assert.match(ddl, /INSERT INTO government_rank_permissions \(rank_key, permission_key\)/,
+        `${file}: a grant insert must target government_rank_permissions (rank_key, permission_key)`);
+    }
+  }
+});