agent

type AcquireLeaseCommand ¶

type AcquireLeaseCommand struct {
	ID     CommandID `json:"id"`
	Task   TaskRef   `json:"task"`
	Worker WorkerID  `json:"worker"`
}

type Agent ¶

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

Agent owns the durable HumanAgent domain store. It does not own an HTTP listener or worker transport; those are adapters over this lifecycle.

func New(ctx context.Context, config Config) (*Agent, error)

func Open(ctx context.Context, config Config) (*Agent, error)

func (agent *Agent) AcceptTask(ctx context.Context, command WorkerTaskCommand) (Task, error)

func (agent *Agent) AcquireLease(ctx context.Context, command AcquireLeaseCommand) (LeaseAssignment, error)

func (agent *Agent) CancelTask(ctx context.Context, command TaskCommand) (Task, error)

func (agent *Agent) ClaimLease(ctx context.Context, command ClaimLeaseCommand) (LeaseAssignment, error)

func (agent *Agent) Close() error

func (agent *Agent) CompleteTask(ctx context.Context, command CompleteTaskCommand) (Task, error)

func (agent *Agent) CreateTask(ctx context.Context, command CreateTaskCommand) (Task, error)

func (agent *Agent) Done() <-chan struct{}

func (agent *Agent) Err() error

func (agent *Agent) FailTask(ctx context.Context, command WorkerTaskCommand) (Task, error)

func (agent *Agent) FenceLease(ctx context.Context, command FenceLeaseCommand) error

func (agent *Agent) FreezeArtifact(ctx context.Context, command FreezeArtifactCommand) (FreezeArtifactResult, error)

func (agent *Agent) GetApplyReceipt(ctx context.Context, ref ArtifactRef) (ApplyReceipt, error)

func (agent *Agent) GetArtifact(ctx context.Context, ref ArtifactRef) (ArtifactContent, error)

func (agent *Agent) GetLease(ctx context.Context, ref TaskRef) (LeaseAssignment, error)

func (agent *Agent) GetMessage(ctx context.Context, authority AuthorityID, id MessageID) (Message, error)

func (agent *Agent) GetTask(ctx context.Context, ref TaskRef) (Task, error)

func (agent *Agent) GetWorkspaceHead(ctx context.Context, ref WorkspaceRef) (WorkspaceHead, error)

func (agent *Agent) ListAuthorityTasks(ctx context.Context, authority AuthorityID, request TaskQuery) (TaskQueryPage, error)

func (agent *Agent) ListLeases(
	ctx context.Context,
	authority AuthorityID,
	worker WorkerID,
	request LeasePageRequest,
) (LeasePage, error)

func (agent *Agent) ListMessages(ctx context.Context, ref TaskRef, request PageRequest) (MessagePage, error)

func (agent *Agent) ListTasks(ctx context.Context, contextRef ContextRef, request TaskPageRequest) (TaskPage, error)

func (agent *Agent) ReadEvents(ctx context.Context, ref TaskRef, request PageRequest) (EventPage, error)

func (agent *Agent) RecordApplyReceipt(ctx context.Context, command RecordApplyReceiptCommand) (ApplyReceipt, error)

func (agent *Agent) RejectTask(ctx context.Context, command WorkerTaskCommand) (Task, error)

func (agent *Agent) ReplyTask(ctx context.Context, command MessageCommand) (Task, error)

func (agent *Agent) RequestInput(ctx context.Context, command WorkerMessageCommand) (Task, error)

func (agent *Agent) ResolveTask(ctx context.Context, authority AuthorityID, id TaskID) (TaskRef, error)

func (agent *Agent) Shutdown(ctx context.Context) error

func (agent *Agent) SnapshotTask(ctx context.Context, ref TaskRef) (TaskSnapshot, error)

type AgentWorkerEndpoint ¶

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

AgentWorkerEndpoint is the official transport-neutral WorkerEndpoint. It borrows Agent: neither the endpoint nor any connection shuts the Agent down. One live session is allowed per authenticated authority/worker pair. A second session is rejected with ErrWorkerConnectionConflict instead of silently superseding the first and causing a reconnect fight.

func NewWorkerEndpoint(
	ctx context.Context,
	service *Agent,
	config WorkerEndpointConfig,
) (*AgentWorkerEndpoint, error)

func (endpoint *AgentWorkerEndpoint) OpenWorker(
	ctx context.Context,
	principal AuthenticatedWorker,
) (WorkerConnection, error)

type ApplyReceipt ¶

type ApplyReceipt struct {
	ID               ApplyReceiptID          `json:"id"`
	Artifact         ArtifactRef             `json:"artifact"`
	ArtifactDigest   workspace.Digest        `json:"artifact_digest"`
	BaseRevision     workspace.Revision      `json:"base_revision"`
	ResultRevision   workspace.Revision      `json:"result_revision"`
	Decision         workspace.ApplyDecision `json:"decision"`
	ObservedRevision workspace.Revision      `json:"observed_revision,omitempty"`
	Code             string                  `json:"code,omitempty"`
	Message          string                  `json:"message,omitempty"`
	RecordedAt       time.Time               `json:"recorded_at"`
}

type ApplyReceiptID ¶

type ApplyReceiptID string

type Artifact ¶

type Artifact struct {
	Ref            ArtifactRef        `json:"ref"`
	Task           TaskRef            `json:"task"`
	State          ArtifactState      `json:"state"`
	BaseRevision   workspace.Revision `json:"base_revision"`
	ResultRevision workspace.Revision `json:"result_revision"`
	Digest         workspace.Digest   `json:"digest"`
	PayloadDigest  workspace.Digest   `json:"payload_digest"`
	PayloadSize    int64              `json:"payload_size"`
	MediaType      string             `json:"media_type"`
	FrozenAt       time.Time          `json:"frozen_at"`
	PublishedAt    *time.Time         `json:"published_at,omitempty"`
	DiscardedAt    *time.Time         `json:"discarded_at,omitempty"`
}

Artifact is immutable workspace content plus its publication state. Payload bytes are returned separately so ordinary Task listing remains bounded.

type ArtifactContent ¶

type ArtifactContent struct {
	Artifact Artifact          `json:"artifact"`
	Payload  workspace.Payload `json:"payload"`
}

type ArtifactID ¶

type ArtifactID string

type ArtifactRef ¶

type ArtifactRef struct {
	Workspace WorkspaceRef `json:"workspace"`
	ID        ArtifactID   `json:"id"`
}

type ArtifactState ¶

type ArtifactState string

const (
	ArtifactFrozen    ArtifactState = "frozen"
	ArtifactPublished ArtifactState = "published"
	ArtifactDiscarded ArtifactState = "discarded"
)

type AuthenticatedWorker ¶

type AuthenticatedWorker struct {
	Authority AuthorityID     `json:"-"`
	Worker    WorkerID        `json:"-"`
	Session   WorkerSessionID `json:"-"`
}

AuthenticatedWorker is constructed by a transport after authentication. No inbound WorkerEventDelivery contains WorkerID; WorkerEndpoint binds every event to this principal when it constructs the durable LeaseGrant.

