Design: event sources, reaction delivery, and how extensions hook them #94

Closed
opened 2026-10-27 13:34:55 +00:00 by sam · 0 comments
Owner

No settled design covers this. docs/architecture/plugins-and-extensions.md settles the PLUGIN FRAMEWORK (metadata-only contract, typed capability families, owning registries) but says nothing about event sources, reaction delivery, or intake. Under the scope-discipline rule merged as PR #533, that means design first -- one page, decisive -- then a diff.

Decide and record in docs/prds/:

  1. THE HEADLINE QUESTION, which changes everything downstream: do extensions react in-process through typed capability families (what the approved rule mandates), or out-of-process like tau's generic DispatchEvent? If out-of-process generic dispatch is genuinely wanted, docs/architecture/plugins-and-extensions.md is an APPROVED document and must be amended first -- CLAUDE.md's organisation rule is explicit that you change the doc before the rule it states. Do not quietly work around it.

  2. Reaction delivery. events.Bus drops on overflow by design and must stay that way for the dashboard. Decide whether reactions get a second in-process bus with at-least-once delivery, or ride the existing NATS eventbus (internal/infrastructure/eventbus), which already has durable semantics and the work-queue traps documented in CLAUDE.md.

  3. Whether a reaction may INFLUENCE an outcome (veto, mutate, add work) or only observe. This is the difference between a hook and a subscriber, and it determines whether ordering and failure semantics matter. If a reaction can block, decide what a slow or crashed extension does -- tau's answer was a dispatch timeout, and it still deadlocked unload once.

  4. The typed source/intake family: its interface, its owning registry, and how a source declares what it produces.

Respect dependency direction: cmd -> app -> {domain, infrastructure}. A domain declares the contract; app wires implementations. Cross-cutting packages may be imported by any layer and import none.

Acceptance criteria

A one-page decision in docs/prds/ answering all four questions, naming the packages it will touch, and stating explicitly whether plugins-and-extensions.md needs amending. It decides rather than surveys.

Notes

CORRECTION 2026-08-22 (second): decision question 2 in this bead's description asked whether reactions get a second in-process bus or ride the existing NATS eventbus. That framing is wrong -- there is no 'or'. NATS is the settled transport; the only open axis is external-server vs embedded, not NATS vs something else. Do not design a second bus. See archie-core-7d5u and archie-core-7d5u.2 for the corrected framing and the verified state of github.com/nats-io/nats-server/v2 as an already-present, test-proven, production-unwired dependency.

Close reason

Decided and documented in docs/prds/event-sources-and-reactions.md, satisfying this bead's own acceptance criterion (a one-page decision naming the packages it touches and stating whether plugins-and-extensions.md needs amending -- it does not).

Answers: (1) in-process typed families, no out-of-process dispatch -- archie has no existing extension-process boundary and neither epic's stated payoff needs one. (2) Reaction delivery reuses internal/eventbus's Publisher/Consumer contract (PublishUnique + Ack/Nak already provide at-least-once with dedup), but NOT the existing nats.Client as-is: it hardcodes Retention: jetstream.WorkQueuePolicy (client.go:65) for the competing-consumer ARCHIE_TASKS stream, which silently starves a second consumer on overlapping subjects per CLAUDE.md's documented trap -- reactions need fan-out, so retention needs to become a Config field and reactions get their own stream. (3) Reactions in these two epics are producer-only (cheap wake via curator's WakeOnPrimaryInput pattern, or produce real work via the existing pollNATS->publishTask path) -- no veto/mutate-in-flight-work capability is being built here; that belongs to archie-core-h019 if it's ever needed. (4) No single generic Source interface -- forge intake reuses workintake.TaskEnvelope unchanged (its IdempotencyKey is already keyed on owner/repo/number, not delivery source, so a webhook-sourced envelope naturally dedups against a poll-discovered one for free); chat webhook stays internal/channels/webhook, unmodified; what's genuinely new and shared is a small cross-cutting package for HMAC/rate-limit/approval/capture mechanics, owned by neither domain.


Imported from beads archie-core-7d5u.1 · GitHub #544 · type decision · priority P1 · created 2026-08-21 · closed 2026-08-21

