goal

package
v0.3.0-beta.2 Latest Latest
Warning

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

Go to latest
Published: Jul 29, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package goal defines the durable convergence contracts implemented by the Loop store.

Index

Constants

View Source
const (
	// MaxReportEvidenceBytes is the maximum inline evidence accepted by goal_report.
	MaxReportEvidenceBytes = 16 * 1024
)

Variables

View Source
var (
	// ErrCheckpointNotFound reports a missing workspace-owned checkpoint.
	ErrCheckpointNotFound = errors.New("loop goal: checkpoint not found")
	// ErrTurnNotFound reports a missing workspace-owned turn.
	ErrTurnNotFound = errors.New("loop goal: turn not found")
	// ErrBindingNotFound reports a missing workspace-owned binding attempt.
	ErrBindingNotFound = errors.New("loop goal: binding not found")
	// ErrOutboxEventNotFound reports an unknown session projection event.
	ErrOutboxEventNotFound = errors.New("loop goal: outbox event not found")
)

Functions

This section is empty.

Types

type ActivateBindingRequest

type ActivateBindingRequest struct {
	Key                  BindingKey
	CheckpointKey        *TurnKey
	ExpectedBindingEpoch int64
	ExpectedControlEpoch int64
	GrantID              int64
	ActivatedAt          time.Time
}

ActivateBindingRequest atomically swaps one creating run-owned attempt into active state.

type AdvanceBindingCreationFailureRequest

type AdvanceBindingCreationFailureRequest struct {
	Key                            BindingKey
	CheckpointKey                  TurnKey
	ExpectedControlEpoch           int64
	ExpectedCheckpointPhase        string
	ExpectedTaskRunID              string
	ExpectedQueueEntryID           string
	ExpectedPromptID               string
	ExpectedCheckpointBindingEpoch int64
	ExpectedCheckpointSessionID    string
	ExpectedCheckpointHandle       string
	ExpectedPromptAttempt          int
	ExpectedBindingEpoch           int64
	ExpectedBindingAttemptID       string
	ExpectedBindingSessionID       string
	ExpectedBindingProfileRef      string
	ExpectedBindingPolicyDigest    string
	ExpectedBindingCreationDigest  string
	FailureCode                    string
	FailedAt                       time.Time
	PrepareSuccessor               bool
	SuccessorBindingEpoch          int64
	SuccessorBindingAttemptID      string
	SuccessorSessionID             string
	CreationProfileRef             string
	PolicySpecDigest               string
	SuccessorCreationDigest        string
	SuccessorCreatedAt             time.Time
}

AdvanceBindingCreationFailureRequest atomically consumes one Goal-owned creation attempt.

type AmbiguousRequest

type AmbiguousRequest struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	TaskRunID            string
	QueueEntryID         string
	PromptID             string
	Cause                loop.ReasonCode
}

AmbiguousRequest finalizes an already-started effect without allocating a successor.

type BeginCompactionCancelRequest

type BeginCompactionCancelRequest struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	TaskRunID            string
	QueueEntryID         string
	PromptID             string
	Cause                string
}

BeginCompactionCancelRequest records one correlated cancel intent.

type BeginJudgeAttemptRequest

type BeginJudgeAttemptRequest struct {
	AttemptID            string
	Key                  TurnKey
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	TaskRunID            string
	PromptID             string
	Turn                 int
	JudgeDigest          string
	UsageBaseTokens      int64
	BudgetDecision       BudgetDecision
}

BeginJudgeAttemptRequest records evaluator intent under Goal CAS.

type BindingKey

type BindingKey struct {
	WorkspaceID loop.WorkspaceID
	LoopRunID   loop.RunID
	Handle      string
}

BindingKey identifies one run-local continuous handle.

func (BindingKey) Validate

func (k BindingKey) Validate() error

Validate enforces workspace-safe binding identity.

type BindingOwnership

type BindingOwnership string

BindingOwnership determines whether terminal cleanup may stop the bound session.

const (
	BindingOwnershipOriginBorrowed BindingOwnership = "origin-borrowed"
	BindingOwnershipRunOwned       BindingOwnership = "run-owned"
)

