provisional

package

v0.1.0 Latest Latest Go to latest Published: Jul 14, 2026 License: MIT Imports: 9 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/Rememorio/codog

Links

Open Source Insights

Documentation ¶

Overview ¶

Package provisional deduplicates in-flight status acknowledgements while retaining raw audit events.

Constants ¶

View Source

const (
	// DefaultWindow is the reconciliation window for unchanged provisional updates.
	DefaultWindow = 5 * time.Minute
	// DefaultTimeout is the maximum age for unchanged provisional status before escalation.
	DefaultTimeout = 30 * time.Minute

	// DecisionNew marks the first provisional status observed for a channel.
	DecisionNew = "new_provisional"
	// DecisionMaterialChange marks an update with a changed status fingerprint.
	DecisionMaterialChange = "material_change"
	// DecisionRepeatedAfterWindow marks an unchanged update exposed after the reconciliation window.
	DecisionRepeatedAfterWindow = "repeated_after_window"
	// DecisionSuppressedDuplicate marks an unchanged update hidden inside the reconciliation window.
	DecisionSuppressedDuplicate = "suppressed_duplicate"
	// DecisionStaleProvisional marks an unchanged provisional status that exceeded its TTL policy.
	DecisionStaleProvisional = "stale_provisional"
)

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type Escalation ¶

type Escalation struct {
	Kind            string        `json:"kind"`
	Signal          string        `json:"signal"`
	Channel         string        `json:"channel"`
	Fingerprint     string        `json:"fingerprint"`
	Actionable      bool          `json:"actionable"`
	StaleForSeconds int64         `json:"stale_for_seconds"`
	Policy          TimeoutPolicy `json:"policy"`
}

Escalation is the typed stale/blocker signal emitted for long-running provisional status.

type Event ¶

type Event struct {
	EventID       string    `json:"event_id"`
	Channel       string    `json:"channel"`
	Owner         string    `json:"owner,omitempty"`
	Status        string    `json:"status,omitempty"`
	ProgressState string    `json:"progress_state,omitempty"`
	Blocker       string    `json:"blocker,omitempty"`
	ETA           string    `json:"eta,omitempty"`
	Message       string    `json:"message,omitempty"`
	Fingerprint   string    `json:"fingerprint"`
	ObservedAt    time.Time `json:"observed_at"`
	Decision      string    `json:"decision"`
	Exposed       bool      `json:"exposed"`
}

Event is the audit record for a raw provisional status observation.

type Observation ¶

type Observation struct {
	Kind                string      `json:"kind"`
	Channel             string      `json:"channel"`
	Decision            string      `json:"decision"`
	Exposed             bool        `json:"exposed"`
	Reason              string      `json:"reason"`
	Fingerprint         string      `json:"fingerprint"`
	PreviousFingerprint string      `json:"previous_fingerprint,omitempty"`
	WindowSeconds       int64       `json:"window_seconds"`
	TimeoutSeconds      int64       `json:"timeout_seconds"`
	Stale               bool        `json:"stale"`
	Escalation          *Escalation `json:"escalation,omitempty"`
	Event               Event       `json:"event"`
	State               State       `json:"state"`
}

Observation reports the deduplication decision for a newly observed update.

type State ¶

type State struct {
	Kind                       string      `json:"kind"`
	Channel                    string      `json:"channel"`
	Fingerprint                string      `json:"fingerprint"`
	FirstObservedAt            time.Time   `json:"first_observed_at"`
	FingerprintFirstObservedAt time.Time   `json:"fingerprint_first_observed_at"`
	LastObservedAt             time.Time   `json:"last_observed_at"`
	LastExposedAt              time.Time   `json:"last_exposed_at"`
	RepeatCount                int         `json:"repeat_count"`
	SuppressedCount            int         `json:"suppressed_count"`
	RawEventCount              int         `json:"raw_event_count"`
	Stale                      bool        `json:"stale"`
	EscalationCount            int         `json:"escalation_count"`
	LastEscalatedAt            time.Time   `json:"last_escalated_at,omitempty"`
	LastDecision               string      `json:"last_decision"`
	TimeoutPolicy              string      `json:"timeout_policy,omitempty"`
	TimeoutSeconds             int64       `json:"timeout_seconds,omitempty"`
	DeadlineAt                 time.Time   `json:"deadline_at,omitempty"`
	LastEscalation             *Escalation `json:"last_escalation,omitempty"`
	LastExposedEvent           Event       `json:"last_exposed_event"`
	LastObservedEvent          Event       `json:"last_observed_event"`
}

State stores the latest deduplication state for a channel.

type Store ¶

type Store struct {
	Dir string
}

Store persists provisional status states and append-only audit events.

func NewStore ¶

func NewStore(configHome string) Store

NewStore returns a store rooted under configHome.

func (Store) Get ¶

func (s Store) Get(channel string) (State, error)

Get returns the current deduplication state for a channel.

func (Store) List ¶

func (s Store) List() ([]State, error)

List returns all known channel states ordered by most recent observation.

func (Store) Observe ¶

func (s Store) Observe(update Update) (Observation, error)

Observe records an update, returns whether it should be exposed, and always writes an audit event.

type TimeoutPolicy ¶

type TimeoutPolicy struct {
	ID             string    `json:"id"`
	TimeoutSeconds int64     `json:"timeout_seconds"`
	Basis          string    `json:"basis"`
	StartedAt      time.Time `json:"started_at"`
	DeadlineAt     time.Time `json:"deadline_at"`
	TriggeredAt    time.Time `json:"triggered_at,omitempty"`
}

TimeoutPolicy records the TTL rule applied to a provisional status.

type Update ¶

type Update struct {
	Channel       string
	Owner         string
	Status        string
	ProgressState string
	Blocker       string
	ETA           string
	Message       string
	ObservedAt    time.Time
	Window        time.Duration
	Timeout       time.Duration
	TimeoutPolicy string
}

Update describes a provisional or in-flight status acknowledgement to observe.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL