alkcall/docs/architecture/decisions/047-openable-alpns-are-operations.md

ADR-047: Openable ALPNs Are Operations

Status

Accepted (amends ADR-037; refines ADR-044, ADR-046; §4 amended 2026-08-13 — open ops are registered per-connection, not resolved via context.env downcast — see "Amendment (§4 per-connection registration, 2026-08-13)" below)

Amendment (§4 per-connection registration, 2026-08-13)

ADR-047 §4 specified that the open-op wrapper resolves the per-connection ChannelManager by downcasting context.env to &dyn ChannelOperationEnv at invocation time — "static registration, dynamic resolution." Implementation (review 001, C-03) found this shape is not workable as written: context.env is a PeerCompositeEnv (a composite of base + session + per-connection overlays), not a single concrete type, so a direct as_any() downcast of context.env to ChannelsSessionEnv cannot reach the ChannelManager. Traversing the composite's layers to find the channels-backed overlay would hardcode PeerCompositeEnv's internal structure into the channels module — fragile, leaky, and a layering violation (the call crate's composite-env shape is not part of the channels crate's contract).

The amendment: open ops are registered per-connection. The ChannelCore is constructed per channels connection (in the install_channel_zero hook, which already runs per-connection and already receives the ChannelManager). ChannelCore::register_openable is called on that connection's OperationRegistry (the connection overlay registry, Layer 2 per ADR-019), closing over the per-connection ChannelCore. The wrapper uses ChannelCore::manager() directly — no context.env downcast, no dynamic resolution. The open op lives on the connection overlay, which is where per-connection state naturally belongs (ADR-019, ADR-024).

This preserves every invariant ADR-047 §4 was written to protect:

• Layering (ADR-044): the call crate stays free of channels types. The open-op wrapper is in channels-call (src/channels/operations.rs); the call crate's OperationRegistry and OperationEnv are unchanged. No as_any() is added to OperationEnv (the trait stays concrete-rpc- shaped, preserving the session/connection overlay patterns from ADR-024 — AGENTS.md §6).
• Per-connection resolution: the open op gets the right ChannelManager (the one for the connection it was invoked on) because the op is registered on that connection's overlay registry, with a ChannelCore closing over that connection's manager. A globally- registered handler (Layer 0) is not on this path.
• "Marked ops invoked outside a channels session" (ADR-047 §2): unchanged. A channels/<alpn>/sub op registered only on a channels connection's overlay is not reachable on a bare alk/call connection (the overlay isn't attached there) — the dispatch path returns NOT_FOUND, which is the correct behavior for "no channels session" (the channel:no_channels_session error code from the original §4 is no longer reached; NOT_FOUND is the natural reachable-but-not-here result).

