@bongos/core 1.19.392 → 1.19.393

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.392",
-  "core_contract": "1.19.392",
-  "source_commit": "4190fb38da41bebf7a88f615a8ab79fedd639d41",
+  "core_version": "1.19.393",
+  "core_contract": "1.19.393",
+  "source_commit": "e4673d8af6d2b24d57be0c3a9d31c15627ef07db",
   "source_ref": "HEAD",
-  "built_at": "2026-08-28T13:35:20.944Z",
+  "built_at": "2026-08-28T13:49:26.259Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 340,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1628,
+    "functional_verbatim": 1630,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1990,
-  "tree_sha256": "f7ac578ee44964ff1176606f3ecd818002c622d2c3916e3cc351ee9f789ec202",
+  "file_count": 1992,
+  "tree_sha256": "f327722f7c80662fb8f132891464528b071371bd874c73487b6f3a55b6424113",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -367,7 +367,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "4b36b46a77832a0f4fb56f627691e396e519ba886addcb9624db2301d67d5006"
+      "sha256": "e2924c48715177477a8f828e2118f832acad6b3f63ae7b4fe5f124e80a4e7c17"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -1487,12 +1487,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "01f4d002d3ea1b02c204b48674125deae8e0ffabdd77384852cc51348ecbd18b"
+      "sha256": "3e488311a87f4db6ffbb85b26c7a61fba0204ff6cc1cc8ab6c09b2ae21cea24b"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "246192acc035ea58448701176e6f98f6d2f0a01cf27930efcbc58c019291cd3e"
+      "sha256": "6e93e2f283103158bc46062459b79b5528424ffb57f4730eb29a1cdba1b4976b"
     },
     {
       "path": "docs/architecture.md",
@@ -4704,6 +4704,11 @@
       "mode": "0000644",
       "sha256": "8f03dc84d8fe3864aa5f933512df71259c266e8a16214a926cf89eaf01cc5668"
     },