type BindingState

type BindingState string

BindingState is the append-only binding-attempt lifecycle.

const (
	BindingStateCreating BindingState = "creating"
	BindingStateActive   BindingState = "active"
	BindingStateFailed   BindingState = "failed"
	BindingStateClosed   BindingState = "closed"
	BindingStateReseeded BindingState = "reseeded"
)

type BindingStore

type BindingStore interface {
	GetOrCreateSessionBinding(context.Context, GetOrCreateBindingRequest) (SessionBinding, error)
	PrepareSessionBindingAttempt(context.Context, PrepareBindingAttemptRequest) (SessionBinding, error)
	AdvanceBindingCreationFailure(context.Context, AdvanceBindingCreationFailureRequest) error
	SettleStoppedSessionBindingCreation(context.Context, SettleStoppedBindingCreationRequest) (bool, error)
	FinalizeSessionBindingCreation(context.Context, ActivateBindingRequest) (SessionBinding, bool, error)
	ActivateSessionBinding(context.Context, ActivateBindingRequest) (SessionBinding, error)
	CloseSessionBinding(context.Context, CloseBindingRequest) error
	GetActiveSessionBinding(context.Context, BindingKey) (SessionBinding, error)
	GetSessionBindingAttempt(context.Context, BindingKey, int64) (SessionBinding, error)
}

BindingStore owns continuous-session binding CAS and audit history.

type BudgetBoundary

type BudgetBoundary string

BudgetBoundary identifies one synchronous nested-budget fence.

const (
	BudgetBeforeWork    BudgetBoundary = "before_work"
	BudgetAfterWork     BudgetBoundary = "after_work"
	BudgetBeforeCompact BudgetBoundary = "before_compact"
	BudgetAfterCompact  BudgetBoundary = "after_compact"
	BudgetBeforeJudge   BudgetBoundary = "before_judge"
	BudgetAfterJudge    BudgetBoundary = "after_judge"
)

type BudgetBoundarySnapshot

type BudgetBoundarySnapshot struct {
	Key                  TurnKey
	TaskRunID            string
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	ExpectedPhase        string
	ExpectedQueueEntryID string
	ExpectedPromptID     string
	Boundary             BudgetBoundary
	Phase                string
	Turn                 int64
	OperationID          string
	OperationBaseTokens  int64
	LiveTokensUsed       int64
	TokensReported       bool
}

BudgetBoundarySnapshot carries cumulative task usage at one effect boundary.

type BudgetDecision

type BudgetDecision struct {
	Allowed       bool
	Disposition   loop.ActionDisposition
	Cause         loop.ReasonCode
	BudgetVersion int64
	ValidUntil    time.Time
	GrantID       int64
	GrantTurn     int
	GrantScope    ControlGrantScope
}

BudgetDecision is the short-lived durable authorization presented at effect start.

type BudgetGuard

type BudgetGuard interface {
	FlushAndCheck(context.Context, BudgetBoundarySnapshot) (BudgetDecision, error)
}

BudgetGuard synchronously flushes usage and returns a short-lived durable decision.

type Checkpoint

type Checkpoint struct {
	Key                        TurnKey
	ControlEpoch               int64
	Phase                      string
	Status                     string
	ControlCause               loop.ReasonCode
	TurnsUsed                  int
	TurnLimit                  int
	BrokenStreak               int
	RecoveryStreak             int
	TaskRunID                  string
	QueueEntryID               string
	PromptID                   string
	PromptKind                 string
	PromptAttempt              int
	SessionID                  string
	BindingHandle              string
	BindingEpoch               int64
	ContextState               string
	UsageSequence              *int64
	UsagePendingAfterSequence  *int64
	CompactionBaselineUsed     *int64
	CompactionRecoveryRequired bool
	ControlGrant               *ControlGrant
	JudgeAttemptID             string
	ReportIntent               *ReportIntent
	CompactionCancel           *CompactionCancelIntent
	ControlActorKind           string
	ControlActorID             string
	ControlRequestedAt         *time.Time
	ContextNudgeRatio          float64
	UpdatedAt                  time.Time
}

