shared

package
v0.14.0 Latest Latest
Warning

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

 Go to latest Published: Oct 28, 2026 License: Apache-2.0 Imports: 50 Imported by: 0

Documentation

Overview

Package shared provides backend-agnostic components that can be reused across different backend implementations (Docker, Kubernetes, Nomad, etc.).

What lives here

  • SKUProfile and the shared SKU types (types.go), and ResourcePool and ResourceStats (resources.go) — the resource pool primitives used by every backend that tracks CPU/memory/disk
  • Registry helpers (registry.go) — image-registry parsing + allowlist validation (ParseRegistry, IsImageAllowed, ValidateImage) used by substrate adapters to enforce the backend's configured registry allowlist
  • The identity-bound authoritative journals, each embedding the private boltStore (bolt_store.go): CallbackStore (callbacks.go) holds the operation, maintenance and close intents, the per-lease callback outbox and the compact terminal receipts; ReleaseStore (releases.go) holds release history with typed or legacy runtime authority; RetentionStore (retention.go) holds retained-volume records. DiagnosticsStore (diagnostics.go) persists failure diagnostics for leases no longer in memory.
  • Settlement capabilities bound to one exact journal pair, the only way to change that authority: OperationSettlement, MaintenanceSettlement, CloseSettlement, RestoreSettlement and ReleaseBackfiller, plus RecoveryCoordinator for lease-scoped recovery
  • CallbackPublisher (callback_publisher.go) — commits each operation and maintenance result and its outbox entry in one transaction (close results commit through CloseSettlement); CallbackSender (callback_sender.go) only signs, delivers and replays rows that are already durable

All of these are consumed by the docker backend and are usable by any future in-process backend (Kubernetes, Nomad, etc.). An HTTP-only backend in a separate process implements the same callback contract (BACKEND_GUIDE.md) with its own durable outbox; CallbackSender requires an identity-bound CallbackStore, so it cannot be reused on its own.

Index

Constants

View Source 
const (
	// Diagnostic logs retain the same aggregate budget as the Docker log API.
	// The independent encoded budget also bounds JSON escaping and metadata.
	MaxFailureDiagnosticLogBytes     = backend.MaxLogContentBytes
	MaxFailureDiagnosticEncodedBytes = 40 << 20
)
View Source 
const (
	// CallbackMaxAttempts is the number of times to attempt callback delivery.
	CallbackMaxAttempts = 3

	// DefaultCallbackReplayInterval bounds how long an exhausted callback stays
	// dormant while the backend process remains up.
	DefaultCallbackReplayInterval = 30 * time.Second
)
View Source 
const (
	PartitionReasonNoInput    = "no_input"    // manifest nil/empty after hydration
	PartitionReasonDivergent  = "divergent"   // carrying services disagree
	PartitionReasonInvalid    = "invalid"     // value fails NormalizePartition
	PartitionReasonOverLimit  = "over_limit"  // produced by the write-time bound (next phase)
	PartitionReasonStoreError = "store_error" // produced by the write-time bound (next phase)
)

Collapse reasons — the CLOSED label set of the partition-collapse metric. Declared here (not in the docker package) so extraction and the write-time bound share one vocabulary. "" means "did not collapse" (either a valid partition or the silent not-declared default).

View Source 
const ImageInspectionCreationStep = "create image inspection helper"
View Source 
const MaintenanceSourceLaunchStep = "settle frozen compensation source effects"
View Source 
const MaintenanceTargetLaunchStep = "launch prepared managed compose project"

MaintenanceTargetLaunchStep names the sole concrete effect whose receipt can authorize compensation. Image helper or other mutation receipts cannot.

View Source 
const RetentionStatusActive = "active"

RetentionStatusActive is the status of an active (held) retention entry.

View Source 
const RetentionStatusReaping = "reaping"

RetentionStatusReaping marks a record whose volumes are pending physical destruction: the bytes are still on disk (so the footprint must keep counting in the admission projection) but the record is NOT restore-claimable. It is a finalizer tombstone — kept until every volume is confirmed destroyed, then Delete()d. See ENG-376.

View Source 
const RetentionStatusRestoring = "restoring"

RetentionStatusRestoring is the status of an entry currently being restored.

Variables

View Source 
var (

	// ErrStoreIdentityUnbound means an authoritative database predates the
	// storage-lineage seal (or was replaced by an unbound file). Only the explicit
	// pending initializer may add the binding; ordinary startup must fail closed.
	ErrStoreIdentityUnbound = errors.New("authoritative backend store is not bound to storage identity")

	// ErrStoreIdentityMismatch means a bound database belongs to another storage
	// generation or another authoritative store role.
	ErrStoreIdentityMismatch = errors.New("authoritative backend store identity mismatch")
)
View Source 
var (
	// ErrNoRetention is returned when no retained data exists for a given lease UUID.
	ErrNoRetention = errors.New("no retained data for lease")
	// ErrNotRestorable is returned when a retained lease is not in a restorable state.
	ErrNotRestorable = errors.New("retained lease not in a restorable state")
	// ErrLegacyRestoringRetention means an unbound v0.13 retention journal still
	// contains a restore whose outcome was not resolved by the v0.13 reconciler.
	// Current destination authority cannot be reconstructed from that wire shape,
	// so storage-lineage adoption must stop before publishing a binding.
	ErrLegacyRestoringRetention = errors.New("v0.13 retention journal contains an unresolved restoring record")
)
View Source 
var (

	// ErrCallbackIntentRequired means a caller tried to enqueue exact causal
	// evidence without atomically transitioning the durable intent that
	// authorized it. Semantic publication must cross CallbackPublisher; the raw
	// journal write is package-private.
	ErrCallbackIntentRequired = errors.New("exact callback requires durable intent settlement")
)
View Source 
var ErrCloseAuthorityMissing = errors.New("close has no durable cleanup authority")

ErrCloseAuthorityMissing means neither release history nor an operation journal can authorize destructive close work. Cleanup-only callers may treat this as an effect-free absence; projected closes must fail closed.

View Source 
var ErrCloseIntentConflict = errors.New("unresolved callback close intent")

ErrCloseIntentConflict means a lease already has an unresolved close whose immutable input differs from the requested close. The existing intent is preserved; callers must not perform cleanup for the conflicting request.

View Source 
var ErrDiskAccountingIncomplete = errors.New("disk capacity is withheld while a footprint of unknown size remains")

ErrDiskAccountingIncomplete refuses a disk-bearing allocation while a footprint whose size is not yet known remains on disk. It is a capacity refusal, not a fault: allocations that need no disk stay admissible.

View Source 
var ErrFailedMaintenanceReceiptGone = errors.New("failed-maintenance cleanup receipt is no longer durable")

ErrFailedMaintenanceReceiptGone means the receipt left the journal after it was listed: evicted from the window once its cleanup was confirmed, or taken by a lease close. Its cleanup authority went with it.

View Source 
var ErrLeaseMutationCapacity = errors.New("callback lease mutation UUID capacity exhausted")

ErrLeaseMutationCapacity is a definitive pre-side-effect refusal. The journal cannot safely accept another never-reusable lease UUID while keeping every closed-lease tombstone permanent.

View Source 
var ErrMaintenanceExpired = errors.New("maintenance command is older than the lease's retained history")

ErrMaintenanceExpired is a pre-side-effect refusal: a provider restart or update is older than this lease's admission high-water mark, so its receipt may have left the rolling window. Executing it could move the lease backward; it is refused instead of being treated as new work.

View Source 
var ErrMaintenanceIntentConflict = errors.New("unresolved callback maintenance intent")
View Source 
var ErrMaintenanceReceiptCapacity = errors.New("maintenance receipt capacity exhausted")

ErrMaintenanceReceiptCapacity is a pre-side-effect refusal: the backend cannot accept another maintenance generation without dropping a receipt it must keep. That happens for an unstamped command from an older provider at a full window, which cannot be ordered against the history, or for a window full of failed receipts whose late-container cleanup is unconfirmed.

View Source 
var ErrMaintenanceReleaseClaimRequired = errors.New("maintenance release requires exact claim")

ErrMaintenanceReleaseClaimRequired marks a raw release-store mutation that attempted to bypass the exact MaintenanceReleaseClaim API. Maintenance rows are causal authority and may only be appended or transitioned by the typed methods in this file.

View Source 
var ErrOperationIntentConflict = errors.New("unresolved callback operation intent")

ErrOperationIntentConflict means a lease already has an unresolved durable operation. The existing intent is preserved; callers must not mutate the substrate for the conflicting request.

View Source 
var ErrOperationIntentMissing = errors.New("callback operation intent missing")

ErrOperationIntentMissing means an exact operation has no durable journal state. Manufacturing completion evidence after its write-ahead authority disappeared would let a stale worker settle a newer or already-closed lease generation, so absence never implies success or failure.

View Source 
var ErrOperationReceiptCapacity = errors.New("operation receipt capacity exhausted")

ErrOperationReceiptCapacity identifies a new asynchronous operation that cannot reserve its permanent replay fence. Admission fails before any substrate mutation, so backend HTTP handlers may safely return the coded insufficient-resources verdict that providerd treats as a definitive refusal of this exact attempt.

View Source 
var ErrOperationReleaseConflict = errors.New("operation release conflicts with durable history")

ErrOperationReleaseConflict means an operation token already appears in release history but no longer denotes the exact active generation this candidate would publish. Replaying it must never reactivate or duplicate an older operation.

View Source 
var ErrReleaseHistoryCapacity = errors.New("release history capacity exceeded")

ErrReleaseHistoryCapacity identifies a release-history write whose load-bearing records cannot fit within the authoritative per-lease byte contract. Callers may safely treat this as a definitive pre-admission refusal only when it is returned by a Check*Capacity method; a write after a substrate mutation still has an ambiguous outcome until durable recovery proves otherwise.

View Source 
var ErrResourceAccountingIncomplete = errors.New("resource capacity is withheld while an unaccounted substrate footprint remains")
View Source 
var ErrVolumeLaunchUnsettled = errors.New("physical volume has an unsettled Docker launch")

ErrVolumeLaunchUnsettled means Docker may still accept an earlier Create or Start using these physical directories. Inventory absence and a stopped container cannot revoke an outstanding daemon request.

View Source 
var PartitionCollapseReasons = []string{
	PartitionReasonNoInput, PartitionReasonDivergent, PartitionReasonInvalid,
	PartitionReasonOverLimit, PartitionReasonStoreError,
}

PartitionCollapseReasons is the full closed set, exported for metric pre-initialization.

Functions

func BindCloseSubstrateExecutor added in v0.14.0 

func BindCloseSubstrateExecutor[T any](
	s *CloseSettlement,
	authorize substratemutation.Authorize,
	complete substratemutation.Complete,
	build func(substratemutation.Runner, ClosePhysicalSubject) T,
	run func(context.Context, T, ClosePhysicalSubject) error,
	classify func(context.Context, ClosePhysicalSubject) (ClosePhysicalEvidence, error),
) error

BindCloseSubstrateExecutor atomically binds the only live close workflow and its restart classifier to this exact journal set. The builder alone receives Runner, and both functions receive the journal-minted subject, so callers can neither inject a mutator nor substitute physical targets at execution time.

func BindMaintenanceCompensationExecutor added in v0.14.0 

func BindMaintenanceCompensationExecutor[T any](
	s *MaintenanceSettlement,
	authorize substratemutation.Authorize,
	complete substratemutation.Complete,
	capture func(context.Context, MaintenancePhysicalSubject) (MaintenanceSourceCapture, error),
	validate func(MaintenancePhysicalSubject, []byte) error,
	build func(substratemutation.Runner, MaintenanceCompensationSubject) T,
	run func(context.Context, T, MaintenanceCompensationSubject) error,
	classify func(context.Context, MaintenanceCompensationSubject) (MaintenancePhysicalEvidence, error),
) error

BindMaintenanceCompensationExecutor binds source capture, strict plan decoding, execution and classification together. There is no caller-supplied rollback closure at admission or recovery, and no use of cleanup authority to launch.

func BindMaintenanceSubstrateExecutor added in v0.14.0 

func BindMaintenanceSubstrateExecutor[T any](
	s *MaintenanceSettlement,
	authorize substratemutation.Authorize,
	complete substratemutation.Complete,
	build func(substratemutation.Runner, MaintenancePhysicalSubject) T,
	run func(context.Context, T, MaintenancePhysicalSubject) error,
	classify func(context.Context, MaintenancePhysicalSubject) (MaintenancePhysicalEvidence, error),
) error

BindMaintenanceSubstrateExecutor atomically binds one narrow maintenance facade and its construction-fixed exhaustive classifier. The paired restart attestor never escapes the settlement.

func BindOperationFindingExecutor added in v0.14.0 

func BindOperationFindingExecutor[T any, F any](
	s *OperationSettlement,
	authorize substratemutation.Authorize,
	complete substratemutation.Complete,
	build func(substratemutation.Runner, OperationPhysicalSubject) T,
	run func(context.Context, T, OperationPhysicalSubject) (substratemutation.Accepted[F], error),
	classify func(context.Context, OperationPhysicalSubject, substratemutation.Accepted[F]) (OperationPhysicalEvidence, error),
) error

BindOperationFindingExecutor binds a facade whose live workflow may report a typed Finding: a definite outcome it observed after its effects, accepted by its own session before any work that depends on it. The construction-bound classifier receives the Finding only from a wholly successful session and alone decides whether it becomes evidence (ENG-1125). Recovery never sees one.

func BindOperationSubstrateExecutor added in v0.14.0 

func BindOperationSubstrateExecutor[T any](
	s *OperationSettlement,
	authorize substratemutation.Authorize,
	complete substratemutation.Complete,
	build func(substratemutation.Runner, OperationPhysicalSubject) T,
	run func(context.Context, T, OperationPhysicalSubject) error,
	classify func(context.Context, OperationPhysicalSubject) (OperationPhysicalEvidence, error),
) error

BindOperationSubstrateExecutor atomically binds one narrow physical facade and the construction-fixed exhaustive classifier to this settlement. The paired recovery attestor remains private; callers cannot choose a verdict at recovery time.

func CheckBoundCallbackStoreStorage added in v0.14.0 

func CheckBoundCallbackStoreStorage(
	path *BoundAuthoritativeStorePath,
	storage backendidentity.PendingStorage,
) error

CheckBoundCallbackStoreStorage verifies a prepared callback journal through its retained physical-parent capability.

func CheckBoundReleaseStoreStorage added in v0.14.0 

func CheckBoundReleaseStoreStorage(
	path *BoundAuthoritativeStorePath,
	storage backendidentity.PendingStorage,
) error

func CheckBoundRetentionStoreStorage added in v0.14.0 

func CheckBoundRetentionStoreStorage(
	path *BoundAuthoritativeStorePath,
	storage backendidentity.PendingStorage,
) error

func ExtractPartition added in v0.11.0 

func ExtractPartition(src PartitionSource, in PartitionInputs) (partition, reason, rawDetail string)

