singularity-forge/docs/design-docs/notification-event-model.md

Notification Event Model

Status: Draft

Context

Observed facts:

• The current working CLI/product is Singularity Forge.
• The active runtime and transcript/agent-loop implementation live in this repository.
• The reported issue involves automated workflow/system notices appearing near or instead of user-authored input.

Inferred facts:

• A future runtime needs event metadata rather than text matching to separate user messages from notices.

The product needs a durable distinction between user-authored messages and automated workflow status. Without that boundary, repeated system notices can look like user input and can interrupt the work the user actually requested.

Decision

Model inbound transcript events with an explicit source and blocking flag:

• source: user, system, tool, or workflow.
• kind: message, notice, warning, error, or approval_request.
• blocking: whether user action is required before work can continue.
• dedupe_key: stable key for grouping repeated non-blocking notices.
• created_at: event timestamp from the producing system.

Rendering and scheduling should prioritize source=user events over non-blocking notices. Blocking notices may interrupt, but they must still render as notices rather than user messages.

Consequences

• Transcript rendering can label notices without relying on fragile text matching.
• Duplicate workflow notices can be grouped by dedupe_key.
• Tests can assert that user input remains primary when notices arrive nearby.
• Integrations must supply enough metadata to classify events correctly.

Verification

When implemented, add unit tests for classification, deduplication, and transcript ordering.