Checkpoint is the mutable CAS state for one Goal node instance.

type CheckpointStore

type CheckpointStore interface {
	CreateCheckpoint(context.Context, CreateCheckpointRequest) (Checkpoint, error)
	LoadCheckpoint(context.Context, TurnKey) (Checkpoint, error)
	CheckpointControl(context.Context, ControlCheckpointRequest) error
	GrantAndReactivate(context.Context, GrantRequest) error
	RecordReportIntent(context.Context, RecordReportIntentRequest) (ReportIntent, error)
	BeginCompactionCancel(context.Context, BeginCompactionCancelRequest) error
	RecordContextUsage(context.Context, RecordContextUsageRequest) (Checkpoint, error)
}

CheckpointStore is the durable checkpoint/control subset used by Goal execution.

type ClaimPreparedCompactionRequest

type ClaimPreparedCompactionRequest struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	TaskRunID            string
	QueueEntryID         string
	PromptID             string
	SessionID            string
	BindingHandle        string
	BindingEpoch         int64
	UsageBaseTokens      int64
	UsageBaseReported    bool
	UsageSequence        *int64
	BudgetDecision       BudgetDecision
}

ClaimPreparedCompactionRequest atomically starts compaction without allocating a turn.

type ClaimPreparedWorkPromptRequest

type ClaimPreparedWorkPromptRequest struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	TaskRunID            string
	QueueEntryID         string
	PromptID             string
	SessionID            string
	BindingHandle        string
	BindingEpoch         int64
	UsageBaseTokens      int64
	UsageBaseReported    bool
	BudgetDecision       BudgetDecision
	ActorKind            string
	ActorID              string
}

ClaimPreparedWorkPromptRequest atomically starts one durable work turn.

type ClaimedPrompt

type ClaimedPrompt struct {
	Checkpoint    Checkpoint
	DispatchToken string
}

ClaimedPrompt returns the raw one-time token while retaining only its digest on disk.

type CloseBindingRequest

type CloseBindingRequest struct {
	Key                  BindingKey
	ExpectedBindingEpoch int64
	ClosedAt             time.Time
}

CloseBindingRequest closes one exact active binding without adopting another epoch.

type CompactionCancelIntent

type CompactionCancelIntent struct {
	PromptID    string
	Cause       string
	RequestedAt time.Time
}

CompactionCancelIntent persists the timeout cancellation decision before effect.

type CompactionOutcome

type CompactionOutcome string

CompactionOutcome is the operational outcome of one correlated compact prompt.

const (
	CompactionSucceeded   CompactionOutcome = "succeeded"
	CompactionIneffective CompactionOutcome = "ineffective"
	CompactionRefused     CompactionOutcome = "refused"
	CompactionCancelled   CompactionOutcome = "cancelled" //nolint:misspell // Persistence vocabulary is pinned.
	CompactionTimedOut    CompactionOutcome = "timed-out"
	CompactionFailed      CompactionOutcome = "failed"
)

type CompactionResult

type CompactionResult struct {
	PromptResult      loop.ActionPromptResult
	Outcome           CompactionOutcome
	UsageSequence     *int64
	UsageBaselineUsed *int64
}

CompactionResult carries the exact managed prompt terminal and freshness evidence.

type CompleteCompactionRequest

type CompleteCompactionRequest struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	TaskRunID            string
	QueueEntryID         string
	PromptID             string
	Result               CompactionResult
}

CompleteCompactionRequest settles one started compact operation.

type CompleteJudgeAttemptRequest

type CompleteJudgeAttemptRequest struct {
	AttemptID            string
	Key                  TurnKey
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	TaskRunID            string
	PromptID             string
	Verdict              gate.Verdict
	TokensUsed           int64
	TokensReported       bool
}

CompleteJudgeAttemptRequest records one typed evaluator terminal.

type CompleteTurnRequest

type CompleteTurnRequest struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	TaskRunID            string
	QueueEntryID         string
	PromptID             string
	Result               loop.ActionPromptResult
	Verdict              *gate.Verdict
	DispatchActorKind    string
	DispatchActorID      string
}