ExtractPartition derives the candidate partition for a closing lease from the configured source. Returns (partition, collapseReason, rawDetail):

  • ("", "", "") — not declared (source none, no service carries the key, or every carrier's value is empty/whitespace): the silent, normal state for every non-participating tenant.
  • (p, "", "") — exactly one distinct declared value, normalized.
  • ("", reason, det) — declared but unusable; the caller counts+logs and the record lands in the default bucket. det is already truncation-bounded (via TruncatePartitionRaw): the offending value (invalid) or the established value and the first divergent one (divergent) for the WARN line — it is the most-bounded form, so no caller may log anything rawer.

It CANNOT fail: there is no error return, which structurally enforces the never-fail-a-close invariant.

func IsImageAllowed 

func IsImageAllowed(image string, allowedRegistries []string) bool

IsImageAllowed checks if an image is from an allowed registry.

func IsLifecyclePending added in v0.14.0 

func IsLifecyclePending(err error) bool

IsLifecyclePending reports an exact journal/physical observation, never a refusal, terminal result, or permission to replace the outstanding request.

func IsOperationCompletionPending added in v0.14.0 

func IsOperationCompletionPending(err error) bool

IsOperationCompletionPending identifies the journal-authored FIFO diagnostic. It grants no refusal, replay, or lifecycle authority; the requested operation remains unresolved until exact callback settlement or reconciliation.

func NormalizePartition added in v0.11.0 

func NormalizePartition(raw string) (string, bool)

NormalizePartition validates a raw declared partition value: trimmed, 1..64 chars of [A-Za-z0-9._-]. ok=false means the value is unusable and MUST collapse to the default "" bucket. "" is deliberately unrepresentable as a valid value — it is exclusively the whole-tenant sentinel, so no declared value can collide with it. Case is PRESERVED (no folding): fragmentation from case variance is observable, whereas silent merging of intentionally-distinct IDs would be invisible.

func ParseRegistry 

func ParseRegistry(image string) (string, error)

ParseRegistry extracts the registry domain from a container image reference. Uses the distribution/reference library for robust parsing with Docker Hub normalization (e.g., "nginx" -> "docker.io").

func PrepareBoundCallbackStoreStorage added in v0.14.0 

func PrepareBoundCallbackStoreStorage(
	path *BoundAuthoritativeStorePath,
	storage backendidentity.PendingStorage,
	profile backendidentity.InitializationProfile,
) error

PrepareBoundCallbackStoreStorage binds a callback journal through a retained physical-parent capability and a pending authority minted only after the marker-pair anchor is durable.

func PrepareBoundReleaseStoreStorage added in v0.14.0 

func PrepareBoundReleaseStoreStorage(
	path *BoundAuthoritativeStorePath,
	storage backendidentity.PendingStorage,
	profile backendidentity.InitializationProfile,
) error

func PrepareBoundRetentionStoreStorage added in v0.14.0 

func PrepareBoundRetentionStoreStorage(
	path *BoundAuthoritativeStorePath,
	storage backendidentity.PendingStorage,
	profile backendidentity.InitializationProfile,
) error

func RejectCallbackRedirect added in v0.14.0 

func RejectCallbackRedirect(*http.Request, []*http.Request) error

RejectCallbackRedirect keeps an HMAC-signed callback bound to its exact configured destination. Following a 3xx could forward the POST body and signature to an attacker-controlled or internal URL, and the signature would no longer cover the redirected RequestURI.

func SumSKUResourceSnapshotDiskMB added in v0.14.0 

func SumSKUResourceSnapshotDiskMB(items []backend.LeaseItem, snapshot []SKUResourceSnapshot) (int64, error)

SumSKUResourceSnapshotDiskMB returns the exact durable, retainable disk footprint for items using only persisted snapshot authority. It deliberately excludes ScratchDiskMB; callers that model physical live capacity use EffectiveDiskMB, while retention accounting may add an exact conservatively retained scratch-volume name separately. It rejects invalid quantities, incomplete snapshots, and int64 overflow so corrupt durable data can never wrap a conservative accounting projection into the under-count direction.

func TruncatePartitionRaw added in v0.11.0 

func TruncatePartitionRaw(raw string) string

TruncatePartitionRaw bounds a tenant-supplied raw value for logging: the manifest imposes no per-value length cap (only the 1-2 MiB body caps), so a raw value can be ~1 MB. Structured slog quoting neutralizes control characters; this bounds size. NO log site may record the untruncated value.

func ValidateDistinctStorePaths added in v0.14.0 

func ValidateDistinctStorePaths(paths map[string]string) error

ValidateDistinctStorePaths rejects lexical, symlink-parent, and existing inode aliases before any authoritative file is created or opened. Names are used only for bounded operator diagnostics.

func ValidateImage 

func ValidateImage(image string, allowedRegistries []string) error

ValidateImage checks if an image reference is valid and allowed.

func ValidateSKUResourceSnapshot added in v0.14.0 

func ValidateSKUResourceSnapshot(items []backend.LeaseItem, snapshot []SKUResourceSnapshot) error

ValidateSKUResourceSnapshot verifies both the resource values and exact, canonical coverage of items. Empty items and an empty snapshot are a valid empty topology; durable owners that require a non-empty topology enforce that separately.

func VerifyBoundCallbackStoreStorage added in v0.14.0 

func VerifyBoundCallbackStoreStorage(
	path *BoundAuthoritativeStorePath,
	storage backendidentity.VerifiedStorage,
) error

VerifyBoundCallbackStoreStorage is the capability-bound committed-store verifier used before marker finalization.

func VerifyBoundReleaseStoreStorage added in v0.14.0 

func VerifyBoundReleaseStoreStorage(
	path *BoundAuthoritativeStorePath,
	storage backendidentity.VerifiedStorage,
) error

func VerifyBoundRetentionStoreStorage added in v0.14.0 

func VerifyBoundRetentionStoreStorage(
	path *BoundAuthoritativeStorePath,
	storage backendidentity.VerifiedStorage,
) error

func VerifyCallbackStoreStorage added in v0.14.0 

func VerifyCallbackStoreStorage(dbPath string, storage backendidentity.VerifiedStorage) error

func VerifyReleaseStoreStorage added in v0.14.0 

func VerifyReleaseStoreStorage(dbPath string, storage backendidentity.VerifiedStorage) error

func VerifyRetentionStoreStorage added in v0.14.0 

func VerifyRetentionStoreStorage(dbPath string, storage backendidentity.VerifiedStorage) error

Types

type ActiveRetentionCandidate added in v0.14.0 

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

ActiveRetentionCandidate is store-issued authority to attempt one destructive transition from one exact Active row. Candidates come only from the store's active selectors; a caller cannot turn a lease UUID or a detached inspection DTO into mutation authority. Every consumer re-attests the complete durable row, so a copied candidate cannot survive an ABA rewrite or store reopen.

This type is deliberately distinct from ActiveRetentionProof. The latter is close-settlement evidence minted only after physical retained-volume attestation and can complete a retained close; a pre-cleanup candidate cannot.

func (ActiveRetentionCandidate) Entry added in v0.14.0 

func (candidate ActiveRetentionCandidate) Entry() RetentionEntry

Entry returns a detached read DTO for policy checks and diagnostics. Mutating the result cannot alter the candidate or authorize another row.

func (ActiveRetentionCandidate) Valid added in v0.14.0 

func (candidate ActiveRetentionCandidate) Valid() bool

Valid reports whether the candidate has a complete opaque shape. It does not establish current authority; transition consumers always re-attest the row.

type ActiveRetentionProof added in v0.14.0 

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

ActiveRetentionProof is an opaque snapshot of one exact active retention record. A proof is useful only to the CloseSettlement bound to its issuing store; settlement re-reads the canonical bytes while holding both the per-lease transition gate and the retention store's read lock.

func (ActiveRetentionProof) RetainedVolumeNames added in v0.14.0 

func (proof ActiveRetentionProof) RetainedVolumeNames() []string

RetainedVolumeNames returns the detached exact volume cohort carried by this active-retention generation. It is observation-only input to the construction-bound physical classifier; terminal settlement re-attests the canonical row before accepting retained completion.

func (ActiveRetentionProof) Valid added in v0.14.0 

func (proof ActiveRetentionProof) Valid() bool

Valid reports whether the proof has a complete opaque shape. It does not establish durable liveness; CompleteClose performs that re-attestation.

type ActorCloseScope added in v0.14.0 

type ActorCloseScope interface {
	LeaseUUID() string
}

ActorCloseScope is the narrow observation surface accepted at the shared package boundary. Implementing it does not grant authority: the construction-bound validator must still prove leasesm's exact active actor value and coordinator lineage before a recovery scope is minted.

type AdoptInstance added in v0.11.0 

type AdoptInstance struct {
	ID  string
	SKU string
}

AdoptInstance identifies one container instance to reserve on the restore/adopt path: its pool allocation id and the SKU of the tier it is restored onto.

type BoundAuthoritativeStorePath added in v0.14.0 

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

BoundAuthoritativeStorePath retains the exact physical parent directory of one authority-bearing journal during a storage-lineage initialization. Its bbolt opens are descriptor-relative and do not follow a final-component symlink, so replacing the configured pathname cannot redirect an evidence read or identity-binding write into a different directory.

The zero value is invalid. Call Close after the complete proof-and- publication transaction, not after an individual store operation.

func BindAuthoritativeStorePath added in v0.14.0 

func BindAuthoritativeStorePath(dbPath string) (*BoundAuthoritativeStorePath, error)

BindAuthoritativeStorePath acquires a retained physical-parent capability for dbPath. Parent symlinks are resolved once before acquisition; all later filesystem operations use the retained descriptor rather than dbPath.

func (*BoundAuthoritativeStorePath) Close added in v0.14.0 

func (path *BoundAuthoritativeStorePath) Close() error

Close revokes the retained parent-directory capability.

func (*BoundAuthoritativeStorePath) VerifyPath added in v0.14.0 

func (path *BoundAuthoritativeStorePath) VerifyPath() error

VerifyPath proves that the acquisition pathname still names the retained physical parent directory.

type CallbackDeliveryKind added in v0.14.0 

type CallbackDeliveryKind string

CallbackDeliveryKind identifies whether a durable callback settles a requested operation or reports an autonomous lifecycle observation. The distinction is persisted so enqueue can safely coalesce stale lifecycle observations without ever deleting an undelivered operation completion for the same lease. 

const (
	// CallbackDeliveryKindOperation is an exact requested-operation
	// completion. Operation completions are independent durable deliveries and
	// are never removed by enqueue of another callback.
	CallbackDeliveryKindOperation CallbackDeliveryKind = "operation"

	// CallbackDeliveryKindMaintenance is an exact maintenance-derived fact
	// delivered through the lifecycle callback route. It covers the requested
	// restart/update/custom-domain completion and, when a committed target is
	// already lost, its paired runtime-failure fact. Both are causal barriers,
	// never coalescible observations, so later lifecycle activity cannot erase or
	// overtake either one.
	CallbackDeliveryKindMaintenance CallbackDeliveryKind = "maintenance"

	// CallbackDeliveryKindLifecycle is an observation-only lifecycle event.
	// Enqueueing a newer lifecycle observation atomically replaces older typed
	// lifecycle observations for the lease.
	CallbackDeliveryKindLifecycle CallbackDeliveryKind = "lifecycle"
)

type CallbackEntry 

type CallbackEntry struct {
	// MaintenanceID is present only on the exact maintenance completion, never
	// on a subsequent runtime-failure observation from that generation.
	MaintenanceID MaintenanceID `json:"maintenance_id,omitzero"`
	// MaintenanceAdmittedAt is that command's provider admission stamp, echoed
	// on the wire; zero for an unstamped command.
	MaintenanceAdmittedAt time.Time `json:"maintenance_admitted_at,omitzero"`
	// DeliveryID identifies this delivery inside its lease's durable v2 queue.
	// Writers allocate a random UUIDv4; precise storage authority is the lease,
	// delivery ID, and value digest together.
	DeliveryID  string `json:"delivery_id,omitempty"`
	LeaseUUID   string `json:"lease_uuid"`
	CallbackURL string `json:"callback_url"`
	// DeliveryKind is present on every runtime row.
	DeliveryKind CallbackDeliveryKind `json:"delivery_kind,omitempty"`
	// Sequence is allocated from bbolt in the same transaction as enqueue and
	// lifecycle coalescing. Every runtime row has a positive sequence encoded in
	// its durable key.
	Sequence uint64                 `json:"sequence,omitempty"`
	Status   backend.CallbackStatus `json:"status,omitempty"`
	Backend  string                 `json:"backend,omitempty"`
	// BackendStorageID is captured when a new callback is enqueued. Replays
	// preserve it exactly instead of restamping a queued observation with the
	// backend's current identity.
	BackendStorageID string `json:"backend_storage_id,omitempty"`
	Error            string `json:"error,omitempty"`
	// Retained persists the best-effort deprovision retain-success flag so a
	// restart-replayed callback keeps it.
	Retained  bool      `json:"retained,omitempty"`
	CreatedAt time.Time `json:"created_at"`
	// contains filtered or unexported fields
}

CallbackEntry represents a pending callback to be delivered. Status is the sole outcome representation: the v2 outbox is isolated from v0.13 readers, so persisting a second derived success bit would create contradictory states without providing rollback compatibility.

type CallbackPublisher added in v0.14.0 

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

CallbackPublisher is the construction-bound semantic boundary between backend outcomes and the durable callback journal. It owns exact operation and maintenance settlement authority; CallbackSender owns only replay and transport. The zero value is invalid.

Publication and settlement are one bbolt transaction under the callback store's per-lease gate. Transport subscribes to the store independently; semantic publication cannot invoke or depend on callback HTTP machinery.

func NewCallbackPublisher added in v0.14.0 

func NewCallbackPublisher(cfg CallbackPublisherConfig) (*CallbackPublisher, error)

NewCallbackPublisher constructs a publisher only when every dependency names the same exact open CallbackStore, ReleaseStore, storage identity, and backend-lifetime authority gate. Merely matching durable lineage is not sufficient after a store has been closed and reopened.

func (*CallbackPublisher) AuthorizeRuntimeObservationContext added in v0.14.0 

func (p *CallbackPublisher) AuthorizeRuntimeObservationContext(
	ctx context.Context,
	proof RuntimeGenerationProof,
) (RuntimeObservationPermit, error)

AuthorizeRuntimeObservationContext atomically observes the release journal and callback aggregate while holding their shared per-lease transition gate. It is the only constructor for RuntimeObservationPermit. Cancellation before the journal pair is attested creates no capability and changes no durable state.

func (*CallbackPublisher) PublishLifecycleFailureContext added in v0.14.0 

func (p *CallbackPublisher) PublishLifecycleFailureContext(
	ctx context.Context,
	permit RuntimeObservationPermit,
	errMsg string,
) error

PublishLifecycleFailureContext records the fixed observation-only Failed callback for an authorized runtime phase. RuntimeObservationPermit binds both the exact active release and the aggregate mutation head seen during authorization. Route, backend, storage identity, status, and retained=false are all derived after both facts are re-attested under the shared per-lease journal gate. Cancellation while waiting publishes nothing; the observation carries no requested-operation settlement which would otherwise need to complete during shutdown.

func (*CallbackPublisher) PublishMaintenanceFailureContext added in v0.14.0 

func (p *CallbackPublisher) PublishMaintenanceFailureContext(
	ctx context.Context,
	failed MaintenanceReleaseFailure,
	errMsg string,
) error

PublishMaintenanceFailureContext atomically settles an exact maintenance intent using proof that its target failed or was never appended. Cancellation leaves the exact failed release and maintenance head available to recovery.

func (*CallbackPublisher) PublishMaintenanceSuccessContext added in v0.14.0 

func (p *CallbackPublisher) PublishMaintenanceSuccessContext(
	ctx context.Context,
	active MaintenanceReleaseActive,
) error

PublishMaintenanceSuccessContext atomically settles an exact maintenance intent using proof that its target release remains active. Success is fixed by the proof type and cannot be caller-selected. Cancellation before settlement leaves the durable maintenance head for level-triggered recovery.

func (*CallbackPublisher) PublishOperationFailureContext added in v0.14.0 

func (p *CallbackPublisher) PublishOperationFailureContext(
	ctx context.Context,
	uncommitted OperationReleaseUncommitted,
	errMsg string,
) error

PublishOperationFailureContext atomically settles an exact provision/restore operation and publishes Failed. The proof establishes that its release was not committed; a success proof cannot be substituted. Cancellation leaves the durable operation head for level-triggered recovery.

func (*CallbackPublisher) PublishOperationSuccessContext added in v0.14.0 

func (p *CallbackPublisher) PublishOperationSuccessContext(
	ctx context.Context,
	committed OperationReleaseCommitted,
) error

PublishOperationSuccessContext atomically settles an exact provision/restore operation and publishes Success. The status, route, backend, and storage identity are all derived from the store-issued committed-release proof. Cancellation while waiting for the lease gate leaves the exact durable operation head for level-triggered recovery; it can never manufacture a failure or erase committed evidence.

func (*CallbackPublisher) TryPublishMaintenanceFailureContext added in v0.14.0 

func (p *CallbackPublisher) TryPublishMaintenanceFailureContext(
	ctx context.Context,
	failed MaintenanceReleaseFailure,
	errMsg string,
) (acquired bool, err error)

TryPublishMaintenanceFailureContext is the cancellation-aware non-blocking recovery form for an exact failed-or-absent target proof.

func (*CallbackPublisher) TryPublishMaintenanceRuntimeFailureContext added in v0.14.0 

func (p *CallbackPublisher) TryPublishMaintenanceRuntimeFailureContext(
	ctx context.Context,
	active MaintenanceReleaseActive,
	errMsg string,
) (acquired bool, err error)

TryPublishMaintenanceRuntimeFailureContext atomically publishes the successful completion of an already-committed maintenance command followed by the fixed Failed lifecycle observation for its now-divergent runtime. It is cancellation-aware and non-blocking on an owned lease gate.

func (*CallbackPublisher) TryPublishMaintenanceSuccessContext added in v0.14.0 

func (p *CallbackPublisher) TryPublishMaintenanceSuccessContext(
	ctx context.Context,
	active MaintenanceReleaseActive,
) (acquired bool, err error)

TryPublishMaintenanceSuccessContext is the cancellation-aware non-blocking recovery form. acquired is false only when another journal transition currently owns this lease.

type CallbackPublisherConfig added in v0.14.0 

type CallbackPublisherConfig struct {
	OperationSettlement   *OperationSettlement
	MaintenanceSettlement *MaintenanceSettlement
	StorageAttestor       *CallbackStorageAttestor
	Logger                *slog.Logger
	OnStoreError          func()
}

CallbackPublisherConfig binds semantic publication directly to the exact journals and their storage attestor. Sender/HTTP configuration is deliberately absent: publication commits facts, while a separately composed sender transports them.

type CallbackReceiptCapacity added in v0.14.0 

type CallbackReceiptCapacity struct {
	Reserved uint64
	Limit    uint64
}

CallbackReceiptCapacity is a point-in-time view of the shared durable operation/maintenance receipt budget. Unlike the permanent lease-UUID budget, successful close can reclaim these reservations after installing the stronger lease-wide closed receipt.

func (CallbackReceiptCapacity) Remaining added in v0.14.0 

func (capacity CallbackReceiptCapacity) Remaining() uint64

Remaining returns the number of operation or maintenance receipts that can still be reserved. It saturates at zero for diagnostic values assembled outside the store.

type CallbackSender 

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

CallbackSender transports and replays already-durable callbacks with bounded retry and HMAC authentication. It has no semantic settlement authority; CallbackPublisher owns publication into its outbox.

func MustNewCallbackSender added in v0.14.0 

func MustNewCallbackSender(cfg CallbackSenderConfig) *CallbackSender

MustNewCallbackSender is the explicit panic-on-programmer-error form. It is convenient in tests and static composition where the configuration is a literal; runtime backend constructors should use NewCallbackSender and propagate its error.

func NewCallbackSender 

func NewCallbackSender(cfg CallbackSenderConfig) (*CallbackSender, error)

NewCallbackSender creates a durable CallbackSender. The durable store, sufficiently strong signing secret, and physical storage identity are mandatory: asynchronous operation completions must not be constructible without their outbox and exact backend authority. Its lifecycle owner must start exactly one tracked RunReplayLoop before reporting ready, cancel the StorageAttestor lifecycle during shutdown, and join that loop before closing Store.

func (*CallbackSender) NotifyPendingCallbacks added in v0.14.0 

func (s *CallbackSender) NotifyPendingCallbacks()

NotifyPendingCallbacks asks the tracked replay loop to drain the durable outbox promptly. The notification is deliberately non-blocking and coalescing: the bbolt rows, not this in-memory signal, are the delivery authority, and the periodic sweep remains the fallback if no loop is running yet or another wake is already pending. This explicit request can retry an in-flight failed head once, in the retained lane. Ordinary commits and timer observations cannot carry that permission across a failed attempt.

func (*CallbackSender) RunReplayLoop added in v0.14.0 

func (s *CallbackSender) RunReplayLoop()

RunReplayLoop continuously schedules the durable callback outbox until the sender lifecycle context is canceled. At most callbackReplayWorkerLimit leases perform HTTP concurrently, and each worker yields after one delivered head. Unlike a sweep-wide worker batch, the scheduler keeps consuming commit wakes while those requests are in flight, so fresh healthy work cannot sit behind the complete cardinality of an outage backlog.

type CallbackSenderConfig 

type CallbackSenderConfig struct {
	// Store is the exact identity-bound outbox this transport drains.
	Store *CallbackStore
	// StorageAttestor binds Store to its runtime substrate verifier, storage
	// identity, authority gate, lifecycle, and finite verification budget.
	StorageAttestor *CallbackStorageAttestor
	HTTPClient      *http.Client
	Secret          string
	Logger          *slog.Logger
	OnDelivery      func(outcome string)                // optional metrics callback
	OnStoreError    func()                              // optional; called when bbolt persistence fails
	OnReplayPanic   func(any)                           // optional; called after recovering a lease replay panic
	Backoff         *[CallbackMaxAttempts]time.Duration // retry delays; nil uses default {0, 1s, 5s}
	DeliveryTimeout time.Duration                       // total delivery-attempt-chain budget; zero uses backend.DefaultCallbackDeliveryTimeout
	ReplayInterval  time.Duration                       // zero uses DefaultCallbackReplayInterval
}

CallbackSenderConfig configures a CallbackSender.

type CallbackStorageAttestor added in v0.14.0 

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

CallbackStorageAttestor is an opaque capability binding one runtime storage verifier to one exact, open callback journal instance. The zero value is invalid. The fixed timeout belongs to this capability so publication and transport cannot be configured with contradictory or unbounded probes.

func MustNewCallbackStorageAttestor added in v0.14.0 

func MustNewCallbackStorageAttestor(
	store *CallbackStore,
	verifier CallbackStorageVerifier,
	stopCtx context.Context,
) *CallbackStorageAttestor

MustNewCallbackStorageAttestor is the panic-on-programmer-error form for static backend composition and tests.

func NewCallbackStorageAttestor added in v0.14.0 

func NewCallbackStorageAttestor(
	store *CallbackStore,
	verifier CallbackStorageVerifier,
	stopCtx context.Context,
) (*CallbackStorageAttestor, error)

NewCallbackStorageAttestor constructs an exact-store callback authority. The verifier must report the same immutable storage identity and the same backend-lifetime commit gate captured by the journal when it was opened.

type CallbackStorageVerifier added in v0.14.0 

type CallbackStorageVerifier interface {
	StorageIdentity() backendidentity.ID
	StorageAuthorityGate() *backendidentity.StorageAuthorityGate
	Verify(context.Context) error
}

CallbackStorageVerifier re-attests one backend storage substrate. Its identity and authority gate are part of the proof: reporting only an ID is insufficient because two backend lifetimes may legitimately carry copied metadata while owning different fail-stop gates.

type CallbackStore 

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

CallbackStore persists pending callbacks in bbolt so they survive restarts.

func OpenIdentityBoundCallbackStore added in v0.14.0 

func OpenIdentityBoundCallbackStore(
	cfg CallbackStoreConfig,
	storage backendidentity.VerifiedStorage,
	gate *backendidentity.StorageAuthorityGate,
) (*CallbackStore, error)

OpenIdentityBoundCallbackStore opens an initialized authoritative journal without creating its file or binding. It may transactionally add empty, backward-compatible schema buckets after verifying the pre-existing core schema and storage identity. Cleanup is deferred until StartMaintenance so the whole backend store set can open first.

func (*CallbackStore) CallbackReceiptCapacity added in v0.14.0 

func (s *CallbackStore) CallbackReceiptCapacity() (CallbackReceiptCapacity, error)

CallbackReceiptCapacity returns the O(1) durable capacity counter shared by operation and maintenance receipt reservations. Healthy and stopped inspection additionally prove the counter equals the bounded history rows.

func (CallbackStore) Close 

func (s CallbackStore) Close() error

Close shuts down the store gracefully. It is idempotent: the first call closes the database and captures any error; subsequent calls return the same error.

func (*CallbackStore) GetCloseIntent added in v0.14.0 

func (s *CallbackStore) GetCloseIntent(leaseUUID string) (CloseIntentClaim, bool, error)

GetCloseIntent is a read-only diagnostic snapshot. The returned value is deliberately not bound to a CloseSettlement and therefore cannot authorize cleanup progress, release retirement, or terminal settlement.

func (*CallbackStore) Healthy 

func (s *CallbackStore) Healthy() error

Healthy checks both queue buckets and validates every durable row. Delivery quarantine is per identifiable lease, but any corruption keeps health red so an operator cannot miss preserved poison evidence. The embedded boltStore health check only knows its legacy bucket and cannot enforce that contract.

func (*CallbackStore) HealthyContext added in v0.14.0 

func (s *CallbackStore) HealthyContext(ctx context.Context) error

HealthyContext validates the current immutable store snapshot, cooperatively stopping between bounded records when the caller cancels. It never caches a healthy verdict or leaves a traversal running after it returns. Filesystem operations and bbolt read-transaction acquisition remain synchronous.

func (*CallbackStore) LeaseMutationUUIDCapacity added in v0.14.0 

func (s *CallbackStore) LeaseMutationUUIDCapacity() (LeaseMutationUUIDCapacity, error)

LeaseMutationUUIDCapacity returns the O(1) durable capacity counter used by runtime observability. Healthy and stopped inspection additionally walk the bounded marker set and prove this metadata equals its actual cardinality.

func (*CallbackStore) ListCloseIntents added in v0.14.0 

func (s *CallbackStore) ListCloseIntents() ([]CloseIntentClaim, error)

ListCloseIntents returns read-only diagnostic snapshots. Recovery code that needs usable capabilities must call CloseSettlement.ListCloseIntents.

func (*CallbackStore) ListPending 

func (s *CallbackStore) ListPending() ([]CallbackEntry, error)

ListPending returns all pending callback entries for durable outbox replay.

func (*CallbackStore) LookupClosedLeaseReceipts added in v0.14.0 

func (s *CallbackStore) LookupClosedLeaseReceipts(
	leaseUUIDs []string,
) ([]ClosedLeaseReceipt, error)

LookupClosedLeaseReceipts resolves only the requested lease heads in one read transaction. Recovery uses this instead of scanning the permanent closed history: closed UUIDs never expire, while cleanup work is needed only for UUIDs that currently have a live substrate or projection witness.

func (*CallbackStore) StartMaintenance added in v0.14.0 

func (s *CallbackStore) StartMaintenance()

StartMaintenance runs the initial expiry pass and starts the periodic loop exactly once.

func (CallbackStore) VerifyStorageIdentity added in v0.14.0 

func (s CallbackStore) VerifyStorageIdentity(storage backendidentity.VerifiedStorage) error

VerifyStorageIdentity proves that an authoritative store's configured path still names the exact regular file opened by the constructor and that the durable binding remains intact. This catches delete/rename/replacement while the process still holds a writable descriptor to the old inode.

type CallbackStoreConfig 

type CallbackStoreConfig struct {
	DBPath          string            // Path to bbolt database file
	MaxAge          time.Duration     // Max age for lifecycle observations; exact operation/maintenance completions never expire (0 = no expiry)
	CleanupInterval time.Duration     // How often to run cleanup (defaults to MaxAge)
	OnCleanupPanic  util.PanicHandler // Optional: invoked on cleanup-loop panic (e.g., bump a metric)
}

CallbackStoreConfig configures the callback store.

type CallbackStoreInspection added in v0.14.0 

type CallbackStoreInspection struct {
	Exists                          bool
	IdentityBound                   bool
	LegacySchema                    bool
	UpgradedSchema                  bool
	Pending                         int
	LeaseMutationUUIDSlots          uint64
	LeaseMutationUUIDSlotLimit      uint64
	CallbackReceiptReservations     uint64
	CallbackReceiptReservationLimit uint64
	// PendingHeads describes each pending lease-mutation head that Pending
	// counts (a pending operation, a maintenance, or a close), so a
	// substrate-aware reader can classify it further. It adds nothing to
	// Pending.
	PendingHeads []PendingLeaseMutationHead
}

CallbackStoreInspection is read-only schema/evidence used by explicit storage-lineage initialization and by the coordinated update's stopped drain proof.

func InspectBoundCallbackStoreReadOnly added in v0.14.0 

func InspectBoundCallbackStoreReadOnly(
	path *BoundAuthoritativeStorePath,
) (CallbackStoreInspection, error)

InspectBoundCallbackStoreReadOnly is the descriptor-relative form used by storage-lineage initialization after the journal's physical parent has been retained.

func InspectCallbackStoreReadOnly added in v0.14.0 

func InspectCallbackStoreReadOnly(dbPath string) (CallbackStoreInspection, error)

InspectCallbackStoreReadOnly inspects durable v0.13 and v2 outbox rows without creating a database, bucket, cleanup goroutine, or write transaction. Storage-lineage initialization requires zero: an old queued callback has no immutable backend storage ID and must be drained by the old backend before a new lineage can be sealed.

type CleanupCloseRequest added in v0.14.0 

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

CleanupCloseRequest is the deliberately weaker admission used when no live projection exists. It never carries callback or retention authority. When a release or pending operation exists, the coordinator still derives cleanup topology from that durable source; a request with neither source is refused.

type CloseAttemptDiagnostics added in v0.14.0 

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

CloseAttemptDiagnostics is the exact interrupted attempt durably named by a close head. It can record observations but cannot publish before terminal close evidence; its identity is never selected from inventory or timestamps.

func (CloseAttemptDiagnostics) Capture added in v0.14.0 

func (attempt CloseAttemptDiagnostics) Capture(observation FailureDiagnosticObservation) (FailureDiagnosticCapture, error)

func (CloseAttemptDiagnostics) MaintenanceID added in v0.14.0 

func (attempt CloseAttemptDiagnostics) MaintenanceID() MaintenanceID

func (CloseAttemptDiagnostics) MatchesTarget added in v0.14.0 

func (attempt CloseAttemptDiagnostics) MatchesTarget(callbackURL, lifecycleURL string, maintenanceID MaintenanceID) bool

MatchesTarget compares complete routing labels as observations of the exact archived attempt; neither a tokenless ID match nor a service name suffices.

func (CloseAttemptDiagnostics) OperationID added in v0.14.0 

func (attempt CloseAttemptDiagnostics) OperationID() OperationID

func (CloseAttemptDiagnostics) ProviderUUID added in v0.14.0 

func (attempt CloseAttemptDiagnostics) ProviderUUID() string

func (CloseAttemptDiagnostics) Tenant added in v0.14.0 

func (attempt CloseAttemptDiagnostics) Tenant() string

func (CloseAttemptDiagnostics) Valid added in v0.14.0 

func (attempt CloseAttemptDiagnostics) Valid() bool

type CloseDestroyed added in v0.14.0 

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

CloseDestroyed attests that the exact close cohort, its canonical volumes, and any retained-volume cohort are absent. Durable retention absence is independently re-attested by terminal settlement.

func (CloseDestroyed) Valid added in v0.14.0 

func (e CloseDestroyed) Valid() bool

type CloseExecutionClaim added in v0.14.0 

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

CloseExecutionClaim is the irreversible-effect capability returned only after the close journal durably advances its monotonic execution generation. Copies of the earlier CloseIntentClaim become stale in that transaction.

type CloseExecutionDestroyed added in v0.14.0 

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

CloseExecutionDestroyed and CloseExecutionRetained are the only terminal close outcomes. Their private fields can be minted only from an exact executor result; callers cannot choose retained/destroyed with a boolean.

func (CloseExecutionDestroyed) Items added in v0.14.0 

func (outcome CloseExecutionDestroyed) Items() []backend.LeaseItem

func (CloseExecutionDestroyed) LeaseUUID added in v0.14.0 

func (outcome CloseExecutionDestroyed) LeaseUUID() string

func (CloseExecutionDestroyed) Tenant added in v0.14.0 

func (outcome CloseExecutionDestroyed) Tenant() string

func (CloseExecutionDestroyed) Valid added in v0.14.0 

func (outcome CloseExecutionDestroyed) Valid() bool

type CloseExecutionGeneration added in v0.14.0 

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

CloseExecutionGeneration is an opaque monotonic durable generation. Zero is the not-started phase and cannot authorize physical work.

func (CloseExecutionGeneration) Number added in v0.14.0 

func (generation CloseExecutionGeneration) Number() int

func (CloseExecutionGeneration) Valid added in v0.14.0 

func (generation CloseExecutionGeneration) Valid() bool

type CloseExecutionOutcome added in v0.14.0 

type CloseExecutionOutcome interface {
	// contains filtered or unexported methods
}

CloseExecutionOutcome is a sealed sum. Only the two terminal variants also implement CloseTerminalOutcome and can cross CompleteClose.

type CloseExecutionPending added in v0.14.0 

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

CloseExecutionPending deliberately grants no terminal authority. Refusal, ambiguous effects, incomplete strict inventory, and interrupted recovery all leave the durable close head as the sole retry owner.

func (CloseExecutionPending) Cause added in v0.14.0 

func (outcome CloseExecutionPending) Cause() error

func (CloseExecutionPending) Error added in v0.14.0 

func (outcome CloseExecutionPending) Error() string

func (CloseExecutionPending) RetryableNow added in v0.14.0 

func (outcome CloseExecutionPending) RetryableNow() bool

RetryableNow reports that strict classification proved the current cohort incomplete (or the guard refused before entering a Step), so a new durable generation may safely retry work immediately. Ambiguous results return false and must wait for a later independent recovery classification.

func (CloseExecutionPending) Unwrap added in v0.14.0 

func (outcome CloseExecutionPending) Unwrap() error

Unwrap preserves internal recovery diagnostics while the typed outcome keeps its pending authority. HTTP encoders emit only the separate transport marker, which deliberately has no cause or refusal sentinel.

func (CloseExecutionPending) Valid added in v0.14.0 

func (outcome CloseExecutionPending) Valid() bool

type CloseExecutionRetained added in v0.14.0 

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

func (CloseExecutionRetained) Items added in v0.14.0 

func (outcome CloseExecutionRetained) Items() []backend.LeaseItem

func (CloseExecutionRetained) LeaseUUID added in v0.14.0 

func (outcome CloseExecutionRetained) LeaseUUID() string

func (CloseExecutionRetained) Tenant added in v0.14.0 

func (outcome CloseExecutionRetained) Tenant() string

func (CloseExecutionRetained) Valid added in v0.14.0 

func (outcome CloseExecutionRetained) Valid() bool

type CloseIncomplete added in v0.14.0 

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

CloseIncomplete is the nonterminal exhaustive classification: some exact cleanup target still survives, or a retaining close does not yet have a complete retained cohort. It carries no settlement authority.

func (CloseIncomplete) Valid added in v0.14.0 

func (e CloseIncomplete) Valid() bool

type CloseIntentAdmission added in v0.14.0 

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

CloseIntentAdmission is returned only after the close barrier is durably committed. Existing is an exact idempotent retry and returns the original capability, including its persisted physical-execution generation.

func (CloseIntentAdmission) Claim added in v0.14.0 

func (admission CloseIntentAdmission) Claim() CloseIntentClaim

Claim returns the journal-issued cleanup authority. Both a newly-created close and its exact replay carry the same durable authority, allowing cleanup to resume after a crash without letting callers assemble an admission.

func (CloseIntentAdmission) Disposition added in v0.14.0 

func (admission CloseIntentAdmission) Disposition() CloseIntentAdmissionDisposition

Disposition reports whether this call created the durable close barrier or replayed the exact existing barrier.

func (CloseIntentAdmission) MaintenancePreempted added in v0.14.0 

func (admission CloseIntentAdmission) MaintenancePreempted() bool

MaintenancePreempted reports whether admitting this close terminalized an unresolved maintenance replacement in the same transaction.

func (CloseIntentAdmission) OperationPreempted added in v0.14.0 

func (admission CloseIntentAdmission) OperationPreempted() bool

OperationPreempted reports whether admitting this close terminalized an unresolved operation in the same transaction.

type CloseIntentAdmissionDisposition added in v0.14.0 

type CloseIntentAdmissionDisposition uint8

CloseIntentAdmissionDisposition tells a backend whether it created the durable close barrier or recovered an exact retry of one already accepted. 

const (
	CloseIntentAdmissionNone CloseIntentAdmissionDisposition = iota
	CloseIntentAdmissionCreated
	CloseIntentAdmissionExisting
)

type CloseIntentClaim added in v0.14.0 

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

CloseIntentClaim is an opaque, copy-safe capability for one exact durable close. It contains no caller-settable authority. Every mutation verifies the lease key and SHA-256 digest against bbolt, so using two copies cannot replay a resolve or overwrite a refreshed physical-execution generation.

func (CloseIntentClaim) ActiveReleaseDigest added in v0.14.0 

func (c CloseIntentClaim) ActiveReleaseDigest() [sha256.Size]byte

func (CloseIntentClaim) ActiveReleaseOperationID added in v0.14.0 

func (c CloseIntentClaim) ActiveReleaseOperationID() OperationID

func (CloseIntentClaim) ActiveReleaseVersion added in v0.14.0 

func (c CloseIntentClaim) ActiveReleaseVersion() int

func (CloseIntentClaim) Backend added in v0.14.0 

func (c CloseIntentClaim) Backend() string

func (CloseIntentClaim) BackendStorageID added in v0.14.0 

func (c CloseIntentClaim) BackendStorageID() backendidentity.ID

func (CloseIntentClaim) CallbackURL added in v0.14.0 

func (c CloseIntentClaim) CallbackURL() string

func (CloseIntentClaim) CleanupOnly added in v0.14.0 

func (c CloseIntentClaim) CleanupOnly() bool

func (CloseIntentClaim) CreatedAt added in v0.14.0 

func (c CloseIntentClaim) CreatedAt() time.Time

func (CloseIntentClaim) ExecutionGeneration added in v0.14.0 

func (c CloseIntentClaim) ExecutionGeneration() CloseExecutionGeneration

func (CloseIntentClaim) IntentID added in v0.14.0 

func (c CloseIntentClaim) IntentID() string

func (CloseIntentClaim) InterruptedMaintenanceID added in v0.14.0 

func (c CloseIntentClaim) InterruptedMaintenanceID() MaintenanceID

func (CloseIntentClaim) InterruptedOperationID added in v0.14.0 

func (c CloseIntentClaim) InterruptedOperationID() OperationID

Interrupted attempt identities are authored only while consuming the exact previous journal head. They survive restart and never select by timestamp.

func (CloseIntentClaim) Items added in v0.14.0 

func (c CloseIntentClaim) Items() []backend.LeaseItem

func (CloseIntentClaim) LeaseUUID added in v0.14.0 

func (c CloseIntentClaim) LeaseUUID() string

func (CloseIntentClaim) LifecycleCallbackURL added in v0.14.0 

func (c CloseIntentClaim) LifecycleCallbackURL() string

func (CloseIntentClaim) Manifest added in v0.14.0 

func (c CloseIntentClaim) Manifest() []byte

func (CloseIntentClaim) ProviderUUID added in v0.14.0 

func (c CloseIntentClaim) ProviderUUID() string

func (CloseIntentClaim) ResourceProfiles added in v0.14.0 

func (c CloseIntentClaim) ResourceProfiles() []SKUResourceSnapshot

func (CloseIntentClaim) RetainOnClose added in v0.14.0 

func (c CloseIntentClaim) RetainOnClose() bool

func (CloseIntentClaim) Tenant added in v0.14.0 

func (c CloseIntentClaim) Tenant() string

type ClosePhysicalEvidence added in v0.14.0 

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

ClosePhysicalEvidence is an opaque closed value algebra. Its private tag and concrete payloads make mixed and typed-nil classifications unrepresentable. The zero value is invalid.

func NewCloseDestroyed added in v0.14.0 

func NewCloseDestroyed(subject ClosePhysicalSubject) (ClosePhysicalEvidence, error)

func NewCloseIncomplete added in v0.14.0 

func NewCloseIncomplete(subject ClosePhysicalSubject) (ClosePhysicalEvidence, error)

func NewCloseRetained added in v0.14.0 

func NewCloseRetained(
	subject ClosePhysicalSubject,
	retention ActiveRetentionProof,
) (ClosePhysicalEvidence, error)

type ClosePhysicalSubject added in v0.14.0 

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

ClosePhysicalSubject is the immutable physical identity returned by the same durable CAS which advances a close execution generation. Its pointer representation is comparable while all authority-bearing state remains private. The zero value is invalid.

func (ClosePhysicalSubject) ExecutionGeneration added in v0.14.0 

func (subject ClosePhysicalSubject) ExecutionGeneration() CloseExecutionGeneration

ExecutionGeneration is the exact monotonic generation which crossed the durable Started boundary before this subject was minted.

func (ClosePhysicalSubject) Intent added in v0.14.0 

func (subject ClosePhysicalSubject) Intent() CloseIntentClaim

Intent returns detached observation and routing authority for the exact close. It cannot itself start, execute, or settle physical work.

func (ClosePhysicalSubject) IntentID added in v0.14.0 

func (subject ClosePhysicalSubject) IntentID() string

func (ClosePhysicalSubject) LeaseUUID added in v0.14.0 

func (subject ClosePhysicalSubject) LeaseUUID() string

func (ClosePhysicalSubject) Valid added in v0.14.0 

func (subject ClosePhysicalSubject) Valid() bool

Valid reports whether this value has complete journal-minted authority. It does not re-read durable state; Start/Recover and terminal settlement perform the exact generation re-attestation at their transition boundaries.

type CloseRequest added in v0.14.0 

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

CloseRequest contains policy and substrate-cleanup evidence only. The security- and causality-bearing principal, callback route, topology, and release fence are derived from the bound journals by BeginClose; callers cannot splice those authorities together themselves.

type CloseRetained added in v0.14.0 

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

CloseRetained attests that the exact workload and canonical volumes are absent and every volume named by the exact Active retention generation is present. Terminal settlement re-reads that durable retention generation.

func (CloseRetained) Valid added in v0.14.0 

func (e CloseRetained) Valid() bool

type CloseSettlement added in v0.14.0 

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

CloseSettlement is the sole phase-safe boundary for close admission, cleanup progress, release retirement, and lifecycle settlement. Its zero value is invalid. All three journals must be the exact open instances for one backend storage lineage and share the same terminal authority gate.

func NewCloseSettlement added in v0.14.0 

func NewCloseSettlement(
	callbacks *CallbackStore,
	releases *ReleaseStore,
	retentions *RetentionStore,
) (*CloseSettlement, error)

NewCloseSettlement binds the complete close authority set. Matching backend names are not enough: pointer identity, immutable storage identity, and the backend-lifetime authority gate must all agree.

func (*CloseSettlement) BeginCleanupClose added in v0.14.0 

func (s *CloseSettlement) BeginCleanupClose(
	request CleanupCloseRequest,
) (CloseIntentAdmission, error)

BeginCleanupClose admits the no-projection path with deliberately reduced authority. It never emits a lifecycle callback or retains volumes. An exact current Failed operation may supply topology only when its terminal record sealed predecessor absence and Release history is still wholly absent.

func (*CloseSettlement) BeginClose added in v0.14.0 

func (s *CloseSettlement) BeginClose(request CloseRequest) (CloseIntentAdmission, error)

BeginClose derives the complete destructive and observational authority from the exact release selected under the journal pair's per-lease gate. If no release exists, an exact pending operation or a Failed operation with sealed, re-attested predecessor absence may supply the same authority.

func (*CloseSettlement) CompleteClose added in v0.14.0 

func (s *CloseSettlement) CompleteClose(
	outcome CloseTerminalOutcome,
) (CallbackEntry, error)

CompleteClose accepts only executor-minted terminal variants. It re-attests the exact close generation before touching release history, then validates the corresponding durable retention fact under the per-lease gate.

func (*CloseSettlement) ExecuteClose added in v0.14.0 

func (s *CloseSettlement) ExecuteClose(
	ctx context.Context,
	execution CloseExecutionClaim,
) (outcome CloseExecutionOutcome)

ExecuteClose runs only the construction-bound physical workflow. A plain error, panic, or incomplete observation cannot terminalize the close.

func (*CloseSettlement) GetCloseIntent added in v0.14.0 

func (s *CloseSettlement) GetCloseIntent(
	leaseUUID string,
) (CloseIntentClaim, bool, error)

GetCloseIntent returns the exact recovery capability issued by this complete journal set. A claim obtained from another open set cannot be mutated here.

func (*CloseSettlement) ListCloseIntents added in v0.14.0 

func (s *CloseSettlement) ListCloseIntents() ([]CloseIntentClaim, error)

ListCloseIntents returns recovery claims bound to this exact settlement.

func (*CloseSettlement) NewCleanupCloseRequest added in v0.14.0 

func (s *CloseSettlement) NewCleanupCloseRequest(
	leaseUUID string,
) (CleanupCloseRequest, error)

NewCleanupCloseRequest constructs the separately typed, callbackless and non-retaining request used only when the volatile projection is absent.

func (*CloseSettlement) NewCloseRequest added in v0.14.0 

func (s *CloseSettlement) NewCloseRequest(
	leaseUUID string,
	retainOnClose bool,
) (CloseRequest, error)

NewCloseRequest validates and detaches the only caller-observed cleanup evidence before binding the request to this exact settlement. Principal, runtime identity, and release fencing are intentionally not parameters.

func (*CloseSettlement) ProveRetention added in v0.14.0 

func (s *CloseSettlement) ProveRetention(
	claim CloseIntentClaim,
) (ActiveRetentionProof, error)

ProveRetention reissues active-retention evidence for a retry after Docker has independently re-attested every persisted retained volume.

func (*CloseSettlement) RecordRetention added in v0.14.0 

func (s *CloseSettlement) RecordRetention(
	claim CloseIntentClaim,
	partition string,
	retainedVolumeNames []string,
) (bool, error)

RecordRetention is the close-owned soft-delete writer. Every identity and topology field comes from the exact close claim; callers contribute only the physical retained-volume observations and optional partition policy. It deliberately returns no completion capability: only ProveRetention, called after physical rename success, can mint ActiveRetentionProof.

func (*CloseSettlement) RecoverCloseExecution added in v0.14.0 

func (s *CloseSettlement) RecoverCloseExecution(
	ctx context.Context,
	scope LeaseRecoveryScope,
	claim CloseIntentClaim,
) (CloseExecutionOutcome, error)

RecoverCloseExecution performs a read-only strict classification of one exact persisted Started generation. It cannot replay live work and cannot choose its classifier. A close which never started must cross StartCloseExecution instead.

func (*CloseSettlement) RetryCloseExecution added in v0.14.0 

func (s *CloseSettlement) RetryCloseExecution(
	pending CloseExecutionPending,
) (CloseExecutionClaim, error)

RetryCloseExecution is the only transition from one Started generation to the next. Its input is minted only when the fixed classifier proves the previous generation incomplete, or when the previous live executor was refused before any tenant Step. An ambiguous live result therefore cannot be replayed in the same process merely by re-reading its durable claim.

func (*CloseSettlement) StartCloseExecution added in v0.14.0 

func (s *CloseSettlement) StartCloseExecution(
	claim CloseIntentClaim,
) (CloseExecutionClaim, error)

StartCloseExecution is the only transition into live physical close work. Incrementing the persisted generation is the durable Started boundary: no tenant Step can be entered until the exact refreshed claim and subject exist.

type CloseTerminalOutcome added in v0.14.0 

type CloseTerminalOutcome interface {
	CloseExecutionOutcome

	LeaseUUID() string
	Tenant() string
	Items() []backend.LeaseItem
	// contains filtered or unexported methods
}

type ClosedLeaseAuthorityKind added in v0.14.0 

type ClosedLeaseAuthorityKind string

ClosedLeaseAuthorityKind makes the two valid cleanup authorities explicit: principal-bound cleanup requires both tenant and provider, while an orphan receipt authorizes only lease-UUID cleanup under the already-attested backend storage identity. The decoder rejects every mixed representation. 

const (
	ClosedLeaseAuthorityPrincipal ClosedLeaseAuthorityKind = "principal_bound"
	ClosedLeaseAuthorityOrphan    ClosedLeaseAuthorityKind = "orphan"
)

type ClosedLeaseReceipt added in v0.14.0 

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

ClosedLeaseReceipt is the opaque, permanent cleanup authority for one UUID whose successful close crossed the irreversible lifecycle boundary. A backend may use it only to exclude that UUID from live projection and remove managed substrate that independently proves the same lease identity. Its zero value is invalid; private fields make every non-zero value store-issued and eliminate nil-interface authority states.

func (ClosedLeaseReceipt) AuthorityKind added in v0.14.0 

func (r ClosedLeaseReceipt) AuthorityKind() ClosedLeaseAuthorityKind

func (ClosedLeaseReceipt) Backend added in v0.14.0 

func (r ClosedLeaseReceipt) Backend() string

func (ClosedLeaseReceipt) BackendStorageID added in v0.14.0 

func (r ClosedLeaseReceipt) BackendStorageID() backendidentity.ID

func (ClosedLeaseReceipt) CleanupOnly added in v0.14.0 

func (r ClosedLeaseReceipt) CleanupOnly() bool

func (ClosedLeaseReceipt) ClosedAt added in v0.14.0 

func (r ClosedLeaseReceipt) ClosedAt() time.Time

func (ClosedLeaseReceipt) LeaseUUID added in v0.14.0 

func (r ClosedLeaseReceipt) LeaseUUID() string

func (ClosedLeaseReceipt) ProviderUUID added in v0.14.0 

func (r ClosedLeaseReceipt) ProviderUUID() string

func (ClosedLeaseReceipt) Tenant added in v0.14.0 

func (r ClosedLeaseReceipt) Tenant() string

func (ClosedLeaseReceipt) Valid added in v0.14.0 

func (r ClosedLeaseReceipt) Valid() bool

type CommandFence added in v0.14.0 

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

CommandFence serializes admission, reconciliation, and teardown for one lease. It is a zero-value-ready, ref-counted keyed mutex registry: unrelated leases never block one another, and an entry is removed after its last holder or waiter releases it. It deliberately carries no lifecycle state; durable intent/outbox records remain the crash-recovery authority.

CommandFence must not be copied after first use, like sync.Mutex.

func (*CommandFence) Lock added in v0.14.0 

func (f *CommandFence) Lock(leaseUUID string) func()

Lock acquires the mutex for leaseUUID and returns an idempotent unlock function. Refcounts include both the current holder and queued waiters, which prevents an entry from being removed while another goroutine can still acquire its mutex.

func (*CommandFence) TryLock added in v0.14.0 

func (f *CommandFence) TryLock(leaseUUID string) (func(), bool)

TryLock acquires leaseUUID only when doing so cannot wait. It is intended for level-triggered background convergence: a live caller already owning the command is authoritative, so recovery should defer that lease without stalling unrelated work. The returned unlock function is idempotent.

type DiagnosticCaptureStatus added in v0.14.0 

type DiagnosticCaptureStatus string

DiagnosticCaptureStatus describes an observation, never cleanup authority. 

const (
	DiagnosticCaptureComplete    DiagnosticCaptureStatus = "complete"
	DiagnosticCapturePartial     DiagnosticCaptureStatus = "partial"
	DiagnosticCaptureTruncated   DiagnosticCaptureStatus = "truncated"
	DiagnosticCaptureUnavailable DiagnosticCaptureStatus = "unavailable"
)

type DiagnosticEntry 

type DiagnosticEntry struct {
	LeaseUUID    string `json:"lease_uuid"`
	ProviderUUID string `json:"provider_uuid"`
	Tenant       string `json:"tenant"`
	Error        string `json:"error"`
	// Reason/Message: curated tenant-safe failure signal (ENG-508). Error stays
	// operator-only. Reason authored at source; Message == on-chain CallbackErr.
	Reason    backend.Reason    `json:"reason,omitempty"`
	Message   string            `json:"message,omitempty"`
	Logs      map[string]string `json:"logs,omitempty"`
	FailCount int               `json:"fail_count"`
	// RuntimeReleaseVersion identifies the observed active release when this is
	// a runtime failure snapshot. It is not authority; publication rechecks it
	// against the current journal under the lease transition gate.
	RuntimeReleaseVersion int `json:"runtime_release_version,omitempty"`
	// LifecycleGeneration is the historical, non-secret observation captured
	// from the callback pair that owned this failure. It keeps a singular
	// diagnostics read consistent after the live projection disappears, but is
	// never lifecycle/settlement authority: diagnostic-only rows remain excluded
	// from fleet inventory. Older rows omit it and remain readable as unknown.
	LifecycleGeneration *backend.LifecycleGenerationObservation `json:"lifecycle_generation,omitempty"`
	CreatedAt           time.Time                               `json:"created_at"`
}

DiagnosticEntry represents a persisted failure diagnostic record.

type DiagnosticsStore 

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

DiagnosticsStore persists failure diagnostics in bbolt so they survive container removal and backend restarts.

func NewDiagnosticsStore 

func NewDiagnosticsStore(cfg DiagnosticsStoreConfig) (*DiagnosticsStore, error)

NewDiagnosticsStore opens or creates a bbolt database for diagnostics persistence. If MaxAge > 0, a background cleanup loop removes expired entries periodically and an initial cleanup runs immediately to clear stale entries from previous runs.

func (*DiagnosticsStore) Close 

func (store *DiagnosticsStore) Close() error

Close waits for physical cleanup to relinquish its saved diagnostic, without stopping an unrelated writer behind a read transaction's mmap lock.

func (*DiagnosticsStore) Delete 

func (s *DiagnosticsStore) Delete(leaseUUID string) error

Delete removes a diagnostic entry by lease UUID. It is a no-op if the entry does not exist.

func (*DiagnosticsStore) Get 

func (s *DiagnosticsStore) Get(leaseUUID string) (*DiagnosticEntry, error)

Get retrieves a diagnostic entry by lease UUID. Returns nil, nil when not found.

func (DiagnosticsStore) Healthy 

func (s DiagnosticsStore) Healthy() error

Healthy checks that the bbolt database is accessible and the bucket exists.

func (*DiagnosticsStore) RemoveOlderThan 

func (s *DiagnosticsStore) RemoveOlderThan(maxAge time.Duration) (int, error)

RemoveOlderThan deletes diagnostic entries older than maxAge and returns the number of entries removed.

func (*DiagnosticsStore) Store 

func (s *DiagnosticsStore) Store(entry DiagnosticEntry) error

Store persists a diagnostic entry, upserting by LeaseUUID.

func (DiagnosticsStore) VerifyStorageIdentity added in v0.14.0 

func (s DiagnosticsStore) VerifyStorageIdentity(storage backendidentity.VerifiedStorage) error

VerifyStorageIdentity proves that an authoritative store's configured path still names the exact regular file opened by the constructor and that the durable binding remains intact. This catches delete/rename/replacement while the process still holds a writable descriptor to the old inode.

type DiagnosticsStoreConfig 

type DiagnosticsStoreConfig struct {
	DBPath          string            // Path to bbolt database file
	MaxAge          time.Duration     // Max age before entries are cleaned up (0 = no expiry)
	CleanupInterval time.Duration     // How often to run cleanup (defaults to MaxAge)
	OnCleanupPanic  util.PanicHandler // Optional: invoked on cleanup-loop panic.
}

DiagnosticsStoreConfig configures the diagnostics store.

type DiskAccountingHold added in v0.14.0 

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

DiskAccountingHold is pool-issued ownership of one disk-capacity exclusion. While any is held, available disk is unknown: every allocation, adoption or provision reservation that needs disk is refused with ErrDiskAccountingIncomplete, and the stats report no available disk. SetRetainedDisk cannot clear it; only its owner's Release can. Copies share one idempotent release, and the zero value grants none.

func (DiskAccountingHold) Release added in v0.14.0 

func (h DiskAccountingHold) Release()

Release returns only the disk exclusion owned by this hold.

type DockerRecoveryInspection added in v0.14.0 

type DockerRecoveryInspection struct {
	Verdict         string   `json:"verdict"`
	Backend         string   `json:"backend"`
	StorageID       string   `json:"storage_id"`
	Database        string   `json:"database"`
	SnapshotSHA256  string   `json:"snapshot_sha256"`
	Launches        int      `json:"launches"`
	UnknownHelpers  int      `json:"unknown_helpers"`
	Leases          []string `json:"leases"`
	Acknowledgement string   `json:"acknowledgement"`
}

DockerRecoveryInspection describes pending effects without granting runtime mutation authority. Acknowledgement is an exact operator statement, not a daemon observation: neither an empty inventory nor a timeout proves a fence.

func InspectDockerRecovery added in v0.14.0 

func InspectDockerRecovery(ctx context.Context, path string, storage backendidentity.VerifiedStorage) (inspection DockerRecoveryInspection, err error)

InspectDockerRecovery opens only an existing, identity-bound callback journal read-only. It does not create buckets or start maintenance workers.

type DockerRecoveryRepairResult added in v0.14.0 

type DockerRecoveryRepairResult struct {
	Verdict        string `json:"verdict"`
	Backup         string `json:"backup,omitempty"`
	SnapshotSHA256 string `json:"snapshot_sha256"`
	Launches       int    `json:"launches"`
	UnknownHelpers int    `json:"unknown_helpers"`
}

DockerRecoveryRepairResult reports the backup and exact repair outcome. A nonempty Backup on error must be preserved. DOCKER_EFFECTS_FENCED with nil error confirms completion; an error requires read-only reinspection under the same external fence before restarting normal recovery.

func RepairDockerRecovery added in v0.14.0 

func RepairDockerRecovery(ctx context.Context, path string, storage backendidentity.VerifiedStorage, acknowledgement, backupPath string, verify func(context.Context) error) (result DockerRecoveryRepairResult, err error)

RepairDockerRecovery is the explicit offline escape from an unknown remote call, not a retry policy. Exclusive database ownership excludes the backend; the exact acknowledgement supplies the external daemon/runtime fencing fact. verify must re-attest the configured daemon and storage marker lineage.

type FailedMaintenanceCleanupProof added in v0.14.0 

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

FailedMaintenanceCleanupProof is store-issued evidence that one exact failed receipt's late-arrival cleanup attested that no container of its generation exists. Only CleanupFailedMaintenanceReceipt mints it.

type FailedMaintenanceReceipt added in v0.14.0 

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

FailedMaintenanceReceipt is store-issued authority to remove a replacement generation that becomes visible after its failed terminal settlement. It lasts as long as its receipt is retained. It is minted only for an intent which durably crossed the physical-effect boundary and binds the exact immutable target release row. Pre-effect failures and older receipts deliberately cannot produce one.

func (FailedMaintenanceReceipt) Backend added in v0.14.0 

func (r FailedMaintenanceReceipt) Backend() string

func (FailedMaintenanceReceipt) BackendStorageID added in v0.14.0 

func (r FailedMaintenanceReceipt) BackendStorageID() backendidentity.ID

func (FailedMaintenanceReceipt) LeaseUUID added in v0.14.0 

func (r FailedMaintenanceReceipt) LeaseUUID() string

func (FailedMaintenanceReceipt) MaintenanceID added in v0.14.0 

func (r FailedMaintenanceReceipt) MaintenanceID() MaintenanceID

func (FailedMaintenanceReceipt) ProviderUUID added in v0.14.0 

func (r FailedMaintenanceReceipt) ProviderUUID() string

func (FailedMaintenanceReceipt) SettledAt added in v0.14.0 

func (r FailedMaintenanceReceipt) SettledAt() time.Time

func (FailedMaintenanceReceipt) TargetRelease added in v0.14.0 

func (r FailedMaintenanceReceipt) TargetRelease() (Release, bool)

func (FailedMaintenanceReceipt) Tenant added in v0.14.0 

func (r FailedMaintenanceReceipt) Tenant() string

func (FailedMaintenanceReceipt) Valid added in v0.14.0 

func (r FailedMaintenanceReceipt) Valid() bool

type FailedOperationReceipt added in v0.14.0 

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

FailedOperationReceipt is the opaque, immutable teardown identity of an operation that settled Failed. Unlike a live recovery state it intentionally carries no manifest or resource payload: a later generation may own the lease, so consumers may remove only substrate objects whose complete labels match this exact historical authority. Its zero value is invalid, and its private fields eliminate nil-interface authority states.

func (FailedOperationReceipt) Backend added in v0.14.0 

func (r FailedOperationReceipt) Backend() string

func (FailedOperationReceipt) BackendStorageID added in v0.14.0 

func (r FailedOperationReceipt) BackendStorageID() backendidentity.ID

func (FailedOperationReceipt) CallbackURL added in v0.14.0 

func (r FailedOperationReceipt) CallbackURL() string

func (FailedOperationReceipt) Error added in v0.14.0 

func (r FailedOperationReceipt) Error() string

func (FailedOperationReceipt) Kind added in v0.14.0 

func (r FailedOperationReceipt) Kind() OperationIntentKind

func (FailedOperationReceipt) LeaseUUID added in v0.14.0 

func (r FailedOperationReceipt) LeaseUUID() string

func (FailedOperationReceipt) LifecycleCallbackURL added in v0.14.0 

func (r FailedOperationReceipt) LifecycleCallbackURL() string

func (FailedOperationReceipt) OperationID added in v0.14.0 

func (r FailedOperationReceipt) OperationID() OperationID

func (FailedOperationReceipt) ProviderUUID added in v0.14.0 

func (r FailedOperationReceipt) ProviderUUID() string

func (FailedOperationReceipt) SettledAt added in v0.14.0 

func (r FailedOperationReceipt) SettledAt() time.Time

func (FailedOperationReceipt) Tenant added in v0.14.0 

func (r FailedOperationReceipt) Tenant() string

func (FailedOperationReceipt) Valid added in v0.14.0 

func (r FailedOperationReceipt) Valid() bool

type FailureDiagnosticCapture added in v0.14.0 

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

FailureDiagnosticCapture is an immutable reference to an attempt record in one open diagnostics store. It grants observation only: cleanup still needs its exact physical subject and publication needs a current terminal proof.

func (FailureDiagnosticCapture) RetainDuring added in v0.14.0 

func (capture FailureDiagnosticCapture) RetainDuring(action func() error) (err error)

RetainDuring keeps the already-durable record readable until the caller's bounded action ends. A store-owned pin prevents expiry or store closure from deleting the only saved copy between persistence and physical removal. No database transaction remains open during the action. This grants no cleanup authority; substrate adapters must separately own the exact captured cohort and its opaque physical subject.

func (FailureDiagnosticCapture) Snapshot added in v0.14.0 

func (capture FailureDiagnosticCapture) Snapshot() (DiagnosticEntry, DiagnosticCaptureStatus, error)

func (FailureDiagnosticCapture) Valid added in v0.14.0 

func (capture FailureDiagnosticCapture) Valid() bool

type FailureDiagnosticObservation added in v0.14.0 

type FailureDiagnosticObservation struct {
	Error        string
	Reason       backend.Reason
	Message      string
	Logs         map[string]string
	ContainerIDs []string
	Status       DiagnosticCaptureStatus
}

FailureDiagnosticObservation is non-authoritative data supplied by the subject-bound log reader. Every identity is derived separately from the operation or maintenance subject, never from these fields.

type FailureDiagnosticPublication added in v0.14.0 

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

FailureDiagnosticPublication carries one attempt's durable capture and the exact terminal proof needed to make it tenant-visible. Neither capture nor a historical cleanup receipt alone can construct this value. Consumption rechecks the current journal head under the same lease gate as admission and close; a copied reference cannot publish after a newer command takes over.

func (FailureDiagnosticPublication) PublishContext added in v0.14.0 

func (publication FailureDiagnosticPublication) PublishContext(ctx context.Context, failCount int) error

PublishContext is intentionally the only effect exposed by the handoff. Its argument is an observational counter; callers cannot substitute identity, logs, category, callback message, or attempt ordering.

func (FailureDiagnosticPublication) Snapshot added in v0.14.0 

func (publication FailureDiagnosticPublication) Snapshot() (DiagnosticEntry, DiagnosticCaptureStatus, error)

func (FailureDiagnosticPublication) Valid added in v0.14.0 

func (publication FailureDiagnosticPublication) Valid() bool

type FailureDiagnostics added in v0.14.0 

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

FailureDiagnostics binds observational storage to the exact journals which serialize new admission, terminal publication, and close. It never owns a substrate writer, release transition, or callback settlement capability.

func NewFailureDiagnostics added in v0.14.0 

func NewFailureDiagnostics(store *DiagnosticsStore, operations *OperationSettlement, maintenance *MaintenanceSettlement) (*FailureDiagnostics, error)

func (*FailureDiagnostics) CaptureMaintenance added in v0.14.0 

func (diagnostics *FailureDiagnostics) CaptureMaintenance(subject MaintenancePhysicalSubject, observation FailureDiagnosticObservation) (FailureDiagnosticCapture, error)

func (*FailureDiagnostics) CaptureOperation added in v0.14.0 

func (diagnostics *FailureDiagnostics) CaptureOperation(subject OperationPhysicalSubject, observation FailureDiagnosticObservation) (FailureDiagnosticCapture, error)

func (*FailureDiagnostics) CloseAttempt added in v0.14.0 

func (diagnostics *FailureDiagnostics) CloseAttempt(subject ClosePhysicalSubject) (CloseAttemptDiagnostics, bool, error)

func (*FailureDiagnostics) MaintenanceFailureContext added in v0.14.0 

func (diagnostics *FailureDiagnostics) MaintenanceFailureContext(ctx context.Context, proof MaintenanceReleaseFailure, observation FailureDiagnosticObservation) (FailureDiagnosticPublication, error)

func (*FailureDiagnostics) OperationFailureContext added in v0.14.0 

func (diagnostics *FailureDiagnostics) OperationFailureContext(ctx context.Context, proof OperationReleaseUncommitted, observation FailureDiagnosticObservation) (FailureDiagnosticPublication, error)

OperationFailureContext prepares an opaque diagnostic handoff. A pre-effect refusal may have no containers to capture; it still gets an explicit unavailable observation. Existing captures retain their original cause and logs.

func (*FailureDiagnostics) PublishCloseFailure added in v0.14.0 

func (diagnostics *FailureDiagnostics) PublishCloseFailure(outcome CloseTerminalOutcome) error

PublishCloseFailure consumes terminal physical evidence while the exact close head still owns the lease. It precedes CompleteClose, so diagnostics failure cannot destroy the last recovery obligation or compact the linked receipts.

func (*FailureDiagnostics) PublishedForRuntime added in v0.14.0 

func (diagnostics *FailureDiagnostics) PublishedForRuntime(runtime RuntimeGenerationProof) (RuntimeFailureLogs, error)

func (*FailureDiagnostics) RetireHistoricalCapture added in v0.14.0 

func (diagnostics *FailureDiagnostics) RetireHistoricalCapture(capture FailureDiagnosticCapture) error

RetireHistoricalCapture is used after an exact captured cohort is removed. Retirement permission is derived afresh from the durable aggregate head; callers cannot select a timestamp or assert that a capture is obsolete.

func (*FailureDiagnostics) StoreRuntime added in v0.14.0 

func (diagnostics *FailureDiagnostics) StoreRuntime(entry DiagnosticEntry) error

StoreRuntime retains the existing runtime-failure diagnostic path while preventing a snapshot of an older generation from overwriting an attempt capture. The current release and principal are checked under the journal pair's lease gate; an unresolved operation/maintenance owns publication until its terminal handoff completes.

func (*FailureDiagnostics) TryPublishMaintenanceFailure added in v0.14.0 

func (diagnostics *FailureDiagnostics) TryPublishMaintenanceFailure(proof MaintenanceReleaseFailure, observation FailureDiagnosticObservation, failCount int) (DiagnosticEntry, bool, error)

TryPublishMaintenanceFailure preserves recovery's nonblocking lease-gate contract while committing the exact terminal diagnostic before callback settlement is allowed to proceed.

type ImageInspectionJournal added in v0.14.0 

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

ImageInspectionJournal issues exact helper receipts. It shares the callback store's pathname attestation, commit gate and close lifetime; it never opens a second unbound database or gains authority from a caller-selected storage ID.

func NewImageInspectionJournal added in v0.14.0 

func NewImageInspectionJournal(store *CallbackStore) (*ImageInspectionJournal, error)

func (*ImageInspectionJournal) ForgetRemoved added in v0.14.0 

func (j *ImageInspectionJournal) ForgetRemoved(receipt ImageInspectionReceipt) error

ForgetRemoved consumes a response-complete or explicitly fenced receipt after its owner established exact absence. Unfenced response-loss receipts remain available to remove later appearances even after workload close.

func (*ImageInspectionJournal) List added in v0.14.0 

func (j *ImageInspectionJournal) List() ([]ImageInspectionReceipt, error)

func (*ImageInspectionJournal) Prepare added in v0.14.0 

func (j *ImageInspectionJournal) Prepare(origin ImageInspectionOrigin, imageID, reference string) (PreparedImageInspection, error)

Prepare creates an immutable identity after rereading the exact Started head. It does not allocate durable cleanup debt before mutation admission.

func (*ImageInspectionJournal) RecordCreationSettled added in v0.14.0 

func (j *ImageInspectionJournal) RecordCreationSettled(receipt ImageInspectionReceipt, id string, completed substratemutation.CompletedStep) (ImageInspectionReceipt, error)

RecordCreationSettled records a daemon response only after the exact creation bracket passed its storage postcheck. An error response may have no ID; cleanup still requires exact owned-helper absence before forgetting the row.

func (*ImageInspectionJournal) Reserve added in v0.14.0 

func (j *ImageInspectionJournal) Reserve(p PreparedImageInspection) (ImageInspectionReceipt, error)

Reserve persists an exact prepared identity immediately before Create. The write rechecks its origin so a close or successor cannot lend stale rights.

type ImageInspectionOrigin added in v0.14.0 

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

ImageInspectionOrigin is preparation authority from one exact live Started subject. It cannot be assembled from a lease/operation ID or recovered from a historical receipt. Allocation rechecks its journal head in the write itself.

func ImageInspectionForCompensation added in v0.14.0 

func ImageInspectionForCompensation(subject MaintenanceCompensationSubject) ImageInspectionOrigin

ImageInspectionForCompensation authorizes preparation of the exact captured source before its first launch. A dispatched/settled recovery subject can observe its containers but cannot create fresh image helpers.

func ImageInspectionForMaintenance added in v0.14.0 

func ImageInspectionForMaintenance(subject MaintenancePhysicalSubject) ImageInspectionOrigin

func ImageInspectionForOperation added in v0.14.0 

func ImageInspectionForOperation(subject OperationPhysicalSubject) ImageInspectionOrigin

type ImageInspectionReceipt added in v0.14.0 

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

ImageInspectionReceipt binds one helper identity to its issuing open journal. A receipt without a response or offline fence retains uncertain Create authority; an empty inventory cannot prove that a canceled daemon call will not appear.

func (ImageInspectionReceipt) Backend added in v0.14.0 

func (r ImageInspectionReceipt) Backend() string

func (ImageInspectionReceipt) ContainerID added in v0.14.0 

func (r ImageInspectionReceipt) ContainerID() string

func (ImageInspectionReceipt) CreationSettled added in v0.14.0 

func (r ImageInspectionReceipt) CreationSettled() bool

CreationSettled reports a completed response or explicit offline daemon fence. It does not prove helper absence; cleanup must still inspect exact ownership.

func (ImageInspectionReceipt) ID added in v0.14.0 

func (r ImageInspectionReceipt) ID() string

func (ImageInspectionReceipt) ImageID added in v0.14.0 

func (r ImageInspectionReceipt) ImageID() string

func (ImageInspectionReceipt) ImageReference added in v0.14.0 

func (r ImageInspectionReceipt) ImageReference() string

func (ImageInspectionReceipt) Kind added in v0.14.0 

func (r ImageInspectionReceipt) Kind() string

func (ImageInspectionReceipt) LeaseUUID added in v0.14.0 

func (r ImageInspectionReceipt) LeaseUUID() string

func (ImageInspectionReceipt) Name added in v0.14.0 

func (r ImageInspectionReceipt) Name() string

func (ImageInspectionReceipt) StorageID added in v0.14.0 

func (r ImageInspectionReceipt) StorageID() backendidentity.ID

func (ImageInspectionReceipt) SubjectID added in v0.14.0 

func (r ImageInspectionReceipt) SubjectID() string

type ImagePin added in v0.14.0 

type ImagePin struct {
	LeaseUUID    string           `json:"lease_uuid"`
	ManifestHash string           `json:"manifest_hash"`
	Reference    string           `json:"reference"`
	ImageID      string           `json:"image_id"`
	PullDigest   string           `json:"pull_digest,omitempty"`
	Platform     ocispec.Platform `json:"platform"`
	// ImportBytes records the verified import allowance for this immutable
	// content. Legacy zero is readable but grants no deferred-unpack budget.
	ImportBytes int64 `json:"import_bytes,omitempty"`
	// VerificationBytes bounds compressed staging and decoded verification.
	// Its absence marks legacy evidence; ImportBytes cannot supply this bound.
	VerificationBytes int64 `json:"verification_bytes,omitempty"`
}

ImagePin preserves execution content independently of mutable registry tags. Pins share the callback journal's storage identity and commit failure gate. A lease/manifest pair always selects the first successfully admitted content.

func (ImagePin) Budget added in v0.14.0 

func (pin ImagePin) Budget() (imagebudget.Budget, error)

Budget decodes both durable dimensions together. The pin journal verifies the containing immutable identity before returning the record to its owner.

type ImagePinBackfillObservation added in v0.14.0 

type ImagePinBackfillObservation struct {
	Reference  string
	ImageID    string
	PullDigest string
	Platform   ocispec.Platform
}

ImagePinBackfillObservation reports positive local content evidence. It is not write authority: only the constructor-bound observer is invoked while the backfiller owns the exact journal and lease generation.

type ImagePinBackfillObserver added in v0.14.0 

type ImagePinBackfillObserver interface {
	ObserveImagePins(context.Context, ImagePinBackfillSubject) ([]ImagePinBackfillObservation, error)
}

type ImagePinBackfillReport added in v0.14.0 

type ImagePinBackfillReport struct {
	PinsAdded        int
	UnresolvedLeases int
}

ImagePinBackfillReport distinguishes unavailable historical evidence from a journal failure. Incomplete evidence keeps cache collection conservative.

type ImagePinBackfillSubject added in v0.14.0 

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

ImagePinBackfillSubject is the exact active generation held by the backfiller's lease transition lock. Detached Release values cannot authorize pin writes.

func (ImagePinBackfillSubject) LeaseUUID added in v0.14.0 

func (s ImagePinBackfillSubject) LeaseUUID() string

func (ImagePinBackfillSubject) Release added in v0.14.0 

func (s ImagePinBackfillSubject) Release() Release

type ImagePinBackfiller added in v0.14.0 

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

ImagePinBackfiller may enrich existing generations from positive physical evidence. It cannot accept a caller-selected generation or replacement pin.

func NewImagePinBackfiller added in v0.14.0 

func NewImagePinBackfiller(journal *ImagePinJournal, observer ImagePinBackfillObserver) (*ImagePinBackfiller, error)

func (*ImagePinBackfiller) Sweep added in v0.14.0 

func (b *ImagePinBackfiller) Sweep(ctx context.Context) (ImagePinBackfillReport, error)

func (*ImagePinBackfiller) VerifyLease added in v0.14.0 

func (b *ImagePinBackfiller) VerifyLease(ctx context.Context, lease string) (ImagePinVerification, error)

VerifyLease matches one lease's active generation against positive physical evidence of its running cohort. A missing pin is minted from that evidence, as Sweep does; an existing pin that names other content is reported, never replaced. Unavailable evidence verifies nothing.

type ImagePinInventory added in v0.14.0 

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

ImagePinInventory is the collector's complete immutable-content inventory. Only Collect can mint a value that permits unused image removal.

func (ImagePinInventory) CanRemove added in v0.14.0 

func (i ImagePinInventory) CanRemove(imageID string) bool

CanRemove proves that the complete journal snapshot did not name this image. A zero value or legacy manifest with missing pins never grants collection.

func (ImagePinInventory) Complete added in v0.14.0 

func (i ImagePinInventory) Complete() bool

Complete reports whether every relaunchable generation has immutable pins. Incompleteness inhibits deletion without rejecting unrelated admission.

func (ImagePinInventory) UnpinnedActiveGenerations added in v0.14.0 

func (i ImagePinInventory) UnpinnedActiveGenerations() int

UnpinnedActiveGenerations counts active or required compensation generations with at least one missing immutable pin, including unavailable ancestry. Pending targets have not completed image admission and are not counted.

func (ImagePinInventory) UnpinnedRetainedGenerations added in v0.14.0 

func (i ImagePinInventory) UnpinnedRetainedGenerations() int

UnpinnedRetainedGenerations counts restorable manifests with at least one missing immutable pin. A legacy retention without a manifest counts once.

type ImagePinJournal added in v0.14.0 

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

ImagePinJournal is a bounded cache of immutable execution identities. The Started subject, rather than caller-selected lease metadata, authorizes pins.

func NewImagePinJournal added in v0.14.0 

func NewImagePinJournal(store *CallbackStore, releases *ReleaseStore, retentions *RetentionStore) (*ImagePinJournal, error)

func (*ImagePinJournal) Collect added in v0.14.0 

func (j *ImagePinJournal) Collect(ctx context.Context) (ImagePinInventory, error)

Collect derives pin liveness from its construction-bound journals. Callers cannot supply a lease inventory or authorize deletion with a detached DTO. The same per-lease lock used by settlement spans all three store reads and pruning, preventing a release-to-retention or intent-to-release handoff gap. Exact manifest references, rather than mere lease existence, keep pins live.

func (*ImagePinJournal) List added in v0.14.0 

func (j *ImagePinJournal) List() ([]ImagePin, error)

func (*ImagePinJournal) Lookup added in v0.14.0 

func (j *ImagePinJournal) Lookup(lease string, payload []byte, ref string) (*ImagePin, error)

func (*ImagePinJournal) Pin added in v0.14.0 

func (j *ImagePinJournal) Pin(origin ImageInspectionOrigin, ref, id, pullDigest string, platform ocispec.Platform, budget imagebudget.Budget) error

Pin writes only the exact Started manifest's reference; repeated admission cannot silently replace a previously pinned image after its tag moves. A verified import allowance may increase for the same image and platform, but can never shrink or authorize replacing the original execution identity. That verification may also fill a missing legacy recovery digest; an existing digest is never replaced.

type ImagePinVerification added in v0.14.0 

type ImagePinVerification struct {
	// Verified reports that every image of the active generation is pinned to
	// exactly the content its running cohort executes.
	Verified bool
	// Diverged lists, sorted, the references whose existing pin names other
	// content than the cohort executes. A pin is never replaced, so a
	// divergence does not heal.
	Diverged []string
}

ImagePinVerification matches one lease's pins against the images its running cohort executes.

type InterruptedRestoreSource added in v0.14.0 

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

InterruptedRestoreSource binds a recovery-only restore subject to the exact retained close which still owns its source namespace. It permits observation of the recorded names, never deletion or terminal settlement. Docker must independently prove quiescence and re-attest this proof inside its guarded namespace mutation before returning source-canonical bytes to retention.

func (InterruptedRestoreSource) ReattestFor added in v0.14.0 

func (proof InterruptedRestoreSource) ReattestFor(subject OperationPhysicalSubject) error

ReattestFor re-reads both exact journal heads and the whole source record. Its caller holds the namespace reservation across this check and the rename; a copied proof cannot survive a retry generation, changed row, or store reopen.

func (InterruptedRestoreSource) RetainedVolumeNames added in v0.14.0 

func (proof InterruptedRestoreSource) RetainedVolumeNames() []string

RetainedVolumeNames returns detached immutable source observations.

type LeaseMutationCapacityError added in v0.14.0 

type LeaseMutationCapacityError struct {
	Limit uint64
}

LeaseMutationCapacityError carries the global UUID bound and participates in the backend's existing coded capacity protocol.

func (*LeaseMutationCapacityError) Error added in v0.14.0 

func (e *LeaseMutationCapacityError) Error() string

func (*LeaseMutationCapacityError) Unwrap added in v0.14.0 

func (e *LeaseMutationCapacityError) Unwrap() []error

type LeaseMutationUUIDCapacity added in v0.14.0 

type LeaseMutationUUIDCapacity struct {
	Reserved uint64
	Limit    uint64
}

LeaseMutationUUIDCapacity is a point-in-time view of the callback journal's permanent lease-identity budget. Reserved never decreases: maintenance and operation heads may settle, but their lease UUID remains reserved so a later successful close can install its non-expiring retirement fence without allocating after destructive work has begun.

func (LeaseMutationUUIDCapacity) Remaining added in v0.14.0 

func (capacity LeaseMutationUUIDCapacity) Remaining() uint64

Remaining returns the number of never-before-seen lease UUIDs the journal can still admit. It saturates at zero so even a manually assembled diagnostic value cannot underflow.

type LeaseRecoveryScope added in v0.14.0 

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

LeaseRecoveryScope is an opaque, exact-lease capability valid only while a RecoveryCoordinator callback is running. Copies share revocation state, so a retained copy becomes invalid as soon as the callback returns or panics.

type LegacyRuntimeAuthority added in v0.14.0 

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

LegacyRuntimeAuthority is an immutable, tokenless v0.13 runtime identity. Its zero value is invalid and all fields are private so a caller cannot mix a principal from one cohort with callback authority from another.

func NewLegacyRuntimeAuthority added in v0.14.0 

func NewLegacyRuntimeAuthority(
	tenant, providerUUID, callbackURL, lifecycleCallbackURL string,
) (LegacyRuntimeAuthority, error)

NewLegacyRuntimeAuthority validates and freezes one coherent tokenless operation/lifecycle callback pair. Typed callback identities are rejected: they belong in ReleaseRuntimeAuthority together with their OperationID.

func (LegacyRuntimeAuthority) CallbackURL added in v0.14.0 

func (authority LegacyRuntimeAuthority) CallbackURL() string

func (LegacyRuntimeAuthority) LifecycleCallbackURL added in v0.14.0 

func (authority LegacyRuntimeAuthority) LifecycleCallbackURL() string

func (LegacyRuntimeAuthority) MarshalJSON added in v0.14.0 

func (authority LegacyRuntimeAuthority) MarshalJSON() ([]byte, error)

func (LegacyRuntimeAuthority) ProviderUUID added in v0.14.0 

func (authority LegacyRuntimeAuthority) ProviderUUID() string

func (LegacyRuntimeAuthority) Tenant added in v0.14.0 

func (authority LegacyRuntimeAuthority) Tenant() string

func (*LegacyRuntimeAuthority) UnmarshalJSON added in v0.14.0 

func (authority *LegacyRuntimeAuthority) UnmarshalJSON(data []byte) error

type LegacyRuntimeAuthorityFreeze added in v0.14.0 

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

LegacyRuntimeAuthorityFreeze is the only input that can persist a v0.13 callback principal. It pairs an observation, the tokenless identity read from a validated surviving cohort, with the exact active release it was made against, and it can exist only while that release has no durable runtime authority. Once recorded, the authority is a fact that nothing re-persists: replaying it against a history that has since gained maintenance rows is what left every maintained v0.13 lease unable to re-provision (ENG-1313). The zero value is invalid.

func FreezeLegacyRuntimeAuthority added in v0.14.0 

func FreezeLegacyRuntimeAuthority(
	leaseUUID string,
	active Release,
	observed LegacyRuntimeAuthority,
) (LegacyRuntimeAuthorityFreeze, error)

FreezeLegacyRuntimeAuthority mints the freeze for an authority observed on the complete cohort of an active, fully backfilled v0.13 release that has no durable runtime authority yet. A release that already carries one is refused: its recorded authority needs no freeze.

type MaintenanceAppendClaim added in v0.14.0 

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

MaintenanceAppendClaim is the only authority ReleaseStore accepts for a new maintenance generation. It can be constructed only after the callback WAL durably records that cancellation is no longer legal.

func (MaintenanceAppendClaim) Intent added in v0.14.0 

func (c MaintenanceAppendClaim) Intent() MaintenanceIntentClaim

func (MaintenanceAppendClaim) Valid added in v0.14.0 

func (c MaintenanceAppendClaim) Valid() bool

type MaintenanceCompensationSubject added in v0.14.0 

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

MaintenanceCompensationSubject authorizes only replay of the durably captured source of one failed, uncommitted target. It cannot be used as a normal target execution or cleanup subject. Its copies share the execution protocol's one-shot, callback-scoped mutation capability.

func (MaintenanceCompensationSubject) FailedTarget added in v0.14.0 

func (s MaintenanceCompensationSubject) FailedTarget() MaintenancePhysicalSubject

FailedTarget supplies only exact retirement/diagnostic authority. It cannot authorize source creation; that requires MaintenanceCompensationSubject.

func (MaintenanceCompensationSubject) Intent added in v0.14.0 

func (s MaintenanceCompensationSubject) Intent() MaintenanceIntentClaim

func (MaintenanceCompensationSubject) Plan added in v0.14.0 

func (s MaintenanceCompensationSubject) Plan() []byte

Plan is a detached observation; only the construction-bound decoder and compensation sink consume it, together with this exact subject.

func (MaintenanceCompensationSubject) SourceLaunchRequired added in v0.14.0 

func (subject MaintenanceCompensationSubject) SourceLaunchRequired() bool

SourceLaunchRequired distinguishes a never-issued compensation launch from a prior request which may still reach Docker. The latter is observation-only.

func (MaintenanceCompensationSubject) SourceRelease added in v0.14.0 

func (s MaintenanceCompensationSubject) SourceRelease() (Release, bool)

func (MaintenanceCompensationSubject) TargetRelease added in v0.14.0 

func (s MaintenanceCompensationSubject) TargetRelease() (Release, bool)

func (MaintenanceCompensationSubject) Valid added in v0.14.0 

func (s MaintenanceCompensationSubject) Valid() bool

type MaintenanceExecutionAmbiguous added in v0.14.0 

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

MaintenanceExecutionAmbiguous grants no terminal authority. Recovery must classify the exact target from strict inventory before another transition.

func (MaintenanceExecutionAmbiguous) Cause added in v0.14.0 

func (outcome MaintenanceExecutionAmbiguous) Cause() error

func (MaintenanceExecutionAmbiguous) Error added in v0.14.0 

func (outcome MaintenanceExecutionAmbiguous) Error() string

func (MaintenanceExecutionAmbiguous) Valid added in v0.14.0 

func (outcome MaintenanceExecutionAmbiguous) Valid() bool

type MaintenanceExecutionClaim added in v0.14.0 

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

type MaintenanceExecutionFailure added in v0.14.0 

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

func (MaintenanceExecutionFailure) Cause added in v0.14.0 

func (outcome MaintenanceExecutionFailure) Cause() error

func (MaintenanceExecutionFailure) SourceRecovered added in v0.14.0 

func (outcome MaintenanceExecutionFailure) SourceRecovered() bool

SourceRecovered reports the only failure shape which is safe to project back to Ready: strict inventory attested the complete previous generation.

func (MaintenanceExecutionFailure) Valid added in v0.14.0 

func (outcome MaintenanceExecutionFailure) Valid() bool

type MaintenanceExecutionOutcome added in v0.14.0 

type MaintenanceExecutionOutcome interface {
	// contains filtered or unexported methods
}

type MaintenanceExecutionPhase added in v0.14.0 

type MaintenanceExecutionPhase uint8

MaintenanceExecutionPhase is the durable causal phase of one replacement. The closed values prevent Docker recovery from turning a missing legacy bool into caller-selected evidence that no physical effect could have occurred. 

const (
	MaintenanceExecutionBeforeEffects MaintenanceExecutionPhase
	MaintenanceExecutionStarted
)

type MaintenanceExecutionSuccess added in v0.14.0 

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

MaintenanceExecutionSuccess and MaintenanceExecutionFailure are the two terminal physical observations produced by ExecuteMaintenance. Their fields are private and bind the exact coordinator and target generation; an intent or freshly appended target alone is not terminal authority.

func (MaintenanceExecutionSuccess) Valid added in v0.14.0 

func (outcome MaintenanceExecutionSuccess) Valid() bool

type MaintenanceExpiredError added in v0.14.0 

type MaintenanceExpiredError struct {
	LeaseUUID string
	HighWater time.Time
}

MaintenanceExpiredError carries the admission high-water mark the refused command was older than.

func (*MaintenanceExpiredError) Error added in v0.14.0 

func (e *MaintenanceExpiredError) Error() string

func (*MaintenanceExpiredError) Unwrap added in v0.14.0 

func (e *MaintenanceExpiredError) Unwrap() []error

type MaintenanceFailedReceiptAbsent added in v0.14.0 

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

func (MaintenanceFailedReceiptAbsent) LeaseUUID added in v0.14.0 

func (e MaintenanceFailedReceiptAbsent) LeaseUUID() string

func (MaintenanceFailedReceiptAbsent) MaintenanceID added in v0.14.0 

func (e MaintenanceFailedReceiptAbsent) MaintenanceID() MaintenanceID

func (MaintenanceFailedReceiptAbsent) Valid added in v0.14.0 

func (e MaintenanceFailedReceiptAbsent) Valid() bool

type MaintenanceID added in v0.14.0 

type MaintenanceID = maintenanceid.ID

MaintenanceID is the opaque caller-issued replacement-generation identity shared by the write-ahead intent, target release, and every replacement container.

type MaintenanceIntentAdmission added in v0.14.0 

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

MaintenanceIntentAdmission classifies one request as newly created, existing, or completed. Only Created carries a MaintenanceIntentDispatch; replay classifications are mutation-capability-free by construction.

func (MaintenanceIntentAdmission) CreatedDispatch added in v0.14.0 

func (a MaintenanceIntentAdmission) CreatedDispatch() (MaintenanceIntentDispatch, bool)

CreatedDispatch returns first-dispatch authority only for the transaction that created the durable maintenance intent. Existing and completed replay classifications cannot be converted into mutation authority.

func (MaintenanceIntentAdmission) Disposition added in v0.14.0 

func (a MaintenanceIntentAdmission) Disposition() MaintenanceIntentAdmissionDisposition

Disposition reports the journal-issued replay classification. It is intentionally read-only: sibling packages cannot relabel an Existing replay as Created and turn its precise intent snapshot back into append authority.

func (MaintenanceIntentAdmission) LeaseUUID added in v0.14.0 

func (a MaintenanceIntentAdmission) LeaseUUID() string

func (MaintenanceIntentAdmission) MaintenanceID added in v0.14.0 

func (a MaintenanceIntentAdmission) MaintenanceID() MaintenanceID

func (MaintenanceIntentAdmission) TargetRelease added in v0.14.0 

func (a MaintenanceIntentAdmission) TargetRelease() Release

type MaintenanceIntentAdmissionDisposition added in v0.14.0 

type MaintenanceIntentAdmissionDisposition uint8

MaintenanceIntentAdmissionDisposition distinguishes new authority from exact request replay. Every non-Created replay disposition is capability-free: the caller must not start another substrate mutation. CompletedSuperseded is additionally a refusal to reinstall an older update payload. 

const (
	MaintenanceIntentAdmissionNone MaintenanceIntentAdmissionDisposition = iota
	MaintenanceIntentAdmissionCreated
	MaintenanceIntentAdmissionExisting
	MaintenanceIntentAdmissionCompleted
	// MaintenanceIntentAdmissionCompletedSuperseded means this exact update
	// completed, but a later update generation is already durable. The backend
	// must acknowledge that it will not repeat substrate work while refusing to
	// let the provider reinstall this older payload as current desired state.
	MaintenanceIntentAdmissionCompletedSuperseded
)

type MaintenanceIntentCandidate added in v0.14.0 

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

MaintenanceIntentCandidate is a store-minted, immutable admission capability. Its fields and issuer are private so sibling packages cannot combine a request replay identity with a different target callback or pass a candidate to a journal from another storage lineage. The zero value is invalid.

func (MaintenanceIntentCandidate) Request added in v0.14.0 

func (candidate MaintenanceIntentCandidate) Request() MaintenanceRequestAuthority

type MaintenanceIntentClaim added in v0.14.0 

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

MaintenanceIntentClaim is an opaque precise recovery and settlement capability for one journal row. It deliberately cannot append a Release or cancel admission: those phase-specific authorities have distinct types.

func (MaintenanceIntentClaim) Backend added in v0.14.0 

func (c MaintenanceIntentClaim) Backend() string

func (MaintenanceIntentClaim) BackendStorageID added in v0.14.0 

func (c MaintenanceIntentClaim) BackendStorageID() backendidentity.ID

func (MaintenanceIntentClaim) CallbackURL added in v0.14.0 

func (c MaintenanceIntentClaim) CallbackURL() string

func (MaintenanceIntentClaim) CreatedAt added in v0.14.0 

func (c MaintenanceIntentClaim) CreatedAt() time.Time

func (MaintenanceIntentClaim) ExecutionPhase added in v0.14.0 

func (c MaintenanceIntentClaim) ExecutionPhase() MaintenanceExecutionPhase

func (MaintenanceIntentClaim) Kind added in v0.14.0 

func (c MaintenanceIntentClaim) Kind() MaintenanceIntentKind

func (MaintenanceIntentClaim) LeaseUUID added in v0.14.0 

func (c MaintenanceIntentClaim) LeaseUUID() string

func (MaintenanceIntentClaim) LifecycleCallbackURL added in v0.14.0 

func (c MaintenanceIntentClaim) LifecycleCallbackURL() string

func (MaintenanceIntentClaim) MaintenanceID added in v0.14.0 

func (c MaintenanceIntentClaim) MaintenanceID() MaintenanceID

func (MaintenanceIntentClaim) MatchesIntent added in v0.14.0 

func (c MaintenanceIntentClaim) MatchesIntent(other MaintenanceIntentClaim) bool

MatchesIntent reports whether both claims name the same immutable maintenance generation in the same exact open journal pair. The execution phase and row digest are deliberately normalized: StartMaintenanceExecution advances that one bit before a terminal proof is minted, while preserving every identity, request, source, and bound-target field.

func (MaintenanceIntentClaim) ProviderUUID added in v0.14.0 

func (c MaintenanceIntentClaim) ProviderUUID() string

func (MaintenanceIntentClaim) SourceRelease added in v0.14.0 

func (c MaintenanceIntentClaim) SourceRelease() ReleaseClaim

func (MaintenanceIntentClaim) TargetRelease added in v0.14.0 

func (c MaintenanceIntentClaim) TargetRelease() Release

func (MaintenanceIntentClaim) Tenant added in v0.14.0 

func (c MaintenanceIntentClaim) Tenant() string

func (MaintenanceIntentClaim) Valid added in v0.14.0 

func (c MaintenanceIntentClaim) Valid() bool

type MaintenanceIntentDispatch added in v0.14.0 

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

MaintenanceIntentDispatch is the opaque, store-issued authority to perform the first external work for a newly-created maintenance intent. Exact replay admissions deliberately carry no value of this type. Copies become stale as soon as StartMaintenanceAppend advances the durable phase.

func (MaintenanceIntentDispatch) LeaseUUID added in v0.14.0 

func (d MaintenanceIntentDispatch) LeaseUUID() string

func (MaintenanceIntentDispatch) MaintenanceID added in v0.14.0 

func (d MaintenanceIntentDispatch) MaintenanceID() MaintenanceID

func (MaintenanceIntentDispatch) TargetRelease added in v0.14.0 

func (d MaintenanceIntentDispatch) TargetRelease() Release

func (MaintenanceIntentDispatch) Valid added in v0.14.0 

func (d MaintenanceIntentDispatch) Valid() bool

type MaintenanceIntentKind added in v0.14.0 

type MaintenanceIntentKind string

MaintenanceIntentKind identifies the replacement command being journaled. 

const (
	MaintenanceIntentRestart      MaintenanceIntentKind = "restart"
	MaintenanceIntentUpdate       MaintenanceIntentKind = "update"
	MaintenanceIntentCustomDomain MaintenanceIntentKind = "custom_domain"
	// MaintenanceIntentRuntimeRefresh is the provider's own redeploy of a
	// healthy lease, unchanged, so its containers are recreated under the
	// current container runtime contract. Only an operator starts one.
	MaintenanceIntentRuntimeRefresh MaintenanceIntentKind = "runtime_refresh"
)

func (MaintenanceIntentKind) Valid added in v0.14.0 

func (k MaintenanceIntentKind) Valid() bool

Valid reports whether k is a maintenance kind this journal records. Every journal validator consults it, so a kind is accepted everywhere or nowhere: the receipt window that bounds it is the single list of known kinds.

type MaintenancePhysicalEvidence added in v0.14.0 

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

MaintenancePhysicalEvidence is an opaque closed value algebra. Its private tag selects exactly one concrete payload, so callers cannot forge a mixed or typed-nil result. The zero value is invalid.

func NewMaintenanceCleanupSourceFailed added in v0.14.0 

func NewMaintenanceCleanupSourceFailed(
	subject MaintenancePhysicalSubject,
	containerIDs []string,
	serviceContainers map[string][]string,
) (MaintenancePhysicalEvidence, error)

NewMaintenanceCleanupSourceFailed attests a complete, exactly identified source cohort whose runtime is definitively unready after target cleanup. Ordinary inspection and live execution cannot use this constructor to bypass compensation or convert uncertain readiness into terminal failure.

func NewMaintenanceCompensationSourceFailed added in v0.14.0 

func NewMaintenanceCompensationSourceFailed(subject MaintenanceCompensationSubject, ids []string, services map[string][]string) (MaintenancePhysicalEvidence, error)

NewMaintenanceCompensationSourceFailed is available only to the bound compensation classifier after the source launch settled durably. An unhealthy source after an ambiguous create/start cannot manufacture this terminal fact.

func NewMaintenanceFailedReceiptAbsent added in v0.14.0 

func NewMaintenanceFailedReceiptAbsent(
	subject MaintenancePhysicalSubject,
) (MaintenancePhysicalEvidence, error)

func NewMaintenanceSourceReady added in v0.14.0 

func NewMaintenanceSourceReady(
	subject MaintenancePhysicalSubject,
	containerIDs []string,
	serviceContainers map[string][]string,
) (MaintenancePhysicalEvidence, error)

func NewMaintenanceTargetAbsent added in v0.14.0 

func NewMaintenanceTargetAbsent(subject MaintenancePhysicalSubject) (MaintenancePhysicalEvidence, error)

func NewMaintenanceTargetDivergent added in v0.14.0 

func NewMaintenanceTargetDivergent(
	subject MaintenancePhysicalSubject,
	containerIDs []string,
	serviceContainers map[string][]string,
) (MaintenancePhysicalEvidence, error)

func NewMaintenanceTargetReady added in v0.14.0 

func NewMaintenanceTargetReady(
	subject MaintenancePhysicalSubject,
	containerIDs []string,
	serviceContainers map[string][]string,
) (MaintenancePhysicalEvidence, error)

type MaintenancePhysicalSubject added in v0.14.0 

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

MaintenancePhysicalSubject is the exact target and source authority returned by the transaction which advances one maintenance intent to Started.

func (MaintenancePhysicalSubject) FailedReceiptCleanup added in v0.14.0 

func (subject MaintenancePhysicalSubject) FailedReceiptCleanup() (FailedMaintenanceReceipt, bool)

func (MaintenancePhysicalSubject) Intent added in v0.14.0 

func (subject MaintenancePhysicalSubject) Intent() MaintenanceIntentClaim

func (MaintenancePhysicalSubject) LeaseUUID added in v0.14.0 

func (subject MaintenancePhysicalSubject) LeaseUUID() string

func (MaintenancePhysicalSubject) MaintenanceID added in v0.14.0 

func (subject MaintenancePhysicalSubject) MaintenanceID() MaintenanceID

func (MaintenancePhysicalSubject) RecoveryCleanup added in v0.14.0 

func (subject MaintenancePhysicalSubject) RecoveryCleanup() bool

RecoveryCleanup distinguishes the construction-bound destructive recovery handler from ordinary maintenance execution and read-only recovery.

func (MaintenancePhysicalSubject) SourceRelease added in v0.14.0 

func (subject MaintenancePhysicalSubject) SourceRelease() (Release, bool)

func (MaintenancePhysicalSubject) TargetRelease added in v0.14.0 

func (subject MaintenancePhysicalSubject) TargetRelease() (Release, bool)

func (MaintenancePhysicalSubject) Valid added in v0.14.0 

func (subject MaintenancePhysicalSubject) Valid() bool

type MaintenanceReceiptCapacityError added in v0.14.0 

type MaintenanceReceiptCapacityError struct {
	LeaseUUID string
	Limit     uint64
}

MaintenanceReceiptCapacityError preserves whether the lease-local or shared journal-wide receipt budget refused admission. It matches the coded capacity protocol so the refusal is definitive before substrate mutation.

func (*MaintenanceReceiptCapacityError) Error added in v0.14.0 

func (e *MaintenanceReceiptCapacityError) Error() string

func (*MaintenanceReceiptCapacityError) Unwrap added in v0.14.0 

func (e *MaintenanceReceiptCapacityError) Unwrap() []error

type MaintenanceReleaseActive added in v0.14.0 

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

MaintenanceReleaseActive is store-issued proof that the exact bound target generation is currently active. Its fields are private and bind both open journals, the precise maintenance intent, and the terminal release bytes. Copies are safe because settlement rechecks liveness under the pair gate.

func (MaintenanceReleaseActive) Intent added in v0.14.0 

func (proof MaintenanceReleaseActive) Intent() MaintenanceIntentClaim

func (MaintenanceReleaseActive) LeaseUUID added in v0.14.0 

func (proof MaintenanceReleaseActive) LeaseUUID() string

func (MaintenanceReleaseActive) MaintenanceID added in v0.14.0 

func (proof MaintenanceReleaseActive) MaintenanceID() MaintenanceID

func (MaintenanceReleaseActive) MatchesIntent added in v0.14.0 

func (proof MaintenanceReleaseActive) MatchesIntent(claim MaintenanceIntentClaim) bool

MatchesIntent reports whether this terminal proof completes the exact immutable maintenance generation named by claim. The proof necessarily carries the post-effect successor of the actor's pre-effect claim.

func (MaintenanceReleaseActive) TargetReady added in v0.14.0 

func (proof MaintenanceReleaseActive) TargetReady() (MaintenanceTargetReady, bool)

func (MaintenanceReleaseActive) TargetRelease added in v0.14.0 

func (proof MaintenanceReleaseActive) TargetRelease() (Release, bool)

TargetRelease returns the exact committed maintenance generation. The intent's pre-append target deliberately has Version zero; callers updating a live projection must use this proof-bound copy after activation instead.

func (MaintenanceReleaseActive) Valid added in v0.14.0 

func (proof MaintenanceReleaseActive) Valid() bool

Valid reports whether the active proof has a complete opaque shape. Durable liveness and exact journal identity are rechecked by MaintenanceSettlement.

func (MaintenanceReleaseActive) Version added in v0.14.0 

func (proof MaintenanceReleaseActive) Version() int

type MaintenanceReleaseClaim added in v0.14.0 

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

MaintenanceReleaseClaim is the exact target-generation capability returned by AppendMaintenance or recovery lookup. Its immutable digest deliberately excludes terminal state fields, so the same claim remains valid across the deploying -> active/failed transition and cannot match a different cohort.

func (MaintenanceReleaseClaim) Digest added in v0.14.0 

func (c MaintenanceReleaseClaim) Digest() [sha256.Size]byte

func (MaintenanceReleaseClaim) Intent added in v0.14.0 

func (c MaintenanceReleaseClaim) Intent() MaintenanceIntentClaim

func (MaintenanceReleaseClaim) LeaseUUID added in v0.14.0 

func (c MaintenanceReleaseClaim) LeaseUUID() string

func (MaintenanceReleaseClaim) MaintenanceID added in v0.14.0 

func (c MaintenanceReleaseClaim) MaintenanceID() MaintenanceID

func (MaintenanceReleaseClaim) Valid added in v0.14.0 

func (c MaintenanceReleaseClaim) Valid() bool

func (MaintenanceReleaseClaim) Version added in v0.14.0 

func (c MaintenanceReleaseClaim) Version() int

type MaintenanceReleaseFailure added in v0.14.0 

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

MaintenanceReleaseFailure is store-issued proof that the exact maintenance target is terminal failed, or that no target was ever appended. A zero terminal claim denotes the latter; callers cannot manufacture either form.

func (MaintenanceReleaseFailure) Intent added in v0.14.0 

func (proof MaintenanceReleaseFailure) Intent() MaintenanceIntentClaim

func (MaintenanceReleaseFailure) LeaseUUID added in v0.14.0 

func (proof MaintenanceReleaseFailure) LeaseUUID() string

func (MaintenanceReleaseFailure) MaintenanceID added in v0.14.0 

func (proof MaintenanceReleaseFailure) MaintenanceID() MaintenanceID

func (MaintenanceReleaseFailure) MatchesIntent added in v0.14.0 

func (proof MaintenanceReleaseFailure) MatchesIntent(claim MaintenanceIntentClaim) bool

MatchesIntent reports whether this terminal proof completes the exact immutable maintenance generation named by claim.

func (MaintenanceReleaseFailure) PhysicalEvidence added in v0.14.0 

func (proof MaintenanceReleaseFailure) PhysicalEvidence() (MaintenancePhysicalEvidence, bool)

PhysicalEvidence returns the strict source/target classification which produced this terminal failure. Callback-only reconstructed proofs omit it.

func (MaintenanceReleaseFailure) SourceProjection added in v0.14.0 

func (proof MaintenanceReleaseFailure) SourceProjection() (Release, []string, map[string][]string, bool)

SourceProjection exposes the exact observed source cohort after failed maintenance, including an unhealthy or incomplete compensated source. It is a runtime observation, not readiness authority; only SourceReady supplies that proof. Refusal and callback-only proofs cannot supply a projection.

func (MaintenanceReleaseFailure) SourceReady added in v0.14.0 

func (proof MaintenanceReleaseFailure) SourceReady() (MaintenanceSourceReady, bool)

SourceReady exposes only the complete source cohort attested by this exact failed maintenance. Refusal and callback-only proofs cannot supply a runtime projection or claim that a recreated source is ready.

func (MaintenanceReleaseFailure) Valid added in v0.14.0 

func (proof MaintenanceReleaseFailure) Valid() bool

Valid reports whether the failure proof has one complete sealed variant.

type MaintenanceRequestAuthority added in v0.14.0 

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

MaintenanceRequestAuthority is the opaque, immutable identity of the wire request. It is valid only for the exact CallbackStore instance that issued it; reopening the same file requires minting fresh process-local authority. It can be constructed before any mutable provision/release read, so a completed retry never depends on reconstructing its now-superseded source generation. Payload bytes are reduced to SHA-256 at construction.

func (MaintenanceRequestAuthority) AdmittedAt added in v0.14.0 

func (a MaintenanceRequestAuthority) AdmittedAt() time.Time

func (MaintenanceRequestAuthority) Backend added in v0.14.0 

func (a MaintenanceRequestAuthority) Backend() string

func (MaintenanceRequestAuthority) BackendStorageID added in v0.14.0 

func (a MaintenanceRequestAuthority) BackendStorageID() backendidentity.ID

func (MaintenanceRequestAuthority) CallbackURL added in v0.14.0 

func (a MaintenanceRequestAuthority) CallbackURL() string

func (MaintenanceRequestAuthority) Kind added in v0.14.0 

func (a MaintenanceRequestAuthority) Kind() MaintenanceIntentKind

func (MaintenanceRequestAuthority) LeaseUUID added in v0.14.0 

func (a MaintenanceRequestAuthority) LeaseUUID() string

func (MaintenanceRequestAuthority) MaintenanceID added in v0.14.0 

func (a MaintenanceRequestAuthority) MaintenanceID() MaintenanceID

func (MaintenanceRequestAuthority) Valid added in v0.14.0 

func (a MaintenanceRequestAuthority) Valid() bool

type MaintenanceSettlement added in v0.14.0 

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

MaintenanceSettlement is the construction-bound handoff between the callback write-ahead journal and the release journal for restart, update, and custom-domain replacement. Every maintenance release mutation and its terminal callback settlement crosses this exact pair while holding the callback journal's per-lease transition gate. The zero value is invalid.

func NewMaintenanceSettlement added in v0.14.0 

func NewMaintenanceSettlement(
	callbacks *CallbackStore,
	releases *ReleaseStore,
) (*MaintenanceSettlement, error)

NewMaintenanceSettlement binds the exact open journal instances which jointly own maintenance state. Matching names alone are insufficient: the journals must share both the immutable storage identity and the same backend-lifetime storage-authority gate.

func (*MaintenanceSettlement) ActivateMaintenance added in v0.14.0 

func (s *MaintenanceSettlement) ActivateMaintenance(
	outcome MaintenanceExecutionSuccess,
) (MaintenanceReleaseActive, error)

ActivateMaintenance consumes physical-success evidence for one exact replacement generation. Replaying the same outcome after commit is idempotent.

func (*MaintenanceSettlement) AppendMaintenance added in v0.14.0 

func (s *MaintenanceSettlement) AppendMaintenance(
	appendClaim MaintenanceAppendClaim,
) (MaintenanceReleaseClaim, error)

AppendMaintenance appends the exact MaintenanceID-bearing deploying target only while the source claim still names the active release. The returned capability includes the store-assigned version and immutable target digest.

func (*MaintenanceSettlement) BeginMaintenanceIntent added in v0.14.0 

func (s *MaintenanceSettlement) BeginMaintenanceIntent(
	candidate MaintenanceIntentCandidate,
) (MaintenanceIntentAdmission, error)

func (*MaintenanceSettlement) BindMaintenanceIntentTarget added in v0.14.0 

func (s *MaintenanceSettlement) BindMaintenanceIntentTarget(
	target MaintenanceReleaseClaim,
) (MaintenanceReleaseClaim, error)

BindMaintenanceIntentTarget records the exact store-assigned target version and immutable release digest after AppendMaintenance. It returns the refreshed target capability, not a detached intent plus the now-stale input target: anything allowed to cross the physical-effect boundary therefore carries the bound journal generation by construction. A crash before this bind is recoverable by searching the release history for MaintenanceID.

func (*MaintenanceSettlement) CancelMaintenanceIntent added in v0.14.0 

func (s *MaintenanceSettlement) CancelMaintenanceIntent(dispatch MaintenanceIntentDispatch) error

CancelMaintenanceIntent removes only the exact pre-append intent when no target release or substrate mutation was accepted. StartMaintenanceAppend rewrites the row, so every copied dispatch becomes a stale CAS capability.

func (*MaintenanceSettlement) CapturedMaintenanceSource added in v0.14.0 

func (s *MaintenanceSettlement) CapturedMaintenanceSource(subject MaintenancePhysicalSubject) ([]byte, error)

CapturedMaintenanceSource returns the source execution plan that subject's execution captured before any target effect, while its target is still the one executing. A runtime refresh binds its target images to it: the refresh recreates exactly what the source ran.

func (*MaintenanceSettlement) CheckAppendMaintenanceCapacity added in v0.14.0 

func (s *MaintenanceSettlement) CheckAppendMaintenanceCapacity(
	dispatch MaintenanceIntentDispatch,
) error

CheckAppendMaintenanceCapacity proves that the exact source is still active and that both terminal forms of target fit before any substrate mutation. The check is advisory, but it still consumes pair-bound dispatch authority so a replay or a claim from a reopened journal cannot reserve capacity.

func (*MaintenanceSettlement) ClaimLatestActive added in v0.14.0 

func (s *MaintenanceSettlement) ClaimLatestActive(
	leaseUUID string,
) (Release, MaintenanceSourceClaim, error)

ClaimLatestActive returns the active release and the only source capability accepted by this maintenance protocol. The capability is bound to the exact open ReleaseStore, so a claim from another file or a prior open cannot be admitted even when its bytes happen to be identical.

func (*MaintenanceSettlement) CleanupFailedMaintenanceReceipt added in v0.14.0 

func (s *MaintenanceSettlement) CleanupFailedMaintenanceReceipt(
	ctx context.Context,
	scope LeaseRecoveryScope,
	receipt FailedMaintenanceReceipt,
) (FailedMaintenanceCleanupProof, error)

CleanupFailedMaintenanceReceipt invokes only the construction-bound late-arrival cleanup workflow for one exact permanent failure receipt. A fresh receipt re-read occurs after lease exclusion is held, so neither a caller-selected ID nor a receipt removed by close can authorize mutation.

func (*MaintenanceSettlement) CleanupRecoveredMaintenance added in v0.14.0 

func (s *MaintenanceSettlement) CleanupRecoveredMaintenance(
	ctx context.Context,
	scope LeaseRecoveryScope,
	intent MaintenanceIntentClaim,
) (MaintenanceExecutionOutcome, error)

CleanupRecoveredMaintenance runs the construction-bound destructive recovery handler for one exact current Started maintenance intent. No caller supplies a container ID, project, volume name, or cleanup closure; those are derived from the opaque subject minted by the durable journal re-read.

func (*MaintenanceSettlement) CompensationPending added in v0.14.0 

func (s *MaintenanceSettlement) CompensationPending(intent MaintenanceIntentClaim) (bool, error)

CompensationPending is an observation for recovery routing. The dispatch phase retains unknown remote effects independently of recovery deadlines.

func (*MaintenanceSettlement) CompensationStarted added in v0.14.0 

func (s *MaintenanceSettlement) CompensationStarted(intent MaintenanceIntentClaim) (bool, error)

CompensationStarted is a read-only routing observation. Once restoration starts, a late ready target is never eligible for activation.

func (*MaintenanceSettlement) ConfirmFailedMaintenanceCleanup added in v0.14.0 

func (s *MaintenanceSettlement) ConfirmFailedMaintenanceCleanup(
	proofs []FailedMaintenanceCleanupProof,
	unverifiable []UnverifiableMaintenanceReceipt,
) error

ConfirmFailedMaintenanceCleanup advances, per lease, the completion sequence through which failed, effect-started receipts no longer need to stay in the window for their late-arrival cleanup authority. A receipt qualifies when its cleanup attested absence at least the grace window after it settled, so no in-flight creation can still land, or when it can no longer authorize cleanup at all. The sequence advances only over a contiguous run of qualifying receipts and never moves backward.

func (*MaintenanceSettlement) ExecuteMaintenance added in v0.14.0 

func (s *MaintenanceSettlement) ExecuteMaintenance(
	lifetime MaintenanceWorkerLifetime,
	execution MaintenanceExecutionClaim,
) (outcome MaintenanceExecutionOutcome)

ExecuteMaintenance is the normal physical boundary for restart and update. It does not hold the per-lease journal lock while the external action runs. Only after that action returns does it mint an outcome-specific capability; panic or an explicitly ambiguous mutation outcome leaves the intent and deploying release non-terminal for strict-inventory recovery.

func (*MaintenanceSettlement) FailMaintenance added in v0.14.0 

func (s *MaintenanceSettlement) FailMaintenance(
	outcome MaintenanceExecutionFailure,
	reason backend.Reason,
	message string,
) (MaintenanceReleaseFailure, error)

FailMaintenance records a terminal failure against one exact target and returns the only capability that can settle its maintenance callback as failed. Replaying an already-failed target transitions nothing: it re-proves that target with the replay's own physical evidence.

func (*MaintenanceSettlement) FindMaintenanceRelease added in v0.14.0 

func (s *MaintenanceSettlement) FindMaintenanceRelease(
	leaseUUID string,
	maintenanceID MaintenanceID,
) (Release, MaintenanceReleaseClaim, bool, error)

FindMaintenanceRelease finds by the unguessable maintenance identity rather than by tail position. It returns (zero, zero, false, nil) when no target was ever appended.

func (*MaintenanceSettlement) GetMaintenanceIntent added in v0.14.0 

func (s *MaintenanceSettlement) GetMaintenanceIntent(
	leaseUUID string,
) (MaintenanceIntentClaim, bool, error)

GetMaintenanceIntent reads one exact maintenance claim through the construction-bound callback/release pair used for subsequent recovery.

func (*MaintenanceSettlement) LatestSettledMaintenance added in v0.14.0 

func (s *MaintenanceSettlement) LatestSettledMaintenance(kind MaintenanceIntentKind) ([]SettledMaintenance, error)

LatestSettledMaintenance returns, for every lease with a retained receipt of kind, the receipt that settled last. Receipts are deleted when a lease closes, so only live leases appear.

func (*MaintenanceSettlement) ListFailedMaintenanceReceipts added in v0.14.0 

func (s *MaintenanceSettlement) ListFailedMaintenanceReceipts() (
	[]FailedMaintenanceReceipt,
	[]UnverifiableMaintenanceReceipt,
	error,
)

ListFailedMaintenanceReceipts returns only retained failure records which prove the exact maintenance generation crossed the effect boundary. Each result is joined to its immutable target release under the journal pair's lease lock. A missing or divergent target is returned separately as unverifiable: it grants no cleanup authority, and it never fails the listing for other leases, which one tenant's compacted history could otherwise do to the whole backend. A live close head exclusively owns the lease's physical cleanup, so it cannot issue a competing receipt.

func (*MaintenanceSettlement) ListMaintenanceIntents added in v0.14.0 

func (s *MaintenanceSettlement) ListMaintenanceIntents() ([]MaintenanceIntentClaim, error)

ListMaintenanceIntents reads recovery claims only through their exact callback/release pair, preventing a claim from one callback store from being combined with another release journal after reopen or mis-wiring.

func (*MaintenanceSettlement) NewMaintenanceIntentCandidate added in v0.14.0 

func (s *MaintenanceSettlement) NewMaintenanceIntentCandidate(
	request MaintenanceRequestAuthority,
	source MaintenanceSourceClaim,
	targetRelease Release,
) (MaintenanceIntentCandidate, error)

NewMaintenanceIntentCandidate validates and detaches the complete maintenance transition before BeginMaintenanceIntent may publish it. Exact redelivery is intentionally handled by ProbeMaintenanceIntent, so a replay never needs to manufacture a partial candidate from mutable release state.

func (*MaintenanceSettlement) NewMaintenanceRequestAuthority added in v0.14.0 

func (s *MaintenanceSettlement) NewMaintenanceRequestAuthority(
	maintenanceID MaintenanceID,
	kind MaintenanceIntentKind,
	leaseUUID, callbackURL string,
	payload []byte,
) (MaintenanceRequestAuthority, error)

NewMaintenanceRequestAuthority mints request replay authority from this exact journal pair's verified backend lineage. Production callers therefore supply only wire facts; they cannot pair a request with caller-selected storage or release authority.

func (*MaintenanceSettlement) NewProviderMaintenanceRequestAuthority added in v0.14.0 

func (s *MaintenanceSettlement) NewProviderMaintenanceRequestAuthority(
	maintenanceID MaintenanceID,
	kind MaintenanceIntentKind,
	leaseUUID, callbackURL string,
	payload []byte,
	admittedAt time.Time,
) (MaintenanceRequestAuthority, error)

NewProviderMaintenanceRequestAuthority mints request authority for a provider restart or update carrying the provider's admission stamp. A zero stamp is an older provider's unstamped request.

func (*MaintenanceSettlement) NewRuntimeRefreshIntentCandidate added in v0.14.0 

func (s *MaintenanceSettlement) NewRuntimeRefreshIntentCandidate(
	request MaintenanceRequestAuthority,
	source MaintenanceSourceClaim,
) (MaintenanceIntentCandidate, error)

NewRuntimeRefreshIntentCandidate is the only constructor of a runtime_refresh candidate. A refresh recreates the source's exact workload, so its target is derived from the sealed source release itself: the same payload, and so the same image pins, the same items, resource profiles, lineage and runtime authority. Only the version-zero deploying shape and its creation time are new; no caller supplies any part of the target.

func (*MaintenanceSettlement) ProbeMaintenanceIntent added in v0.14.0 

func (s *MaintenanceSettlement) ProbeMaintenanceIntent(
	request MaintenanceRequestAuthority,
) (MaintenanceIntentAdmissionDisposition, error)

ProbeMaintenanceIntent classifies an exact request without minting mutation authority. It uses the same canonical request digest and live-lease terminal receipt fence as BeginMaintenanceIntent.

func (*MaintenanceSettlement) ProveMaintenanceActive added in v0.14.0 

func (s *MaintenanceSettlement) ProveMaintenanceActive(
	intent MaintenanceIntentClaim,
) (MaintenanceReleaseActive, error)

ProveMaintenanceActive reconstructs success authority after a process crash or an ambiguous callback-journal commit. The target must be bound into the still-current intent and remain the exact active generation.

func (*MaintenanceSettlement) ProveMaintenanceFailure added in v0.14.0 

func (s *MaintenanceSettlement) ProveMaintenanceFailure(
	intent MaintenanceIntentClaim,
) (MaintenanceReleaseFailure, error)

ProveMaintenanceFailure reconstructs failure authority after restart. It grants exactly one of two facts: the bound target is terminal failed, or an unbound intent has no target bearing its MaintenanceID anywhere in history.

func (*MaintenanceSettlement) RecoverMaintenanceAppend added in v0.14.0 

func (s *MaintenanceSettlement) RecoverMaintenanceAppend(
	intent MaintenanceIntentClaim,
) (MaintenanceAppendClaim, error)

RecoverMaintenanceAppend reissues pair-bound append authority from the exact current durable append-started phase after process restart. It never recreates first-dispatch or cancellation authority.

func (*MaintenanceSettlement) RecoverMaintenanceCompensation added in v0.14.0 

func (s *MaintenanceSettlement) RecoverMaintenanceCompensation(ctx context.Context, scope LeaseRecoveryScope, intent MaintenanceIntentClaim) (MaintenanceExecutionOutcome, error)

RecoverMaintenanceCompensation requires the existing exclusive actor/recovery scope and rereads every durable fact before minting its one-shot executor.

func (*MaintenanceSettlement) RecoverMaintenanceExecution added in v0.14.0 

func (s *MaintenanceSettlement) RecoverMaintenanceExecution(
	ctx context.Context,
	scope LeaseRecoveryScope,
	intent MaintenanceIntentClaim,
) (MaintenanceExecutionOutcome, error)

RecoverMaintenanceExecution is the sole post-restart physical classifier. Its strict inventory implementation is fixed when the settlement is bound; callers cannot inject a success/failure verifier.

func (*MaintenanceSettlement) RefuseMaintenanceExecution added in v0.14.0 

func (s *MaintenanceSettlement) RefuseMaintenanceExecution(
	target MaintenanceReleaseClaim,
) (MaintenanceExecutionFailure, error)

RefuseMaintenanceExecution mints pre-effect failure authority. It fails after StartMaintenanceExecution because the exact target intent digest has advanced durably.

func (*MaintenanceSettlement) SettledMaintenanceByID added in v0.14.0 

func (s *MaintenanceSettlement) SettledMaintenanceByID(leaseUUID string, id MaintenanceID) (SettledMaintenance, bool, error)

SettledMaintenanceByID returns the retained receipt of maintenance id on leaseUUID, or found=false while it is unsettled or no longer retained.

func (*MaintenanceSettlement) SnapshotMaintenanceSource added in v0.14.0 

func (s *MaintenanceSettlement) SnapshotMaintenanceSource(
	intent MaintenanceIntentClaim,
) (MaintenanceSourceSnapshot, error)

SnapshotMaintenanceSource reads the exact current active source named by intent and binds the detached bytes to this settlement/store lineage. It cannot silently fall through to a predecessor or successor generation.

func (*MaintenanceSettlement) StartMaintenanceAppend added in v0.14.0 

func (s *MaintenanceSettlement) StartMaintenanceAppend(
	dispatch MaintenanceIntentDispatch,
) (MaintenanceAppendClaim, error)

StartMaintenanceAppend irreversibly consumes first-dispatch authority and advances its maintenance intent to the append-started phase before ReleaseStore can create a target generation. A crash after this transition but before the release append is classified as an interrupted failure by recovery; cancellation authority is never recreated.

func (*MaintenanceSettlement) StartMaintenanceExecution added in v0.14.0 

func (s *MaintenanceSettlement) StartMaintenanceExecution(
	target MaintenanceReleaseClaim,
) (MaintenanceExecutionClaim, error)

StartMaintenanceExecution durably advances a bound target across the irreversible-effect boundary. A copied target from before this transaction becomes stale and can no longer authorize a synchronous refusal.

func (*MaintenanceSettlement) TryBindMaintenanceIntentTarget added in v0.14.0 

func (s *MaintenanceSettlement) TryBindMaintenanceIntentTarget(
	target MaintenanceReleaseClaim,
) (bound MaintenanceReleaseClaim, acquired bool, err error)

TryBindMaintenanceIntentTarget is the recovery-safe form of BindMaintenanceIntentTarget. It never waits behind another journal mutation for this lease; acquired=false leaves the exact unbound intent untouched for the next level-triggered sweep. Callback HTTP owns a separate drain lock and cannot delay this mutation. Live admission uses the blocking form because it does not hold the fleet-wide recovery mutex.

type MaintenanceSourceCapture added in v0.14.0 

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

MaintenanceSourceCapture is an observation from the construction-bound source inspector. An unavailable prior source preserves Restart-from-Failed; it never acquires restoration authority. The zero observation is invalid.

func CapturedMaintenanceSource added in v0.14.0 

func CapturedMaintenanceSource(plan []byte) (MaintenanceSourceCapture, error)

func UnavailableMaintenanceSource added in v0.14.0 

func UnavailableMaintenanceSource() MaintenanceSourceCapture

type MaintenanceSourceClaim added in v0.14.0 

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

MaintenanceSourceClaim is pair-bound authority for the active generation from which a maintenance replacement may be admitted. A plain ReleaseClaim remains useful to internal journal validation, but cannot cross the public maintenance boundary: only MaintenanceSettlement can bind one to its exact open ReleaseStore instance. Reopening the same file therefore requires a fresh claim.

func (MaintenanceSourceClaim) Digest added in v0.14.0 

func (source MaintenanceSourceClaim) Digest() [sha256.Size]byte

func (MaintenanceSourceClaim) LeaseUUID added in v0.14.0 

func (source MaintenanceSourceClaim) LeaseUUID() string

func (MaintenanceSourceClaim) Valid added in v0.14.0 

func (source MaintenanceSourceClaim) Valid() bool

func (MaintenanceSourceClaim) Version added in v0.14.0 

func (source MaintenanceSourceClaim) Version() int

type MaintenanceSourceFailed added in v0.14.0 

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

type MaintenanceSourceReady added in v0.14.0 

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

func (MaintenanceSourceReady) LeaseUUID added in v0.14.0 

func (e MaintenanceSourceReady) LeaseUUID() string

func (MaintenanceSourceReady) MaintenanceID added in v0.14.0 

func (e MaintenanceSourceReady) MaintenanceID() MaintenanceID

func (MaintenanceSourceReady) Projection added in v0.14.0 

func (e MaintenanceSourceReady) Projection() (Release, []string, map[string][]string)

func (MaintenanceSourceReady) Valid added in v0.14.0 

func (e MaintenanceSourceReady) Valid() bool

type MaintenanceSourceSnapshot added in v0.14.0 

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

MaintenanceSourceSnapshot is an immutable observation of the exact active source generation sealed into one maintenance intent. It carries no release mutation authority: consumers may use its cloned topology to validate an actor projection, while terminal settlement still requires a distinct MaintenanceExecution outcome.

The snapshot is pinned by the source release's version and full encoded-row digest. Release history never rewrites a generation's topology or runtime identity; only its terminal status may advance. Callers that need liveness must therefore consume a current settlement proof as well as this snapshot.

func (MaintenanceSourceSnapshot) LeaseUUID added in v0.14.0 

func (snapshot MaintenanceSourceSnapshot) LeaseUUID() string

func (MaintenanceSourceSnapshot) MaintenanceID added in v0.14.0 

func (snapshot MaintenanceSourceSnapshot) MaintenanceID() MaintenanceID

MaintenanceID binds the snapshot to the exact intent that requested the replacement. Two maintenance generations may legitimately share one source release, so lease/source identity alone is not sufficient at consumption.

func (MaintenanceSourceSnapshot) Release added in v0.14.0 

func (snapshot MaintenanceSourceSnapshot) Release() Release

Release returns a detached observation. Mutating it cannot alter the snapshot or any durable journal authority.

func (MaintenanceSourceSnapshot) Valid added in v0.14.0 

func (snapshot MaintenanceSourceSnapshot) Valid() bool

type MaintenanceTargetAbsent added in v0.14.0 

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

func (MaintenanceTargetAbsent) LeaseUUID added in v0.14.0 

func (e MaintenanceTargetAbsent) LeaseUUID() string

func (MaintenanceTargetAbsent) MaintenanceID added in v0.14.0 

func (e MaintenanceTargetAbsent) MaintenanceID() MaintenanceID

func (MaintenanceTargetAbsent) Valid added in v0.14.0 

func (e MaintenanceTargetAbsent) Valid() bool

type MaintenanceTargetDivergent added in v0.14.0 

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

func (MaintenanceTargetDivergent) LeaseUUID added in v0.14.0 

func (e MaintenanceTargetDivergent) LeaseUUID() string

func (MaintenanceTargetDivergent) MaintenanceID added in v0.14.0 

func (e MaintenanceTargetDivergent) MaintenanceID() MaintenanceID

func (MaintenanceTargetDivergent) Projection added in v0.14.0 

func (e MaintenanceTargetDivergent) Projection() (Release, []string, map[string][]string)

func (MaintenanceTargetDivergent) Valid added in v0.14.0 

func (e MaintenanceTargetDivergent) Valid() bool

type MaintenanceTargetReady added in v0.14.0 

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

func (MaintenanceTargetReady) LeaseUUID added in v0.14.0 

func (e MaintenanceTargetReady) LeaseUUID() string

func (MaintenanceTargetReady) MaintenanceID added in v0.14.0 

func (e MaintenanceTargetReady) MaintenanceID() MaintenanceID

func (MaintenanceTargetReady) Projection added in v0.14.0 

func (e MaintenanceTargetReady) Projection() (Release, []string, map[string][]string)

func (MaintenanceTargetReady) Valid added in v0.14.0 

func (e MaintenanceTargetReady) Valid() bool

type MaintenanceWorkerHandoff added in v0.14.0 

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

MaintenanceWorkerHandoff carries one backend-owned lifetime across actor admission. It can issue only one worker, even when commands or handoffs are copied. Target deadline expiry does not revoke the independent cancellation root needed by compensation. The zero handoff is invalid.

func NewMaintenanceWorkerHandoff added in v0.14.0 

func NewMaintenanceWorkerHandoff(shutdown context.Context, timeout time.Duration) (MaintenanceWorkerHandoff, context.CancelFunc)

NewMaintenanceWorkerHandoff is called with the backend shutdown context. The returned cancel discards only an unclaimed handoff. Once accepted, the worker retains cancellation ownership through completion.

func (MaintenanceWorkerHandoff) ClaimWorker added in v0.14.0 

func (h MaintenanceWorkerHandoff) ClaimWorker() (MaintenanceWorkerLifetime, error)

ClaimWorker transfers cancellation ownership exactly once. A canceled handoff remains canceled even when it is claimed after waiting in the actor inbox.

func (MaintenanceWorkerHandoff) Discard added in v0.14.0 

func (h MaintenanceWorkerHandoff) Discard()

Discard releases a rejected or undispatched handoff. A lost HTTP reply or a copied command cannot revoke a worker that has already claimed ownership.

func (MaintenanceWorkerHandoff) TargetContext added in v0.14.0 

func (h MaintenanceWorkerHandoff) TargetContext() context.Context

TargetContext bounds actor admission by the original target deadline without granting access to the independent compensation cancellation root.

func (MaintenanceWorkerHandoff) Valid added in v0.14.0 

func (h MaintenanceWorkerHandoff) Valid() bool

type MaintenanceWorkerLifetime added in v0.14.0 

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

MaintenanceWorkerLifetime is the claimed actor worker's cancellation owner. Both target and compensation budgets derive from its backend shutdown root. Copies share cancellation; no copy can revive a closed worker.

func (MaintenanceWorkerLifetime) Cancel added in v0.14.0 

func (l MaintenanceWorkerLifetime) Cancel()

Cancel revokes target and compensation work and releases the handoff's shutdown registration. The actor invokes it on close and worker completion.

func (MaintenanceWorkerLifetime) TargetContext added in v0.14.0 

func (l MaintenanceWorkerLifetime) TargetContext() context.Context

func (MaintenanceWorkerLifetime) Valid added in v0.14.0 

func (l MaintenanceWorkerLifetime) Valid() bool

type OperationExactAbsent added in v0.14.0 

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

OperationExactAbsent is strict evidence that the exact operation subject has no surviving substrate cohort. It deliberately exposes no projection.

func (OperationExactAbsent) LeaseUUID added in v0.14.0 

func (e OperationExactAbsent) LeaseUUID() string

func (OperationExactAbsent) OperationID added in v0.14.0 

func (e OperationExactAbsent) OperationID() OperationID

func (OperationExactAbsent) Valid added in v0.14.0 

func (e OperationExactAbsent) Valid() bool

type OperationExecutionAmbiguous added in v0.14.0 

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

OperationExecutionAmbiguous records that a guarded worker panicked or reported an ambiguous mutation outcome. It intentionally grants no terminal journal authority. The pending intent remains the recovery fence.

func (OperationExecutionAmbiguous) Cause added in v0.14.0 

func (outcome OperationExecutionAmbiguous) Cause() error

func (OperationExecutionAmbiguous) Error added in v0.14.0 

func (outcome OperationExecutionAmbiguous) Error() string

func (OperationExecutionAmbiguous) Valid added in v0.14.0 

func (outcome OperationExecutionAmbiguous) Valid() bool

type OperationExecutionClaim added in v0.14.0 

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

OperationExecutionClaim is the irreversible-effect capability returned only after the callback WAL durably advances NotStarted -> Started. Copies of the pre-effect candidate become stale at that transaction.

type OperationExecutionFailure added in v0.14.0 

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

OperationExecutionFailure is evidence that the guarded operation worker returned a definitive failure for one exact release candidate. It does not itself assert release absence; CommitOperationFailure rechecks that durable fact while consuming the proof.

func (OperationExecutionFailure) Cause added in v0.14.0 

func (outcome OperationExecutionFailure) Cause() error

func (OperationExecutionFailure) OperationID added in v0.14.0 

func (outcome OperationExecutionFailure) OperationID() OperationID

OperationID is the exact operation this failure settles.

func (OperationExecutionFailure) StartupFailure added in v0.14.0 

func (outcome OperationExecutionFailure) StartupFailure() (OperationStartupFailure, bool)

StartupFailure returns the sealed account of a definite live startup failure (ENG-1125); every other failure has none.

func (OperationExecutionFailure) Valid added in v0.14.0 

func (outcome OperationExecutionFailure) Valid() bool

type OperationExecutionOutcome added in v0.14.0 

type OperationExecutionOutcome interface {
	// contains filtered or unexported methods
}

OperationExecutionOutcome is the sealed result of one guarded physical execution. Sibling packages can inspect the concrete outcome but cannot implement or construct another variant.

type OperationExecutionPhase added in v0.14.0 

type OperationExecutionPhase uint8

OperationExecutionPhase is the durable side-effect boundary of a pending operation. The journal, rather than a caller-supplied boolean, is the only source of this fact. Recovery may refuse an operation in BeforeEffects without inspecting Docker because no substrate capability was ever issued; Started must be treated conservatively until exact substrate evidence is recovered. 

const (
	OperationExecutionStarted OperationExecutionPhase
	OperationExecutionBeforeEffects
)

type OperationExecutionSuccess added in v0.14.0 

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

OperationExecutionSuccess is evidence that the guarded operation worker returned successfully for one exact release candidate. It is deliberately a different type from journal-phase authority: only ExecuteOperation or the strict-inventory recovery minter can create it, and only this value may cross the active-release commit boundary.

func (OperationExecutionSuccess) Valid added in v0.14.0 

func (outcome OperationExecutionSuccess) Valid() bool

type OperationFailed added in v0.14.0 

type OperationFailed interface {
	OperationRecoveryState
	SettledAt() time.Time
	Error() string
	// contains filtered or unexported methods
}

OperationFailed is durable proof that an exact operation settled as failed. It remains queryable after its callback leaves the outbox.

type OperationFailedReceiptAbsent added in v0.14.0 

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

OperationFailedReceiptAbsent is the terminal postcondition for removing a late container owned by one permanent failed-operation receipt. It is deliberately distinct from OperationExactAbsent: it cannot fail or settle a current intent and says nothing about a legitimate successor on the lease.

func (OperationFailedReceiptAbsent) Valid added in v0.14.0 

func (e OperationFailedReceiptAbsent) Valid() bool

type OperationID added in v0.14.0 

type OperationID = operationid.ID

OperationID is the opaque operation authority shared by provider and backend layers. Its zero value is reserved for historical records, legacy observations, and their exact replay; new admission requires a canonical UUIDv4.

type OperationIntentAdmission added in v0.14.0 

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

func (OperationIntentAdmission) CreatedClaim added in v0.14.0 

func (admission OperationIntentAdmission) CreatedClaim() (OperationIntentClaim, bool)

CreatedClaim returns first-dispatch authority only for a newly-created intent. Exact pending and completed replays are capability-free; restart recovery obtains their durable claims through ListOperationIntents.

func (OperationIntentAdmission) Disposition added in v0.14.0 

func (admission OperationIntentAdmission) Disposition() OperationIntentAdmissionDisposition

Disposition reports whether this exact operation was newly admitted or is an idempotent replay. It is read-only so callers cannot relabel a replay as newly-created authority.

type OperationIntentAdmissionDisposition added in v0.14.0 

type OperationIntentAdmissionDisposition uint8

OperationIntentAdmissionDisposition tells a backend whether it owns the newly-created intent and may start work, or whether an exact retry was already durably accepted/completed and should receive an idempotent success. 

const (
	OperationIntentAdmissionNone OperationIntentAdmissionDisposition = iota
	OperationIntentAdmissionCreated
	OperationIntentAdmissionExisting
	OperationIntentAdmissionCompleted
)

type OperationIntentCandidate added in v0.14.0 

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

OperationIntentCandidate is a store-minted, immutable admission capability. The semantic spec is detached from caller-owned buffers, while the private issuer and lineage prevent a candidate assembled for one callback journal from authorizing mutation through another. Its retained runtime authority requires a canonical UUIDv4 operation callback and makes success and refusal representable before Pending can become durable. The zero value is invalid.

type OperationIntentClaim added in v0.14.0 

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

OperationIntentClaim is an opaque, precise capability for resolving one pending durable intent. Its fields are private and its zero value is invalid, eliminating nil and typed-nil interface states while preventing callers from relabelling a terminal outcome as pending authority.

func (OperationIntentClaim) Backend added in v0.14.0 

func (c OperationIntentClaim) Backend() string

func (OperationIntentClaim) BackendStorageID added in v0.14.0 

func (c OperationIntentClaim) BackendStorageID() backendidentity.ID

func (OperationIntentClaim) CallbackURL added in v0.14.0 

func (c OperationIntentClaim) CallbackURL() string

func (OperationIntentClaim) CreatedAt added in v0.14.0 

func (c OperationIntentClaim) CreatedAt() time.Time

func (OperationIntentClaim) EffectiveItems added in v0.14.0 

func (c OperationIntentClaim) EffectiveItems() []backend.LeaseItem

func (OperationIntentClaim) ExecutionPhase added in v0.14.0 

func (c OperationIntentClaim) ExecutionPhase() OperationExecutionPhase

func (OperationIntentClaim) HealthCheckServices added in v0.14.0 

func (c OperationIntentClaim) HealthCheckServices() []string

func (OperationIntentClaim) Items added in v0.14.0 

func (c OperationIntentClaim) Items() []backend.LeaseItem

func (OperationIntentClaim) Kind added in v0.14.0 

func (c OperationIntentClaim) Kind() OperationIntentKind

func (OperationIntentClaim) LeaseUUID added in v0.14.0 

func (c OperationIntentClaim) LeaseUUID() string

func (OperationIntentClaim) LifecycleCallbackURL added in v0.14.0 

func (c OperationIntentClaim) LifecycleCallbackURL() string

func (OperationIntentClaim) Manifest added in v0.14.0 

func (c OperationIntentClaim) Manifest() []byte

func (OperationIntentClaim) OperationID added in v0.14.0 

func (c OperationIntentClaim) OperationID() OperationID

func (OperationIntentClaim) ProviderUUID added in v0.14.0 

func (c OperationIntentClaim) ProviderUUID() string

func (OperationIntentClaim) ResourceProfiles added in v0.14.0 

func (c OperationIntentClaim) ResourceProfiles() []SKUResourceSnapshot

func (OperationIntentClaim) SourceGeneration added in v0.14.0 

func (c OperationIntentClaim) SourceGeneration() int

func (OperationIntentClaim) SourceLeaseUUID added in v0.14.0 

func (c OperationIntentClaim) SourceLeaseUUID() string

func (OperationIntentClaim) Tenant added in v0.14.0 

func (c OperationIntentClaim) Tenant() string

func (OperationIntentClaim) Valid added in v0.14.0 

func (c OperationIntentClaim) Valid() bool

type OperationIntentKind added in v0.14.0 

type OperationIntentKind string

OperationIntentKind identifies the asynchronous operation whose exact completion must survive a backend crash. 

const (
	OperationIntentProvision OperationIntentKind = "provision"
	OperationIntentRestore   OperationIntentKind = "restore"
)

type OperationIntentProbe added in v0.14.0 

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

OperationIntentProbe is store-minted exact authority to recognize a redelivery before mutable SKU, manifest, or restore-source validation. Its storage lineage and issuer are private: callers can ask the journal that owns the lineage to mint a probe, but cannot restamp a probe for another backend or journal. A positive result authorizes only an idempotent acknowledgement, never a new substrate mutation. The zero value is invalid.

func (OperationIntentProbe) CallbackURL added in v0.14.0 

func (probe OperationIntentProbe) CallbackURL() string

func (OperationIntentProbe) LeaseUUID added in v0.14.0 

func (probe OperationIntentProbe) LeaseUUID() string

type OperationIntentSpec added in v0.14.0 

type OperationIntentSpec struct {
	Kind                 OperationIntentKind
	LeaseUUID            string
	CallbackURL          string
	LifecycleCallbackURL string
	Tenant               string
	ProviderUUID         string
	Items                []backend.LeaseItem
	// ResourceProfiles freezes the resource definition used for admission and
	// substrate creation before either can happen. Operation intents are new in
	// v0.14, so unlike Release there is no deployed legacy format without this
	// authority.
	ResourceProfiles []SKUResourceSnapshot
	// EffectiveItems is the exact item metadata emitted to substrate labels.
	// It may differ from desired Items only by omitting a custom domain that
	// ingress configuration, routable-port selection, domain validation, or DNS
	// admission did not authorize for this exact operation.
	EffectiveItems      []backend.LeaseItem
	HealthCheckServices []string
	Manifest            []byte
	SourceLeaseUUID     string
	SourceGeneration    int
}

OperationIntentSpec is the immutable evidence needed to classify an accepted asynchronous operation after restart. CallbackURL and LifecycleCallbackURL must already contain the exact resolved pair; request defaults are applied before constructing this durable authority.

type OperationPhysicalEvidence added in v0.14.0 

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

OperationPhysicalEvidence is an opaque closed value algebra. Keeping its tag and every payload private makes invalid combinations, interface injection, and typed-nil variants unconstructable while the public payload types remain available on terminal projections. The zero value is invalid.

func NewOperationExactAbsent added in v0.14.0 

func NewOperationExactAbsent(subject OperationPhysicalSubject) (OperationPhysicalEvidence, error)

func NewOperationFailedReceiptAbsent added in v0.14.0 

func NewOperationFailedReceiptAbsent(
	subject OperationPhysicalSubject,
) (OperationPhysicalEvidence, error)

func NewOperationStartupFailed added in v0.14.0 

func NewOperationStartupFailed(
	subject OperationPhysicalSubject,
	failure OperationStartupFailure,
) (OperationPhysicalEvidence, error)

NewOperationStartupFailed seals classifier evidence of a definite live startup failure for the exact subject.

func NewOperationTargetReady added in v0.14.0 

func NewOperationTargetReady(
	subject OperationPhysicalSubject,
	containerIDs []string,
	serviceContainers map[string][]string,
) (OperationPhysicalEvidence, error)

NewOperationTargetReady seals a complete projection for the exact subject. Exhaustive physical classification remains construction-bound to the Guard; this constructor only makes the resulting value immutable and lineage-bound.

type OperationPhysicalSubject added in v0.14.0 

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

OperationPhysicalSubject is the immutable substrate identity returned by the same durable transaction which advances an operation to Started. Its pointer backed representation makes it comparable without exposing caller-writable authority. The zero value is invalid.

func (OperationPhysicalSubject) ExpectedRelease added in v0.14.0 

func (subject OperationPhysicalSubject) ExpectedRelease() (Release, bool)

ExpectedRelease returns the detached release topology which strict inventory must classify. It is observation only and carries no commit authority.

func (OperationPhysicalSubject) FailedReceiptCleanup added in v0.14.0 

func (subject OperationPhysicalSubject) FailedReceiptCleanup() (FailedOperationReceipt, bool)

FailedReceiptCleanup identifies the permanent late-arrival cleanup mode and returns its exact sealed receipt. It cannot be set on a live operation subject or substituted after construction.

func (OperationPhysicalSubject) Intent added in v0.14.0 

func (subject OperationPhysicalSubject) Intent() OperationIntentClaim

func (OperationPhysicalSubject) LeaseUUID added in v0.14.0 

func (subject OperationPhysicalSubject) LeaseUUID() string

func (OperationPhysicalSubject) OperationID added in v0.14.0 

func (subject OperationPhysicalSubject) OperationID() OperationID

func (OperationPhysicalSubject) PredecessorRelease added in v0.14.0 

func (subject OperationPhysicalSubject) PredecessorRelease() (Release, bool)

PredecessorRelease returns the exact active generation observed while the operation crossed Started. It is present only for an identity-preserving provision repair and lets the subject-bound facade accept that predecessor's containers without accepting an arbitrary same-lease generation.

func (OperationPhysicalSubject) RecoveryCleanup added in v0.14.0 

func (subject OperationPhysicalSubject) RecoveryCleanup() bool

RecoveryCleanup reports whether this unforgeable subject was minted for the construction-bound destructive recovery workflow rather than ordinary live execution or read-only recovery classification. Callers cannot toggle the bit or replace its candidate.

func (OperationPhysicalSubject) Valid added in v0.14.0 

func (subject OperationPhysicalSubject) Valid() bool

type OperationReceiptCapacityError added in v0.14.0 

type OperationReceiptCapacityError struct {
	LeaseUUID string
	Limit     uint64
}

OperationReceiptCapacityError preserves whether the per-lease or global journal bound refused admission. It matches both ErrOperationReceiptCapacity and backend.ErrInsufficientResources: the first gives operators and tests a precise diagnosis, while the second uses the existing backend protocol's coded, pre-side-effect capacity response.

func (*OperationReceiptCapacityError) Error added in v0.14.0 

func (e *OperationReceiptCapacityError) Error() string

func (*OperationReceiptCapacityError) Unwrap added in v0.14.0 

func (e *OperationReceiptCapacityError) Unwrap() []error

type OperationRecoveryState added in v0.14.0 

type OperationRecoveryState interface {
	Kind() OperationIntentKind
	OperationID() OperationID
	LeaseUUID() string
	CallbackURL() string
	LifecycleCallbackURL() string
	Backend() string
	BackendStorageID() backendidentity.ID
	Tenant() string
	ProviderUUID() string
	Items() []backend.LeaseItem
	ResourceProfiles() []SKUResourceSnapshot
	EffectiveItems() []backend.LeaseItem
	HealthCheckServices() []string
	Manifest() []byte
	SourceLeaseUUID() string
	SourceGeneration() int
	CreatedAt() time.Time
	// contains filtered or unexported methods
}

OperationRecoveryState is the sealed durable state of one exact asynchronous operation. CallbackStore returns the opaque OperationIntentClaim value or one of the two private terminal implementations exposed through OperationSucceeded and OperationFailed. Private representation fields prevent callers from constructing valid proof values or converting one state representation into another.

type OperationReleaseCandidate added in v0.14.0 

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

OperationReleaseCandidate is a store-issued capability to publish the active Release of one exact provision or restore operation. Its fields are private: callers can carry the capability across the substrate mutation, but cannot replace its operation ID, callback routes, principal, topology, sizing, or admission timestamp before the durable success commit.

A candidate is deliberately bound to one open ReleaseStore. After restart a caller must load the operation claim/outcome again and ask the reopened store to mint a fresh candidate. The zero value is invalid.

func (OperationReleaseCandidate) Intent added in v0.14.0 

func (candidate OperationReleaseCandidate) Intent() OperationIntentClaim

Intent returns the immutable operation claim sealed into this candidate. It is observation and routing authority only; it cannot settle either terminal outcome.

type OperationReleaseCommitted added in v0.14.0 

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

OperationReleaseCommitted is durable proof that the exact active Release derived from one pending operation has crossed its ReleaseStore commit boundary. Its zero value is invalid and every field is private: callers may carry the proof to the callback journal, but cannot splice a different operation, release version, or release digest into it.

The proof is intentionally copyable and idempotent. Linearity is enforced by CallbackStore's exact pending-claim CAS, while the durable release version and digest make every copy name the same already-committed generation.

func (OperationReleaseCommitted) LeaseUUID added in v0.14.0 

func (committed OperationReleaseCommitted) LeaseUUID() string

LeaseUUID and OperationID expose only the immutable identity sealed into the proof. They let downstream typed adapters reject a proof for another actor generation without exposing any caller-writable authority fields.

func (OperationReleaseCommitted) MatchesIntent added in v0.14.0 

func (committed OperationReleaseCommitted) MatchesIntent(claim OperationIntentClaim) bool

MatchesIntent reports whether proof and claim name the same immutable operation in the same open journal pair. The execution-phase bit and digest are deliberately not compared: StartOperationExecution advances them while preserving the operation identity this terminal proof completes.

func (OperationReleaseCommitted) OperationID added in v0.14.0 

func (committed OperationReleaseCommitted) OperationID() OperationID

func (OperationReleaseCommitted) Release added in v0.14.0 

func (committed OperationReleaseCommitted) Release() (Release, bool)

func (OperationReleaseCommitted) TargetReady added in v0.14.0 

func (committed OperationReleaseCommitted) TargetReady() (OperationTargetReady, bool)

TargetReady returns the strict cohort sealed by the physical execution which produced this commit. Reconstructed callback-only proofs intentionally omit it; callers needing a runtime projection must recover strict inventory.

func (OperationReleaseCommitted) TargetRelease added in v0.14.0 

func (committed OperationReleaseCommitted) TargetRelease() (Release, bool)

TargetRelease is the exact persisted operation generation. Unlike the pre-commit subject expectation, its Version is the ReleaseStore-assigned positive version sealed by the committed ReleaseClaim.

func (OperationReleaseCommitted) Valid added in v0.14.0 

func (committed OperationReleaseCommitted) Valid() bool

Valid reports whether the proof has a complete store-issued shape. The callback journal additionally checks the exact operation authority before it may consume the proof.

type OperationReleaseUncommitted added in v0.14.0 

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

OperationReleaseUncommitted is a store-issued, short-lived proof that the exact operation has no Release in this journal. Failure settlement rechecks this fact at consumption, so a copied proof cannot race a later successful commit into the contradictory Failed-plus-active state.

func (OperationReleaseUncommitted) CallbackURL added in v0.14.0 

func (uncommitted OperationReleaseUncommitted) CallbackURL() string

func (OperationReleaseUncommitted) Kind added in v0.14.0 

func (uncommitted OperationReleaseUncommitted) Kind() OperationIntentKind

func (OperationReleaseUncommitted) LeaseUUID added in v0.14.0 

func (uncommitted OperationReleaseUncommitted) LeaseUUID() string

func (OperationReleaseUncommitted) LifecycleCallbackURL added in v0.14.0 

func (uncommitted OperationReleaseUncommitted) LifecycleCallbackURL() string

func (OperationReleaseUncommitted) MatchesIntent added in v0.14.0 

func (uncommitted OperationReleaseUncommitted) MatchesIntent(claim OperationIntentClaim) bool

func (OperationReleaseUncommitted) OperationID added in v0.14.0 

func (uncommitted OperationReleaseUncommitted) OperationID() OperationID

func (OperationReleaseUncommitted) Valid added in v0.14.0 

func (uncommitted OperationReleaseUncommitted) Valid() bool

Valid reports whether the uncommitted proof has a complete store-issued shape. Durable absence is always rechecked by the consumer.

type OperationSettlement added in v0.14.0 

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

OperationSettlement is the construction-bound handoff between the callback write-ahead journal and the release journal. Every operation release commit and terminal settlement crosses this pair so the exact pending claim and release fact are checked while holding one shared per-lease transition gate. The zero value is invalid.

func NewOperationSettlement added in v0.14.0 

func NewOperationSettlement(
	callbacks *CallbackStore,
	releases *ReleaseStore,
) (*OperationSettlement, error)

NewOperationSettlement binds the two identity-bound journals which jointly implement an asynchronous provision/restore operation. Aliased or merely lineage-compatible stores are insufficient: proofs name these exact open store instances and are invalid after either instance is replaced.

func (*OperationSettlement) AdmitProvisionManifest added in v0.14.0 

func (s *OperationSettlement) AdmitProvisionManifest(ctx context.Context, lease, tenant, provider string, items []backend.LeaseItem, payload []byte) (ProvisionManifestAdmission, error)

AdmitProvisionManifest keeps new submissions on current tenant policy. A historical exception is available only for the identical active payload, principal and topology, observed under the journal's lease transition lock.

func (*OperationSettlement) BeginOperationIntent added in v0.14.0 

func (s *OperationSettlement) BeginOperationIntent(
	candidate OperationIntentCandidate,
) (OperationIntentAdmission, error)

BeginOperationIntent commits the write-ahead record which grants first dispatch authority for this exact settlement pair.

func (*OperationSettlement) CheckOperationReleaseCapacity added in v0.14.0 

func (s *OperationSettlement) CheckOperationReleaseCapacity(
	candidate OperationReleaseCandidate,
) error

CheckOperationReleaseCapacity proves that the exact candidate currently fits without writing it. CommitOperationSuccess repeats both proof validation and capacity planning inside its write transaction; this method is advisory and is useful only before the first external side effect.

func (*OperationSettlement) CleanupFailedOperationReceipt added in v0.14.0 

func (s *OperationSettlement) CleanupFailedOperationReceipt(
	ctx context.Context,
	scope LeaseRecoveryScope,
	receipt FailedOperationReceipt,
) error

CleanupFailedOperationReceipt executes the same construction-bound physical handler in permanent late-arrival mode. The receipt itself is store-issued and bound to this exact callback journal; a fresh durable re-read confirms it still exists before any mutation capability is minted.

func (*OperationSettlement) CleanupRecoveredOperation added in v0.14.0 

func (s *OperationSettlement) CleanupRecoveredOperation(
	ctx context.Context,
	scope LeaseRecoveryScope,
	claim OperationIntentClaim,
) (OperationExecutionOutcome, error)

CleanupRecoveredOperation runs the construction-bound destructive recovery handler for one exact current Started intent, then returns only evidence from the same executor's exhaustive classifier. The caller supplies no workflow, target IDs, project name, or volume names; all such authority is derived from the opaque subject minted by the durable re-read below.

func (*OperationSettlement) CommitOperationFailure added in v0.14.0 

func (s *OperationSettlement) CommitOperationFailure(
	outcome OperationExecutionFailure,
) (OperationReleaseUncommitted, error)

CommitOperationFailure consumes guarded physical-failure evidence and mints the exact release-absence proof accepted by callback settlement. Absence is rechecked at consumption, so a copied or delayed outcome cannot contradict a concurrently committed success.

func (*OperationSettlement) CommitOperationSuccess added in v0.14.0 

func (s *OperationSettlement) CommitOperationSuccess(
	outcome OperationExecutionSuccess,
) (OperationReleaseCommitted, error)

CommitOperationSuccess consumes guarded physical-success evidence and atomically publishes the exact operation-derived active Release.

func (*OperationSettlement) ExecuteOperation added in v0.14.0 

func (s *OperationSettlement) ExecuteOperation(
	ctx context.Context,
	execution OperationExecutionClaim,
) (outcome OperationExecutionOutcome)

ExecuteOperation is the normal-path physical boundary after Started is durable. Until the substrate guard supplies its opaque tri-state outcome, every non-successful return is deliberately ambiguous; a plain error can never mint terminal failure authority.

func (*OperationSettlement) ListFailedOperationReceipts added in v0.14.0 

func (s *OperationSettlement) ListFailedOperationReceipts() ([]FailedOperationReceipt, error)

ListFailedOperationReceipts returns the permanent exact cleanup fences for operations that settled as failures.

func (*OperationSettlement) ListOperationIntents added in v0.14.0 

func (s *OperationSettlement) ListOperationIntents() ([]OperationIntentClaim, error)

ListOperationIntents returns pending recovery claims from this exact settlement pair.

func (*OperationSettlement) ListOperationRecoveryStates added in v0.14.0 

func (s *OperationSettlement) ListOperationRecoveryStates() ([]OperationRecoveryState, error)

ListOperationRecoveryStates returns every rich operation head, including durable terminal heads that still fence late substrate creation.

func (*OperationSettlement) LookupOperationRecovery added in v0.14.0 

func (s *OperationSettlement) LookupOperationRecovery(
	probe OperationIntentProbe,
) (OperationRecoveryState, error)

LookupOperationRecovery returns the sealed durable state of one exact operation from the coordinator that owns its possible settlement.

func (*OperationSettlement) NewOperationIntentCandidate added in v0.14.0 

func (s *OperationSettlement) NewOperationIntentCandidate(
	spec OperationIntentSpec,
) (OperationIntentCandidate, error)

NewOperationIntentCandidate freezes one operation request against the exact callback/release pair that will later publish its success or failure.

func (*OperationSettlement) NewOperationIntentProbe added in v0.14.0 

func (s *OperationSettlement) NewOperationIntentProbe(
	leaseUUID, callbackURL string,
) (OperationIntentProbe, error)

NewOperationIntentProbe binds an exact redelivery lookup to both journals that own operation settlement. Keeping admission and recovery on the same coordinator as terminal settlement makes a mismatched callback/release pair unrepresentable to backend callers.

func (*OperationSettlement) PrepareOperationRelease added in v0.14.0 

func (s *OperationSettlement) PrepareOperationRelease(
	claim OperationIntentClaim,
) (OperationReleaseCandidate, error)

PrepareOperationRelease validates and detaches the complete active-release authority of a pending operation. The returned capability can be used for a pre-side-effect capacity proof and then crossed through StartOperationExecution.

func (*OperationSettlement) ProbeOperationIntent added in v0.14.0 

func (s *OperationSettlement) ProbeOperationIntent(
	probe OperationIntentProbe,
) (OperationIntentAdmissionDisposition, error)

ProbeOperationIntent classifies an exact redelivery without granting new mutation authority.

func (*OperationSettlement) ProveCommittedOperation added in v0.14.0 

func (s *OperationSettlement) ProveCommittedOperation(
	claim OperationIntentClaim,
) (OperationReleaseCommitted, error)

ProveCommittedOperation reconstructs a success-settlement proof after a crash or an ambiguous callback-journal write. Only the exact currently active Release derived from claim is admissible; an older, superseded, divergent, or absent generation grants no success authority.

func (*OperationSettlement) RecoverOperationExecution added in v0.14.0 

func (s *OperationSettlement) RecoverOperationExecution(
	ctx context.Context,
	scope LeaseRecoveryScope,
	claim OperationIntentClaim,
) (OperationExecutionOutcome, error)

RecoverOperationExecution is the only post-restart physical outcome minter. Its classifier was bound at construction; the caller supplies only context and an exact durable claim and therefore cannot select success or failure.

func (*OperationSettlement) RefuseOperationExecution added in v0.14.0 

func (s *OperationSettlement) RefuseOperationExecution(
	candidate OperationReleaseCandidate,
) (OperationExecutionFailure, error)

RefuseOperationExecution is the only normal-path failure minter before the irreversible boundary. Once StartOperationExecution commits, the candidate's exact row digest is stale and this method fails closed.

func (*OperationSettlement) ReserveProvisionResources added in v0.14.0 

func (s *OperationSettlement) ReserveProvisionResources(
	p *ResourcePool,
	claim OperationIntentClaim,
) (ProvisionAdmission, error)

ReserveProvisionResources derives both generations from their journal authority, then atomically checks and reserves their conservative envelope. Neither an absent predecessor Release nor an existing Failed projection bypasses this admission. No substrate work or actor command is performed.

func (*OperationSettlement) StartOperationExecution added in v0.14.0 

func (s *OperationSettlement) StartOperationExecution(
	candidate OperationReleaseCandidate,
) (OperationExecutionClaim, error)

StartOperationExecution durably crosses the irreversible-effect boundary. The callback-row CAS invalidates every copy of the pre-effect candidate before a Started capability can reach a raw substrate mutator.

type OperationStartupFailed added in v0.14.0 

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

OperationStartupFailed is classifier evidence that a live provision's startup failed definitely and its exact substrate is gone: the classifier re-read the strict inventory, the launch-debt journal and the volume namespace before minting it. It is valid only for the live execution of a provision; recovery can never mint or consume it.

func (OperationStartupFailed) Valid added in v0.14.0 

func (e OperationStartupFailed) Valid() bool

type OperationStartupFailure added in v0.14.0 

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

OperationStartupFailure is the sealed account of one definite provision startup failure (ENG-1125): the provision's launch exchange settled, a container of its cohort then positively failed startup, and the attempt was rolled back exactly. It carries what the lease state machine needs to attribute the failure (what was observed, the substrate's termination of the container, the live provenance of its death, and whether the platform degraded or did not complete the launch), never a cause: attribution happens in the state machine's provision-failure entry action. The zero value is invalid.