func (principal AuthenticatedWorker) Validate() error

type Author ¶

type Author string

const (
	AuthorCaller Author = "caller"
	AuthorAgent  Author = "agent"
)

type AuthorityID ¶

type AuthorityID string

type ClaimLeaseCommand ¶

type ClaimLeaseCommand struct {
	ID        CommandID   `json:"id"`
	Authority AuthorityID `json:"authority"`
	Worker    WorkerID    `json:"worker"`
}

ClaimLeaseCommand asks the durable dispatcher to select the oldest claimable Task within one authenticated authority. Authority and Worker must come from the authenticated transport principal, never an untrusted payload.

type CommandID ¶

type CommandID string

type CommandMeta ¶

type CommandMeta struct {
	ID               CommandID `json:"id"`
	ExpectedRevision uint64    `json:"expected_revision"`
}

CommandMeta supplies durable idempotency and optimistic concurrency. An exact retry of a committed command returns its original result snapshot even if the Task has advanced since then. Once committed, reusing ID with different input fails. A command rejected before commit does not reserve ID.

type CompleteTaskCommand ¶

type CompleteTaskCommand struct {
	Meta       WorkerCommandMeta `json:"meta"`
	Task       TaskRef           `json:"task"`
	Submission SubmissionID      `json:"submission"`
	Message    MessageInput      `json:"message"`
	Artifact   *ArtifactRef      `json:"artifact,omitempty"`
}

type Config ¶

type Config struct {
	// Store injects a complete Agent persistence consistency domain. Borrowed
	// resources remain caller-owned; owned resources are released by Shutdown.
	// It is not a distributed live-owner lease; see agent.Store's contract.
	Store framework.Resource[Store]
	// Protector optionally seals static message and Artifact payloads before they
	// enter Store callbacks. Borrowed Protectors remain caller-owned; owned
	// Protectors are released before the Store during Shutdown.
	Protector protect.Resource
	// AllowPlaintextReads is an explicit migration policy. With a configured
	// Protector the default rejects plain StoredValues, preventing a database
	// attacker from downgrading authenticated ciphertext to plaintext. Enable it
	// only while reading records written by a deliberately unprotected runtime.
	AllowPlaintextReads bool
	// MaxArtifactBytes limits newly frozen payloads. Reads continue to accept
	// already committed payloads up to the schema hard limit of 64 MiB.
	MaxArtifactBytes int64
	// Clock supplies core-owned timestamps. It must be safe for concurrent use
	// and return UTC-normalizable wall-clock values. Nil uses time.Now.
	Clock func() time.Time
	// ReleaseTimeout bounds each owned Protector and Store release independently.
	// Shutdown's context only bounds the caller's wait; cleanup continues after a
	// caller timeout and a broken adapter cannot prevent the next dependency's
	// release attempt.
	ReleaseTimeout time.Duration
}

Config controls one durable HumanAgent domain instance. Store is required and is the persistence extension point. Physical drivers such as agent/sqlite are composed by the caller and injected as borrowed or owned resources.

func DefaultConfig() Config

type ContextID ¶

type ContextID string

type ContextRef ¶

type ContextRef struct {
	Authority AuthorityID `json:"authority"`
	ID        ContextID   `json:"id"`
}

ContextRef is an authority-qualified display/conversation scope. Two Tasks in one Context are allowed to be active concurrently.

type CreateTaskCommand ¶

type CreateTaskCommand struct {
	Meta    CommandMeta  `json:"meta"`
	Task    TaskRef      `json:"task"`
	Context ContextRef   `json:"context"`
	Message MessageInput `json:"message"`
}

type Event ¶

type Event struct {
	Task       TaskRef      `json:"task"`
	Sequence   uint64       `json:"sequence"`
	Type       EventType    `json:"type"`
	State      TaskState    `json:"state"`
	Revision   uint64       `json:"revision"`
	Message    MessageID    `json:"message,omitempty"`
	Submission SubmissionID `json:"submission,omitempty"`
	Artifact   ArtifactID   `json:"artifact,omitempty"`
	OccurredAt time.Time    `json:"occurred_at"`
}

Event is an append-only status stream. Status/progress belongs here rather than in Message history, whose caller/agent turn alternation stays strict.

type EventPage ¶

type EventPage struct {
	Items   []Event `json:"items"`
	Next    uint64  `json:"next,omitempty"`
	HasMore bool    `json:"has_more"`
}

type EventType ¶

type EventType string

const (
	EventTaskSubmitted  EventType = "task_submitted"
	EventTaskAccepted   EventType = "task_accepted"
	EventTaskRejected   EventType = "task_rejected"
	EventInputRequired  EventType = "input_required"
	EventCallerReplied  EventType = "caller_replied"
	EventTaskCanceled   EventType = "task_canceled"
	EventTaskFailed     EventType = "task_failed"
	EventTaskCompleted  EventType = "task_completed"
	EventArtifactFrozen EventType = "artifact_frozen"
)

type FenceLeaseCommand ¶

type FenceLeaseCommand struct {
	ID    CommandID  `json:"id"`
	Grant LeaseGrant `json:"grant"`
}

type FreezeArtifactCommand ¶

type FreezeArtifactCommand struct {
	Meta                 WorkerCommandMeta  `json:"meta"`
	Task                 TaskRef            `json:"task"`
	Artifact             ArtifactID         `json:"artifact"`
	ExpectedBaseRevision workspace.Revision `json:"expected_base_revision"`
	Payload              workspace.Payload  `json:"payload"`
}

type FreezeArtifactResult ¶

type FreezeArtifactResult struct {
	Task     Task     `json:"task"`
	Artifact Artifact `json:"artifact"`
}

type LeaseAssignment ¶

type LeaseAssignment struct {
	Grant     LeaseGrant `json:"grant"`
	Task      Task       `json:"task"`
	GrantedAt time.Time  `json:"granted_at"`
}

LeaseAssignment is returned only after both the current grant and its immutable history row have committed. Dispatchers may therefore publish this value directly and can recover the same assignment after a process restart.

type LeaseFence ¶

type LeaseFence uint64

type LeaseGrant ¶

type LeaseGrant struct {
	Task   TaskRef    `json:"task"`
	Worker WorkerID   `json:"worker"`
	Fence  LeaseFence `json:"fence"`
}

LeaseGrant is the durable, fenced authority for one worker to mutate a Task. It deliberately has no wall-clock expiry: a dispatcher fences a disconnected worker explicitly, then acquires the next monotonically larger generation. Remote adapters must construct Worker from the authenticated principal, never from an untrusted request body.

type LeasePage ¶

type LeasePage struct {
	Items   []LeaseAssignment `json:"items"`
	Next    *LeasePageCursor  `json:"next,omitempty"`
	HasMore bool              `json:"has_more"`
}

type LeasePageCursor ¶

type LeasePageCursor struct {
	GrantedAt time.Time   `json:"granted_at"`
	Workspace WorkspaceID `json:"workspace"`
	Task      TaskID      `json:"task"`
	Fence     LeaseFence  `json:"fence"`
}

type LeasePageRequest ¶

