Event System

Events are facts, not commands. They are past-tense records of state changes. Interested parties poll for new events using a sequence-based cursor — there is no push-based event delivery in Phase 1.

Event Types

type EventType =
  | "entity.created"
  | "entity.updated"
  | "entity.deleted"
  | "entity.status.changed"
  | "telos.field.updated"
  | "workflow.started"
  | "workflow.step.entered"
  | "workflow.step.completed"
  | "workflow.step.failed"
  | "workflow.completed"
  | "workflow.failed"
  | "policy.evaluated"
  | "policy.created"
  | "policy.updated"
  | "policy.deleted";

Event Structure

interface LatticeEvent {
  id: string;              // Format: evt_<nanoid(12)>
  type: EventType;
  entityId: string;
  timestamp: string;       // ISO 8601
  data: Record<string, unknown>;
  seq: number;             // Monotonically increasing sequence number
}

Sequence Numbering

Events are assigned monotonically increasing sequence numbers via an atomic increment on the event_seq table (D1 batch operation). Consumers track their last-seen seq value and poll for seq > lastSeen.

Auto-Emitted Events

• entity.created — when POST /api/v1/entities succeeds
• entity.updated — on every successful PATCH (includes version and changed field names)
• entity.status.changed — when metadata.status is modified via PATCH
• telos.field.updated — one event per telos field changed in a PATCH (field name in data)
• policy.evaluated — when a policy check is performed via the policy check endpoint