func NewOperationStartupFailure added in v0.14.0 

func NewOperationStartupFailure(terms OperationStartupFailureTerms) (OperationStartupFailure, error)

NewOperationStartupFailure seals one startup failure. An exit must carry the substrate's Exited termination (the exit code alone proves nothing: it is an int). An unhealthy container and a container whose start was refused must carry neither a termination nor a death provenance: neither died. A provenance must have been minted for this very container.

func (OperationStartupFailure) Degraded added in v0.14.0 

func (f OperationStartupFailure) Degraded() bool

func (OperationStartupFailure) Detail added in v0.14.0 

func (f OperationStartupFailure) Detail() string

func (OperationStartupFailure) ExitStatus added in v0.14.0 

func (f OperationStartupFailure) ExitStatus() (code int, oomKilled, exited bool)

ExitStatus reports the observed exit code and OOM flag, which only an exit has.

func (OperationStartupFailure) InstanceID added in v0.14.0 

func (f OperationStartupFailure) InstanceID() string

func (OperationStartupFailure) Kind added in v0.14.0 

func (f OperationStartupFailure) Kind() OperationStartupFailureKind

Kind is what the failure observed; zero for the invalid value.

func (OperationStartupFailure) Message added in v0.14.0 

func (f OperationStartupFailure) Message() string

