Documentation
¶
Overview ¶
Package terminal defines provider-neutral public contracts for single terminal ownership and durable terminal-work kinds/states.
These types are storage- and transport-agnostic. Request/attempt owner state machines live in internal/core/terminal; work-item lifecycle lives in internal/core/terminalwork. Enterprise and OSS adapters may depend on this package without importing internal/core.
Boundary rules:
- Must not import internal/*, database/sql, net/http, or provider SDKs.
- Enums use IsKnown/Validate for local strict construction; unknown wire values may be preserved by callers without mapping them to known constants.
Design rules D8, D9, D13: one terminal outcome per request/attempt; required effects complete or record durable intent; never retry after committed output.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalid indicates an unknown or malformed contract value. ErrInvalid = errors.New("terminal: invalid") // ErrInvalidTransition indicates a disallowed state-machine transition. ErrInvalidTransition = errors.New("terminal: invalid transition") // ErrConflict indicates a competing command lost the CAS claim and must // observe the winner outcome without re-running effects (requirement 7.3). ErrConflict = errors.New("terminal: conflict") // ErrOutputCommitted rejects retry/replacement after visible output // (requirement 7.5, design D13). ErrOutputCommitted = errors.New("terminal: output committed") // ErrScopeMismatch rejects a command that is not legal for the owner scope // (request-only vs attempt-only terminal commands). ErrScopeMismatch = errors.New("terminal: scope mismatch") // ErrClaimLeaseHeld indicates another worker still holds a valid claim lease. ErrClaimLeaseHeld = errors.New("terminal: claim lease held") // ErrNotDue indicates retry work is not yet eligible for claim. ErrNotDue = errors.New("terminal: not due") // ErrPermanent indicates a non-retryable work failure that must quarantine. ErrPermanent = errors.New("terminal: permanent") )
Sentinel errors for terminal and terminal-work domain contracts.
Functions ¶
This section is empty.
Types ¶
type Command ¶
type Command string
Command identifies a competing terminalization path (requirements 7.1, 13.4).
const ( CommandNormalFinish Command = "normal_finish" CommandPartialError Command = "partial_error" CommandCancel Command = "cancel" CommandClose Command = "close" CommandTimeout Command = "timeout" CommandGateReplacement Command = "gate_replacement" CommandParallelLoser Command = "parallel_loser" CommandFrontendEncoderFailure Command = "frontend_encoder_failure" CommandPreBackendDenial Command = "pre_backend_denial" CommandPanic Command = "panic" CommandEOF Command = "eof" CommandSwallowedAttempt Command = "swallowed_attempt" CommandBackendOpenFailure Command = "backend_open_failure" )
func AllCommands ¶
func AllCommands() []Command
AllCommands returns every documented terminal command in stable order.
func (Command) AllowedScopes ¶
AllowedScopes returns the terminal owner scopes that may claim with c.
Conservative mapping from design Single Terminal Ownership / D8:
- request-only: frontend encoder failure, completion-gate replacement
- attempt-only: parallel loser, swallowed attempt, pre-backend denial, backend-open failure
- both: normal finish, partial/error, cancel, close, timeout, panic, EOF
func (Command) AllowsScope ¶
AllowsScope reports whether c may compete on the given owner scope.
func (Command) IsRetryOrReplacement ¶
IsRetryOrReplacement reports whether c would retry or replace an in-flight stream after visible output may already be committed (design D13).
type OutcomeCode ¶
type OutcomeCode string
OutcomeCode classifies the published terminal result without carrying provider-specific wire shapes.
const ( OutcomeCodeSuccess OutcomeCode = "success" OutcomeCodePartial OutcomeCode = "partial" OutcomeCodeCancelled OutcomeCode = "cancelled" OutcomeCodeError OutcomeCode = "error" OutcomeCodeTimeout OutcomeCode = "timeout" OutcomeCodeReplaced OutcomeCode = "replaced" OutcomeCodeParallelLoser OutcomeCode = "parallel_loser" OutcomeCodeDenied OutcomeCode = "denied" OutcomeCodeEncoderFailure OutcomeCode = "encoder_failure" OutcomeCodePanic OutcomeCode = "panic" OutcomeCodeEOF OutcomeCode = "eof" OutcomeCodeSwallowed OutcomeCode = "swallowed" OutcomeCodeBackendOpen OutcomeCode = "backend_open_failure" OutcomeCodeFailed OutcomeCode = "failed" )
func OutcomeCodeFor ¶
func OutcomeCodeFor(cmd Command) OutcomeCode
OutcomeCodeFor maps a terminal command to its canonical outcome code.
func (OutcomeCode) IsKnown ¶
func (c OutcomeCode) IsKnown() bool
IsKnown reports whether c is a documented outcome code.
func (OutcomeCode) Validate ¶
func (c OutcomeCode) Validate() error
Validate returns an error when c is not a known outcome code.
type Scope ¶
type Scope string
Scope identifies whether a terminal owner covers a logical request or a backend attempt (design: per-attempt owners may finish before request owner).
type State ¶
type State string
State is a terminal-owner lifecycle state (requirement 7.4).
func AllStates ¶
func AllStates() []State
AllStates returns every documented terminal-owner state in stable order.
func (State) IsTerminal ¶
IsTerminal reports whether s is a finished owner state.
type WorkKind ¶
type WorkKind string
WorkKind identifies one independently idempotent terminal action (requirement 8.1).
const ( WorkKindAppendFact WorkKind = "append_fact" WorkKindSettleRequestProvider WorkKind = "settle_request_provider" WorkKindReleaseRequestProvider WorkKind = "release_request_provider" WorkKindSettleAttemptProvider WorkKind = "settle_attempt_provider" WorkKindReleaseAttemptProvider WorkKind = "release_attempt_provider" WorkKindCompensateProvider WorkKind = "compensate_provider" WorkKindReleaseLeaseSet WorkKind = "release_lease_set" WorkKindAuthoritativeCorrection WorkKind = "authoritative_correction" )
func AllWorkKinds ¶
func AllWorkKinds() []WorkKind
AllWorkKinds returns every documented work kind in stable order.
func (WorkKind) RequiresProvider ¶
RequiresProvider reports whether k is scoped to a stable provider ID.
type WorkState ¶
type WorkState string
WorkState is a durable terminal-work lifecycle state (requirement 8.2). Intent is the first durable record before pending claim eligibility.
func AllWorkStates ¶
func AllWorkStates() []WorkState
AllWorkStates returns every documented work state in stable order.
func (WorkState) IsTerminal ¶
IsTerminal reports whether s is a finished work state.
Source Files