Events Worker

Events Worker

Status: Current local implementation reference; deployment validation pending

Last reviewed: 2026-10-21

Purpose and boundary

Events reads the canonical Corpus change feed, validates each event, publishes accepted batches to the toastmachine-events queue and records producer progress. MCP consumes that queue separately. Queue acceptance does not prove downstream processing, and Events does not provide exactly-once delivery.

The Worker has no public HTTP API. Its scheduled handler invokes one singleton Durable Object named canonical-event-pump. The Durable Object serializes overlapping scheduled invocations in process and stores the durable checkpoint in its own storage.

Identity-bound checkpoint

Checkpoint version 1 is:

{
  "version": 1,
  "corpus_id": "11111111-1111-4111-8111-111111111111",
  "history_lineage": "22222222-2222-4222-8222-222222222222",
  "sequence": 42
}

For an existing checkpoint, every feed request sends X-Expected-Corpus-Id and X-Expected-Corpus-Lineage. Every successful feed page must return a complete, valid authoritative pair matching the checkpoint before any page event is queued. A mismatch or malformed/missing identity fails the run without changing the checkpoint.

A new installation starts at sequence zero only after a successful feed response establishes authoritative identity. Events stores that identity before it can publish the first page. Sequence remains the last event accepted by the queue, not an event count; valid gaps are allowed.

Legacy KV migration

The KV namespace remains only for migrating the earlier last_sequence value. Bare numeric state is ambiguous and fails closed unless both LEGACY_CHECKPOINT_CORPUS_ID and LEGACY_CHECKPOINT_LINEAGE are configured from externally verified evidence about that cursor’s original scope.

Migration sends those values as feed expectations and completes only when Corpus returns the same authoritative pair. Events then stores the versioned Durable Object checkpoint and deletes the legacy KV value. Any request, identity or storage failure leaves the legacy value and prior versioned state unchanged. Operators must not use migration settings to relabel an unknown cursor or one from another lineage.

Processing and failure semantics

Each page is parsed as NDJSON. Events rejects malformed JSON, noncanonical event envelopes, oversized messages and sequences that do not strictly increase from the current checkpoint. It batches at no more than 100 events and within the configured queue byte budget.

For each batch, queue acceptance happens before checkpoint storage. A queue failure does not advance progress. If queue acceptance succeeds and checkpoint storage fails, a later run can publish that batch again. Consumers must therefore tolerate duplicate observations within the same corpus and lineage. The implementation does not claim exactly-once delivery.

The coordinator prevents two scheduled executions from concurrently overwriting the checkpoint in the current Worker instance. No transaction spans Corpus, Queue and Durable Object storage. Deployment of the v1-event-pump-checkpoint Durable Object migration is required before the updated scheduled handler runs.

Configuration

Evidence and limits

Current behavior is covered by local Worker tests for initialization, resume, mismatches, ambiguous and attested legacy migration, failed feed/queue/storage operations, restart and overlapping invocations. Provider-level Durable Object scheduling, Queue delivery and migration behavior have not been tested in deployed infrastructure.

Related sources:

• Events Worker implementation
• Checkpoint validation
• Pagination and synchronization
• Multi-corpus identity decision