func (OperationStartupFailure) Provenance added in v0.14.0 

func (f OperationStartupFailure) Provenance() failurecause.Provenance

func (OperationStartupFailure) Reason added in v0.14.0 

func (f OperationStartupFailure) Reason() backend.Reason

func (OperationStartupFailure) Service added in v0.14.0 

func (f OperationStartupFailure) Service() string

func (OperationStartupFailure) Termination added in v0.14.0 

func (f OperationStartupFailure) Termination() failurecause.Termination

func (OperationStartupFailure) Valid added in v0.14.0 

func (f OperationStartupFailure) Valid() bool

type OperationStartupFailureKind added in v0.14.0 

type OperationStartupFailureKind uint8

OperationStartupFailureKind is the closed account of what a definite startup failure observed. NewOperationStartupFailure derives it from the validated terms; nothing else produces one. 

const (
	// OperationStartupExited: the container exited and the substrate reported
	// its exit status (ContainerExited).
	OperationStartupExited OperationStartupFailureKind = iota + 1
	// OperationStartupUnhealthy: the container is running and its health check
	// never passed (HealthCheckFailed).
	OperationStartupUnhealthy
	// OperationStartupRefused: the container runtime refused to start the
	// container, which never ran (ContainerStartFailed).
	OperationStartupRefused
)

