runtimeorchestration

package
v0.0.0-...-804b954 Latest Latest
Warning

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

Go to latest
Published: Aug 13, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package runtimeorchestration contains the private Temporal composition for state-backed Session work. It is intentionally unreachable from the public runtime API and SDK packages.

Package runtimeorchestration contains the private, replay-safe Temporal adapter for durable Session work.

Index

Constants

View Source
const (
	// SessionCommandSignal is the private signal name for one already-durable state command.
	SessionCommandSignal = "runtime.session.command.v1"
	// DispatchStateCommandActivity is the registered activity name that reaches the state-backed dispatcher.
	DispatchStateCommandActivity = "runtime.dispatch-state-command.v1"
)

Variables

View Source
var (
	// ErrUncertainExternalEffect stops automatic retry when a future activity
	// cannot prove whether an irreversible effect happened. It must reconcile
	// from durable operation state instead of blindly executing again.
	ErrUncertainExternalEffect = errors.New("runtime external effect is uncertain")
	// ErrIncompatiblePersistedPolicy stops retry when durable policy state can
	// no longer be interpreted by the active worker version.
	ErrIncompatiblePersistedPolicy = errors.New("runtime persisted policy is incompatible")
)

Functions

func Register

func Register(registrar workflowRegistry, activities *Activities) error

Register binds the complete private workflow/activity set to a runtime-owned worker.

func Run

func Run(ctx context.Context, config ProcessConfig) error

Run starts the codec-enabled worker and drains only durable state/outbox routes until cancellation. It owns and closes every private client.

func RunWithWait

func RunWithWait(ctx context.Context, config ProcessConfig, wait Wait) error

RunWithWait is Run with an injected private scheduling seam.

func SessionWorkflow

func SessionWorkflow(ctx workflow.Context, input WorkflowInput) error

SessionWorkflow serially dispatches already-durable command routes and rolls over with compact state.

Types

type Activities

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

Activities carries the injected state-backed dispatch authority outside workflow replay.

func NewActivities

func NewActivities(dispatcher StateDispatcher) (*Activities, error)

NewActivities constructs one activity set from the required state-backed dispatcher.

func (*Activities) DispatchStateCommand

func (activities *Activities) DispatchStateCommand(ctx context.Context, command Command) error

DispatchStateCommand delivers one already-durable command to the state-backed dispatcher.

type AuditExporter

type AuditExporter interface {
	Export(context.Context, runtimestate.AuditFactRecord) error
}

AuditExporter delivers one already-committed redacted audit fact. It has no authority to create or alter runtime state; publisher acknowledgement is the durable record of a successful delivery attempt.

type Command

type Command struct {
	Tenant    string
	OutboxID  string
	SessionID string
	Kind      CommandKind
	Sequence  uint64
}

Command carries only public runtime IDs and ordered durable metadata; never content or backend handles.

type CommandKind

type CommandKind string

CommandKind is the closed private workflow command vocabulary.

const (
	// CommandInputAccepted represents an already persisted input-admission outbox route.
	CommandInputAccepted CommandKind = "input_accepted"
	// CommandTurnCancelled represents an already persisted cancellation route.
	CommandTurnCancelled CommandKind = "turn_cancelled"
	// CommandTurnSucceeded represents an already persisted terminal operation route.
	CommandTurnSucceeded CommandKind = "turn_succeeded"
	// CommandTurnFailed represents an already persisted failed terminal operation route.
	CommandTurnFailed CommandKind = "turn_failed"
	// CommandApprovalResolved represents an already persisted terminal approval route.
	CommandApprovalResolved CommandKind = "approval_resolved"
	// CommandApprovalExpired represents an already persisted approval-expiry route.
	CommandApprovalExpired CommandKind = "approval_expired"
	// CommandApprovalCancelled represents an already persisted approval-cancellation route.
	CommandApprovalCancelled CommandKind = "approval_cancelled"
	// CommandSandboxOperationFinalized represents an already persisted sandbox finalization route.
	CommandSandboxOperationFinalized CommandKind = "sandbox_operation_finalized"
	// CommandSessionClosing reports that durable state stopped accepting Inputs
	// while work already admitted is allowed to drain.
	CommandSessionClosing CommandKind = "session_closing"
	// CommandSessionCompleted finalizes a drained Session workflow chain.
	CommandSessionCompleted CommandKind = "session_completed"
	// CommandSessionCancelled finalizes an explicitly cancelled Session workflow chain.
	CommandSessionCancelled CommandKind = "session_cancelled"
	// CommandSessionFailed finalizes a runtime-failed Session workflow chain.
	CommandSessionFailed CommandKind = "session_failed"
)

type DurableStateDispatcher

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

DurableStateDispatcher rechecks the state-owned outbox route before an activity may act on a Temporal signal. A Temporal credential by itself therefore cannot manufacture runtime work: the command must name a durable outbox record with the matching tenant, Session, and event route.

func NewDurableStateDispatcher

func NewDurableStateDispatcher(store runtimestate.RuntimeStateStore) (*DurableStateDispatcher, error)

