spec: Define adapter-level caching and pre-fetch strategy for slow transports

[mickdarling]

Summary

Native transports (AppleScript, serial, IPC) can be orders of magnitude slower than HTTP APIs due to per-operation IPC overhead. The Apple Mail adapter demonstrated this: listing 3 messages from a 1,600-message mailbox takes 10+ seconds, and larger mailboxes time out entirely.

The pipeline needs a standard caching/pre-fetch strategy for slow transports.

Problem

AppleScript communicates via Apple Events — each property access is a cross-process IPC round trip. For a list_messages operation returning 5 messages with 7 properties each, that's 35 IPC calls minimum. For a mailbox with 100k+ messages, even mailbox.messages() enumeration times out.

This isn't specific to Apple Mail. Any native transport will have similar IPC overhead:

• D-Bus on Linux (per-property IPC)
• Serial/USB (per-command round trip)
• COM/OLE on Windows (per-property IPC)

Proposed Solutions

1. Batch Property Access (Template-Level)

JXA supports batch property reads:

// SLOW: N IPC calls
for (var i = 0; i < msgs.length; i++) {
  result.push({ subject: msgs[i].subject(), sender: msgs[i].sender() });
}

// FAST: 2 IPC calls total
var subjects = mailbox.messages.subject();
var senders = mailbox.messages.sender();

The template research stage (#238) should identify batch-accessible properties and generate batch templates.

2. Local Index Cache (Server-Level)

The MCP server maintains a local SQLite/JSON cache:

• Periodic sync from the native source (e.g., every 5 minutes)
• Queries hit the cache first
• Mutations write-through to the native source and update the cache
• Cache invalidation on write operations

3. Incremental Sync

For large datasets, full refresh is impractical. The server should track:

• Last sync timestamp
• New/modified/deleted items since last sync
• Use native notification mechanisms where available (e.g., Mail's new mail arrived notification)

4. Pipeline Integration

The adapter onboarding pipeline (#236) should include a performance profiling step that:

• Measures per-operation latency
• Identifies operations that need caching
• Recommends batch patterns where available
• Sets appropriate timeout values in the adapter schema

Acceptance Criteria

• Caching strategy specified (cache location, format, TTL, invalidation)
• Batch property access documented as a template optimization pattern
• Incremental sync model defined
• Performance profiling step added to pipeline (spec: Define adapter onboarding pipeline — end-to-end workflow for new API targets #236)
• Interaction with adapter schema (cache config, timeout config) defined

References

• Apple Mail pipeline walkthrough: spec: Define adapter onboarding pipeline — end-to-end workflow for new API targets #236 (comment)
• Template research stage: spec: Define template research and authoring stage for native adapter pipeline #238
• Apple Event IPC overhead: inherent to Open Scripting Architecture