channels/ — realm-shipped channel connectors

A channel is a general data pipe, including provider messages, webhooks, database changes and Realm-produced events. It may carry data in either direction. channels/ declares provider connector drafts; data-pipes.yml declares captured sources and consumers. See the hosted data-pipe contract for source identity, grants, publication, atomic polling positions, receipts and checkpoints.

The governed host requires owner approval and owner-scoped credential references before starting a provider connector. A Realm declaration, auto-start value or process environment variable grants no runtime authority. The following legacy connector format applies only where the host explicitly supports it; it does not replace the owner lifecycle API.

A realm configures a connector the host implements — host-extension via FQN, the same dispatch pattern as PolicyActionSpec:

channels/discord.yml

type: com.embabel.world.event.channel.discord.DiscordChannelConfig
name: discord
token-env: DISCORD_BOT_TOKEN
auto-start: true

Field	Required	Meaning
type	yes	FQN of a host-provided channel connector configuration. The host documents which connectors it ships; a realm cannot ship connector code.
name	yes	The channel’s name on this world.
token-env	connector-specific	Legacy credential name resolved by a trusted host. Governed hosts require owner-scoped credential approval. Values never belong in the Realm.
auto-start	no	Legacy startup preference. Governed startup also requires current owner approval and a supported provider lifecycle.

auto-start controls the connector lifecycle only; it does not adopt or activate any handler or manifest schedule. A credential-backed live connector registration is owned by exactly one world in the portable v1 contract. If another world attempts to use the same provider credential, the host must reject the second registration rather than instantiate another session or silently attribute both worlds to the first owner. Organization-owned shared connectors require a later explicit orgId membership and route-attribution contract.

Within that world, every inbound and reply route is bound to one explicit context, access-policy revision, and run-as principal. A connector session may multiplex such routes only when it keeps those bindings separate; it never broadcasts an event or reply route into every context by default.

Provider adapters map incoming data to host events. The governed host appends the event to a durable journal before acknowledgment, then projects signals or invokes approved consumers with independent checkpoints. A provider message, a journal receipt and a completed consumer effect have different completion semantics.

Provider-specific addressing, conversation identity and reply rules belong to the connector implementation. channels/ references only host-provided connector types; a Realm cannot install JVM connector code. General Realm-produced sources use captured declarations and sandbox callbacks instead.

An unknown type is reported against the file and that channel is skipped; the realm’s other content loads.