lifecycle

type Deps ¶

type Deps struct {
	Values map[SharedDepKey]any
}

Deps is the dependency bundle delivered to [ModeRuntime.Start] by the registry. The Values map contains exactly the keys this runtime declared via [ModeRuntime.Requires], with values produced by the factories registered in SharedDepRegistry.

Helpers below provide typed access; ModeRuntime implementations should never reach into Values directly without a type assertion.

func (d Deps) Get(key SharedDepKey) (any, bool)

func (d Deps) MustGet(key SharedDepKey) any

type Diff ¶

type Diff struct {
	ToStart []ModeKey
	ToStop  []ModeKey
}

Diff describes the work Registry.Apply needs to do to reach a target state. ToStop is processed before ToStart so refcounted shared deps released by stopping a mode become available to a mode being started in the same transition.

func (d Diff) IsEmpty() bool

type ModeKey ¶

type ModeKey string

ModeKey identifies one of the three SpeechKit strict modes.

Hosts may extend the value space (e.g. for experimental modes) but the three canonical keys below are guaranteed to be recognised by the Device-Target and Server-Target adapter layers.

const (
	ModeDictation  ModeKey = "dictation"
	ModeAssist     ModeKey = "assist"
	ModeVoiceAgent ModeKey = "voiceagent"
)

type ModeRuntime ¶

type ModeRuntime interface {
	// Name returns the mode identity. The registry uses Name() to key
	// runtimes; duplicate registrations are rejected at Register time.
	Name() ModeKey

	// Start brings the runtime to Running. The deps map carries values
	// for every key returned by Requires(). Returns error if any
	// startup step fails; the registry treats this as a Failed
	// transition and releases any shared deps it acquired on the
	// runtime's behalf.
	Start(ctx context.Context, deps Deps) error

	// Stop tears the runtime down to Stopped. Idempotent. MUST drain
	// goroutines, close channels, and free any state derived from
	// borrowed deps before returning.
	Stop(ctx context.Context) error

	// Status returns the current lifecycle state. The registry treats
	// this as authoritative for diff computations and observability —
	// implementations must keep it consistent with actual goroutine /
	// resource ownership.
	Status() Status

	// Requires returns the SharedDepKeys this runtime needs as Deps
	// inputs. The slice is consumed at every Start; implementations
	// should return a stable copy or a pre-built constant.
	Requires() []SharedDepKey
}

ModeRuntime is the contract every SpeechKit mode implements so the Registry can orchestrate its lifecycle.

Implementations MUST:

• Be idempotent: Start on a Running runtime returns nil; Stop on a Stopped runtime returns nil.
• Terminate every goroutine they spawned before Stop returns.
• Treat the deps map as borrowed: don't retain references past Stop.
• Return the same Requires() list across the lifetime of the instance. The registry caches this set; mid-life changes are undefined behaviour.

The contract is verified by [TestRegistryLeak] in registry_leak_test.go.

type Registry ¶

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

Registry orchestrates mode runtimes and their shared dependencies.

Typical wiring:

sharedDeps := lifecycle.NewSharedDepRegistry()
sharedDeps.Register("audio.capture", audioFactory)
sharedDeps.Register("stt.router", sttFactory)
// ... etc

registry := lifecycle.NewRegistry(sharedDeps)
_ = registry.Register(dictationRuntime)
_ = registry.Register(assistRuntime)
_ = registry.Register(voiceAgentRuntime)

// At startup or when settings change:
if err := registry.Apply(ctx, lifecycle.Target{
    lifecycle.ModeDictation:  true,
    lifecycle.ModeAssist:     false,
    lifecycle.ModeVoiceAgent: false,
}); err != nil { ... }

Registry is safe for concurrent use; Apply calls serialise on an internal mutex so transitions never interleave.

func NewRegistry(sharedDeps *SharedDepRegistry) *Registry

func (r *Registry) Apply(ctx context.Context, target Target) error

func (r *Registry) Diff(target Target) Diff

func (r *Registry) Register(rt ModeRuntime) error

func (r *Registry) SetClock(clock func() time.Time)

func (r *Registry) Shutdown(ctx context.Context) error

func (r *Registry) Snapshot() SnapshotView

func (r *Registry) Subscribe(buffer int) (<-chan TransitionEvent, func())

type ReleaseFunc ¶

type ReleaseFunc func() error

