coord

type BackendKind string

type Capability struct {
	// Supported is true when direct coordination is available.
	Supported bool
	// Backend identifies the backend that would coordinate the scope.
	Backend BackendKind
	// VolumeID is the owning Volume id.
	VolumeID string
	// ObjectStoreID is the ObjectStore id inside the Volume.
	ObjectStoreID string
	// Generation is the latest durable generation observed by the coordinator.
	Generation uint64
	// Generations is true when the scope carries durable generation fencing,
	// Snapshot, Publish, and Watch.
	Generations bool
	// DetectsLoss is true when the backend closes WriteLease.Done and reports
	// WriteLease.Err on involuntary loss.
	DetectsLoss bool
	// FallbackReason explains why Supported is false.
	FallbackReason FallbackReason
}

type Coordinator interface {
	// Capability reports whether the scoped ObjectStore supports direct
	// multi-writer coordination and why callers must fall back when it does not.
	Capability(ctx context.Context, scope Scope) (*Capability, error)
	// Snapshot returns the latest durable generation and root metadata.
	Snapshot(ctx context.Context, scope Scope) (*Snapshot, error)
	// Watch returns root, prefix, lock, and fallback events after generation.
	Watch(ctx context.Context, scope Scope, afterGeneration uint64) (Watch, error)
	// TryAcquireWriteLease attempts to acquire the logical write lease.
	TryAcquireWriteLease(ctx context.Context, scope Scope) (WriteLease, bool, error)
	// WaitAcquireWriteLease waits until the logical write lease is available.
	WaitAcquireWriteLease(ctx context.Context, scope Scope) (WriteLease, error)
}

type Event struct {
	// ProcessID identifies the process that produced or requested the event.
	ProcessID string
	// VolumeID is the owning Volume id.
	VolumeID string
	// ObjectStoreID is the ObjectStore id inside the Volume.
	ObjectStoreID string
	// Generation is the durable generation associated with this event.
	Generation uint64
	// WantLock is true when another participant is waiting for the write lease.
	WantLock bool
	// Unlocked is true when a participant released the write lease.
	Unlocked bool
	// RootChanged carries the accepted root after a commit.
	RootChanged *bucket.ObjectRef
	// KeyPrefixChanged carries a key prefix invalidated by a commit.
	KeyPrefixChanged []byte
	// FallbackReason carries a visible fallback reason when direct coordination fails.
	FallbackReason FallbackReason
}

type FallbackReason string

type Scope struct {
	// VolumeID is the owning Volume id.
	VolumeID string
	// ObjectStoreID is the ObjectStore id inside the Volume.
	ObjectStoreID string
	// ParticipantID identifies the process or handle performing the operation.
	ParticipantID string
	// Key names a caller-chosen exclusion subject inside the Volume.
	Key string
}

type Snapshot struct {
	// VolumeID is the owning Volume id.
	VolumeID string
	// ObjectStoreID is the ObjectStore id inside the Volume.
	ObjectStoreID string
	// Generation is the latest durable generation.
	Generation uint64
	// Root is the latest durable ObjectStore root.
	Root *bucket.ObjectRef
}

type UnsupportedCoordinator struct {
	// Backend is the unsupported backend kind to report.
	Backend BackendKind
	// Reason is the fallback reason to report.
	Reason FallbackReason
}

type Watch interface {
	// Events returns the event stream for this watch.
	Events() <-chan Event
	// Close releases resources held by this watch.
	Close() error
}

type WriteLease interface {
	// Done returns a channel closed when the lease is released or lost.
	//
	// Done closes on release or on involuntary loss. A backend reporting
	// Capability.DetectsLoss false closes Done only from Release.
	Done() <-chan struct{}
	// Err returns the loss error after Done is closed, or nil for a held or
	// cleanly released lease.
	Err() error
	// Refresh returns the latest durable generation and root before writing.
	//
	// Refresh on a scope with Capability.Generations false returns ErrUnsupported.
	Refresh(ctx context.Context) (*Snapshot, error)
	// Publish records an accepted generation/root/prefix change.
	//
	// Publish on a scope with Capability.Generations false returns ErrUnsupported.
	Publish(ctx context.Context, event Event) (*Snapshot, error)
	// Release releases the logical write lease.
	//
	// Release must complete regardless of ctx cancellation. Callers release on
	// cleanup paths that run precisely because their context ended, so a
	// release that honored cancellation would strand the scope locked and
	// every waiter blocked. ctx carries deadlines for backend I/O only.
	Release(ctx context.Context) error
}