type OperationStartupFailureTerms added in v0.14.0 

type OperationStartupFailureTerms struct {
	// Reason and Message are the curated tenant surface authored where the
	// failure was observed: ContainerExited for an exit, HealthCheckFailed
	// for a health check that never passed, ContainerStartFailed for a start
	// the container runtime refused.
	Reason  backend.Reason
	Message string
	// Detail is operator-side text (exit status, logs); never tenant-facing.
	Detail     string
	InstanceID string
	Service    string
	// Termination is the substrate adapter's classification of an exited
	// container: failurecause.Exited for an exit with a status. An unhealthy
	// container is still running and has none.
	Termination failurecause.Termination
	// Provenance is the live event stream's account of the container's death,
	// bound to InstanceID, or zero when none was observed.
	Provenance failurecause.Provenance
	ExitCode   int
	OOMKilled  bool
	// Degraded marks a launch the platform did not complete as planned: part
	// of its preparation was skipped (for example, writable-path seeding), or
	// its launch exchange was rejected (Compose reported a failure, or the
	// container runtime refused a Start). Its failure never counts.
	Degraded bool
}

OperationStartupFailureTerms are the observed facts of one startup failure. NewOperationStartupFailure validates them as a whole.

type OperationSucceeded added in v0.14.0 

type OperationSucceeded interface {
	OperationRecoveryState
	SettledAt() time.Time
	// contains filtered or unexported methods
}

