test(route-parity): declared===enforced gate + honest standalone hono discovery (#3369)

[os-zhuang]

Summary

The route-parity declared === enforced gate for HTTP routes #3369 asks for — the "one boot-the-real-server test" that closes the class of "works in the dispatcher, dead on os serve" bugs (#3361, #3362, MCP 501).

Rebased & slimmed. While this was in flight, the two underlying fixes landed independently on main:

• v16.0: per-request admin-gated Server-Timing never emits on the hono server (os serve/dev) #3361 (admin-gated Server-Timing) → fix(server-timing): emit admin-gated per-request Server-Timing on the standard server (#3361) #3384, with a more correct fix (opens the disclosure gate in RestServer.resolveExecCtx, since @objectstack/rest shadows the hono plugin's own CRUD on os serve; homes isPerfDisclosurePrincipal in @objectstack/observability).
• v16.0: mark-notification-read 404s on os dev/serve — unread never clears (#3354 not effective on hono server) #3362 (notifications mark-read) → fix(i18n/notifications): localize collab notification titles + storage objects; wire the notifications REST routes #3354 + the e2e test in test(runtime): e2e regression for notifications mark-read on the hono server (#3362) #3388.

So this PR now carries only the net-new, non-overlapping work: the discovery route-parity gate.

Changes

1. Route-parity e2e gate (packages/runtime/src/route-parity.integration.test.ts).
Boots the real hono app the way os serve mounts it (hono server + dispatcher plugin, services provisioned), opens a socket, reads /api/v1/discovery, and asserts:

• every advertised / dispatcher-registered route is reachable — never 404/405/501 — for an anonymous AND an admin principal (covers /notifications, /notifications/read[/all], /mcp, /health, /ready);
• discovery is service-aware in both directions — a route is advertised iff its backing service is present (no dead advertisement);
• the MCP discovery↔route lockstep holds (advertised ⇒ reachable, never 501).

It deliberately does not duplicate the Server-Timing coverage (#3384's server-timing-e2e.test.ts / rest-server-timing.test.ts), the notifications mark-read coverage (#3388), or the REST-owned /data·/meta·/ui coverage (@objectstack/client integration suite).

2. Documented the MCP discovery lockstep (http-dispatcher.ts, comment-only): why routes.mcp is advertised on the isMcpServerEnabled() flag (the #2698 auto-load lockstep) rather than gated on service presence — keeps the dispatcher symmetric with @objectstack/rest.

Test + comment only; no runtime code changes (no-release changeset).

Verification

• @objectstack/runtime: route-parity gate green; @objectstack/plugin-hono-server + @objectstack/client suites green locally.
• eslint / tsc --noEmit clean.

Note

An earlier revision also trimmed the standalone HonoServerPlugin discovery to advertise only its mounted routes (/data + /auth/me/*). That was dropped: it's a shadowed fallback path (never served under real os serve), and it changed a discovery contract the @objectstack/client suite depends on (client.hono.test.ts expects metadata advertised). Not worth altering a cross-package contract for a shadowed path; can be revisited deliberately if desired.

Refs: #3369, #3361 (fixed in #3384), #3362 (#3354 / #3388), #2698, #3358.

🤖 Generated with Claude Code

https://claude.ai/code/session_015si15Q1KWMKpVQWYsEvgcS

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 21, 2026 3:03pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/runtime.

17 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/api/index.mdx (via @objectstack/runtime)
• content/docs/api/wire-format.mdx (via @objectstack/runtime)
• content/docs/automation/hook-bodies.mdx (via @objectstack/runtime)
• content/docs/concepts/north-star.mdx (via packages/runtime)
• content/docs/data-modeling/drivers.mdx (via @objectstack/runtime)
• content/docs/deployment/index.mdx (via @objectstack/runtime)
• content/docs/deployment/production-readiness.mdx (via @objectstack/runtime)
• content/docs/deployment/single-project-mode.mdx (via @objectstack/runtime)
• content/docs/deployment/vercel.mdx (via @objectstack/runtime)
• content/docs/getting-started/your-first-project.mdx (via @objectstack/runtime)
• content/docs/permissions/authentication.mdx (via @objectstack/runtime)
• content/docs/permissions/authorization.mdx (via packages/runtime)
• content/docs/plugins/packages.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/http-protocol.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/index.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/lifecycle.mdx (via @objectstack/runtime)
• content/docs/releases/implementation-status.mdx (via @objectstack/runtime)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.