@bongos/core 1.19.508 → 1.19.509

package/docs/module-api-changelog.md

@@ -1453,5 +1453,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.506 with no explicit bump. run 33788726591. (task 1002620)
   1.19.508 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.507 with no explicit bump. run 33790206682. (task 1002620)
+  1.19.509 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.508 with no explicit bump. run 33790542026. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/platform-identity/module.json

@@ -14,6 +14,6 @@
     "migrations": true,
     "pollers": ["code-sweep"]
   },
-  "provides": ["platform-identity.hub"],
+  "provides": ["platform-identity.hub", "project.publishGate"],
   "consumes": []
 }

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

@@ -300,38 +300,18 @@ const PROJECT_TEMPLATE_WALK = ['blob-tint', 'pair-gold-wash', 'bead-obsidian-pla
 // `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, '')) <> '')`;
-}
+// The publish gate — the derived "is this project on the map at all" bar — lives in
+// its own file (ADR 0182 D4; the account-visibility.js precedent). Every symbol is
+// re-exported below, so this module's public surface is exactly what it was before
+// the split and no caller has to know about it.
+const {
+  PUBLISH_GATE_FIELDS,
+  projectPublishability,
+  projectIsPublishable,
+  publishableSql,
+  missingPhrase,
+  publishGatePort,
+} = require('./publish-gate');
 
 // 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.
@@ -412,14 +392,26 @@ async function listAllProjects({ pool = defaultPool } = {}) {
   return rows.map((r) => ({ ...r, missing: projectPublishability(r).missing }));
 }
 