CompleteTurnRequest atomically finalizes the existing open turn and projection.

type ContextHealth

type ContextHealth interface {
	Usage(context.Context, loop.ActionSessionBinding) (ContextUsage, error)
	HasAdvertisedCommand(context.Context, loop.ActionSessionBinding, string) (bool, error)
}

ContextHealth reads context pressure and advertised session commands.

type ContextUsage

type ContextUsage struct {
	Used       int64
	Size       int64
	Sequence   int64
	Known      bool
	ReportedAt time.Time
}

ContextUsage is one sequenced provider context-usage observation.

type ControlCheckpointRequest

type ControlCheckpointRequest struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	ExpectedPhase        string
	TaskRunID            string
	QueueEntryID         string
	PromptID             string
	Disposition          loop.ActionDisposition
	Status               string
	Cause                loop.ReasonCode
	ActorKind            string
	ActorID              string
}

ControlCheckpointRequest writes one typed boundary under control CAS.

type ControlGrant

type ControlGrant struct {
	ID       int64
	Kind     ControlGrantKind
	Cause    loop.ReasonCode
	Turn     int
	Scope    ControlGrantScope
	Consumed bool
}

ControlGrant is the latest monotonic checkpoint-local approval identity.

type ControlGrantKind

type ControlGrantKind string

ControlGrantKind classifies one checkpoint-local approval.

const (
	ControlGrantTurnExtension ControlGrantKind = "turn-extension"
	ControlGrantBudget        ControlGrantKind = "budget"
	ControlGrantReseed        ControlGrantKind = "reseed"
	ControlGrantPlainResume   ControlGrantKind = "plain-resume"
)

type ControlGrantScope

type ControlGrantScope string

ControlGrantScope constrains the exact effect authorized by one approval.

const (
	ControlGrantScopeTurnLimit     ControlGrantScope = "turn-limit"
	ControlGrantScopeSettleCurrent ControlGrantScope = "settle-current"
	ControlGrantScopeWorkAndSettle ControlGrantScope = "work-and-settle"
	ControlGrantScopeRotateBinding ControlGrantScope = "rotate-binding"
	ControlGrantScopeReactivate    ControlGrantScope = "reactivate"
)

type CreateCheckpointRequest

type CreateCheckpointRequest struct {
	Checkpoint Checkpoint
}

CreateCheckpointRequest seeds one Goal checkpoint without overwriting existing state.

type Dependencies

type Dependencies struct {
	Store             ExecutorStore
	Binder            loop.ManagedActionSessionBinder
	Judge             JudgeEvaluator
	Budget            BudgetGuard
	Context           ContextHealth
	Recovery          PromptRecovery
	Now               func() time.Time
	CompactionTimeout time.Duration
	CompactionDrain   time.Duration
}

Dependencies contains the child-package ports supplied by daemon composition.

type DriverAttachmentRequest

type DriverAttachmentRequest struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	TaskRunID            string
	QueueEntryID         string
	PromptID             string
	SessionID            string
	BindingHandle        string
	DispatchToken        string
	DriverTurnID         string
	AttachedAt           time.Time
}

DriverAttachmentRequest proves the live driver attached to the exact started operation.

type EnqueueSessionOutboxRequest

type EnqueueSessionOutboxRequest struct {
	EventID         string
	WorkspaceID     loop.WorkspaceID
	OriginSessionID string
	LoopRunID       loop.RunID
	BoundSessionID  *string
	Cause           SessionOutboxCause
	CreatedAt       time.Time
}

EnqueueSessionOutboxRequest inserts one deterministic idempotency identity.

func (EnqueueSessionOutboxRequest) Validate

func (r EnqueueSessionOutboxRequest) Validate() error

Validate rejects incomplete or open-ended session projection identities.

type Executor

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

Executor advances one serialized Goal worker segment until its first control boundary.

func NewExecutor

func NewExecutor(deps Dependencies) (*Executor, error)

