residency

type ActorID string

type Admissions interface {
	// Admit charges one session's admission weight. It is idempotent for a
	// repeated (key, agent).
	Admit(registry.Key, sessionwire.AgentID) error

	// Release credits an admitted session's weight back, whoever owns it. Only
	// an attach's own rollback uses it: the charge is that attach's.
	Release(registry.Key) bool

	// Own binds the session's charge to the residency generation that
	// installed it, and reports whether it is now that generation's. A
	// re-admission of the session (a successor's) claims the charge back for
	// the attach in flight; see ReleaseOwned.
	Own(registry.Key, uint64) bool

	// ReleaseOwned credits the charge back only while it still belongs to the
	// releasing generation (booked finding B2). Every path that ends a
	// residency credits through it: a successor that admitted the session
	// between the old residency's registry removal and its credit holds the
	// charge, and a credit keyed by session alone uncharged it.
	ReleaseOwned(registry.Key, uint64) bool

	// Draining reports whether this Host has begun graceful drain.
	//
	// IT IS ON THE LEDGER RATHER THAN BESIDE IT because they are the same
	// object and the same rule: internal/service owns exactly one of each, and
	// two sources of "draining" is a Host that stops accepting in one place
	// while advertising Accepting from the other. This Manager WAS that second
	// place — step 8 published accepting as a literal true — so an attach
	// admitted a moment before a drain began went on to advertise an accepting
	// route on a draining Host. The window is not narrow: Admit refuses new
	// sessions once draining, but an already-admitted attach spans the lease,
	// and the whole of hydration.
	Draining() bool
}

type AttachError struct {
	Step   Step
	Code   sessionwire.HostLinkErrorCode
	Key    registry.Key
	Reason string
	Cause  error

	// RuntimeCompatibilityID is the build THIS Host runs or launches for the
	// refused request — the resident runtime's on the warm path, the launch
	// target's on the cold one — and is set exactly when Code is
	// runtime_mismatch. Core refuses to encode that class without it, so a
	// runtime_mismatch without one could not reach a Factory as a refusal at
	// all (D3.1 F1). It is never the caller's value and never the durable
	// state's: a Factory reading it learns what this Host offers.
	RuntimeCompatibilityID department.CompatibilityID

	// Unreleased names every compensation that itself failed, so a caller can
	// tell "the attach failed and took nothing" from "the attach failed and
	// something is still held". The second is an operator's problem — a live
	// route with no owner, a lease nobody will renew — and it must not be
	// indistinguishable from the first.
	Unreleased []string

	// UnreleasedCauses are the errors behind Unreleased, one per compensation
	// that itself failed, for a caller that must classify them (an expected
	// lost-grant refusal is not a leak). A resource Unreleased names only
	// because a registry loser leaves it to the winner has no cause here.
	UnreleasedCauses []error
}

type Consumption interface {
	// Wake resumes consumption for a session. It is a wake and not a delivery,
	// so repeating it is harmless.
	Wake(registry.Key)
}

type ConsumptionHalter interface {
	// Halt stops the session's consumer claiming anything and waits, bounded
	// by ctx, for a pass in flight to finish.
	Halt(context.Context, registry.Key) error

	// Resume undoes Halt, for a release that aborts.
	Resume(registry.Key)
}

type DurableInbox interface {
	// AcceptedWork reports whether the durable inbox holds work accepted for
	// this session and not yet terminal.
	AcceptedWork(context.Context, registry.Key) (bool, error)
}

type DurableStore interface {
	// LoadSessionState returns the durable state for a session.
	LoadSessionState(context.Context, sessionwire.TenantID, sessionwire.SessionID) (SessionState, error)
}

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

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