type LeasePageRequest struct {
	After *LeasePageCursor `json:"after,omitempty"`
	Limit int              `json:"limit,omitempty"`
}

type Message ¶

type Message struct {
	ID        MessageID `json:"id"`
	Task      TaskRef   `json:"task"`
	Sequence  uint64    `json:"sequence"`
	Author    Author    `json:"author"`
	Parts     []Part    `json:"parts"`
	CreatedAt time.Time `json:"created_at"`
}

type MessageCommand ¶

type MessageCommand struct {
	Meta    CommandMeta  `json:"meta"`
	Task    TaskRef      `json:"task"`
	Message MessageInput `json:"message"`
}

type MessageID ¶

type MessageID string

type MessageInput ¶

type MessageInput struct {
	ID    MessageID `json:"id"`
	Parts []Part    `json:"parts"`
}

type MessagePage ¶

type MessagePage struct {
	Items   []Message `json:"items"`
	Next    uint64    `json:"next,omitempty"`
	HasMore bool      `json:"has_more"`
}

type PageRequest ¶

type PageRequest struct {
	After uint64 `json:"after,omitempty"`
	Limit int    `json:"limit,omitempty"`
}

PageRequest pages append-only Message and Event streams by sequence. Next is always the last returned sequence, or After when the page is empty, so a caller can use it as the next tail-poll cursor even when HasMore is false.

type Part ¶

type Part struct {
	MediaType string `json:"media_type"`
	Data      []byte `json:"data"`
}

Part is an ordered, transport-neutral content part. A2A, JSON, or another wire adapter must translate at the boundary instead of leaking its DTOs into this domain package.

type RecordApplyReceiptCommand ¶

type RecordApplyReceiptCommand struct {
	CommandID        CommandID               `json:"command_id"`
	Receipt          ApplyReceiptID          `json:"receipt"`
	Artifact         ArtifactRef             `json:"artifact"`
	ArtifactDigest   workspace.Digest        `json:"artifact_digest"`
	BaseRevision     workspace.Revision      `json:"base_revision"`
	ResultRevision   workspace.Revision      `json:"result_revision"`
	Decision         workspace.ApplyDecision `json:"decision"`
	ObservedRevision workspace.Revision      `json:"observed_revision,omitempty"`
	Code             string                  `json:"code,omitempty"`
	Message          string                  `json:"message,omitempty"`
}

type RevisionConflictError ¶

type RevisionConflictError struct {
	Expected uint64
	Actual   uint64
}

RevisionConflictError reports the exact failed CAS values.

func (failure *RevisionConflictError) Error() string

func (failure *RevisionConflictError) Unwrap() error

type Store ¶

type Store interface {
	// Description returns static, non-secret implementation metadata. It must be
	// safe before and during resource release and must not perform network or
	// storage I/O.
	Description() StoreDescription
	// View executes one callback against a stable, read-only snapshot. On a valid,
	// live invocation it calls the callback exactly once and returns an error
	// matching the callback's result. The context bounds snapshot acquisition and
	// every StoreView primitive.
	View(context.Context, func(StoreView) error) error
	// Update executes one callback in one atomic, strictly serializable transaction
	// with read-your-writes. On a valid, live invocation it calls the callback
	// exactly once. A callback error rolls back and remains matchable in the return;
	// a nil callback result enters the commit-ambiguity contract described above.
	// The context bounds transaction acquisition, every StoreTx primitive, and
	// commit, but cancellation never permits a partial commit.
	Update(context.Context, func(StoreTx) error) error
}

Store is the complete persistence consistency boundary for HumanAgent. Tasks, command receipts, messages, events, lease history, Artifacts, submissions, apply receipts, and Workspace heads deliberately share this one Store. Splitting them across independently committed implementations would invalidate the Agent state machine.

A non-nil context and callback are required. A nil argument is rejected with ErrInvalidArgument without invoking the callback; a context already done is returned without invoking it. Once admitted, View and Update call the callback exactly once. Implementations must never retry a callback: Agent callbacks can derive timestamps and return precise conflict information from the snapshot they observed. The enclosing context supplies every primitive's cancellation and deadline; an implementation must not replace it with a background context.

View supplies one stable read snapshot. Update supplies one atomic, strictly serializable read/write transaction with read-your-writes. A callback and its StoreView or StoreTx are valid only until the enclosing method returns and must not be retained or used concurrently. A primitive used outside that lifetime returns an error matching ErrStoreClosed and performs no work.

If an Update callback returns an error, none of its writes may become visible. View and Update return an error matching the callback error; a rollback failure may be joined without hiding it. If it returns nil, all writes, including the command receipt, become visible atomically or none do. A definite commit failure returns an ordinary error and guarantees no commit. A failure that may have committed must return an error matching ErrStoreCommitUnknown. An exact retry then observes either the whole command receipt and replays it, or no receipt and safely attempts the command.

Successful Update effects are durable across a process restart. View and Update must be safe for concurrent callers. Implementations own copies of all byte slices after a successful write and return caller-owned copies from all reads; mutable aliases may not cross a transaction boundary.

Store serializability is not a live-runtime lease. Unless the embedding host adds external generation/fencing coordination, exactly one active Agent may drive a Store correctness namespace. Two Agent instances can otherwise present the same durable Task to different Humans before either one commits.

Store intentionally has no Close method. Construction receives it through a framework.Resource[Store], which makes borrowed versus owned lifetime and the release callback explicit without contaminating this business port.

type StoreApplyReceiptRecord ¶

type StoreApplyReceiptRecord struct {
	Receipt ApplyReceipt
}

StoreApplyReceiptRecord is the caller-side terminal decision for one exact published Artifact.

type StoreArtifactMutation ¶

type StoreArtifactMutation struct {
	Ref           ArtifactRef
	Task          TaskRef
	ExpectedState ArtifactState
	NextState     ArtifactState
	PublishedAt   *time.Time
	DiscardedAt   *time.Time
}

StoreArtifactMutation changes only publication state and its associated terminal timestamp without materializing the immutable payload. Exactly one of PublishedAt or DiscardedAt is set according to NextState. Identity, payload, digests, revisions, media type, Task, and FrozenAt remain unchanged. A false result means the record is absent or ExpectedState or Task no longer matches.

type StoreArtifactRecord ¶

type StoreArtifactRecord struct {
	Artifact       Artifact
	EncodedPayload []byte
}

StoreArtifactRecord contains immutable plaintext payload identity, its mutable publication state, and a versioned opaque StoredValue. Artifact PayloadSize and PayloadDigest always describe canonical plaintext; EncodedPayload has an independent physical size and is preserved byte-for-byte. State transitions may not change EncodedPayload or any identity field.

type StoreCommandKey ¶

type StoreCommandKey struct {
	Authority AuthorityID
	ID        CommandID
}

StoreCommandKey is authority-qualified because command IDs are unique only inside an authenticated Authority.

type StoreCommandRecord ¶

type StoreCommandRecord struct {
	Authority    AuthorityID
	ID           CommandID
	Kind         string
	IntentDigest StoreDigest
	ResultKind   string
	Result       []byte
	ResultDigest StoreDigest
	CreatedAt    time.Time
}

