Zephr Docs

MCP fabric and event bus

Two platform-extension capabilities own the hosted surface layer: mcp-fabric is the installation-scoped catalog of hosted user MCP servers plus the observed deployment rows that mirror them; event-bus is the single publish surface that turns real producers (webhook ingress, recall handlers, report completion) into DispatchEvent envelopes consumed by the existing pure routing evaluator (evaluateRouting) and multi-channel dispatcher (dispatchEvent). It is additive over the shipped integration-routing substrate — it does not re-specify channel-adapter filter semantics or routing_rules CRUD.

Status at a glance

SurfaceStateEvidence
Routing-bus publish (publishRoutingEvent)Ships — closed set, spoof guard, idempotency, 11 live producers + countersapps/web/src/lib/cloud/routing-publisher.ts
finding.filed producerReserved, no producer yet → UI labels (no producers yet)routing-vocabulary.ts
MCP fabric catalog + deployment rowsShips — tables + data-access modules0313_mcp_fabric_catalog.sql, 0314_mcp_fabric_deployment.sql
Fabric provision executor (status → ready)Not wired — Wave 4spec W4
Fabric / host webhook UINot shipped — W1 has no UIspec comment

MCP fabric

Catalog

The catalog is the single registry for hosted user MCP servers. Each row is one of (installation_id, source declaration, isolation tier) — duplicates are refused:

CREATE TABLE mcp_fabric_catalog (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    installation_id UUID NOT NULL REFERENCES installation(id) ON DELETE RESTRICT,
    name            TEXT NOT NULL CHECK (length(name) BETWEEN 1 AND 120),
    source_kind     TEXT NOT NULL CHECK (source_kind IN ('git', 'oci', 'bring-remote')),
    source_ref      TEXT NOT NULL CHECK (length(source_ref) BETWEEN 1 AND 2000),
    isolation_tier  TEXT NOT NULL DEFAULT 'shared'
        CHECK (isolation_tier IN ('remote-proxy', 'shared', 'container')),
    verification_status TEXT NOT NULL DEFAULT 'unknown'
        CHECK (verification_status IN ('unknown', 'verifying', 'verified', 'failed')),
    env_refs        JSONB NOT NULL DEFAULT '{}'::jsonb
        CHECK (env_refs::text !~ '(sk-|AKIA[0-9A-Z]{16}|Bearer [A-Za-z0-9._~+/=-]{20,})'),
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    UNIQUE (installation_id, source_kind, source_ref, isolation_tier)
);
  • Verification is probe-owned. verification_status defaults to unknown and moves to verified only after a successful probe; it is never client-asserted. A create/update that supplies verification_status: 'verified' is stored as unknown and the supplied value is ignored.
  • Secrets are secret:// refs only. The same CHECK that defends managed_environment_revision.snapshot (0312) refutes sk-, AKIA…, and Bearer … literals in env_refs, so a catalog row is safe to hold as a config artifact.
  • RLS. ENABLE + FORCE row-level security keyed off tenant_installation_matches(); authenticated selects via auth_installation_matches(); writes are tenant_request/service_role only (no tenant DELETE — catalog rows are soft-lifecycle).

Deployment (observed state)

