Authored by Claude Opus 4.7 (Claude Code). Session aaf22f06-cc5c-4dff-aa2f-7d5efb3a6343.

Summary

Implements the token-economy throttle / coalescing engine for the Phase 3 cross-harness autonomous wake substrate (Epic #10357). Per ADR 0002 §6.4, wake events MUST NOT be 1:1 with the underlying event stream at high velocity — broadcast bursts and Task transition flurries cause catastrophic token burn and session thrashing without this throttle.

Resolves #10362.

Why this exists now

Foundational for Shape A + Shape B in-process delivery. Shape C (bridge daemon) coalesces in its own out-of-process queue per ADR §6.3 (already shipped via #10381). With #10378's WakeSubscriptionService schema + resync boundary contract on dev, this engine is the natural next layer: matched events go in, digests come out, dispatch routes to the channel matching subscription.harnessTarget.

Changes (2 files, +505 / -0)

1. ai/mcp/server/memory-core/services/CoalescingEngineService.mjs (NEW, 246 lines)

Singleton extending Neo.core.Base (per the canonical sibling pattern in PermissionService / MailboxService / WakeSubscriptionService). Public surface:

• enqueue(subscription, event) — adds event to per-subscription queue, starts (or extends) timer, schedules dispatch at window-fire
• flushAll() — force-flush all subscriptions immediately (graceful shutdown / tests)
• clearAll() — cancel timers + drop state without dispatching (test reset)

Per-subscription state lives in coalesceState: Map<subscriptionId, {queue, timer, subscription, windowStart}>. Timer-fire callback _flush builds the digest envelope and dispatches.

Window resolution (ADR §6.4.1):

• Default 30s; overridable per subscription via harnessTargetMetadata.coalesceWindow (in seconds)
• Clamped to [0, 300] — 0 = immediate-flush; max 5 minutes
• Override of 0 triggers synchronous flush at enqueue time (no timer)

Digest envelope (ADR §6.4.2): Wrapped in standard notification envelope (schemaVersion: '1.0', eventType: 'wake/digest', fresh eventId ULID, logId of last queued event for cursor-based catchup, agentIdentity, subscriptionId, emittedAt). Payload structure:

{
  "totalEvents": 3,
  "breakdown": {
    "sent_to_me":         {"count": 2, "latest": {messageId, from, ...}},
    "task_state_changed": {"count": 1, "latest": {taskId, newState, ...}},
    "permission_granted": {"count": 0, "latest": null}
  },
  "windowMs": 30000
}

latest retains the most recent payload per trigger type so consumers have context without needing the full event list.

Dispatch routing (ADR §6.4 + §6.5):

2. test/playwright/unit/ai/mcp/server/memory-core/services/CoalescingEngineService.spec.mjs (NEW, 192 lines)

15 tests covering:

• Window resolution (5): default fallback, override honored, negative clamps to 0, over-300 clamps to 300, 0 triggers immediate-flush
• Coalescing behavior (4): multi-event single-digest within window, immediate-flush synchronous, latest-payload-per-type retained, last-event logId preserved
• Dispatch routing (4): a2a-webhook calls WebhookDeliveryService.deliver, mcp-notifications no-op pending #10358, bridge-daemon no-op, disabled no-op
• Lifecycle (3): flushAll force-flushes pending, clearAll cancels timers, per-subscription state isolation

WebhookDeliveryService.deliver is mocked per-test to assert dispatch behavior; original method is restored in afterAll. Symmetric beforeEach + afterEach clearAll() per feedback_symmetric_spec_cleanup.md — Playwright's fullyParallel can interleave specs in the same worker; cross-singleton state must be reset symmetrically.

Acceptance Criteria — verification

• 30-60s coalescing window — default 30s; overridable per subscription via harnessTargetMetadata.coalesceWindow (ADR §6.4.1)
• Digest payload format — structured per ADR §6.4.2; eventType wake/digest for in-process consumers; literal-text injection deferred to Shape C's daemon (already shipped)
• Per-subscription coalesceWindow override respected — _resolveWindowMs reads override, clamps [0, 300]
• Built against ADR §6.4 contract — engine consumes events as data (matches resync-boundary green-lit on #10378), dispatches via per-subscription harnessTarget routing

Out of Scope

• Shape A MCP notifications emit-wiring — covered by #10358 (Gemini's parallel track). This PR's _dispatchDigest for mcp-notifications logs the digest pending that wiring; once #10358 lands, that branch routes through Shape A's notification dispatcher without touching this engine's contract.
• Live emit-point integration — MailboxService.addMessage / transitionTask / GraphService.linkNodes event emission into the engine is a separate integration step; this PR provides the engine surface; consumers wire when they're ready.
• Cross-process coalescing for Shape C — Shape C's bridge daemon has its own coalescer in ai/scripts/bridge-daemon.mjs per ADR §6.3.4 (READ-ONLY peer-process consumer of GraphLog). Symmetric implementation, distinct process boundaries.
• Telemetry / observability — coalesce-window-hit logging per subscription, average-batch-size telemetry, etc. Worth a follow-up if empirical patterns warrant tuning the default.

Provenance

Internal Origin — implements ADR 0002 §6.4 which I authored in prior sessions (48197e2e-... → 52e84f76-...). Discussion #10354 OQ 6 resolution with @neo-gemini-pro shaped the 30-60s window choice and per-subscription override semantics.

Related

• Parent Epic: #10357 (Phase 3 Cross-harness autonomous wake substrate)
• ADR: 0002 §6.4
• Predecessor (this PR consumes): #10378 (#10361 schema, merged) — WakeSubscriptionService.resync() boundary contract; harnessTargetMetadata.coalesceWindow property
• Sibling consumer (Shape B, already wired): #10379 (#10359 webhook, merged) — WebhookDeliveryService.deliver receives digests transparently
• Successor consumer (Shape A): #10358 (Gemini's parallel track) — wires mcp-notifications emit-point through the engine's dispatcher
• Out-of-process sibling: #10381 (#10360 bridge daemon, merged) — has its own coalescer per ADR §6.3.4

Test plan

• CI: Playwright unit suite runs CoalescingEngineService.spec.mjs (15 tests)
• Manual: enqueue 3 events on a single a2a-webhook subscription → verify single digest POST'd (via webhook test surface or live tmux observation if Shape A is wired)
• Cross-family review by @neo-gemini-pro — particularly on the digest envelope format (does the breakdown shape match what her Shape B receiver expects?) + the dispatch routing for mcp-notifications (logs-pending-wiring, ready for her #10358 to plug in)

Origin Session ID: aaf22f06-cc5c-4dff-aa2f-7d5efb3a6343