ReleaseFunc is returned by SharedDepRegistry.Acquire; calling it decrements the refcount and triggers teardown when the count hits zero. ReleaseFunc is safe to call multiple times — second and subsequent calls are no-ops.

type SharedDepFactory ¶

type SharedDepFactory func(ctx context.Context) (value any, teardown func() error, err error)

SharedDepFactory produces a value plus a teardown callback the registry will invoke when the last holder releases the value.

The teardown MAY be nil for stateless values (e.g. a pre-built catalog struct). Non-nil teardown errors are surfaced to the releasing caller; the registry still drops the entry so a fresh Acquire rebuilds from scratch.

type SharedDepKey ¶

type SharedDepKey string

SharedDepKey identifies a refcounted shared dependency in SharedDepRegistry. Values are opaque strings — the lifecycle package does not interpret them. Hosts choose stable names that match their own module organisation (e.g. "audio.capture", "stt.router", "ai.genkit"). Two ModeRuntime implementations that declare the same key MUST be able to consume the same underlying value type.

type SharedDepRegistry ¶

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

SharedDepRegistry refcounts shared dependencies so multiple modes can share expensive state (Genkit runtime, STT router, audio capture) without duplicating it, and so a dep is released deterministically when no mode is using it any more.

Construction sequence:

1. NewSharedDepRegistry creates an empty registry.
2. Host calls [Register] for every key it expects modes to claim.
3. Mode runtimes call [Acquire] from their Start methods.
4. Each Acquire returns a ReleaseFunc the runtime stashes and invokes from its Stop method.

The registry is safe for concurrent use.

func NewSharedDepRegistry() *SharedDepRegistry

func (r *SharedDepRegistry) Acquire(ctx context.Context, key SharedDepKey) (any, ReleaseFunc, error)

func (r *SharedDepRegistry) Register(key SharedDepKey, factory SharedDepFactory)

func (r *SharedDepRegistry) Snapshot() []SharedDepStatus

type SharedDepStatus ¶

type SharedDepStatus struct {
	Key  SharedDepKey
	Refs int
}

SharedDepStatus is a read-only view of one entry for observability.

type SnapshotView ¶

type SnapshotView struct {
	Modes      map[ModeKey]Status
	SharedDeps []SharedDepStatus
}

Snapshot returns the current Status of every registered mode, plus the active shared-dep refcounts. Used by /readyz handlers and OTel metric collection.

type Status ¶

type Status string

Status is a mode runtime's observable lifecycle state.

const (
	// StatusStopped means the mode has never started, or has been cleanly
	// torn down. No goroutines, no live shared-dep references.
	StatusStopped Status = "stopped"

	// StatusStarting means a Start call is in flight but has not yet
	// returned. Shared deps are being acquired or the runtime is wiring up.
	StatusStarting Status = "starting"

	// StatusRunning means the mode is live and serving requests.
	StatusRunning Status = "running"

	// StatusStopping means a Stop call is in flight. The runtime is
	// draining and will release its shared deps once Stop returns.
	StatusStopping Status = "stopping"

	// StatusFailed means the last transition aborted with an error. The
	// runtime is back at rest from the registry's point of view; a fresh
	// Start may be attempted.
	StatusFailed Status = "failed"

	// StatusDisabled means an operator has explicitly turned the mode off
	// (e.g. config flag), distinct from Stopped (transient) — disabled
	// modes never auto-start and do not block readiness checks.
	// See internal/server/core/health.go for the analogous distinction
	// at the HTTP /readyz surface.
	StatusDisabled Status = "disabled"
)

func (s Status) IsActive() bool

func (s Status) IsTerminal() bool

func (s Status) Rank() int

Stopped  / Disabled → 0
Starting / Stopping → 1
Running             → 2 (not "worst" — Running is the goal)
Failed              → 3

func (s Status) String() string

type Target ¶

type Target map[ModeKey]bool

Target is the desired-state input to Registry.Apply. A mode whose key is true should be running; a mode whose key is false (or absent) should be stopped. Modes not registered with the registry are silently ignored — Target may safely include keys for modes the current host build does not ship.

type TransitionEvent ¶

type TransitionEvent struct {
	Mode      ModeKey
	From      Status
	To        Status
	Err       error // populated when To == StatusFailed
	Timestamp time.Time
}

TransitionEvent is published by Registry.Subscribe consumers. One event is emitted per status change.

Hosts wire the audit-log on top of this stream — see docs/compliance/audit-event-catalog.md "Mode lifecycle" for the canonical event-name mapping.