type HeartbeatOptions struct {
	// Host supplies the identity, endpoint, placement, clock, heartbeat
	// interval and registry expiry every observation is derived from. Nothing
	// here restates a value host.New already checked.
	Host *hostconfig.Host

	// HostGeneration is this Host process's incarnation identity, which Core
	// requires to be non-zero on every HostLink record.
	HostGeneration uint64

	Registry  HeartbeatRegistry
	Locations Locations

	// Admissions is the Host's ONE ledger, and its drain flag with it.
	//
	// IT IS THE WHOLE LEDGER RATHER THAN A NARROWER DrainState, which this
	// package used to declare. That interface was a strict subset, so a
	// composition could satisfy the two independently and hand the Manager one
	// object and the heartbeat another — moving "two sources of draining" from
	// a code possibility to a COMPOSITION possibility, which is the defect the
	// Workspaces note in manager.go describes. Naming the same type in both
	// places is what makes them the same object by construction.
	Admissions Admissions

	// Teardown receives a residency whose ownership is gone, once.
	Teardown TeardownObserver
}

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

type HeartbeatRegistry interface {
	Get(registry.Key) (registry.Entry, bool)
	MarkReleasing(registry.Key, uint64) (registry.Entry, bool)
	ResumeResident(registry.Key, uint64) (registry.Entry, bool)
	BeginTeardown(registry.Key, uint64) (registry.Entry, bool)
	RemoveByGeneration(registry.Key, uint64) bool
}

type InvalidManagerOptionsError struct {
	Field  string
	Reason string
}

type JournalEpoch uint64

type Lease interface {
	// Epoch is the RESIDENCY epoch this grant owns. It is never zero: Core
	// rejects a zero lease_epoch on the registry observation, so a store that
	// grants one has granted something Host cannot publish under.
	Epoch() ResidencyEpoch

	// Lost closes when the grant is no longer held, whether by renewal
	// failure, expiry, or observation of a later epoch. It is the FAST guard
	// only; the non-rebasing journal CAS is the hard backstop.
	Lost() <-chan struct{}

	// Release drops the grant. It is not termination: the session remains
	// durable and resumable.
	Release(context.Context) error
}

type LeaseCleanupError struct {
	// Cause is the refusal, joined with the cleanup failure by an
	// implementation that has both.
	Cause error

	// Cleanup retries the release. It may be nil only in a value nobody built
	// through a store; Release treats that as nothing owed.
	Cleanup func(context.Context) error
}

type LocalRegistry interface {
	Get(registry.Key) (registry.Entry, bool)
	Insert(registry.Key, registry.Admission) (registry.Entry, bool)
	RemoveByGeneration(registry.Key, uint64) bool
}

type Locations interface {
	// PublishResidency writes the observation under its lease epoch. The
	// implementation rejects an epoch lower than the greatest already
	// committed for that record.
	PublishResidency(context.Context, sessionwire.HostLinkRegistryObservation) error

	// TombstoneResidency writes the EXPIRED epoch-fenced tombstone of §10.1.
	// It removes the route without erasing the fencing high-water mark, which
	// is why a rollback calls this rather than deleting the record.
	TombstoneResidency(context.Context, sessionwire.TenantID, sessionwire.SessionID, uint64) error
}

type LossReason string

type LostResidency struct {
	Key             registry.Key
	AgentID         sessionwire.AgentID
	CompatibilityID department.CompatibilityID
	LeaseEpoch      ResidencyEpoch
	Generation      uint64
	Runtime         department.Runtime
	Reason          LossReason
}

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

type Mode string

type Options struct {
	// Host is the validated Host whose identity, endpoint, placement, tenant,
	// registry expiry and clock the projection is derived from. Nothing here
	// re-states a value host.New already checked.
	Host *hostconfig.Host

	// HostGeneration is this Host process's incarnation identity. Core
	// requires it to be non-zero on every HostLink record, and it belongs to
	// the run rather than to the configuration, which is why it is not on
	// host.Options.
	HostGeneration uint64

	// Registry is the local residency index. It is an optimization; see
	// LocalRegistry and the registry package comment.
	Registry LocalRegistry

	// Admissions is the Host's ONE admission ledger. See Admissions.
	Admissions Admissions

	Leases     SessionLeases
	Durable    DurableStore
	Workspaces Workspaces
	Locations  Locations
	Ownership  Ownership
}

type Ownership interface {
	// BeginOwnership starts ownership under the SESSION context, not the
	// request's, and returns the handle that ends it.
	BeginOwnership(context.Context, OwnershipRequest) (OwnershipHandle, error)
}

