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
| Surface | State | Evidence |
|---|---|---|
Routing-bus publish (publishRoutingEvent) | Ships — closed set, spoof guard, idempotency, 11 live producers + counters | apps/web/src/lib/cloud/routing-publisher.ts |
finding.filed producer | Reserved, no producer yet → UI labels (no producers yet) | routing-vocabulary.ts |
| MCP fabric catalog + deployment rows | Ships — tables + data-access modules | 0313_mcp_fabric_catalog.sql, 0314_mcp_fabric_deployment.sql |
Fabric provision executor (status → ready) | Not wired — Wave 4 | spec W4 |
| Fabric / host webhook UI | Not shipped — W1 has no UI | spec 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_statusdefaults tounknownand moves toverifiedonly after a successful probe; it is never client-asserted. A create/update that suppliesverification_status: 'verified'is stored asunknownand the supplied value is ignored. - Secrets are
secret://refs only. The same CHECK that defendsmanaged_environment_revision.snapshot(0312) refutessk-,AKIA…, andBearer …literals inenv_refs, so a catalog row is safe to hold as a config artifact. - RLS.
ENABLE+FORCErow-level security keyed offtenant_installation_matches();authenticatedselects viaauth_installation_matches(); writes aretenant_request/service_roleonly (no tenantDELETE— 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:
- validates
event_typeagainst the closed setROUTING_EVENT_TYPES(the authoritative CHECK onrouting_rules.event_type); an unknown type throwsRoutingPublishErrorwith codeinvalid_event_typeand writes nochannel_deliveriesrow; - resolves the tenant from the credential, refusing a body-claimed
installation_idthat differs from the resolved tenant (RoutingPublishErrorcodetenant_claim_mismatch); - loads enabled
routing_rulesfor that installation (indexedpriority ASC); - runs the pure evaluator
evaluateRouting(event, rules)from@zephr-ai/routing-match; - fan-outs matching rules through
dispatchEvent(resolve channel →applyTagTemplate→ writechannel_deliveriesaudit 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_type | Live 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
publishRoutingEventfailure 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
dispatchEventand 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_deliveriesrow.
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_deliveriesaudit rows are the durable record; a re-run ofdispatchEventfor 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/channelsare RLS-scoped per installation andinstallation_idis resolved, not claimed; a foreign-tenant publish is refused astenant_claim_mismatchbefore evaluation.