workqueue

package
v0.91.15 Latest Latest
Warning

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

 Go to latest Published: Oct 14, 2026 License: MIT Imports: 34 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultBranch = "work-queue"
View Source 
const FileName = "work-queue.jsonl"
View Source 
const MaxClaimsPerDispatch = 16
View Source 
const MaxEnqueued = MaxTimestamp
View Source 
const MaxTimestamp int64 = 9007199254740991
View Source 
const Version = 3

Variables

This section is empty.

Functions

func AuthorizeEffect added in v0.91.6 

func AuthorizeEffect(state Projection, actor Actor, target EffectResource) error

func BuildCandidate added in v0.91.6 

func BuildCandidate(commits []QueueCommit, actor Actor, request Request, at int64) ([]QueueCommit, *QueueCommit, Decision, error)

func Canonical added in v0.91.6 

func Canonical(data []byte) ([]byte, error)

Canonical uses the contract's integer-only JSON profile and UTF-8 key order.

func CanonicalValue added in v0.91.6 

func CanonicalValue(value any) ([]byte, error)

CanonicalValue encodes typed JSON without repairing strings or losing numeric values.

func DispatchPrincipal 

func DispatchPrincipal(dispatch *DispatchState) string

DispatchPrincipal is frozen at launch from the selected AW credential, not from the publisher or an unverified native run.

func Fingerprint added in v0.91.6 

func Fingerprint(actor Actor, kind string, parameters json.RawMessage) (string, error)

func IndependentGraphID added in v0.91.6 

func IndependentGraphID(payload []byte) (string, error)

func NodeID added in v0.91.6 

func NodeID(graphID, nodeKey string) string

func NormalizeClaimHandle added in v0.91.6 

func NormalizeClaimHandle(assignment Assignment, selector *string) (string, error)

func ObservationRefreshBudget added in v0.91.6 

func ObservationRefreshBudget(state Projection, requested int) (int, error)

ObservationRefreshBudget reserves a Claim slot and excludes optional recovery-capacity reads.

func ProposedCommitID added in v0.91.6 

func ProposedCommitID(state Projection, request Request) string

func RecoveryHeadroom added in v0.91.6 

func RecoveryHeadroom(state Projection) int64

RecoveryHeadroom reports the outstanding closure reservation for a replayed projection.

func Serialize 

func Serialize(commits []QueueCommit) ([]byte, error)

func ValidateAssignment added in v0.91.6 

func ValidateAssignment(state Projection, assignment Assignment) error

func ValidateCommit added in v0.91.6 

func ValidateCommit(commit QueueCommit) error

func ValidatePolicy added in v0.91.6 

func ValidatePolicy(policy Policy) error

ValidatePolicy checks the closed contract and semantic limits, not caller authentication or approval of the configured worker identities.

Types

type Actor added in v0.91.6 

type Actor struct {
	Role        string `json:"role"`
	Principal   string `json:"principal"`
	Repository  string `json:"repository"`
	Workflow    string `json:"workflow,omitempty"`
	RunID       string `json:"run_id,omitempty"`
	RunAttempt  int    `json:"run_attempt,omitempty"`
	DispatchID  string `json:"dispatch_id,omitempty"`
	ClaimHandle string `json:"claim_handle,omitempty"`
}

type Assignment added in v0.91.6 

type Assignment struct {
	Version       int               `json:"version"`
	DispatchID    string            `json:"dispatch_id"`
	RequestID     string            `json:"request_id"`
	CommitID      string            `json:"commit_id"`
	PolicyEpoch   string            `json:"policy_epoch"`
	Pool          string            `json:"pool"`
	WorkerProfile string            `json:"worker_profile"`
	Claims        []AssignmentClaim `json:"claims"`
}

func ParseAssignment added in v0.91.6 

func ParseAssignment(data []byte) (Assignment, error)

func (Assignment) ToReceipt 

func (assignment Assignment) ToReceipt() AssignmentReceipt

ToReceipt projects immutable identity only, preserving source claim order. Callers must validate the assignment and populate lifecycle facts from their captured projection.

type AssignmentClaim added in v0.91.6 

type AssignmentClaim struct {
	Handle     string            `json:"handle"`
	ClaimID    string            `json:"claim_id"`
	WorkID     string            `json:"work_id"`
	Work       json.RawMessage   `json:"work"`
	ResultRefs []ResultReference `json:"result_refs"`
}

func (AssignmentClaim) ToReceipt 

func (claim AssignmentClaim) ToReceipt() ClaimReceipt

ToReceipt omits work payloads and result references; lifecycle fields are populated separately from the captured projection.

type AssignmentReceipt 

type AssignmentReceipt struct {
	DispatchID string         `json:"dispatch_id"`
	RequestID  string         `json:"request_id"`
	CommitID   string         `json:"commit_id"`
	State      string         `json:"state"`
	Released   bool           `json:"released"`
	Claims     []ClaimReceipt `json:"claims"`
}

AssignmentReceipt describes assignment identity and captured lifecycle facts without carrying work payloads, result descriptors, or actor credentials.

type Branch 

type Branch struct {
	Remote              string
	Name                string
	DependencyClients   map[string]*api.RESTClient
	DeliveryVerifier    DeliveryVerifier
	RemediationVerifier RemediationVerifier
	PolicyProposal      *Policy // Host-approved first-submit proposal; never replaces installed Policy.
	// contains filtered or unexported fields
}

Branch operates through GitHub Git APIs without a local checkout or Git executable.

func (Branch) Authenticate added in v0.91.6 