OperationSucceeded is durable proof that an exact operation settled successfully. It remains queryable after its callback leaves the outbox.

type OperationTargetReady added in v0.14.0 

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

OperationTargetReady is an exact, complete target-cohort observation.

func (OperationTargetReady) LeaseUUID added in v0.14.0 

func (e OperationTargetReady) LeaseUUID() string

func (OperationTargetReady) OperationID added in v0.14.0 

func (e OperationTargetReady) OperationID() OperationID

func (OperationTargetReady) Projection added in v0.14.0 

func (e OperationTargetReady) Projection() (Release, []string, map[string][]string)

func (OperationTargetReady) Valid added in v0.14.0 

func (e OperationTargetReady) Valid() bool

type PartitionInputs added in v0.11.0 

type PartitionInputs struct {
	Manifest *manifest.StackManifest
}

PartitionInputs carries the close-time artifacts a partition can be extracted from. A struct (not bare params) so future sources extend it without breaking the ExtractPartition signature.

type PartitionSource added in v0.11.0 

type PartitionSource struct {
	Kind PartitionSourceKind
	Key  string // label key or env var name; empty iff Kind == PartitionSourceNone
}

PartitionSource is the parsed retention_partition_source config value.

func ParsePartitionSource added in v0.11.0 

func ParsePartitionSource(s string) (PartitionSource, error)

ParsePartitionSource parses a retention_partition_source config string. Grammar: "" | "manifest.label:<key>" | "manifest.env:<key>". Intended to be called from config validation, so a malformed or unsatisfiable source is a STARTUP failure, never a close-time surprise.

type PartitionSourceKind added in v0.11.0 

type PartitionSourceKind int

PartitionSourceKind enumerates where a retention-partition value is read from at lease close. Future kinds (a reserved manifest field, an on-chain lease field) are additive switch arms; the store/caps machinery never changes with the source. 

const (
	PartitionSourceNone PartitionSourceKind = iota
	PartitionSourceManifestLabel
	PartitionSourceManifestEnv
)

type PendingLeaseMutationHead added in v0.14.0 

type PendingLeaseMutationHead struct {
	Kind      PendingLeaseMutationHeadKind
	LeaseUUID string
	Items     []backend.LeaseItem
}

PendingLeaseMutationHead is one pending lease-mutation head of a stopped callback journal. Items is the volume topology the head owns on its lease: the close's items, or the pending operation's effective items. A maintenance head carries none.

type PendingLeaseMutationHeadKind added in v0.14.0 

type PendingLeaseMutationHeadKind uint8

PendingLeaseMutationHeadKind is the closed kind of a pending lease-mutation head. 

const (
	PendingOperationHead PendingLeaseMutationHeadKind = iota + 1
	PendingMaintenanceHead
	PendingCloseHead
)

type PreparedImageInspection added in v0.14.0 

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

PreparedImageInspection binds a fresh helper identity to an exact live Started origin. It grants no cleanup authority until Reserve persists it inside the helper's admitted creation step.

type ProvisionAdmission added in v0.14.0 

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

ProvisionAdmission binds a pending operation to pool-owned capacity before actor admission. Copies share one state: only an unstarted admission may be aborted, and only matching terminal evidence may release executing capacity. Ambiguity preserves the conservative ledger for ordinary durable recovery.

func (ProvisionAdmission) Abort added in v0.14.0 

func (a ProvisionAdmission) Abort() error

Abort restores the exact pre-admission ledger only while no worker owns it.

func (ProvisionAdmission) Begin added in v0.14.0 

func (a ProvisionAdmission) Begin() (ProvisionResourceExecution, error)

Begin transfers admission ownership to its one worker before Started can issue a mutation capability. A rejected command can no longer abort a copy.

func (ProvisionAdmission) Operation added in v0.14.0 

func (a ProvisionAdmission) Operation() OperationIntentClaim

func (ProvisionAdmission) Valid added in v0.14.0 

func (a ProvisionAdmission) Valid() bool

type ProvisionManifestAdmission added in v0.14.0 

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

ProvisionManifestAdmission owns either a strictly admitted new payload or an exact historical payload derived from this journal's current active release. A historical admission carries its private release fence through acceptance; no caller flag can select stored-policy validation.

func (ProvisionManifestAdmission) Bind added in v0.14.0 

func (a ProvisionManifestAdmission) Bind(candidate OperationIntentCandidate) (OperationIntentCandidate, error)

Bind preserves the admission's private replay fence in the store-minted candidate. Acceptance must consume both authorities as one transition.

func (ProvisionManifestAdmission) Payload added in v0.14.0 

func (a ProvisionManifestAdmission) Payload() []byte

Payload returns the owned bytes chosen by admission. Historical replay uses the durable release bytes even when the request used equivalent JSON syntax.

func (ProvisionManifestAdmission) Stack added in v0.14.0 

func (a ProvisionManifestAdmission) Stack() (*manifest.StackManifest, error)

Stack returns a detached structural projection of the admitted bytes.

type ProvisionResourceExecution added in v0.14.0 

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

ProvisionResourceExecution is the consumed reservation carried by the live worker. Only Begin can mint it; an unaccepted command cannot execute work or consume terminal evidence through its admission token. The distinct private field name prevents Go conversions between capabilities.

func (ProvisionResourceExecution) CompleteFailure added in v0.14.0 

func (a ProvisionResourceExecution) CompleteFailure(proof OperationReleaseUncommitted) error

func (ProvisionResourceExecution) CompleteSuccess added in v0.14.0 

func (a ProvisionResourceExecution) CompleteSuccess(proof OperationReleaseCommitted) error

func (ProvisionResourceExecution) DeferRecovery added in v0.14.0 

func (a ProvisionResourceExecution) DeferRecovery()

DeferRecovery ends live ownership without releasing any reservation. Durable intent/release evidence, not this process-local capability, owns recovery.

func (ProvisionResourceExecution) Operation added in v0.14.0 

func (e ProvisionResourceExecution) Operation() OperationIntentClaim

func (ProvisionResourceExecution) Valid added in v0.14.0 

func (e ProvisionResourceExecution) Valid() bool

type ReapingRetentionProof added in v0.14.0 

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

ReapingRetentionProof is store-issued authority for one exact Reaping generation. Physical cleanup carries this opaque value and can delete only the unchanged tombstone it actually inspected.

func (ReapingRetentionProof) Entry added in v0.14.0 

func (proof ReapingRetentionProof) Entry() RetentionEntry

Entry returns a detached read DTO. Mutating the result cannot modify the proof's canonical row or authorize a different transition.

func (ReapingRetentionProof) Valid added in v0.14.0 

func (proof ReapingRetentionProof) Valid() bool

Valid reports whether the proof has a complete opaque shape. It does not establish current authority; terminal consumers always re-attest the row.

type RecoveryCoordinator added in v0.14.0 

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

RecoveryCoordinator is the sole issuer of callback-lifetime recovery authority. Durable claims describe what may be recovered; they do not prove that concurrent live work is excluded.

func NewRecoveryCoordinator added in v0.14.0 

func NewRecoveryCoordinator(config RecoveryCoordinatorConfig) (*RecoveryCoordinator, error)

func (*RecoveryCoordinator) BoundTo added in v0.14.0 

func (c *RecoveryCoordinator) BoundTo(
	operations *OperationSettlement,
	maintenance *MaintenanceSettlement,
	close *CloseSettlement,
) bool

BoundTo reports whether this coordinator owns the exact settlement objects. It supports composition roots which install optional protocols in stages; it does not expose or mint a recovery scope.

func (*RecoveryCoordinator) Lineage added in v0.14.0 

func (c *RecoveryCoordinator) Lineage() RecoveryLineage

func (*RecoveryCoordinator) WithActorClose added in v0.14.0 

func (c *RecoveryCoordinator) WithActorClose(
	actorScope ActorCloseScope,
	work func(LeaseRecoveryScope) error,
) error

WithActorClose exchanges an active exact-actor close scope for the same short-lived recovery authority used by background convergence. No command or actor lock is reacquired: the actor already owns serial execution and has drained its workers before minting the supplied scope.

func (*RecoveryCoordinator) WithLease added in v0.14.0 

func (c *RecoveryCoordinator) WithLease(
	ctx context.Context,
	leaseUUID string,
	work func(LeaseRecoveryScope) error,
) (bool, error)

WithLease holds the configured live-work exclusion for the complete callback. A scope cannot escape: its shared state is revoked by defer even when work panics.

type RecoveryCoordinatorConfig added in v0.14.0 

