incidents

package
v0.36.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 17, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package incidents defines Incidentius's store-independent incident model and deterministic event projection. Persistence and transport adapters live in their owning repositories and depend on these validated types.

Index

Constants

View Source 
const (
	ActorViaWeb   = "web"
	ActorViaCLI   = "cli"
	ActorViaAPI   = "api"
	ActorViaSlack = "slack"
)
View Source 
const (
	ConfidenceSpeculative = "speculative"
	ConfidenceLikely      = "likely"
	ConfidenceConfirmed   = "confirmed"
)

Variables

View Source 
var (
	ErrMutationConflict = errors.New("incident mutation id was reused with different content")
	ErrSequenceConflict = errors.New("incident event sequence changed")
)

Functions

func MatchesListQuery added in v0.31.0 

func MatchesListQuery(incident IncidentView, query ListQuery) bool

func ValidateMutationID 

func ValidateMutationID(value string) error

ValidateMutationID applies the store-wide receipt key rules to every transport and storage mutation before the identifier is used as a path.

Types

type APIStore added in v0.31.0 

type APIStore interface {
	Store
	Create(ctx context.Context, mutation CreateMutation) (CreateResult, error)
	List(ctx context.Context, query CandidateListQuery) ([]Incident, error)
	Watch(ctx context.Context, query WatchQuery) (EventStream, error)
}

APIStore is the Task 3 server contract. Store remains source-compatible for append/replay adapters while providers implement atomic creation, querying, and a server-driven stream before exposing Incidentius endpoints.

type Actor 

type Actor struct {
	Kind ActorKind `json:"kind"`
	ID   string    `json:"id"`
	Via  string    `json:"via,omitempty"`
}

func (Actor) Validate added in v0.31.0 

func (a Actor) Validate() error

type ActorKind 

type ActorKind string
const (
	ActorHuman  ActorKind = "human"
	ActorAgent  ActorKind = "agent"
	ActorSystem ActorKind = "system"
)

type AppendResult 

type AppendResult struct {
	Event      Event    `json:"event"`
	Projection Incident `json:"projection"`
	Replayed   bool     `json:"replayed"`
}

type ArtifactRef 

type ArtifactRef struct {
	Kind       RefKind             `json:"kind"`
	ID         string              `json:"id,omitempty"`
	Incident   *IncidentRef        `json:"incident,omitempty"`
	Project    *ProjectRef         `json:"project,omitempty"`
	Execution  *ExecutionRef       `json:"execution,omitempty"`
	Artifact   *ProjectArtifactRef `json:"artifact,omitempty"`
	Comparison *ComparisonRef      `json:"comparison,omitempty"`
}

ArtifactRef uses structured identities for cross-store artifacts. ID is reserved for incident-local hypotheses and events.

func (ArtifactRef) Validate 

func (r ArtifactRef) Validate() error

type Assertion 

type Assertion struct {
	Kind       AssertionKind `json:"kind"`
	Confidence string        `json:"confidence,omitempty"`
}

type AssertionKind 

type AssertionKind string
const (
	AssertionObservation         AssertionKind = "observation"
	AssertionClaim               AssertionKind = "claim"
	AssertionQuestion            AssertionKind = "question"
	AssertionHypothesis          AssertionKind = "hypothesis"
	AssertionInference           AssertionKind = "inference"
	AssertionDeterministicResult AssertionKind = "deterministic-result"
)

type AssetRefEntry added in v0.31.0 

type AssetRefEntry struct {
	EventID string      `json:"eventId"`
	Ref     ArtifactRef `json:"ref"`
}

AssetRefEntry retains the stable source event for each derived backlink. AssetRefs remains the source-compatible unique projection for older readers.

type CandidateListQuery added in v0.31.0 

type CandidateListQuery struct {
	Statuses       []Status `json:"statuses,omitempty"`
	ProjectStoreID string   `json:"projectStoreId,omitempty"`
	ProjectID      string   `json:"project,omitempty"`
	Environment    string   `json:"environment,omitempty"`
}

CandidateListQuery is the provider-facing safe subset. Protected backlink filters are applied only after current-policy IncidentViews are constructed.