func (b Branch) Authenticate(ctx context.Context, role string) (Actor, error)

Authenticate derives operator identity from the credential, not command flags, Git authors, submitted actor fields, or an untrusted Actions environment.

func (Branch) CancelReserved added in v0.91.6 

func (b Branch) CancelReserved(ctx context.Context, dispatchID, requestID string) (Reconciliation, error)

CancelReserved is a checked prelaunch cancellation, never a force release. A competing start marker wins through CAS and makes this request invalid.

func (Branch) Compact added in v0.91.6 

func (b Branch) Compact(ctx context.Context) (Compaction, error)

Compact replaces validated history with a canonical checkpoint rooted at the Git commit that supplied the prior ledger.

func (Branch) DeploymentOperationsFromConfig 

func (b Branch) DeploymentOperationsFromConfig(ctx context.Context, state Projection, poolName, workerName string) ([]Operation, error)

DeploymentOperationsFromConfig proposes route-only changes for existing AW workers. Missing artifacts or registrations pause only the affected targets.

func (Branch) DispatcherFromConfig 

func (b Branch) DispatcherFromConfig(ctx context.Context, name string) (DispatcherRoute, error)

DispatcherFromConfig resolves a dispatcher, never a worker assignment, at the repository's verified default revision. It does not grant or launch Claims.

func (Branch) InspectEvidence added in v0.91.6 

func (b Branch) InspectEvidence(ctx context.Context, dispatchID string) (Reconciliation, error)

func (Branch) PolicyFromConfig 

func (b Branch) PolicyFromConfig(ctx context.Context) (Policy, error)

PolicyFromConfig resolves scheduling and AW worker approval from this target repository's verified immutable default ref, never the current local checkout.

func (Branch) PrepareDispatcherActivation 

func (b Branch) PrepareDispatcherActivation(ctx context.Context, route DispatcherRoute) (string, error)

PrepareDispatcherActivation binds a previously verified dispatcher route to a named snapshot ref. It never moves or deletes tags, including on collisions. Repository writers must not mutate the snapshot tag while it is in use.

func (Branch) Publish added in v0.91.6 

func (b Branch) Publish(ctx context.Context, actor Actor, request Request) (Publication, error)

Publish retains only authenticated logical intent across CAS retries. It discards selections, handles, charges and clocks and recovers uncertain ref acknowledgments by stable request identity before constructing another grant.

func (Branch) Read 

func (b Branch) Read(ctx context.Context) ([]QueueCommit, error)

func (Branch) Reconcile added in v0.91.6 

func (b Branch) Reconcile(ctx context.Context, dispatchID, requestID string) (Reconciliation, error)

Reconcile inspects the exact bound native attempt. Missing/unbound runs retain reservations; terminal recovery cancels open members only, preserving every Completion and independently pending delivery barrier.

func (Branch) RecoverDelivery added in v0.91.6 

func (b Branch) RecoverDelivery(ctx context.Context, workID, requestID string) (DeliveryRecovery, error)

RecoverDelivery settles a barrier independently of native capacity. Missing proof remains unknown; neither an overall run success nor a missing artifact is interpreted as verified delivery or as proof that effects never began.

type Capacity added in v0.91.6 

type Capacity struct {
	Logical int `json:"logical"`
	Native  int `json:"native"`
	Account int `json:"account"`
}

type CheckpointOperation 

type CheckpointOperation struct {
	Kind          string          `json:"kind"`
	PriorGitSHA   string          `json:"prior_git_sha"`
	PriorTip      string          `json:"prior_tip"`
	HistorySHA256 string          `json:"history_sha256"`
	StateSHA256   string          `json:"state_sha256"`
	State         json.RawMessage `json:"state"`
}

CheckpointOperation carries a minimal projection bound to prior Git history.

type CheckpointParameters 

type CheckpointParameters struct {
	PriorGitSHA   string `json:"prior_git_sha"`
	PriorTip      string `json:"prior_tip"`
	HistorySHA256 string `json:"history_sha256"`
	StateSHA256   string `json:"state_sha256"`
}

type ClaimExplanation added in v0.91.6 

type ClaimExplanation struct {
	Tip            string    `json:"tip"`
	At             int64     `json:"at"`
	Status         string    `json:"status"`
	BeforeTip      string    `json:"before_tip"`
	Position       Position  `json:"position"`
	RequestID      string    `json:"request_id"`
	CommitID       string    `json:"commit_id"`
	PolicyEpoch    string    `json:"policy_epoch"`
	ClaimID        string    `json:"claim_id"`
	DispatchID     string    `json:"dispatch_id"`
	Handle         string    `json:"claim_handle"`
	WorkID         string    `json:"work_id"`
	Pool           string    `json:"pool"`
	Priority       int       `json:"priority"`
	FairnessKey    string    `json:"fairness_key"`
	WorkPosition   Position  `json:"work_position"`
	Selection      Selection `json:"selection"`
	ClassPassPrior string    `json:"class_pass_prior"`
	KeyPassPrior   string    `json:"key_pass_prior"`
	CapacityBefore Capacity  `json:"capacity_before"`
	CapacityAfter  Capacity  `json:"capacity_after"`
}

func ExplainBeforeClaim added in v0.91.6 

func ExplainBeforeClaim(commits []QueueCommit, claimID string) (ClaimExplanation, error)

ExplainBeforeClaim validates the whole authority, then reduces the exact predecessor and earlier in-commit observations/Claims with native reducers.

type ClaimOperation added in v0.91.6 