StoreCommandRecord is the durable idempotency receipt for one Agent command. Result contains the exact canonical result bytes produced by Agent; the Store does not decode or re-encode them. The key is (Authority, ID).

type StoreCommitUnknownError ¶

type StoreCommitUnknownError struct {
	Cause error
}

StoreCommitUnknownError preserves an infrastructure cause while supporting errors.Is for both ErrStoreCommitUnknown and the cause. Cause may be nil.

func (failure *StoreCommitUnknownError) Error() string

func (failure *StoreCommitUnknownError) Unwrap() []error

type StoreConflictError ¶

type StoreConflictError struct {
	Constraint StoreConstraint
	Key        string
}

StoreConflictError reports a typed logical constraint collision and supports errors.Is(err, ErrStoreConflict).

func (failure *StoreConflictError) Error() string

func (*StoreConflictError) Unwrap() error

type StoreConstraint ¶

type StoreConstraint string

StoreConstraint identifies the logical uniqueness or immutability rule that rejected an insert. Store implementations must not expose vendor index names or parse error strings at the Agent boundary.

const (
	StoreConstraintCommandID       StoreConstraint = "command_id"
	StoreConstraintTaskKey         StoreConstraint = "task_key"
	StoreConstraintPublicTaskID    StoreConstraint = "public_task_id"
	StoreConstraintMessageID       StoreConstraint = "message_id"
	StoreConstraintMessageSequence StoreConstraint = "message_sequence"
	StoreConstraintEventSequence   StoreConstraint = "event_sequence"
	StoreConstraintLeaseFence      StoreConstraint = "lease_fence"
	StoreConstraintArtifactID      StoreConstraint = "artifact_id"
	StoreConstraintArtifactTask    StoreConstraint = "artifact_task"
	StoreConstraintSubmissionID    StoreConstraint = "submission_id"
	StoreConstraintReceiptID       StoreConstraint = "receipt_id"
)

type StoreDescription ¶

type StoreDescription struct {
	Contract framework.Contract
	Provider string
	Version  string
}

StoreDescription identifies an implementation without exposing its backing location. Provider should identify the driver (for example, "sqlite" or a Go module path); Version is the driver's own release version. Contract describes behavior, not the driver's schema version.

Description values are suitable for diagnostics and audit metadata. They must not contain database paths, network addresses with credentials, DSNs, tokens, key identifiers, or tenant data.

func (description StoreDescription) Validate() error

type StoreDigest ¶

type StoreDigest string

StoreDigest is an opaque digest emitted and verified by the Agent core. A Store must preserve it byte-for-byte and must not recalculate it with a driver-specific serialization.

type StoreEventRecord ¶

type StoreEventRecord struct {
	Event Event
}

StoreEventRecord is one append-only Task revision event.

type StoreEventScan ¶

type StoreEventScan struct {
	Task  TaskRef
	After uint64
	Limit int
}

StoreEventScan selects Task events with Sequence strictly greater than After in ascending order. Limit is an item cap in 1..MaxPageSize+1 and has no zero default at this port.

type StoreLeaseGrantRecord ¶

type StoreLeaseGrantRecord struct {
	Grant     LeaseGrant
	GrantedAt time.Time
}

StoreLeaseGrantRecord is immutable history for one monotonically increasing Task fence. Current lease state may be empty, but committed history is never deleted or rewritten.

type StoreLeaseScan ¶

type StoreLeaseScan struct {
	Authority AuthorityID
	Worker    WorkerID
	After     *LeasePageCursor
	Limit     int
}

StoreLeaseScan selects current (not historical) leases for one authenticated worker, ordered by GrantedAt, Workspace ID, Task ID, and Fence, all ascending. After is an exclusive lexicographic cursor in that order. Limit is an item cap in 1..MaxPageSize+1 and has no zero default at this port.

type StoreLeaseState ¶

type StoreLeaseState struct {
	Owner WorkerID
	Fence LeaseFence
}

StoreLeaseState is the mutable lease pointer embedded in a Task record. A zero Owner means unleased. Fence never decreases and identifies the latest immutable StoreLeaseGrantRecord even after that generation is fenced.

type StoreLimitError ¶

type StoreLimitError struct {
	Record StoreRecordKind
	Limit  int64
}

StoreLimitError describes a bounded read refusal and supports errors.Is(err, ErrStoreRecordTooLarge).

func (failure *StoreLimitError) Error() string

func (*StoreLimitError) Unwrap() error

type StoreMessageKey ¶

type StoreMessageKey struct {
	Authority AuthorityID
	ID        MessageID
}

StoreMessageKey is authority-qualified because message IDs are unique only inside an authenticated Authority.

type StoreMessageRecord ¶

type StoreMessageRecord struct {
	ID           MessageID
	Task         TaskRef
	Sequence     uint64
	Author       Author
	EncodedParts []byte
	PartsDigest  StoreDigest
	CreatedAt    time.Time
}

StoreMessageRecord keeps a versioned opaque StoredValue containing canonical encoded Parts and their plaintext digest alongside message metadata. Store implementations preserve EncodedParts byte-for-byte and never decrypt it.

type StoreMessageScan ¶

type StoreMessageScan struct {
	Task      TaskRef
	After     uint64
	Limit     int
	ReadLimit StoreReadLimit
}

StoreMessageScan selects Task messages with Sequence strictly greater than After in ascending order. Limit is an item cap in 1..MaxPageSize+1. ReadLimit is a hard aggregate EncodedParts budget. A Store fails with ErrStoreRecordTooLarge when the first record cannot fit; after at least one record fits it returns the largest ordered contiguous prefix within the budget. Agent compares the last sequence with Task.MessageCount to derive HasMore without a driver-specific continuation flag.

type StoreNotFoundError ¶

type StoreNotFoundError struct {
	Record StoreRecordKind
	Key    string
}

StoreNotFoundError adds a logical record kind and non-secret stable key to ErrStoreRecordNotFound. Implementations may return the sentinel directly when no safe key is available.

func (failure *StoreNotFoundError) Error() string

func (*StoreNotFoundError) Unwrap() error

type StoreReadLimit ¶

type StoreReadLimit struct {
	MaxBytes int64
}

StoreReadLimit is a hard materialization budget for one opaque record field. MaxBytes must be positive. A Store must reject a larger value before returning the blob, using an error matching ErrStoreRecordTooLarge. It must never treat a zero value as unlimited.

type StoreRecordKind ¶

type StoreRecordKind string

StoreRecordKind identifies a logical record without exposing a table or a document collection. Values are stable diagnostics and conformance labels.

const (
	StoreRecordCommand       StoreRecordKind = "command"
	StoreRecordTask          StoreRecordKind = "task"
	StoreRecordMessage       StoreRecordKind = "message"
	StoreRecordEvent         StoreRecordKind = "event"
	StoreRecordLeaseGrant    StoreRecordKind = "lease_grant"
	StoreRecordWorkspaceHead StoreRecordKind = "workspace_head"
	StoreRecordArtifact      StoreRecordKind = "artifact"
	StoreRecordSubmission    StoreRecordKind = "submission"
	StoreRecordApplyReceipt  StoreRecordKind = "apply_receipt"
)