NewExecutor constructs the convergence engine from daemon-owned ports.

func (*Executor) Execute

Execute advances ordinary Goal turns serially until the first control boundary.

func (*Executor) Harvest

Harvest returns only a successfully settled Goal result.

type ExecutorStore

type ExecutorStore interface {
	TurnStore
	JudgeStore
}

ExecutorStore is the durable Goal state needed by the convergence worker.

type FencePreparedPromptRequest

type FencePreparedPromptRequest struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	TaskRunID            string
	QueueEntryID         string
	PromptID             string
	Outcome              loop.ActionPromptOutcome
	Disposition          loop.ActionDisposition
	Cause                loop.ReasonCode
	BudgetDecision       BudgetDecision
}

FencePreparedPromptRequest fences or terminalizes a prepared prompt without a work turn.

type FinalizePromptRequest

type FinalizePromptRequest struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	TaskRunID            string
	QueueEntryID         string
	PromptID             string
	SessionID            string
	BindingHandle        string
	DispatchToken        string
	Result               loop.ActionPromptResult
	TerminalAt           time.Time
}

FinalizePromptRequest writes exact queue terminal evidence under dispatch-token CAS.

type GetOrCreateBindingRequest

type GetOrCreateBindingRequest struct {
	Key                            BindingKey
	CheckpointKey                  TurnKey
	ExpectedControlEpoch           int64
	ExpectedCheckpointPhase        string
	ExpectedTaskRunID              string
	ExpectedQueueEntryID           string
	ExpectedPromptID               string
	ExpectedCheckpointBindingEpoch int64
	ExpectedCheckpointSessionID    string
	ExpectedCheckpointHandle       string
	BindingAttemptID               string
	SessionID                      string
	CreationProfileRef             string
	PolicySpecDigest               string
	CreationDigest                 string
	Ownership                      BindingOwnership
	CreatedAt                      time.Time
}

GetOrCreateBindingRequest atomically adopts a validated origin or returns its active epoch.

type GrantRequest

type GrantRequest struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	TurnIncrement        int
	Kind                 ControlGrantKind
	Cause                loop.ReasonCode
	Turn                 int
	Scope                ControlGrantScope
	ActorKind            string
	ActorID              string
}

GrantRequest atomically advances control and records a typed approval.

type JudgeAttempt

type JudgeAttempt struct {
	AttemptID       string
	Key             TurnKey
	Turn            int
	Status          string
	Outcome         string
	BlockingIssues  []gate.BlockingIssue
	EvidenceRef     string
	TokensUsed      int64
	TokensReported  bool
	UsageBaseTokens int64
	StartedAt       time.Time
	CompletedAt     *time.Time
}

JudgeAttempt is the durable persist-before-effect aggregate judge operation.

type JudgeEvaluator

type JudgeEvaluator interface {
	EvaluateGoal(context.Context, JudgeRequest) (JudgeResult, error)
}

JudgeEvaluator executes one complete Goal criteria bundle.

type JudgeRequest

type JudgeRequest struct {
	AttemptID string
	Key       TurnKey
	Turn      int
	Criteria  []dsl.GateCriterion
	Result    loop.ActionPromptResult
}

JudgeRequest carries the pinned criteria for one evaluator operation.

type JudgeResult

type JudgeResult struct {
	Verdict        gate.Verdict
	TokensUsed     int64
	TokensReported bool
}

JudgeResult carries the evaluator verdict and nullable-token truth.

type JudgeStore

type JudgeStore interface {
	BeginJudgeAttempt(context.Context, BeginJudgeAttemptRequest) (JudgeAttempt, error)
	CompleteJudgeAttempt(context.Context, CompleteJudgeAttemptRequest) (JudgeAttempt, error)
	MarkJudgeAmbiguous(context.Context, MarkJudgeAmbiguousRequest) error
	GetJudgeAttempt(context.Context, TurnKey, string) (JudgeAttempt, error)
}

JudgeStore persists aggregate judge attempts.

type MarkJudgeAmbiguousRequest

