Documentation / guides
Runtime Services
Describe runtime services attached to a Rig.
Rig options wire services that the session runtime owns after construction.
They are composition seams, not mutable services exposed from Rig.
Foreign builders
func WithForeignBuilders(
foreign.Builder,
foreign.RestoredBuilder,
) Option
func WithForeignServicesBuilders(
foreign.ServicesBuilder,
foreign.ServicesRestoredBuilder,
) OptionThe legacy builder receives a bound loop, event publisher, ID generator, and
factory. The services-aware builder additionally receives a per-loop
foreign.Services value containing an opaque broker descriptor and narrow
delivery hook. Both live and restored callbacks are required. Nil callbacks or
duplicate options fail at Rig definition. A runtime profile selects the builder
through the parent-scoped loop runtime catalog; unknown profiles fail closed.
The Rig never serializes a foreign builder or broker capability. On restore it rebuilds the callback-owned runtime from the durable profile and bound definition.
Session resource storage
Process-service tools require a durable per-session resource location:
type SessionResourceStorage struct {
Path string
Identity string
}
type SessionResourceStorageProvider interface {
StorageForSession(context.Context, uuid.UUID) (SessionResourceStorage, error)
}
func WithSessionResourceStorage(SessionResourceStorageProvider) OptionThe provider must be safe for concurrent calls and return the same durable path
and identity for a session ID across restart. Rig stores the provider interface
but does not mutate its state. A nil or typed-nil provider returns
DefinitionInvalidResourceStorage; a process-services tool without one returns
DefinitionMissingResourceStorage.
Offload GC
type OffloadGCPolicy struct {
Interval time.Duration
Timeout time.Duration
}
func WithOffloadGC(policy OffloadGCPolicy) OptionBoth fields must be positive. This policy reaps orphaned session journal blobs
left after a blob-durable-before-pointer crash gap. It never collects workspace
snapshots. Invalid interval/timeout values return typed errors at Define.
Runtime catalog
WithRuntimeCatalog(loop.RuntimeCatalog) forwards one immutable parent-scoped
catalog to new and restored sessions. The catalog selects explicit gateway or
native tuples, or a harness-managed native entry; it is not a global registry.
Its digest is included in bound runtime identity and restore fingerprints.
%%{init: {"theme":"dark"}}%%
flowchart LR
R[Rig options] --> F[foreign builders]
R --> S[session resource provider]
R --> G[offload GC policy]
R --> C[runtime catalog]
F --> L[session lifecycle]
S --> L
G --> L
C --> L