type RecoveryCoordinatorConfig struct {
	Operations   *OperationSettlement
	Maintenance  *MaintenanceSettlement
	Close        *CloseSettlement
	ExcludeLease RecoveryLeaseExclusion
	// ValidateActorClose is installed by the actor-owning substrate. Its input
	// is intentionally opaque here to avoid a shared <-> leasesm import cycle;
	// the implementation must accept only leasesm's unforgeable active scope for
	// the exact registered actor and coordinator lineage.
	ValidateActorClose func(ActorCloseScope, RecoveryLineage) (leaseUUID string, valid bool)
}

RecoveryCoordinatorConfig binds every recovery authority for one backend lineage to the same lease-exclusion implementation. Nil settlements are permitted for substrates which implement only a subset of the protocols.

type RecoveryLeaseExclusion added in v0.14.0 

type RecoveryLeaseExclusion func(
	context.Context,
	string,
	func() error,
) (acquired bool, err error)

RecoveryLeaseExclusion is the construction seam which proves that live work for one lease cannot overlap recovery. The implementation must hold its exclusion until run returns. acquired=false is a normal level-triggered deferral, not an error.

type RecoveryLineage added in v0.14.0 

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

RecoveryLineage is an opaque comparable identity passed into a lease actor at construction. Possessing it does not mint recovery authority; it only lets the coordinator reject an active scope from another backend construction.

type Release 

type Release struct {
	Version  int    `json:"version"`
	Manifest []byte `json:"manifest"`
	Image    string `json:"image"`
	// MaintenanceID identifies the exact restart/update replacement cohort.
	// Provision/restore rows omit it; a maintenance generation may carry either
	// current or v0.13 runtime authority. A maintenance ID is immutable across
	// deploying, active, failed, and superseded states and is also placed on
	// every replacement container.
	MaintenanceID MaintenanceID `json:"maintenance_id,omitzero"`
	// OperationID is the exact causal token of the provision/restore generation
	// that first committed this release lineage. Maintenance releases preserve it.
	// Empty is accepted only for v0.13/legacy rows.
	OperationID OperationID `json:"operation_id,omitzero"`
	// Items is the immutable emitted instance topology for this release. It equals
	// the requested topology except that a DNS-deferred custom domain is empty,
	// matching the labels and routers actually committed to the substrate. New
	// writers persist it before reporting success so recovery can distinguish a
	// complete cohort from a set of surviving containers. It remains optional on
	// disk for releases written by older binaries.
	Items []backend.LeaseItem `json:"items,omitempty"`
	// ResourceProfiles is the immutable resource authority paired with Items.
	// New writers always persist it before reporting success. It remains
	// optional only for release rows written by v0.13 and older binaries; Docker
	// recovery snapshots the then-current configuration when migrating those
	// rows so subsequent restarts and closes cannot reprice a live lease.
	ResourceProfiles []SKUResourceSnapshot `json:"resource_profiles,omitempty"`
	// RuntimeAuthority is the current non-expiring identity needed to reconstruct a
	// terminal lease projection when an exact committed generation has no
	// surviving containers. It is a nested all-or-nothing snapshot so JSON cannot
	// represent a partially-authoritative combination of tenant, provider, and
	// callback routes. A v0.13 row uses LegacyRuntimeAuthority instead.
	RuntimeAuthority *ReleaseRuntimeAuthority `json:"runtime_authority,omitempty"`
	// LegacyRuntimeAuthority is the separately typed, tokenless identity frozen
	// from a complete v0.13 cohort. It is never interchangeable with
	// RuntimeAuthority: legacy rows have no OperationID and cannot be granted a
	// UUID-scoped capability they never received. Persisting this exact pair is
	// nevertheless required before removing the last legacy container, because
	// otherwise a later restart could not reconstruct the active release's
	// principal, callback route, or resource ownership.
	LegacyRuntimeAuthority *LegacyRuntimeAuthority `json:"legacy_runtime_authority,omitempty"`
	Status                 string                  `json:"status"`
	CreatedAt              time.Time               `json:"created_at"`
	Error                  string                  `json:"error,omitempty"`
	Reason                 backend.Reason          `json:"reason,omitempty"`
	Message                string                  `json:"message,omitempty"`
}

Release represents a single release (deployment) of a lease.

func (Release) RuntimeIdentity added in v0.14.0 

func (release Release) RuntimeIdentity() (ReleaseRuntimeIdentity, bool)

RuntimeIdentity returns the only authority projection a Release can expose. It rejects invalid, mixed, or mismatched shapes even when a caller built the Release directly instead of reading it through the validated store.

type ReleaseAdmissionFinding added in v0.14.0 

type ReleaseAdmissionFinding struct {
	LeaseUUID   string `json:"lease_uuid"`
	Version     int    `json:"version"`
	Status      string `json:"status"`
	PolicyError string `json:"policy_error"`
}

ReleaseAdmissionFinding identifies a stored row accepted under an older manifest policy. This is advisory evidence, not a corrupt-history verdict. Status is the row's status as stopped adoption binds it: adoption may supersede an older v0.13 active row but never changes a version or manifest.

type ReleaseAdmissionInspection added in v0.14.0 

type ReleaseAdmissionInspection struct {
	Histories int                       `json:"histories"`
	Releases  int                       `json:"releases"`
	Findings  []ReleaseAdmissionFinding `json:"findings"`
}

ReleaseAdmissionInspection summarizes an offline scan of every release row, including failed and superseded rows, against current admission policy.

func InspectReleaseAdmissionReadOnly added in v0.14.0 

func InspectReleaseAdmissionReadOnly(dbPath string) (ReleaseAdmissionInspection, error)

InspectReleaseAdmissionReadOnly opens an existing stopped release database read-only. Both v0.13 arrays and current versioned histories are supported. Structural corruption is an error; policy drift is reported per lease and release. No database, binding, normalization or background writer is created.

type ReleaseAuthorityClass added in v0.14.0 

type ReleaseAuthorityClass uint8

ReleaseAuthorityClass identifies which disjoint on-disk authority a release carries. The zero value is invalid. 

const (
	ReleaseAuthorityTyped ReleaseAuthorityClass = iota + 1
	ReleaseAuthorityLegacy
)

type ReleaseBackfiller added in v0.14.0 

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

ReleaseBackfiller is the construction-bound authority for the three compare-and-swap upgrades which enrich an already-active Release. It is a separate capability from operation settlement: backfills do not settle an operation, but they must share the exact callback/release journal pair and its per-lease transition gate so they cannot cross lifecycle publication. The zero value is invalid.

func NewReleaseBackfiller added in v0.14.0 

func NewReleaseBackfiller(
	callbacks *CallbackStore,
	releases *ReleaseStore,
) (*ReleaseBackfiller, error)

NewReleaseBackfiller binds release upgrades to one exact, open callback/release journal pair. Matching paths or storage lineage are not enough: reopening either store requires constructing a new capability.

func (*ReleaseBackfiller) BackfillActiveResourceProfilesContext added in v0.14.0 

func (backfiller *ReleaseBackfiller) BackfillActiveResourceProfilesContext(
	ctx context.Context,
	leaseUUID string,
	version int,
	items []backend.LeaseItem,
	resourceProfiles []SKUResourceSnapshot,
) error

BackfillActiveResourceProfilesContext freezes resource authority through the exact callback/release journal pair. The shared lease gate makes this compare-and- swap linearizable with runtime-observation permits and every operation, maintenance, and close transition.

func (*ReleaseBackfiller) BackfillLegacyActiveAuthorityContext added in v0.14.0 

func (backfiller *ReleaseBackfiller) BackfillLegacyActiveAuthorityContext(
	ctx context.Context,
	leaseUUID string,
	expected Release,
	items []backend.LeaseItem,
	resourceProfiles []SKUResourceSnapshot,
) error

BackfillLegacyActiveAuthorityContext freezes a stopped v0.13 workload's topology through the exact callback/release journal pair. ReleaseStore deliberately exposes no independent writer which could bypass this lease transition gate.

func (*ReleaseBackfiller) BackfillLegacyRuntimeAuthorityContext added in v0.14.0 

func (backfiller *ReleaseBackfiller) BackfillLegacyRuntimeAuthorityContext(
	ctx context.Context,
	freeze LegacyRuntimeAuthorityFreeze,
) error

BackfillLegacyRuntimeAuthorityContext persists one frozen tokenless v0.13 callback principal through the exact callback/release journal pair. It cannot race a phase-qualified lifecycle publication between release re-attestation and callback enqueue because both transitions require this same lease gate.

type ReleaseClaim added in v0.14.0 

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

ReleaseClaim is an opaque compare-and-swap capability for one exact durable release row. It is intentionally not constructible outside this package.

func (ReleaseClaim) Digest added in v0.14.0 

func (c ReleaseClaim) Digest() [sha256.Size]byte

func (ReleaseClaim) LeaseUUID added in v0.14.0 

func (c ReleaseClaim) LeaseUUID() string

func (ReleaseClaim) Version added in v0.14.0 

func (c ReleaseClaim) Version() int

type ReleaseHistoryCapacityError added in v0.14.0 

type ReleaseHistoryCapacityError struct {
	LimitBytes    int
	RequiredBytes int
}

ReleaseHistoryCapacityError reports the minimum encoded bytes needed for the records that cannot be discarded. It unwraps to ErrReleaseHistoryCapacity for stable classification while retaining exact operator diagnostics through errors.As.

func (*ReleaseHistoryCapacityError) Error added in v0.14.0 

func (e *ReleaseHistoryCapacityError) Error() string

func (*ReleaseHistoryCapacityError) Unwrap added in v0.14.0 

func (e *ReleaseHistoryCapacityError) Unwrap() error

type ReleaseRuntimeAuthority added in v0.14.0 

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

ReleaseRuntimeAuthority is the immutable observational identity paired with one operation-token lineage. Callback URLs contain unguessable capabilities and make the release database a sensitive backup artifact.

func NewReleaseRuntimeAuthority added in v0.14.0 

func NewReleaseRuntimeAuthority(
	operationID OperationID,
	tenant, providerUUID, callbackURL, lifecycleCallbackURL string,
) (ReleaseRuntimeAuthority, error)

NewReleaseRuntimeAuthority constructs the immutable runtime identity paired with one typed release lineage. Its zero value is invalid, and its fields are deliberately private so callers cannot detach a validated callback pair from the operation token it names.

func (ReleaseRuntimeAuthority) CallbackURL added in v0.14.0 

func (authority ReleaseRuntimeAuthority) CallbackURL() string

func (ReleaseRuntimeAuthority) LifecycleCallbackURL added in v0.14.0 

func (authority ReleaseRuntimeAuthority) LifecycleCallbackURL() string

func (ReleaseRuntimeAuthority) MarshalJSON added in v0.14.0 

func (authority ReleaseRuntimeAuthority) MarshalJSON() ([]byte, error)

func (ReleaseRuntimeAuthority) OperationID added in v0.14.0 

func (authority ReleaseRuntimeAuthority) OperationID() OperationID

func (ReleaseRuntimeAuthority) ProviderUUID added in v0.14.0 

func (authority ReleaseRuntimeAuthority) ProviderUUID() string

func (ReleaseRuntimeAuthority) Tenant added in v0.14.0 

func (authority ReleaseRuntimeAuthority) Tenant() string

func (*ReleaseRuntimeAuthority) UnmarshalJSON added in v0.14.0 

func (authority *ReleaseRuntimeAuthority) UnmarshalJSON(data []byte) error

type ReleaseRuntimeIdentity added in v0.14.0 

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

ReleaseRuntimeIdentity is an immutable read-only projection of either durable release-authority class. Its fields are private and its zero value is invalid, so consumers can handle v0.13 and current releases without being able to manufacture or mix their authority.

func (ReleaseRuntimeIdentity) CallbackURL added in v0.14.0 

func (identity ReleaseRuntimeIdentity) CallbackURL() string

func (ReleaseRuntimeIdentity) Class added in v0.14.0 

func (identity ReleaseRuntimeIdentity) Class() ReleaseAuthorityClass

func (ReleaseRuntimeIdentity) LifecycleCallbackURL added in v0.14.0 

func (identity ReleaseRuntimeIdentity) LifecycleCallbackURL() string

func (ReleaseRuntimeIdentity) OperationID added in v0.14.0 

func (identity ReleaseRuntimeIdentity) OperationID() OperationID

func (ReleaseRuntimeIdentity) ProviderUUID added in v0.14.0 

func (identity ReleaseRuntimeIdentity) ProviderUUID() string

func (ReleaseRuntimeIdentity) Tenant added in v0.14.0 

func (identity ReleaseRuntimeIdentity) Tenant() string

type ReleaseStore 

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

ReleaseStore persists release history in bbolt so it survives backend restarts.

func OpenIdentityBoundReleaseStore added in v0.14.0 

func OpenIdentityBoundReleaseStore(
	cfg ReleaseStoreConfig,
	storage backendidentity.VerifiedStorage,
	gate *backendidentity.StorageAuthorityGate,
) (*ReleaseStore, error)

OpenIdentityBoundReleaseStore opens an initialized authoritative release journal without creating or repairing it. Maintenance remains paused until StartMaintenance so callers can verify their complete store set first.

func (ReleaseStore) Close 

func (s ReleaseStore) Close() error

Close shuts down the store gracefully. It is idempotent: the first call closes the database and captures any error; subsequent calls return the same error.

func (*ReleaseStore) Healthy 

func (s *ReleaseStore) Healthy() error

Healthy validates the complete recovery journal, not only bbolt reachability. A release manifest is cleanup and restart authority; leaving a semantically invalid row health-green would defer the failure until the next recovery or close, after the original operation may already have committed externally.

func (*ReleaseStore) Latest 

func (s *ReleaseStore) Latest(leaseUUID string) (*Release, error)

Latest returns the most recent release for a lease. Returns nil, nil when not found.

func (*ReleaseStore) LatestActive 

func (s *ReleaseStore) LatestActive(leaseUUID string) (*Release, error)

LatestActive returns the most recent release with "active" status for a lease. Returns nil, nil when no active release is found.

func (*ReleaseStore) LeaseUUIDs added in v0.14.0 

func (s *ReleaseStore) LeaseUUIDs() ([]string, error)

LeaseUUIDs returns every release-history key in deterministic byte order. Recovery uses this index to detect an exact active release even when Docker has no surviving container from which to rediscover the lease UUID.

func (*ReleaseStore) List 

func (s *ReleaseStore) List(leaseUUID string) ([]Release, error)

List returns all releases for a lease. Returns nil, nil when not found.

func (*ReleaseStore) ProveRuntimeGeneration added in v0.14.0 

func (s *ReleaseStore) ProveRuntimeGeneration(leaseUUID string) (RuntimeGenerationProof, error)

ProveRuntimeGeneration reads the active Release and mints an exact generation proof from the same bbolt snapshot.

func (*ReleaseStore) StartMaintenance added in v0.14.0 

func (s *ReleaseStore) StartMaintenance()

StartMaintenance performs the initial pruning pass and starts the periodic loop exactly once.

func (ReleaseStore) VerifyStorageIdentity added in v0.14.0 

func (s ReleaseStore) VerifyStorageIdentity(storage backendidentity.VerifiedStorage) error

VerifyStorageIdentity proves that an authoritative store's configured path still names the exact regular file opened by the constructor and that the durable binding remains intact. This catches delete/rename/replacement while the process still holds a writable descriptor to the old inode.

type ReleaseStoreConfig 

type ReleaseStoreConfig struct {
	DBPath          string
	MaxAge          time.Duration
	CleanupInterval time.Duration
	OnCleanupPanic  util.PanicHandler // Optional: invoked on cleanup-loop panic.
}

ReleaseStoreConfig configures the release store.

type ReleaseStoreInspection added in v0.14.0 

type ReleaseStoreInspection struct {
	Exists           bool
	IdentityBound    bool
	ActiveLeaseUUIDs map[string]struct{}
	ActiveReleases   map[string]Release

	// RequiresLegacyNormalization reports a wire-recognizable v0.13 history
	// whose redundant authority rows must be normalized atomically with identity
	// binding (older active rows left by RecordMigration or Provision, or
	// semantically identical post-active deploying retries).
	RequiresLegacyNormalization bool
	// contains filtered or unexported fields
}

ReleaseStoreInspection is read-only v0.13 adoption evidence.

func InspectBoundLegacyReleaseStoreReadOnly added in v0.14.0 

func InspectBoundLegacyReleaseStoreReadOnly(
	path *BoundAuthoritativeStorePath,
) (ReleaseStoreInspection, error)

InspectBoundLegacyReleaseStoreReadOnly is the stopped-v0.13 adoption inspector. In addition to current histories, it accepts the wire-recognizable multi-active histories that v0.13 RecordMigration and Provision (including a re-provision of a failed lease) wrote by appending an active row without superseding the older one. The newest active row was already v0.13 LatestActive authority. It also recognizes post-active v0.13 Update/Restart deploying rows only when every complete parsed manifest is semantically identical to LatestActive. The identity-binding transaction normalizes older actives and equivalent deploying retries to superseded before a current store can open the journal; a distinct deploying manifest remains ambiguous and is rejected without mutation.

func InspectBoundReleaseStoreReadOnly added in v0.14.0 

func InspectBoundReleaseStoreReadOnly(
	path *BoundAuthoritativeStorePath,
) (ReleaseStoreInspection, error)

InspectBoundReleaseStoreReadOnly is the descriptor-relative form used by a storage-lineage initialization after retaining the journal parent.

func InspectReleaseStoreReadOnly added in v0.14.0 

func InspectReleaseStoreReadOnly(dbPath string) (ReleaseStoreInspection, error)

InspectReleaseStoreReadOnly validates every durable history without creating a database, bucket, binding, or cleanup goroutine.

func (ReleaseStoreInspection) CheckActiveResourceProfilesCapacity added in v0.14.0 

func (inspection ReleaseStoreInspection) CheckActiveResourceProfilesCapacity(
	leaseUUID string,
	expected Release,
	resourceProfiles []SKUResourceSnapshot,
) error

CheckActiveResourceProfilesCapacity simulates the narrower startup backfill for a release that already has exact Items but predates immutable profile snapshots.

func (ReleaseStoreInspection) CheckLegacyActiveAuthorityAndRuntimeCapacity added in v0.14.0 

func (inspection ReleaseStoreInspection) CheckLegacyActiveAuthorityAndRuntimeCapacity(
	leaseUUID string,
	expected Release,
	items []backend.LeaseItem,
	resourceProfiles []SKUResourceSnapshot,
	authority LegacyRuntimeAuthority,
) error

CheckLegacyActiveAuthorityAndRuntimeCapacity simulates the complete startup upgrade of a stopped v0.13 Release, including the separately typed tokenless runtime identity. This ensures the offline sealing proof cannot pass only for startup to fail when it persists the additional zero-survivor authority.

func (ReleaseStoreInspection) CheckLegacyActiveAuthorityCapacity added in v0.14.0 

func (inspection ReleaseStoreInspection) CheckLegacyActiveAuthorityCapacity(
	leaseUUID string,
	expected Release,
	items []backend.LeaseItem,
	resourceProfiles []SKUResourceSnapshot,
) error

CheckLegacyActiveAuthorityCapacity simulates the exact startup backfill that converts one stopped v0.13 active release into current recovery authority. The inspection snapshot already reflects any deterministic v0.13 normalization that the identity-binding transaction will perform. No file is reopened or changed.

type ResolvedAdoptInstance added in v0.14.0 

type ResolvedAdoptInstance struct {
	ID        string
	Resources SKUResourceSnapshot
}

ResolvedAdoptInstance pairs an adopted allocation ID with the exact profile already frozen in its durable operation intent.

type ResourceAccountingHold added in v0.14.0 

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

ResourceAccountingHold is pool-issued ownership of one capacity exclusion. Copies share the same idempotent release; one observer cannot release another observer's hold. The zero value grants no release authority.

func (ResourceAccountingHold) Release added in v0.14.0 

func (h ResourceAccountingHold) Release()

Release returns only the capacity exclusion owned by this hold. Call after strict inventory proves that this observer's unaccounted footprint is gone.

type ResourceAllocation 

type ResourceAllocation struct {
	LeaseUUID string
	Tenant    string
	SKU       string
	CPUCores  float64
	MemoryMB  int64
	DiskMB    int64
	// contains filtered or unexported fields
}

ResourceAllocation tracks resources allocated to a single lease.

func ConservativeResourceEnvelope added in v0.14.0 

func ConservativeResourceEnvelope(cohorts ...[]ResourceAllocation) ([]ResourceAllocation, error)

ConservativeResourceEnvelope retains every immutable cohort's keys and the maximum sizing of overlapping keys. Admission and Pending-intent recovery use the same rule: replacing a generation cannot expose capacity before teardown.

type ResourcePool 

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

ResourcePool manages the backend's resource capacity. It provides atomic allocation and release from immutable resource rows; effective disk may include substrate-specific scratch in addition to the durable SKU profile.

func NewResourcePool 

func NewResourcePool(totalCPU float64, totalMemoryMB, totalDiskMB int64, resolver SKUResolver, tenantQuota *TenantQuotaConfig) *ResourcePool

NewResourcePool creates a new resource pool with the given capacity. It panics when a capacity, quota, or resolver is invalid: callers construct a pool once at startup, so accepting a malformed boundary would permanently corrupt or disable its admission accounting. The quota is copied so later caller mutation cannot invalidate a live pool.

func (*ResourcePool) GetAllocation 

func (p *ResourcePool) GetAllocation(leaseUUID string) *ResourceAllocation

GetAllocation returns the allocation for a lease, or nil if not allocated.

func (*ResourcePool) HoldUnaccountedFootprint added in v0.14.0 

func (p *ResourcePool) HoldUnaccountedFootprint() ResourceAccountingHold

HoldUnaccountedFootprint atomically excludes new allocations while substrate without an immutable resource snapshot is present. Existing allocations, releases, retained accounting, and conservative recovery remain operable.

func (*ResourcePool) HoldUnsizedDiskFootprint added in v0.14.0 

func (p *ResourcePool) HoldUnsizedDiskFootprint() DiskAccountingHold

HoldUnsizedDiskFootprint atomically withholds disk capacity while a footprint that cannot yet be sized remains on disk. The owner releases the hold once that footprint is either sized and counted (for example through SetRetainedDisk) or gone.

func (*ResourcePool) ListAllocations 

func (p *ResourcePool) ListAllocations() []ResourceAllocation

ListAllocations returns a copy of all current allocations.

func (*ResourcePool) Release 

func (p *ResourcePool) Release(leaseUUID string)

Release returns resources for a lease back to the pool. It is safe to call Release for a lease that has no allocation.

func (*ResourcePool) Reset 

func (p *ResourcePool) Reset(allocations []ResourceAllocation) error

Reset clears all allocations and rebuilds from a list of allocations. It returns an error without changing the existing snapshot if an allocation is malformed or the rebuilt accounting cannot be represented.

func (*ResourcePool) ResetConservatively added in v0.14.0 

func (p *ResourcePool) ResetConservatively(allocations []ResourceAllocation) error

ResetConservatively is the recovery-safe variant of Reset. It replaces every current lease owner represented by allocations and preserves every current owner absent from that snapshot. The polarity is deliberately fail-closed: an incomplete recovery publication can retain capacity, but cannot erase a live reservation and expose phantom capacity. Only the exact terminal path that owns an allocation may release an absent owner.

recoverState rebuilds the pool from a container-derived snapshot each tick, but a lease that is mid-operation (Provisioning/Restarting/Updating) may have no containers yet (still pulling its image) or containers that do not yet reflect its authoritative TryAllocate reservation, so such leases are excluded from that snapshot. Dropping their reservation on the rebuild would let TryAllocate momentarily see phantom free capacity and over-admit past physical capacity, leaving the pool over-committed once the lease re-registers (ENG-546). Preserving all unrepresented owners makes that safety independent of a caller-maintained classification set and also covers the window before an operation's Items are populated.

No caller code runs while the pool lock is held. Both existing and rebuilt allocation keys must expose a canonical fixed-width lease owner; malformed recovery input fails atomically without changing the previous snapshot.

func (*ResourcePool) SetRetainedDisk added in v0.5.0 

func (p *ResourcePool) SetRetainedDisk(mb int64) error

SetRetainedDisk records the aggregate disk (MB) reserved by retained (soft-deleted) volumes. The owner derives this from the retention store and pushes it here; TryAllocate subtracts it from available disk so retained volumes keep counting against the pool until reaped. It rejects a negative projection without changing the last valid value: silently converting broken accounting to zero would erase durable capacity authority and over-admit. Idempotent.

func (*ResourcePool) Stats 

func (p *ResourcePool) Stats() ResourceStats

Stats returns current resource usage statistics.

func (*ResourcePool) TenantStats 

func (p *ResourcePool) TenantStats(tenant string) ResourceStats

TenantStats returns resource usage statistics for a specific tenant. RetainedDiskMB is intentionally left 0: retained disk is a provider-level term (not attributed per tenant), so AvailableDiskMB() on a tenant snapshot intentionally excludes it.

func (*ResourcePool) TryAllocate 

func (p *ResourcePool) TryAllocate(leaseUUID, sku, tenant string) error

TryAllocate attempts to reserve resources for a new provision (gates all of CPU, memory, disk, and tenant quota).

func (*ResourcePool) TryAllocateAdoptAll added in v0.11.0 

func (p *ResourcePool) TryAllocateAdoptAll(instances []AdoptInstance, tenant string, oldRetainedDiskMB int64) error