type MarkJudgeAmbiguousRequest struct {
	AttemptID            string
	Key                  TurnKey
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	TaskRunID            string
	PromptID             string
	Cause                string
}

MarkJudgeAmbiguousRequest terminalizes a running judge without re-execution.

type PrepareBindingAttemptRequest

type PrepareBindingAttemptRequest struct {
	Key                BindingKey
	BindingEpoch       int64
	BindingAttemptID   string
	SessionID          string
	CreationProfileRef string
	PolicySpecDigest   string
	CreationDigest     string
	CreatedAt          time.Time
}

PrepareBindingAttemptRequest persists a run-owned creating attempt before session creation.

type PreparePromptRequest

type PreparePromptRequest struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	TaskRunID            string
	QueueEntryID         string
	PromptID             string
	PromptKind           string
	PromptAttempt        int
	SessionID            string
	BindingHandle        string
	BindingEpoch         int64
	UsageBaseTokens      int64
	UsageBaseReported    bool
	ContextUsageSequence *int64
	ContextUsageUsed     *int64
	Message              string
	PreparedAt           time.Time
}

PreparePromptRequest inserts one non-dispatchable Goal-owned queue ticket idempotently.

type PreparedPromptRejectionStore

type PreparedPromptRejectionStore interface {
	RejectPreparedGoalPrompt(context.Context, RejectPreparedPromptRequest) error
}

PreparedPromptRejectionStore owns safe pre-submission retry advancement.

type PromptRecovery

type PromptRecovery interface {
	ReconcileTerminalFromEvents(
		context.Context,
		PromptRecoveryIdentity,
	) (loop.ActionPromptResult, bool, error)
}

PromptRecovery proves an exact terminal result from correlated session events.

type PromptRecoveryIdentity

type PromptRecoveryIdentity struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	QueueEntryID         string
	PromptID             string
	SessionID            string
}

PromptRecoveryIdentity is the complete persisted identity eligible for event reconciliation.

type PromptTerminalRecoveryStore

type PromptTerminalRecoveryStore interface {
	RecoverGoalPromptTerminal(context.Context, RecoverPromptTerminalRequest) error
}

PromptTerminalRecoveryStore owns the boot-only no-raw-token terminal CAS.

type PromptTicket

type PromptTicket struct {
	QueueEntryID string
	PromptID     string
}

PromptTicket identifies one prepared managed input.

type RecordContextUsageRequest

type RecordContextUsageRequest struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	ExpectedPhase        string
	SessionID            string
	BindingHandle        string
	Usage                ContextUsage
}

RecordContextUsageRequest advances freshness for one exact binding and checkpoint phase.

type RecordReportIntentRequest

type RecordReportIntentRequest struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	PromptID             string
	Status               string
	EvidenceRef          string
	ActorKind            string
	ActorID              string
}

RecordReportIntentRequest records one report under prompt/control/binding CAS.

type RecordToolReportRequest

type RecordToolReportRequest struct {
	Target    ToolReportTarget
	Status    string
	Evidence  string
	ActorKind string
	ActorID   string
}

RecordToolReportRequest records one prompt-bound report and its inline evidence atomically.

type RecoverPromptTerminalRequest

type RecoverPromptTerminalRequest struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	TaskRunID            string
	QueueEntryID         string
	PromptID             string
	SessionID            string
	BindingHandle        string
	Result               loop.ActionPromptResult
	TerminalAt           time.Time
}

RecoverPromptTerminalRequest commits terminal proof reconstructed from the exact session event range.

type RejectPreparedPromptRequest

type RejectPreparedPromptRequest struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	TaskRunID            string
	QueueEntryID         string
	PromptID             string
	ReasonCode           loop.ReasonCode
}

RejectPreparedPromptRequest terminalizes one effect-known-false attempt and advances its retry identity.

type ReportIntent

type ReportIntent struct {
	PromptID     string
	Status       string
	EvidenceRef  string
	BindingEpoch int64
	ActorKind    string
	ActorID      string
	RecordedAt   time.Time
}

ReportIntent is the durable one-prompt request written by goal_report.

type RevokePromptRequest

