Skip to content

[FEATURE] VNext Phase 7 — Trigger/Event runtime with dedupe, causality, and zero-token idle #341

Description

@Joncallim

Parent: #333
Execution mode: implementation
Depends on: #340, #347
Downstream consumers: #356, #190
Spec references: SPEC-0009 (Trigger/Event Envelope — CloudEvents compatibility, causality, loop prevention, deduplication, granular concurrency per dedupe identity), SPEC-0002 (Mission lifecycle, waiting state), SPEC-0004 (Operation identity, side-effect lifecycle), SPEC-0008 (conformance)

Problem Statement

Persistent Missions need deterministic wakeups, but implementing schedules/webhooks independently inside verification goals, Sentinel, HearthBot or each Workforce would recreate multiple scheduler truths and ambient LLM polling. Forge must have one Trigger/occurrence substrate that provides source authentication, dedupe, replay protection, causality, retry and zero-token irrelevant-event handling before recurring/autonomous features expand.

Desired Outcome

Missions can be awakened by manual actions, schedules and supported signed webhooks/events through one durable Trigger contract. Duplicate/replayed/self-induced events do not create duplicate Executions, disabled/revoked Missions do not wake, and deterministic filters terminate unchanged events with zero model calls.

Verification-goal scheduling (#356) and Sentinel scheduling (#190) are downstream consumers of this substrate. Phase 7 defines and proves the stable generic ports they need, but does not implement either downstream product feature and does not depend on either issue closing.

User Story

As the Forge operator,
I want ongoing Missions to wake only from authenticated, deduplicated and policy-admitted events,
So that monitoring and recurring work remain cheap, explainable and restart-safe without a permanent LLM poller.

Requirements

A. Trigger definition

Persist/version Trigger definitions with stable id/version/type, Mission binding, source/principal policy, Resource scope/classification, schedule or adapter configuration as data, dedupe/replay/debounce policy, deterministic prefilter policy, enabled/disabled state, inherited budget/authority constraints and actor/evidence.

A Trigger never owns broader authority than its Mission.

B. Occurrence contract

Every observed delivery creates or deterministically maps to a durable occurrence containing Trigger id/version, source/authentication state, external occurrence identity where available, observed time, stable dedupe/replay identity + policy window, causal parent event/Operation, Mission correlation, input Resource refs/safe metadata, lifecycle and attempt/error evidence.

Use PostgreSQL as occurrence truth; Redis is delivery/wakeup transport through #347.

C. Manual + schedule first

  • Manual Trigger is the baseline.
  • Add one replaceable schedule-engine adapter; product semantics live in Trigger definitions, not cron/systemd syntax.
  • Restart/missed schedule follows explicit catch-up policy (skip, latest, or bounded occurrences); never silently burst replay.
  • Clock/timezone/cadence calculations are deterministic/testable.

D. Webhook/event adapters

For supported signed sources validate signature/source identity, timestamp/replay window, body/header bounds and schema. Persist only policy-approved/redacted evidence. Unverifiable sources are explicitly lower-trust; endpoint arrival is not authentication.

E. Dedupe/debounce/coalescing

Same occurrence identity creates at most one eligible Execution under policy. Equivalent high-frequency observations may debounce/coalesce deterministically. Restart/ambiguous processing cannot become duplicate side effects. Replay windows/state are durable and bounded.

F. Causality/loop prevention

Per SPEC-0009 R8, loop prevention MUST detect multi-Trigger cycles (A→Operation→B→Operation→A) through bounded causal ancestry chains, not just same-Trigger self-loops. Trigger occurrence identity prevents duplicate execution intent; Operation identity separately prevents duplicate side effects.

G. Concurrency (per SPEC-0009 concurrency semantics)

Occurrence admission and deduplication are serialized per dedupe identity, NOT per Trigger definition. Independent occurrences for unrelated Resources MAY proceed concurrently within Mission/Execution/budget limits. Conflicting Resource mutation lanes MUST be serialized per Resource identity.

Record Forge-authored external Operation causal identities. Default policy prevents side-effect -> inbound-event recursive loops. Explicit causal chains are bounded by depth/count policy.

G. Deterministic prefilters

Cheap deterministic states such as unchanged, irrelevant, duplicate, outside-window, disabled, revoked or budget-blocked terminate without a model call and with stable reason/evidence.

H. Mission wake admission

Before requesting Execution re-check Mission state/lease, Grant/autonomy, Resource scope/version, budget, Trigger/source policy and egress/model policy only if cognition is needed. A stale queued occurrence cannot wake a cancelled/revoked Mission.

I. Downstream consumer contracts

Phase 7 owns only generic integration contracts and conformance fixtures:

J. Operator surface

Expose Trigger health, next/last schedule, last occurrence, auth state, ignore/dedupe/block reason, retry/dead state, linked Execution and recovery action without log spelunking.

Implementation Sequence

  1. Trigger/occurrence schemas + lifecycle invariants.
  2. Manual Trigger -> Mission Execution with durable occurrence/dedupe/authority/budget recheck.
  3. Schedule adapter with cadence/catch-up/timezone/restart semantics and zero-token deterministic runs.
  4. Occurrence retry/dead-letter using [BUG][P0] Make Postgres-to-Redis wakeups durable, idempotent, and recoverable #347 durable wakeup.
  5. Signed webhook fixture with auth/replay/body bounds and lower-trust unsigned state.
  6. Causality/loop prevention fixture and bounded explicit chain.
  7. Deterministic prefilter framework.
  8. Verification-style consumer conformance fixture — a synthetic schedule consumer proves the generic occurrence/Execution seam [FEATURE] Schedule verification-goal proof runs through generic Triggers #356 will consume; no [FEATURE] Schedule verification-goal proof runs through generic Triggers #356 module or goal scheduler is implemented.
  9. Sentinel-style consumer conformance fixture — a synthetic detector consumer proves the generic occurrence/detector-run seam [FEATURE] Add Project Sentinel detection and escalation flow #190 will consume; no [FEATURE] Add Project Sentinel detection and escalation flow #190 finding/detector product code is implemented.
  10. Operator APIs/UI + event-storm/restart/disabled-Mission/zero-token E2E.

Primary Code Seams To Inspect First

Do not import future #356 or #190 modules to make Phase 7 tests pass.

Orthogonal Checkpoints

  1. Occurrence identity: duplicate, replay, ambiguous delivery, DB/Redis restart.
  2. Authentication/security: forged signatures, stale timestamps, oversized input, credential/Resource confusion.
  3. Time/scheduling: timezone/DST, missed ticks, restart, burst catch-up, disabled state.
  4. Causality: self-loop, mutual loop, bounded explicit chains, event storms.
  5. Zero-token behavior: unchanged schedule windows and irrelevant events produce no model call.
  6. Authority: stale queued occurrence vs cancelled/revoked/demoted Mission.
  7. Consumer-contract isolation: synthetic verification/Sentinel consumers can use the generic seams, while Phase 7 has no dependency/import on [FEATURE] Schedule verification-goal proof runs through generic Triggers #356/[FEATURE] Add Project Sentinel detection and escalation flow #190 and no product-specific scheduler/detector truth.
  8. Final dependency review: repository/code search proves Phase 7 can close with [FEATURE] Schedule verification-goal proof runs through generic Triggers #356 and [FEATURE] Add Project Sentinel detection and escalation flow #190 still open.

Acceptance Criteria

Out of Scope

Implementation Scope

Very Large - durable event/scheduling/security integration, expected as 6-9 small PRs.

Technical Notes

Keep occurrences small/evidence-oriented; do not store arbitrary webhook bodies indefinitely. Event source authentication and Mission execution authorization are distinct checks and both are required. The key closure invariant is that Phase 7 proves a generic Trigger substrate; downstream consumers prove their own product integration later.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    dependency-blockedREADINESS PROJECTION — Issue is blocked by unresolved dependencies. This label is a cache.enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions