Idempotency and poll/webhook parity: never double-dispatch, never lose work #98

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

Webhooks deliver at-least-once, out of order, and sometimes not at all. Polling is the opposite: slow but eventually consistent. Running both (intake='both') is the honest production configuration, and it is also where the two failure modes meet.

Two things must hold. A single issue event must not start two tasks because the webhook and the next poll both saw it. And a webhook outage must not silently stop work -- if the receiver is wedged or the ingress is down, polling has to pick the work up, which is the entire argument for keeping it.

Note archie-core-...-286 (WebhookAdapter: idempotency cache) already exists for the chat adapter. Decide whether that mechanism generalises to intake or whether forge dispatch needs its own key; do not build a second one by accident.

The silent-failure shape to design against is the one this codebase keeps hitting: a path that looks like it is working because nothing errors. A webhook receiver that has silently stopped delivering looks identical to a repo with no activity.

Acceptance criteria

A duplicate delivery of the same forge event starts exactly one task; with intake='both', disabling the webhook path still results in the work being picked up by polling; a wedged or non-delivering webhook receiver is observable rather than indistinguishable from an idle repo.

Close reason

Investigated first: the dedup mechanism (TaskEnvelope.IdempotencyKey + PublishUnique + JetStream Nats-Msg-Id dedup) and the shared dispatch predicate were already fully wired by 7d5u.4 -- no double-dispatch code change was needed. Closed the two real gaps: (1) internal/infrastructure/eventbus/nats/dedup_test.go is a new regression test proving PublishUnique actually suppresses a duplicate publish on the same WorkQueuePolicy stream ARCHIE_TASKS uses in production; (2) internal/forge/webhook/receiver.go gained Status()/GET support tracking authenticated deliveries vs successful publishes separately, so a wedged or non-delivering receiver is observable rather than indistinguishable from an idle repo. AC's poll/webhook parity clause (disabling webhook still polls) is satisfied architecturally with no code change possible to violate it -- verified Cycle()/Run() never reference cfg.Forge.Intake anywhere in internal/daemon; only setupForgeWebhook in cmd/archied/bootstrap.go gates the webhook HTTP server. Adversarial review pass (fresh subagent, -race) found zero blocking issues; closed two minor coverage gaps it flagged. [Closure restored 2026-08-24: originally closed 2026-08-22, lost when the beads DB was rebuilt (.beads.backup-pre-recovery).]


Imported from beads archie-core-7d5u.5 · GitHub #543 · type feature · priority P1 · created 2026-08-21 · closed 2026-08-24

Webhooks deliver at-least-once, out of order, and sometimes not at all. Polling is the opposite: slow but eventually consistent. Running both (intake='both') is the honest production configuration, and it is also where the two failure modes meet. Two things must hold. A single issue event must not start two tasks because the webhook and the next poll both saw it. And a webhook outage must not silently stop work -- if the receiver is wedged or the ingress is down, polling has to pick the work up, which is the entire argument for keeping it. Note archie-core-...-286 (WebhookAdapter: idempotency cache) already exists for the chat adapter. Decide whether that mechanism generalises to intake or whether forge dispatch needs its own key; do not build a second one by accident. The silent-failure shape to design against is the one this codebase keeps hitting: a path that looks like it is working because nothing errors. A webhook receiver that has silently stopped delivering looks identical to a repo with no activity. ### Acceptance criteria A duplicate delivery of the same forge event starts exactly one task; with intake='both', disabling the webhook path still results in the work being picked up by polling; a wedged or non-delivering webhook receiver is observable rather than indistinguishable from an idle repo. ### Close reason Investigated first: the dedup mechanism (TaskEnvelope.IdempotencyKey + PublishUnique + JetStream Nats-Msg-Id dedup) and the shared dispatch predicate were already fully wired by 7d5u.4 -- no double-dispatch code change was needed. Closed the two real gaps: (1) internal/infrastructure/eventbus/nats/dedup_test.go is a new regression test proving PublishUnique actually suppresses a duplicate publish on the same WorkQueuePolicy stream ARCHIE_TASKS uses in production; (2) internal/forge/webhook/receiver.go gained Status()/GET support tracking authenticated deliveries vs successful publishes separately, so a wedged or non-delivering receiver is observable rather than indistinguishable from an idle repo. AC's poll/webhook parity clause (disabling webhook still polls) is satisfied architecturally with no code change possible to violate it -- verified Cycle()/Run() never reference cfg.Forge.Intake anywhere in internal/daemon; only setupForgeWebhook in cmd/archied/bootstrap.go gates the webhook HTTP server. Adversarial review pass (fresh subagent, -race) found zero blocking issues; closed two minor coverage gaps it flagged. [Closure restored 2026-08-24: originally closed 2026-08-22, lost when the beads DB was rebuilt (.beads.backup-pre-recovery).] --- _Imported from beads `archie-core-7d5u.5` · GitHub #543 · type feature · priority P1 · created 2026-08-21 · closed 2026-08-24_
sam added the highfeature labels 2026-10-27 13:34:56 +00:00
sam self-assigned this 2026-10-27 13:34:56 +00:00
sam closed this issue 2026-10-27 13:34:56 +00:00
sam added a new dependency 2026-10-27 13:41:42 +00:00
sam added a new dependency 2026-10-27 13:41:42 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#98