type RevokePromptRequest struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	TaskRunID            string
	QueueEntryID         string
	PromptID             string
	Disposition          loop.ActionDisposition
	Status               string
	Cause                loop.ReasonCode
	ActorKind            string
	ActorID              string
	ProjectionCause      SessionOutboxCause
	RevokedAt            time.Time
}

RevokePromptRequest atomically fences prepared work or terminalizes one claimed operation.

type SessionBinding

type SessionBinding struct {
	Key                BindingKey
	BindingEpoch       int64
	BindingAttemptID   string
	SessionID          string
	CreationProfileRef string
	PolicySpecDigest   string
	CreationDigest     string
	Ownership          BindingOwnership
	State              BindingState
	AdoptedGeneration  int
	AdoptionAttemptID  string
	FailureCode        string
	CreatedAt          time.Time
	ActivatedAt        *time.Time
	FailedAt           *time.Time
	ClosedAt           *time.Time
}

SessionBinding is one immutable binding attempt plus its lifecycle timestamps.

type SessionCleanupCause

type SessionCleanupCause string

SessionCleanupCause identifies the transaction that retired a run-owned session binding.

const (
	SessionCleanupCauseTerminal       SessionCleanupCause = "terminal"
	SessionCleanupCauseReseed         SessionCleanupCause = "reseed"
	SessionCleanupCauseControlRevoked SessionCleanupCause = "control-revoked"
	SessionCleanupCauseStop           SessionCleanupCause = "stop"
)

func (SessionCleanupCause) Valid

func (c SessionCleanupCause) Valid() bool

Valid reports whether the cleanup cause belongs to the closed persistence vocabulary.

type SessionCleanupObligation

type SessionCleanupObligation struct {
	ID           int64
	CleanupID    string
	WorkspaceID  loop.WorkspaceID
	LoopRunID    loop.RunID
	Handle       string
	BindingEpoch int64
	SessionID    string
	Cause        SessionCleanupCause
	CreatedAt    time.Time
	CompletedAt  *time.Time
}

SessionCleanupObligation is one durable, idempotently acknowledged session Stop effect.

func (SessionCleanupObligation) Validate

func (o SessionCleanupObligation) Validate() error

Validate enforces the complete run-owned cleanup identity.

type SessionCleanupStore

type SessionCleanupStore interface {
	ClaimGoalSessionCleanup(context.Context, int) ([]SessionCleanupObligation, error)
	AcknowledgeGoalSessionCleanup(context.Context, string, time.Time) error
}

SessionCleanupStore owns pending cleanup delivery and acknowledgement.

type SessionOutboxCause

type SessionOutboxCause string

SessionOutboxCause is the closed session-projection transition vocabulary.

const (
	SessionOutboxCauseStart   SessionOutboxCause = "start"
	SessionOutboxCauseReplace SessionOutboxCause = "replace"
	SessionOutboxCauseStatus  SessionOutboxCause = "status"
	SessionOutboxCauseClear   SessionOutboxCause = "clear"
	SessionOutboxCauseReseed  SessionOutboxCause = "reseed"
)

func (SessionOutboxCause) Valid

func (c SessionOutboxCause) Valid() bool

Valid reports whether the cause belongs to the closed projection vocabulary.

type SessionOutboxEvent

type SessionOutboxEvent struct {
	ID              int64
	EventID         string
	WorkspaceID     loop.WorkspaceID
	OriginSessionID string
	LoopRunID       loop.RunID
	BoundSessionID  *string
	Cause           SessionOutboxCause
	CreatedAt       time.Time
	DeliveredAt     *time.Time
}

SessionOutboxEvent is one restart-safe projection notification.

type SessionOutboxStore

type SessionOutboxStore interface {
	EnqueueGoalSessionOutbox(context.Context, EnqueueSessionOutboxRequest) (SessionOutboxEvent, error)
	ClaimGoalSessionOutbox(context.Context, int) ([]SessionOutboxEvent, error)
	AcknowledgeGoalSessionOutbox(context.Context, string, time.Time) error
}

SessionOutboxStore bridges committed global state into the per-session event store.