type ClaimOperation struct {
	Kind         string   `json:"kind"`
	WorkID       string   `json:"work_id"`
	ClaimID      string   `json:"claim_id"`
	DispatchID   string   `json:"dispatch_id"`
	Handle       string   `json:"handle"`
	Observations []string `json:"observations"`
}

type ClaimReceipt 

type ClaimReceipt struct {
	Handle  string `json:"claim_handle"`
	ClaimID string `json:"claim_id"`
	WorkID  string `json:"work_id"`
	State   string `json:"state"`
	Barrier string `json:"delivery_barrier"`
}

type ClaimState 

type ClaimState struct {
	ClaimOperation
	State              string `json:"state"`
	CommitID           string `json:"commit_id"`
	RequestID          string `json:"request_id"`
	TerminalCommitID   string `json:"terminal_commit_id,omitempty"`
	CancellationReason string `json:"cancellation_reason,omitempty"`
	RetryNotBefore     int64  `json:"retry_not_before,omitempty"`
	IssueComment       string `json:"issue_comment,omitempty"`
	KeepOpen           bool   `json:"keep_open,omitempty"`
	Barrier            string `json:"barrier,omitempty"`
}

type Clock added in v0.91.6 

type Clock struct {
	V      string            `json:"v"`
	Pass   map[string]string `json:"pass"`
	Active map[string]bool   `json:"active"`
}

type Compaction added in v0.91.6 

type Compaction struct {
	Tip                     string `json:"tip"`
	At                      int64  `json:"at"`
	Changed                 bool   `json:"changed"`
	AcknowledgmentRecovered bool   `json:"acknowledgment_recovered"`
	Commits                 int    `json:"commits"`
	DuplicatesRemoved       int    `json:"duplicates_removed"`
	BytesBefore             int    `json:"bytes_before"`
	BytesAfter              int    `json:"bytes_after"`
}

type Decision added in v0.91.6 

type Decision struct {
	Tip         string       `json:"tip"`
	Operations  []Operation  `json:"operations"`
	Assignments []Assignment `json:"assignments"`
	Reason      string       `json:"reason"`
	Next        Selection    `json:"next"`
}

func PlanDispatch added in v0.91.6 

func PlanDispatch(state Projection, params DispatchParameters, requestID, commitID string, at int64) (Decision, error)

type DeliveryRecovery added in v0.91.6 

type DeliveryRecovery struct {
	WorkID      string       `json:"work_id"`
	Reason      string       `json:"reason"`
	Attempts    int          `json:"attempts"`
	Publication *Publication `json:"publication,omitempty"`
}

type DeliveryVerification added in v0.91.6 

type DeliveryVerification struct {
	Verified          bool
	Descriptor        json.RawMessage
	Receipt           string
	Disposition       string
	PositiveNoEffects bool
}

type DeliveryVerifier added in v0.91.6 

type DeliveryVerifier func(context.Context, Projection, ClaimState) (DeliveryVerification, error)

DeliveryVerifier is a trusted, read-only receipt/effect-contract adapter. It verifies existing scoped effects; it must never execute or retry effects. Configuring it is a host capability, not an actor/source string or CLI flag.

type Dependency added in v0.91.6 

type Dependency struct {
	Kind      string    `json:"kind"`
	WorkID    string    `json:"work_id,omitempty"`
	Resource  *Resource `json:"resource,omitempty"`
	Condition string    `json:"condition,omitempty"`
}

type DeploymentOperation 

type DeploymentOperation struct {
	Kind             string        `json:"kind"`
	Pool             string        `json:"pool"`
	WorkerProfile    string        `json:"worker_profile"`
	ExpectedRef      string        `json:"expected_ref"`
	ExpectedContract string        `json:"expected_contract"`
	Profile          WorkerProfile `json:"profile"`
	Available        bool          `json:"available"`
	Activate         *bool         `json:"activate,omitempty"`
	Reason           string        `json:"reason"`
}

Deployment changes execution routes, never the installed scheduling policy.

type DispatchParameters added in v0.91.6 

type DispatchParameters struct {
	WorkerProfiles []string `json:"worker_profiles,omitempty"`
	Pool           string   `json:"pool"`
	MaxClaims      int      `json:"max_claims"`
	MaxDispatches  int      `json:"max_dispatches"`
	MaxBytes       int64    `json:"max_bytes"`
}

func (DispatchParameters) MarshalJSON 

func (parameters DispatchParameters) MarshalJSON() ([]byte, error)

type DispatchState added in v0.91.6 

type DispatchState struct {
	Assignment
	Profile             WorkerProfile `json:"profile"`
	State               string        `json:"state"`
	Sender              *Actor        `json:"sender,omitempty"`
	CredentialPrincipal string        `json:"credential_principal,omitempty"`
	Run                 *RunBinding   `json:"run,omitempty"`
	Released            bool          `json:"released"`
	Reason              string        `json:"reason,omitempty"`
	LifecycleWrites     int           `json:"lifecycle_writes"`
}

type DispatcherRoute 

type DispatcherRoute struct {
	Repository string `json:"repository"`
	Workflow   string `json:"workflow"`
	Ref        string `json:"ref"`
	Revision   string `json:"revision"`
}

type EffectResource added in v0.91.6 

type EffectResource map[string]string

EffectResource is a broker-resolved target, not an assertion of authenticated evidence.

type Evidence added in v0.91.6 