+    {
+      "path": "modules/platform-identity/migrations/platform_identity_011_project_visibility.sql",
+      "mode": "0000644",
+      "sha256": "18e3641beba26d8a515616ba9bdb1bcc83151e620d6e038243d7d67850da3be8"
+    },
     {
       "path": "modules/platform-identity/module.json",
       "mode": "0000644",
@@ -4712,7 +4717,7 @@
     {
       "path": "modules/platform-identity/platform-identity.js",
       "mode": "0000644",
-      "sha256": "8e51d1b28d33534e04dffd0ac139aecb85b9f2a8e1c5a0adbd2847893b650f24"
+      "sha256": "89672916aa04ee2246df97e008ff1b42cd2945321760452676b80b26301a4783"
     },
     {
       "path": "modules/platform-identity/pollers/code-sweep.js",
@@ -4737,7 +4742,7 @@
     {
       "path": "modules/platform-identity/routes/projects.js",
       "mode": "0000644",
-      "sha256": "a3e25369ad9edc6aed1a8a6997d6b6cb794dce14abb3605954d535525af1a93a"
+      "sha256": "fc7be0e85b029ae4cd252ad9978bf64d481b743d1fc99143cf8c6bb250636bda"
     },
     {
       "path": "modules/platform-identity/routes/public-profile.js",
@@ -4757,7 +4762,7 @@
     {
       "path": "modules/platform-identity/tests/platform-identity.mjs",
       "mode": "0000644",
-      "sha256": "6f442cd4ae9ebb770e3537ae82da30e555f7e6ce3a293a60fbd154eff6c1eaf1"
+      "sha256": "dfb9a451afa52143f9d68aef371432e38b318d94fa83c8322f1dfd831780cd9c"
     },
     {
       "path": "modules/platform-identity/ui/.gitkeep",
@@ -5147,12 +5152,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "b36f0f8b8ea9a6748b1a3be5c3a8f54e33d20339b32c21e0ebb08cd71e1fe4c0"
+      "sha256": "e07dabb4292a7652cbd2f4bf6092eb6e4037693fcd55ee4964cb6b091749228d"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "95d40e824b8da871c7168496f16f6e36b91379d6c92489ce3f141a1f6fb2b854"
+      "sha256": "f8304e8d1f9338bccfae2cac3ea289dd58262eeccf5820857145a5490660a2e8"
     },
     {
       "path": "public-docs/index.html",
@@ -6362,7 +6367,7 @@
     {
       "path": "scripts/gds/run-unit-tests.js",
       "mode": "0000644",
-      "sha256": "21726e53ad33bef62c5a2a0e0d59c380927e06cfa00994d5bbfd9669b83ce167"
+      "sha256": "29ee6bd76bdfb65522170808b6e636032079a145df4f995570901fb4f05b6035"
     },
     {
       "path": "scripts/gds/sandbox-stage.js",
@@ -7142,7 +7147,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "129f7524912a1dfda3b4d8307d0cf12b1869b3c937f173846098597d542fba09"
+      "sha256": "14825991cbc68b5a14edfedbcb6ed78739254bc02ea966ce02516f65c9d5abc0"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9149,6 +9154,11 @@
       "mode": "0000644",
       "sha256": "6bd78c47b6dbbdd81f862df8afdc0b514e27f0ffb71d14161ac8feb19f9fbe19"
     },
+    {
+      "path": "tests/project_visibility_db.mjs",
+      "mode": "0000644",
+      "sha256": "cf233daef30554217cfcde137ad0718e2bcef3f3504198769dea6448a90af3b0"
+    },
     {
       "path": "tests/projects_hub.mjs",
       "mode": "0000644",

package/clients/bongos-client/index.d.ts

@@ -296,7 +296,7 @@ export interface PostMyProjectsJoinRequest { origin: string }
 export interface PostMyProjectsJoinResponse { ok: boolean; status: unknown; project: unknown; message: unknown }
 export interface PostOverrideRequestsIdDecideRequest { decision: string; note?: string }
 export interface PostProjectsInviteRequest { client_id: string; github_login: string }
-export interface PostProjectsRequest { origin: string; name: string; tagline?: string; art_url?: string; type?: string }
+export interface PostProjectsRequest { origin: string; name: string; tagline?: string; description?: string; art_url?: string; type?: string }
 export interface PostProjectsResponse { project: unknown }
 export interface PostProvisioningInstancesIdDomainRequest { domain: string }
 export interface PostProvisioningInstancesIdDomainResponse { ok: boolean; changed: boolean; queued: unknown; domain: unknown; message: unknown }

package/docs/api/openapi.json

@@ -19040,6 +19040,10 @@
             "type": "string",
             "maxLength": 400
           },
+          "description": {
+            "type": "string",
+            "maxLength": 2000
+          },
           "art_url": {
             "type": "string",
             "maxLength": 2048

package/docs/api-reference.md

@@ -415,7 +415,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | GET | `/api/bongos/projects` | `metic+archon` | — | the full curation list (includes unfeatured + owner attribution). |
-| POST | `/api/bongos/projects` | `metic+archon` | `origin`, `name`, `tagline`, `art_url`, `type` | create / update a catalog entry (manual seed for hand-wired instances; federated projects auto-catalogue at registration). |
+| POST | `/api/bongos/projects` | `metic+archon` | `origin`, `name`, `tagline`, `description`, `art_url`, `type` | create / update a catalog entry (manual seed for hand-wired instances; federated projects auto-catalogue at registration). |
 | PATCH | `/api/bongos/projects/:id/featured` | `metic+archon` | `featured` | the feature / unfeature control (the ADR 0141 §5 curation gate). |
 | GET | `/api/bongos/projects/featured` | `public` | — | a curated public showcase; no auth by design. |
 | POST | `/api/bongos/projects/invite` | `metic+archon` | `client_id`, `github_login` | invite a builder into a project (ADR 0141 §5, task #1002115). |

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.393",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.392",
+      "version": "1.19.393",
       "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.393",
   "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/scripts/gds/run-unit-tests.js

@@ -115,6 +115,11 @@ const INTEGRATION = new Set([
   // and an unverified claim about exactly that is the comment this task fixed.
   'recall_freshness_plan_db',
   'reward_mode_cost_plus_only',
+  // task 1002323 (BV1.R04): the project visibility half against real SQL. The DB-free
+  // sibling in the module pins the JS gate and the migration text; only a real engine can
+  // prove the CHECK actually refuses a stored fourth state, that the backfill lands on a
+  // pre-migration row, and that publishableSql and projectPublishability agree.
+  'project_visibility_db',
   'scouting_rollup_fanout', 'session_records',
   // task 1003217: the cost-row RAISE against real SQL. Every claim in it IS the
   // SQL — an ON CONFLICT DO UPDATE guarded to move a row only upward, and a

package/src/module-api.js

@@ -1224,8 +1224,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.390 with no explicit bump. run 33134514193. (task 1002620)
 //   1.19.392 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.391 with no explicit bump. run 33176032603. (task 1002620)
+//   1.19.393 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.392 with no explicit bump. run 33177136260. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.392'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.393'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/project_visibility_db.mjs

@@ -0,0 +1,175 @@
+// tests/project_visibility_db.mjs — BV1.R04, task 1002323 (goal 1000046; real DB).
+//
+// The DB-free sibling (modules/platform-identity/tests/platform-identity.mjs) pins the
+// JS gate and the migration's TEXT. This proves what only a real transaction engine can:
+//
+//   1. THE BACKFILL — a row that existed BEFORE migration 011 comes out `visibility =
+//      'public'` (today's behaviour, unchanged) with `description` still NULL, because
+//      ADR 0182 D4 refuses to seed the publish bar from `tagline`.
+//   2. THE CHECK actually refuses a fourth stored state — 'unlisted' / 'dark-matter'
+//      cannot be written, which is the constraint the whole 3+1 split rests on.
+//   3. THE DERIVED GATE agrees in SQL and in JS — publishableSql() and
+//      projectPublishability() return the same verdict for the same row, so the feed
+//      (R06) and the owner-facing refusal (R16) cannot disagree about who is on the map.
+//   4. `featured = true AND status = 'active'` is NO LONGER "is this public" — a
+//      featured, active, visibility='public' husk with no description is dark matter.
+//   5. A client re-registration (registerClient → upsertProject) never resets an owner's
+//      door: the hub row is a CACHE and the door arrives by report (ADR 0182 D5 / R08).
+//   6. The migration is IDEMPOTENT — replaying it over populated rows changes nothing.
+//
+// Real-DB integration test: self-skips without a reachable Postgres; in run-unit-tests.js's
+// INTEGRATION set so the default DB-free lane never runs it.
+//
+// Run:  DATABASE_URL=... node tests/project_visibility_db.mjs
+
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { strict as assert } from 'node:assert';
+const require = createRequire(import.meta.url);
+const { Pool } = require('pg');
+const pi = require('../modules/platform-identity/platform-identity.js');
+
+const here = dirname(fileURLToPath(import.meta.url));
+const MIG_DIR = join(here, '..', 'modules', 'platform-identity', 'migrations');
+const migrationSql = (f) => readFileSync(join(MIG_DIR, f), 'utf8');
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`project_visibility_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+// Fixture origins carry the task id so a shared DB can never collide with real rows.
+const LEGACY = 'https://legacy-1002323.test';
+const HUSK = 'https://husk-1002323.test';
+const FULL = 'https://full-1002323.test';
+const ALL = [LEGACY, HUSK, FULL];
+
+const q = (sql, params) => pool.query(sql, params);
+const cleanup = async () => {
+  await q(`DELETE FROM platform_identity_projects WHERE origin = ANY($1::text[])`, [ALL]).catch(() => {});
+  await q(`DELETE FROM platform_identity_sso_clients WHERE origin = ANY($1::text[])`, [ALL]).catch(() => {});
+};
+
+let pass = 0;
+const ok = (cond, msg) => { assert.ok(cond, msg); pass++; console.log(`  ok - ${msg}`); };
+const rowOf = async (origin) => (await q(
+  `SELECT id, origin, name, tagline, description, visibility, status, featured
+     FROM platform_identity_projects WHERE origin = $1`, [origin],
+)).rows[0];
+
+try {
+  // The table as it stood BEFORE this task, so the backfill has something to act on.
+  await q(migrationSql('platform_identity_001_tables.sql'));
+  await q(migrationSql('platform_identity_004_projects.sql'));
+  await q(migrationSql('platform_identity_006_project_type.sql'));
+  await cleanup();
+
+  // ---------------------------------------------------------------------------
+  // 1. The backfill: a pre-migration row keeps today's behaviour.
+  // ---------------------------------------------------------------------------
+  await q(
+    `INSERT INTO platform_identity_projects (origin, name, tagline, featured)
+     VALUES ($1, 'Legacy', 'a card one-liner', true)`, [LEGACY],
+  );
+  await q(migrationSql('platform_identity_011_project_visibility.sql'));
+
+  const legacy = await rowOf(LEGACY);
+  ok(legacy.visibility === 'public', 'the backfill IS the DEFAULT: a pre-migration row lands visibility=public');
+  ok(legacy.description === null, 'description is NOT seeded from tagline (ADR 0182 D4) — the card cannot publish the project');
+  ok(legacy.tagline === 'a card one-liner', 'the existing tagline is untouched');
+  ok(legacy.featured === true && legacy.status === 'active', 'nothing else about the row moved');
+
+  // ---------------------------------------------------------------------------
+  // 2. The CHECK refuses a stored fourth state.
+  // ---------------------------------------------------------------------------
+  for (const forbidden of ['unlisted', 'dark-matter', 'published', '']) {
+    let refused = false;
+    try {
+      await q(`UPDATE platform_identity_projects SET visibility = $2 WHERE origin = $1`, [LEGACY, forbidden]);
+    } catch (e) {
+      refused = e.code === '23514'; // check_violation
+    }
+    ok(refused, `the DB CHECK refuses visibility='${forbidden}' — there is no stored fourth state`);
+  }
+  for (const allowed of ['public', 'private', 'stealth']) {
+    await q(`UPDATE platform_identity_projects SET visibility = $2 WHERE origin = $1`, [LEGACY, allowed]);
+    ok((await rowOf(LEGACY)).visibility === allowed, `the DB accepts the door value '${allowed}'`);
+  }
+  await q(`UPDATE platform_identity_projects SET visibility = 'public' WHERE origin = $1`, [LEGACY]);
+
+  // ---------------------------------------------------------------------------
+  // 3 + 4. The derived gate: SQL and JS agree, and `featured` no longer answers it.
+  // ---------------------------------------------------------------------------
+  await pi.upsertProject({ origin: HUSK, name: 'Husk' }, { pool });
+  await pi.upsertProject({ origin: FULL, name: 'Full', description: 'A weather simulation.' }, { pool });
+  await q(`UPDATE platform_identity_projects SET featured = true WHERE origin = ANY($1::text[])`, [[HUSK, FULL]]);
+
+  const verdicts = (await q(
+    `SELECT origin, name, description, ${pi.publishableSql()} AS publishable
+       FROM platform_identity_projects WHERE origin = ANY($1::text[]) ORDER BY origin`,
+    [[HUSK, FULL, LEGACY]],
+  )).rows;
+  for (const row of verdicts) {
+    const js = pi.projectPublishability(row);
+    ok(row.publishable === js.publishable,
+      `SQL and JS agree on ${row.origin} (publishable=${row.publishable}) — the feed and the refusal cannot drift`);
+  }
+  const husk = verdicts.find((r) => r.origin === HUSK);
+  ok(husk.publishable === false, 'a featured, active, visibility=public project with no description is DARK MATTER');
+  ok(pi.projectPublishability(husk).missing.join() === 'description', 'and the gate NAMES the missing field, never merely refuses');
+  ok(verdicts.find((r) => r.origin === FULL).publishable === true, 'name + description alone clears the bar — the gate is identity only');
+
+  // A whitespace-only description is not an identity, in SQL too (btrim, not NULL-checks).
+  await q(`UPDATE platform_identity_projects SET description = '   ' WHERE origin = $1`, [FULL]);
+  const blank = (await q(
+    `SELECT ${pi.publishableSql()} AS publishable FROM platform_identity_projects WHERE origin = $1`, [FULL],
+  )).rows[0];
+  ok(blank.publishable === false, 'a whitespace-only description does not clear the bar in SQL either');
+  await q(`UPDATE platform_identity_projects SET description = 'A weather simulation.' WHERE origin = $1`, [FULL]);
+
+  // The aliased form is the one R06 will use across a join — prove it parses and agrees.
+  const joined = (await q(
+    `SELECT p.origin, ${pi.publishableSql('p')} AS publishable
+       FROM platform_identity_projects p WHERE p.origin = $1`, [FULL],
+  )).rows[0];
+  ok(joined.publishable === true, 'publishableSql(alias) is valid SQL in a joined query and agrees');
+
+  // ---------------------------------------------------------------------------
+  // 5. The hub row is a CACHE — no write path here resets an owner's door.
+  // ---------------------------------------------------------------------------
+  await q(`UPDATE platform_identity_projects SET visibility = 'stealth' WHERE origin = $1`, [FULL]);
+  await pi.registerClient(
+    { clientId: `c-1002323-${Date.now()}`, secret: 'z'.repeat(64), name: 'Full', redirectUris: [], origin: FULL },
+    { pool },
+  );
+  ok((await rowOf(FULL)).visibility === 'stealth',
+    'a client re-registration does not reset the door to public (ADR 0182 D5 — the door arrives by report, R08)');
+  await pi.upsertProject({ origin: FULL, name: 'Full renamed' }, { pool });
+  const afterUpsert = await rowOf(FULL);
+  ok(afterUpsert.visibility === 'stealth', 'nor does a descriptionless catalog upsert');
+  ok(afterUpsert.description === 'A weather simulation.', 'nor does it erase the description (COALESCE-preserved)');
+
+  // A stealth project is a NORMAL row in the curation list — all three doors are visible.
+  const listed = (await pi.listAllProjects({ pool })).find((p) => p.origin === FULL);
+  ok(listed && listed.visibility === 'stealth' && listed.publishable === true,
+    'listAllProjects carries the stored door and the derived verdict together');
+
+  // ---------------------------------------------------------------------------
+  // 6. Idempotent replay over populated rows.
+  // ---------------------------------------------------------------------------
+  await q(migrationSql('platform_identity_011_project_visibility.sql'));
+  const replayed = await rowOf(FULL);
+  ok(replayed.visibility === 'stealth' && replayed.description === 'A weather simulation.',
+    'replaying migration 011 over populated rows changes nothing');
+
+  console.log(`\nproject_visibility_db: ${pass} assertions passed`);
+} finally {
+  await cleanup();
+  await pool.end().catch(() => {});
+}