type OwnershipHandle interface {
	// Stop ends the ownership this handle started.
	Stop(context.Context) error
}

type OwnershipRequest struct {
	Key             registry.Key
	AgentID         sessionwire.AgentID
	CompatibilityID department.CompatibilityID
	LeaseEpoch      ResidencyEpoch
	Generation      uint64
	Runtime         department.Runtime

	// Fence is the attach's OWN epochFence, handed on rather than rebuilt.
	//
	// IT IS THE GRANT'S FENCE AND NOT MERELY ITS LEASE, and the difference is
	// what "the one mechanism" has to mean. Building a second fence over the
	// same lease gave two objects that shared Lost() and did NOT share the
	// classification: a supersession one of them observed was invisible to the
	// other, so the Manager could know the epoch was stale while the heartbeat
	// went on publishing under it. One grant, one fence.
	//
	// IT CLOSES A REAL HOLE, and an earlier version of this comment called it
	// equivalent on a reason that was simply wrong — that a heartbeat ends its
	// own fence only after the attach has returned. It does not: the heartbeat
	// starts at step 7 and TWO fenced writes follow it inside the same attach.
	// So a beat refused with ErrEpochSuperseded ends the heartbeat's fence
	// without closing Lost(); step 8 then fails for some other reason; and the
	// unwinder's tombstone goes through a Manager fence that knows nothing, at
	// an epoch a successor has already superseded. That closure's own comment
	// calls that the worst case in the file, because a tombstone is a route
	// removal and the route may be the successor's.
	Fence *epochFence

	// Commit is the attach's point of no return, for an Ownership that keeps a
	// resident set a drain reads. It reports whether the attach may still become
	// resident — false once CancelAttaches has cancelled it — and, having
	// answered true, takes the attach out of CancelAttaches' reach: from then on
	// it is a residency the drain releases, and cancelling its session context
	// would tear a live runtime down beneath that release. An implementation
	// calls it inside the same critical section that inserts the session into
	// its resident set. Nil means there is nothing to commit.
	Commit func() bool
}

type Principal struct {
	// TenantID is the tenant the attach acts within. It must equal the
	// request's tenant; a principal for one tenant may not attach another's
	// session.
	TenantID sessionwire.TenantID

	// ActorID is who the attach acts for. It is REQUIRED: an attach with no
	// actor is an attach nothing can be attributed to.
	ActorID ActorID

	// TraceID correlates the attach with its cause. It is optional.
	TraceID TraceID
}

type ReleaseAuthority interface {
	ReleaseRuntime(context.Context) error
	ReleaseLease(context.Context) error
	ReleaseWorkspace(context.Context) error
	// ReleaseLocation writes the epoch-fenced tombstone and removes the local
	// registry entry, as one step with one verdict.
	ReleaseLocation(context.Context) error
	// ReleaseAdmission credits the residency's admission charge back.
	ReleaseAdmission(context.Context) error
}

type ReleaseError struct {
	Key registry.Key

	// Cause carries the typed reason, so a caller can tell a lost grant from an
	// unreachable store with errors.Is instead of matching text.
	Cause error

	// Unwritten names each durable write that failed, in the order attempted,
	// for the reason AttachError.Unreleased exists: a release that reports
	// failure and a release that leaves a live route with no owner must not be
	// indistinguishable.
	Unwritten []string
}

type Request struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	AgentID   sessionwire.AgentID
	Mode      Mode

	// CompatibilityID is the runtime build Factory placed this session on. It
	// is OPTIONAL, and when set it must equal the target's own. Checking it in
	// step 1 refuses a mis-placed session before a lease is taken; the durable
	// state's build is checked again in step 3, against a different source.
	CompatibilityID department.CompatibilityID

	// Principal is the approved subset of the caller's identity that may reach
	// the session root context. See Principal.
	Principal Principal
}