type Evidence struct {
	Kind       string `json:"kind"`
	Source     string `json:"source"`
	Repository string `json:"repository"`
	Workflow   string `json:"workflow"`
	Ref        string `json:"ref"`
	Principal  string `json:"principal"`
	CheckedAt  int64  `json:"checked_at"`
	RunID      string `json:"run_id,omitempty"`
	RunAttempt int    `json:"run_attempt,omitempty"`
	Status     string `json:"status,omitempty"`
	Conclusion string `json:"conclusion,omitempty"`
	Receipt    string `json:"receipt,omitempty"`
	Attempts   int    `json:"attempts,omitempty"`
	Effects    string `json:"effects,omitempty"`
}

type FinishParameters added in v0.91.6 

type FinishParameters struct {
	DispatchID  string `json:"dispatch_id"`
	ClaimHandle string `json:"claim_handle"`
	Outcome     string `json:"outcome"`
	KeepOpen    bool   `json:"keep_open,omitempty"`
}

func NormalizeFinishIntent added in v0.91.6 

func NormalizeFinishIntent(assignment Assignment, data []byte) (FinishParameters, error)

NormalizeFinishIntent preserves absent versus null through schema validation. The result still needs durable assignment/run/ownership verification.

type IssueCommentOperation added in v0.91.7 

type IssueCommentOperation struct {
	Kind             string `json:"kind"`
	WorkID           string `json:"work_id"`
	CommentID        string `json:"comment_id"`
	ProjectorRef     string `json:"projector_ref"`
	ClaimID          string `json:"claim_id,omitempty"`
	AuthorityClaimID string `json:"authority_claim_id,omitempty"`
}

type IssueLinkOperation added in v0.91.7 

type IssueLinkOperation struct {
	Kind         string   `json:"kind"`
	WorkID       string   `json:"work_id"`
	Resource     Resource `json:"resource"`
	ProjectorRef string   `json:"projector_ref"`
	ClaimID      string   `json:"claim_id,omitempty"`
}

type IssuesSettings 

type IssuesSettings struct {
	Label       string `json:"label"`
	TitlePrefix string `json:"title_prefix"`
}

IssuesSettings describes optional Issues projection, not queue authority. Nil Settings.Issues means disabled; true or {} uses the default label and title prefix.

type Limits added in v0.91.6 

type Limits struct {
	LedgerBytes       int64 `json:"ledger_bytes"`
	RecoveryBytes     int64 `json:"recovery_bytes"`
	PayloadBytes      int64 `json:"payload_bytes"`
	GraphNodes        int   `json:"graph_nodes"`
	Predecessors      int   `json:"predecessors"`
	PendingNodes      int   `json:"pending_nodes"`
	Operations        int   `json:"operations"`
	AssignmentBytes   int64 `json:"assignment_bytes"`
	ResultBytes       int64 `json:"result_bytes"`
	EvidenceBytes     int64 `json:"evidence_bytes"`
	ObservationWrites int   `json:"observation_writes"`
}

type NativeDeliveryHost added in v0.91.6 

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

NativeDeliveryHost owns in-process callback capabilities. JSON cannot create or configure a host. The copied registrations cannot be changed by Work data.

func NewNativeDeliveryHost added in v0.91.6 

func NewNativeDeliveryHost(options NativeDeliveryHostOptions) *NativeDeliveryHost

func (*NativeDeliveryHost) Verifier added in v0.91.6 

func (host *NativeDeliveryHost) Verifier(branch Branch) DeliveryVerifier

Verifier returns the native adapter used by both recovery and every fresh CAS prefix. It re-reads API provenance and approved callbacks on each invocation; a copied receipt/digest or successful job can never bypass those reads.

type NativeDeliveryHostOptions added in v0.91.6 

type NativeDeliveryHostOptions struct {
	Inventory func(context.Context, NativeDeliveryScope) (NativeDeliveryInventory, error)
	// Credentials proves the host has approved read credentials for this exact
	// target and generation before any output verifier may call an external SDK.
	Credentials func(context.Context, NativeDeliveryScope, EffectResource) error
	Builtin     map[string]NativeOutputVerifier
	Declared    map[string]NativeOutputVerifier
}

type NativeDeliveryInventory added in v0.91.6 

type NativeDeliveryInventory struct {
	Closed  bool
	Outputs []NativeDeliveryOutput
}

NativeDeliveryInventory must come from an approved process callback, not a receipt file, subprocess stdout, artifact, or caller-supplied source string. Closed means the process has stopped accepting effects for this member.

type NativeDeliveryOutput added in v0.91.6 

type NativeDeliveryOutput struct {
	Type      string
	Target    EffectResource
	Intent    json.RawMessage
	RequestID string
}

NativeDeliveryOutput is an item from the protected worker's closed effect channel. Intent and Target are data; neither grants verifier authority.

type NativeDeliveryScope added in v0.91.6 

type NativeDeliveryScope struct {
	Member               AssignmentClaim
	Run                  RunBinding
	CompletionID         string
	CredentialGeneration string
}

NativeDeliveryScope binds approved process callbacks to the immutable member and the authenticated original Actions attempt. It is not a wire credential.

type NativeOutputVerifier added in v0.91.6 

type NativeOutputVerifier func(context.Context, NativeDeliveryScope, NativeDeliveryOutput, json.RawMessage) (json.RawMessage, bool, error)

NativeOutputVerifier performs independent readback only. Hosts register these callbacks before admitting untrusted worker input; no verifier is executable merely because a Work names its ID.

type NativeRun added in v0.91.6 

