​

spec_id: SPEC-058 version: v0.1 status: draft authored_by: Donna date: 2026-04-30

​

SPEC-058 — Signal Delivery Single-Source-of-Truth

​

Status

​

Problem

​

Why this is structural, not cosmetic

​

Pre-port working contract (the thing we lost)

# Two sources, merged and de-duplicated by ``signal_id``:
#   1. In-process strategy buffer (drain_buffered)
#   2. Backend HTTP drain (poll_pending_signals — atomic mark+return)
#
# SPEC-037 §3 — de-dupe by signal_id. In-cluster agents may see the
# same signal from both paths; LAN clients only see the backend path.
# Either way, never deliver the same signal twice.
collected = list(result.get("pending_signals") or [])
collected.extend(strategy.drain_buffered())
collected.extend(await client.poll_pending_signals(...))
deduped = [s for s in collected if seen.add(s["signal_id"])]
result["pending_signals"] = deduped

1. Universal coverage. Every non-lifecycle verb response carried any pending signals — agents saw new arrivals in the next conversational turn without explicit polling.
2. Two-source robustness. Push (LAN-cluster Redis subscriber) and pull (HTTP backend drain) both fed into the same merge point — either failing alone never lost a signal.
3. Single-delivery invariant. Deduplication by signal_id ensured one logical signal was reported exactly once, no matter how many transport paths happened to carry it.

​

Current Node implementation (the gap)

​

Backend-side amplifier

• The function is racing with drain_for_caller (which stamps 'piggyback' on every prism_signals_pending call), or
• The function is silently no-op’ing (no log lines in either backend or session-manager containers indicate either success or failure).

​

Goals

1. Single-delivery invariant. A signal_id reaches the agent’s pending_signals[] field at most once, regardless of how many transport paths carried it.
2. Universal coverage. Every non-lifecycle verb response carries any pending signals — same as Python had.
3. Two-source robustness. Push (WS) and pull (HTTP drain) both feed the merge point; either path failing alone never loses a signal.
4. Honest delivery accounting. signal_queue.delivered_at and delivery_method reflect what actually happened, not whichever drain raced first.
5. Port-miss prevention. A single test catches the entire family of SPEC-054-class regressions on any future cross-language port.

​

Non-goals

• Changing the wire envelope (SPEC-045 §4.2). Same shape on the WebSocket.
• Changing the categories taxonomy (SPEC-052 §3). INFO/TASK/ASK/BLOCKER unchanged.
• Changing the doorbell semantics (SPEC-044 §3.3). One coalesced notification per drain cycle, unchanged.
• Reworking SPEC-056 routing or schema. The agent_id channel + four-level hierarchy are unaffected.
• Adding any new transport. WS push and HTTP poll are the two paths; this spec just insists on a clean merge over them.

​

Architecture

​

One merge function, called from two sites

// mcp-node/src/signalMerge.ts (NEW)
//
// SPEC-058 — single merge point for the two pending-signal sources.
// Used by:
//   1. server.ts every-verb piggyback hook (non-lifecycle verbs)
//   2. coordination.ts:prism_signals_pending verb handler
//
// Contract (SPEC-037 §3):
//   - Drains both the local strategy buffer AND the backend
//     /signal/poll endpoint.
//   - Deduplicates the union by signal_id.
//   - Records each unique signal into the per-identity cache (idempotent).
//   - Returns the deduped list — the only place pending_signals[] is built.
//
export async function mergeAndDedupPending(
  client: PrismClient,
  pid: string,
  identity: string,
): Promise<PrismSignal[]> {
  const local = (getActiveStrategy()?.drainBuffered() ?? []) as PrismSignal[];
  let remote: PrismSignal[] = [];
  try {
    remote = (await client.pollPendingSignals(pid, identity)) as PrismSignal[];
  } catch (exc) {
    log.warn("backend drain failed (non-fatal)", { exc });
  }

  const seen = new Set<string>();
  const merged: PrismSignal[] = [];
  for (const sig of [...local, ...remote]) {
    const sid = sig?.signal_id;
    if (!sid || seen.has(sid)) continue;
    seen.add(sid);
    merged.push(sig);
    await signalCache.record(sig, identity); // idempotent by sid
  }
  return merged;
}

