test(runtime): e2e regression for notifications mark-read on the hono server (#3362)

[os-zhuang]

Closes#3362.

TL;DR

#3362 does not reproduce on current main. The in-app notifications surface works end-to-end on the standalone os dev / os serve (hono) server — routes are mounted, the service resolves, and mark-read persists. #3354's fix is effective. What was missing is a test that actually proves it, so this PR adds the end-to-end regression test the issue asked for.

What the issue claimed vs. what actually happens

The issue reported that GET /api/v1/notifications and POST /api/v1/notifications/read[/all] return 404 on the hono server, blaming the dispatcher-plugin's route registrations for "not landing on the hono app."

I verified empirically by building main and booting the real CLI (objectstack dev --fresh) against both the CRM and showcase examples:

Request	Result on real os dev (hono)
GET /api/v1/notifications (unauth)	401 — route reachable, self-gated (not a 404)
GET /api/v1/notifications (auth)	200{ notifications, unreadCount }
POST /api/v1/notifications/read/all (auth)	200{ success, readCount }
discovery services.notification	status: "available" (declared === enforced)
full cycle with a real digest notification	unread count drops 1 → 0, receipts flip to read

Supporting evidence that the dispatcher's routes do bind to the hono listener:

• /ready (dispatcher-only route) → 200, already covered by dispatcher-plugin.ready.integration.test.ts.
• /keys (dispatcher-only) → 401 (reaches the handler).
• /mcp → the dispatcher's ownhandleMcp 501 ("MCP server is not available"), not a "hono-native handler" — so the premise that dispatcher registrations don't reach hono is incorrect.

The notification routes were added by #3354 (ee0a499) and have not been touched since, so main reflects post-#3354 behavior. The most likely cause of the original 404 is a stale @objectstack/runtime dist (a common monorepo gotcha: os dev loads packages/runtime/dist, which must be rebuilt after pulling source changes).

The real gap: coverage

The only prior guard (dispatcher-plugin.routes.test.ts) asserts route registration against a fake server. It cannot catch a real unmounting on hono, a notification-service resolution break, or a receipt-persistence regression — exactly the failure modes the issue feared.

Change

Adds packages/runtime/src/notifications.hono.integration.test.ts — a real end-to-end integration test (same style as the existing /ready integration test):

• Boots the actual stack: in-memory driver + ObjectQLPlugin + MessagingServicePlugin + a minimal auth service + HonoServerPlugin + createDispatcherPlugin, on a real socket.
• Delivers notifications through the real messaging pipeline, then drives mark-read over fetch exactly like the Console bell.
• Asserts: discovery reports the service available; an unauthenticated request self-gates with 401 (route reachable, not a 404); listing shows the unread count; POST /read and POST /read/all flip the sys_notification_receipt rows to read and drop the unread count to 0.

It is a real guard, not a vacuous one: temporarily disabling the three server.<verb>() notification mounts in the dispatcher plugin makes it fail (404 instead of 401/200).

Also adds @objectstack/service-messaging as a devDependency of @objectstack/runtime (test-only; messaging does not depend on runtime, so there is no dependency cycle).

Testing

• New test: 3/3 pass.
• Full @objectstack/runtime suite: 40 files / 580 tests pass.
• Related suites (dispatcher-plugin.routes, dispatcher-plugin.ready.integration, http-dispatcher): pass.
• tsc --noEmit and eslint clean; @objectstack/runtime builds.

No changeset (test-only, no user-facing runtime change).

🤖 Generated with Claude Code

---

Generated by Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
spec	Canceled		Jul 21, 2026 2:22pm

[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.