wehub-resource-sync
db620d33df
dotnet-build-and-test / dotnet-test-functions (push) Has been cancelled
dotnet-build-and-test / paths-filter (push) Has been cancelled
dotnet-build-and-test / dotnet-build (Debug, windows-latest, net9.0) (push) Has been cancelled
dotnet-build-and-test / dotnet-build (Release, ubuntu-latest, net10.0) (push) Has been cancelled
dotnet-build-and-test / dotnet-build (Release, ubuntu-latest, net8.0) (push) Has been cancelled
dotnet-build-and-test / dotnet-build (Release, windows-latest, net472) (push) Has been cancelled
dotnet-build-and-test / dotnet-test (Release, integration, true, ubuntu-latest, net10.0) (push) Has been cancelled
dotnet-build-and-test / dotnet-test (Release, integration, true, windows-latest, net472) (push) Has been cancelled
dotnet-build-and-test / dotnet-foundry-hosted-it (push) Has been cancelled
dotnet-build-and-test / dotnet-build-and-test-check (push) Has been cancelled
dotnet-build-and-test / Integration Test Report (push) Has been cancelled
CodeQL / Analyze (csharp) (push) Has been cancelled
CodeQL / Analyze (python) (push) Has been cancelled
133 lines
7.7 KiB
Markdown
133 lines
7.7 KiB
Markdown
---
|
|
status: proposed
|
|
contact: eavanvalkenburg
|
|
date: 2026-06-11
|
|
deciders: eavanvalkenburg
|
|
---
|
|
|
|
# Hosting linking and multicast enhancements
|
|
|
|
## Context and Problem Statement
|
|
|
|
[ADR-0027](0027-hosting-channels.md) defines the minimal v1 hosting core: originating-channel responses, explicit `ChannelSession.isolation_key`, and no host-level identity linking, push, multicast, background delivery, or durable runners.
|
|
|
|
This ADR tracks the richer cross-channel behaviors that were removed from v1. These enhancements are **follow-up work** and are **not prerequisites** for shipping, using, or stabilizing the v1 host/channel core.
|
|
|
|
## Decision Drivers
|
|
|
|
- Cross-channel continuity must not create accidental cross-user, cross-tenant, or cross-channel data leaks.
|
|
- Non-originating delivery must be observable, idempotent, retryable, and supportable.
|
|
- Protocol payloads must remain channel-native while still being safe to persist and replay.
|
|
- App authors need opt-in policy controls, not hidden defaults.
|
|
- The enhancement stack should layer on top of the v1 host without reshaping the minimal channel contract.
|
|
|
|
## Enhancement Areas
|
|
|
|
The follow-up design should cover these capabilities together because they share identity, storage, delivery, and replay concerns:
|
|
|
|
- **Cross-channel identity linking** — a user can connect multiple `ChannelIdentity` values to one channel-neutral `isolation_key`.
|
|
- **Authorization and allowlist policy** — channels or hosts can require verified identity, allow specific native identities or claims, and deny unknown callers.
|
|
- **Non-originating response delivery** — a run can respond somewhere other than the request's originating protocol when explicitly configured.
|
|
- **Active-channel routing** — delivery can target the most recently observed linked channel for an `isolation_key`.
|
|
- **Multicast / all-linked delivery** — delivery can fan out to every linked channel or a selected set.
|
|
- **Background runs and continuation tokens** — long-running requests can return immediately and complete later, with a polling/status fallback.
|
|
- **Durable delivery runners** — delivery work can survive process restarts and support dead-letter handling.
|
|
- **Retry and replay semantics** — delivery attempts are bounded, deduplicated, and safe to replay.
|
|
- **Payload serialization** — channel-specific payloads can be persisted, redacted, versioned, and reconstructed without losing protocol fidelity.
|
|
|
|
Candidate API names from the broader design (`IdentityLinker`, `IdentityAllowlist`, `AuthPolicy`, `ResponseTarget`, `ChannelPush`, `ChannelPushCodec`, `DurableTaskRunner`, `InProcessTaskRunner`, `RetryPolicy`, `LinkPolicy`) remain design vocabulary for this ADR. They are not approved v1 APIs.
|
|
|
|
## Considered Options
|
|
|
|
### Option A — Leave all behavior to applications
|
|
|
|
Applications implement linking, authorization, push, retry, and serialization independently.
|
|
|
|
- Good: the hosting core stays very small.
|
|
- Neutral: advanced apps can still build what they need.
|
|
- Bad: every app must solve the same security and delivery problems, likely inconsistently.
|
|
|
|
### Option B — Add the full enhancement stack to v1
|
|
|
|
The first host release includes linking, authorization, active channel, multicast, background runs, durable runners, and codecs.
|
|
|
|
- Good: the original cross-channel experience is available immediately.
|
|
- Neutral: samples can demonstrate rich end-to-end flows.
|
|
- Bad: v1 becomes security-sensitive, storage-heavy, and harder to stabilize.
|
|
|
|
### Option C — Layer opt-in enhancement packages after v1
|
|
|
|
Ship the minimal host first, then add linking, authorization, and delivery packages behind explicit configuration.
|
|
|
|
- Good: v1 remains simple while leaving room for a reviewed, supportable enhancement stack.
|
|
- Neutral: apps that need advanced delivery wait for follow-up packages.
|
|
- Bad: the first release does not satisfy proactive or all-linked scenarios.
|
|
|
|
### Option D — Build only platform-specific integrations
|
|
|
|
Implement linking and proactive delivery separately in Telegram, Activity Protocol, Discord, and future channels.
|
|
|
|
- Good: each package can match its protocol exactly.
|
|
- Neutral: some shared abstractions may emerge later.
|
|
- Bad: cross-channel behavior becomes fragmented and hard to reason about.
|
|
|
|
## Decision Outcome
|
|
|
|
Proposed direction: **Option C — layered opt-in enhancement packages after v1**.
|
|
|
|
The minimal host remains the foundation. Follow-up packages may add linking, authorization, delivery, and durable execution, but must be explicitly enabled and must pass the validation gates below before becoming part of the public contract.
|
|
|
|
## Safety Requirements
|
|
|
|
### Threat model
|
|
|
|
The design must account for:
|
|
|
|
- spoofed channel-native identities,
|
|
- stolen or replayed link challenges,
|
|
- cross-tenant or cross-confidentiality data leakage,
|
|
- unsolicited proactive messages,
|
|
- malicious payloads persisted for replay,
|
|
- denial-of-service through fan-out or retry storms, and
|
|
- privacy leakage through logs, metrics, or support tooling.
|
|
|
|
Required mitigations include verified identity claims where available, signed and expiring link challenges, explicit user consent, per-channel capability checks, default-deny policy options, tenant partitioning, and uninformative denial messages on shared channels.
|
|
|
|
### Idempotency and replay
|
|
|
|
Exactly-once delivery is not a realistic guarantee. The design must provide:
|
|
|
|
- stable run, continuation, and delivery-attempt identifiers,
|
|
- channel-level idempotency keys where protocols support them,
|
|
- bounded retry with jitter and explicit terminal states,
|
|
- replay windows and expiration,
|
|
- duplicate suppression for persisted attempts, and
|
|
- clear semantics for "delivered", "accepted by platform", and "observed by user".
|
|
|
|
### Storage
|
|
|
|
Enhancement storage must stay distinct from v1 `AgentSession` history and workflow checkpoints unless an implementation deliberately backs them with the same physical store.
|
|
|
|
Stored data should be schema-versioned, minimized, encrypted or otherwise protected as appropriate, and partitioned by tenant/project. Link records, continuation records, active-channel state, delivery attempts, dead letters, and serialized payloads need independent TTL and deletion policies.
|
|
|
|
### Observability and support
|
|
|
|
The design must include structured logs, traces, and metrics for link attempts, authorization decisions, delivery scheduling, retries, replay, and dead-letter outcomes. Logs must avoid message content and sensitive identity claims by default. Operators need a way to inspect, revoke, replay, or purge stuck records safely.
|
|
|
|
## Validation Gates
|
|
|
|
Before these enhancements are accepted:
|
|
|
|
- A reviewed threat model covers identity linking, authorization, non-originating delivery, multicast, and replay.
|
|
- Cross-channel linking tests prove a verified identity can link two channels and that unlink/deny paths do not leak information.
|
|
- Authorization tests cover native-id allowlists, verified-claim allowlists, default-deny behavior, and misconfiguration failures.
|
|
- Delivery tests cover originating-only, specific-channel, active-channel, selected-channel, and all-linked routing.
|
|
- Background/continuation tests cover polling fallback, cancellation or expiration, process restart, retry, and dead-letter behavior.
|
|
- Codec tests prove payloads are versioned, redacted where needed, backward compatible, and rejected safely when unknown.
|
|
- Multicast tests prove fan-out is bounded, independently retried, and idempotent per destination.
|
|
- Observability tests or manual validation prove support operators can correlate a request to delivery attempts without exposing sensitive content.
|
|
|
|
## Relationship to ADR-0027
|
|
|
|
ADR-0027 remains valid without any of these enhancements. This ADR extends the hosting model only after the safety, storage, and support requirements above are satisfied.
|