func (CandidateListQuery) Validate added in v0.31.0 

func (q CandidateListQuery) Validate() error

type CanonicalContext added in v0.31.0 

type CanonicalContext = investigation.Context

CanonicalContext is an alias, not an incident-specific model. Incidents and the transport appendix consume the same Investigation Context type.

type CompareRunPayload added in v0.34.0 

type CompareRunPayload struct {
	Key []string `json:"key"`
}

CompareRunPayload persists only the deterministic key contract. The row diff remains an endpoint result and must never enter the incident event log.

type ComparisonRef 

type ComparisonRef struct {
	Left  ExecutionRef `json:"left"`
	Right ExecutionRef `json:"right"`
}

func (ComparisonRef) Validate 

func (r ComparisonRef) Validate() error

type ContextFactAddedPayload added in v0.33.0 

type ContextFactAddedPayload struct {
	Fact investigation.Fact `json:"fact"`
}

type ContextFactAddedViewPayload added in v0.33.0 

type ContextFactAddedViewPayload struct {
	Fact investigation.FactView `json:"fact"`
}

type ContextFactPromotedPayload added in v0.33.0 

type ContextFactPromotedPayload struct {
	Fact ContextFactRef `json:"fact"`
	Role string         `json:"role"`
}

func (ContextFactPromotedPayload) Validate added in v0.33.0 

func (p ContextFactPromotedPayload) Validate() error

type ContextFactRef added in v0.33.0 

type ContextFactRef struct {
	Scope investigation.ProjectScope `json:"scope"`
	ID    string                     `json:"id"`
	Layer string                     `json:"layer"`
}

ContextFactRef identifies one fact within one named context layer. Fact IDs remain project-scoped; layer disambiguates the retained overlay original from a canonical promotion copy.

func (ContextFactRef) Key added in v0.33.0 

func (r ContextFactRef) Key() investigation.FactKey

func (ContextFactRef) Validate added in v0.33.0 

func (r ContextFactRef) Validate() error

type ContextFactRejectedPayload added in v0.33.0 

type ContextFactRejectedPayload struct {
	Layer string `json:"layer"`
}

func (ContextFactRejectedPayload) Validate added in v0.33.0 

func (p ContextFactRejectedPayload) Validate() error

type ContextPromotion added in v0.33.0 

type ContextPromotion struct {
	EventID string         `json:"eventId"`
	Fact    ContextFactRef `json:"fact"`
	Role    string         `json:"role"`
}

ContextPromotion is durable projection history for a promotion event. The source fact remains in CanonicalContext under its overlay layer.

func (ContextPromotion) Validate added in v0.33.0 

func (p ContextPromotion) Validate() error

type ContextRejection added in v0.33.0 

type ContextRejection struct {
	EventID string `json:"eventId"`
	Layer   string `json:"layer"`
}

func (ContextRejection) Validate added in v0.33.0 

func (r ContextRejection) Validate() error

type CreateMutation added in v0.31.0 

type CreateMutation struct {
	MutationID       string           `json:"mutationId"`
	StoreID          string           `json:"storeId"`
	UID              string           `json:"uid"`
	Title            string           `json:"title"`
	Description      string           `json:"description,omitempty"`
	At               time.Time        `json:"at"`
	Reporter         Actor            `json:"reporter"`
	PrimaryProject   ProjectRef       `json:"primaryProject"`
	Projects         []ProjectRef     `json:"projects,omitempty"`
	CanonicalContext CanonicalContext `json:"canonicalContext"`
}

CreateMutation is allocated atomically by a store. IncidentID is absent on purpose: the implementation assigns the next store-scoped INC-n while it holds the same exclusion boundary used to commit the first event.

func (CreateMutation) Validate added in v0.31.0 

func (m CreateMutation) Validate() error

type CreateResult added in v0.31.0 

type CreateResult struct {
	Event      Event    `json:"event"`
	Projection Incident `json:"projection"`
	Replayed   bool     `json:"replayed"`
}

type CreatedPayload 

