chore(apps): consolidate accessor implementation to runtime (4/4)

Merged
D-
3mo ago
+1131-1580

Proposed changes

This PR adds a comprehensive design document that outlines a phased plan to consolidate accessor logic from packages/apps/src/server/accessors/ into the base-runtime, eliminating the need for the accessor:* JSON-RPC message category and making the base-runtime the single source of truth for accessor behavior.

Key points from the plan:

Current state: Accessor calls from apps take three paths:

  1. Pure proxy via accessor:* messages (forwarded to host)
  2. Local implementation + direct bridge calls
  3. Fully local implementation

Target state: Consolidate all accessor logic into the base-runtime, with side effects flowing through the existing bridges:* RPC channel.

Scope: The document analyzes all ~30 accessor classes and classifies them as:

  • MOVE: Implement in base-runtime (port host logic)
  • RECONCILE: Already in base-runtime; make canonical and delete host copy
  • BRIDGE-GAP: Requires new AppResourceBridge for registration/settings operations
  • DELETE: Dead code on the host

Key design decisions:

  • Runtime behavior supersedes host behavior where they've drifted (runtime is canonical since it's what apps actually use)
  • Introduces RemoteBridges facade for typed bridge access in the runtime
  • Adds AppResourceBridge to handle registration operations (slash commands, APIs, settings, etc.) through the existing bridges:* channel
  • Normalizes all app-identity parameters to use 'APP_ID' placeholder for anti-impersonation
  • Moves UIHelper into base-runtime to resolve module-resolution constraints

Phased rollout:

  • Phase 0: Foundations (RemoteBridges, refactor existing accessors, move UIHelper)
  • Phase 1: Reader family + Persistence + Environment
  • Phase 2: Modify family completion
  • Phase 3: Registration surface via AppResourceBridge
  • Phase 4: Teardown (delete handleAccessorMessage and host accessor code)

End result: Single RPC category (bridges:*) with unified dispatcher, permission model, and accessor implementation in base-runtime.

Issue(s)

Related Jira task: ARCH-2185: reunite duplicated accessor implementations into a shared location

The design doc in this PR is the specification for that task.

Steps to test or reproduce

N/A — This is a design document, not executable code.

Further comments

This document represents significant architectural work to improve code organization and eliminate technical debt. It includes:

  • Detailed analysis of all accessor classes and their dependencies
  • Identification and resolution of behavioral drift between runtime and host implementations
  • Comprehensive design for the new AppResourceBridge to close gaps
  • Clear phased implementation plan that keeps both test suites green
  • Explicit trade-offs and follow-up work items

The plan is ready for review and discussion before implementation begins.

https://claude.ai/code/session_018FbxFGJWHiroxrdNPJRL3P

Summary by CodeRabbit

  • Improvements
    • Standardized how app runtime accessors invoke host operations via a shared bridge-call pathway, improving consistency across messaging, rooms, users, settings, live chat, uploads, scheduling, notifications, persistence, and UI interactions.
    • Kept request/response semantics aligned, with clarified “not found/unavailable” outcomes for a few read operations while preserving existing error handling.
  • Tests
    • Expanded and rewired test coverage to validate bridge routing, payload structure, and error propagation.
  • Documentation
    • Updated the access architecture documentation and removed outdated proposal materials.
  • Refactor
    • Removed the legacy accessor RPC handling path and centralized resource bridge usage in runtime/subprocess wiring.