No settled design covers this. docs/architecture/plugins-and-extensions.md settles the PLUGIN FRAMEWORK (metadata-only contract, typed capability families, owning registries) but says nothing about event sources, reaction delivery, or intake. Under the scope-discipline rule merged as PR #533, that means design first -- one page, decisive -- then a diff. Decide and record in docs/prds/: 1. THE HEADLINE QUESTION, which changes everything downstream: do extensions react in-process through typed capability families (what the approved rule mandates), or out-of-process like tau's generic DispatchEvent? If out-of-process generic dispatch is genuinely wanted, docs/architecture/plugins-and-extensions.md is an APPROVED document and must be amended first -- CLAUDE.md's organisation rule is explicit that you change the doc before the rule it states. Do not quietly work around it. 2. Reaction delivery. events.Bus drops on overflow by design and must stay that way for the dashboard. Decide whether reactions get a second in-process bus with at-least-once delivery, or ride the existing NATS eventbus (internal/infrastructure/eventbus), which already has durable semantics and the work-queue traps documented in CLAUDE.md. 3. Whether a reaction may INFLUENCE an outcome (veto, mutate, add work) or only observe. This is the difference between a hook and a subscriber, and it determines whether ordering and failure semantics matter. If a reaction can block, decide what a slow or crashed extension does -- tau's answer was a dispatch timeout, and it still deadlocked unload once. 4. The typed source/intake family: its interface, its owning registry, and how a source declares what it produces. Respect dependency direction: cmd -> app -> {domain, infrastructure}. A domain declares the contract; app wires implementations. Cross-cutting packages may be imported by any layer and import none. ### Acceptance criteria A one-page decision in docs/prds/ answering all four questions, naming the packages it will touch, and stating explicitly whether plugins-and-extensions.md needs amending. It decides rather than surveys. ### Notes CORRECTION 2026-08-22 (second): decision question 2 in this bead's description asked whether reactions get a second in-process bus or ride the existing NATS eventbus. That framing is wrong -- there is no 'or'. NATS is the settled transport; the only open axis is external-server vs embedded, not NATS vs something else. Do not design a second bus. See archie-core-7d5u and archie-core-7d5u.2 for the corrected framing and the verified state of github.com/nats-io/nats-server/v2 as an already-present, test-proven, production-unwired dependency. ### Close reason Decided and documented in docs/prds/event-sources-and-reactions.md, satisfying this bead's own acceptance criterion (a one-page decision naming the packages it touches and stating whether plugins-and-extensions.md needs amending -- it does not). Answers: (1) in-process typed families, no out-of-process dispatch -- archie has no existing extension-process boundary and neither epic's stated payoff needs one. (2) Reaction delivery reuses internal/eventbus's Publisher/Consumer contract (PublishUnique + Ack/Nak already provide at-least-once with dedup), but NOT the existing nats.Client as-is: it hardcodes Retention: jetstream.WorkQueuePolicy (client.go:65) for the competing-consumer ARCHIE_TASKS stream, which silently starves a second consumer on overlapping subjects per CLAUDE.md's documented trap -- reactions need fan-out, so retention needs to become a Config field and reactions get their own stream. (3) Reactions in these two epics are producer-only (cheap wake via curator's WakeOnPrimaryInput pattern, or produce real work via the existing pollNATS->publishTask path) -- no veto/mutate-in-flight-work capability is being built here; that belongs to archie-core-h019 if it's ever needed. (4) No single generic Source interface -- forge intake reuses workintake.TaskEnvelope unchanged (its IdempotencyKey is already keyed on owner/repo/number, not delivery source, so a webhook-sourced envelope naturally dedups against a poll-discovered one for free); chat webhook stays internal/channels/webhook, unmodified; what's genuinely new and shared is a small cross-cutting package for HMAC/rate-limit/approval/capture mechanics, owned by neither domain. --- _Imported from beads `archie-core-7d5u.1` · GitHub #544 · type decision · priority P1 · created 2026-08-21 · closed 2026-08-21_
sam added the highdecision labels 2026-10-27 13:34:55 +00:00
sam self-assigned this 2026-10-27 13:34:55 +00:00
sam closed this issue 2026-10-27 13:34:55 +00:00
sam added a new dependency 2026-10-27 13:41:41 +00:00
sam added a new dependency 2026-10-27 13:41:41 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#94