workflowprogress

package

v0.0.0-...-1e7ba32 Latest Latest Go to latest Published: Sep 20, 2026 License: MIT Imports: 6 Imported by: 0

Details

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

Repository

github.com/omarluq/librecode

Links

Open Source Insights

Documentation ¶

Overview ¶

Package workflowprogress defines and enforces the bounded progress contract shared by MVM execution profiles. Progress is presentation metadata only; it does not create work, dependencies, or scheduling barriers.

Constants ¶

View Source

const (
	// ContractVersion identifies the serialized progress envelope contract.
	ContractVersion = 1
	// MaxEvents bounds accepted progress updates in one evaluation.
	MaxEvents = 256
	// MaxIDBytes bounds phase/item identifiers.
	MaxIDBytes = 128
	// MaxTextBytes bounds titles, event names, log messages, and levels.
	MaxTextBytes = 4096
	// MaxDataBytes bounds the encoded custom event data object.
	MaxDataBytes = 16 << 10
)

Variables ¶

This section is empty.

Functions ¶

func ValidateEvent ¶

func ValidateEvent(event Event) error

ValidateEvent validates an envelope received from an isolated worker.

Types ¶

type Custom ¶

type Custom struct {
	Data map[string]any `json:"data"`
	Name string         `json:"name"`
}

Custom is a named, structured progress observation.

type Emitter ¶

type Emitter struct {
	// contains filtered or unexported fields
}

Emitter owns validation, transition state, and sequence allocation for one evaluation.

func New ¶

func New(sink Sink) *Emitter

New returns an evaluation-scoped progress emitter. A nil sink validates and tracks state while discarding delivery.

func (*Emitter) Event ¶

func (emitter *Emitter) Event(ctx context.Context, name string, data map[string]any) error

Event validates and emits a custom structured observation.

func (*Emitter) Item ¶

func (emitter *Emitter) Item(ctx context.Context, identifier, phaseID, title, state string) error

Item validates and emits an item snapshot.

func (*Emitter) Log ¶

func (emitter *Emitter) Log(ctx context.Context, level, message string) error

Log validates and emits a diagnostic message.

func (*Emitter) Phase ¶

func (emitter *Emitter) Phase(ctx context.Context, identifier, title, state string) error

Phase validates and emits a phase snapshot.

type Event ¶

type Event struct {
	Phase    *Phase  `json:"phase,omitempty"`
	Item     *Item   `json:"item,omitempty"`
	Custom   *Custom `json:"event,omitempty"`
	Log      *Log    `json:"log,omitempty"`
	Kind     Kind    `json:"kind"`
	Version  int     `json:"version"`
	Sequence uint64  `json:"sequence"`
}

Event is the versioned, ordered progress envelope. Exactly one typed body is set.

type Item ¶

type Item struct {
	ID      string `json:"id"`
	PhaseID string `json:"phase_id,omitempty"`
	Title   string `json:"title"`
	State   State  `json:"state"`
}

Item is an item snapshot. PhaseID may be empty when no phase was declared.

type Kind ¶

type Kind string

Kind identifies the typed body carried by an Event.

const (
	KindPhase Kind = "phase"
	KindItem  Kind = "item"
	KindEvent Kind = "event"
	KindLog   Kind = "log"
)

Progress event kinds.

type Log ¶

type Log struct {
	Level   string `json:"level"`
	Message string `json:"message"`
}

Log is a bounded diagnostic progress message.

type Phase ¶

type Phase struct {
	ID    string `json:"id"`
	Title string `json:"title"`
	State State  `json:"state"`
}

Phase is a phase snapshot. A phase groups progress and has no scheduling semantics.

type Sink ¶

type Sink func(context.Context, Event) error

Sink receives accepted events synchronously in sequence order.

type State ¶

type State string

State is phase/item presentation state.

const (
	StatePending   State = "pending"
	StateRunning   State = "running"
	StateSucceeded State = "succeeded"
	StateFailed    State = "failed"
	StateCanceled  State = "canceled"
)

Phase and item states.

Source Files ¶

View all Source files

progress.go

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