terminalwork

type AppendIntentOutcome ¶

type AppendIntentOutcome struct {
	// Inserted is true only when this call definitively created the Intent row.
	Inserted bool
	// Replay is true only when an existing exact SameIntentReplay was confirmed.
	Replay bool
}

AppendIntentOutcome is the definitive result of a production AppendIntent attempt. Inserted and Replay are mutually exclusive; neither is set when the call returns an ambiguous transport/store error.

func (o AppendIntentOutcome) Definitive() bool

type BoundVersions ¶

type BoundVersions struct {
	GenerationID        string // executable-policy generation (persisted generation_id)
	RuntimeInstanceID   string // opaque process/manager incarnation
	RuntimeGenerationID string // request-plane runtime configuration generation
	ProviderID          string
	RatingID            string
}

BoundVersions records generation/provider/rating versions bound at admit.

Identity rules (task 3.6):

• GenerationID is the executable-policy / snapshotgen generation identity. The historical field name is retained for persisted rows, storage codecs, and SameIntentReplay determinism. Prefer ExecutableGenerationID().
• RuntimeInstanceID is the opaque runtimehost.Manager process incarnation.
• RuntimeGenerationID is the runtimehost request-plane generation identity (GenerationMeta.ID). Together with RuntimeInstanceID it forms durable runtime identity; numeric IDs alone are not restart-safe.
• These identities must never be conflated with each other or with model registry/catalog generations.

func (v BoundVersions) ExecutableGenerationID() string

func (v BoundVersions) HasRuntimeGeneration() bool

func (v BoundVersions) RuntimeIdentity() RuntimeIdentityClass

type BoundedError ¶

type BoundedError struct {
	Code      string
	Permanent bool
	Message   string
}

BoundedError is a content-safe work error classification.

type ClaimDueCommand ¶

type ClaimDueCommand struct {
	OwnerID    string
	TTL        time.Duration
	Limit      int
	Now        time.Time
	ProviderID string
	Kind       sdk.WorkKind
}

ClaimDueCommand selects and claims a bounded batch of due work.

type ClaimLease ¶

type ClaimLease struct {
	OwnerID   string
	ExpiresAt time.Time
}

ClaimLease coordinates workers, not users.

func (l ClaimLease) HeldAt(now time.Time) bool

type Clock ¶

type Clock interface {
	Now() time.Time
}

Clock is an injectable time source for retry/lease decisions.

type CompleteCommand ¶

type CompleteCommand struct {
	WorkID          string
	ExpectedOwnerID string
	Now             time.Time
}

CompleteCommand marks claimed work completed for the expected owner.

type LifecycleCorrelation ¶

type LifecycleCorrelation struct {
	RequestID string
	AttemptID string
	TraceID   string
}

LifecycleCorrelation ties work to safe request/attempt identities.

type ListPage ¶

type ListPage struct {
	Records []WorkRecord
	Cursor  string
}

ListPage is one bounded page of work records.

type ListQuery ¶

type ListQuery struct {
	WorkID        string
	SourceKey     SourceKey
	State         sdk.WorkState
	States        []sdk.WorkState
	ProviderID    string
	Kind          sdk.WorkKind
	RequestID     string
	AttemptID     string
	DueBefore     time.Time
	UpdatedAfter  time.Time
	UpdatedBefore time.Time
	Limit         int
	Cursor        string
}

ListQuery is a bounded operator filter for terminal-work rows (requirement 8.9, 12.6–12.7).

type PromotePendingCommand ¶

type PromotePendingCommand struct {
	WorkID string
	Now    time.Time
}

PromotePendingCommand moves intent rows to pending claim eligibility.

type QuarantineCommand ¶

type QuarantineCommand struct {
	WorkID string
	Err    BoundedError
	Now    time.Time
}

QuarantineCommand permanently parks malformed or non-retryable work.

type RenewClaimCommand ¶

type RenewClaimCommand struct {
	WorkID  string
	OwnerID string
	TTL     time.Duration
	Now     time.Time
}

RenewClaimCommand extends a held claim lease for the same owner.

type RetrySchedule ¶

type RetrySchedule struct {
	Initial    time.Duration
	Multiplier int
	Max        time.Duration
}

RetrySchedule computes deterministic backoff without jitter in the domain.

func (s RetrySchedule) Delay(attempt int) time.Duration

type RuntimeIdentityClass ¶

type RuntimeIdentityClass uint8

RuntimeIdentityClass classifies BoundVersions runtime identity material.

const (
	// RuntimeIdentityLegacy is both runtime instance and generation empty —
	// process-registry compatible rows from before task 3.6.
	RuntimeIdentityLegacy RuntimeIdentityClass = iota
	// RuntimeIdentityExact is both runtime instance and generation non-empty.
	RuntimeIdentityExact
	// RuntimeIdentityMalformed is only one of instance/generation populated.
	// It never falls back to legacy process-registry resolution.
	RuntimeIdentityMalformed
)

type ScheduleRetryCommand ¶

type ScheduleRetryCommand struct {
	WorkID          string
	ExpectedOwnerID string
	Schedule        RetrySchedule
	Err             BoundedError
	Now             time.Time
}

ScheduleRetryCommand schedules a non-permanent retry for claimed work.

type SourceKey ¶

type SourceKey struct {
	IdentityVersion int
	Key             string
}

SourceKey is a stable versioned work identity key (requirement 8.2).

func (k SourceKey) String() string

func (k SourceKey) Validate() error

type WorkItem ¶

type WorkItem struct {
	SourceKey   SourceKey
	WorkID      string
	Kind        sdk.WorkKind
	State       sdk.WorkState
	ProviderID  string
	Lifecycle   LifecycleCorrelation
	Versions    BoundVersions
	Attempts    int
	NextRetryAt time.Time
	Lease       ClaimLease
	Error       BoundedError
}

WorkItem is one independently idempotent terminal action.

func NewIntent(source SourceKey, workID string, kind sdk.WorkKind, providerID string, life LifecycleCorrelation, ver BoundVersions) (*WorkItem, error)

func (w *WorkItem) Claim(ownerID string, ttl time.Duration, clock Clock) error

func (w *WorkItem) Complete() error

func (w *WorkItem) MarkPending() error

func (w *WorkItem) Quarantine(err BoundedError) error

func (w *WorkItem) RenewClaim(ownerID string, ttl time.Duration, clock Clock) error

func (w *WorkItem) Retry(schedule RetrySchedule, clock Clock, err BoundedError) error

type WorkRecord ¶

type WorkRecord struct {
	WorkID         string
	SourceKey      SourceKey
	PayloadVersion int
	Kind           sdk.WorkKind
	State          sdk.WorkState
	ProviderID     string
	Lifecycle      LifecycleCorrelation
	Versions       BoundVersions
	Payload        []byte
	FactID         string
	LeaseSetID     string
	Attempts       int
	NextRetryAt    time.Time
	Lease          ClaimLease
	Error          BoundedError
	CreatedAt      time.Time
	UpdatedAt      time.Time
}

WorkRecord is the persisted terminal-work row (requirements 8.1–8.2, design D14).

func (r *WorkRecord) ApplyWorkItem(w *WorkItem, now time.Time)

func (r WorkRecord) ToWorkItem() *WorkItem

func (r WorkRecord) Validate() error