docs(eda): resolve the Channel action position
Notification is a contract in internal/domain/messaging, not a channel type. A channel implementation satisfies it by importing its own parent, which it already does, so channels.Channel gains no notification method and no import and the dependency stays channels -> messaging. A notification has no lifecycle, no inbound direction and no config schema, so modelling it as a channel would force Start/Stop/ConfigSchema onto something with no meaning for them. Destinations are configured, never named by a playbook: [notify] grows from one webhook URL into named destinations, each binding a name to a channel already registered in the Messaging composition plus that channel's address. An action names a destination. Playbook triggers are reachable from a public intake surface, so an action that could address an arbitrary chat would be a new exfiltration surface. Host access needs no new process surface. archie-messaging dials out only and deliberately has no NATS connection, so nothing can push to it today. Delivery travels the Gateway connection every process already holds, as a new server-streaming RPC on ChatService; the per-turn Stream RPC is not reused. The 2026-09-03 section presenting two options is superseded. Its claim that no send capability exists anywhere was too strong: telegram.SendPendingReport already sends unsolicited to a stored chat id, with no interface for it. Closes archie-core-t2db.19
This commit is contained in:
1 file changed
+97
-57
@@ -1,13 +1,13 @@
|
||||
# Channel and Forge action positions -- investigation (resolves `t2db.19`)
|
||||
# Channel and Forge action positions (resolves `t2db.19`)
|
||||
|
||||
**Status:** Investigation complete for Forge; Channel corrected and flagged
|
||||
for a decision only Sam can make -- not a design recommendation.
|
||||
**Date:** 2026-09-03
|
||||
**Status:** Draft
|
||||
**Date:** 2026-09-03, Channel resolved 2026-09-22
|
||||
**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`
|
||||
**Blocked on:** `archie-core-t2db.17` (idempotency keying) for implementation
|
||||
of either position -- both are side-effecting.
|
||||
**Blocked on:** `archie-core-t2db.24` (the `playbook_dispatches` ledger) for
|
||||
implementation of either position. Both are side-effecting, and `t2db.17`
|
||||
resolved the keying scheme in design only.
|
||||
|
||||
## Forge: ready to design once t2db.17 lands
|
||||
## Forge: ready to implement once the ledger lands
|
||||
|
||||
`internal/forge.Forge` is already exactly the shape a native-Go action
|
||||
position needs -- a real, typed, general-purpose interface, not something
|
||||
@@ -50,8 +50,8 @@ layer today. Depend on `Forger`, not on `internal/forge`.
|
||||
starting set. `create-pr` is explicitly a heavier case -- opening a PR is a
|
||||
harder-to-reverse action with its own dedup shape beyond "did this event
|
||||
fire before" (a redelivered event must not open a second PR for the same
|
||||
logical change) -- defer it to a follow-up slice once `t2db.17`'s keying
|
||||
scheme is proven on the simpler operations, don't design it blind now.
|
||||
logical change) -- defer it to a follow-up slice once the keying scheme is
|
||||
proven on the simpler operations, don't design it blind now.
|
||||
|
||||
**Host access:** the coordinator needs the same `Forge` instance
|
||||
`internal/daemon`'s poller already holds (constructed once at startup via
|
||||
@@ -59,65 +59,97 @@ scheme is proven on the simpler operations, don't design it blind now.
|
||||
existing instance into the coordinator's constructor), not a new
|
||||
extensibility mechanism.
|
||||
|
||||
## Channel: the crew's assumption doesn't hold -- flagged, not designed
|
||||
## Channel: resolved 2026-09-22
|
||||
|
||||
The investigation backlog that recommended scoping this alongside Forge
|
||||
assumed `channels.Channel` already has an addressable send capability that
|
||||
just needs a name-based lookup. **That's not true.** Verified directly:
|
||||
Superseded: the 2026-09-03 section here presented two options and asked for a
|
||||
decision. The decision is below; the options are not repeated.
|
||||
|
||||
### Constraints this satisfies
|
||||
|
||||
Messaging is the root, Channel is the integration layer, an implementation
|
||||
such as Telegram sits under Channel. A channel is added by implementing one
|
||||
reusable interface, and every channel must implement it. A notification
|
||||
mechanism belongs under Messaging, and `channels.Channel` must not reach
|
||||
across into it.
|
||||
|
||||
### Notification is a Messaging contract, not a channel type
|
||||
|
||||
The contract lives in `internal/domain/messaging`. A channel implementation
|
||||
satisfies it by importing its own parent, which it already does, so the
|
||||
dependency stays `channels -> messaging` and nothing points back.
|
||||
|
||||
`channels.Channel` does not change. It gains no notification method and no
|
||||
import, so the interface every channel must implement stays the lifecycle and
|
||||
config contract it is today. `internal/channels/telegram` satisfying both
|
||||
contracts is an implementation choosing to, not the Channel layer knowing
|
||||
about notification.
|
||||
|
||||
A notification is not a channel type because it has no lifecycle to start and
|
||||
stop, no inbound direction, and no configuration schema of its own. Modelling
|
||||
it as one would force `Start`/`Stop`/`ConfigSchema` onto something with no
|
||||
meaning for them, and make every real channel declare whether it is a
|
||||
notification.
|
||||
|
||||
### Destinations are configured, never named by a playbook
|
||||
|
||||
`[notify]` today is one webhook URL, read in one place
|
||||
(`internal/domain/workflow/feasibility.go:134`). It becomes a set of named
|
||||
destinations. Each binds a name the operator chooses to a channel already
|
||||
registered in the Messaging composition (`internal/app/archiemessaging/compose.go`
|
||||
registers `telegram`, `email`, `webhook`) plus that channel's own address,
|
||||
such as a Telegram chat id. The existing single-webhook form keeps working as
|
||||
a destination named `webhook`.
|
||||
|
||||
A playbook action names a destination. It never names an address. Playbook
|
||||
triggers are reachable from a public, unauthenticated intake surface, so an
|
||||
action that could address an arbitrary chat would be a new exfiltration
|
||||
surface; a destination the operator configured once is not.
|
||||
|
||||
### Args and Result
|
||||
|
||||
```go
|
||||
// internal/gateway/gateway.go
|
||||
type Gateway interface {
|
||||
Name() string
|
||||
Start(ctx context.Context, router *Router, lifecycle Lifecycle) error
|
||||
Stop(ctx context.Context) error
|
||||
type NotifyArgs struct {
|
||||
Destination string // a name from [notify]
|
||||
Text string
|
||||
}
|
||||
|
||||
type NotifyResult struct {
|
||||
Delivered bool
|
||||
}
|
||||
```
|
||||
|
||||
`channels.Channel` embeds exactly this plus `ConfigSchema`/`ValidateConfig`
|
||||
-- lifecycle and config introspection, nothing about sending a message.
|
||||
Grepping `internal/channels` and `internal/gateway` for any `Send` method
|
||||
returns nothing. The only generic outbound-message mechanism in the entire
|
||||
codebase is `Notify` (`internal/config`'s `[notify]` block) -- a single
|
||||
fixed webhook URL for gate failures/approvals/parked tasks, not a
|
||||
per-channel-addressable send.
|
||||
An unknown destination is a reported error at playbook load, not at dispatch:
|
||||
the destination set is known at startup, so this follows the engine's
|
||||
reject-at-load rule.
|
||||
|
||||
Real per-channel sending exists, but deliberately not as a reusable
|
||||
capability: `telegramApprover` (`internal/channels/telegram/approval.go`)
|
||||
captures a `*bot.Bot` plus a specific `chatID`/`threadID`/`recipient` at
|
||||
construction, scoped to one conversation for one launch. This is the
|
||||
established precedent in this codebase (already in project memory from
|
||||
before this session) precisely to prevent reading a shared bot handle
|
||||
across chats -- a playbook-triggered send has no chat turn to be scoped to,
|
||||
so this precedent doesn't transfer as-is.
|
||||
### Host access: no new process surface
|
||||
|
||||
**This means "Channel action position" is not a small wrapper over an
|
||||
existing capability -- it requires deciding whether to build a genuinely
|
||||
new send capability that doesn't exist today, and if so, what it targets.**
|
||||
Two different things could reasonably be meant by "Channel" here, and they
|
||||
have different shapes:
|
||||
`archie-messaging` is its own process (`cmd/archie-messaging`). It dials out
|
||||
to the Gateway and the State Store and serves nothing, and it deliberately
|
||||
has no NATS connection: `internal/app/archiemessaging/telegram_features.go:65`
|
||||
records that it "must not decode" the daemon's `[nats]` config. So a
|
||||
notification cannot be pushed into it today by any route.
|
||||
|
||||
1. **A new, playbook-scoped notification capability** -- closer in spirit
|
||||
to `Notify` (fire a message somewhere, no chat-turn context needed) but
|
||||
addressable by name/target instead of one fixed webhook. This would be
|
||||
new engine-family work (its own typed contract, registry, narrow host
|
||||
access), not an extension of `channels.Channel`.
|
||||
2. **Reusing the interactive chat channels** (Telegram, email) for
|
||||
playbook-originated sends -- requires deciding what conversation context
|
||||
a playbook-triggered message has (which chat? whose approval flow?) when
|
||||
there was no incoming chat turn to anchor it, and building whatever
|
||||
capture/scoping mechanism the interactive channels use today, generalized
|
||||
to a non-chat trigger. This is materially harder and touches the
|
||||
gateway's session model.
|
||||
Delivery therefore travels the connection that already exists. Every process
|
||||
that needs Messaging already dials the Gateway: `archied`
|
||||
(`internal/app/archied/chat_service.go:25`), `archie-messaging`
|
||||
(`internal/app/archiemessaging/run.go:26`) and `archie-ui`. The Gateway is the
|
||||
hub. A new server-streaming RPC on `ChatService` lets `archie-messaging`
|
||||
subscribe at startup and receive notifications the daemon publishes; Messaging
|
||||
then delivers through the named channel instance it already holds in
|
||||
`Service.channels`. No new listener, no NATS in Messaging, no change to how
|
||||
any process is reached.
|
||||
|
||||
**This is not a call to make unilaterally.** It changes what "Channel
|
||||
action" even means, and the answer affects the trust/scoping model, not
|
||||
just an implementation detail. Recommend: Sam decides which of the two (or
|
||||
a third option not listed here) before any Channel position design work
|
||||
starts. Until then, `t2db.19` should be treated as **Forge scoping only**
|
||||
-- the Channel half stays genuinely open, not just unimplemented.
|
||||
The existing `Stream` RPC is not reused: it streams one chat turn's events for
|
||||
one inbound message (`internal/infrastructure/gatewayrpc/server.go:Stream`).
|
||||
|
||||
## Packages this touches (Forge only, once `t2db.17` lands)
|
||||
### Out of scope
|
||||
|
||||
Giving playbook-originated sends the session and approval scoping the
|
||||
interactive channels use. Configured destinations carry the address, so there
|
||||
is no conversation to anchor to and no scoping mechanism to generalize.
|
||||
|
||||
## Packages this touches
|
||||
|
||||
- `internal/domain/eda` (or a new sibling package, e.g.
|
||||
`internal/domain/eda/forgeaction`): typed `Args`/`Result` per operation,
|
||||
@@ -128,3 +160,11 @@ starts. Until then, `t2db.19` should be treated as **Forge scoping only**
|
||||
the daemon's already-built `forge.Forge` client, passed in as the
|
||||
`workflow.Forger` it already satisfies -- no new lifecycle to manage,
|
||||
and no change to `internal/forge` itself.
|
||||
|
||||
- `internal/domain/messaging`: the notification contract and its
|
||||
`NotifyArgs`/`NotifyResult`.
|
||||
- `internal/config`: `[notify]` becomes named destinations.
|
||||
- `proto/gateway/v1` and `internal/infrastructure/gatewayrpc`: the
|
||||
server-streaming notification RPC.
|
||||
- `internal/app/archiemessaging`: subscribe at startup, resolve a destination
|
||||
to a registered channel instance, deliver.
|
||||
Reference in new issue
Block a user