type NativeRun struct {
	ID           json.Number `json:"id"`
	RunAttempt   int         `json:"run_attempt"`
	Event        string      `json:"event"`
	Status       string      `json:"status"`
	Conclusion   string      `json:"conclusion"`
	HeadSHA      string      `json:"head_sha"`
	Path         string      `json:"path"`
	DisplayTitle string      `json:"display_title"`
	Actor        struct {
		ID    json.Number `json:"id"`
		Login string      `json:"login"`
	} `json:"actor"`
	TriggeringActor struct {
		ID json.Number `json:"id,omitempty"`
	} `json:"triggering_actor"`
	Repository struct {
		FullName string `json:"full_name"`
	} `json:"repository"`
}

NativeRun is a bounded projection of the authenticated Actions run API. Native/resource IDs are decoded as json.Number and never through float64.

type Observation added in v0.91.6 

type Observation struct {
	Kind                 string   `json:"kind"`
	ObservationID        string   `json:"observation_id"`
	Resource             Resource `json:"resource"`
	Condition            string   `json:"condition"`
	State                string   `json:"state"`
	ObservedAt           int64    `json:"observed_at"`
	CredentialGeneration string   `json:"credential_generation"`
	SourceUpdatedAt      *int64   `json:"source_updated_at,omitempty"`
	ReadStatus           string   `json:"read_status"`
	StateReason          string   `json:"state_reason,omitempty"`
	ResourceState        string   `json:"resource_state,omitempty"`
	Merged               *bool    `json:"merged,omitempty"`
	MergeCommit          string   `json:"merge_commit,omitempty"`
}

type Operation added in v0.91.6 

type Operation = json.RawMessage

Operation stores a closed variant as raw JSON. Typed accessors keep absent, null, and explicit zero distinct, unlike a struct with omitempty authority.

func Op added in v0.91.6 

func Op(value any) (Operation, error)

type OperationsParameters added in v0.91.6 

type OperationsParameters struct {
	Operations []Operation `json:"operations"`
}

type Policy added in v0.91.6 

type Policy struct {
	Authorization     string                  `json:"authorization,omitempty"`
	Mode              string                  `json:"mode"`
	ClassWeights      []int                   `json:"class_weights"`
	AccountingWeights map[string]int          `json:"accounting_weights"`
	Producers         map[string]ProducerRule `json:"producers"`
	Projectors        []ProjectorRule         `json:"projectors,omitempty"`
	Pools             map[string]PoolPolicy   `json:"pools"`
	Limits            Limits                  `json:"limits"`
}

func DefaultPolicy added in v0.91.6 

func DefaultPolicy(principal, repository string) Policy

func FuturePolicy 

func FuturePolicy(state Projection) Policy

FuturePolicy exposes current routes for trusted admission builders only. It does not replace the installed policy or affect existing assignments.

type PoolClocks added in v0.91.6 

type PoolClocks struct {
	Classes Clock         `json:"classes"`
	Keys    map[int]Clock `json:"keys"`
}

type PoolPolicy added in v0.91.6 

type PoolPolicy struct {
	DefaultProfile      string                   `json:"default_profile"`
	Profiles            map[string]WorkerProfile `json:"profiles"`
	LogicalLimit        int                      `json:"logical_limit"`
	NativeLimit         int                      `json:"native_limit"`
	PerAccountLimit     int                      `json:"per_account_limit,omitempty"`
	AllowedRepositories []string                 `json:"allowed_repositories"`
	MaxObservationAgeMS int64                    `json:"max_observation_age_ms"`
	Retry               RetryPolicy              `json:"retry"`
	Reconciliation      ReconciliationPolicy     `json:"reconciliation"`
}

type PoolSettings 

type PoolSettings struct {
	Concurrency     int           `json:"concurrency"`
	PerAccountLimit int           `json:"per_account_limit,omitempty"`
	Retry           SettingsRetry `json:"retry"`
}

PoolSettings overrides scheduling while inheriting host-approved worker routes.

type Position added in v0.91.6 

type Position struct {
	Commit    int `json:"commit"`
	Operation int `json:"operation"`
}

type ProducerRule added in v0.91.6 

type ProducerRule struct {
	Pools        []string `json:"pools"`
	Priorities   []int    `json:"priorities"`
	FairnessKeys []string `json:"fairness_keys"`
}

type Projection 

type Projection struct {
	SchedulingProfiles   []string                                `json:"-"`
	Repository           string                                  `json:"repository"`
	Tip                  string                                  `json:"tip"`
	PolicyEpoch          string                                  `json:"policy_epoch"`
	Policy               *Policy                                 `json:"policy"`
	Deployments          map[string]map[string]*WorkerDeployment `json:"deployments,omitempty"`
	Works                map[string]*WorkState                   `json:"works"`
	Claims               map[string]*ClaimState                  `json:"claims"`
	Dispatches           map[string]*DispatchState               `json:"dispatches"`
	Observations         map[string]*Observation                 `json:"observations"`
	Requests             map[string]QueueCommit                  `json:"requests"`
	Clocks               map[string]PoolClocks                   `json:"clocks"`
	AdmissionPaused      bool                                    `json:"admission_paused"`
	GrantsPaused         bool                                    `json:"grants_paused"`
	CredentialGeneration string                                  `json:"credential_generation"`
	Stats                Stats                                   `json:"stats"`
	LedgerBytes          int64                                   `json:"ledger_bytes"`
	ObservationWrites    map[string]int                          `json:"observation_writes"`
	RequestOrder         []string                                `json:"-"`
	CheckpointReceipts   []checkpointReceipt                     `json:"-"`
	WorkCreators         map[string]Actor                        `json:"-"`
	ClaimExplanations    map[string]ClaimExplanation             `json:"-"`
	SeenEpochs           map[string]bool                         `json:"-"`
	SeenGenerations      map[string]bool                         `json:"-"`
	ObservationIDs       map[string]*Observation                 `json:"-"`
	TerminalBarriers     map[string]Operation                    `json:"-"`
	Cancellations        map[string]Operation                    `json:"-"`
}

