Events & Triggers

Ported and adapted to gist's TriggerDefinition and EventDelivery models.

Principle

Spatial relationships are facts. Events represent the operational consequence of those facts.

Fact:        Road intersects mining lease
Consequence: Coordination required

Trigger sources (TriggerDefinition)

A TriggerDefinition binds an entity's watched events to a list of actions. Seeded triggers:

Code Entity Watches Actions
FEATURE_CREATED SpatialFeature created validate → derive geometry → evaluate rules → audit
FEATURE_GEOMETRY_CHANGED SpatialFeature geometry_changed validate → derive → evaluate → detect changed/ceased → audit
GEOJSON_IMPORT_COMPLETED DataTransfer completed evaluate imported features → audit

Later: scheduled re-evaluation, external GIS update, reconciliation job.

Event lifecycle (SpatialEvent.status)

stateDiagram-v2
    [*] --> pending
    pending --> emitted
    pending --> failed
    failed --> pending: retry
    emitted --> acknowledged
    acknowledged --> closed
    emitted --> closed: no downstream action required

Required event fields

event_id · event_type · severity · tenant_id · correlation_id · rule_id · source/target feature refs · relationship_id · evaluation_run_id · disclosure_profile_code · payload · emitted_at. The event carries its disclosure profile so delivery knows what may cross the boundary.

Delivery (EventDelivery)

Each event is delivered per destination by an EventDelivery row: destination_code, endpoint, status (queued → sending → delivered → acknowledged → retrying → failed), attempt_count, idempotency_key (= event_id, header X-Event-ID), response status/body. The demo delivers all six events to orchestrator at http://orchestrator:8000/api/v1/events.

Idempotency

Repeated delivery of the same event_id must be treated as replay, not a new business event.

Failure behaviour

If the Orchestrator is unavailable:

  1. persist the event;
  2. mark the EventDelivery failed;
  3. retry (backoff 5 / 15 / 60 / 300 / 900 s, max_attempts: 5);
  4. retain audit history;
  5. allow manual replay.

No spatial event should be lost because of a temporary downstream outage.