type CreatedPayload struct {
	UID              string           `json:"uid"`
	Title            string           `json:"title"`
	Description      string           `json:"description"`
	Projects         []ProjectRef     `json:"projects,omitempty"`
	Reporter         Actor            `json:"reporter"`
	CanonicalContext CanonicalContext `json:"canonicalContext"`
}

type CreatedViewPayload added in v0.31.0 

type CreatedViewPayload struct {
	UID              string                    `json:"uid"`
	Title            string                    `json:"title"`
	Description      string                    `json:"description"`
	Projects         []ProjectRef              `json:"projects,omitempty"`
	Reporter         Actor                     `json:"reporter"`
	CanonicalContext investigation.ContextView `json:"canonicalContext"`
}

type Event 

type Event struct {
	ID        string      `json:"id"`
	Seq       uint64      `json:"seq"`
	At        time.Time   `json:"at"`
	VisibleAt time.Time   `json:"visibleAt"`
	Incident  IncidentRef `json:"incident"`
	// ImportedFrom preserves the original identity of an event copied by a
	// merge. Imported events remain timeline evidence but do not mutate the
	// survivor's active projection.
	ImportedFrom *ImportedEventRef `json:"importedFrom,omitempty"`
	Actor        Actor             `json:"actor"`
	Type         EventType         `json:"type"`
	Assertion    Assertion         `json:"assertion"`
	Refs         []ArtifactRef     `json:"refs,omitempty"`
	Payload      json.RawMessage   `json:"payload"`
}

func ApplyEventView added in v0.31.0 

func ApplyEventView(stored Event, policy ViewPolicy) (Event, bool, error)

func (Event) Validate 

func (e Event) Validate() error

func (Event) ValidateView added in v0.31.0 

func (e Event) ValidateView() error

ValidateView validates a detached, policy-filtered event. Unlike persisted events, a view may contain explicit fact-value redaction markers.

type EventCursor added in v0.31.0 

type EventCursor string

func (EventCursor) Validate added in v0.31.0 

func (c EventCursor) Validate() error

type EventDraft 

type EventDraft struct {
	At        time.Time       `json:"at"`
	Actor     Actor           `json:"actor"`
	Type      EventType       `json:"type"`
	Assertion Assertion       `json:"assertion"`
	Refs      []ArtifactRef   `json:"refs,omitempty"`
	Payload   json.RawMessage `json:"payload"`
}

func (EventDraft) Validate 

func (d EventDraft) Validate(incident IncidentRef) error

type EventStream added in v0.31.0 

type EventStream interface {
	Next(ctx context.Context) (StreamItem, error)
	Close() error
}

type EventType 

type EventType string
const (
	EventIncidentCreated     EventType = "incident.created"
	EventIncidentStatus      EventType = "incident.status"
	EventIncidentOutcome     EventType = "incident.outcome"
	EventIncidentMerged      EventType = "incident.merged"
	EventNoteAdded           EventType = "note.added"
	EventContextFactAdded    EventType = "context.fact.added"
	EventContextFactPromoted EventType = "context.fact.promoted"
	EventContextFactRejected EventType = "context.fact.rejected"
	EventCompareRun          EventType = "compare.run"
)

type ExecutionRef 

type ExecutionRef struct {
	StoreID     string `json:"storeId"`
	ProjectID   string `json:"projectId"`
	ExecutionID string `json:"executionId"`
}

func (ExecutionRef) Validate 

func (r ExecutionRef) Validate() error

type FactSignal added in v0.31.0 

type FactSignal struct {
	Entity    string                   `json:"entity"`
	Field     string                   `json:"field"`
	Value     investigation.TypedValue `json:"value"`
	Condition string                   `json:"condition,omitempty"`
}

func (FactSignal) Validate added in v0.31.0 

func (s FactSignal) Validate() error

type FactVisibility added in v0.31.0 

type FactVisibility string
const (
	FactVisible       FactVisibility = "visible"
	FactValueRedacted FactVisibility = "value-redacted"
	FactHidden        FactVisibility = "hidden"
)

type ImportedEventRef 

type ImportedEventRef struct {
	Incident IncidentRef `json:"incident"`
	EventID  string      `json:"eventId"`
	Seq      uint64      `json:"seq"`
	MergeID  string      `json:"mergeId"`
}