type SessionProjection

type SessionProjection struct {
	Found             bool
	Cleared           bool
	RunID             loop.RunID
	RunStatus         loop.Status
	DefinitionDigest  string
	OriginSessionID   string
	ContextNudgeRatio float64
	Checkpoint        *Checkpoint
	LastVerdict       *Turn
}

SessionProjection is the store-owned state needed to compose one canonical session Goal snapshot.

type SessionProjectionReader

type SessionProjectionReader interface {
	GetSessionGoalProjection(
		context.Context,
		loop.WorkspaceID,
		string,
	) (SessionProjection, error)
}

SessionProjectionReader loads the newest session-origin Goal before applying its clear tombstone.

type SettleStoppedBindingCreationRequest

type SettleStoppedBindingCreationRequest struct {
	Key                  BindingKey
	ExpectedBindingEpoch int64
	SessionID            string
}

SettleStoppedBindingCreationRequest closes the post-effect race for a binding stopped while creating.

type ToolReportTarget

type ToolReportTarget struct {
	Key                  TurnKey
	ExpectedControlEpoch int64
	ExpectedBindingEpoch int64
	PromptID             string
	OriginSessionID      string
	BoundSessionID       string
}

ToolReportTarget pins the only active prompt identity eligible for goal_report.

func (ToolReportTarget) Validate

func (t ToolReportTarget) Validate() error

Validate enforces a complete prompt/control/binding identity.

type ToolStore

type ToolStore interface {
	FindGoalReportTarget(
		context.Context,
		loop.WorkspaceID,
		string,
	) (ToolReportTarget, bool, error)
	ResolveActiveGoalOriginAlias(context.Context, loop.WorkspaceID, string) (string, bool, error)
	RecordGoalReport(context.Context, RecordToolReportRequest) (ReportIntent, error)
}

ToolStore is the durable Goal subset required by session-scoped native tools.

type Turn

type Turn struct {
	Key             TurnKey
	Seq             int64
	Turn            int
	SessionID       string
	BindingHandle   string
	BindingEpoch    int64
	PromptID        string
	PromptAttempt   int
	UsageBaseTokens int64
	ResultStatus    *string
	StopReason      *loop.ActionStopReason
	ReasonCode      *loop.ReasonCode
	VerdictOutcome  *gate.VerdictOutcome
	BlockingIssues  []gate.BlockingIssue
	EvidenceRef     *string
	PromptRef       *string
	TokensUsed      *int64
	ActorKind       string
	ActorID         string
	StartedAt       time.Time
	EndedAt         *time.Time
}

Turn is one immutable-start, single-terminal-transition Goal work audit row.

type TurnKey

type TurnKey struct {
	WorkspaceID loop.WorkspaceID
	LoopRunID   loop.RunID
	Generation  int
	NodeID      dsl.NodeID
	ItemIndex   int
}

TurnKey identifies one workspace-owned Goal node instance.

func (TurnKey) Validate

func (k TurnKey) Validate() error

Validate enforces the complete workspace-safe Goal identity.

type TurnPage

type TurnPage struct {
	Turns        []Turn
	NextAfterSeq *int64
}

TurnPage is the run-wide monotonic cursor page.

type TurnQuery

type TurnQuery struct {
	WorkspaceID loop.WorkspaceID
	LoopRunID   loop.RunID
	NodeID      dsl.NodeID
	ItemIndex   *int
	AfterSeq    int64
	Limit       int
}

TurnQuery filters run-wide sequence pagination without weakening workspace ownership.

func (TurnQuery) Validate

func (q TurnQuery) Validate() error

Validate rejects ambiguous cursors and invalid filter ranges.

type TurnReader

type TurnReader interface {
	ListGoalTurns(context.Context, TurnQuery) (TurnPage, error)
	GetGoalTurnByPromptID(context.Context, TurnKey, string) (Turn, error)
}

TurnReader loads immutable Goal audit history by run-wide sequence.

type TurnStore

TurnStore is the complete Goal prompt/checkpoint persistence contract.

Jump to

Keyboard shortcuts

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