type StoreSubmissionRecord ¶

type StoreSubmissionRecord struct {
	Submission Submission
}

StoreSubmissionRecord contains only durable identity, routing, and timestamp metadata. Final user content lives in its referenced protected Message and optional Artifact; Store implementations must not duplicate that payload here. It is written once, in the same transaction that publishes an optional Artifact and moves its Task to completed.

type StoreTaskAuthorityResult ¶

type StoreTaskAuthorityResult struct {
	Records   []StoreTaskRecord
	TotalSize uint64
}

StoreTaskAuthorityResult is the raw authority query result from one View.

type StoreTaskAuthorityScan ¶

type StoreTaskAuthorityScan struct {
	Authority        AuthorityID
	Context          ContextID
	State            TaskState
	UpdatedAtOrAfter *time.Time
	After            *TaskQueryCursor
	Limit            int
}

StoreTaskAuthorityScan selects a bounded authority-wide page ordered by UpdatedAt descending, then Workspace ID and Task ID ascending. Context and State zero values do not filter; UpdatedAtOrAfter is inclusive. After is an exclusive lexicographic cursor in the mixed direction above. Limit is the physical maximum, must be in 1..MaxPageSize+1, and has no zero default at the Store port. TotalSize counts the filtered set before applying After and must be observed in the same View snapshot as Records.

type StoreTaskCondition ¶

type StoreTaskCondition struct {
	ExpectedRevision uint64
	ExpectedLease    *StoreLeaseState
}

StoreTaskCondition is the compare-and-swap precondition for a Task mutation. ExpectedRevision is always matched. ExpectedLease nil ignores the lease (for caller-authorized transitions); a non-nil zero value requires an unleased Task, and a non-zero value requires that exact owner/fence generation.

type StoreTaskContextScan ¶

type StoreTaskContextScan struct {
	Context ContextRef
	After   *TaskPageCursor
	Limit   int
}

StoreTaskContextScan selects a bounded page ordered by CreatedAt ascending, then Workspace ID and Task ID ascending. After is an exclusive lexicographic cursor in that order. Limit is the physical maximum number of records returned and must be in 1..MaxPageSize+1; zero has no default meaning at the Store port. Agent normally requests one extra record to derive HasMore.

type StoreTaskMutation ¶

type StoreTaskMutation struct {
	Ref       TaskRef
	Condition StoreTaskCondition
	Next      StoreTaskRecord
}

StoreTaskMutation replaces one existing Task aggregate when Condition still matches. Ref and Next.Task.Ref must be identical; Context and CreatedAt are immutable, and every nested Task/Workspace reference must remain in the same identity scope. ExpectedRevision must be non-zero. A false result from CompareAndSwapTask means no field was changed.

type StoreTaskRecord ¶

type StoreTaskRecord struct {
	Task          Task
	Lease         StoreLeaseState
	ArtifactState *ArtifactState
}

StoreTaskRecord is the materialized Task aggregate plus its non-public current lease. ArtifactState is nil exactly when Task.Artifact is nil; Agent uses it to fail closed when an implementation returns a Task/Artifact state mismatch.

type StoreTx ¶

type StoreTx interface {
	StoreView
	// InsertCommand inserts the immutable (Authority, ID) receipt. Any collision
	// returns ErrStoreConflict with StoreConstraintCommandID.
	InsertCommand(StoreCommandRecord) error
	// InsertTask inserts an initial Task. It must be unleased at fence zero and
	// have no pre-bound Artifact, ArtifactState, or Submission. Task.Ref is unique;
	// (Authority, Task ID) is also unique across Workspaces. Collisions use
	// StoreConstraintTaskKey and StoreConstraintPublicTaskID respectively.
	InsertTask(StoreTaskRecord) error
	// CompareAndSwapTask replaces an existing Task when ExpectedRevision and, when
	// non-nil, ExpectedLease match. A revision/lease miss returns (false, nil); an
	// absent Task matches ErrStoreRecordNotFound. Invalid or changed identity is an
	// error. Artifact and Submission links in Next are backed by their paired
	// immutable inserts in the same Update, rather than created by this primitive.
	CompareAndSwapTask(StoreTaskMutation) (bool, error)
	// InsertMessage inserts an immutable message. (Authority, Message ID) and
	// (TaskRef, Sequence) are unique; collisions use StoreConstraintMessageID and
	// StoreConstraintMessageSequence respectively.
	InsertMessage(StoreMessageRecord) error
	// InsertEvent inserts an immutable event keyed by (TaskRef, Sequence). A
	// collision uses StoreConstraintEventSequence.
	InsertEvent(StoreEventRecord) error
	// InsertLeaseGrant inserts immutable history keyed by (TaskRef, Fence). A
	// collision uses StoreConstraintLeaseFence. It does not itself change the
	// Task's current lease; core pairs it with CompareAndSwapTask in this Update.
	InsertLeaseGrant(StoreLeaseGrantRecord) error
	// InsertArtifact inserts one immutable payload identity. Artifact IDs are
	// authority-wide unique and a Task owns at most one Artifact; collisions use
	// StoreConstraintArtifactID and StoreConstraintArtifactTask respectively.
	InsertArtifact(StoreArtifactRecord) error
	// CompareAndSwapArtifact changes only the state and terminal timestamps when
	// the exact ArtifactRef, bound TaskRef, and ExpectedState match. Absence or a
	// Task/state miss returns (false, nil); identity-invalid input is an error.
	CompareAndSwapArtifact(StoreArtifactMutation) (bool, error)
	// InsertSubmission inserts the immutable, sole Submission for its Task. Its
	// (Authority, Submission ID) is also unique. Any collision returns
	// ErrStoreConflict with StoreConstraintSubmissionID.
	InsertSubmission(StoreSubmissionRecord) error
	// InsertWorkspaceHead is first-writer-wins for Head.Workspace. It returns true
	// only when it inserted the row. An existing row returns (false, nil), remains
	// unchanged even when its value differs, and must be loaded before deciding the
	// next action.
	InsertWorkspaceHead(StoreWorkspaceHeadRecord) (bool, error)
	// CompareAndSwapWorkspaceHead replaces an existing head only when
	// ExpectedRevision matches. An absent head or revision miss returns (false,
	// nil); a Workspace/Next identity mismatch is an error.
	CompareAndSwapWorkspaceHead(StoreWorkspaceHeadMutation) (bool, error)
	// InsertApplyReceipt inserts the immutable, sole receipt for its Artifact.
	// (Authority, Receipt ID) is also unique. Any collision returns
	// ErrStoreConflict with StoreConstraintReceiptID.
	InsertApplyReceipt(StoreApplyReceiptRecord) error
}

StoreTx extends one StoreView with typed mutation primitives. These methods do not commit independently. All successful calls become visible together only when the enclosing Store.Update commits.

Immutable inserts return an error matching ErrStoreConflict on any logical uniqueness collision, including an exact duplicate; the typed constraint named below is part of the portable contract. InsertWorkspaceHead is the sole first-writer-wins exception and reports existence with its boolean. CAS and first-writer methods return (false, nil) for the documented miss and must not partially modify a record. The Agent core, not the Store, owns state-transition policy, command digests, timestamps, replay validation, and lease authorization.