​

Call sites

​

Backend stamping race resolution

1. Priority order via UPDATE conditional: mark_delivered_via_ws already has WHERE delivered_at IS NULL; drain_for_caller does too. Order is whoever commits first. Acceptable.
2. Add log instrumentation: mark_delivered_via_ws should log at INFO (not DEBUG) on every fire — both successful (rowcount=1) and silent-loss (rowcount=0, meaning piggyback won the race). Today’s container logs show neither, which is the diagnostic gap that hid this for 24h. INFO logs would have surfaced “channels_push attempted, raced lost — piggyback claimed” frequency immediately.
3. Retain the priority preference in display. When both stamps exist on a row across its lifetime (impossible due to WHERE clause but if it ever happened), the row would be channels_push since whichever wrote first wins. No additional code needed.

​

Files changed

​

Test plan — port-miss prevention

TEST: signal_delivery_single_source_of_truth (E2E, real backend, real WS, two real MCP processes)

GIVEN  Agent A and Agent B, both bootstrapped on a real backend
       (one Postgres, one Redis, both MCP processes are real Node shims).

WHEN   A calls prism_signal(to=B, ...) returning signal_id=X
       — wait for the WS push to land at B (≤2s).
       — B calls prism_signals_pending.

THEN
  1. B's pending_signals[] contains EXACTLY ONE entry with signal_id=X.
     (Catches port miss #6 — dedup at merge.)
  2. signal_queue row for X has delivered_at != NULL.
     (Catches both #1 — WS auth — and the backend stamping defects.)
  3. B's per-identity ring file contains ONE entry for signal_id=X.
     (Catches #2 — signalCache port miss.)
  4. B observed a `<channel>` doorbell within 2s of A's send.
     (Catches #3 — capability flag — and #4 — channel push wiring.)
  5. Send a second signal Y immediately after X. B observes a SECOND
     doorbell (not coalesced) AFTER B has called prism_signals_pending.
     (Catches #5b — coalescing reset on drain.)
  6. Repeat with Codex agent for B — expect the same single-delivery
     and same `delivery_path: turn_start` (or piggyback fallback if
     app-server is off in the test env).
     (Catches #5 — codex strategy.)

  Total: ONE TEST covers all six port misses + the dedup contract.

​

Acceptance criteria

1. mcp-node/src/signalMerge.ts exists and is the only place pending_signals[] is constructed.
2. server.ts and coordination.ts both call mergeAndDedupPending — no inline concat or strategy-only drain remains.
3. The fan-out test from this morning (Donna → 4 agents, 4 acks back) returns each ack EXACTLY ONCE in prism_signals_pending.
4. After 10 signals between two connected agents, ≥80% of signal_queue rows show delivery_method='channels_push' (validates WS stamping is firing more often than piggyback).
5. The end-to-end test in §test plan passes on a fresh backend with two real Node MCP processes.
6. The cross-language port-miss family — points 1-5b above — each have a dedicated assertion in the E2E test.

​

Phased rollout

​

Out of scope

• Federation, cross-tenant signals (SPEC-056 covers).
• Replacing the WebSocket transport with anything else.
• Coalescing tuning. The current SPEC-044 §3.3 boolean flag is correct.
• Cleanup of the legacy session channel — that drops naturally when SPEC-056 cutover completes.

​

References

• Specs: SPEC-034 (signal delivery), SPEC-037 (backend piggyback + dedup contract), SPEC-044 (channel push), SPEC-045 (WS data plane), SPEC-048 (codex), SPEC-052 (signal cache), SPEC-054 (Node MCP shim — the port).
• Memories (port miss family): project_spec_054_port_miss_project_id, project_spec_054_port_miss_coalescing_reset, feedback_document_port_misses.
• ADRs: ADR #34 (agent_id channel), ADR-25 (lifecycle ≠ messaging multiplex).
• Live evidence (this session): signal_queue distribution showing 22 piggyback / 1 channels_push for last 24h; fan-out test #3 returning duplicate acks via prism_signals_pending.

​

Authorship