-// Archon-only: flip the Explore feature flag on a catalog row.
+// Archon-only: flip the Explore feature flag — BOUNDED BY THE PUBLISH GATE (ADR 0182
+// D3, task 1002335). Featuring may rank among projects ALREADY on the map, never put
+// one there. The bound rides the UPDATE's own WHERE, not a read-then-write, so a
+// description cleared mid-flight cannot slip a husk on; un-featuring is never blocked,
+// since an already-featured husk must stay removable. Answers a VERDICT rather than a
+// row — { project } | { blocked, missing } | { notFound } — because a bare null
+// collapsed "the gate refused" into "no such row", and a curator is owed each.
 async function setProjectFeatured(id, featured, { pool = defaultPool } = {}) {
+  const on = !!featured;
   const { rows } = await pool.query(
     `UPDATE platform_identity_projects SET featured = $2, updated_at = now()
-      WHERE id = $1 RETURNING id, origin, name, featured, status`,
-    [id, !!featured],
+      WHERE id = $1 AND ($2 = false OR ${publishableSql()})
+      RETURNING id, origin, name, featured, status`,
+    [id, on],
   );
-  return rows[0] || null;
+  if (rows[0]) return { project: rows[0] };
+  // Re-read only to tell the two failures apart — and, when it was the gate, to name
+  // the identity field that is still missing (D4: never merely refuse).
+  const project = await getProject(id, { pool });
+  return project ? { blocked: true, missing: project.missing } : { notFound: true };
 }
 
 // -------------------------------------------------------------------------
@@ -1435,6 +1427,8 @@ module.exports = {
   projectPublishability,
   projectIsPublishable,
   publishableSql,
+  missingPhrase,
+  publishGatePort,
   upsertProject,
   PROJECT_TYPES,
   PROJECT_TEMPLATES,

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

@@ -0,0 +1,103 @@
+// modules/platform-identity/publish-gate.js — THE project publish gate, published
+// in all three forms it is asked in, so no two of them can drift (ADR 0182 D4; the
+// account-visibility.js precedent, which took this file's shape for the same reason).
+//
+// WHAT IT ANSWERS: "is this project on the public map at all?" — and, when the answer
+// is no, WHICH identity field is absent. The bar is IDENTITY ONLY: a `name` and a
+// `description`. Not tagline, art, modules, governance, or a completed interview. It
+// exists to keep empty husks off the map, never to enforce completeness — a higher bar
+// would make skipping the optional project-detail step (task 1002334) a dead end
+// rather than the supported default the goal explicitly wants.
+//
+// "Dark matter" — off the map and un-joinable — is the ABSENCE of a met bar, derived
+// here and never stored. A stored fourth visibility value would compete with `private`
+// and give one question two sources of truth that can drift apart (ADR 0182 D1).
+//
+// THE THREE FORMS, and why they live together:
+//   • projectPublishability(row) — the verdict + `missing`, for JS callers
+//   • publishableSql(alias)      — the identical predicate as SQL, for the feed
+//   • publishGatePort            — the kernel seam port, for another module
+// A caller that reached only one of these could not have drifted; a caller that
+// re-implements a two-field rule inevitably does. That is the whole point of the file.
+//
+// WHY ITS OWN FILE. Same reason account-visibility.js is: platform-identity.js sits at
+// the file-size ratchet (scripts/gds/fitness-ratchets.js), and R16 (task 1002335) added
+// the port + the phrase. platform-identity.js re-exports every symbol here, so the
+// module's public surface is unchanged and no caller has to know about the split.
+//
+// WHAT IT IS NOT. Not the join door: `visibility ∈ (public|private|stealth)` is a
+// stored, owner-set policy and all three of its values are VISIBLE (ADR 0182 D2). Not
+// curation: `featured` may rank among projects already on the map, never put one there
+// (D3) — setProjectFeatured enforces that bound with publishableSql(). Not authority.
+'use strict';
+
+// The two fields, and only these two (ADR 0182 D4, owner interview on R16).
+const PUBLISH_GATE_FIELDS = Object.freeze(['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, '')) <> '')`;
+}
+
+// What is missing, as a PHRASE, so every surface that refuses says it the same way
+// (task 1002335). ADR 0182 D4 requires the gate to NAME what is absent, and a list
+// rendered ad hoc at each call site is how two surfaces end up telling one owner two
+// different stories about one rule. ['description'] → "no description";
+// ['name','description'] → "no name and no description". PURE.
+function missingPhrase(missing) {
+  const list = (missing || []).filter(Boolean);
+  if (!list.length) return '';
+  if (list.length === 1) return `no ${list[0]}`;
+  return `no ${list.slice(0, -1).join(', no ')} and no ${list[list.length - 1]}`;
+}
+
+// The gate as a KERNEL SEAM PORT — `project.publishGate` (R16, task 1002335),
+// registered by routes/projects.js and declared in module.json.
+//
+// The module one-way rule (ADR 0083) forbids `provisioning` from importing this file,
+// and provisioning is the plane an owner actually stands on BEFORE their project is
+// ever catalogued here — so without a port it would have to keep its own copy of the
+// rule, which is exactly the drift publishableSql() exists to prevent. One definition,
+// reached through the kernel switchboard.
+//
+// `evaluate` is deliberately tolerant of a FOREIGN row shape: a consumer maps its own
+// columns onto { name, description } — provisioning's `slug` IS its project's name —
+// so the gate never learns another module's schema. `fields` is published so a consumer
+// can render the bar without hardcoding it.
+const publishGatePort = Object.freeze({
+  fields: PUBLISH_GATE_FIELDS,
+  evaluate: (project) => projectPublishability(project),
+  missingPhrase,
+});
+
+module.exports = {
+  PUBLISH_GATE_FIELDS,
+  projectPublishability,
+  projectIsPublishable,
+  publishableSql,
+  missingPhrase,
+  publishGatePort,
+};

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

@@ -24,7 +24,23 @@ function hostOfOrigin(origin) {
   try { return new URL(String(origin)).hostname.replace(/^www\./, '').toLowerCase(); } catch { return ''; }
 }
 
+// Register this module's publish-gate seam (R16, task 1002335; the
+// registerProvisioningSeams precedent). Idempotent — the loader calls the factory
+// once at boot, but tests instantiate the router repeatedly, and a port is
+// single-provider so a second registration throws.
+//
+//   • PROVIDES port `project.publishGate` → { fields, evaluate(project) }.
+//     Lets provisioning — the plane an owner stands on before their project is
+//     catalogued here — ask THIS module's gate whether a project is on the map,
+//     without importing it (the ADR 0083 one-way rule) and without keeping a
+//     second copy of the rule that could drift from publishableSql().
+function registerPublishGateSeam() {
+  if (api.hasProvider('project.publishGate')) return;
+  api.registerProvider('project.publishGate', pi.publishGatePort);
+}
+
 module.exports = function projectsRoutes() {
+  registerPublishGateSeam();
   const router = express.Router();
 
   // rank: metic+archon — the full curation list (includes unfeatured + owner attribution).
@@ -99,15 +115,26 @@ module.exports = function projectsRoutes() {
     }
   });
 