type StoreView ¶

type StoreView interface {
	// LookupCommand loads the immutable command keyed by (Authority, ID). MaxBytes
	// applies to Result only; absence matches ErrStoreRecordNotFound.
	LookupCommand(StoreCommandKey, StoreReadLimit) (StoreCommandRecord, error)
	// LoadTask loads the aggregate whose Task.Ref exactly equals ref. It includes
	// the current lease and any Artifact/Submission links visible in this snapshot;
	// absence matches ErrStoreRecordNotFound.
	LoadTask(TaskRef) (StoreTaskRecord, error)
	// ResolveTask resolves the authority-wide public identity (authority, task ID)
	// to its unique Workspace-qualified TaskRef. It must never cross authority
	// boundaries; absence matches ErrStoreRecordNotFound.
	ResolveTask(AuthorityID, TaskID) (TaskRef, error)
	// LoadMessage loads the immutable message keyed by (Authority, Message ID). The
	// returned record ID and Task authority must match that key. MaxBytes applies
	// to EncodedParts; absence matches ErrStoreRecordNotFound.
	LoadMessage(StoreMessageKey, StoreReadLimit) (StoreMessageRecord, error)
	// LoadArtifact loads the Artifact whose Artifact.Ref exactly equals ref.
	// MaxBytes applies to EncodedPayload; absence matches ErrStoreRecordNotFound.
	LoadArtifact(ArtifactRef, StoreReadLimit) (StoreArtifactRecord, error)
	// LoadApplyReceipt loads the immutable terminal receipt keyed by its exact
	// ArtifactRef; absence matches ErrStoreRecordNotFound.
	LoadApplyReceipt(ArtifactRef) (StoreApplyReceiptRecord, error)
	// LoadWorkspaceHead loads the head whose WorkspaceRef exactly equals ref;
	// absence matches ErrStoreRecordNotFound.
	LoadWorkspaceHead(WorkspaceRef) (StoreWorkspaceHeadRecord, error)
	// LoadLeaseGrant loads immutable history for the exact (TaskRef, Fence) key;
	// absence matches ErrStoreRecordNotFound.
	LoadLeaseGrant(TaskRef, LeaseFence) (StoreLeaseGrantRecord, error)
	// LoadLatestLeaseGrant returns the record with the greatest Fence for ref, not
	// the record with the greatest wall-clock time. No history matches
	// ErrStoreRecordNotFound.
	LoadLatestLeaseGrant(TaskRef) (StoreLeaseGrantRecord, error)
	// FindClaimableTask returns the deterministic oldest unleased, non-terminal
	// Task in authority: CreatedAt, Workspace ID, then Task ID, all ascending. It
	// only selects; it does not reserve or mutate the Task. No candidate matches
	// ErrStoreRecordNotFound.
	FindClaimableTask(AuthorityID) (StoreTaskRecord, error)
	// ScanContextTasks returns only records in scan.Context, in the exact order and
	// exclusive-cursor semantics defined by StoreTaskContextScan. It returns at
	// most Limit records; zero matches are a successful empty result.
	ScanContextTasks(StoreTaskContextScan) ([]StoreTaskRecord, error)
	// ScanAuthorityTasks applies all filters and returns Records, ordering, and
	// TotalSize exactly as StoreTaskAuthorityScan specifies. Zero matches are a
	// successful result with TotalSize zero.
	ScanAuthorityTasks(StoreTaskAuthorityScan) (StoreTaskAuthorityResult, error)
	// ScanMessages returns at most Limit messages in the exact order, cursor, and
	// aggregate byte-budget semantics defined by StoreMessageScan. Zero matches are
	// a successful empty result.
	ScanMessages(StoreMessageScan) ([]StoreMessageRecord, error)
	// ScanEvents returns at most Limit events in the exact order and exclusive
	// cursor semantics defined by StoreEventScan. Zero matches are a successful
	// empty result.
	ScanEvents(StoreEventScan) ([]StoreEventRecord, error)
	// ScanLeases returns at most Limit assignments in StoreLeaseScan order. Each
	// item couples the current Task lease with the immutable grant at that same
	// Fence from this snapshot. Zero matches are a successful empty result.
	ScanLeases(StoreLeaseScan) ([]LeaseAssignment, error)
}

StoreView is a transaction-bound logical snapshot. It intentionally exposes no SQL, table, driver cursor, or transport type. Every returned record and byte slice belongs to the caller. Single-record lookup, load, resolve, and find methods report absence with an error matching ErrStoreRecordNotFound; scan methods instead return a successful empty result. Every read made through the StoreView embedded in StoreTx observes earlier writes in that Update.

type StoreWorkspaceHeadMutation ¶

type StoreWorkspaceHeadMutation struct {
	Workspace        WorkspaceRef
	ExpectedRevision workspace.Revision
	Next             StoreWorkspaceHeadRecord
}

StoreWorkspaceHeadMutation advances a Workspace head by exact revision CAS. Workspace and Next.Head.Workspace must be identical. A false result means the head is absent or ExpectedRevision is no longer confirmed.

type StoreWorkspaceHeadRecord ¶

type StoreWorkspaceHeadRecord struct {
	Head WorkspaceHead
}

StoreWorkspaceHeadRecord is the confirmed caller Workspace revision. A successful apply receipt advances it by compare-and-swap in the same Update.

type Submission ¶

type Submission struct {
	ID           SubmissionID `json:"id"`
	Task         TaskRef      `json:"task"`
	FinalMessage MessageID    `json:"final_message"`
	Artifact     *ArtifactRef `json:"artifact,omitempty"`
	PublishedAt  time.Time    `json:"published_at"`
}

Submission is published atomically with its final Agent message and the Task's transition to completed. Artifact is added by the workspace delivery phase; a nil/absent Artifact is a first-class content-only result.

type SubmissionID ¶

type SubmissionID string

type Task ¶

type Task struct {
	Ref          TaskRef      `json:"ref"`
	Context      ContextRef   `json:"context"`
	State        TaskState    `json:"state"`
	Revision     uint64       `json:"revision"`
	MessageCount uint64       `json:"message_count"`
	EventCount   uint64       `json:"event_count"`
	Artifact     *ArtifactRef `json:"artifact,omitempty"`
	Submission   *Submission  `json:"submission,omitempty"`
	CreatedAt    time.Time    `json:"created_at"`
	UpdatedAt    time.Time    `json:"updated_at"`
}

type TaskCommand ¶

type TaskCommand struct {
	Meta CommandMeta `json:"meta"`
	Task TaskRef     `json:"task"`
}

type TaskID ¶

type TaskID string

type TaskPage ¶

type TaskPage struct {
	Items   []Task          `json:"items"`
	Next    *TaskPageCursor `json:"next,omitempty"`
	HasMore bool            `json:"has_more"`
}

type TaskPageCursor ¶

type TaskPageCursor struct {
	CreatedAt time.Time   `json:"created_at"`
	Workspace WorkspaceID `json:"workspace"`
	Task      TaskID      `json:"task"`
}

