docs(runtime,metadata,rest): retire the expired "structurally unreachable until the E7 flip" comment family + cover the multi-tenant decline branch (#5399) (#5404)

The #5040 E7 publish flip landed (packages/spec/src/api/endpoint-publish-gate.ts
opens with "This module is that flip"), and E8 moved endpoints back into the
OpenAPI document. Thirteen comments across runtime/metadata/rest still asserted
the pre-flip world -- "Structurally unreachable today", "Nothing calls this yet",
"Today it emits nothing" -- which is exactly the #5078 defect: a comment that
contradicts the code in front of it.

Each site is rewritten to describe current reality and cite the authority
(the publish gate, or the real-boot probe in
packages/qa/dogfood/test/showcase-declarative-endpoints.dogfood.test.ts, whose
/openapi.json case disproves "emits nothing" directly). Surrounding still-true
prose is preserved. Pure comment change: the only non-comment line touched is a
descriptive `note:` string in the route ledger.

Also adds dispatcher-plugin.multi-tenant-endpoint.integration.test.ts, covering
the E5b branch "multi-tenant resolution finds no environment -> decline + warn",
which had zero test references repo-wide because the kernel-resolver PROVIDER
ships in the cloud distribution. A stub resolver drives a real boot over a real
socket: a placed request executes on its own tenant kernel; an unplaced one gets
the transport's bare 404, the warn, and no probe of any declaration.

The host kernel deliberately declares the same path too. Without that, the
decline cases pass vacuously -- verified by deleting the branch and re-running:
with tenant-only declarations only the warn assertion moved, because the step
declined a second time for an unrelated reason. With the host copy in place,
deleting the branch turns both decline cases red with "expected 200 to be 404",
the cross-tenant answer the branch exists to prevent.

Out of scope, filed as #5400: the sibling `else` branch still logs `debug` when
an adapter exposes no setFallbackHandler. Its own comment scheduled a move to
`warn` "when that flip lands" -- it has landed, so declared endpoints are now
silently unservable there -- but changing the level is a behavior change, so
this commit only makes the comment truthful and names the tracking issue.

Refs #5231, #5040, #5078, #5230, #5385


Claude-Session: https://claude.ai/code/session_01VkPSGsX9o17MsGv3Lbxu2w

Co-authored-by: Claude <noreply@anthropic.com>

Author: baozhoutao

packages/metadata/src/metadata-manager.ts

@@ -2161,9 +2161,14 @@ export class MetadataManager implements IMetadataService {
    * already resolve the `metadata` service for the environment they serve —
    * adding one here would create a second scoping mechanism.
    *
-   * Nothing reaches this method over HTTP in 17.x: the dispatcher seam is
-   * #5090's, and publish still rejects a non-empty `apis:` (#4936), so the
-   * whole path is structurally unreachable until the #5040 E7 flip.
+   * This method is reached over HTTP on a real boot. The dispatcher seam
+   * landed as #5090 (`packages/runtime/src/api-endpoint-step.ts`, called from
+   * the `setFallbackHandler` the dispatcher plugin installs), and #4936's
+   * wholesale publish refusal of a non-empty `apis:` was replaced by the
+   * #5040 E7 per-shape gates (`packages/spec/src/api/endpoint-publish-gate.ts`)
+   * — so declarations exist and requests arrive here. The showcase's two
+   * declared endpoints are matched and executed through this path in
+   * `packages/qa/dogfood/test/showcase-declarative-endpoints.dogfood.test.ts`.
    *
    * @throws when the metadata store cannot be read — an outage must never be
    *   reported as a miss, because a miss becomes a 404.

packages/rest/src/openapi-endpoints.test.ts

@@ -3,14 +3,17 @@
 /**
  * #5040 E6 — declared endpoints in the OpenAPI document.
  *
- * Two jobs, and the second one is the load-bearing one TODAY:
+ * Two jobs:
  *
  *  1. the positive shapes, driven straight through the pure enrichment with
- *    parsed declarations (publish still refuses to let any of them exist, so
- *    there is no boot that could exercise them end to end yet);
+ *    parsed declarations. Since the #5040 E7 publish flip these are the LIVE
+ *    path — a real showcase boot serves an `/openapi.json` carrying its two
+ *    declared endpoints
+ *    (`packages/qa/dogfood/test/showcase-declarative-endpoints.dogfood.test.ts`);
+ *    the cases here pin the projection itself, apart from any boot;
  *  2. the empty-set invariant — with no declarations the document must come
- *    back not merely equivalent but IDENTICAL, because that is the entire
- *    live-behaviour claim this change makes until the E7 flip.
+ *    back not merely equivalent but IDENTICAL, which is what keeps a
+ *    deployment that declares nothing byte-for-byte unchanged.
  */
 
 import { describe, it, expect, vi } from 'vitest';

