@bongos/core 1.19.563 → 1.19.565

package/docs/adr/README.md

@@ -339,6 +339,8 @@ This keeps the decision history honest and traceable.
 | 0249 | [**The invite step is the done panel’s first act, not a rail step — and the same widget is the way back** ([task 1002346](https://cloudbongos.com/builders#/task/1002346) · goal 1000046, criterion `proj-invite-builders` / C6). BV1.R27 asks for a skippable invite step *in creation*, but an invite cannot be one of the wizard’s numbered panels: `POST /projects/invite` takes `{ client_id, github_login }` where `client_id` **is the slug**, and per [ADR 0246](<redacted>.md) the catalog row that slug resolves is projected **at create** — so before the Create step there is nothing to invite anyone to, and a pre-Create panel could only queue names and replay them, inventing a second unaudited invite path whose failures land after the owner has left. **Decision: the step is the FIRST act of the DONE panel**, keyed on the created record (not `instanceId`, which `startProgress` sets only *after* `renderDone`), so it also returns on a resumed watch; the rail is NOT renumbered (a captured learning on this file: a renumbering couples in four places, and a step that can only run after the terminal step is not a step in the rail). The SAME widget is mounted again on the project’s own page beside *Its extras* — the [ADR 0245](<redacted>.md) argument, one implementation and two mounts, so the refusal vocabulary cannot drift. The widget answers neither “is anyone signed in” nor “is this their project”: each call site hands over a slug or nothing (the created record; the own-scoped manage read that 404s for everyone else), because a page that re-derived ownership would be a second, weaker copy of a server rule. **The 403 is quoted carefully and that is the point** — [ADR 0248](<redacted>.md) paid two equalised reads per request to make the refusal identical for a real, stealth, absent or malformed target ([ADR 0182](<redacted>.md) D2a), and “you lack permission on **this project**” would assert in copy the existence the route refuses to confirm, so the page says only “this account can’t invite people here” and a test pins that wording. `account_not_found` and `unknown_project` are said in the route’s own words (the latter as a moment, not a dead end — the row is projected at create); anything else falls through to the server’s own message. The pending line is drawn from the 201 row’s `membership_kind` and the typed login — **never the `github_id`** it carries, which names someone who has accepted nothing yet. Creation is never blocked: the project is filed before the step is shown, so every refusal leaves it created and the step re-tryable, and Skip sends nothing. Rejected: a rail step before or after Create; the manage page alone (R27 asks for it *in creation*); reading the real membership directory back (no own-scoped route exists, and the session receipt is honest about being one).](<redacted>.md) | provisioning / project creation |
 | 0250 | [**Strict versioning — the version boundary is the scope gate** ([task 1003589](https://cloudbongos.com/builders#/task/1003589) · goal 1000086). The work hierarchy ([ADR 0086](<redacted>.md)) has a bottom and no top: tasks close, criteria close, goals close, and a version never does. Measured live — **14 goals reading `achieved`/`archived` while holding 35 unfinished tasks**, 523 open tasks across 37 open goals, and **two versions `building` on one project**; every number was worse than the planning session had recorded two days earlier, which is the argument: the drift is the steady state, not a backlog. The cause is four mechanical gaps, not a social one — `POST /goals` fetches the version row and never reads its `status`; goal achievement is computed from criteria alone and never consults `tasks` (both the `db-goals.js` writer and the `done-when.js` cascade); `POST /goals/:id/archive` checks nothing at all; and no route ships a version, so version status has only ever moved as hand-run SQL on the droplet. **Decision, five rules:** the goal set closes when a version starts `building` (new goals go on the `planning` version — where the next version is scoped in advance) with a named 409 an agent can act on; a goal reaches `achieved` only when its criteria are satisfied **and** no task in it is non-terminal, where terminal is `shipped`|`abandoned` per [task 1003588](https://cloudbongos.com/builders#/task/1003588)'s one vocabulary and the mid-ship `completed`/`confirmed` hold it open; archiving a goal that holds open tasks refuses until the caller dispositions each (abandon with the reason, or move to a named surviving goal); `goal_id` becomes required and the per-version catch-all fallback is deleted; and exactly one version builds per project, auto-closing when its last non-maintenance goal achieves, with the single `planning` version promoting itself so the project is never without a live train. **The escape hatches are deliberate and visible**: an Archon may admit one *named* goal to a building version with a reason, and the overrides are counted on the version (the standard failure of a hard scope gate is a fake hotfix version cut to hold what did not fit — an untraced override is just a slower version of no rule); plus one auto-created maintenance goal per version, exempt from the auto-close count, so bugs never need an override to be filed. **Nothing here can refuse a ship, a claim, or a task** — every rule acts on a *closing* move. Rejected: counting `completed`/`confirmed` as finished (they can fail a grade or strand — the goals **board** buckets them as done, but that is a progress ring, and `task-status.js` keeps the two questions apart); a nightly reconciler that reopens wrongly-closed goals (detection is what you build when prevention is unavailable, and it is available here); a human review gate before a goal may close (the queue [ADR 0183](<redacted>.md) dismantled — the check is a fact the table already holds); concurrent building versions scoped by module (two live trains means every "what is in this version" question has two answers); retiring versions entirely (the version is the unit the owner sets scope in and `limitations/<version>-shipped.md` archives). **Amends [ADR 0157](<redacted>.md) for exactly one key:** `version.create` returns to the Archon floor. 0157's "authoring delegates, disposition does not" was right about what a version *was* — but once the boundary carries the scope gate, cutting a new version is no longer authoring, it is the way *around* the gate, so create joins close as a disposition over scope.](<redacted>.md) | lifecycle / versioning / scope |
 | 0251 | [**A suggestion of who to invite is a recruiting surface, and owes the recruiting opt-out** ([task 1002347](https://cloudbongos.com/builders#/task/1002347) · goal 1000046, criterion `proj-invite-builders` / C6). BV1.R28 fills the seam [ADR 0239](<redacted>.md) §6 left open: the wizard’s pure rule engine emits a **seek** (`solo` → `null`, `small-team` → 3, `community` → 5) and never a list, because ranking builders is a directory read a pure file may not run and `provisioning` may not import a sibling. Two readers could answer “who are the top builders” and they differ by **one SQL predicate**: `economy`’s `leaderboard()` joins `rollupVisibleSql` and deliberately honours **no** recruiting opt-out, while `platform-identity`’s `listScoutingRollup()` joins `scoutingListableSql`, which carries it. The leaderboard is cheaper in every mechanical sense — already a public route, no port, callable straight from the browser. **Decision: use the recruiting directory anyway**, because `account-visibility.js` says the split in its own words (`hide_stats` suppresses *numbers* everywhere; the recruiting opt-out “removes an account from the RECRUITING SURFACE only”, community spec D3), and a list of people the platform proposes you recruit **is** that surface — sourcing it from the leaderboard would route around the one control built for this exact case and name every builder who asked not to be recruited. The rule for later readers: **the cheapness of a public read is not an argument about who consented to appear in it.** The lookup ships as `listInviteSuggestions` on the existing `platform-identity.hub` port, reached with `resolveOptional` and NOT declared in `consumes` (the `catalog-bridge.js` precedent — platform-identity is hub-only, so its absence is “no suggestions”, never a 500); `github_id` **does not cross the port** (explicit whitelist — login, display name, avatar, disciplines, two counts — so a new rollup column cannot leak by default), and the owner-exclusion is applied inside, over-read by the exclusion count so filtering never returns short. The route `GET /provisioning/instances/:id/invite-suggestions` is own-scoped by the **existing** `instanceAccessDenied` (same 404 as the manage read) and deliberately does NOT reuse `/scouting`’s gate ([ADR 0210](<redacted>.md)): a brand-new owner has no hub-witnessed owner row at the moment the done panel paints, so the correct-looking gate would refuse the exact caller the feature exists for — and reaching the route IS the ownership answer ([ADR 0249](<redacted>.md) §4). On the surface: a **second door in** (`setInviteSuggestions`) beside `setInviteSlug`, so the widget still answers neither “signed in” nor “theirs”; the reason is **always** said including when the answer is nobody (`seeking: null` costs no query — rendering a stated answer as an empty list would make it look like a failed lookup); a picked name fills the field and takes the **same write path** as a typed one, so the refusal vocabulary cannot fork; a filed invite stops being a suggestion; and every failure is silent, because a suggestion is an extra and a just-created project must not look broken over one. Rejected: the browser reading the economy leaderboard (the whole decision — consent, not architecture); reusing `/scouting` (right data, gate that refuses this caller); filling `invites.suggested` inside the engine (I/O in a pure file + a sibling import); a `provisioning → economy` port (legal, still the wrong directory — the boundary was never the objection).](<redacted>.md) | provisioning / platform-identity / privacy |
+| 0252 | [**The self-hosted visibility report is a PULL, and auto-appear buys a retraction lever** ([task 1002321](https://cloudbongos.com/builders#/task/1002321) · goal 1000046, criterion `proj-visibility-states` / C1, BV1.R02 — a spike whose output is this decision; gates [task 1002327](https://cloudbongos.com/builders#/task/1002327) / R08). **The premise failed first:** a self-hosted instance has no channel to the hub and no credential to open one — `registerClient` has exactly one caller in the tree (the operator's own `provision-net.js`), gated `hosting_shape !== 'co-tenant'`, and no route registers a client. So *federated* ⊆ *operator-provisioned co-tenant* and *self-hosted* holds nothing, deliberately: [ADR 0145](<redacted>.md) says do NOT extend federation to `standalone`, and [ADR 0144](<redacted>.md)'s Known Limitation rests on "every secret-holder is an operator-provisioned, trusted instance … the proper fix must land before federation opens to untrusted third-party clients." [ADR 0182](<redacted>.md) D5's "accepts a report from the authenticated `sso_client`" described a client that, for this population, does not exist. **Decision 1 — the channel is a PULL of the instance's already-public manifest** (`GET <origin>/api/gds/instance` → `branding.project.visibility`, a value every core already serves and whose author anticipated this consumer). It buys five things a push must build: no credential (0144's tripwire untouched — the whole reason), **no replay surface** (a pull reads current state, so the `jti` machinery D5 handed R02 is moot — replay is answered by not having a message), no wire change on another instance's upgrade clock ([ADR 0205](<redacted>.md)'s and [ADR 0201](<redacted>.md) D2.2's rejected-required-field problem simply absent), the hub still authorising nothing (0182 D5 satisfied, [ADR 0238](<redacted>.md)'s rejected `PATCH /projects/:id/visibility` still rejected), and a fetch that already exists behind a real SSRF guard (`project-stats.js` — DNS-resolve-all, `redirect: 'error'`, TTL + negative caches). The pull carries `visibility` and NOTHING else, so the property the map has today — a project owner controls no free-text field that reaches the feed — is not spent. **Decision 2 (the Archon's) — auto-appear:** no human stands between a public project and the map; `featured` keeps only the ranking job [ADR 0182](<redacted>.md) D3 left it. Conditional on Decision 4. **Decision 3 (the Archon's) — trust follows provenance:** both populations auto-appear, and the asymmetry is in the GUARDS, not a gate — a control-plane row's `visibility` is *assigned* by the bridge from an own-scoped audited route (authoritative), a self-hosted row's is *pulled* from a manifest the hub does not control (a cached claim with a recency stamp, able to move its own row and nothing else). An instance is authoritative about its own door and about nothing else. **Absent is a THIRD state and must not purge:** `null` (never read) ≠ `false` (read, negative). 0182 D5's fail-closed default holds only for a self-hosted row that has NEVER answered; a row that answered before and is unreachable now keeps its last state with a recency stamp ([ADR 0199](<redacted>.md), [ADR 0226](<redacted>.md)), because [ADR 0247](<redacted>.md) D4 found the live shape of that trap — every catalog row at `description: null`, so naive fail-closed would have emptied the map at once. Narrowing is free; widening is what costs. **Decision 4 — auto-appear buys a retraction lever, in the same task** ([ADR 0047](<redacted>.md): the straight-through path and its abuse guard are one task, treated as binding): `platform_identity_projects.status` is `(active,hidden)` and **no route writes it** — takedown is hand SQL today, and a one-way door onto a public surface is not a door. R08 ships `PATCH /projects/:id/status` (curate floor, audited), a per-IP limit on the unmetered CORS-open feed read ([ADR 0209](<redacted>.md)), and above all **`hidden` STICKY against the pull** — a retracted project that keeps reporting `public` stays hidden, or the next sweep silently undoes every takedown and the lever is decorative. Also named: `hall_origin` reaches the feed from the remote's own discovery index checked only for *differing* from the project host — the opposite of containment — and gets `shipUrlWithinClientOrigin`'s downward-only rule, filed against R08. Rejected: a pushed credentialed report (the literal R08 — needs the credentials 0144/0145 forbid, plus replay, rate and a wire-compatible field, none of which the pull has); `PATCH /projects/:id/visibility` (0238 already); a one-time admission and ongoing curation (both offered to the Archon, both declined); trusting the pull to move `status`; enforcing "unreported ⇒ dark matter" across all rows; letting the pull carry name/tagline/art. The later ANALYTICS feed is deliberately NOT decided here — it carries per-person data, exactly what [ADR 0205](<redacted>.md) proved cannot ride an unwitnessed self-report, and it needs the 0144 credential work first.](<redacted>.md) | platform-identity / provisioning / federation trust |
+| 0253 | [**The takedown lever has two writers, and provenance has to be a column** ([task 1002327](https://cloudbongos.com/builders#/task/1002327) · goal 1000046, criterion `proj-visibility-states` / C1, BV1.R08 — the build). Amends [ADR 0252](<redacted>.md) §4/§5: three premises that did not survive contact with the tree. The decisions stand; what changes is what has to be BUILT. **(1) `hidden` is sticky against TWO writers, and 0252 names the wrong one.** 0252 §5 says "no route writes [`status`]" and defends the takedown against the PULL. But `project-catalog.js:upsertOwnedProject` writes `status = EXCLUDED.status` on every conflict, sourced from `catalog-bridge.js:catalogStatusForInstance` — which returns `active` for any instance not torn down — and [ADR 0246](<redacted>.md) re-takes that projection at EVERY provisioning write. So the live failure is: curator hides a project → its owner saves any setting → it is back on the map. Stickiness therefore belongs to the ROW (`status_pinned`, set by the curated PATCH, honoured by the projection), not to one writer's manners; the pull separately writes no `status` at all, asserted against the statement text. `retireOwnedProject` deliberately does NOT honour the pin — it is a safety retraction for an origin the project no longer answers on ([ADR 0181](0181-teardown-state-gate-and-address-retention.md) §2), and narrowing is always free. **(2) Provenance must be a stored column.** 0252 §4 tabulates control-plane vs self-hosted rows as though the catalog knew which was which; it has no `hosting_shape` (that lives on `provisioning_instances`, in a module platform-identity may not import — [ADR 0083](<redacted>.md)) and `owner_github_id` separates nothing (set by the bridge, set by `registerClient`, null on hand-seeded rows). `visibility_source` (`control-plane`|`pull`|NULL) records it on the row, re-asserted in the UPDATE's own WHERE so a mid-sweep projection cannot lose the race — making "the two never write the same row" an invariant the SQL enforces. Rejected a `provisioning.instanceShape` port: a cross-module read in a background loop, for a value that never changes per row. **(3) The tri-state cannot live in `visibility`** (`NOT NULL DEFAULT 'public'`), so the recency stamp IS the null-carrier: `visibility_reported_at IS NULL` is the never-read state, and a failed read writes nothing — which is what makes "keep the last known state" fall out rather than be implemented. The fail-closed feed predicate needed a BACKFILL for [ADR 0247](<redacted>.md) D4's exact reason: both columns are new, so unbackfilled it would have emptied the public map on deploy. Migration 020 stamps every existing row `control-plane`, which is safe because it is TRUE — no instance has ever been asked. Two smaller corrections: the manifest key is **`brand`**, not `branding` (0252 §2 and the task body both misname it; reading only the documented spelling makes every pull a silent no-verdict), and the pull is a **POLLER, not a passenger on the feed's fan-out** — the feed excludes exactly the rows that need pulling (a never-answered row is dark matter, so it is never enriched, so it never answers), stealth rows are excluded from enrichment by design, and a read-path pull would make a DB write a side effect of an anonymous CORS-open read. Honest limit recorded: 0247 D4's `description: null` problem is NOT fixed here — 0252 §7 refuses to let the pull carry name/tagline/description, so the publish gate stays unmet for self-hosted rows. The pull moves the door; it does not publish the project.](<redacted>.md) | platform-identity / provisioning / abuse guard |
 
 | 0246 | [**Catalog membership is a projection of the provisioning row, not a side effect of federation** ([task 1003576](https://cloudbongos.com/builders#/task/1003576) · goal 1000046, criterion `proj-detail-interview` / C3). The BV1.R18 proof ([task 1002337](https://cloudbongos.com/builders#/task/1002337)) demonstrated C3 against live and found its last clause — “then it publishes” — structurally false: the owner’s verdict reads `provisioning_instances` while the public map reads `platform_identity_projects`, and the ONLY bridge was `federateInstance → registerClient → upsertProject`, which `shouldFederate` refuses for anything but `co-tenant` (the wizard hard-codes `standalone`) and which runs ONCE, at provision time, through a COALESCE. So a wizard-made project was never catalogued at all and a co-tenant one that answered later never updated — `publishable: true`, `{"projects": []}`, forever. The same missing row is [task 1003580](https://cloudbongos.com/builders#/task/1003580)’s GAP 1: `POST /projects/invite` resolves against `platform_identity_sso_clients`, whose only writer is that same `registerClient`. Underneath is one conflation — federation mints CREDENTIALS and was incidentally the only thing that minted MEMBERSHIP, while [ADR 0182](<redacted>.md) D4 already fixed the map’s gate at IDENTITY, which has nothing to do with hosting topology. **Decision: the catalog row is a PROJECTION of the provisioning row, re-derived at every write that can change its inputs** — two halves, neither sufficient alone. (1) THE ROW SHAPE: every control-plane project gets both rows whatever its hosting shape, and the client row carries NO credential (`secret_hash = ''`, `redirect_uris = '{}'`), so **the shape is the enforcement** rather than a flag a caller could forget — `redirectUriAllowed` refuses `/sso/authorize`, `clientSecretValid` refuses `/sso/token`, `/sso/membership/check-in` and `/sso/activity/rollup`, and the one leg that checked NEITHER (`/sso/device/start`, which resolves a client from a user-typed origin) grew an explicit `clientIsCredentialed` guard. (2) THE TIMING: re-taken on create, on `PATCH …/detail`, on `PATCH …/settings` when the door changes, and on `POST …/domain` (which re-keys the row, retiring the abandoned origin — [ADR 0181](0181-teardown-state-gate-and-address-retention.md) §2’s leak, in the catalog instead of DNS). **NO MIGRATION** — `secret_hash` is `NOT NULL` and `''` satisfies it while hashing to nothing. `description` and `visibility` are ASSIGNED, not COALESCEd (clearing a description must UN-publish); `featured`/`tagline`/`art_url`/`template` are curation and stay untouched, so [ADR 0182](<redacted>.md) D3 holds. It grants nothing — the row is attribution per [ADR 0238](<redacted>.md), ownership stays `provisioning_instances.owner_builder_id` — and because it writes rows keyed on owner-supplied values (a slug, a BYO domain) each write carries its **claim rule in the ON CONFLICT action’s own WHERE**: the client is refreshed only `WHERE secret_hash = ''` (a real client’s origin, which binds the CLI mint audience, can never be rewritten) and the project only `WHERE owner_github_id = EXCLUDED.owner_github_id` (`NULL = anything` is not true, so the hand-seeded rows cannot be claimed). Writing `visibility` does not contradict [ADR 0182](<redacted>.md) D5: the hub authorizes nothing — the authority already ran on the provisioning plane ([ADR 0238](<redacted>.md)’s own-scoped, audited PATCH), and a project the control plane does NOT own has no provisioning row, so D5’s instance report (R08) stays the only channel for those. `tearing_down`/`torn_down` project `hidden`; a `no_address` instance is not catalogued at all. Travels on the kernel port `project.catalog`, the `project.publishGate` seam in the other direction ([ADR 0083](<redacted>.md) forbids the import). Rejected: extending `shouldFederate` to every shape (hands a real secret to instances whose web.env the platform does not write, and keeps the once-at-standup bug); bridging only at the publish moment (leaves the invite with nothing to resolve); registering only at standup (the bug itself); a `catalog_only` boolean column (needs a migration and is weaker than the shape); letting the bridge write `featured`; and backfilling the three existing catalog rows from code.](<redacted>.md) | provisioning / project creation |
 

package/docs/api/openapi.json

@@ -11127,7 +11127,7 @@
           "projects"
         ],
         "summary": "GET /projects/featured",
-        "description": "the public map of projects; no auth by design.\n\n**Rank:** `public` — No authentication — any caller.",
+        "description": "the public map of projects; no auth by design. 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.\n\n**Rank:** `public` — No authentication — any caller.",
         "x-rank": "public",
         "x-source": "modules/platform-identity/routes/projects.js",
         "responses": {
@@ -11259,6 +11259,72 @@
         ]
       }
     },
+    "/projects/{id}/status": {
+      "patch": {
+        "operationId": "patch_projects_id_status",
+        "tags": [
+          "projects"
+        ],
+        "summary": "PATCH /projects/:id/status",
+        "description": "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.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `project.curate` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/platform-identity/routes/projects.js",
+        "x-permissions": [
+          "project.curate"
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PatchProjectsIdStatusRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PatchProjectsIdStatusResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/provisioning/fleet": {
       "get": {
         "operationId": "get_provisioning_fleet",
@@ -18530,6 +18596,27 @@
           "project"
         ]
       },
+      "PatchProjectsIdStatusRequest": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "status"
+        ],
+        "additionalProperties": false
+      },
+      "PatchProjectsIdStatusResponse": {
+        "type": "object",
+        "properties": {
+          "project": {}
+        },
+        "required": [
+          "project"
+        ]
+      },
       "PatchProvisioningInstancesIdDetailRequest": {
         "type": "object",
         "properties": {
@@ -22505,9 +22592,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 357,
-  "x-schema-count": 391,
+  "x-endpoint-count": 358,
+  "x-schema-count": 393,
   "x-undocumented-bodies": 9,
-  "x-response-schemas": 265,
+  "x-response-schemas": 266,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

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

@@ -1575,5 +1575,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.561 with no explicit bump. run 34048961786. (task 1002620)
   1.19.563 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         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,
 };