gates

type InvalidOptionsError struct {
	Field string
}

type Options struct {
	// Session is the session's durable gate surface. Required.
	Session Session

	// Hints is the runtime's committed stream. Required. Its deliveries are
	// hints only; see the package documentation.
	Hints department.PublicationSubscriber

	// After is the clock the retry waits on. Required.
	After func(time.Duration) <-chan time.Time

	// Retry is how long the publisher waits after a failed pass, or after
	// its subscription ended, before trying again. Required and positive.
	Retry time.Duration

	// OnConverged is called after each pass that converged the projection,
	// so a caller waiting on this Host's ownership of a gate can re-check.
	// Optional.
	OnConverged func()

	// Logger receives WARN records for failed passes. Optional.
	Logger *slog.Logger

	// StopBound is how long Stop waits for the publisher to return after
	// cancelling it. Zero means DefaultStopBound.
	//
	// N5, RECORDED AND NOT FIXED: NO COMPOSED HOST CAN SET IT. host.Composition
	// declares no field for it and internal/compose passes none, so every Host
	// built through host.Compose runs at DefaultStopBound and this field is
	// reachable only from a test. That is acceptable rather than merely
	// tolerated -- the released stores honour cancellation, so the bound is a
	// backstop against a provider that does not, and a deployment has no
	// information with which to choose a better number than five seconds. It is
	// written down because a configurable-looking option nobody can configure
	// is the kind of thing a reader assumes is wired.
	StopBound time.Duration
}

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

type Scope struct {
	TenantID         coresessionwire.TenantID
	SessionID        coresessionwire.SessionID
	AgentID          coresessionwire.AgentID
	RuntimeSessionID uuid.UUID
}

type Session interface {
	// Scope reads the session's durable binding once and returns its
	// identities. It must be called before Replay.
	Scope(context.Context) (Scope, error)

	// Projected returns the gates the durable projection holds open.
	Projected(context.Context) ([]coresessionwire.GateProjection, error)

	// Open projects one open gate under the bound grant. Replaying an
	// identical open is idempotent.
	Open(context.Context, coresessionwire.GateProjection) error

	// Resolve removes one gate from the projection under the bound grant. A
	// gate the projection does not hold is not an error; the write still
	// raises the residency mark.
	Resolve(context.Context, coresessionwire.GateID) error

	// Replay visits the runtime journal's events in sequence order from the
	// inclusive sequence from, with each event's ledger sequence.
	Replay(ctx context.Context, from uint64, visit func(event.Event, uint64) error) error
}