deadletter

type DeadLetter struct {
	ID        string           `json:"id"`        // ULID — time-sortable within a namespace (cheap cap eviction)
	Namespace v1.NamespaceName `json:"namespace"` //
	Sensor    v1.ObjectName    `json:"sensor"`    // the Sensor whose action failed
	Source    v1.ObjectName    `json:"source"`    // the EventSource — from the delivery unit's dependency tuple
	Event     v1.ObjectName    `json:"event"`     // the event name — from the delivery unit's dependency tuple
	Action    string           `json:"action"`    // the Sensor action name (do[].name)
	Payload   json.RawMessage  `json:"payload"`   // the full CloudEvent JSON (re-injected verbatim on replay)
	Attempts  int              `json:"attempts"`  // delivery attempts made before dead-lettering (0 if never attempted)
	Reason    string           `json:"reason"`    // the terminal delivery error, or the park reason (ADR-0156)
	FailedAt  v1.Timestamp     `json:"failedAt"`  //
}

type Store interface {
	// Put creates or replaces a dead-letter record.
	Put(ctx context.Context, dl DeadLetter) error
	// Update replaces an existing record, or returns fault.NotFound if it is absent: replay re-parks with it,
	// so a discard or a retention sweep made during the replay stays in effect.
	Update(ctx context.Context, dl DeadLetter) error
	// List returns a namespace's dead letters, newest first (ID descending).
	List(ctx context.Context, ns v1.NamespaceName) ([]DeadLetter, error)
	// Get returns one record, or fault.NotFound if absent.
	Get(ctx context.Context, ns v1.NamespaceName, id string) (DeadLetter, error)
	// Delete removes a record (discard / replay-success); absent is not an error.
	Delete(ctx context.Context, ns v1.NamespaceName, id string) error
	// SweepExpired is store-global (no ns) and iterates ALL namespaces: the TTL is global — it evicts
	// entries older than retention across every namespace — while the count cap is enforced per-namespace,
	// by grouping keys under each dl/<ns>/ prefix and evicting the oldest over-cap in each. retention<=0
	// disables the TTL; maxPerNS<=0 disables the cap. Returns the number of records evicted.
	SweepExpired(ctx context.Context, retention time.Duration, maxPerNS int) (int, error)
	// Close releases the driver's resources.
	Close() error
}