func (ImportedEventRef) Validate 

func (r ImportedEventRef) Validate(destination IncidentRef) error

type Incident 

type Incident struct {
	Ref               IncidentRef        `json:"ref"`
	UID               string             `json:"uid"`
	Title             string             `json:"title"`
	Description       string             `json:"description,omitempty"`
	Status            Status             `json:"status"`
	Outcome           Outcome            `json:"outcome,omitempty"`
	MergedInto        *IncidentRef       `json:"mergedInto,omitempty"`
	Projects          []ProjectRef       `json:"projects,omitempty"`
	Participants      []Participant      `json:"participants,omitempty"`
	CanonicalContext  CanonicalContext   `json:"canonicalContext"`
	ContextPromotions []ContextPromotion `json:"contextPromotions,omitempty"`
	ContextRejections []ContextRejection `json:"contextRejections,omitempty"`
	AssetRefs         []ArtifactRef      `json:"assetRefs,omitempty"`
	AssetRefEntries   []AssetRefEntry    `json:"assetRefEntries,omitempty"`
	NoteEntries       []Note             `json:"noteEntries,omitempty"`
	Notes             []string           `json:"notes,omitempty"`
	LastSeq           uint64             `json:"lastSeq"`
}

Incident is the deterministic current or historical projection.

func Fold 

func Fold(events []Event, at *time.Time) (Incident, error)

func (Incident) Validate added in v0.31.0 

func (i Incident) Validate() error

type IncidentRef 

type IncidentRef struct {
	StoreID    string `json:"storeId"`
	IncidentID string `json:"incidentId"`
}

IncidentRef is the globally unambiguous identity of an incident.

func ParseIncidentRef 

func ParseIncidentRef(value string) (IncidentRef, error)

func (IncidentRef) String 

func (r IncidentRef) String() string

func (IncidentRef) Validate 

func (r IncidentRef) Validate() error

type IncidentView added in v0.31.0 

type IncidentView struct {
	Ref               IncidentRef               `json:"ref"`
	UID               string                    `json:"uid"`
	Title             string                    `json:"title"`
	Description       string                    `json:"description,omitempty"`
	Status            Status                    `json:"status"`
	Outcome           Outcome                   `json:"outcome,omitempty"`
	MergedInto        *IncidentRef              `json:"mergedInto,omitempty"`
	Projects          []ProjectRef              `json:"projects,omitempty"`
	Participants      []Participant             `json:"participants,omitempty"`
	CanonicalContext  investigation.ContextView `json:"canonicalContext"`
	ContextPromotions []ContextPromotion        `json:"contextPromotions,omitempty"`
	ContextRejections []ContextRejection        `json:"contextRejections,omitempty"`
	AssetRefs         []ArtifactRef             `json:"assetRefs,omitempty"`
	Notes             []string                  `json:"notes,omitempty"`
	LastSeq           uint64                    `json:"lastSeq"`
}

IncidentView is a detached current-policy projection. The stored Incident always contains canonical facts; only this read model may contain redaction markers.

func ApplyIncidentView added in v0.31.0 

func ApplyIncidentView(stored Incident, policy ViewPolicy) IncidentView

func (IncidentView) Validate added in v0.31.0 

func (i IncidentView) Validate() error

type ListQuery added in v0.31.0 

type ListQuery struct {
	Statuses       []Status `json:"statuses,omitempty"`
	ProjectStoreID string   `json:"projectStoreId,omitempty"`
	ProjectID      string   `json:"project,omitempty"`
	Environment    string   `json:"environment,omitempty"`
	QueryID        string   `json:"query,omitempty"`
	CheckID        string   `json:"check,omitempty"`
	BoardID        string   `json:"board,omitempty"`
}

func (ListQuery) Candidates added in v0.31.0 

func (q ListQuery) Candidates() CandidateListQuery

func (ListQuery) Validate added in v0.31.0 

func (q ListQuery) Validate() error

func (ListQuery) ValidateArtifactFilters added in v0.31.0 

func (q ListQuery) ValidateArtifactFilters() error

