@bongos/core 1.19.392 → 1.19.394

package/modules/platform-identity/migrations/platform_identity_011_project_visibility.sql

@@ -0,0 +1,57 @@
+-- platform_identity_011_project_visibility.sql — the project join-door enum + the
+-- missing identity field the publish gate reads (BV1.R04, task 1002323; ADR 0182
+-- Decision 1 + Decision 4). Precedent: `goals.visibility` (core_188, ADR 0112).
+--
+-- ADR 0182 splits what looked like ONE four-valued state into TWO axes:
+--
+--   publishability  DERIVED  from the identity gate (name + description)  → on the map at all
+--   the join door   STORED   `visibility ∈ (public, private, stealth)`    → how it renders, who gets in
+--
+-- so "dark matter" is the ABSENCE of a met bar, never a stored fourth value. There
+-- is deliberately no way to choose it: a stored `unlisted` would compete with
+-- `private` and give one question two sources of truth that can drift apart.
+--
+-- THE BACKFILL is the DEFAULT clause, not a separate UPDATE: every existing row
+-- takes `visibility = 'public'` atomically at ADD COLUMN time, which is today's
+-- behaviour unchanged. `description` is deliberately left NULL on existing rows —
+-- ADR 0182 D4 refuses to seed it from `tagline` ("a description is the publish bar;
+-- collapsing them means editing your card can unpublish your project"), so an
+-- existing row is publishable only once its owner writes a real description.
+--
+-- THIS MIGRATION CHANGES NO LIVE BEHAVIOUR. The public feed predicate is still
+-- `featured = true AND status = 'active'` until R06 (task 1002325) replaces it, so
+-- nothing leaves or joins the map here. When R06 lands, rows with no description
+-- become dark matter — that is the designed consequence, and R16 (task 1002335) is
+-- the surface that tells an owner exactly which field is missing.
+--
+-- Additive + `platform_identity_`-namespaced (ADR 0083 §5). Forward-safe: ADD
+-- COLUMN only, so the previous code release still runs against this schema.
+-- Idempotent (IF NOT EXISTS + the drop-then-add CHECK pattern from migration 006).
+
+BEGIN;
+
+-- 1. The join door. Three values, all of them VISIBLE (ADR 0182 D2) — `private` is
+--    visible-but-closed exactly as it already is for goals, and `stealth` exposes
+--    EXISTENCE without IDENTITY (redacted server-side in the feed by R06).
+ALTER TABLE platform_identity_projects
+  ADD COLUMN IF NOT EXISTS visibility text NOT NULL DEFAULT 'public';
+
+ALTER TABLE platform_identity_projects DROP CONSTRAINT IF EXISTS platform_identity_projects_visibility_check;
+ALTER TABLE platform_identity_projects ADD CONSTRAINT platform_identity_projects_visibility_check
+  CHECK (visibility IN ('public', 'private', 'stealth'));
+
+-- 2. The second half of the identity gate. `name` already exists NOT NULL; this is
+--    the column ADR 0182 D4 found missing. NOT `tagline` — see the header.
+ALTER TABLE platform_identity_projects
+  ADD COLUMN IF NOT EXISTS description text;
+
+COMMENT ON COLUMN platform_identity_projects.visibility IS
+  'The join door, set by the project owner: public|private|stealth (ADR 0182 D1). The name is a mild lie kept for one word across the goal and project planes: this column does NOT decide visibility — publishability does. Anyone reading visibility = ''public'' and expecting the orb on the map is reading it wrong; check the publish gate (name + description both present).';
+
+COMMENT ON COLUMN platform_identity_projects.description IS
+  'The second half of the publish gate (ADR 0182 D4): a project is publishable iff name AND description are both present. Distinct from tagline, which is the Explore card one-liner — collapsing them would mean editing your card can unpublish your project.';
+
+COMMENT ON COLUMN platform_identity_projects.status IS
+  'Operational lifecycle, owned by the system/Archon — a deprovisioned project is hidden. One of the three independent mechanisms in ADR 0182 D3 (status | visibility | featured); a project is on the map iff status = ''active'' AND publishable, and featured may only rank among rows already there.';
+
+COMMIT;

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

@@ -233,37 +233,90 @@ async function getClientByOrigin(origin, { pool = defaultPool } = {}) {
 // provisioning's copy on its own instances table).
 const PROJECT_TYPES = ['game', 'research', 'business', 'non-profit', 'not-sure'];
 
+// The stored JOIN DOOR (ADR 0182 D1, task 1002323). Three values, and ALL THREE ARE
+// VISIBLE: `private` is visible-but-closed (the `goals.visibility` meaning, ADR 0112),
+// `stealth` publishes EXISTENCE without IDENTITY. Mirrored by the CHECK in migration 011.
+//
+// There is no fourth value. "Dark matter" — off the map entirely — is DERIVED from the
+// publish gate below, never stored, because a stored `unlisted` would compete with
+// `private` and let two sources of truth for one question drift apart.
+const PROJECT_VISIBILITIES = ['public', 'private', 'stealth'];
+
+// The publish gate is IDENTITY ONLY (ADR 0182 D4, owner interview on R16): a name and a
+// description. Not tagline, art, modules, governance, or a completed interview — the bar
+// exists to keep empty husks off the map, not to enforce completeness.
+const PUBLISH_GATE_FIELDS = ['name', 'description'];
+
+// Is this project on the map at all? Returns the verdict AND what is missing, because
+// ADR 0182 D4 requires the gate to NAME what is missing rather than merely refuse: a
+// project that cannot be published and is not told why is indistinguishable from a
+// broken one. R16 (task 1002335) renders `missing`; R06 (task 1002325) reads `publishable`.
+function projectPublishability(project) {
+  const missing = PUBLISH_GATE_FIELDS.filter((f) => !String(project?.[f] ?? '').trim());
+  return { publishable: missing.length === 0, missing };
+}
+
+// The boolean alone, for predicates that do not care which field is absent.
+function projectIsPublishable(project) {
+  return projectPublishability(project).publishable;
+}
+
+// The SAME gate as a SQL fragment, so the feed predicate (R06) and the owner-facing
+// refusal (R16) cannot drift from projectPublishability() or from each other. `alias`
+// qualifies the columns for a joined query (e.g. publishableSql('p')).
+function publishableSql(alias) {
+  // The alias is INTERPOLATED, so it is the one thing here that could carry SQL. Callers
+  // pass a literal, but a helper that builds SQL should refuse anything that is not a
+  // bare identifier rather than trust every future caller to remember that.
+  if (alias && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(String(alias))) {
+    throw new Error('publishableSql: alias must be a bare SQL identifier');
+  }
+  const q = alias ? `${alias}.` : '';
+  return `(btrim(coalesce(${q}name, '')) <> '' AND btrim(coalesce(${q}description, '')) <> '')`;
+}
+
 // Upsert a catalog row (keyed by origin). Called when a client registers (so every
 // federated project is catalogued, unfeatured) and by the Archon create/curate route.
 // Never touches `featured` on update — that is Archon-only via setProjectFeatured.
-async function upsertProject({ origin, name, tagline, artUrl, ownerGithubId, type }, { pool = defaultPool } = {}) {
+//
+// `visibility` is likewise absent from the column list, and deliberately: ADR 0182 D5
+// makes the hub row a CACHE, so the hub never AUTHORIZES a door change — it accepts a
+// report from the authenticated instance (R08, task 1002327). Leaving the column out of
+// the upsert is what stops a client re-registration from silently resetting an owner's
+// door back to the 'public' default.
+async function upsertProject({ origin, name, tagline, description, artUrl, ownerGithubId, type }, { pool = defaultPool } = {}) {
   const norm = String(origin || '').replace(/\/+$/, '');
   if (!norm) throw new Error('project origin required');
   // off-vocabulary → null (the DB CHECK is the backstop; a declaration is never invented)
   const declaredType = PROJECT_TYPES.includes(type) ? type : null;
   const { rows } = await pool.query(
-    `INSERT INTO platform_identity_projects (origin, name, tagline, art_url, owner_github_id, type)
-     VALUES ($1, $2, $3, $4, $5, $6)
+    `INSERT INTO platform_identity_projects (origin, name, tagline, description, art_url, owner_github_id, type)
+     VALUES ($1, $2, $3, $4, $5, $6, $7)
      ON CONFLICT (origin) DO UPDATE SET
        name            = EXCLUDED.name,
        tagline         = COALESCE(EXCLUDED.tagline, platform_identity_projects.tagline),
+       description     = COALESCE(EXCLUDED.description, platform_identity_projects.description),
        art_url         = COALESCE(EXCLUDED.art_url, platform_identity_projects.art_url),
        owner_github_id = COALESCE(EXCLUDED.owner_github_id, platform_identity_projects.owner_github_id),
        type            = COALESCE(EXCLUDED.type, platform_identity_projects.type),
        updated_at      = now()
-     RETURNING id, origin, name, tagline, art_url, owner_github_id, type, status, featured`,
-    [norm, name || norm, tagline ?? null, artUrl ?? null, ownerGithubId ?? null, declaredType],
+     RETURNING id, origin, name, tagline, description, art_url, owner_github_id, type, status, featured, visibility`,
+    [norm, name || norm, tagline ?? null, description ?? null, artUrl ?? null, ownerGithubId ?? null, declaredType],
   );
   return rows[0];
 }
 
+// A single catalog row, with the DERIVED publish verdict attached (ADR 0182 D1) — the
+// row alone cannot answer "is this on the map", so every read that returns one answers
+// it here rather than leaving each caller to re-derive the gate.
 async function getProject(id, { pool = defaultPool } = {}) {
   const { rows } = await pool.query(
-    `SELECT id, origin, name, tagline, art_url, owner_github_id, type, status, featured
+    `SELECT id, origin, name, tagline, description, art_url, owner_github_id, type, status, featured, visibility
        FROM platform_identity_projects WHERE id = $1`,
     [id],
   );
-  return rows[0] || null;
+  if (!rows[0]) return null;
+  return { ...rows[0], ...projectPublishability(rows[0]) };
 }
 
 // The PUBLIC Explore listing — featured + active projects only, public projection
@@ -282,15 +335,20 @@ async function listFeaturedProjects({ pool = defaultPool } = {}) {
   return rows;
 }
 
-// The Archon curation list — every active project + its featured flag.
+// The curation list — every active project, its featured flag, its stored door, and the
+// DERIVED publish verdict. `publishable` is computed in SQL from publishableSql() so this
+// list and the public feed (R06) read one definition; `missing` names the absent identity
+// field so a curator can see WHY a row is dark matter instead of guessing (ADR 0182 D4).
 async function listAllProjects({ pool = defaultPool } = {}) {
   const { rows } = await pool.query(
-    `SELECT id, origin, name, tagline, art_url, owner_github_id, type, status, featured, updated_at
+    `SELECT id, origin, name, tagline, description, art_url, owner_github_id, type, status,
+            featured, visibility, updated_at,
+            ${publishableSql()} AS publishable
        FROM platform_identity_projects
       WHERE status = 'active'
       ORDER BY featured DESC, updated_at DESC`,
   );
-  return rows;
+  return rows.map((r) => ({ ...r, missing: projectPublishability(r).missing }));
 }
 
 // Archon-only: flip the Explore feature flag on a catalog row.
@@ -1115,6 +1173,11 @@ module.exports = {
   getClientByOrigin,
   setClientStatus,
   // projects catalog + Explore
+  PROJECT_VISIBILITIES,
+  PUBLISH_GATE_FIELDS,
+  projectPublishability,
+  projectIsPublishable,
+  publishableSql,
   upsertProject,
   PROJECT_TYPES,
   getProject,

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

@@ -2,7 +2,8 @@
 // curated public Explore showcase (ADR 0141 §5, task #1002110).
 //
 //   GET   /projects/featured   — PUBLIC Explore listing (featured + active only)
-//   GET   /projects            — Archon: full curation list (+ featured flags)
+//   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
 //   PATCH /projects/:id/featured — Archon: the feature / unfeature control
 //
@@ -41,6 +42,10 @@ module.exports = function projectsRoutes() {
       origin: { required: true, type: 'string', maxLength: 512 },
       name: { required: true, type: 'string', maxLength: 200 },
       tagline: { type: 'string', maxLength: 400 },
+      // The second half of the publish gate (ADR 0182 D4, task 1002323) — NOT tagline,
+      // which is the Explore card one-liner. Longer cap than the tagline's on purpose:
+      // this is the thing that says what the project IS.
+      description: { type: 'string', maxLength: 2000 },
       art_url: { type: 'string', maxLength: 2048 },
       type: { type: 'string', enum: [...pi.PROJECT_TYPES] },
     })) return;
@@ -49,6 +54,7 @@ module.exports = function projectsRoutes() {
         origin: req.body.origin,
         name: req.body.name,
         tagline: req.body.tagline,
+        description: req.body.description,
         artUrl: req.body.art_url,
         type: req.body.type,
       }, { pool });

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

@@ -14,6 +14,7 @@
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 import crypto from 'node:crypto';
+import { readFileSync } from 'node:fs';
 
 const require = createRequire(import.meta.url);
 const P = require('../platform-identity.js');
@@ -253,6 +254,111 @@ await ta('setProjectFeatured flips the flag (Archon curation)', async () => {
   assert.deepEqual(pool.calls[0].params, [1, true]);
 });
 
+console.log('\nproject visibility: the stored door + the DERIVED publish gate (BV1.R04, ADR 0182):');
+
+t('the stored enum has exactly THREE values — dark matter is derived, never stored', () => {
+  assert.deepEqual([...P.PROJECT_VISIBILITIES].sort(), ['private', 'public', 'stealth']);
+  // ADR 0182 D2 / "Alternatives rejected": a stored fourth value would compete with
+  // `private` and give one question two sources of truth that can drift apart.
+  for (const forbidden of ['unlisted', 'dark-matter', 'dark_matter', 'hidden', 'published']) {
+    assert.ok(!P.PROJECT_VISIBILITIES.includes(forbidden), `${forbidden} must never be a stored door value`);
+  }
+});
+
+t('the publish gate is IDENTITY ONLY — name + description, and it NAMES what is missing', () => {
+  assert.deepEqual([...P.PUBLISH_GATE_FIELDS].sort(), ['description', 'name']);
+  const full = { name: 'Mercury', description: 'A weather sim.', tagline: 't', art_url: 'a', type: 'research' };
+  assert.deepEqual(P.projectPublishability(full), { publishable: true, missing: [] });
+  assert.equal(P.projectIsPublishable(full), true);
+  // ADR 0182 D4: the gate must name what is missing, never merely refuse.
+  assert.deepEqual(P.projectPublishability({ name: 'Mercury' }), { publishable: false, missing: ['description'] });
+  assert.deepEqual(P.projectPublishability({}), { publishable: false, missing: ['name', 'description'] });
+  // Whitespace is not an identity — a husk stays off the map.
+  assert.deepEqual(P.projectPublishability({ name: 'M', description: '   ' }).missing, ['description']);
+  assert.equal(P.projectIsPublishable(null), false);
+});
+
+t('a tagline is NOT a description — the card one-liner can never publish a project', () => {
+  // ADR 0182 D4: collapsing them means editing your card can unpublish your project.
+  const cardOnly = { name: 'Mercury', tagline: 'a weather sim' };
+  assert.equal(P.projectIsPublishable(cardOnly), false);
+  assert.deepEqual(P.projectPublishability(cardOnly).missing, ['description']);
+  // The bar is identity only — art, type, modules and governance are NOT on it.
+  assert.equal(P.projectIsPublishable({ name: 'M', description: 'd' }), true);
+});
+
+t('publishableSql is the SAME gate in SQL — one definition for the feed (R06) and the refusal (R16)', () => {
+  const bare = P.publishableSql();
+  const aliased = P.publishableSql('p');
+  for (const sql of [bare, aliased]) {
+    assert.match(sql, /\bname\b/);
+    assert.match(sql, /\bdescription\b/);
+    assert.doesNotMatch(sql, /\btagline\b/, 'the card one-liner is not on the bar');
+    assert.doesNotMatch(sql, /\bfeatured\b/, 'editorial promotion is not the publish gate (ADR 0182 D3)');
+    assert.doesNotMatch(sql, /\bvisibility\b/, 'the stored door does not decide publishability');
+  }
+  assert.match(aliased, /p\.name/, 'an alias qualifies both columns');
+  assert.match(aliased, /p\.description/);
+  assert.doesNotMatch(bare, /\w\.name/, 'no alias when none is asked for');
+  assert.equal(P.publishableSql(''), bare, 'an empty alias is the same as none');
+  // The alias is the one interpolated thing here — a helper that BUILDS SQL refuses
+  // anything that is not a bare identifier rather than trust every future caller.
+  assert.throws(() => P.publishableSql('p; DROP TABLE platform_identity_projects --'), /bare SQL identifier/);
+});
+
+await ta('upsertProject carries description (COALESCE-preserved) and NEVER writes visibility', async () => {
+  const pool = mockPool([{ rows: [{ id: '1', origin: 'https://p', description: 'd', visibility: 'public' }] }]);
+  await P.upsertProject({ origin: 'https://p', name: 'Proj', description: 'A weather sim.' }, { pool });
+  const c = pool.calls[0];
+  assert.match(c.text, /\bdescription\b/, 'the publish-gate field joins the upsert');
+  assert.match(c.text, /description\s*=\s*COALESCE/, 'a later descriptionless upsert must not unpublish the project');
+  assert.ok(c.params.includes('A weather sim.'), 'the description is parameterized');
+  // ADR 0182 D5: the hub row is a CACHE — it never AUTHORIZES a door change. If a client
+  // re-registration wrote visibility, it would silently reset an owner's door to 'public'.
+  assert.doesNotMatch(c.text, /visibility\s*=/, 'the door is reported (R08), never set by an upsert');
+});
+
+await ta('listAllProjects reports the stored door + the DERIVED verdict, computed in SQL', async () => {
+  const pool = mockPool([{ rows: [
+    { id: '1', name: 'Full', description: 'd', visibility: 'stealth', publishable: true },
+    { id: '2', name: 'Husk', description: null, visibility: 'public', publishable: false },
+  ] }]);
+  const out = await P.listAllProjects({ pool });
+  assert.match(pool.calls[0].text, /\bvisibility\b/, 'the stored door is projected');
+  assert.match(pool.calls[0].text, /AS publishable/, 'the verdict is derived in SQL, not re-derived per caller');
+  // A curator must be able to see WHY a row is dark matter, not just that it is.
+  assert.deepEqual(out[0].missing, []);
+  assert.deepEqual(out[1].missing, ['description']);
+  // All three doors are VISIBLE (D2) — a stealth row is a normal curation row here.
+  assert.equal(out[0].visibility, 'stealth');
+});
+
+await ta('getProject attaches the derived verdict — the row alone cannot answer "is this on the map"', async () => {
+  const pool = mockPool([{ rows: [{ id: '1', name: 'Husk', description: null, visibility: 'public', featured: true, status: 'active' }] }]);
+  const out = await P.getProject(1, { pool });
+  assert.match(pool.calls[0].text, /\bdescription\b/);
+  // featured + active + visibility='public' and STILL off the map: publishability is
+  // the axis that decides, exactly as the column comment warns.
+  assert.equal(out.publishable, false);
+  assert.deepEqual(out.missing, ['description']);
+  assert.equal(await P.getProject(2, { pool: mockPool([{ rows: [] }]) }), null);
+});
+
+t('migration 011 pins the schema half: three-value CHECK, additive, no tagline seed', () => {
+  const sql = readFileSync(new URL('../migrations/platform_identity_011_project_visibility.sql', import.meta.url), 'utf8');
+  const stripped = sql.replace(/--[^\n]*/g, ' ');
+  assert.match(stripped, /ADD COLUMN IF NOT EXISTS visibility text NOT NULL DEFAULT 'public'/);
+  assert.match(stripped, /ADD COLUMN IF NOT EXISTS description text/);
+  const check = (stripped.match(/CHECK \(visibility IN \(([^)]*)\)\)/) || [, ''])[1];
+  const values = check.split(',').map((v) => v.trim().replace(/'/g, '')).filter(Boolean).sort();
+  assert.deepEqual(values, ['private', 'public', 'stealth'], 'the DB CHECK mirrors PROJECT_VISIBILITIES exactly');
+  assert.deepEqual(values, [...P.PROJECT_VISIBILITIES].sort(), 'CHECK and constant cannot drift');
+  // The backfill IS the DEFAULT clause — and ADR 0182 D4 refuses a tagline seed, so an
+  // existing row stays dark matter until its owner writes a real description.
+  assert.doesNotMatch(stripped, /SET\s+description\s*=\s*tagline/i, 'description is never seeded from tagline');
+  assert.doesNotMatch(stripped, /\bDROP COLUMN\b|\bSET NOT NULL\b/i, 'additive + forward-safe only');
+});
+
 await ta('registerClient auto-catalogues the project (2nd query) when an origin is given', async () => {
   const pool = mockPool([{ rows: [{ client_id: 'c1', origin: 'https://p' }] }, { rows: [{ id: '9' }] }]);
   await P.registerClient({ clientId: 'c1', secret: 'z'.repeat(64), name: 'Proj', redirectUris: [], origin: 'https://p', ownerGithubId: 7 }, { pool });

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.392",
+  "version": "1.19.394",
   "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",