@bongos/core 1.19.564 → 1.19.565

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 357 endpoints across 58 route files.
+> **Generated from the live route files** — the route file is authoritative. 358 endpoints across 58 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -449,13 +449,14 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/project-settings` | `metic+archon` | — | GET /project-settings — all five rows in ONE read. |
 | PATCH | `/api/bongos/project-settings/rot-days` | `metic+archon` | `days` | PATCH /project-settings/rot-days — body { days }. |
 
-## `projects` (5)
+## `projects` (6)
 
 | 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`, `description`, `art_url`, `type`, `template` | 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), BOUNDED BY THE PUBLISH GATE (ADR 0182 D3, task 1002335). |
+| PATCH | `/api/bongos/projects/:id/status` | `metic+archon` | `status` | THE TAKEDOWN LEVER (R08, task 1002327; ADR 0252 §5.1). |
 | GET | `/api/bongos/projects/featured` | `public` | — | the public map of projects; no auth by design. |
 | POST | `/api/bongos/projects/invite` | `metic+archon` | `client_id`, `github_login` | own-or-metic in effect: invite a builder into a project (ADR 0141 §5, task #1002115), called by a `project.curate` holder OR the project'… |
 

package/docs/module-api-changelog.md

@@ -1577,5 +1577,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.562 with no explicit bump. run 34049959536. (task 1002620)
   1.19.564 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.563 with no explicit bump. run 34052578659. (task 1002620)
+  1.19.565 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.564 with no explicit bump. run 34055981223. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -646,6 +646,8 @@ function createClient(opts = {}) {
       postProjects: (args) => request("POST", "/projects", { hasBody: true }, args),
       // PATCH /projects/{id}/featured — rank: metic+archon — PATCH /projects/:id/featured
       patchProjectsIdFeatured: (args) => request("PATCH", "/projects/{id}/featured", { hasBody: true }, args),
+      // PATCH /projects/{id}/status — rank: metic+archon — PATCH /projects/:id/status
+      patchProjectsIdStatus: (args) => request("PATCH", "/projects/{id}/status", { hasBody: true }, args),
       // GET /projects/featured — rank: public — GET /projects/featured
       getProjectsFeatured: (args) => request("GET", "/projects/featured", { hasBody: false }, args),
       // POST /projects/invite — rank: metic+archon — POST /projects/invite

package/modules/government/catalog.js

@@ -202,7 +202,7 @@ const PERMISSIONS = [
   // anyone in a room with a stranger on its own.
   { key: 'mingle.manage', system: false, floor: 'metic', guards: 'PUT /mingle/project (the project half of mingle consent), POST /mingle/round (run a pairing round) — task 1003177, goal 1000075' },
   { key: 'project.settings.manage', system: false, floor: 'metic', guards: "PATCH /project-settings/* — the project's own live knobs (the rot timer today) and the work-category set's shape (PATCH /work-categories/:id). Metic, matching goal.create's reasoning that extending the project's vocabulary is a planning act rather than an administrative one — task 1003280, goal 1000072" },
-  { key: 'project.curate', system: false, floor: 'metic', guards: 'platform-identity: GET/POST /projects, /projects/invite, PATCH /projects/:id/featured, GET /scouting (ADR 0157, was archon)' },
+  { key: 'project.curate', system: false, floor: 'metic', guards: 'platform-identity: GET/POST /projects, /projects/invite, PATCH /projects/:id/featured, PATCH /projects/:id/status (the takedown lever — ADR 0252 §5.1), GET /scouting (ADR 0157, was archon)' },
   { key: 'override_request.decide', system: false, floor: 'metic', guards: 'GET /override-requests, POST .../:id/decide (ADR 0157, was archon)' },
   { key: 'claim.release.any', system: false, floor: 'metic', scope: 'any', resource: 'claim', guards: 'POST /claims/:id/release-on-behalf (ADR 0157, was archon)' },
   { key: 'idea.ratify', system: false, floor: 'metic', guards: 'POST /inbox/:id/ratify (ADR 0157, was archon)' },

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

@@ -0,0 +1,106 @@
+-- platform_identity_020_visibility_pull.sql — the three columns the self-hosted
+-- visibility PULL needs (BV1.R08, task 1002327; ADR 0252, corrected by ADR 0253).
+--
+-- ADR 0252 §2 makes the hub READ a self-hosted instance's already-public manifest
+-- rather than accept a pushed report. Two properties that decision needs cannot be
+-- expressed by the columns migration 011 left behind, and this migration adds them.
+--
+-- 1. THE TRI-STATE HAS NOWHERE TO LIVE. `visibility` is `NOT NULL DEFAULT 'public'`,
+--    so it cannot distinguish "reported public" from "never asked". ADR 0252 §4 is
+--    explicit that `null` (never read) ≠ `false` (read, negative) and that a project
+--    read before but unreachable now KEEPS its last state — a distinction the door
+--    column physically cannot carry. `visibility_reported_at` is the null-carrier:
+--    IS NULL means no successful read has ever happened, which is the ONLY condition
+--    under which ADR 0182 D5's fail-closed default applies. A row that answered once
+--    and is down today has a stamp, keeps its value, and stays on the map.
+--
+-- 2. "THE TWO NEVER WRITE THE SAME ROW" WAS A CONVENTION WITH NOTHING ENFORCING IT.
+--    The task body requires the pull to touch self-hosted rows only, leaving
+--    control-plane rows on the bridge's assigned value (ADR 0246). But the catalog
+--    row carries no `hosting_shape` — that column lives on `provisioning_instances`,
+--    in a module platform-identity may not import (ADR 0083's one-way rule), and
+--    opening a seam just to ask would put a cross-module read on every sweep.
+--    `visibility_source` records the provenance ON the row instead, stamped by
+--    whichever writer touched it. The pull's predicate is then a local column read:
+--    it may write a row the control plane has never claimed, and no other.
+--
+-- 3. `hidden` IS STICKY, AND AGAINST TWO WRITERS — not the one ADR 0252 §5.2 names.
+--    The ADR defends a takedown against the pull. The pull is not the writer that
+--    actually undoes takedowns today: `upsertOwnedProject` assigns `status =
+--    EXCLUDED.status` unconditionally, and the ADR 0246 bridge re-takes that
+--    projection on EVERY provisioning write, computing 'active' for any instance
+--    that is not torn down. So an Archon hides a project, its owner saves any
+--    setting, and it is back on the map — the lever is decorative for precisely the
+--    reason ADR 0252 §5.2 gives, one writer over. `status_pinned` is the latch a
+--    curator sets; both writers honour it. ADR 0253 records the correction.
+--
+-- Additive + `platform_identity_`-namespaced (ADR 0083 §5). Forward-safe: ADD COLUMN
+-- only, so the previous code release still runs against this schema — a release that
+-- has never heard of these columns keeps its current behaviour exactly, because an
+-- unpinned row and a NULL source are what every existing row backfills to.
+-- Idempotent (IF NOT EXISTS + the drop-then-add CHECK pattern from migration 006).
+
+BEGIN;
+
+-- 1. The tri-state's null. NOT backfilled to now(): every existing row genuinely has
+--    never been pulled, and claiming otherwise would assert a reading that never
+--    happened. Control-plane rows never acquire a stamp at all — they are not pulled,
+--    and `visibility_source` is what says so.
+ALTER TABLE platform_identity_projects
+  ADD COLUMN IF NOT EXISTS visibility_reported_at timestamptz;
+
+-- 2. Which writer owns this row's door. NULL = neither has claimed it yet, which is
+--    the state every pre-existing row starts in and the state the pull may write.
+ALTER TABLE platform_identity_projects
+  ADD COLUMN IF NOT EXISTS visibility_source text;
+
+ALTER TABLE platform_identity_projects DROP CONSTRAINT IF EXISTS platform_identity_projects_visibility_source_check;
+ALTER TABLE platform_identity_projects ADD CONSTRAINT platform_identity_projects_visibility_source_check
+  CHECK (visibility_source IS NULL OR visibility_source IN ('control-plane', 'pull'));
+
+-- 3. The takedown latch. DEFAULT false so every existing row is unpinned, i.e. today's
+--    behaviour unchanged: nothing is newly frozen by this migration running.
+ALTER TABLE platform_identity_projects
+  ADD COLUMN IF NOT EXISTS status_pinned boolean NOT NULL DEFAULT false;
+
+-- THE BACKFILL, AND IT IS THE SAFETY PROPERTY OF THIS MIGRATION.
+--
+-- R08 makes the feed exclude a pullable row that has never answered — ADR 0182 D5's
+-- "unreported => dark matter". Shipped without this UPDATE that predicate would empty
+-- the public map the moment it deployed, because the column it reads is brand new and
+-- therefore NULL on every row. That is not a hypothetical: ADR 0247 D4 found the exact
+-- shape live, on this table, one column over — every catalog row carried
+-- `description: null`, so a fail-closed join gate wired that day would have refused
+-- every join on the platform at once.
+--
+-- The backfill is also simply TRUE, which is why it is safe to make. Every row that
+-- exists at this moment got its door from the hub: either the ADR 0246 bridge assigned
+-- it from `provisioning_instances.settings`, or an Archon typed the row in. Neither is
+-- a pull — no instance has ever been asked, because this migration is what makes asking
+-- possible. Stamping them 'control-plane' records what already happened; it does not
+-- grant anything, and it leaves today's map exactly as it is.
+--
+-- What stays NULL is therefore precisely the new population: rows catalogued AFTER this
+-- lands that the control plane has not claimed. Those are the ones the sweep may read,
+-- and the ones D5's default is scoped to.
+UPDATE platform_identity_projects
+   SET visibility_source = 'control-plane'
+ WHERE visibility_source IS NULL;
+
+-- The pull's working set: rows the control plane has never claimed. Partial, because
+-- the sweep asks this question and no other, and the control-plane rows it excludes
+-- are the majority of the table.
+CREATE INDEX IF NOT EXISTS platform_identity_projects_pullable
+  ON platform_identity_projects (origin)
+  WHERE visibility_source IS DISTINCT FROM 'control-plane';
+
+COMMENT ON COLUMN platform_identity_projects.visibility_reported_at IS
+  'When the hub last SUCCESSFULLY read this project''s own manifest (ADR 0252 §2). NULL is load-bearing: it means no read has ever succeeded, and is the ONLY state in which ADR 0182 D5''s fail-closed "unreported => dark matter" applies. A row that answered once and is unreachable today keeps both its `visibility` and this stamp — reporting may degrade where enforcement must refuse (ADR 0226), and liveness is an overlay, never a lifecycle state (ADR 0199). Never set on a control-plane row; those are assigned, not read.';
+
+COMMENT ON COLUMN platform_identity_projects.visibility_source IS
+  'WHICH writer owns this row''s join door: ''control-plane'' (assigned by the ADR 0246 bridge from provisioning_instances.settings — authoritative) or ''pull'' (read from the instance''s own public manifest — a cached CLAIM, and only as fresh as visibility_reported_at). NULL means neither has claimed the row yet. This column is what makes "the two never write the same row" an invariant the SQL enforces rather than a convention: the pull''s predicate is `visibility_source IS DISTINCT FROM ''control-plane''`. It exists because the catalog row carries no hosting_shape and may not import the module that does (ADR 0083).';
+
+COMMENT ON COLUMN platform_identity_projects.status_pinned IS
+  'A curator has set `status` by hand (PATCH /projects/:id/status), so no automatic writer may move it. ADR 0252 §5.2 requires a retracted project that keeps reporting `public` to STAY hidden; ADR 0253 found the pull is not the writer that undoes takedowns today — upsertOwnedProject is, assigning status on every re-take of the ADR 0246 projection. Both honour this latch. Cleared only by another curated PATCH, so un-hiding is exactly as deliberate as hiding.';
+
+COMMIT;

package/modules/platform-identity/module.json

@@ -12,7 +12,7 @@
   "contributes": {
     "routes": ["sso", "projects", "my-projects", "scouting", "profile", "public-profile", "connections"],
     "migrations": true,
-    "pollers": ["code-sweep"]
+    "pollers": ["code-sweep", "visibility-pull"]
   },
   "provides": ["platform-identity.hub", "project.publishGate", "project.catalog"],
   "consumes": []

package/modules/platform-identity/pollers/visibility-pull.js

@@ -0,0 +1,99 @@
+'use strict';
+
+// modules/platform-identity/pollers/visibility-pull.js — the loader poller entry that
+// keeps self-hosted projects' join doors current (R08, task 1002327; ADR 0252 §2).
+// The loader's startModulePollers requires THIS file and calls start(deps) at boot /
+// stop() at shutdown for the ENABLED module only (the hub) — non-blocking and
+// failure-isolated, so a sweep hiccup never touches sign-in. Mirrors code-sweep.js.
+//
+// WHY A POLLER AND NOT THE FEED'S EXISTING FAN-OUT. The obvious cheap move — pull the
+// manifest alongside the four stats fetches the public feed already makes — cannot work,
+// and the reason is worth writing down because it is invisible until you try it:
+//
+//   1. THE FEED EXCLUDES EXACTLY THE ROWS THAT NEED PULLING. A pullable project that has
+//      never answered is dark matter, so `listPublicProjects` does not return it, so the
+//      enrichment never fetches it, so it never answers, so it stays dark. A read-path
+//      pull can only ever refresh projects that are ALREADY visible — which is precisely
+//      backwards from what R08 is for. It cannot bootstrap.
+//   2. STEALTH ROWS ARE SKIPPED TOO. `routes/projects.js` filters them out of enrichment
+//      on purpose (asking a stealth project's API for its builders would put identity on
+//      the wire and tell it it was being enumerated), so a project that went stealth
+//      could never be seen coming back.
+//   3. IT WOULD MAKE A DATABASE WRITE A SIDE EFFECT OF AN ANONYMOUS READ, on a route that
+//      is unauthenticated and CORS-open — and add a fifth outbound fetch to the platform's
+//      most expensive public request while doing it.
+//
+// So the sweep runs on its own clock over its own working set, and the feed keeps reading
+// the cached column exactly as it does today.
+//
+// Proof: ../../../tests/visibility_pull.mjs
+
+const api = require('../../../src/module-api');
+const visibilityPull = require('../visibility-pull');
+
+const log = api.logger('platform-identity');
+
+// Every 15 minutes. A join door is not a liveness signal — it changes when an owner
+// decides something, which is rare — so the cadence is set by how long a stale door may
+// linger, not by how fast anything moves. It is also deliberately slower than the stats
+// TTL (10 min): this sweep reaches out to every catalogued third-party instance whether
+// or not anyone is looking at the map, and being a polite client to other people's
+// servers matters more here than freshness measured in minutes.
+const SWEEP_INTERVAL_MS = 15 * 60 * 1000;
+
+// Rows per sweep. A ceiling rather than a page: at 15-minute cadence this is far above
+// any plausible catalog, and `pullableProjects` orders oldest-reading-first, so if the
+// population ever did exceed it the sweep still converges — it just takes more passes,
+// and it spends them on the stalest rows.
+const SWEEP_LIMIT = 200;
+
+// Wait before the FIRST sweep so boot is never competing with a fan-out to every
+// catalogued origin. The catalog-backfill poller's precedent.
+const FIRST_SWEEP_DELAY_MS = 60 * 1000;
+
+let timer = null;
+let firstTimer = null;
+
+async function sweepOnce(deps = {}) {
+  try {
+    const out = await visibilityPull.sweepVisibilityOnce({
+      ...(deps.pool ? { pool: deps.pool } : {}),
+      limit: SWEEP_LIMIT,
+    });
+    // One disposition line per sweep, and only when something actually moved — a
+    // quiet catalog should not write a log line every quarter hour forever.
+    if (out.updated > 0) {
+      log.info({ updated: out.updated, scanned: out.scanned }, 'visibility-pull: project door(s) updated');
+    }
+    return out;
+  } catch (err) {
+    // Best-effort: a sweep failure must never crash the process. Individual projects
+    // already fail closed inside pullOne(), so reaching here means the DB read itself
+    // failed, not that some instance was down.
+    log.error({ err: err && err.message }, 'visibility-pull sweep failed (non-fatal)');
+    return null;
+  }
+}
+
+module.exports = {
+  start: (deps = {}) => {
+    if (timer || firstTimer) return; // idempotent
+    firstTimer = setTimeout(() => {
+      firstTimer = null;
+      sweepOnce(deps);
+      timer = setInterval(() => { sweepOnce(deps); }, SWEEP_INTERVAL_MS);
+      if (timer.unref) timer.unref();
+    }, FIRST_SWEEP_DELAY_MS);
+    // unref so neither timer keeps the process alive on its own.
+    if (firstTimer.unref) firstTimer.unref();
+  },
+  stop: () => {
+    if (timer) { clearInterval(timer); timer = null; }
+    if (firstTimer) { clearTimeout(firstTimer); firstTimer = null; }
+  },
+  // exported for tests
+  sweepOnce,
+  SWEEP_INTERVAL_MS,
+  SWEEP_LIMIT,
+  FIRST_SWEEP_DELAY_MS,
+};

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

@@ -127,26 +127,83 @@ async function upsertCatalogOnlyClient(entry, { pool = defaultPool } = {}) {
 // WHERE is claim rule 2 (the owner must already match), so an origin someone else's row
 // occupies is refused rather than overwritten. Returns the row, or null when the claim
 // refused. `featured`, `tagline`, `art_url` and `template` are curation and stay untouched.
+//
+// TWO THINGS R08 CHANGED HERE (task 1002327; ADR 0253):
+//
+// 1. `status` NOW HONOURS THE PIN, and this is the takedown lever actually working.
+//    ADR 0252 §5.2 requires a retracted project to stay retracted, and defends that
+//    against the visibility pull — but the pull is not the writer that undoes takedowns.
+//    THIS one is. The ADR 0246 projection is re-taken at every provisioning write, and
+//    `catalogStatusForInstance` computes 'active' for any instance that is not torn down,
+//    so before this line an Archon could hide a project and the owner's very next
+//    settings save would put it back on the public map. The pin is set only by a curated
+//    PATCH /projects/:id/status, so what it freezes is a human decision, and only against
+//    automatic writers. Un-pinning is another curated PATCH — un-hiding stays exactly as
+//    deliberate as hiding.
+//
+//    `retireOwnedProject` deliberately does NOT honour the pin: it is a safety retraction
+//    for an address the project no longer answers on (the ADR 0181 §2 stale-orb leak), and
+//    a curator's 'active' pin must not be able to keep a dead origin drawing an orb.
+//    Narrowing is free; widening is what costs.
+//
+// 2. `visibility_source` is stamped 'control-plane'. This row's door is ASSIGNED from
+//    `provisioning_instances.settings`, so the pull must never touch it — and the stamp is
+//    what makes "the two writers never share a row" an invariant the SQL enforces rather
+//    than a convention (the catalog carries no `hosting_shape`, and may not import the
+//    module that does — ADR 0083). Written on the UPDATE branch too: a row that predates
+//    the bridge, or a hand-seeded one this projection later claims, becomes control-plane
+//    the moment the control plane actually writes it.
 async function upsertOwnedProject(entry, { pool = defaultPool } = {}) {
   const e = normalizeEntry(entry);
   const { rows } = await pool.query(
     `INSERT INTO platform_identity_projects
-       (origin, name, description, owner_github_id, type, visibility, status)
-     VALUES ($1, $2, $3, $4, $5, $6, $7)
+       (origin, name, description, owner_github_id, type, visibility, status, visibility_source)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, 'control-plane')
      ON CONFLICT (origin) DO UPDATE SET
        name        = EXCLUDED.name,
        description = EXCLUDED.description,
        visibility  = EXCLUDED.visibility,
-       status      = EXCLUDED.status,
+       status      = CASE WHEN platform_identity_projects.status_pinned
+                          THEN platform_identity_projects.status
+                          ELSE EXCLUDED.status END,
+       visibility_source = 'control-plane',
        type        = COALESCE(EXCLUDED.type, platform_identity_projects.type),
        updated_at  = now()
      WHERE platform_identity_projects.owner_github_id = EXCLUDED.owner_github_id
-     RETURNING id, origin, name, description, owner_github_id, type, status, featured, visibility`,
+     RETURNING id, origin, name, description, owner_github_id, type, status, featured, visibility, status_pinned`,
     [e.origin, e.name, e.description, e.ownerGithubId, e.type, e.visibility, e.status],
   );
   return rows[0] || null;
 }
 
+// setProjectStatus — THE TAKEDOWN LEVER (R08, task 1002327; ADR 0252 §5.1).
+//
+// Before this, `platform_identity_projects.status` had NO route that wrote it: the column
+// existed from migration 004, the public feed required 'active', and removing a project
+// from the map meant hand-written SQL on production. Under operator-provisioned curation
+// that was survivable, because the set of rows was bounded by who the operator had
+// provisioned. Auto-appear (ADR 0252 §3) replaces that bound with whoever points a domain
+// at us, and a one-way door onto a public surface is not a door — so the Archon's
+// auto-appear decision was explicitly conditional on this shipping in the SAME task
+// (ADR 0047's rule that a straight-through path and its abuse guard are one piece of work).
+//
+// SETTING THE PIN IS THE POINT, not a side effect: `status_pinned` is what stops the ADR
+// 0246 projection from reverting the decision on the owner's next settings save. A PATCH
+// back to 'active' clears it, returning the row to automatic management.
+async function setProjectStatus(id, status, { pool = defaultPool } = {}) {
+  if (!CATALOG_STATUSES.includes(status)) {
+    throw new Error(`project-catalog: unknown status ${JSON.stringify(status)}`);
+  }
+  const { rows } = await pool.query(
+    `UPDATE platform_identity_projects
+        SET status = $2, status_pinned = ($2 = 'hidden'), updated_at = now()
+      WHERE id = $1
+      RETURNING id, origin, name, status, status_pinned, featured, visibility`,
+    [id, status],
+  );
+  return rows[0] || null;
+}
+
 // Take a catalog row OFF the map when its project moved to a different address (the domain
 // re-point, task 1003237): an abandoned origin left `active` would keep drawing an orb that
 // points at a hostname the project no longer answers on — the ADR 0181 §2 leak, in the
@@ -222,6 +279,7 @@ module.exports = {
   normalizeEntry,
   upsertCatalogOnlyClient,
   upsertOwnedProject,
+  setProjectStatus,
   retireOwnedProject,
   catalogedOrigins,
   publishControlPlaneProject,

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

@@ -301,10 +301,41 @@ async function getProjectStats(origins = []) {
   return out;
 }
 
+// fetchInstanceVisibility — ONE origin's public manifest, for the visibility pull (R08,
+// task 1002327; ADR 0252 §2). Lives here, not in visibility-pull.js, for the reason this
+// file's SSRF header gives: this is "the one place the server makes an outbound request
+// to an address that came out of the database", and a pull that opened its own fetch
+// path would be a second, weaker one. It reuses the SAME guard the stats fan-out runs —
+// resolve-all with a public-address assertion, `redirect: 'error'` so the remote never
+// chooses our final address, and the per-request timeout.
+//
+// DELIBERATELY OUTSIDE THE STATS CACHE. The stats cache is warmed by public feed reads
+// and holds only the rows the feed enriches; the pull's working set is the opposite one
+// — rows that are dark, or stealth, and therefore excluded from that enrichment
+// entirely. Sharing the cache would mean the sweep could only ever refresh projects that
+// were already visible, which is exactly backwards. The sweep has its own cadence and
+// carries its own staleness stamp in the database, so a second in-memory TTL would be a
+// third opinion about freshness with nothing to settle it.
+//
+// THE PREFIX IS THE CANONICAL ONE, not the one ADR 0252 §2 wrote. The API router is
+// dual-mounted at `/api/bongos` (canonical) and at a permanent legacy alias — see the
+// header of `src/bongos/routes.js` — so both resolve on every instance and the choice
+// is free.
+// `/api/bongos` matches the discovery fetch four lines up in `fetchStats`, so this file
+// asks a remote instance for everything under ONE prefix.
+//
+// Throws on an unreachable, refused or non-JSON response; the caller reads a throw as
+// "no verdict", never as a value.
+async function fetchInstanceVisibility(origin) {
+  await assertPublicHost(siteUrl(origin).hostname);
+  return getJson(apiUrl(origin, '/api/bongos/instance'));
+}
+
 // tests
 function _reset() { _cache.clear(); _inflight.clear(); _coreModules = null; }
 
 module.exports = {
   getProjectStats, isSystemAccount, coreModules, blockedReason, assertPublicHost, httpUrl,
+  fetchInstanceVisibility,
   NULL_STATS, SHIPPED_WINDOW_DAYS, FACES_MAX, _reset, TTL_MS,
 };

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

@@ -118,11 +118,26 @@ const PUBLIC_FEED_MAX_PROJECTS = 500;
 // sort but never projects: feature toggles and client re-registration bump it, so as a
 // public "last updated" it would lie. `description` is the publish BAR, spent in the
 // predicate, never a card field.
+// A PULLABLE row is on the map only once it has actually answered (R08, task 1002327;
+// ADR 0182 D5 via ADR 0252 §4). "Unreported => dark matter" is scoped, deliberately and
+// narrowly, to rows whose door the hub has never successfully read: a control-plane row
+// was ASSIGNED its door by the ADR 0246 bridge and is on the map the moment that lands,
+// and a row that answered once and is unreachable today KEEPS its last state — a project
+// does not leave the map because its server was down for a sweep (ADR 0199 / 0226).
+//
+// THE SCOPING IS THE SAFETY PROPERTY, not a nicety. ADR 0247 D4 found the unscoped
+// version live on this very table: every catalog row carried `description: null`, so a
+// fail-closed gate wired that day would have refused every join on the platform at once.
+// The same predicate written without the `visibility_source` half — or shipped without
+// migration 020's backfill, which stamps every pre-existing row 'control-plane' — would
+// empty the public map on deploy. Both halves are load-bearing.
+const DOOR_KNOWN_SQL = "(visibility_source = 'control-plane' OR visibility_reported_at IS NOT NULL)";
+
 async function listPublicProjects({ pool = defaultPool } = {}) {
   const { rows } = await pool.query(
     `SELECT origin, name, tagline, art_url, type, template, created_at, visibility
        FROM platform_identity_projects
-      WHERE status = 'active' AND ${publishableSql()}
+      WHERE status = 'active' AND ${publishableSql()} AND ${DOOR_KNOWN_SQL}
       ORDER BY featured DESC, updated_at DESC
       LIMIT ${PUBLIC_FEED_MAX_PROJECTS}`,
   );
@@ -138,5 +153,6 @@ module.exports = {
   isStealthProject,
   feedShapeFor,
   PUBLIC_FEED_MAX_PROJECTS,
+  DOOR_KNOWN_SQL,
   listPublicProjects,
 };

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

@@ -15,6 +15,9 @@
 //   POST  /projects/invite     — a `project.curate` holder OR the project's OWN owner:
 //                                pre-seed a 'pending' membership (invite-authz.js)
 //   PATCH /projects/:id/featured — Archon: the feature / unfeature control
+//   PATCH /projects/:id/status   — `project.curate`: the TAKEDOWN lever (R08, ADR 0252
+//                                §5.1). Setting 'hidden' pins the row so the ADR 0246
+//                                projection cannot quietly put it back on the map.
 //
 // Reaches core only through the doorway (ADR 0083). Archon routes declared first so
 // route-rank-check's look-ahead never misclassifies the trailing public GET.
@@ -181,12 +184,56 @@ module.exports = function projectsRoutes() {
     }
   });
 
+  // rank: metic — THE TAKEDOWN LEVER (R08, task 1002327; ADR 0252 §5.1). Until this
+  // route, `platform_identity_projects.status` had no writer on the API at all: the
+  // column shipped in migration 004, the public feed requires 'active', and removing a
+  // project from the map meant hand-written SQL against production.
+  //
+  // IT SHIPS IN THE SAME TASK AS AUTO-APPEAR, NOT AFTER IT. ADR 0252 §3 lets a
+  // self-hosted project put itself on the public map with no human act, and the Archon
+  // took that decision explicitly conditional on retraction landing beside it — ADR 0047's
+  // rule that a straight-through path and its abuse guard are one piece of work. A
+  // one-way door onto a public surface is not a door.
+  //
+  // Setting 'hidden' PINS the row (project-catalog.js), which is what makes the
+  // retraction survive: the ADR 0246 projection re-takes `status` on every provisioning
+  // write, so without the pin an owner's next settings save would quietly undo the
+  // takedown. PATCHing back to 'active' releases the pin and returns the row to automatic
+  // management, so un-hiding is exactly as deliberate an act as hiding.
+  router.patch('/projects/:id/status', 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, { status: { required: true, type: 'string' } })) return;
+    if (!projectCatalog.CATALOG_STATUSES.includes(req.body.status)) {
+      return res.fail('bad_project_status', 400, { valid: projectCatalog.CATALOG_STATUSES });
+    }
+    try {
+      const project = await projectCatalog.setProjectStatus(id, req.body.status, { pool });
+      if (!project) return res.fail('project_not_found', 404);
+      res.json({ project });
+    } catch (err) {
+      log.error({ err: err.message }, 'PATCH /projects/:id/status');
+      res.fail('status_change_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // The PUBLIC projects feed — every project ON THE MAP (active + publishable),
   // public projection. CORS-enabled cross-origin read (a status page / the apex /
   // the static orbs site fetches it pre-auth).
   router.use('/projects/featured', corsPublicGet('/projects/featured'));
   // rank: public — the public map of projects; no auth by design.
-  router.get('/projects/featured', async (_req, res) => {
+  //
+  // THE PER-IP CEILING IS PART OF THE ROUTE, not a decoration on it (ADR 0252 §5.3).
+  // This GET is unauthenticated and CORS-open, and it was unmetered by construction: the
+  // two global limiters return early for reads, and the /public/* read limiter is mounted
+  // on a prefix this route does not sit under. It is also the platform's most expensive
+  // anonymous read — a cold cache turns one request into as many as 500 rows × 4 outbound
+  // fetches at OTHER PEOPLE's servers, so leaving it open aims our fan-out, not just our
+  // database. Auto-appear removed the old bound (the set of projects the operator had
+  // provisioned) and replaced it with "whoever points a domain at us", which is what makes
+  // the ceiling load-bearing rather than prudent. It runs BEFORE the handler, so a refused
+  // read costs no query and no fetch.
+  router.get('/projects/featured', api.publicProjectFeedRateLimit, async (_req, res) => {
     try {
       const projects = await pi.listPublicProjects({ pool });
       // A stealth project is on the map ANONYMOUSLY (ADR 0182 D2a), so its origin