refactor(runtime-host): consolidate host change broadcasts

[CxHsin]

Summary

Fixes #3217

Consolidate the four cloned Runtime Host change broadcast services into one grant-filtered HostChangeFeed. Each connection now has one subscription handle and a mask derived from its operation grants. The existing four protocol frame kinds, payloads, and revision semantics remain unchanged.

The old per-domain service files and duplicated connection lifecycles are removed. Focused tests cover grant isolation, independent revisions, send-failure cleanup, and migrated lifecycle fixtures.

Verification

• npm --workspace @maka/runtime-host run typecheck -- --pretty false
• npm --workspace @maka/runtime-host run build
• npx biome check packages/runtime-host/src/server packages/runtime-host/src/__tests__/host-change-feed.test.ts packages/runtime-host/src/__tests__/host-kernel.test.ts packages/runtime-host/src/__tests__/project-catalog-coordinator.test.ts
• node --test packages/runtime-host/dist/__tests__/host-change-feed.test.js packages/runtime-host/dist/__tests__/project-catalog-coordinator.test.js

The focused checks pass. The full runtime-host suite was also run; one unrelated host-kernel shutdown scenario failed with an existing-style write EPIPE race (answers an admitted bootstrap with draining after shutdown commits).

Review focus

• Verify per-grant routing cannot disclose unrelated change frames.
• Verify configuration, project catalog, and session catalog revisions remain independent.
• Verify scheduled-task revisions remain supplied by the scheduled-task coordinator.
• Verify failed sends remove only the current subscription identity.

AI use

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope: Codex performed the implementation, tests, code review, and PR preparation. A human contributor must review and own the submission.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 113680c0-31cd-487c-8f0c-d5a3458b86b8

📥 Commits

Reviewing files that changed from the base of the PR and between 7bb776b and 55d8d5f.

📒 Files selected for processing (13)

• packages/runtime-host/src/__tests__/host-change-feed.test.ts
• packages/runtime-host/src/__tests__/host-kernel.test.ts
• packages/runtime-host/src/__tests__/project-catalog-coordinator.test.ts
• packages/runtime-host/src/server/configuration-change-service.ts
• packages/runtime-host/src/server/connection-session.ts
• packages/runtime-host/src/server/execution-composition.ts
• packages/runtime-host/src/server/host-change-feed.ts
• packages/runtime-host/src/server/host-kernel.ts
• packages/runtime-host/src/server/project-catalog-change-service.ts
• packages/runtime-host/src/server/project-catalog-coordinator.ts
• packages/runtime-host/src/server/scheduled-task-change-service.ts
• packages/runtime-host/src/server/scheduled-task-coordinator.ts
• packages/runtime-host/src/server/session-catalog-change-service.ts

💤 Files with no reviewable changes (4)

• packages/runtime-host/src/server/session-catalog-change-service.ts
• packages/runtime-host/src/server/configuration-change-service.ts
• packages/runtime-host/src/server/project-catalog-change-service.ts
• packages/runtime-host/src/server/scheduled-task-change-service.ts

🚧 Files skipped from review as they are similar to previous changes (9)

• packages/runtime-host/src/tests/host-change-feed.test.ts
• packages/runtime-host/src/server/host-kernel.ts
• packages/runtime-host/src/server/project-catalog-coordinator.ts
• packages/runtime-host/src/tests/project-catalog-coordinator.test.ts
• packages/runtime-host/src/server/scheduled-task-coordinator.ts
• packages/runtime-host/src/server/host-change-feed.ts
• packages/runtime-host/src/server/execution-composition.ts
• packages/runtime-host/src/tests/host-kernel.test.ts
• packages/runtime-host/src/server/connection-session.ts

Included review availability: Your plan provides up to 3 included reviews per hour; 0 remain after this review.

---

📝 Walkthrough

Summary

This PR consolidates four duplicated Runtime Host change services into one HostChangeFeed. The feed uses grant-derived subscription masks and one connection registry. It preserves the four protocol frame kinds, payloads, and per-domain revision semantics.

The PR extends the existing notification path. Coordinators publish through the shared feed, and connection sessions use one subscription handle. It does not create a parallel notification path.

The solution is the smallest coherent design described by the diff. The subscription mask and feed-managed state are required for grant isolation, routing, independent revisions, and failure cleanup.

The deleted service files and duplicated connection fields can remain removed. The migrated tests preserve coverage for routing, revisions, failed-send cleanup, and composition wiring. The added feed tests centralize behavior coverage.

The summary reports typechecking, build, formatting/lint checks, and focused tests. The full suite reported one unrelated existing write EPIPE shutdown race. Final required-check status is unverified here.

Complexity delta

• Authorities: Removes four change-service authorities and adds one HostChangeFeed authority.
• State: Removes four connection registries and duplicated lifecycle state. Adds one subscription registry, one grant mask per subscription, and feed-managed revisions.
• Branches: Removes duplicated attach, close, and send-failure branches. Adds mask-based routing branches.
• Configuration: Replaces four resolver options with one optional resolveHostChanges() resolver.
• Public surface: Removes four service classes and connection interfaces. Adds HostChangeFeed, HostChangeSubscription, HostChangeFrame, HostChangeKind, and HostChangeSubscriptionMask.
• Test maintenance: Centralizes feed behavior tests and simplifies migrated fixtures.