func Replay 

func Replay(commits []QueueCommit) (Projection, error)

type ProjectorRule added in v0.91.7 

type ProjectorRule struct {
	Principal        string     `json:"principal"`
	Workflow         string     `json:"workflow"`
	Ref              string     `json:"ref"`
	Pools            []string   `json:"pools"`
	Repositories     []string   `json:"repositories"`
	BackingIssues    []Resource `json:"backing_issues,omitempty"`
	CompletionPolicy string     `json:"completion_policy,omitempty"`
}

type ProtocolError added in v0.91.6 

type ProtocolError struct {
	Code    string
	Message string
}

ProtocolError preserves a stable rejection code without requiring message matching.

func (*ProtocolError) Error added in v0.91.6 

func (e *ProtocolError) Error() string

type Publication added in v0.91.6 

type Publication struct {
	Commit   *QueueCommit `json:"commit,omitempty"`
	Decision Decision     `json:"decision"`
	Changed  bool         `json:"changed"`
}

type QueueCommit added in v0.91.6 

type QueueCommit struct {
	Version     int         `json:"version"`
	ID          string      `json:"id"`
	Previous    *string     `json:"previous"`
	Request     Request     `json:"request"`
	Actor       Actor       `json:"actor"`
	PolicyEpoch string      `json:"policy_epoch"`
	At          int64       `json:"at"`
	Operations  []Operation `json:"operations"`
	Trace       *Trace      `json:"trace,omitempty"`
}

func Compact 

func Compact(commits []QueueCommit) ([]QueueCommit, error)

func CompactCheckpoint 

func CompactCheckpoint(commits []QueueCommit, priorGitSHA string, actor Actor, at int64) ([]QueueCommit, error)

CompactCheckpoint constructs a minimal state checkpoint from validated history; priorGitSHA names the Git commit containing the prior ledger.

func Genesis added in v0.91.6 

func Genesis(actor Actor, policy Policy, requestID, epoch string, at int64) (QueueCommit, error)

func Parse 

func Parse(data []byte) ([]QueueCommit, error)

type Reconciliation added in v0.91.6 

type Reconciliation struct {
	DispatchID  string       `json:"dispatch_id"`
	State       string       `json:"state"`
	Reason      string       `json:"reason"`
	Evidence    *Evidence    `json:"evidence,omitempty"`
	Publication *Publication `json:"publication,omitempty"`
}

type ReconciliationPolicy added in v0.91.6 

type ReconciliationPolicy struct {
	MaxAttempts int   `json:"max_attempts"`
	DeadlineMS  int64 `json:"deadline_ms"`
}

type RemediationVerifier added in v0.91.6 

type RemediationVerifier func(context.Context, Projection, WorkDefinition) error

RemediationVerifier validates domain-specific idempotence, compensation, or inspection-only scope before replacing a node with partial/unknown effects.

type Replacement added in v0.91.6 

type Replacement struct {
	WorkID      string `json:"work_id"`
	Disposition string `json:"disposition"`
	Evidence    string `json:"evidence"`
}

type Request added in v0.91.6 

type Request struct {
	ID          string          `json:"id"`
	Kind        string          `json:"kind"`
	Parameters  json.RawMessage `json:"parameters"`
	Fingerprint string          `json:"fingerprint"`
}

func NewRequest added in v0.91.6 

func NewRequest(id, kind string, actor Actor, parameters any) (Request, error)

type RequestExplanation added in v0.91.6 

type RequestExplanation struct {
	Tip         string             `json:"tip"`
	At          int64              `json:"at"`
	Status      string             `json:"status"`
	RequestID   string             `json:"request_id"`
	CommitID    string             `json:"commit_id"`
	Kind        string             `json:"kind"`
	PolicyEpoch string             `json:"policy_epoch"`
	Claims      []ClaimExplanation `json:"claims"`
}

func ExplainRequest added in v0.91.6 

func ExplainRequest(commits []QueueCommit, requestID string) (RequestExplanation, error)

type Resource added in v0.91.6 

type Resource struct {
	Kind         string `json:"kind"`
	Host         string `json:"host"`
	Repository   string `json:"repository"`
	RepositoryID string `json:"repository_id"`
	ResourceID   string `json:"resource_id"`
	Number       string `json:"number"`
}

type ResultReference added in v0.91.6 

type ResultReference struct {
	WorkID         string          `json:"work_id"`
	ResultCommitID string          `json:"result_commit_id"`
	Descriptor     json.RawMessage `json:"descriptor"`
}

type RetryPolicy added in v0.91.6 

type RetryPolicy struct {
	MaxAttempts int   `json:"max_attempts"`
	BackoffMS   int64 `json:"backoff_ms"`
}

type RunBinding added in v0.91.6 

type RunBinding struct {
	RunID      string `json:"run_id"`
	RunAttempt int    `json:"run_attempt"`
	Repository string `json:"repository"`
	Workflow   string `json:"workflow"`
	Ref        string `json:"ref"`
	Principal  string `json:"principal"`
	Event      string `json:"event"`
}

type Selection added in v0.91.6 