-  // rank: archon — the feature / unfeature control (the ADR 0141 §5 curation gate).
+  // rank: archon — the feature / unfeature control (the ADR 0141 §5 curation gate),
+  // BOUNDED BY THE PUBLISH GATE (ADR 0182 D3, task 1002335). Featuring ranks among
+  // projects already on the map; it is not a way ONTO it, so featuring a dark-matter
+  // row is refused — and the refusal names the identity field that is missing rather
+  // than merely saying no (D4). Un-featuring is never refused.
   router.patch('/projects/:id/featured', requireBuilder, requirePermission('project.curate'), async (req, res) => {
     const id = parseId(req, res, { code: 'bad_project_id', positiveInt: true });
     if (id === null) return;
     if (validateOrRespond(req, res, { featured: { required: true, type: 'boolean' } })) return;
     try {
-      const project = await pi.setProjectFeatured(id, req.body.featured, { pool });
-      if (!project) return res.fail('project_not_found', 404);
-      res.json({ project });
+      const out = await pi.setProjectFeatured(id, req.body.featured, { pool });
+      if (out.notFound) return res.fail('project_not_found', 404);
+      if (out.blocked) {
+        return res.fail('not_publishable', {
+          status: 409,
+          message: `This project is not on the public map yet, so it cannot be featured — it still has ${pi.missingPhrase(out.missing)}. Featuring promotes a project that is already published; it cannot publish one.`,
+          details: { missing: out.missing },
+        });
+      }
+      res.json({ project: out.project });
     } catch (err) {
       console.error('[platform-identity] PATCH /projects/:id/featured', err);
       res.fail('feature_toggle_failed', { status: 500, message: 'internal error' });

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

@@ -286,12 +286,17 @@ await ta('listFeaturedProjects returns a PUBLIC projection (featured+active only
   assert.doesNotMatch(sel, /updated_at/, 'updated_at is curation noise — never projected');
 });
 
-await ta('setProjectFeatured flips the flag (Archon curation)', async () => {
+await ta('setProjectFeatured flips the flag (Archon curation) — and answers with a VERDICT', async () => {
   const pool = mockPool([{ rows: [{ id: '1', featured: true }] }]);
   const out = await P.setProjectFeatured(1, true, { pool });
-  assert.equal(out.featured, true);
+  assert.equal(out.project.featured, true);
   assert.match(pool.calls[0].text, /UPDATE platform_identity_projects SET featured = \$2/);
   assert.deepEqual(pool.calls[0].params, [1, true]);
+  // Bounded by the publish gate since task 1002335 (ADR 0182 D3): featuring may
+  // promote among projects already on the map, never put one there. The full
+  // refusal contract — blocked vs notFound, and the un-feature escape — lives in
+  // tests/publish_gate.mjs.
+  assert.ok(pool.calls[0].text.includes(P.publishableSql()), 'the gate rides in the WHERE');
 });
 
 console.log('\nproject visibility: the stored door + the DERIVED publish gate (BV1.R04, ADR 0182):');

package/modules/provisioning/routes/provisioning.js

@@ -262,12 +262,48 @@ function registerProvisioningSeams() {
   api.registerProvider('provisioning.projectPlanets', (hosts) => provisioning.planetChoicesForHosts(pool, hosts));
 }
 
+// Is this project on the public map, and if not, what is it still missing?
+// (R16, task 1002335 — the surface R15 pointed at by name.)
+//
+// The rule itself is ADR 0182 D4's and lives in `platform-identity`; this module
+// reaches it through the kernel port `project.publishGate` rather than keeping a
+// copy, because a second copy of a two-field rule is exactly the drift that
+// module's single SQL definition exists to prevent (ADR 0083 forbids the import).
+//
+// resolveOptional, not resolve, and NOT declared in `consumes` (the lifecycle →
+// reward precedent): platform-identity is hub-only (`default: false`), and the
+// public map is a HUB concept — an instance running provisioning without it has no
+// map to be on. The honest answer there is "no verdict" (null), never a locally
+// invented one, and every surface below hides the section rather than guessing.
+//
+// The MAPPING is the one part this module owns: an instance's `slug` IS its
+// project's name on this plane — there is no `name` column and a slug can never be
+// empty — so the only identity field this plane can be missing is the description
+// the optional About step (task 1002334) asks for.
+function publishVerdict(row) {
+  const gate = api.resolveOptional('project.publishGate');
+  if (!gate || !row) return null;
+  const { publishable, missing } = gate.evaluate({ name: row.slug, description: row.description });
+  // The phrase travels with the verdict so the owner-facing surfaces and the hub's
+  // own refusal cannot word one rule two different ways.
+  return { publishable, missing, missing_phrase: gate.missingPhrase(missing) };
+}
+
+// The owner-facing projection every instance read returns: the allow-listed row
+// plus the derived publish verdict. One helper so a new read cannot ship the row
+// without the verdict and leave an owner unable to see why they are dark matter.
+function ownerInstance(row) {
+  return { ...provisioning.publicInstance(row), publish: publishVerdict(row) };
+}
+
 // Project an instance row for the fleet view — the owner identity + the same
-// allow-listed public projection an owner sees.
+// projection an owner sees, verdict included: "why is this project not on the map"
+// is a support question, and an operator who has to re-derive the answer will
+// eventually derive a different one.
 function fleetInstance(row) {
   return {
     owner: { id: row.owner_builder_id, github_login: row.github_login, display_name: row.display_name, rank: row.rank },
-    ...provisioning.publicInstance(row),
+    ...ownerInstance(row),
   };
 }
 
@@ -575,7 +611,7 @@ module.exports = function provisioningRoutes() {
         };
       }
       res.status(created ? 201 : 200).json({
-        instance: provisioning.publicInstance(instance),
+        instance: ownerInstance(instance),
         open_intent: intent ? { action: intent.action, state: intent.state } : null,
         queued: intentCreated,
         created,
@@ -647,7 +683,7 @@ module.exports = function provisioningRoutes() {
       for (const row of rows) {
         const open = await provisioning.getOpenIntent(pool, row.id);
         instances.push({
-          ...provisioning.publicInstance(row),
+          ...ownerInstance(row),
           open_intent: open ? { action: open.action, state: open.state } : null,
         });
       }
@@ -684,7 +720,7 @@ module.exports = function provisioningRoutes() {
       // panel recovers it from server state after a reload — not from sessionStorage.
       const manifest = await provisioning.getLatestOAuthManifestForInstance(pool, id);
       res.json({
-        instance: provisioning.publicInstance(inst),
+        instance: ownerInstance(inst),
         open_intent: open ? { action: open.action, state: open.state } : null,
         github_app: provisioning.publicGithubApp(manifest),
       });
@@ -746,6 +782,11 @@ module.exports = function provisioningRoutes() {
         description: updated.description || null,
         detail: provisioning.projectDetail(updated),
         options: provisioning.PROJECT_DETAIL_VOCAB,
+        // The whole point of the step, answered in the same breath (R16, task
+        // 1002335): an owner who just wrote a description learns HERE that the
+        // project is now on the map, and one who cleared it learns it just left.
+        // Re-deriving it from a follow-up GET would let the two answers disagree.
+        publish: publishVerdict(updated),
       });
     } catch (err) {
       log.error('[provisioning] PATCH /provisioning/instances/:id/detail', err);
@@ -1342,3 +1383,8 @@ module.exports = function provisioningRoutes() {
 
 // Re-export the seam registrar for tests that assert the port is registered.
 module.exports.registerProvisioningSeams = registerProvisioningSeams;
+// …and the publish-gate projection (task 1002335), so a test can pin the one
+// thing this module owns about the gate — the slug-is-the-name mapping — and
+// prove it answers with the REAL port rather than a copy of the rule.
+module.exports.publishVerdict = publishVerdict;
+module.exports.ownerInstance = ownerInstance;

package/modules/public-landing/public/projects.html

@@ -54,6 +54,22 @@
    cosmos vocabulary, scoped to #view-manage there (task 1003345) ── */
 #view-manage .empty{text-align:left;}
 #view-manage .empty p{margin-bottom:0;}
+/* the publish gate's one field (task 1002335). The description is prose, so it
+   is a textarea — and it wears a skin scoped to THIS view, because the wizard's
+   field rules are scoped to #view-new and borrowing them would couple the two.
+   Same grammar as those fields, though: one bottom hairline that takes ink on
+   focus, never a box — the manage page is cosmos vocabulary throughout. */
+#view-manage textarea{
+  width:100%;font-family:var(--font-body);font-size:15.5px;font-weight:400;color:var(--ink);line-height:1.5;
+  background:none;border:0;border-bottom:1px solid var(--rule);border-radius:0;padding:8px 0;outline:none;
+  resize:vertical;min-height:64px;display:block;
+  transition:border-color .15s ease;
+}
+#view-manage textarea::placeholder{color:var(--ink-faint);font-weight:400;}
+#view-manage textarea:focus{border-bottom-color:var(--ink);box-shadow:none;}
+/* the verdict leads the card — it is the answer, not fine print */
+#view-manage .pubVerdict{font-size:15px;font-weight:500;line-height:1.55;color:var(--ink-soft);margin-bottom:14px;}
+#view-manage .pubVerdict b{font-weight:700;color:var(--ink);}
 
 /* The bongo pair on the New-project view. Component-scoped custom properties,
    never :root (C1). The drum head is SKIN — using --bg-card would turn it black
@@ -690,6 +706,29 @@ summary{min-height:24px;padding:3px 0;}
         <div class="actions" id="mActs" hidden></div>
       </div>
 
+      <!-- live since task 1002335 (BV1.R16): the PUBLISH GATE. A project is on
+           the public map if and only if it has a name and a description — that
+           is the whole bar (ADR 0182 D4), identity only, deliberately not a
+           completeness check. Until it is met the project is DARK MATTER: off
+           the map and un-joinable. This card is the "name what is missing" half
+           of that decision, because a project that cannot be published and is
+           not told why is indistinguishable from a broken one.
+           The verdict rendered here is the SERVER's (instance.publish, derived
+           from the one gate definition platform-identity owns and hands over
+           the kernel seam) — never re-derived in the browser, which is how two
+           surfaces start telling one owner two different stories about one rule.
+           Hidden outright when the server sent no verdict: a platform with no
+           public map has nothing to say here, and inventing a local rule to
+           fill the silence is exactly what the seam exists to prevent. -->
+      <div class="card mSec" id="mPublish" hidden>
+        <h2>On the public map</h2>
+        <div id="mPub"><p class="finePrint">Reading the project…</p></div>
+        <details class="finePrint" id="mPubWhat">
+          <summary>What puts a project on the map</summary>
+          <p>Two things, and only two: a name — this project already has one — and a description of what it is. Modules, artwork, a finished setup interview: none of them are required, because the bar is there to keep empty shells off the map, not to make you finish anything. Until it is met the project is not listed publicly and nobody can ask to join it; the project itself runs exactly the same either way. Adding a description puts it on the map, and clearing one takes it back off.</p>
+        </details>
+      </div>
+
       <!-- its address (task 1003355): the bring-your-own-domain control, moved
            off the list row when a row shrank to view and manage. Its home is
            here, under the ledger's address fact. The section hides itself where
@@ -4577,6 +4616,22 @@ summary{min-height:24px;padding:3px 0;}
         : '<a href="?view=manage&id=' + esc(String(inst.id)) + '" data-manage="' + esc(String(inst.id)) + '">Give it an address on its own page</a>.');
   }
 
+  /* the publish gate on the LIST card (task 1002335, BV1.R16). Only the refusal
+     earns a line here: being on the map is the expected state, and a card that
+     announces it for every healthy project is noise — while a project that is
+     invisible and never told why reads as broken (ADR 0182 D4). It names what is
+     missing in the server's own words and points at the one page that fixes it.
+     A torn-down project is silent: nothing about the public map is its problem
+     while it is off. */
+  function publishRow(inst) {
+    var v = inst && inst.publish;
+    if (!v || v.publishable) return '';
+    if (inst.status === 'torn_down' || inst.status === 'tearing_down') return '';
+    return 'Not on the public map yet — it has ' + esc(v.missing_phrase || 'no description') +
+      '. <a href="?view=manage&id=' + esc(String(inst.id)) + '" data-manage="' + esc(String(inst.id)) +
+      '">Say what it is</a> and it goes on.';
+  }
+
   function renderCard(inst) {
     /* iid is for MARKUP interpolation only (esc() = HTML escape); the DOM
        lookup goes through liFor(), which CSS-escapes — the two escapes are
@@ -4598,6 +4653,8 @@ summary{min-height:24px;padding:3px 0;}
       (meta.length ? '<div class="projMeta">' + meta.map(function (m) { return '<span>' + m + '</span>'; }).join('') + '</div>' : '');
     var addr = addressRow(inst);
     if (addr) body += '<div class="addr">' + addr + '</div>';
+    var pub = publishRow(inst);
+    if (pub) body += '<div class="projMsg">' + pub + '</div>';
     if ((inst.status === 'error' || inst.error_note) && !inst.open_intent) {
       /* once a retry is queued the strip tells the story — the stale error
          paragraph would just contradict it (owner walk, 2026-08-12). Also
@@ -5111,6 +5168,11 @@ summary{min-height:24px;padding:3px 0;}
            the GitHub read: entry + tab return, never the in-flight tick */
         if (!keepRepo) loadVisibility(inst);
         if (!keepRepo) loadJoinability(inst);
+        /* the publish gate (task 1002335) needs no second read — the verdict
+           rode in on the instance itself. It sits behind the same keepRepo
+           guard because its card holds a textarea the in-flight tick must
+           never repaint out from under a typing owner. */
+        if (!keepRepo) renderPublish(inst);
       })
       .catch(function (err) {
         var m = String(err && err.message);
@@ -5256,6 +5318,101 @@ summary{min-height:24px;padding:3px 0;}
     if (t.hasAttribute('data-repo-public-no')) { if (manageRepo) renderRepoVis(manageRepo); }
   });
 
+  /* ── on the public map (task 1002335, BV1.R16): the publish gate ──────────
+     The verdict is the SERVER's — instance.publish, derived from the ONE gate
+     definition platform-identity owns and publishes over the kernel seam (ADR
+     0182 D4). This page renders it and offers the one identity field that can
+     be missing; it never re-derives the rule, because a browser-side copy is
+     how the card and the server start disagreeing about whether a project is
+     published. No verdict at all (an instance whose platform runs no public
+     map) hides the card rather than guessing.
+
+     Rendered on ENTRY and after a save — deliberately NOT from renderManage,
+     which the fetch-free minute tick and the in-flight watch both call: this
+     card holds a textarea, and a repaint mid-sentence would eat what the owner
+     is typing. Nothing the server does in the background changes the answer
+     anyway; only this form does. ── */
+
+  function pubMsg(html) { $('mPub').innerHTML = html; }
+
+  function renderPublish(inst) {
+    var v = inst && inst.publish;
+    if (!v) { $('mPublish').hidden = true; return; }
+    $('mPublish').hidden = false;
+    var on = !!v.publishable;
+    /* the refusal NAMES what is absent, in the server's own words (ADR 0182
+       D4) — a project told only "no" is indistinguishable from a broken one */
+    var verdict = on
+      ? '<b>' + esc(inst.slug) + ' is on the public map.</b> People can find it and ask to join.'
+      : '<b>' + esc(inst.slug) + ' is not on the public map yet</b> — it has ' +
+        esc(v.missing_phrase || 'no description') +
+        '. Nobody can find it there or ask to join until it does.';
+    pubMsg('<p class="pubVerdict">' + verdict + '</p>' +
+      '<label class="wizField" for="mPubDesc"><span>What is this project?' +
+      ' <small>' + (on ? 'Change it any time.' : 'A sentence or two is plenty.') + '</small></span>' +
+      '<textarea id="mPubDesc" maxlength="600" rows="3" placeholder="A weather simulator you can play with in the browser."></textarea></label>' +
+      '<div class="actions"><button type="button" class="btn small" data-pub-save>' +
+      (on ? 'Save' : 'Put it on the map') + '</button></div>' +
+      '<div class="projMsg" id="mPubMsg" role="status" aria-live="polite"></div>');
+    /* the owner's own prose is set as a PROPERTY, never interpolated into the
+       markup above — what someone typed about their project is not HTML */
+    $('mPubDesc').value = inst.description || '';
+  }
+
+  /* Saving sends the description and takes the server's verdict WHOLE. An empty
+     box is a real answer, not a no-op: it clears the description and the project
+     leaves the map — the honest consequence of deleting half the identity gate,
+     which is why the receipt says so instead of just "Saved." */
+  function doPubSave() {
+    var ta = $('mPubDesc');
+    if (!manageInst || !ta) return;
+    var box = $('mPubMsg');
+    var btn = document.querySelector('#mPub [data-pub-save]');
+    if (btn) btn.disabled = true;
+    box.className = 'projMsg'; box.textContent = 'Saving…';
+    var asked = manageId; /* a stale answer must never repaint a newer project */
+    fetch(API + '/provisioning/instances/' + encodeURIComponent(manageId) + '/detail', {
+      method: 'PATCH', credentials: 'same-origin', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ description: ta.value })
+    }).then(function (res) {
+      return jsonOrEmpty(res).then(function (data) {
+        if (asked !== manageId) return;
+        if (res.status === 401) { box.className = 'projMsg err'; box.innerHTML = signInAgain(); return; }
+        if (!res.ok) {
+          var e = apiError(data, res.status);
+          box.className = 'projMsg err';
+          box.textContent = e.message || 'The description could not be saved — try again in a moment.';
+          return;
+        }
+        manageInst.description = data.description || null;
+        manageInst.publish = data.publish || manageInst.publish;
+        renderPublish(manageInst);
+        var m = $('mPubMsg'); /* the re-render replaced the box this closure held */
+        m.className = 'projMsg ok';
+        m.textContent = (manageInst.publish && manageInst.publish.publishable)
+          ? 'Saved — it’s on the public map.'
+          : 'Saved. With no description it stays off the public map.';
+        /* the list card carries the same verdict, and the owner may go back */
+        if (byId[manageInst.id]) {
+          byId[manageInst.id].description = manageInst.description;
+          byId[manageInst.id].publish = manageInst.publish;
+        }
+      });
+    }).catch(function () {
+      if (asked !== manageId) return;
+      var b = $('mPubMsg');
+      if (b) { b.className = 'projMsg err'; b.textContent = 'Couldn’t reach the platform — check your connection and try again.'; }
+    }).then(function () {
+      var b = document.querySelector('#mPub [data-pub-save]');
+      if (b) b.disabled = false;
+    });
+  }
+
+  $('mPub').addEventListener('click', function (ev) {
+    var t = ev.target.closest && ev.target.closest('button');
+    if (t && t.hasAttribute('data-pub-save')) doPubSave();
+  });
+
   /* ── who can see it (task 1003043): the platform-visibility toggle. Two
      reads, kept apart on purpose: the CHOICE comes from the platform's own
      settings row (what the owner asked for), and the line under it reads what

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.508",
+  "version": "1.19.509",
   "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.508'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.509'; // 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');