# Notification Event Model

Status: Draft

## Context

Observed facts:

- The current working CLI/product is Singularity Forge.
- `singularity-foundry` is the old name/path.
- The active runtime and transcript/agent-loop implementation live in `/home/mhugo/code/singularity-forge`.
- The reported issue involves automated workflow/system notices appearing near or instead of user-authored input.

Inferred facts:

- The Forge/Foundry naming mismatch can make triage confusing, but the runtime risk is event-source confusion.
- 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.