TryAllocateAdoptAll atomically reserves every instance of a restore under a single lock acquisition. Restore adopts existing volumes (rename, not fresh disk), so the per-instance reservations SKIP the global disk gate — the adopted bytes are already committed on disk and counted in the retained projection. Disk CAPACITY is gated once, here, on the AGGREGATE promote delta. The pool computes the new total from its OWN resolver — the exact DiskMB the per-instance reservations below will add — and subtracts oldRetainedDiskMB (the lease's already-committed retained footprint, which the caller derives from the retention record and which is already counted in retainedDisk). A same-tier or demote restore (delta <= 0) adds no disk pressure.

Gating the delta and committing all reservations under ONE lock is what makes admission correct on three axes: (1) EXACT — a per-volume disk gate would double-count the retained bytes still in the projection until RestoreSettlement.ClaimForRestore and reject a fitting multi-volume promote; (2) ATOMIC — no concurrent TryAllocate/restore can consume disk between the delta check and the reservations, so the pool cannot be over-committed; and (3) CONSISTENT — the gated new total is computed from the same resolver that sizes the reservations, so a caller whose SKU resolver diverges from the pool's cannot under-gate disk (ENG-545, PR #184 review). Only oldRetainedDiskMB is a caller input, and it enters the gate in the safe direction (undercounting it enlarges the delta).

CPU, memory, and tenant quota are gated per instance (new containers). On any failure nothing is reserved: the instances committed so far in this call are rolled back before returning.

func (*ResourcePool) TryAllocateAdoptAllResolved added in v0.14.0 

func (p *ResourcePool) TryAllocateAdoptAllResolved(
	instances []ResolvedAdoptInstance,
	tenant string,
	oldRetainedDiskMB int64,
) error

TryAllocateAdoptAllResolved is the immutable-profile counterpart of TryAllocateAdoptAll. The complete batch is validated and committed under one pool lock, preserving the aggregate promote-delta gate while guaranteeing that accounting uses the same values as the durable operation intent.

func (*ResourcePool) TryAllocateResolved added in v0.14.0 

func (p *ResourcePool) TryAllocateResolved(
	leaseUUID, tenant string,
	resources SKUResourceSnapshot,
) error

TryAllocateResolved reserves resources using an already-resolved immutable profile. Durable workflow owners use this path so admission cannot resolve a different value from the profile persisted for recovery.

type ResourceStats 

type ResourceStats struct {
	TotalCPU          float64
	TotalMemoryMB     int64
	TotalDiskMB       int64
	AllocatedCPU      float64
	AllocatedMemoryMB int64
	AllocatedDiskMB   int64
	RetainedDiskMB    int64
	AllocationCount   int
	AccountingHeld    bool
	// DiskAccountingHeld reports a disk-only exclusion: a footprint of unknown
	// size remains on disk, so no disk-bearing allocation is admitted.
	DiskAccountingHeld bool
}

ResourceStats contains resource usage statistics.

func (ResourceStats) AvailableCPU 

func (s ResourceStats) AvailableCPU() float64

AvailableCPU returns available CPU cores.

func (ResourceStats) AvailableDiskMB 

func (s ResourceStats) AvailableDiskMB() int64

AvailableDiskMB returns disk available for new allocations: total minus live allocations minus retained (soft-deleted) reservations, clamped to >= 0 (a total_disk_mb shrink or stale retained projection must not surface a negative "available" via the /stats endpoints).

func (ResourceStats) AvailableMemoryMB 

func (s ResourceStats) AvailableMemoryMB() int64

AvailableMemoryMB returns available memory in MB, clamped to zero when the recovered allocation projection is already at or above configured capacity.

func (ResourceStats) RoutingLoadStats added in v0.14.0 

func (s ResourceStats) RoutingLoadStats() (*backend.LoadStats, error)

RoutingLoadStats projects a complete resource ledger into the load signal used for provision routing. An unaccounted footprint invalidates that projection: returning a deceptively low allocation would keep routing new leases to a backend whose pool correctly refuses them. Stats remains available for diagnostics without fabricating usage for that footprint. A disk-only exclusion (DiskAccountingHeld) keeps the CPU signal valid but reports DiskWithheld, so routing prefers a backend that still admits disk instead of choosing this one, which refuses every disk-bearing provision.

type RestoreClaimCandidate added in v0.14.0 

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

RestoreClaimCandidate is an exact, RetentionStore-bound capability for the Active -> Restoring transition of one pending restore. The security and causal fields are detached from caller-owned request buffers and cannot be replaced before the store consumes the candidate. Its zero value is invalid.

type RestoreSettlement added in v0.14.0 

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

RestoreSettlement is the exact three-journal boundary for claiming retained source state on behalf of a pending restore operation. It shares the destination operation gate with OperationSettlement while the retention store's transaction provides the independent source-generation CAS.

func NewRestoreSettlement added in v0.14.0 

func NewRestoreSettlement(
	operations *OperationSettlement,
	retentions *RetentionStore,
) (*RestoreSettlement, error)

NewRestoreSettlement binds one operation pair to the exact retention journal in the same backend-storage lineage. The zero value is invalid.

func (*RestoreSettlement) ClaimForRestore added in v0.14.0 

func (s *RestoreSettlement) ClaimForRestore(
	candidate RestoreClaimCandidate,
	maxAge time.Duration,
) (RestoringRetentionProof, error)

ClaimForRestore consumes an exact store-issued restore capability and atomically transitions its source retention from Active to Restoring. Every security- or causality-bearing destination field comes from the sealed operation claim used by PrepareRestoreClaim; maxAge remains an operator policy rather than request authority.

func (*RestoreSettlement) PrepareRestoreClaim added in v0.14.0 

func (s *RestoreSettlement) PrepareRestoreClaim(
	claim OperationIntentClaim,
) (RestoreClaimCandidate, error)

PrepareRestoreClaim derives the complete retention transition from a sealed pending restore operation. It accepts no caller-spliced lease, token, callback, topology, sizing, or timestamp fields.

func (*RestoreSettlement) ProveInterruptedSourceClose added in v0.14.0 

func (s *RestoreSettlement) ProveInterruptedSourceClose(
	subject OperationPhysicalSubject,
) (InterruptedRestoreSource, error)

ProveInterruptedSourceClose recognizes the record-first close/restore overlap admitted by older versions. Fresh ClaimForRestore excludes this state. The proof cannot be minted from a raw source ID or a caller-authored retention row.

func (*RestoreSettlement) ReadRestorableSource added in v0.14.0 

func (s *RestoreSettlement) ReadRestorableSource(sourceLeaseUUID, tenant string) (*RetentionEntry, error)

ReadRestorableSource is a tenant-scoped admission preflight, not a source transfer capability. It avoids creating a doomed destination operation when the source is already known to have a pending close. ClaimForRestore repeats the source check atomically with transfer after durable destination admission.

type RestoringRetentionProof added in v0.14.0 

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

RestoringRetentionProof is store-issued authority for one exact Restoring generation. The proof contains the canonical durable row rather than a caller-owned RetentionEntry: callers may inspect a detached DTO, but cannot alter the authority later consumed by a terminal transition.

Proofs are copyable and deliberately not linear. Every consumer re-reads the row and compares its canonical bytes while holding the retention-store lock, so a stale copy cannot survive an ABA transition, route move, or reopen.

func (RestoringRetentionProof) Entry added in v0.14.0 

func (proof RestoringRetentionProof) Entry() RetentionEntry

Entry returns a detached read DTO. Mutating the result cannot modify the proof's canonical row or authorize a different transition.

func (RestoringRetentionProof) Valid added in v0.14.0 

func (proof RestoringRetentionProof) Valid() bool

Valid reports whether the proof has a complete opaque shape. It does not establish current authority; terminal consumers always re-attest the row.

type RetentionEntry added in v0.5.0 

type RetentionEntry struct {
	OriginalLeaseUUID string `json:"original_lease_uuid"`
	Tenant            string `json:"tenant"`
	// Partition is an OPTIONAL cooperative sub-grouping WITHIN Tenant, declared
	// by the tenant for its own end-customers (aggregator model). "" is the
	// default whole-tenant bucket: legacy records, non-partitioned tenants, and
	// any collapsed (invalid/divergent/over-limit) declaration all land here.
	// It is grouping metadata for cap sub-division and eviction ordering ONLY —
	// never a security boundary (isolation stays keyed on Tenant) and never
	// load-bearing for restore/reap correctness (a record with a wrong or
	// missing partition remains fully restorable). Stamped only at soft-delete
	// time by the close path; see CloseSettlement.RecordRetention for the retry
	// merge rule.
	Partition    string              `json:"partition,omitempty"`
	ProviderUUID string              `json:"provider_uuid"`
	Items        []backend.LeaseItem `json:"items"`
	// ResourceProfiles is the immutable sizing authority captured when the
	// footprint became retained. It is optional for backward compatibility with
	// records written before exact profile snapshots existed.
	ResourceProfiles []SKUResourceSnapshot `json:"resource_profiles,omitempty"`
	// DestinationItems and DestinationResourceProfiles are the immutable
	// ownership authority for a restore destination. RestoreSettlement writes
	// them in the same transaction that changes Active to Restoring, before
	// any retained volume is adopted. They let recovery rebuild and finalize a
	// successful destination even when its initial active Release append failed.
	// The terminal operation outcome selects commit versus rollback; this snapshot
	// supplies the immutable data needed to execute that decision. Both fields are
	// required while Restoring and are cleared when rollback returns the source to
	// Active.
	DestinationItems            []backend.LeaseItem   `json:"destination_items,omitempty"`
	DestinationResourceProfiles []SKUResourceSnapshot `json:"destination_resource_profiles,omitempty"`
	DestinationOperationID      OperationID           `json:"destination_operation_id,omitzero"`
	// DestinationCallbackURL is retained only as the paired operation identity
	// needed to validate DestinationLifecycleCallbackURL. Lifecycle observations
	// are always delivered to the latter; the operation URL is never reused to
	// settle another generation.
	DestinationCallbackURL          string                  `json:"destination_callback_url,omitempty"`
	DestinationLifecycleCallbackURL string                  `json:"destination_lifecycle_callback_url,omitempty"`
	StackManifest                   *manifest.StackManifest `json:"stack_manifest"`
	CallbackURL                     string                  `json:"callback_url"`
	RetainedVolumeNames             []string                `json:"retained_volume_names"`
	Status                          string                  `json:"status"`
	NewLeaseUUID                    string                  `json:"new_lease_uuid,omitempty"`
	Generation                      int                     `json:"generation"`
	CreatedAt                       time.Time               `json:"created_at"`
	RestoringSince                  time.Time               `json:"restoring_since,omitempty"`
	ReapingSince                    time.Time               `json:"reaping_since,omitempty"`
}

RetentionEntry is a detached read DTO for one durable retention row. Its exported fields support inspection, projection, and v0.13 decoding; passing a modified value back to a runtime state transition grants no authority. Active, Restoring, and Reaping writes are derived by CloseSettlement, RestoreSettlement, or exact RetentionStore-issued proofs.

func InspectRetentionEntriesReadOnly added in v0.14.0 

func InspectRetentionEntriesReadOnly(dbPath string) ([]RetentionEntry, error)

InspectRetentionEntriesReadOnly decodes the authoritative retention bucket without creating a database, bucket, index, cleanup goroutine, or write transaction. Backend storage-lineage initialization uses it while the old daemon is stopped to prove configured tenant bytes belong to the root being sealed before any marker is published.

type RetentionOrphanPruner added in v0.14.0 

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

RetentionOrphanPruner is the sole owner of orphan candidate selection, complete-volume inventory, consecutive confirmation state, and ACTIVE-row deletion. It is safe for concurrent callers, though production binds it once to the single cleanup loop.

func NewRetentionOrphanPruner added in v0.14.0 

func NewRetentionOrphanPruner(
	store *RetentionStore,
	confirmations int,
	rootConfigured bool,
	inventory RetentionOrphanVolumeInventory,
) (*RetentionOrphanPruner, error)

NewRetentionOrphanPruner binds all authority required for orphan cleanup. The inventory capability is fixed for the pruner's lifetime; Sweep accepts only a context and cannot be supplied per-record evidence.

func (*RetentionOrphanPruner) Sweep added in v0.14.0 

func (p *RetentionOrphanPruner) Sweep(ctx context.Context) (RetentionOrphanSweepResult, error)

Sweep inventories the entire volume namespace, selects every current ACTIVE row itself, and consumes only a row that remained byte-identical for the configured number of consecutive complete observations.

type RetentionOrphanSkipReason added in v0.14.0 

type RetentionOrphanSkipReason uint8

RetentionOrphanSkipReason is a closed observation vocabulary for a sweep that deliberately performed no orphan deletion. 

const (
	RetentionOrphanSkipNone RetentionOrphanSkipReason = iota
	RetentionOrphanSkipDisabled
	RetentionOrphanSkipInventoryError
	RetentionOrphanSkipStoreError
)

type RetentionOrphanSweepResult added in v0.14.0 

type RetentionOrphanSweepResult struct {
	Pruned         int
	Raced          int
	DeleteFailures int
	SkipReason     RetentionOrphanSkipReason
}

RetentionOrphanSweepResult contains aggregate observations only. It exposes no candidate, proof, lease key, or caller-selected deletion target.

type RetentionOrphanVolumeInventory added in v0.14.0 

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

RetentionOrphanVolumeInventory is an opaque, purpose-specific read capability. Its zero value is invalid; callers must bind the complete substrate inventory once with BindRetentionOrphanVolumeInventory. Keeping the callable unexported prevents swapping the evidence source per sweep; the sweep additionally turns a dependency panic (including a bound method with a nil receiver) into a fail-closed inventory error before selecting or deleting any row.

func BindRetentionOrphanVolumeInventory added in v0.14.0 

func BindRetentionOrphanVolumeInventory(
	listForProof func(context.Context) ([]string, error),
) (RetentionOrphanVolumeInventory, error)

BindRetentionOrphanVolumeInventory turns the backend's complete physical inventory operation into the only input a pruner can retain. The operation must enumerate every entry in fred's reserved volume namespace and fail on uncertain root identity.

type RetentionStore added in v0.5.0 

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

RetentionStore persists soft-deleted lease data in bbolt. The `retention` bucket is the single source of truth; byTenant/byStatus are a DERIVED in-memory index rebuilt from the bucket on open (never persisted, cannot drift across a restart). The bucket is INDEX-COUPLED: it may be mutated ONLY through this type's wrapped methods (each maintains the index under s.mu). Never wire boltStore.startCleanup / removeOlderThan to this store — they cursor.Delete directly on the bucket and would bypass the index.

func OpenIdentityBoundRetentionStore added in v0.14.0 

func OpenIdentityBoundRetentionStore(
	cfg RetentionStoreConfig,
	storage backendidentity.VerifiedStorage,
	gate *backendidentity.StorageAuthorityGate,
) (*RetentionStore, error)

OpenIdentityBoundRetentionStore opens an initialized authoritative retention journal without creating or repairing it.

func (*RetentionStore) BeginExpiredReaping added in v0.14.0 

func (s *RetentionStore) BeginExpiredReaping(
	candidate ActiveRetentionCandidate,
	maxAge time.Duration,
) (ReapingRetentionProof, bool, error)

BeginExpiredReaping is BeginReaping with an in-transaction age gate. The caller supplies policy only; the store derives and proves the exact state.

func (*RetentionStore) BeginReaping added in v0.14.0 

func (s *RetentionStore) BeginReaping(
	candidate ActiveRetentionCandidate,
) (ReapingRetentionProof, bool, error)

BeginReaping atomically changes the candidate's exact Active row to Reaping and returns the resulting tombstone capability. State, generation, timestamps, and immutable authority are derived inside the store.

func (RetentionStore) Close added in v0.5.0 

func (s RetentionStore) Close() error

Close shuts down the store gracefully. It is idempotent: the first call closes the database and captures any error; subsequent calls return the same error.

func (*RetentionStore) DeleteReaped added in v0.14.0 

func (s *RetentionStore) DeleteReaped(proof ReapingRetentionProof) (bool, error)

DeleteReaped consumes one exact Reaping proof after physical absence has been established. A copied proof cannot delete a rewritten or reopened row.

func (*RetentionStore) DeleteRestoring added in v0.14.0 

func (s *RetentionStore) DeleteRestoring(proof RestoringRetentionProof) (bool, error)

DeleteRestoring consumes one exact restore-finalizer proof. Absence is an idempotent success; a surviving different row is a stale-authority error.

func (*RetentionStore) Get added in v0.5.0 

func (s *RetentionStore) Get(orig string) (*RetentionEntry, error)

Get retrieves a RetentionEntry by original lease UUID. Returns nil, nil when absent.

func (*RetentionStore) Healthy added in v0.5.0 

func (s *RetentionStore) Healthy() error

Healthy revalidates both the exact authority root and every current row. The derived indexes cannot establish health: they intentionally contain no representation of an unknown future bucket and may predate an external mutation detected by the runtime authority checks.

func (*RetentionStore) Keys added in v0.5.0 

func (s *RetentionStore) Keys() ([]string, error)

Keys returns every retained lease UUID (the bbolt key) without unmarshalling the heavy record value (skips the dominant per-record json.Unmarshal). string(k) copies, so no cursor bytes escape the transaction.

func (*RetentionStore) List added in v0.5.0 

func (s *RetentionStore) List() ([]RetentionEntry, error)

List returns all RetentionEntry records in the store.

func (*RetentionStore) ListActiveCandidates added in v0.14.0 

func (s *RetentionStore) ListActiveCandidates() ([]ActiveRetentionCandidate, error)

ListActiveCandidates returns opaque transition candidates for the exact Active rows in one MVCC snapshot. Read-only callers should continue to use List; destructive policy must carry one of these store-issued candidates.

func (*RetentionStore) ListActiveCandidatesByTenant added in v0.14.0 

func (s *RetentionStore) ListActiveCandidatesByTenant(
	tenant string,
) ([]ActiveRetentionCandidate, error)

ListActiveCandidatesByTenant is the indexed-policy selector for cap eviction. It returns only exact Active rows for tenant.

func (*RetentionStore) ListByTenant added in v0.5.0 

func (s *RetentionStore) ListByTenant(tenant string) ([]RetentionEntry, error)

ListByTenant returns all entries for the given tenant (eventually-consistent; callers must re-validate via CAS before mutating — see type doc). Served from the index.

func (*RetentionStore) ListExpired added in v0.5.0 

func (s *RetentionStore) ListExpired(maxAge time.Duration) ([]RetentionEntry, error)

ListExpired returns active entries whose CreatedAt is older than maxAge.

func (*RetentionStore) ListExpiredCandidates added in v0.14.0 

func (s *RetentionStore) ListExpiredCandidates(
	maxAge time.Duration,
) ([]ActiveRetentionCandidate, error)

ListExpiredCandidates returns exact Active rows which were already expired in the selector snapshot. BeginExpiredReaping repeats the age check while consuming the candidate, so clock policy and durable authority stay atomic.

func (*RetentionStore) ListPage added in v0.14.0 

func (s *RetentionStore) ListPage(after string, limit int) ([]RetentionEntry, string, error)

ListPage returns detached retention records and their continuation from one identity-bound bbolt snapshot. Decoding happens before that view closes, so a concurrent restore finalizer cannot separate a selected key from its value. Positive limits use an ordered cursor and decode at most limit records; next is the last returned key only when more keys exist. A nonpositive limit is the unpaginated passthrough and ignores after. Separate pages are separate snapshots: the cursor establishes key order, not a whole-walk transaction.

func (*RetentionStore) ListReaping added in v0.5.0 

func (s *RetentionStore) ListReaping() ([]RetentionEntry, error)

ListReaping returns all entries currently in the reaping (pending-destroy) state.

func (*RetentionStore) ListReapingProofs added in v0.14.0 

func (s *RetentionStore) ListReapingProofs() ([]ReapingRetentionProof, error)

ListReapingProofs returns exact cleanup authority for every Reaping row in one MVCC snapshot. Restart recovery must select work through this method: a caller-supplied lease UUID is inspection data, not mutation authority.

func (*RetentionStore) ListRestoring added in v0.5.0 

func (s *RetentionStore) ListRestoring() ([]RetentionEntry, error)

ListRestoring returns all entries currently restoring (eventually-consistent). Served from the index.

func (*RetentionStore) ListTenantRetentionCandidates added in v0.14.0 

func (s *RetentionStore) ListTenantRetentionCandidates(
	tenant string,
) ([]RetentionEntry, []ActiveRetentionCandidate, error)

ListTenantRetentionCandidates returns one tenant's complete read snapshot together with mutation authority only for the Active subset, from the same bbolt view. Partition policy can therefore observe Restoring rows without granting them destructive authority, while cap eviction consumes only exact Active candidates.

func (*RetentionStore) ProveRestoringSnapshot added in v0.14.0 

func (s *RetentionStore) ProveRestoringSnapshot(
	expected RetentionEntry,
) (RestoringRetentionProof, error)

ProveRestoringSnapshot upgrades a read-only DTO to mutation authority only when its complete canonical encoding is still the exact durable Restoring row. This is the recovery bridge from ListRestoring/Get without reopening a caller-authored generation or callback route as a mutation API.

func (*RetentionStore) ReIndex added in v0.5.0 

func (s *RetentionStore) ReIndex() error

ReIndex rebuilds the in-memory index from the primary bucket and swaps it in. Safe on a live store: it holds s.mu across the WHOLE scan+swap, which serializes it with mutators (each holds s.mu across its {db.Update + indexApply}). Holding the lock only for the swap would be unsafe — a mutator could commit a write and update the live index between the scan returning and the swap, and the swap would then overwrite that write with a pre-scan snapshot (lost update → drift until the next rebuild). fireReindex runs outside the lock. The self-heal/recovery seam (the index is never the source of truth).

func (*RetentionStore) RestoringSourceByDestination added in v0.14.0 

func (s *RetentionStore) RestoringSourceByDestination(destinationLease string) (*RetentionEntry, error)

RestoringSourceByDestination returns the exact source finalizer currently owning destinationLease, or nil when the destination is free. A duplicate is durable corruption and fails closed rather than picking one by bbolt order. Callers still need their per-destination command fence across this read and subsequent admission; this store query is the durable half of that guard.

func (*RetentionStore) RollbackRestoring added in v0.14.0 

func (s *RetentionStore) RollbackRestoring(
	proof RestoringRetentionProof,
	resourceProfiles []SKUResourceSnapshot,
) (ActiveRetentionProof, error)

RollbackRestoring consumes one exact restore-finalizer proof and publishes the source Active row only after validating its physical quota authority.

func (RetentionStore) VerifyStorageIdentity added in v0.14.0 

func (s RetentionStore) VerifyStorageIdentity(storage backendidentity.VerifiedStorage) error

VerifyStorageIdentity proves that an authoritative store's configured path still names the exact regular file opened by the constructor and that the durable binding remains intact. This catches delete/rename/replacement while the process still holds a writable descriptor to the old inode.

type RetentionStoreConfig added in v0.5.0 

type RetentionStoreConfig struct {
	DBPath string
	// OnReindex (nil-safe) fires after each index build with record count, duration, and
	// trigger ("open"|"manual"). A callback (not a metrics import) so this package stays
	// free of internal/metrics — mirrors boltStore.startCleanup's onPanic seam.
	OnReindex func(count int, dur time.Duration, trigger string)
}

RetentionStoreConfig configures the retention store.

type RetentionStoreInspection added in v0.14.0 

type RetentionStoreInspection struct {
	Exists        bool
	IdentityBound bool
	Entries       []RetentionEntry
}

RetentionStoreInspection distinguishes an absent journal from an existing, valid but empty v0.13 journal.

func InspectBoundRetentionStoreReadOnly added in v0.14.0 

func InspectBoundRetentionStoreReadOnly(
	path *BoundAuthoritativeStorePath,
) (RetentionStoreInspection, error)

InspectBoundRetentionStoreReadOnly is the descriptor-relative form used by storage-lineage initialization after retaining the journal parent.

func InspectRetentionStoreReadOnly added in v0.14.0 

func InspectRetentionStoreReadOnly(dbPath string) (RetentionStoreInspection, error)

InspectRetentionStoreReadOnly decodes the authoritative retention bucket without creating or mutating it.

type RuntimeFailureLogs added in v0.14.0 

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

RuntimeFailureLogs is a read-only view of the failed attempt whose exact source is still the current runtime. Its private binding is authored only by terminal source-ready evidence, never caller-selected diagnostic metadata.

func (RuntimeFailureLogs) Logs added in v0.14.0 

func (view RuntimeFailureLogs) Logs() map[string]string

func (RuntimeFailureLogs) MatchesProjection added in v0.14.0 

func (view RuntimeFailureLogs) MatchesProjection(version int, tenant, provider string, lifecycle backend.LifecycleGenerationObservation) bool

type RuntimeGenerationProof added in v0.14.0 

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

RuntimeGenerationProof is an opaque, store-issued capability for one exact active Release generation. It seals the row's version, full digest, runtime authority class, and typed operation identity (when present). Both current typed releases and valid v0.13 legacy releases can mint it; the zero value is invalid.

The proof is observational authority only. It cannot mutate a release or choose callback semantics; CallbackPublisher may consume it only for the fixed lifecycle-failure observation after a fresh exact ReleaseStore read, so a delayed substrate event cannot act on a replacement generation.

func (RuntimeGenerationProof) AuthorityClass added in v0.14.0 

func (proof RuntimeGenerationProof) AuthorityClass() ReleaseAuthorityClass

func (RuntimeGenerationProof) LeaseUUID added in v0.14.0 

func (proof RuntimeGenerationProof) LeaseUUID() string

func (RuntimeGenerationProof) MatchesRelease added in v0.14.0 

func (proof RuntimeGenerationProof) MatchesRelease(release Release) bool

MatchesRelease reports whether release is the exact durable row from which this proof was minted. The comparison includes the full serialized digest, not only Version or OperationID, so an in-place legacy-authority backfill invalidates an observation captured before that write.

func (RuntimeGenerationProof) OperationID added in v0.14.0 

func (proof RuntimeGenerationProof) OperationID() OperationID

func (RuntimeGenerationProof) Reattest added in v0.14.0 

func (proof RuntimeGenerationProof) Reattest() error

Reattest proves that this exact row remains the current active Release.

func (RuntimeGenerationProof) Valid added in v0.14.0 

func (proof RuntimeGenerationProof) Valid() bool

func (RuntimeGenerationProof) Version added in v0.14.0 

func (proof RuntimeGenerationProof) Version() int

Version returns the exact active release version sealed by this proof. A zero result means the proof is invalid. OperationID alone is deliberately insufficient as a generation discriminator because maintenance releases preserve their originating provision/restore operation ID.

type RuntimeObservationPermit added in v0.14.0 

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

RuntimeObservationPermit is an opaque, journal-pair-issued capability for publishing an autonomous observation about one exact runtime phase. Unlike RuntimeGenerationProof, which is intentionally release-only so substrate events can be classified without callback authority, this permit also seals the aggregate mutation phase observed under the pair's per-lease gate.

A permit can exist only while the exact release generation is active and the lease has either no mutation head, the matching successful operation receipt, or a failed successor which durably seals this exact active Release as its predecessor. Pending operation work, an initial failed operation, and every maintenance, close, or closed phase are unrepresentable publication authority. PublishLifecycleFailure re-attests both sealed facts, so retaining or copying a permit cannot carry an observation across a later phase transition or reopened journal pair. The zero value is invalid.

func (RuntimeObservationPermit) LeaseUUID added in v0.14.0 

func (permit RuntimeObservationPermit) LeaseUUID() string

LeaseUUID returns the lease whose exact runtime and mutation phase the permit seals. An invalid permit returns the empty string.

func (RuntimeObservationPermit) Valid added in v0.14.0 

func (permit RuntimeObservationPermit) Valid() bool

Valid reports whether the permit still names its exact open journal pair. It intentionally does not perform I/O; publication is the consumption point which re-attests the sealed release and aggregate phase under the lease gate.

type SKUProfile 

type SKUProfile struct {
	CPUCores float64 `yaml:"cpu_cores"`
	MemoryMB int64   `yaml:"memory_mb"`
	DiskMB   int64   `yaml:"disk_mb"`
}

SKUProfile defines resource limits for a SKU.

func LookupSKUResourceSnapshot added in v0.14.0 

func LookupSKUResourceSnapshot(snapshot []SKUResourceSnapshot, sku string) (SKUProfile, bool)

LookupSKUResourceSnapshot returns the immutable profile for sku. The input must already have passed ValidateSKUResourceSnapshot; canonical ordering makes lookup logarithmic and avoids rebuilding a map in recovery/accounting loops.

func (SKUProfile) Validate 

func (p SKUProfile) Validate() error

Validate checks that the profile's resource values are valid.

type SKUResolver 

type SKUResolver func(sku string) (SKUProfile, error)

SKUResolver resolves a SKU identifier to its resource profile. This abstracts the SKU mapping logic so it can be shared between components.

type SKUResourceSnapshot added in v0.14.0 

type SKUResourceSnapshot struct {
	SKU           string  `json:"sku"`
	CPUCores      float64 `json:"cpu_cores"`
	MemoryMB      int64   `json:"memory_mb"`
	DiskMB        int64   `json:"disk_mb"`
	ScratchDiskMB int64   `json:"scratch_disk_mb,omitempty"`
}

SKUResourceSnapshot is the immutable resource definition of one SKU at the time a durable workflow acquires authority over a lease. Persisting the values, rather than resolving the mutable backend configuration during recovery, keeps reservations and retained-disk accounting exact after an operator renames, removes, or resizes a SKU profile.

A snapshot slice is canonical when it contains exactly one row for every distinct SKU referenced by Items and is strictly sorted by SKU. Use BuildSKUResourceSnapshot to construct one and ValidateSKUResourceSnapshot at every durable decode boundary.

func BuildSKUResourceSnapshot added in v0.14.0 

func BuildSKUResourceSnapshot(items []backend.LeaseItem, resolver SKUResolver) ([]SKUResourceSnapshot, error)

BuildSKUResourceSnapshot resolves every distinct item SKU exactly once and returns a canonical snapshot sorted by the original SKU identifier. The original identifier is load-bearing: a configured SKU mapping may change independently from the profile name it resolved to.

func CloneSKUResourceSnapshot added in v0.14.0 

func CloneSKUResourceSnapshot(snapshot []SKUResourceSnapshot) []SKUResourceSnapshot

CloneSKUResourceSnapshot returns a copy safe for an opaque durable claim.

func LookupSKUResourceSnapshotRow added in v0.14.0 

func LookupSKUResourceSnapshotRow(snapshot []SKUResourceSnapshot, sku string) (SKUResourceSnapshot, bool)

LookupSKUResourceSnapshotRow returns the complete immutable authority for sku. Callers doing capacity accounting must use this rather than Profile, which intentionally exposes only the durable SKU resources and omits ephemeral scratch.

func (SKUResourceSnapshot) EffectiveDiskMB added in v0.14.0 

func (s SKUResourceSnapshot) EffectiveDiskMB() (int64, error)

EffectiveDiskMB returns the physical disk capacity held by one live instance. DiskMB is durable, retainable SKU storage. ScratchDiskMB is the separate conservative host-volume ceiling Docker pins and charges for every diskless instance; a physical scratch volume is created only when the image needs writable-path scaffolding. They are mutually exclusive by construction: a stateful instance's writable paths share its durable volume.

func (SKUResourceSnapshot) Profile added in v0.14.0 

func (s SKUResourceSnapshot) Profile() SKUProfile

Profile returns the resource profile represented by this immutable row.

type SettledMaintenance added in v0.14.0 

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

SettledMaintenance is one retained maintenance completion receipt, read back as the durable outcome of that exact maintenance. Only the store mints one, from a validated receipt, so its outcome and source fact cannot disagree.

func (SettledMaintenance) LeaseUUID added in v0.14.0 

func (m SettledMaintenance) LeaseUUID() string

func (SettledMaintenance) MaintenanceID added in v0.14.0 

func (m SettledMaintenance) MaintenanceID() MaintenanceID

func (SettledMaintenance) SourceReady added in v0.14.0 

func (m SettledMaintenance) SourceReady() (SettledSourceRelease, bool)

SourceReady returns the release a failed maintenance settled back onto, when the settlement proved it was the lease's running, ready cohort. A successful maintenance never has one.

func (SettledMaintenance) Succeeded added in v0.14.0 

func (m SettledMaintenance) Succeeded() bool

Succeeded reports that the maintenance's target became the active release.

type SettledSourceRelease added in v0.14.0 

type SettledSourceRelease struct {
	Version int
	Digest  string
}

SettledSourceRelease identifies the release a failed maintenance settled back onto.

type TenantQuotaConfig 

type TenantQuotaConfig struct {
	MaxCPUCores float64 `yaml:"max_cpu_cores"`
	MaxMemoryMB int64   `yaml:"max_memory_mb"`
	MaxDiskMB   int64   `yaml:"max_disk_mb"`
}

TenantQuotaConfig configures per-tenant resource limits. When set, each tenant's aggregate resource usage is capped; MaxDiskMB is physical admission disk and may include substrate-specific ephemeral scratch.

func (TenantQuotaConfig) Validate 

func (q TenantQuotaConfig) Validate() error

Validate checks that all quota values are positive.

type UnverifiableMaintenanceReceipt added in v0.14.0 

type UnverifiableMaintenanceReceipt struct {
	LeaseUUID     string
	MaintenanceID MaintenanceID
	Cause         error
	// contains filtered or unexported fields
}

UnverifiableMaintenanceReceipt is a failed, effect-started receipt whose exact target release could not be read or verified, for example after release-history compaction dropped the target row. It grants no cleanup authority: uncertainty keeps the bytes, and it never blocks another lease's receipts. Only ListFailedMaintenanceReceipts mints one.

type VolumeLaunchDebt added in v0.14.0 

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

VolumeLaunchDebt can only be completed with the successful step of its exact live subject. Reopened rows intentionally cannot mint this capability: a new process did not observe the original synchronous Create/Start completion.

type VolumeLaunchJournal added in v0.14.0 

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

VolumeLaunchJournal is bound to the same authoritative file and commit gate as its originating callback operation. It stores only unresolved launches; a positive synchronous effect receipt consumes debt in the same transaction as any maintenance target/source phase transition.

func NewVolumeLaunchJournal added in v0.14.0 

func NewVolumeLaunchJournal(store *CallbackStore) (*VolumeLaunchJournal, error)

func (*VolumeLaunchJournal) Begin added in v0.14.0 

func (j *VolumeLaunchJournal) Begin(origin VolumeLaunchOrigin, volumes []fsidentity.Identity) (VolumeLaunchDebt, error)

func (*VolumeLaunchJournal) Check added in v0.14.0 

func (j *VolumeLaunchJournal) Check(origin VolumeLaunchOrigin, volumes []fsidentity.Identity) error

Check runs under the caller's physical-directory reservations, before any bind preparation or writer retirement. Begin repeats it in the durable write immediately before launch, while those same reservations remain held.

func (*VolumeLaunchJournal) CheckNamespace added in v0.14.0 

func (j *VolumeLaunchJournal) CheckNamespace(leaseUUID string) error

CheckNamespace is a read-only refusal fence for the namespace coordinator. An outstanding Docker request holds the originating canonical paths as well as their physical IDs. Destroying/renaming them and recreating a new inode must not make that request's old bind source appear reusable.

func (*VolumeLaunchJournal) Complete added in v0.14.0 

func (j *VolumeLaunchJournal) Complete(debt VolumeLaunchDebt, completed substratemutation.CompletedStep) error

Complete is the runtime debt-removal path. The receipt is non-forgeable, bound to the exact live subject/effect, single-use, and minted only after the full effect plus post-attestation succeeded. Any commit failure preserves debt. Unknown requests instead require the separate stopped operator-fence repair.

func (*VolumeLaunchJournal) PendingCount added in v0.14.0 

func (j *VolumeLaunchJournal) PendingCount() (int, error)

PendingCount reports outstanding launch requests for operator monitoring. It grants no authority to clear them or infer workload readiness.

type VolumeLaunchOrigin added in v0.14.0 

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

VolumeLaunchOrigin is one of the closed, exact live mutation subjects. A parsed ID, recovery cleanup subject, or historical receipt cannot launch.

func VolumeLaunchForCompensation added in v0.14.0 

func VolumeLaunchForCompensation(subject MaintenanceCompensationSubject) VolumeLaunchOrigin

func VolumeLaunchForMaintenance added in v0.14.0 

func VolumeLaunchForMaintenance(subject MaintenancePhysicalSubject) VolumeLaunchOrigin

func VolumeLaunchForOperation added in v0.14.0 

func VolumeLaunchForOperation(subject OperationPhysicalSubject) VolumeLaunchOrigin

Source Files

View all Source files

Directories

Path Synopsis
Package completion owns the bounded completion window of an admitted effect.
 Package completion owns the bounded completion window of an admitted effect.
Package imagebudget keeps immutable image verification work and physical daemon allocation in separate dimensions across preparation and durable pins.
 Package imagebudget keeps immutable image verification work and physical daemon allocation in separate dimensions across preparation and durable pins.
Package leasesm owns the per-lease state machine and actor, plus the substrate-agnostic seams they consume.
 Package leasesm owns the per-lease state machine and actor, plus the substrate-agnostic seams they consume.
failurecause
Package failurecause attributes one lease workload failure to its cause, for the consecutive-failure terminal budget the lease state machine keeps (ENG-799).
 Package failurecause attributes one lease workload failure to its cause, for the consecutive-failure terminal budget the lease state machine keeps (ENG-799).
Package manifest defines the tenant-facing container manifest schema (StackManifest, holding a map of named per-service Manifest entries), JSON parsing, and validation.
 Package manifest defines the tenant-facing container manifest schema (StackManifest, holding a map of named per-service Manifest entries), JSON parsing, and validation.
Package substratemutation defines the causal protocol between a durable mutation journal and an attested physical-substrate executor.
 Package substratemutation defines the causal protocol between a durable mutation journal and an attested physical-substrate executor.
Package workbarrier provides a reference-counted barrier whose zero signal is exposed as a real channel, so callers can wait-with-timeout using a plain select without spawning helper goroutines that would leak when the count never drops to zero.
 Package workbarrier provides a reference-counted barrier whose zero signal is exposed as a real channel, so callers can wait-with-timeout using a plain select without spawning helper goroutines that would leak when the count never drops to zero.

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.