type Selection struct {
	WorkID       string   `json:"work_id,omitempty"`
	Reason       string   `json:"reason"`
	Observations []string `json:"observations"`
	ClassPass    string   `json:"class_pass,omitempty"`
	KeyPass      string   `json:"key_pass,omitempty"`
}

func PlanNext added in v0.91.6 

func PlanNext(state Projection, pool string, at int64) (Selection, error)

PlanNext does not change clocks, active sets, reservations, or ownership.

type Settings 

type Settings struct {
	Mode              string                  `json:"mode"`
	ClassWeights      []int                   `json:"class_weights"`
	AccountingWeights map[string]int          `json:"accounting_weights"`
	Concurrency       int                     `json:"concurrency"`
	PendingLimit      int                     `json:"pending_limit"`
	Retry             SettingsRetry           `json:"retry"`
	Pools             map[string]PoolSettings `json:"pools"`
	Issues            *IssuesSettings         `json:"issues,omitempty"`
}

Settings contains scheduling and optional Issues projection preferences, never queue authorization or routes. ParseSettings accepts the raw work_queue property from .github/workflows/aw.json.

func ParseRepositorySettings 

func ParseRepositorySettings(data []byte) (Settings, error)

ParseRepositorySettings extracts only work_queue; other aw.json properties are owned by the repository configuration parser.

func ParseSettings 

func ParseSettings(data []byte) (Settings, error)

ParseSettings resolves omitted preferences to the ordinary singleton queue defaults. A missing section is nil/empty bytes; explicit null or malformed input is an error.

func (Settings) Apply 

func (settings Settings) Apply(policy Policy) (Policy, error)

Apply copies only scheduling preferences onto host-approved policy routes. Issues preferences remain available to the host and never enroll projectors. Additional scheduling pools inherit the approved default pool; no profile authority is authored. Full policy validation remains the host's responsibility after binding templates.

type SettingsRetry 

type SettingsRetry struct {
	MaxAttempts    int `json:"max_attempts"`
	BackoffSeconds int `json:"backoff_seconds"`
}

type Stats 

type Stats struct {
	Work         int `json:"work"`
	Available    int `json:"available"`
	Claimed      int `json:"claimed"`
	Completed    int `json:"completed"`
	Cancelled    int `json:"cancelled"`
	Claims       int `json:"claims"`
	Dispatches   int `json:"dispatches"`
	Transactions int `json:"transactions"`
	Nodes        int `json:"nodes"`
}

type SubmitParameters added in v0.91.6 

type SubmitParameters struct {
	Nodes []WorkDefinition `json:"nodes"`
}

type Trace added in v0.91.6 

type Trace struct {
	TraceID          string `json:"trace_id,omitempty"`
	SpanID           string `json:"span_id,omitempty"`
	PublisherAttempt int    `json:"publisher_attempt,omitempty"`
}

type TraceEvent added in v0.91.6 

type TraceEvent struct {
	Position            Position        `json:"position"`
	CommitID            string          `json:"commit_id"`
	Previous            *string         `json:"previous"`
	RequestID           string          `json:"request_id"`
	RequestKind         string          `json:"request_kind"`
	PolicyEpoch         string          `json:"policy_epoch"`
	At                  int64           `json:"at"`
	Actor               Actor           `json:"actor"`
	Kind                string          `json:"kind"`
	Pool                string          `json:"pool,omitempty"`
	WorkerProfile       string          `json:"worker_profile,omitempty"`
	Profile             *WorkerProfile  `json:"profile,omitempty"`
	ExpectedRef         string          `json:"expected_ref,omitempty"`
	ExpectedContract    string          `json:"expected_contract,omitempty"`
	Available           *bool           `json:"available,omitempty"`
	Activate            *bool           `json:"activate,omitempty"`
	LogicalContract     string          `json:"logical_contract,omitempty"`
	AdmissionContract   string          `json:"admission_contract,omitempty"`
	ExecutionRef        string          `json:"execution_ref,omitempty"`
	WorkID              string          `json:"work_id,omitempty"`
	ClaimID             string          `json:"claim_id,omitempty"`
	DispatchID          string          `json:"dispatch_id,omitempty"`
	CredentialPrincipal string          `json:"credential_principal,omitempty"`
	ClaimHandle         string          `json:"claim_handle,omitempty"`
	CompletionID        string          `json:"completion_id,omitempty"`
	KeepOpen            bool            `json:"keep_open,omitempty"`
	State               string          `json:"state,omitempty"`
	Reason              string          `json:"reason,omitempty"`
	Disposition         string          `json:"disposition,omitempty"`
	Control             string          `json:"control,omitempty"`
	Value               json.RawMessage `json:"value,omitempty"`
	ObservationID       string          `json:"observation_id,omitempty"`
	Observations        []string        `json:"observations,omitempty"`
	Run                 *RunBinding     `json:"run,omitempty"`
	RunID               string          `json:"run_id,omitempty"`
	RunAttempt          int             `json:"run_attempt,omitempty"`
	Evidence            *TraceEvidence  `json:"evidence,omitempty"`
	Trace               *Trace          `json:"trace,omitempty"`
}

type TraceEvidence added in v0.91.6 

type TraceEvidence struct {
	Kind       string `json:"kind"`
	Source     string `json:"source"`
	CheckedAt  int64  `json:"checked_at"`
	Repository string `json:"repository"`
	Workflow   string `json:"workflow"`
	Ref        string `json:"ref"`
	Principal  string `json:"principal"`
	RunID      string `json:"run_id,omitempty"`
	RunAttempt int    `json:"run_attempt,omitempty"`
	Status     string `json:"status,omitempty"`
	Conclusion string `json:"conclusion,omitempty"`
	Effects    string `json:"effects,omitempty"`
	Attempts   int    `json:"attempts,omitempty"`
}

