controlplane

type Action string

type Command struct {
	// CommandID is an optional bounded operation identity; Service/Journal
	// generate it when absent.
	CommandID string
	// IdempotencyKey is the required tenant-scoped duplicate/conflict key, not
	// authorization.
	IdempotencyKey string
	// TenantID is required bounded scope; a trusted ingress must authenticate
	// and authorize it.
	TenantID string
	// Actor is required bounded attribution; authenticated ingress owns its
	// binding to a principal.
	Actor string
	// AuthenticationMethod is optional bounded audit attribution; orchestration
	// defaults it to internal, without authenticating anyone.
	AuthenticationMethod string
	// Reason is required nonblank audit text bounded by MaxReasonBytes; callers
	// must omit credentials.
	Reason string
	// Action selects a supported mutation and its required
	// target/confirmation/options.
	Action Action
	// Capability is optional bounded audit attribution; orchestration defaults
	// it to the action text.
	Capability string
	// Target identifies the scoped resource; action/target combinations are
	// validated.
	Target Target
	// RequestedAt is required and anchors the enforcement lifetime; validation
	// does not replace caller time.
	RequestedAt time.Time
	// Deadline is optional; orchestration defaults it to RequestedAt plus
	// DefaultCommandLifetime, and supplied values must follow RequestedAt
	// within MaxCommandLifetime.
	Deadline time.Time
	// Confirmed must be true for purge, bulk retry, replay and scaling to zero.
	Confirmed bool
	// Selection is required for bulk retry; its pointer remains caller-owned
	// outside explicit copying boundaries.
	Selection *Selection
	// Replay is required for replay, including an explicit destination and
	// duplicate policy.
	Replay *Replay
	// Scale is required for scaling; zero replicas additionally require
	// confirmation.
	Scale *Scale
}

type CommandResult struct {
	// CommandID is an optional bounded operation identity retained for legacy
	// result compatibility.
	CommandID string `json:"command_id"`
	// IdempotencyKey is the required scoped journal lookup key.
	IdempotencyKey string `json:"idempotency_key"`
	// TenantID is the required bounded journal scope.
	TenantID string `json:"tenant_id"`
	// Status selects a validated lifecycle state; a returned unknown result
	// need not itself have been durably saved.
	Status CommandStatus `json:"status"`
	// Failure is required bounded nonblank text for unsuccessful terminal
	// states and absent otherwise; use secret-safe public codes.
	Failure string `json:"failure,omitempty"`
	// WorkerID is optional bounded acknowledgement attribution and must
	// accompany Protocol.
	WorkerID string `json:"worker_id,omitempty"`
	// Protocol is optional worker protocol attribution; when present its major
	// must be nonzero and WorkerID must be present.
	Protocol *ProtocolVersion `json:"protocol,omitempty"`
	// CapabilityAvailable optionally distinguishes a reported capability from
	// an unspecified acknowledgement; nil means not supplied.
	CapabilityAvailable *bool `json:"capability_available,omitempty"`
	// DispatchedAt records the pre-dispatch boundary, not proof that a backend
	// accepted the operation.
	DispatchedAt time.Time `json:"dispatched_at,omitempty"`
	// AcknowledgedAt records acknowledgement after dispatch;
	// accepted/pending/dispatched states may not carry it.
	AcknowledgedAt time.Time `json:"acknowledged_at,omitempty"`
	// CompletedAt is required for terminal states and absent before completion.
	CompletedAt time.Time `json:"completed_at,omitempty"`
}

type CommandStatus string

type Permission string

type ProtocolVersion struct {
	// Major is the nonzero major identity required when attached to a
	// CommandResult.
	Major uint16 `json:"major"`
	// Minor is the worker's reported minor protocol revision.
	Minor uint16 `json:"minor"`
}

type Replay struct {
	// Destination is a required nonblank queue identity; Service separately
	// authorizes this destination.
	Destination string
	// IdempotencyPolicy must explicitly select rejection or replacement of
	// destination duplicates.
	IdempotencyPolicy ReplayPolicy
}

type ReplayPolicy string

type Scale struct {
	// Replicas is at most MaxScaleReplicas; zero requires command confirmation.
	Replicas uint32
}

type Selection struct {
	// Limit must be positive and at most MaxBulkSelection; it is a per-command
	// selection bound.
	Limit uint32
}

type SensitiveAccess struct {
	// CommandID is a required bounded identity linking this privileged access
	// to its audit record.
	CommandID string
	// TenantID is required tenant scope; the record itself does not
	// authenticate it.
	TenantID string
	// Actor is required bounded authenticated attribution supplied by ingress.
	Actor string
	// Permission must be PermissionPayloadView or PermissionDiagnosticsView.
	Permission Permission
	// Target must identify a bounded failure or dead-letter record.
	Target Target
	// OccurredAt is required observation time for the privileged access.
	OccurredAt time.Time
}

type Target struct {
	// Kind selects the resource class; supported classes depend on the action.
	Kind TargetKind
	// Name is required nonblank identity text bounded by MaxIdentityBytes;
	// validation does not trim it.
	Name string
}

type TargetKind string

type ValidationError struct {
	// Field names the invalid input boundary and is printed by Error; keep
	// labels non-sensitive.
	Field string
	// Problem is printed by Error; use rule descriptions rather than rejected
	// values.
	Problem string
}