ValidateArtifactFilters validates the public filter values before a serving adapter resolves their project store and constructs the scoped ListQuery.

type MatchedSignal added in v0.31.0 

type MatchedSignal struct {
	Kind  SignalKind `json:"kind"`
	Value string     `json:"value"`
}

func (MatchedSignal) Validate added in v0.31.0 

func (s MatchedSignal) Validate() error

type MergeMutation 

type MergeMutation struct {
	MutationID string      `json:"mutationId"`
	Source     IncidentRef `json:"source"`
	Into       IncidentRef `json:"into"`
}

func (MergeMutation) Validate 

func (m MergeMutation) Validate() error

type MergeResult 

type MergeResult struct {
	Source   Incident `json:"source"`
	Into     Incident `json:"into"`
	Replayed bool     `json:"replayed"`
}

type MergedPayload 

type MergedPayload struct {
	Into    IncidentRef `json:"into"`
	MergeID string      `json:"mergeId"`
}

type Mutation 

type Mutation struct {
	MutationID  string      `json:"mutationId"`
	Incident    IncidentRef `json:"incident"`
	ExpectedSeq *uint64     `json:"expectedSeq,omitempty"`
	Event       EventDraft  `json:"event"`
}

func (Mutation) Validate 

func (m Mutation) Validate() error

type Note added in v0.31.0 

type Note struct {
	EventID string `json:"eventId"`
	Body    string `json:"body"`
}

Note retains the stable source event identity required to re-check human text visibility without keying a policy decision by its sensitive body.

type NoteAddedPayload 

type NoteAddedPayload struct {
	Body string `json:"body"`
}

type Outcome 

type Outcome string
const (
	OutcomeResolved   Outcome = "resolved"
	OutcomeFalseAlarm Outcome = "false-alarm"
	OutcomeAccepted   Outcome = "accepted"
	OutcomeHandedOff  Outcome = "handed-off"
	OutcomeUnresolved Outcome = "unresolved"
)

type OutcomePayload 

type OutcomePayload struct {
	Outcome Outcome `json:"outcome"`
}

type Participant added in v0.31.0 

type Participant struct {
	Actor Actor           `json:"actor"`
	Role  ParticipantRole `json:"role"`
}

type ParticipantRole added in v0.31.0 

type ParticipantRole string
const ParticipantReporter ParticipantRole = "reporter"

type ProjectArtifactRef 

type ProjectArtifactRef struct {
	StoreID     string `json:"storeId"`
	ProjectID   string `json:"projectId"`
	Environment string `json:"environment,omitempty"`
	ID          string `json:"id"`
}

func (ProjectArtifactRef) Validate 

func (r ProjectArtifactRef) Validate() error

type ProjectRef 

type ProjectRef = investigation.ProjectScope

ProjectRef remains a source- and wire-compatible alias of the one canonical persisted project scope used by Investigation Context facts.

type RefKind 

type RefKind string
const (
	RefExecution  RefKind = "execution"
	RefSnapshot   RefKind = "snapshot"
	RefAnnotation RefKind = "annotation"
	RefCheck      RefKind = "check"
	RefCompare    RefKind = "compare"
	RefQuery      RefKind = "query"
	RefBoard      RefKind = "board"
	RefFact       RefKind = "fact"
	RefHypothesis RefKind = "hypothesis"
	RefEvent      RefKind = "event"
	RefIncident   RefKind = "incident"
	RefProject    RefKind = "project"
)

type SearchMatch added in v0.31.0 

type SearchMatch struct {
	Incident       IncidentView    `json:"incident"`
	MatchedSignals []MatchedSignal `json:"matchedSignals"`
}
func Search(candidates []IncidentView, query SearchQuery) []SearchMatch

Search operates only on current-policy views. Hidden and redacted fact values therefore cannot influence a match or leak through matched signals.

func (SearchMatch) Validate added in v0.31.0 

func (m SearchMatch) Validate() error

type SearchQuery added in v0.31.0 

type SearchQuery struct {
	Text  string       `json:"text"`
	Facts []FactSignal `json:"facts,omitempty"`
}

func (SearchQuery) Validate added in v0.31.0 