The catalog entry is desired state; a mcp_fabric_deployment row is the observed mirror — created when an operator asks the platform to provision a catalog entry from a git or oci source. The executor progresses it through pending → queued → dispatched → ready (or failed / terminated); the client opens the row only at pending, and cannot set ready itself — the route layer refuses a client status = 'ready' update (only the executor's service role writes non-pending transitions).

export type FabricDeploymentStatus =
  'pending' | 'queued' | 'dispatched' | 'ready' | 'failed' | 'terminated';

Data access lives in apps/web/src/lib/cloud/managed-environments/ (fabric-catalog.ts, fabric-deployments.ts) exposing listFabricDeployments, getFabricDeployment, and the McpFabricDeployment shape (incl. sourceSha, revisionId → managed_environment_revision.id, log).

Wiring to compute

The fabric isolation_tier is the placement key the compute plane consumes: remote-proxy | shared | container. Wave 4 wires provisionPod to these tiers — so the catalog and observed-state rows ship, but provisioning execution does not yet drive pods from a catalog entry.

Event / routing bus

The publish surface

export interface DispatchEvent {
  readonly event_type: string;
  readonly subject: { readonly type: 'repo' | 'project' | 'global'; readonly id: string | null };
  readonly timestamp: string; // ISO-8601 UTC
  readonly confidence?: number;
  readonly source?: string;
  readonly payload?: Record<string, unknown>;
  readonly caller_role?: string;
  readonly event_id: string; // stable; idempotency key with channel_id
  readonly installation_id: string; // resolved server-side, never body-claimed
}

publishRoutingEvent(client, event) (in routing-publisher.ts) is the single publish entrypoint. It:

  1. validates event_type against the closed set ROUTING_EVENT_TYPES (the authoritative CHECK on routing_rules.event_type); an unknown type throws RoutingPublishError with code invalid_event_type and writes no channel_deliveries row;
  2. resolves the tenant from the credential, refusing a body-claimed installation_id that differs from the resolved tenant (RoutingPublishError code tenant_claim_mismatch);
  3. loads enabled routing_rules for that installation (indexed priority ASC);
  4. runs the pure evaluator evaluateRouting(event, rules) from @zephr-ai/routing-match;
  5. fan-outs matching rules through dispatchEvent (resolve channel → applyTagTemplate → write channel_deliveries audit row → platform adapter send).
flowchart LR
    P[R0: webhook / recall / report] --> A[publishRoutingEvent]
    A --> B[validateRoutingEventType — closed set]
    B --> C[resolve installation_id server-side]
    C --> D[load enabled routing_rules — priority ASC]
    D --> E[evaluateRouting — pure]
    E --> F[dispatchEvent]
    F --> G[channel: slack / teams / email / telegram / discord / clickup / in_app / http_webhook]
    G --> H[channel_deliveries — (channel_id, event_id) UNIQUE]

Event types and producers

The closed set (routing-vocabulary.ts, mirrored by the 0122 CHECK) is 12 values. routingTypeLabel appends (no producers yet) at render time for any value with no live producer:

event_typeLive producer?
reminder.triggered✅
notification.created✅
webhook.received✅ verified ingress persists, then publishes once
recall.queried✅ accepted recall (incl. zero hits) publishes with result count
report.ready✅ successful report run publishes; failure is fail-loud (job marked failed/retryable)
memory.captured / revised / confirmed✅
invite.created✅
review.pending / review.confirmed✅
finding.filed✗ reserved — labeled (no producers yet)

The three producers this capability is responsible for — webhook.received, recall.queried, report.ready — are the canonical fan-out from ingress, recall, and report completion into the dispatcher. finding.filed is the one reserved-but-unwired type.

Idempotency and ordering

Delivery idempotency is enforced by the unique index channel_deliveries_channel_event_unique on (channel_id, event_id) (added in 0122): re-publishing the same event_id for the same channel records a non-insert already-delivered outcome and does not invoke the adapter a second time. The bus is at-least-once across process restarts, but side effects are effectively once-per-channel because the duplicate is rejected at the delivery-record layer, not at the adapter. Within a single publish call, matched rules fire in priority ascending order (matching dispatchEvent today).

Channels

channel_kind is shared with channels.kind and widened (0122) to the closed set: slack_channel, teams_channel, email, webhook, in_app, telegram_chat_id, discord_channel, clickup_list, whatsapp_chat. Adapter wiring is staged by wave in apps/worker/reminders/src/dispatch.ts (dispatchSlackMatch base; Telegram W3; Discord + ClickUp W4; Email W5).

Outbound webhooks (http_webhook)

A routing rule may target channel_kind = 'http_webhook'. The worker resolves the target via the outbound_webhooks table by installation_id and signs every delivery with the subscription's signing_secret:

X-Zephr-Signature: sha256=<hex>    // hmac-sha256(signing_secret, body)

Delivery retry policy, dead-lettering, and audit:

  • 2xx → marked delivered, no retry.
  • 4xx → retried up to 3 times, then dead-lettered; rule delivery = 'dead_lettered'.
  • 5xx → retried up to 5 times, then dead-lettered.
  • Missing subscription → rejected audit row reason = 'http_webhook.subscription_missing', no retry.
  • Dead-letter rows are retained for 7 days.

Tenancy and security

Every publish and rule load is scoped to installation_id. The bus never loads rules or channels for another installation, and it never accepts a client-supplied installation id that is not already authorized by the producer path. For webhook.received specifically, the published installation_id is the resolved tenant, never a body claim — a body that names a different installation throws tenant_claim_mismatch before any delivery is attempted. All routing tables (routing_rules, tag_templates, report_routings, recall_handlers) are ENABLE + FORCE RLS via tenant_installation_matches(); an unbound connection sees zero rows.

Observability

Each publishRoutingEvent call increments routing_bus_publish_total, keyed by the producer event_type (the closed set). On a failure path — closed-set rejection, data-access error, or a dispatch port throwing — the façade records routing_bus_publish_failed with the same event_type and a cause from the closed producer-error enum. routing-bus lag is an observability alerting obligation not yet wired — the counter-manifest records the future alert for a later agent rather than firing it today; the delivery-layer audit rows (channel_deliveries, with its (channel_id, event_id) unique constraint) still make a stalled pipeline observable rather than customer-noticeable.

Fail-soft, never fail-closed over real work

  • A publishRoutingEvent failure after a verified ingress is persisted does not roll back the persisted webhook — the ingress response stays a successful accept, the failure is logged/metric'd, and delivery is not attempted for that event.
  • Direct callers of dispatchEvent and the webhook HTTP accept path continue to work without the bus; introducing the bus does not remove or break the existing primary accept path.
  • A publish with no enabled rules for an event type is still successful, performs zero outbound sends, and does not invent a synthetic channel_deliveries row.

Limits and recovery

  • Budget: the bus has no compute quota of its own — it is gated by the routing rules and channels of the installation; delivery fan-out is bounded by the rule set.
  • Recovery from producer failure: because persistence precedes bus publish and the publish is idempotent per (channel_id, event_id), a crashed publisher or a replay cannot double-send; the unique index is the recovery guarantee, not a per-adapter guard.
  • Recovery from dispatcher failure: channel_deliveries audit rows are the durable record; a re-run of dispatchEvent for an already-delivered (channel_id, event_id) is a no-op insert and the adapter is not re-invoked.
  • Cross-tenant leak: structurally impossible — routing_rules/channels are RLS-scoped per installation and installation_id is resolved, not claimed; a foreign-tenant publish is refused as tenant_claim_mismatch before evaluation.