Total maintenance complexity decreases. The added subscription and mask state is necessary for the consolidated, grant-filtered design.

Review-relevant risks

• Grant-derived subscription masks control access to change notifications. An incorrect mask could expose notifications across domains. Any material security change requires independent human review under repository policy.
• The session and composition contracts change from four resolvers and fields to one optional feed. Consumers and integrations may require migration. Any material public-contract change requires independent human review under repository policy.
• Revision tracking and failed-send cleanup now use one implementation for all four domains. A feed defect could affect multiple change domains and alter user-visible notifications. Any material behavior change requires independent human review under repository policy.
• The full-suite result includes an unrelated existing write EPIPE shutdown race. Required check status is unverified here.

The person performing the merge reviews the final diff. A maintainer makes the final determination.

Walkthrough

The runtime host consolidates four change services into HostChangeFeed. It adds masked subscriptions, independent catalog revisions, failure cleanup, unified connection-session wiring, and shared publication through runtime composition. Tests cover routing, revisions, cleanup, and integration.

Changes

Host change feed consolidation

Layer / File(s)	Summary
Feed contract and delivery packages/runtime-host/src/server/host-change-feed.ts, packages/runtime-host/src/__tests__/host-change-feed.test.ts	Adds masked subscriptions and publication for four host-change kinds. Catalog revisions remain independent. Failed deliveries remove subscriptions.
Composition and publisher wiring packages/runtime-host/src/server/execution-composition.ts, packages/runtime-host/src/server/host-kernel.ts, packages/runtime-host/src/server/project-catalog-coordinator.ts, packages/runtime-host/src/server/scheduled-task-coordinator.ts, packages/runtime-host/src/server/*-change-service.ts, packages/runtime-host/src/__tests__/project-catalog-coordinator.test.ts	Exposes one shared feed and routes all change notifications through it. Removes the four specialized change services and updates coordinator contracts.
Connection subscription integration packages/runtime-host/src/server/connection-session.ts, packages/runtime-host/src/__tests__/host-kernel.test.ts	Resolves one feed, derives its mask from authorization grants, forwards frames through the bounded writer, and closes the unified subscription during cleanup.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 55d8d

The change consolidates host-change broadcasts while preserving grant filtering, frame formats, and revision semantics. No actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: consolidating Runtime Host change broadcasts.
Description check	✅ Passed	The description includes the required summary, issue reference, verification results, AI disclosure, checklist, and relevant review focus.
Linked Issues check	✅ Passed	The implementation satisfies #3217 by unifying subscriptions, preserving frame and revision semantics, filtering by grants, and removing duplicated services.
Out of Scope Changes check	✅ Passed	The code and test changes remain within the linked issue's consolidation and lifecycle-migration objectives.
Ai Use Disclosure	✅ Passed	The description selects only generative tooling, names Codex and its scope, and both the PR commit and merge commit contain standalone Generated-by: Codex trailers.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

PR Summary by Qodo

Consolidate Runtime Host change broadcasts

✨ Enhancement 🧪 Tests 🕐 20-40 Minutes

AI Description

• Replaces four duplicated broadcast services with one grant-filtered HostChangeFeed.
• Preserves existing frame formats and independent domain revision semantics.
• Adds coverage for grant isolation, revision independence, and failed-send cleanup.

Diagram

graph TD
  P["Domain Publishers"] --> F["Host Change Feed"] --> D{"Grant Allowed"} -->|Yes| W["Frame Writer"] --> C["Client Connection"]
  S["Connection Session"] --> M["Grant Mask"] --> F
  D -->|No| X["Skip Frame"]

Loading

High-Level Assessment

The consolidated feed is the strongest approach because it removes duplicated registries and connection lifecycles while preserving domain-specific frames and revisions. A shared generic broadcaster with four service instances was considered, but it would retain multiple subscription handles and scatter grant routing across the connection session.

Files changed (9) +281 / -188

Refactor (6) +184 / -162

connection-session.tsConsolidate connection change subscriptions +38/-124

Consolidate connection change subscriptions

• Replaces four service resolvers and subscription handles with one 'HostChangeFeed' subscription. Derives its mask from operation grants and closes the single handle during drain or teardown.

packages/runtime-host/src/server/connection-session.ts

execution-composition.tsWire all host changes through one feed +16/-19

Wire all host changes through one feed

• Creates one 'HostChangeFeed' and routes configuration, project, session, and scheduled-task publishers through it. Exposes the feed on the runtime composition instead of four domain services.

packages/runtime-host/src/server/execution-composition.ts

host-change-feed.tsIntroduce grant-filtered HostChangeFeed +120/-0

Introduce grant-filtered HostChangeFeed

• Adds the unified subscription registry and typed mask for four host change domains. Preserves separate configuration, project, and session revision counters, accepts coordinator-owned scheduled-task revisions, and safely removes failed subscription identities.

packages/runtime-host/src/server/host-change-feed.ts

host-kernel.tsExpose the unified feed to connection sessions +3/-12

Expose the unified feed to connection sessions

• Replaces four optional composition change services with one host feed. Connection sessions now resolve that feed when attaching global change notifications.

packages/runtime-host/src/server/host-kernel.ts

project-catalog-coordinator.tsDepend on minimal change publisher interfaces +2/-4

Depend on minimal change publisher interfaces

• Replaces concrete project and session change-service dependencies with narrow structural publisher contracts, allowing composition adapters to delegate into the unified feed.

packages/runtime-host/src/server/project-catalog-coordinator.ts

scheduled-task-coordinator.tsGeneralize scheduled-task change publisher dependency +5/-3

Generalize scheduled-task change publisher dependency

• Replaces the deleted concrete change service type with a minimal publisher contract. Scheduled-task revisions and event details continue to originate from the coordinator.

packages/runtime-host/src/server/scheduled-task-coordinator.ts

Tests (3) +97 / -26

host-change-feed.test.tsTest filtered routing and subscription cleanup +69/-0

Test filtered routing and subscription cleanup

• Adds focused tests proving that change frames are restricted by subscription masks. Verifies independent catalog revisions and removal of a failed subscription without affecting healthy subscribers.

packages/runtime-host/src/tests/host-change-feed.test.ts

host-kernel.test.tsMigrate kernel lifecycle fixture to HostChangeFeed +5/-8

Migrate kernel lifecycle fixture to HostChangeFeed

• Updates the non-serving kernel fixture to expose one host change feed and publish configuration and session events through its domain methods.

packages/runtime-host/src/tests/host-kernel.test.ts

project-catalog-coordinator.test.tsMigrate catalog tests to combined subscriptions +23/-18

Migrate catalog tests to combined subscriptions

• Replaces separate project and session change services with a shared feed. Configures masks per test connection and separates received frames by protocol kind.

packages/runtime-host/src/tests/project-catalog-coordinator.test.ts

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can show, collapse, or hide each part of a finding: code, evidence, and all

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 9159c2a4-9595-4e9b-a627-4e0ef22573af

📥 Commits

Reviewing files that changed from the base of the PR and between d2d0121 and d6647a3.

📒 Files selected for processing (13)

• packages/runtime-host/src/__tests__/host-change-feed.test.ts
• packages/runtime-host/src/__tests__/host-kernel.test.ts
• packages/runtime-host/src/__tests__/project-catalog-coordinator.test.ts
• packages/runtime-host/src/server/configuration-change-service.ts
• packages/runtime-host/src/server/connection-session.ts
• packages/runtime-host/src/server/execution-composition.ts
• packages/runtime-host/src/server/host-change-feed.ts
• packages/runtime-host/src/server/host-kernel.ts
• packages/runtime-host/src/server/project-catalog-change-service.ts
• packages/runtime-host/src/server/project-catalog-coordinator.ts
• packages/runtime-host/src/server/scheduled-task-change-service.ts
• packages/runtime-host/src/server/scheduled-task-coordinator.ts
• packages/runtime-host/src/server/session-catalog-change-service.ts

💤 Files with no reviewable changes (4)

• packages/runtime-host/src/server/scheduled-task-change-service.ts
• packages/runtime-host/src/server/project-catalog-change-service.ts
• packages/runtime-host/src/server/configuration-change-service.ts
• packages/runtime-host/src/server/session-catalog-change-service.ts

Included review availability: Your plan provides up to 3 included reviews per hour; 1 remains after this review.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[Astro-Han]

Approved on exact head 55d8d5fb9.

The consolidation preserves the four public frame kinds and independent revision sources while replacing duplicated services with one grant-filtered subscription. Connection grants map correctly to the four masks, teardown removes the unified handle, and failed-send cleanup remains identity-safe. I found no remaining P0–P2 correctness issue. The resolved CodeRabbit suggestion to count failed test sends directly is a nonblocking P3 coverage improvement and is not duplicated.

This is a Runtime Host refactor with no user-visible UI/UX change, so screenshots are not applicable. The PR body and both commits have complete Codex disclosure/trailers. Some required jobs are still pending; approval is code-level, and merge readiness still requires all checks green.

Reviewed with Codex as an AI-assisted code review. I verified the exact-head delta against current main, grants, revisions, subscription lifecycle, tests, CI, UI scope, and commit provenance; no external model output was used.

中文说明

当前 head 的代码审查通过：四类 frame 与独立 revision 保持不变，grant mask、统一 subscription 和 teardown/失败清理都正确，未发现剩余 P0–P2。该 PR 是 Runtime Host 重构，不涉及用户可见 UI/UX，因此无需截图；PR body 与两个 commit 的 Codex 说明完整。仍有 required jobs 在运行，所以这是代码层 APPROVE，只有全部 CI 变绿后才算 merge-ready。

[Astro-Han]

Human merge confirmation: Astro-Han reviewed the final diff at 55d8d5fb9c and explicitly authorized this squash merge. All required checks are green, the current head is approved, AI provenance is complete, and there are no unresolved review threads. The squash commit will retain Generated-by: Codex.