type Residency struct {
	Key             registry.Key
	AgentID         sessionwire.AgentID
	CompatibilityID department.CompatibilityID
	Generation      uint64
	Runtime         department.Runtime

	// LeaseEpoch is HOST'S residency grant, the value published as the registry
	// observation's lease_epoch.
	LeaseEpoch ResidencyEpoch

	// JournalEpoch is THE RUNTIME'S grant, read from the launched runtime and
	// never derived from LeaseEpoch. Its type differs from LeaseEpoch's so the
	// two cannot be assigned across without a conversion a reviewer can see.
	//
	// JournalEpochHeld is the half a consumer must branch on. A runtime that is
	// headless, has no persistence, or is simply not wired for durable commands
	// legitimately holds no journal lease, and one whose lease has been released
	// or lost reports absence rather than the number it used to hold. Zero is
	// therefore not "no epoch" — false is.
	JournalEpoch     JournalEpoch
	JournalEpochHeld bool

	// Attached reports whether THIS call established the residency. False
	// means the session was already resident and this call took nothing.
	Attached bool
}

type ResidencyEpoch uint64

type RuntimeJournal int

type SessionLeases interface {
	// AcquireSessionLease grants the lease for one session, or reports
	// ErrLeaseHeld if another holder has it.
	//
	// A REFUSAL MAY STILL OWE A RELEASE, which is finding F16(b) and the reason
	// LeaseCleanupError exists. (Lease, error) cannot say "refused, and you
	// still owe a release", so every fake in this module read a non-nil error
	// as nothing acquired and LEAKED the case the released store actually
	// produces. An implementation in that state wraps the refusal in a
	// *LeaseCleanupError; a caller reaches it with errors.As and owns the retry.
	AcquireSessionLease(context.Context, sessionwire.TenantID, sessionwire.SessionID) (Lease, error)
}

type SessionState struct {
	// Exists reports whether the session has durable state at all.
	Exists bool

	// Namespace is the tenant- and session-scoped object prefix every launched
	// runtime writes under. It is read from the store rather than derived here
	// because the layout is SessionStore's, not Host's.
	//
	// IT IS REQUIRED WHETHER OR NOT THE SESSION EXISTS. The prefix is a
	// property of the identities, not of the durable state, so a store that
	// answers Exists=false must still answer with the namespace that session's
	// objects will live under. An empty one is refused before the launch: a
	// runtime handed the empty prefix scopes every object it writes to nothing,
	// and it does so having reported success.
	Namespace string

	// CompatibilityID is the runtime build that wrote the durable state. A
	// restore onto a different build is refused.
	CompatibilityID department.CompatibilityID

	// RigSessionID is Harness's identity for the session: the runtime session
	// id the session's immutable durable binding names (Factory derives it
	// at create; it is NOT the Core session id). A restore that does not carry
	// it has nothing to restore from, and a create launches under it so the
	// journal the runtime writes is the one the binding names. Zero arises
	// only for a session with NO catalog record (Exists=false), and a create
	// then lets the rig mint one. A record without a binding (legacy) gets the
	// deprecated RigSessionIDs collaborator's answer, or an error.
	RigSessionID uuid.UUID

	// RuntimeJournal reports whether the runtime's own journal already holds
	// a conversation under RigSessionID. It is what decides a create: see
	// RuntimeJournal. The zero value is RuntimeJournalUnknown, which refuses a
	// create, so a store that forgot to answer fails closed. A legacy record
	// (no binding) is never probed, so it stays Unknown and every create over
	// one is refused; v0.2.1 launched it. No shipped path creates a legacy
	// record a Host could hold (residency is disposition-only).
	RuntimeJournal RuntimeJournal

	// HasCheckpoint and CheckpointSequence report the active workspace
	// checkpoint. A target declaring RequiresCheckpoint may not be restored
	// without one.
	HasCheckpoint      bool
	CheckpointSequence uint64
}

type Step string

type TeardownObserver interface {
	ResidencyLost(context.Context, LostResidency)
}

type TraceID string

type WarmClock interface {
	NewWarmTimer(time.Duration) WarmTimer
}

type WarmConfirmer interface {
	// ConfirmIdle reports whether the session is idle NOW and has done no work
	// since the observation that armed its countdown. Anything it cannot
	// establish must be false.
	ConfirmIdle(registry.Key) bool
}