type TraceOptions added in v0.91.6 

type TraceOptions struct {
	RequestID string
	ClaimID   string
	Offset    int
	Limit     int
}

type TracePage added in v0.91.6 

type TracePage struct {
	Tip               string       `json:"tip"`
	At                int64        `json:"at"`
	Status            string       `json:"status"`
	TraceAvailability string       `json:"trace_availability"`
	RequestID         string       `json:"request_id,omitempty"`
	ClaimID           string       `json:"claim_id,omitempty"`
	Offset            int          `json:"offset"`
	Limit             int          `json:"limit"`
	TotalEvents       int          `json:"total_events"`
	NextOffset        *int         `json:"next_offset,omitempty"`
	Events            []TraceEvent `json:"events"`
}

func TraceQueue added in v0.91.6 

func TraceQueue(commits []QueueCommit, options TraceOptions, at int64) (TracePage, error)

TraceQueue exposes bounded ledger provenance, never payloads, descriptors, receipt contents or request parameters. Missing telemetry does not lose facts.

type WorkDefinition added in v0.91.6 

type WorkDefinition struct {
	Kind             string          `json:"kind"`
	WorkID           string          `json:"work_id"`
	GraphID          string          `json:"graph_id"`
	NodeKey          string          `json:"node_key"`
	Pool             string          `json:"pool"`
	Priority         int             `json:"priority"`
	FairnessKey      string          `json:"fairness_key"`
	WorkerProfile    string          `json:"worker_profile"`
	LogicalContract  string          `json:"logical_contract,omitempty"`
	ExecutionRef     string          `json:"execution_ref,omitempty"`
	BatchTrustDomain string          `json:"batch_trust_domain"`
	Payload          json.RawMessage `json:"payload"`
	DependsOn        []Dependency    `json:"depends_on"`
	Enqueued         int64           `json:"enqueued"`
	Subject          *Resource       `json:"subject,omitempty"`
	BackingIssue     *Resource       `json:"backing_issue,omitempty"`
	ReplacementOf    *Replacement    `json:"replacement_of,omitempty"`
}

func NewChildWork added in v0.91.6 

func NewChildWork(state Projection, actor Actor, payload []byte, nodeKey string, at int64) (WorkDefinition, error)

func NewWork added in v0.90.4 

func NewWork(payload []byte, graphID, nodeKey, pool string, policy Policy, at int64) (WorkDefinition, error)

type WorkExplanation added in v0.91.6 

type WorkExplanation struct {
	WorkID             string   `json:"work_id"`
	State              string   `json:"state"`
	Barrier            string   `json:"barrier"`
	Ready              bool     `json:"ready"`
	SchedulingEligible bool     `json:"scheduling_eligible"`
	Reason             string   `json:"reason"`
	Path               []string `json:"path"`
	Observations       []string `json:"observations"`
}

func ExplainWork added in v0.91.6 

func ExplainWork(state Projection, id string, at int64) (WorkExplanation, error)

type WorkState 

type WorkState struct {
	WorkDefinition
	AdmissionContract    string          `json:"admission_contract,omitempty"`
	EffectivePriority    int             `json:"effective_priority,omitempty"`
	State                string          `json:"state"`
	Position             Position        `json:"position"`
	ClaimID              string          `json:"claim_id,omitempty"`
	Attempts             int             `json:"attempts"`
	RetryNotBefore       int64           `json:"retry_not_before"`
	CompletionID         string          `json:"completion_id,omitempty"`
	Barrier              string          `json:"barrier"`
	Result               json.RawMessage `json:"result,omitempty"`
	ResultCommitID       string          `json:"result_commit_id,omitempty"`
	Disposition          string          `json:"disposition,omitempty"`
	CancellationReason   string          `json:"cancellation_reason,omitempty"`
	CancellationClaimID  string          `json:"cancellation_claim_id,omitempty"`
	CancellationCommitID string          `json:"cancellation_commit_id,omitempty"`
	IssueLink            *Resource       `json:"issue_link,omitempty"`
	IssueSummary         string          `json:"issue_summary,omitempty"`
	// contains filtered or unexported fields
}

func (*WorkState) SchedulingPriority added in v0.91.6 

func (work *WorkState) SchedulingPriority() int

SchedulingPriority leaves the admitted definition and historical Claims immutable.

type WorkerDeployment 

type WorkerDeployment struct {
	CurrentRef      string                    `json:"current_ref"`
	CurrentContract string                    `json:"current_contract"`
	Revisions       map[string]WorkerRevision `json:"revisions"`
}

type WorkerProfile added in v0.91.6 

type WorkerProfile struct {
	LogicalContract string `json:"logical_contract,omitempty"`
	Workflow        string `json:"workflow"`
	Ref             string `json:"ref"`
	Principal       string `json:"principal,omitempty"`
	TrustDomain     string `json:"trust_domain"`
	CredentialScope string `json:"credential_scope"`
	EffectScope     string `json:"effect_scope"`
	MaxClaims       int    `json:"max_claims"`
	ShareKeys       bool   `json:"share_keys"`
}

type WorkerRevision 

type WorkerRevision struct {
	Profile   WorkerProfile `json:"profile"`
	Available bool          `json:"available"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.