The ChannelOperationEnv extension trait and ChannelsSessionEnv impl (src/channels/env.rs) are retained as a two-way-door implementation detail — they are not on the open-op path, but remain available for future per-connection routing (e.g., nested channels where each connection's overlay carries its own manager reference for non-open-op queries). The resolve_channel_manager stub is removed (it described the rejected dynamic-resolution shape).

Door type

Two-way (implementation detail). The ADR's door-type section already marks "The ChannelCore wrapper shape, the extension-trait pattern, and the opener ledger are two-way-door implementation details within the one-way decision." Per-connection registration vs. dynamic resolution is a choice within the wrapper-shape detail — the one-way decisions (per-ALPN op names, the channel_open marker, removal of channel/open/direction) are unchanged. A future revision could move open ops back to Layer 0 with real as_any() downcast machinery if the composite-env structure stabilizes enough to make the traversal non-fragile; the per-connection shape is the simpler choice today.

References

• C-02, C-03 in docs/reviews/001-pub-and-channels-integration-review.md (the register_openable-does-not-exist and resolve_channel_manager-is-a-stub findings this amendment resolves)
• ADR-019: operation registry layering (the connection overlay the open op is registered on)
• ADR-024: peer-graph routing model (the OperationEnv integration-point pattern this amendment preserves by NOT adding as_any())

Context

The channels spec (ADR-037) framed channel lifecycle as one generic channel/open operation whose input carries the authorization-relevant facts (alpn, params, direction) inside its JSON body. The call protocol's ACL machinery (AccessControl::check on OperationSpec) runs before the handler — but the generic op hides everything the ACL would need to see inside one op's input, where the call ACL machinery can't reach it.

The research findings (/workspace/@alkdev/alknet/docs/research/call-channels-unification/ findings.md) surfaced the structural miss and the resolution together:

• The miss. Per-ALPN scopes (tty:open vs tunnel:open) have no enforcement home. ADR-011's resource_id_path (JSON pointer into input for the resource ID, checked by the ACL before the handler runs) can't work on a single generic op — the pointer differs per ALPN (/params/container for tty-docker, /params/target for tunnel). The two direction values are wildly different grants ("may you consume my TTY" vs "may you register a service I will consume as a client") squeezed under one ACL. The shape re-commits the structural miss ADR-024 (superseding ADR-023) was written to avoid: a parallel authorization system duplicating AccessControl one layer down.
• The resolution. An openable ALPN is an operation. Each openable ALPN registers its own ops on the call OperationRegistry, with its own access_control, input_schema, resource_id_path, and a channel_open marker that tells the channels layer "this op's stream is binary, not JSON." The call protocol's existing AccessControl::check is the ACL — unchanged. The direction field is gone; OperationType carries the direction (Sub = consumer subscribes, Pub = producer publishes), building on ADR-046.

This is the cheapest moment to amend: no channels code exists, no deployments exist, the develop branch is pre-alpha. ADR-037's four op names were declared one-way doors, but ADR-035/046 just demonstrated that amendment is the normal mode here.

What the research findings resolved (Gap A, E)

• Gap A (Pub handler shape) — resolved by ADR-046: HandlerKind::Sink / SinkHandler / invoke_sink(). The initiator streams to the responder via call.published events; the handler consumes the stream and returns a single ResponseEnvelope.
• Gap E (OperationEnv::channel_manager() couples call to channels) — resolved by the extension-trait pattern: an alknet-channels-call-local trait (ChannelOperationEnv: OperationEnv) adds the channel_manager() accessor, and the open-op wrapper downcasts context.env at invocation time. alkcall (the call crate) stays free of any channels types; the layering is preserved.

What this ADR decides (Gap B, C, D, F, G)

• Gap B (hub broker) — out of scope for alkcall. The broker (topic registry, Pub↔Sub matching by (op_name, params_hash), N-consumer fan-out) is a hub/consumer concern, not an alkcall concern. alkcall provides the Pub/Sub primitives (ADR-046) and the channel machinery (this ADR); the hub composes the broker on top, the same way the hub relay composes on top of call ops. This ADR names it as out-of-scope so it stops re-tangling every channels-control-plane conversation.
• Gap C (from_call relay wrapper) — the from_call forwarding handler for a marked op wraps with relay machinery (forward + allocate local-leg channel + record id mapping + byte-forward pumps) instead of the plain forwarding stub. The wrapping lives in a separate layer (from_call consumer code, e.g. the hub), not in alkcall's from_call core, preserving the layering. alkcall's from_call reconstructs the channel_open marker from discovery (Gap F) so the consumer can branch on it.
• Gap D (channel_id allocation in Pub case) — the real invariant is "the side that holds the ChannelManager allocates." In the Sub case that's the responder (the side that received the open op); in the Pub case that's the initiator (the side that sent the open op, which owns its own channels connection). ADR-037's "responder allocates" is amended to "connection-owner allocates."
• Gap F (channel_open marker wire format) — the marker is a boolean field "channel_open": true on the services/schema payload. The ALPN is derivable from the op name (channels/<alpn>/sub → ALPN alk/<alpn>); the marker is the dispatch hint, not a carrier for the ALPN string. spec_to_json emits it; rebuild_spec_for parses it.
• Gap G (resource_id_path ACL vs handler ownership) — complementary, not redundant. The ACL check (via resource_id_path + OwnershipProvider) is the coarse gate ("may this identity touch resources of this type, and if a specific resource is targeted, does this identity own it?"). The handler's ownership check is ALPN-specific business logic the ACL can't express ("is this container in a state that allows TTY attachment?"). The two run at different layers and answer different questions.

Decision

1. channel/open dissolves into per-ALPN ops

The generic channel/open operation (ADR-037) is removed. Each openable ALPN registers its own ops on the call OperationRegistry, named channels/<alpn>/sub and/or channels/<alpn>/pub:

Op	OperationType	Initiator role	Responder role	Stream
channels/<alpn>/sub	Sub	consumer (subscribes)	producer (streams)	server→client
channels/<alpn>/pub	Pub	producer (publishes)	consumer (receives)	client→server

An ALPN may register one or both ops. A peer that may subscribe is not the same grant as a peer that may publish — separate op types, separate ACLs.

The direction field from ADR-037 is removed. OperationType carries the direction. The "who writes first" question is ALPN-specific (determined by the handler's params contract), unchanged from ADR-037's "the channels layer does not enforce write order."

The generic ops stay: channel/close, channel/control, channel/resources/subscribe remain generic (keyed by channel_id), registered by channels-call at assembly time. Only channel/open dissolves.

2. channel_open marker on OperationSpec

OperationSpec gains an optional channel_open field — the marker that tells the channels layer "this op's stream is binary, allocate a channel for it":

pub struct OperationSpec {
    // ... existing fields ...
    pub channel_open: Option<ChannelOpenSpec>,
}

pub struct ChannelOpenSpec {
    pub alpn: Cow<'static, str>,  // e.g., "alk/tty"; Cow so from_call can supply an owned String without Box::leak
}

The marker is registry metadata, not auth machinery — parallel to how resource_id_path tells ADR-011 where to find the resource ID. The op's access_control is the ACL (unchanged); the marker is the dispatch hint. The OperationRegistry is opaque to the marker; it's channels-call that reads it.

Wire-visible. The marker survives discovery serialization — it is part of the services/schema payload, not just the in-process struct. spec_to_json emits "channel_open": true when set (boolean — the ALPN is derivable from the op name). rebuild_spec_for parses it back. A from_call importer can branch on the marker to wrap with relay machinery (Gap C).

Marked ops invoked outside a channels session. channels/tty/sub is registered on the call registry — which means it's also visible/invocable on a bare top-level alk/call connection, where there is no ChannelManager. The open-op wrapper resolves channel_manager() at invocation time via the extension trait (Gap E); if it returns None, the wrapper returns channel:no_channels_session.

Amended 2026-08-13 — ChannelOpenSpec::alpn is Cow<'static, str> (not &'static str as originally decided). The &'static str shape forced from_call's discovery path to Box::leak each runtime-parsed ALPN String to satisfy the 'static bound, accumulating a leak on every rediscovery. The Cow<'static, str> keeps the common case (ALPN crates register at compile time with a &'static str literal — zero allocation) cheap while letting from_call supply an owned String without leaking. This is a two-way-door type detail (the wire format — a boolean channel_open marker — is unchanged).

3. ChannelCore wrapper (the open-op composition seam)

The ALPN crate provides:

• The OperationSpec (with channel_open marker, access_control, input_schema, resource_id_path).
• The open handler (ALPN-specific work — validate params, consult ownership, prepare the backend, return a "channel plan" — a ProtocolHandler to spawn on the channel's BiStream).

channels-call provides:

• The ChannelCore (channel-id allocation, ChannelManager integration, per-connection opener ledger, ChannelLifecyclePolicy consultation, teardown hooks).
• A register_openable(spec, open_handler, channel_core) helper that wraps the ALPN's open handler with the channel machinery and registers the op on the call OperationRegistry.

The wrapper shape (not the invoke shape) is preferred: the ALPN's open handler returns a channel plan; channels-call's wrapper does the allocation/ledger/policy/spawn. The alternative (the handler calls context.channel_core.open(...) itself) would require either OperationContext to carry a channel_core reference (inverting the call → channels-call dependency) or a generic extension mechanism on OperationContext (more complexity than the wrapper). The exact API shape of the channel plan is a two-way-door implementation detail; the architectural point is the wrapper.

4. Per-connection ChannelManager resolution (Gap E)

Amended 2026-08-13 — see "Amendment (§4 per-connection registration, 2026-08-13)" at the top of this file. The dynamic-resolution shape described below (downcast context.env to &dyn ChannelOperationEnv at invocation time) was found unworkable as written (context.env is a PeerCompositeEnv, not a single concrete type; the downcast cannot reach the manager without fragile cross-layer traversal). The operative decision is per-connection registration: register_openable is called on the connection overlay registry (Layer 2), closing over a per-connection ChannelCore; the wrapper uses ChannelCore::manager() directly. The body below is the original (rejected) shape, retained for rationale continuity.

The register_openable helper registers ops at assembly time (Layer 0, curated, static per ADR-019). But the wrapper needs the per-connection ChannelManager — the op arrives on channel 0 of one specific channels connection, and the channel must be allocated on that connection's manager. A globally-registered handler closing over a static ChannelCore has no way to know which channels connection invoked it.

The resolution: an extension trait in channels-call (not in the call crate's core OperationEnv trait) adds the channel_manager() accessor:

// in channels-call
pub trait ChannelOperationEnv: OperationEnv {
    fn channel_manager(&self) -> Option<&ChannelManager>;
}

The wrapper handler downcasts context.env to &dyn ChannelOperationEnv at invocation time — static registration, dynamic resolution. If the downcast fails (no channels session), the wrapper returns channel:no_channels_session. This keeps alkcall's call crate free of any channels types and preserves the layering (ADR-044). The OperationEnv is already the integration point for per-connection state (ADR-019); adding a ChannelManager accessor via an extension trait is the natural extension.

Each channels connection's OperationEnv overlay carries its own ChannelManager reference, so nested connections resolve correctly.

5. channel_id allocation: connection-owner allocates (Gap D)

ADR-037's "responder allocates" invariant is amended: the side that holds the ChannelManager for that connection allocates the channel_id. In the Sub case that's the responder (the side that received the open op — it owns its channels connection). In the Pub case that's the initiator (the side that sent the open op — it owns its own channels connection).

This is the same invariant stated correctly: the connection owner allocates. The "responder allocates" framing was a special case that happened to hold for Sub (the common case) but broke for Pub (the initiator owns the connection it's publishing from).

6. The discovery split

• "What may I open" (static, per-op): services/list (visibility- filtered + AccessControl::check(calling_peer_identity) server-side, per ADR-024 §6) + services/schema (per-op access_control and channel_open marker). The existing server-side ACL-filtered discovery is preserved; the spec is the authority. channel:forbidden on the open op is the real check; the preview is "here's what the spec says, you can fail fast."
• "What is currently there" (dynamic, ALPN-level): channel/resources/subscribe. Each ALPN crate that registers open ops also provides a resource enumerator (which containers are running, which TTY sessions are active). channel/resources/subscribe aggregates across all registered openable ALPNs. The data source lives in the ALPN crate, not in channels-call.

The access preview in resources/subscribe (ADR-037) becomes redundant — it's on the op spec, available via services/schema. It is dropped from the resources/subscribe payload; the spec is the authority, and carrying a preview in a different shape invites staleness.

7. Quota lifecycle: the opener ledger (Gap 2 from findings)

ADR-041's ChannelLifecyclePolicy::on_close(&op_ctx.identity) is called from the channel/close handler with the closer's identity, not the opener's — and is not called at all on transport drop. A peer whose connection dies at cap is permanently at cap (a self-DoS).

The fix: channels-call keeps a per-connection opener ledger (channel_id → opener PeerId). The decrement is keyed by the opener (from the ledger), not the closer. The decrement is called from every teardown path — close received, close sent locally, handler exit, connection drop — not just channel/close. The ledger entry is removed atomically with its decrement (teardown paths can race; a double-decrement under-counts and weakens the cap).

The ChannelLifecyclePolicy trait shape (check_open, on_close) survives; the change is where on_close is called from and where the opener identity comes from. channels-core stays auth-blind (the ledger lives in channels-call, not channels-core).

8. ALPN category reframe

ADR-086 §4 (alknet source) split the foundational handlers into "channels data-channel ALPNs" and "SSH (endpoint ALPN wrapping channels)." Under the unified model, the first category dissolves — they're call apps (the same shape as docker). They register ops on the call OperationRegistry. Some ops return JSON; some ops carry the channel_open marker and produce a binary stream. The endpoint (channels or bare call) determines the framing, not the app.

The ALPN crates served under channels (tty, tunnel, socks5, fs, sftp) stop being "just ALPNs" and become call apps. They inherit call's auth/composition/identity by construction (they are call apps). The binary-stream part is the channel_open marker on the op spec. SSH stays distinct (endpoint ALPN wrapping channels).

Consequences

Positive:

• Per-ALPN ACLs have an enforcement home: each openable ALPN's op has its own access_control, checked by OperationRegistry::invoke before the handler runs, like every other op. No new auth machinery.
• ADR-011's resource_id_path works for channel-open ops: the path is per-op (/params/container for tty-docker), not per-ALPN-branch-of-a- generic-op. The coarse ownership gate runs before the handler.
• The direction field is gone; OperationType (Sub/Pub) carries the direction. Separate op types → separate ACLs. The hub-as-proxy pattern (worker publishes, hub owns, consumers subscribe) composes on top.
• The channel_open marker is the dispatch hint — orthogonal to the ACL. The same Pub/Sub model works for JSON streams (marker absent) and binary streams (marker present).
• The ALPN crates are call apps — the gating is a consequence, not the definition. They inherit call's auth by construction.
• The per-connection opener ledger fixes the quota self-DoS (Gap 2).
• The extension-trait pattern (Gap E) keeps the call crate free of channels types.

Negative:

• OperationSpec gains a field (channel_open: Option<ChannelOpenSpec>, defaults None). Every spec-constructing site adds the field, defaulting to None. This is a mechanical, additive change — the Option/None-default keeps it non-breaking.
• The ALPN→path-segment mapping (alk/tty → tty) needs pinning. The op name channels/tty/sub implies the path segment is tty; non-alk/* ALPNs need a rule. The rule: the path segment is the ALPN with the alk/ prefix stripped; ALPNs without that prefix use their full ALPN string as the path segment (rare case, two-way- door).
• The from_call relay wrapper (Gap C) is a consumer concern, not in alkcall's from_call core. The consumer (hub) wraps marked ops with relay machinery after from_call returns. This preserves the layering but means the hub has more to do than a plain register_imported_all.
• The broker (Gap B) is out of scope. The Pub/Sub primitives are the building blocks; the hub composes the broker on top. Designing the broker blind would produce a half-design.

Door type

One-way (control-plane shape). The per-ALPN op names (channels/<alpn>/sub, channels/<alpn>/pub), the channel_open marker on OperationSpec, and the removal of channel/open / direction are one-way: once consumers register open ops and clients call them by name, changing the shape requires a protocol migration. The ChannelCore wrapper shape, the extension-trait pattern, and the opener ledger are two-way-door implementation details within the one-way decision.

The channel_open marker's wire shape ("channel_open": true boolean) is one-way: services/schema consumers will read it, and changing the shape would break them. The ChannelOpenSpec in-process struct carrying the ALPN is a two-way-door detail (the wire shape is boolean; the in-process struct is free to evolve).

References

• ADR-037: channel lifecycle operations (amended by this ADR — channel/open dissolves; generic ops stay; direction removed)
• ADR-041: per-identity channel cap (amended by this ADR — the opener ledger; the trait shape survives)
• ADR-046: Publish operation type and HandlerKind::Sink (the Pub/Sub primitives this ADR builds on; Gap A resolved)
• ADR-024: peer-graph routing model (the AccessControl::check path this ADR preserves; the precedent for avoiding a parallel auth system)
• ADR-011: dynamic resource ownership (resource_id_path works again under per-ALPN ops)
• ADR-019: operation registry layering (OperationEnv as the integration point; the extension-trait pattern extends it)
• ADR-044: channels sub-crate decomposition (the layering this ADR preserves — channels types stay out of the call crate)
• ADR-042: hub relay (the relay contract unchanged in shape; the op name changes, the marker replaces prefix-matching)
• /workspace/@alkdev/alknet/docs/research/call-channels-unification/ findings.md — the research that surfaced the unification and the gaps this ADR resolves