type WarmFailure struct {
	Step WarmStep
	Err  error
}

type WarmObserver interface {
	WarmRelease(WarmOutcome)
}

type WarmOptions struct {
	Clock WarmClock

	// TTL is how long a session stays warm after durable whole-session idle.
	//
	// IT MUST BE POSITIVE. host.Options already refuses a non-positive WarmTTL,
	// so accepting zero here would define a behaviour for a configuration no
	// Host can be constructed with. A deployment that wants no warm window
	// does not watch the session.
	TTL time.Duration

	Registry    WarmRegistry
	Inbox       DurableInbox
	Consumption Consumption

	// Admissions is the Host's ONE admission ledger. The warm release credits a
	// released session's weight back through it; keeping a second count here
	// would be the over-admission bug internal/service's own documentation
	// names this task as a required consumer to avoid.
	Admissions Admissions

	// Observer receives every attempt's outcome. It is optional.
	Observer WarmObserver

	// Confirm re-confirms idle at expiry. It is optional; see WarmConfirmer.
	Confirm WarmConfirmer

	// ReleaseBound bounds the two steps that wait on the session rather than
	// on a store: halting its consumption and releasing its runtime. Zero
	// leaves them unbounded. See release.
	ReleaseBound time.Duration
}

type WarmOutcome struct {
	Key        registry.Key
	Generation uint64
	Kind       WarmOutcomeKind

	// Reason is free text for an operator. A caller branches on Kind and on
	// the Failures' Steps, never on this.
	Reason string

	// Failures are every step that did not succeed, in the order they ran.
	Failures []WarmFailure
}

type WarmOutcomeKind string

type WarmRegistry interface {
	StopAdmitting(registry.Key, uint64) (registry.Entry, bool)
}

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

type WarmSession interface {
	// Key identifies the session.
	Key() registry.Key

	// Generation is the registry generation this residency was installed under.
	// Every step is fenced by it, so a warm timer armed for one residency
	// cannot act on the residency that REPLACED it under the same key.
	Generation() uint64

	// Lost closes when this Host's residency grant is gone. The warm path then
	// abandons the session: releasing under a lost grant would write fenced
	// records under an epoch a successor has superseded, and Heartbeat.surrender
	// already owns the handoff for that case.
	Lost() <-chan struct{}

	// BeginRelease marks the residency releasing and publishes that state
	// durably, without terminating it.
	BeginRelease(context.Context) error

	// Checkpoint commits the runtime and workspace checkpoints the release
	// requires.
	Checkpoint(context.Context) error

	// ReleaseResidency closes process-local resources. It is NONTERMINAL: no
	// terminal event is appended and the session stays durable and resumable.
	ReleaseResidency(context.Context) error

	// FinishRelease writes the epoch-fenced tombstone and removes the visible
	// Host registry entry.
	FinishRelease(context.Context) error

	// ReleaseLease drops the residency grant.
	ReleaseLease(context.Context) error

	// DropState drops in-memory state and disposable local materializations.
	DropState(context.Context) error

	// AbortRelease returns a session whose runtime refused to release to an
	// ordinary resident, admitting session under the same generation: the
	// registry and the durable observation go back to `resident, accepting`
	// and BeginRelease and Checkpoint may run again. It must refuse when it
	// cannot deliver that — the session's work already stopped, the Host is
	// draining, the grant is gone — and the release is then left held.
	AbortRelease(context.Context) error
}

type WarmStep string

type WarmTimer interface {
	// C is the expiry channel.
	C() <-chan time.Time

	// Stop cancels an arming.
	Stop() bool

	// Reset arms the timer for a fresh duration.
	Reset(time.Duration) bool
}

type WorkState string

type Workspaces interface {
	// EnsureWorkspace makes a workspace available and returns its root.
	EnsureWorkspace(context.Context, sessionwire.TenantID, sessionwire.SessionID) (string, error)

	// ReleaseWorkspace drops the local materialization. It never deletes
	// durable state.
	ReleaseWorkspace(context.Context, sessionwire.TenantID, sessionwire.SessionID) error
}