framework

type Contract ¶

type Contract struct {
	ID       ContractID
	Major    uint16
	Minor    uint16
	Features map[Feature]uint16
}

Contract is a port's immutable protocol description. Atomicity and other base correctness requirements belong to the major contract itself; Features describe optional additions, never permissions.

func Negotiate(provided Contract, required Requirements) (Contract, error)

type ContractID ¶

type ContractID string

type Fault ¶

type Fault struct {
	Code    FaultCode
	Retry   RetryMode
	Message string
	Cause   error
}

Fault carries a stable code and retry disposition while retaining the original error for errors.Is/errors.As. Message is safe for the embedding application; adapters must not expose Cause text unless their policy allows it.

func (fault *Fault) Error() string

func (fault *Fault) Unwrap() error

type FaultCode ¶

type FaultCode string

FaultCode is a transport-neutral classification. Adapters map it to their wire protocol without parsing error text.

const (
	CodeInvalid         FaultCode = "invalid"
	CodeUnauthenticated FaultCode = "unauthenticated"
	CodeForbidden       FaultCode = "forbidden"
	CodeNotFound        FaultCode = "not_found"
	CodeConflict        FaultCode = "conflict"
	CodeStale           FaultCode = "stale"
	CodeUnavailable     FaultCode = "unavailable"
	CodeIndeterminate   FaultCode = "indeterminate"
	CodeCorrupt         FaultCode = "corrupt"
	CodeClosed          FaultCode = "closed"
)

type Feature ¶

type Feature string

type ReleaseFunc ¶

type ReleaseFunc func(context.Context) error

ReleaseFunc closes a resource that was explicitly transferred to a Human composition. The context bounds shutdown; implementations should make the operation idempotent because a constructor-failure cleanup and normal shutdown may race.

type Requirements ¶

type Requirements struct {
	ID           ContractID
	Major        uint16
	MinimumMinor uint16
	Features     map[Feature]uint16
}

Requirements declares what a consumer needs from one port.

type Resource ¶

type Resource[T any] struct {
	// contains filtered or unexported fields
}

Resource pairs a dependency with an explicit ownership decision. Borrowed dependencies remain owned by the caller. Owned dependencies are released at most once, including when Resource values are copied.

A Resource is a composition value, not a lease. Calling Release on an owned Resource permanently releases that composition's dependency; Value then returns ErrResourceReleased. The zero Resource is borrowed and contains the zero value of T, which consuming constructors normally reject.

func Borrow[T any](value T) Resource[T]

func Own[T any](value T, release ReleaseFunc) (Resource[T], error)

func (resource Resource[T]) Owned() bool

func (resource Resource[T]) Release(ctx context.Context) error

func (resource Resource[T]) Value() (T, error)

type RetryMode ¶

type RetryMode string

RetryMode tells an adapter which class of retry is safe. It never grants authorization and does not override a domain-specific idempotency contract.

const (
	RetryNever      RetryMode = "never"
	RetryExactInput RetryMode = "exact_input"
	RetryBackoff    RetryMode = "backoff"
	RetryReconcile  RetryMode = "reconcile"
)

type Runtime ¶

type Runtime interface {
	// Done closes after shutdown has stopped background work and released every
	// explicitly owned resource.
	Done() <-chan struct{}
	// Err returns the terminal runtime error after Done closes. A clean explicit
	// shutdown returns nil.
	Err() error
	// Shutdown stops admission, drains accepted work where the concrete runtime
	// contract requires it, and releases owned dependencies in reverse order.
	// It must be safe for concurrent and repeated calls.
	Shutdown(context.Context) error
}

Runtime is the common lifecycle exposed by active Human compositions. Constructor contexts only bound initialization and recovery; after a successful constructor returns, Shutdown owns the runtime lifetime.