packages/rest/src/openapi-endpoints.ts

@@ -55,12 +55,20 @@
  * the mirror; it is not built here because Prime Directive #2 keeps logic out
  * of `packages/spec` and the frozen vocabulary is not this unit's to widen.
  *
- * ## Today it emits nothing
+ * ## What it emits today
  *
- * Publish/validate still rejects a non-empty `apis:` until the E7 flip, so the
- * enumeration yields an empty set and {@link enrichOpenApiWithEndpoints}
- * returns its input document BY REFERENCE — the served bytes are identical to
- * before this change. That invariant is pinned by a test rather than argued.
+ * Real documents. The #5040 E7 publish flip
+ * (`packages/spec/src/api/endpoint-publish-gate.ts`) ended the wholesale
+ * refusal of a non-empty `apis:`, so the enumeration is no longer empty on a
+ * deployment that declares endpoints: a real showcase boot serves an
+ * `/openapi.json` describing its two declared endpoints
+ * (`packages/qa/dogfood/test/showcase-declarative-endpoints.dogfood.test.ts`).
+ *
+ * The empty-set case is still exact rather than approximate — with nothing to
+ * add, {@link enrichOpenApiWithEndpoints} returns its input document BY
+ * REFERENCE — which is what keeps a deployment that declares no endpoint
+ * byte-identical to one built before this module existed. That invariant is
+ * pinned by a test rather than argued.
  */
 
 import { ApiEndpointSchema, type ApiEndpoint } from '@objectstack/spec/api';