func (q SearchQuery) Validate() error

type SharedLayout 

type SharedLayout struct {
	IncidentDir         string
	Events              string
	Projection          string
	MutationReceiptsDir string
	StoreLock           string
	MergeIntentsDir     string
}

func LayoutFor 

func LayoutFor(ref IncidentRef) (SharedLayout, error)

type SignalKind added in v0.31.0 

type SignalKind string
const (
	SignalText    SignalKind = "text"
	SignalFact    SignalKind = "fact"
	SignalQuery   SignalKind = "query"
	SignalCheck   SignalKind = "check"
	SignalBoard   SignalKind = "board"
	SignalProject SignalKind = "project"
)

type SimilarMatch added in v0.31.0 

type SimilarMatch struct {
	Incident       IncidentView    `json:"incident"`
	Score          int             `json:"score"`
	MatchedSignals []MatchedSignal `json:"matchedSignals"`
}

func Similar added in v0.31.0 

func Similar(subject IncidentView, candidates []IncidentView) []SimilarMatch

Similar operates only on current-policy views for the same reason as Search.

func (SimilarMatch) Validate added in v0.31.0 

func (m SimilarMatch) Validate() error

type Status 

type Status string
const (
	StatusOpen          Status = "open"
	StatusInvestigating Status = "investigating"
	StatusMitigating    Status = "mitigating"
	StatusRecovering    Status = "recovering"
	StatusResolved      Status = "resolved"
	StatusWatching      Status = "watching"
	StatusClosed        Status = "closed"
)

type StatusPayload 

type StatusPayload struct {
	Status Status `json:"status"`
}

type Store 

type Store interface {
	Append(ctx context.Context, mutation Mutation) (AppendResult, error)
	Events(ctx context.Context, ref IncidentRef, afterSeq uint64) ([]Event, error)
	Projection(ctx context.Context, ref IncidentRef, at *time.Time) (Incident, error)
	Merge(ctx context.Context, mutation MergeMutation) (MergeResult, error)
}

Store is implemented once per configured StoreLocation. Append and Merge own cross-process exclusion, durable mutation receipts, and crash recovery.

type StoreLocation 

type StoreLocation struct {
	StoreID string            `json:"storeId"`
	Kind    StoreLocationKind `json:"kind"`
	Project *ProjectRef       `json:"project,omitempty"`
}

StoreLocation selects where one incident store is hosted. All kinds use SharedLayout; adapters differ only in how their DALgo database is opened.

func (StoreLocation) Validate 

func (l StoreLocation) Validate() error

type StoreLocationKind 

type StoreLocationKind string
const (
	StoreLocationProjectRepository     StoreLocationKind = "project-repository"
	StoreLocationDedicatedRepository   StoreLocationKind = "dedicated-repository"
	StoreLocationApplicationRepository StoreLocationKind = "application-repository"
)

type StreamItem added in v0.31.0 

type StreamItem struct {
	Cursor EventCursor `json:"cursor"`
	Event  Event       `json:"event"`
}

func ApplyStreamItemView added in v0.31.0 

func ApplyStreamItemView(stored StreamItem, policy ViewPolicy) (StreamItem, bool, error)

ApplyStreamItemView applies the same current-policy event decision to watch items while preserving the provider's opaque resumable cursor.

func (StreamItem) Validate added in v0.31.0 

func (i StreamItem) Validate() error

type ViewPolicy added in v0.31.0 

type ViewPolicy struct {
	// Facts is a complete, scope-qualified decision set. Missing decisions are
	// hidden fail-closed; adapters must emit FactVisible for authorized facts.
	Facts          map[investigation.FactKey]FactVisibility
	WithheldEvents map[string]bool
}

ViewPolicy is a set of decisions produced by the serving adapter's current policy evaluator. It is deliberately not persisted and performs no policy evaluation itself.

type WatchQuery added in v0.31.0 

type WatchQuery struct {
	Incident *IncidentRef `json:"incident,omitempty"`
	Since    EventCursor  `json:"since,omitempty"`
}

func (WatchQuery) Validate added in v0.31.0 

func (q WatchQuery) Validate() error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.