TaskPageCursor is a stable keyset cursor over a live view, not a snapshot. Context is supplied separately; the cursor cannot move a query across an authenticated authority boundary.

type TaskPageRequest ¶

type TaskPageRequest struct {
	After *TaskPageCursor `json:"after,omitempty"`
	Limit int             `json:"limit,omitempty"`
}

type TaskQuery ¶

type TaskQuery struct {
	Context          ContextID        `json:"context,omitempty"`
	State            TaskState        `json:"state,omitempty"`
	UpdatedAtOrAfter *time.Time       `json:"updated_at_or_after,omitempty"`
	After            *TaskQueryCursor `json:"after,omitempty"`
	Limit            int              `json:"limit,omitempty"`
}

TaskQuery filters an authenticated Authority's Tasks. Zero Context and State values mean "any". UpdatedAtOrAfter is inclusive. TotalSize in the result is evaluated in the same stable Store snapshot as the returned page.

type TaskQueryCursor ¶

type TaskQueryCursor struct {
	UpdatedAt time.Time   `json:"updated_at"`
	Workspace WorkspaceID `json:"workspace"`
	Task      TaskID      `json:"task"`
}

TaskQueryCursor is a stable keyset cursor over an authority-wide live view. Tasks are ordered by most recently updated first, then by their stable key. Task IDs are unique inside one authenticated Authority; Workspace remains in the cursor so a corrupt store cannot silently alias two correctness scopes.

type TaskQueryPage ¶

type TaskQueryPage struct {
	Items     []Task           `json:"items"`
	Next      *TaskQueryCursor `json:"next,omitempty"`
	HasMore   bool             `json:"has_more"`
	TotalSize uint64           `json:"total_size"`
}

type TaskRef ¶

type TaskRef struct {
	Workspace WorkspaceRef `json:"workspace"`
	ID        TaskID       `json:"id"`
}

TaskRef is the durable Agent task key. The "agent" surface discriminator is implicit in this package and in its Store namespace; it never aliases a completion task key.

type TaskSnapshot ¶

type TaskSnapshot struct {
	Task        Task   `json:"task"`
	EventCursor uint64 `json:"event_cursor"`
}

TaskSnapshot couples a Task with the exact append-only Event cursor observed in the same database snapshot. Reading events after EventCursor cannot miss a concurrent commit; it either appears in the subsequent page or a later poll.

type TaskState ¶

type TaskState string

const (
	TaskSubmitted     TaskState = "submitted"
	TaskWorking       TaskState = "working"
	TaskInputRequired TaskState = "input_required"
	TaskCompleted     TaskState = "completed"
	TaskCanceled      TaskState = "canceled"
	TaskRejected      TaskState = "rejected"
	TaskFailed        TaskState = "failed"
)

func (state TaskState) Terminal() bool

type TransitionError ¶

type TransitionError struct {
	Operation string
	State     TaskState
	Terminal  bool
}

TransitionError retains the operation and state while supporting errors.Is.

func (failure *TransitionError) Error() string

func (failure *TransitionError) Unwrap() error

type WorkerArtifactFreeze ¶

type WorkerArtifactFreeze struct {
	Artifact             ArtifactID         `json:"artifact"`
	ExpectedBaseRevision workspace.Revision `json:"expected_base_revision"`
	Payload              workspace.Payload  `json:"payload"`
}

WorkerArtifactFreeze is present only for WorkerEventFreezeArtifact. Payload is declarative workspace data; the worker transport never applies it locally.

type WorkerAssignmentDelivery ¶

type WorkerAssignmentDelivery struct {
	ID         WorkerDeliveryID `json:"delivery_id"`
	Assignment LeaseAssignment  `json:"assignment"`
}

WorkerAssignmentDelivery contains a previously committed lease assignment. Repetition is normal protocol behavior and never creates a new lease fence.

func CloneWorkerAssignmentDelivery(delivery WorkerAssignmentDelivery) WorkerAssignmentDelivery

func (delivery WorkerAssignmentDelivery) ValidateFor(principal AuthenticatedWorker) error

type WorkerCommandMeta ¶

type WorkerCommandMeta struct {
	ID               CommandID  `json:"id"`
	ExpectedRevision uint64     `json:"expected_revision"`
	Grant            LeaseGrant `json:"grant"`
}

WorkerCommandMeta couples ordinary command idempotency/revision CAS with the grant that must still be current at the exact Store commit boundary.

type WorkerConnection ¶

type WorkerConnection interface {
	framework.Runtime
	Principal() AuthenticatedWorker
	Assignments() <-chan WorkerAssignmentDelivery
	AckAssignment(context.Context, WorkerDeliveryID) error
	CommitEvent(context.Context, WorkerEventDelivery) (WorkerEventReceipt, error)
}

WorkerConnection binds every operation to one authenticated principal.

Assignments has one sender and closer: the connection. The transport is its only receiver. A delivery remains owned by the connection until AckAssignment succeeds or the connection ends. The transport may ACK only after the remote worker has durably stored the exact assignment. Lack of ACK, an ACK lost in transit, or reconnect permits exact value-equivalent redelivery with the same Delivery ID; task acceptance is a separate WorkerEvent.

CommitEvent is the only event-to-ACK boundary. An ACK receipt may be returned only after the corresponding Agent command and its durable command receipt have committed (or an exact committed command was replayed). A NACK is a deterministic terminal rejection and also tells a durable worker outbox to delete that record. An error settles nothing: the outbox retains the exact delivery and retries or reconciles according to its error classification.

type WorkerConnectionError ¶

type WorkerConnectionError struct {
	Principal AuthenticatedWorker
	Cause     error
}

WorkerConnectionError adds authenticated session context while preserving errors.Is/errors.As classification through Cause.

func (failure *WorkerConnectionError) Error() string

func (failure *WorkerConnectionError) Unwrap() error

type WorkerDeliveryError ¶

type WorkerDeliveryError struct {
	Delivery WorkerDeliveryID
	Event    CommandID
	Cause    error
}

WorkerDeliveryError identifies an unsettled delivery while preserving its typed cause. In particular, ErrWorkerDeliveryIndeterminate requires exact replay/reconciliation and must never be translated into ACK or NACK.

func (failure *WorkerDeliveryError) Error() string

func (failure *WorkerDeliveryError) Unwrap() error

type WorkerDeliveryID ¶

type WorkerDeliveryID string

WorkerDeliveryID identifies one transport delivery. It is intentionally distinct from a domain CommandID and remains stable across retransmission.

type WorkerEndpoint ¶

type WorkerEndpoint interface {
	OpenWorker(context.Context, AuthenticatedWorker) (WorkerConnection, error)
}

WorkerEndpoint is the narrow Agent-core surface borrowed by a transport. OpenWorker is called only after transport authentication and policy checks. Its context bounds initialization only; after success the returned connection has an independent lifecycle. The transport must call connection.Shutdown when the wire session ends, but it never shuts down the endpoint itself. Implementations must allow concurrent OpenWorker calls.

type WorkerEndpointConfig ¶