@@ -328,8 +336,10 @@ export function selectDocumentableEndpoints(
  * Fold declared endpoints into an OpenAPI document's `paths`.
  *
  * Returns `doc` ITSELF when there is nothing to add — that is what makes the
- * empty-set case byte-identical rather than merely equivalent, and it is the
- * state of the world until the E7 flip lets a non-empty `apis:` publish.
+ * empty-set case byte-identical rather than merely equivalent, which is the
+ * state a deployment declaring no endpoint stays in. Since the E7 flip let a
+ * non-empty `apis:` publish, the other branch is the live one wherever
+ * endpoints are declared.
  *
  * A declaration never displaces a built-in: if the document already describes
  * the same path+method, the built-in keeps it and the declaration is reported.

packages/rest/src/rest-openapi-route.test.ts

@@ -77,9 +77,11 @@ describe('GET /api/v1/openapi.json — endpoint enrichment', () => {
   });
 
   it('serves a document identical to the pre-#5093 one while no endpoint is declared', async () => {
-    // The load-bearing invariant: publish rejects a non-empty `apis:` until the
-    // E7 flip, so this is the ONLY state that exists in production today, and
-    // the change is required to be invisible in it. Compared against the same
+    // The load-bearing invariant: a deployment that declares no endpoint must
+    // not be able to tell the enrichment step exists. Since the #5040 E7
+    // publish flip this is no longer the only state in production — endpoints
+    // do publish — which is exactly why the no-declaration state needs pinning
+    // rather than assuming. Compared against the same
     // handler fed a protocol with no `api` capability at all — i.e. the world
     // exactly as it was before the enrichment step existed.
     const withEmptyApis = await serveOpenApi(makeProtocol({ object: [], api: [] }).protocol);

packages/rest/src/rest-server.ts

@@ -2862,10 +2862,12 @@ export class RestServer {
                 //    ADR-0076): declared endpoints join it here rather than
                 //    growing a second generator somewhere else.
                 //
-                //    Until the E7 flip a non-empty `apis:` cannot publish, so
-                //    the enumeration is empty and `enrichOpenApiWithEndpoints`
-                //    hands `enriched` straight back — the served bytes today
-                //    are exactly the ones served before this change.
+                //    Since the E7 flip a non-empty `apis:` publishes, so this
+                //    enumeration returns real declarations on a deployment that
+                //    has them and the document grows a path entry per endpoint.
+                //    Where nothing is declared the enumeration is empty and
+                //    `enrichOpenApiWithEndpoints` hands `enriched` straight
+                //    back, byte for byte.
                 try {
                     const apiResult = await protocol?.getMetaItems?.({ type: 'api' });
                     const apiItems: unknown[] = Array.isArray((apiResult as any)?.items)

packages/runtime/src/api-endpoint-step.test.ts

@@ -5,8 +5,10 @@
  *
  * Every case here is about ONE question: when does this step answer, and when
  * does it write nothing so the transport's existing unmatched answer stands?
- * Getting that wrong in either direction is a live behavior change on a surface
- * that is supposed to be inert until the #5040 E7 flip.
+ * Getting that wrong in either direction is a live behavior change — and since
+ * the #5040 E7 publish flip it is live for real traffic, not just in principle:
+ * endpoints can be declared, so a step that answers when it should stay silent
+ * now shadows the transport's 404 on a deployment.
  *
  * `matchEndpoint` is driven by a stub implementing the contract in
  * `@objectstack/spec/contracts` — deliberately, not by the real matcher: that

packages/runtime/src/api-endpoint-step.ts

@@ -20,11 +20,14 @@
  * ## What it does today, and what it does not
  *
  * On a match it runs the WHOLE chain: policies (#5040 E4) and then target
- * execution (#5040 E5), wired together here by E5b. It is still structurally
- * unreachable — a non-empty `apis:` is rejected at publish / validate until the
- * E7 flip — so no deployment can observe it; the tests drive `matchEndpoint`
- * through a stub, exactly as #5040 §5 prescribes for every E-series unit that
- * lands before the flip.
+ * execution (#5040 E5), wired together here by E5b. Since the E7 publish flip
+ * (`packages/spec/src/api/endpoint-publish-gate.ts`) a non-empty `apis:` is no
+ * longer refused wholesale — only shape by shape — so a deployment CAN observe
+ * this step: the showcase declares two endpoints and a real boot serves them
+ * (`packages/qa/dogfood/test/showcase-declarative-endpoints.dogfood.test.ts`).
+ * The tests here still drive `matchEndpoint` through a stub, which is what
+ * keeps the decision (when to answer, when to write nothing) testable apart
+ * from the wiring.
  *
  * ## The chain, in the one order it can run in
  *

packages/runtime/src/api-mapping.test.ts

@@ -14,9 +14,10 @@
  *     applied. `transform` is the case #5137 was filed over, but an unusable
  *     path and colliding targets are the same category and answer identically.
  *
- * And the property that makes both safe to land before the E7 flip: with no
- * declaration, the value that goes in is the value that comes out, by
- * reference.
+ * And the identity property both rest on: with no declaration, the value that
+ * goes in is the value that comes out, by reference. That is what made these
+ * keys safe to land ahead of the #5040 E7 publish flip, and it is still what
+ * keeps an endpoint declaring no mapping free of any projection cost.
  */
 
 import { describe, it, expect } from 'vitest';

packages/runtime/src/dispatcher-plugin.endpoint-fallback.integration.test.ts

@@ -18,9 +18,12 @@
  * rides a success and never an error.
  *
  * The load-bearing assertion in most of these is a NEGATIVE one: that adding
- * this seam changed nothing for anybody. Today's unmatched answers — the bare
- * 404 and the 405 + `Allow` — must come back byte for byte, since a stack
- * cannot declare an endpoint at all until the E7 flip.
+ * this seam changed nothing for anybody who did not ask for it. The unmatched
+ * answers — the bare 404 and the 405 + `Allow` — must come back byte for byte
+ * for every path no declaration owns. Since the #5040 E7 publish flip that is
+ * the assertion's whole weight: stacks CAN declare endpoints now, so "the
+ * fallback stays silent unless a declaration matches" is a promise to live
+ * deployments rather than a property of a surface nothing could reach.
  *
  * NOTE on the body guarantee: that the fallback receives a READABLE `req.body`
  * (the difference from the `use()` middleware seam) is a transport promise, and