NewDurableStateDispatcher creates the state-only activity authority. It has no runtime-content reader and no public API credential.

func NewDurableStateDispatcherWithInvocationScheduler

func NewDurableStateDispatcherWithInvocationScheduler(store runtimestate.AtomicTransitionStore, compiler *runtimestate.Compiler, planner *runtimestate.RuntimeStatePlanner, observe func(InvocationSchedule)) (*DurableStateDispatcher, error)

NewDurableStateDispatcherWithInvocationScheduler composes the private public-input-to-model-intent scheduler. It retains the exact durable outbox route check and has no public API or content-read authority.

func (*DurableStateDispatcher) Dispatch

func (dispatcher *DurableStateDispatcher) Dispatch(ctx context.Context, command Command) error

Dispatch confirms the publisher-selected outbox route remains durable.

type HTTPAuditExporter

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

HTTPAuditExporter sends committed audit facts to one explicit HTTP(S) sink. A non-success response is returned to the outbox publisher for lease-based at-least-once recovery; it is never treated as a committed export.

func NewHTTPAuditExporter

func NewHTTPAuditExporter(endpoint string, client *http.Client) (*HTTPAuditExporter, error)

NewHTTPAuditExporter constructs an explicit audit-delivery adapter.

func (*HTTPAuditExporter) Export

func (exporter *HTTPAuditExporter) Export(ctx context.Context, fact runtimestate.AuditFactRecord) (err error)

Export posts exactly one bounded redacted audit fact to the configured sink.

type InvocationSchedule

type InvocationSchedule struct {
	Tenant      string
	SessionID   string
	TurnID      string
	OperationID runtimestate.OperationID
}

InvocationSchedule identifies one committed input-owned invocation intent.

type ProcessConfig

type ProcessConfig struct {
	DatabaseDSN         string
	TemporalEndpoint    string
	TemporalToken       string
	Namespace           string
	TaskQueue           string
	PayloadBlobEndpoint string
	PayloadBlobBucket   string
	PayloadBlobPrefix   string
	PayloadAccessKey    string
	PayloadSecretKey    string
	// AuditSinkEndpoint enables optional delivery of already-committed audit
	// facts. It must be an explicit HTTPS endpoint; the worker never treats it
	// as a fail-closed state mutation boundary.
	AuditSinkEndpoint string
	AuditSinkTimeout  time.Duration
	// InvocationScheduled observes a committed model invocation intent. It is
	// an optional local process observer; it has no authority to alter durable
	// dispatch and must return promptly.
	InvocationScheduled func(InvocationSchedule)
}

ProcessConfig contains explicit private-role configuration. It has no public identity, bearer token, or runtime-content object-store fields.

type Publisher

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

Publisher claims durable outbox records, performs the private Temporal operation, and records an acknowledgement only after that operation returns. A lease can be reclaimed after expiry, making the boundary at-least-once.

func NewPublisher

func NewPublisher(config PublisherConfig) (*Publisher, error)

NewPublisher constructs the only state/outbox-to-Temporal scheduler seam.

func (*Publisher) ScanOnce

func (publisher *Publisher) ScanOnce(ctx context.Context) error

ScanOnce drains currently visible durable work. It intentionally has no callback for arbitrary requests: every operation originates in a committed outbox record and is claimed through compiler/planner/CAS first.

type PublisherConfig

type PublisherConfig struct {
	Store     runtimestate.RuntimeStateStore
	Tenants   runtimestate.OutboxTenantSource
	Compiler  *runtimestate.Compiler
	Planner   *runtimestate.RuntimeStatePlanner
	Clock     clock.Clock
	Publisher SessionWorkflowPublisher
	// AuditExporter is optional because the base runtime does not claim a
	// mandatory external audit sink. When configured, its delivery is fenced by
	// the exact committed audit fact and the same outbox lease as the route.
	AuditExporter AuditExporter
	Claimer       string
}

PublisherConfig confines an outbox scheduler to finite state work and one task queue publisher identity.

type SessionStart

type SessionStart struct {
	Tenant    string
	SessionID string
}

SessionStart is the deterministic private workflow identity for one durable Session partition.

func (SessionStart) String

func (start SessionStart) String() string

type SessionWorkflowPublisher

type SessionWorkflowPublisher interface {
	StartSession(context.Context, SessionStart) error
	SignalSession(context.Context, SessionStart, Command) error
}

SessionWorkflowPublisher is the private Temporal publication port. It receives only metadata from the outbox scheduler, never public credentials or runtime-content handles.

type StateDispatcher

type StateDispatcher interface {
	Dispatch(context.Context, Command) error
}

StateDispatcher is the private activity port to the state-backed runtime authority.

type Wait

type Wait func(context.Context, time.Duration) error

Wait is the private scheduling seam used between durable outbox scans. Production waits for the supplied interval; tests can deterministically advance the worker without real-time sleeps.

type WorkflowInput

type WorkflowInput struct {
	SessionID     string
	NextSequence  uint64
	Dispatched    uint32
	ContinueAfter uint32
}

WorkflowInput is the compact replay-safe continuation state for one Session workflow chain.

Jump to

Keyboard shortcuts

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