type WorkerEndpointConfig struct {
	PollInterval       time.Duration
	RedeliveryInterval time.Duration
	AssignmentBuffer   int
}

WorkerEndpointConfig controls the official in-process bridge between an Agent core and any WorkerTransport. PollInterval discovers newly submitted tasks and caller-side Task updates. RedeliveryInterval repeats an assignment until the transport reports that the remote worker durably stored it.

func DefaultWorkerEndpointConfig() WorkerEndpointConfig

type WorkerEvent ¶

type WorkerEvent struct {
	ID               CommandID             `json:"event_id"`
	Kind             WorkerEventKind       `json:"kind"`
	Task             TaskRef               `json:"task"`
	Fence            LeaseFence            `json:"fence"`
	ExpectedRevision uint64                `json:"expected_revision"`
	Message          *MessageInput         `json:"message,omitempty"`
	Submission       SubmissionID          `json:"submission,omitempty"`
	Artifact         *ArtifactRef          `json:"artifact,omitempty"`
	Freeze           *WorkerArtifactFreeze `json:"freeze,omitempty"`
}

WorkerEvent is transport-neutral input to one worker-authorized Agent command. ID is the durable domain command/event identity; Fence and Task identify the lease generation. WorkerID is structurally absent and must be taken from the WorkerConnection principal at the commit boundary.

Message is required only by request_input and complete_task. Submission and optional Artifact are used only by complete_task. Freeze is used only by freeze_artifact. Unused fields must be zero so an adapter cannot smuggle an ignored interpretation through different codecs.

type WorkerEventDecision ¶

type WorkerEventDecision string

WorkerEventDecision is a terminal transport settlement. Both values remove the exact event from a durable worker outbox; an error from CommitEvent does not. ACK means committed/replayed. NACK means deterministically rejected without accepting the requested domain transition.

const (
	WorkerEventACK  WorkerEventDecision = "ack"
	WorkerEventNACK WorkerEventDecision = "nack"
)

type WorkerEventDelivery ¶

type WorkerEventDelivery struct {
	ID    WorkerDeliveryID `json:"delivery_id"`
	Event WorkerEvent      `json:"event"`
}

WorkerEventDelivery is the worker outbox unit. Exact retries use the same ID and the same Event. Reusing ID with different Event is a deterministic NACK.

func CloneWorkerEventDelivery(delivery WorkerEventDelivery) WorkerEventDelivery

func (delivery WorkerEventDelivery) Validate() error

func (delivery WorkerEventDelivery) ValidateFor(principal AuthenticatedWorker) error

type WorkerEventKind ¶

type WorkerEventKind string

WorkerEventKind is the closed set of Agent domain commands accepted from a worker. Adding a kind requires a transport-contract minor or major revision; adapters must never pass unknown values through as generic executable tools.

const (
	WorkerEventAcceptTask     WorkerEventKind = "accept_task"
	WorkerEventRejectTask     WorkerEventKind = "reject_task"
	WorkerEventRequestInput   WorkerEventKind = "request_input"
	WorkerEventFailTask       WorkerEventKind = "fail_task"
	WorkerEventFreezeArtifact WorkerEventKind = "freeze_artifact"
	WorkerEventCompleteTask   WorkerEventKind = "complete_task"
)

type WorkerEventReceipt ¶

type WorkerEventReceipt struct {
	Delivery WorkerDeliveryID    `json:"delivery_id"`
	Event    CommandID           `json:"event_id"`
	Decision WorkerEventDecision `json:"decision"`
	Code     WorkerRejectionCode `json:"code,omitempty"`
	Message  string              `json:"message,omitempty"`
}

WorkerEventReceipt is exact-retry stable. ACK receipts may be emitted only at the domain durability boundary described by WorkerConnection.CommitEvent. NACK Code is safe for protocol logic; Message is diagnostic and must not be parsed for behavior.

func (receipt WorkerEventReceipt) ValidateFor(delivery WorkerEventDelivery) error

type WorkerID ¶

type WorkerID string

type WorkerMessageCommand ¶

type WorkerMessageCommand struct {
	Meta    WorkerCommandMeta `json:"meta"`
	Task    TaskRef           `json:"task"`
	Message MessageInput      `json:"message"`
}

type WorkerRejectionCode ¶

type WorkerRejectionCode string

WorkerRejectionCode is a stable machine code selected by WorkerEndpoint. It is intentionally more specific than an HTTP or WebSocket status.

const (
	WorkerRejectInvalid         WorkerRejectionCode = "invalid"
	WorkerRejectForbidden       WorkerRejectionCode = "forbidden"
	WorkerRejectNotFound        WorkerRejectionCode = "not_found"
	WorkerRejectStaleLease      WorkerRejectionCode = "stale_lease"
	WorkerRejectRevision        WorkerRejectionCode = "revision_conflict"
	WorkerRejectState           WorkerRejectionCode = "state_conflict"
	WorkerRejectCommandConflict WorkerRejectionCode = "command_conflict"
)

type WorkerSessionID ¶

type WorkerSessionID string

WorkerSessionID identifies one live connection only. It is deliberately not part of Task, command, lease, delivery, or idempotency identity and therefore changes on reconnect.

type WorkerTaskCommand ¶

type WorkerTaskCommand struct {
	Meta WorkerCommandMeta `json:"meta"`
	Task TaskRef           `json:"task"`
}

type WorkerTransport ¶

type WorkerTransport interface {
	Description() WorkerTransportDescription
	Start(context.Context, WorkerEndpoint) (WorkerTransportRuntime, error)
}

WorkerTransport owns its listeners, sessions, and background delivery loops, but only borrows endpoint. Start must not retain ctx after initialization; the returned runtime owns its lifetime. Shutdown must stop admission, shut down all WorkerConnections opened through endpoint, and wait for adapter goroutines. It must never close endpoint, type-assert it to *Agent, or close dependencies reachable through endpoint.

type WorkerTransportDescription ¶

type WorkerTransportDescription struct {
	Contract framework.Contract
	Provider string
	Version  string
}

WorkerTransportDescription is static, non-secret adapter metadata. Provider identifies an implementation (for example "websocket" or "grpc") and Version identifies that implementation, not its negotiated wire version.

func (description WorkerTransportDescription) Validate() error

type WorkerTransportRuntime ¶

type WorkerTransportRuntime interface {
	framework.Runtime
}

WorkerTransportRuntime is separated from WorkerTransport so a reusable adapter value is not itself confused with one running instance.

type WorkspaceHead ¶

type WorkspaceHead struct {
	Workspace         WorkspaceRef       `json:"workspace"`
	ConfirmedRevision workspace.Revision `json:"confirmed_revision"`
	UpdatedAt         time.Time          `json:"updated_at"`
}

type WorkspaceID ¶

type WorkspaceID string

type WorkspaceRef ¶

type WorkspaceRef struct {
	Authority AuthorityID `json:"authority"`
	ID        WorkspaceID `json:"id"`
}

WorkspaceRef is an authority-qualified correctness scope. Context and Workspace are deliberately orthogonal: different Contexts may share one Workspace and therefore its future Artifact CAS baseline.