session

type Actor[I IIdentity] struct {
	// contains filtered or unexported fields
}

type DenyError struct {
	// Reason is operator-facing. The client is told a generic denial, because
	// the reason an event was refused describes the rule that refused it.
	Reason string
}

type Effect[I IIdentity] struct {
	// Source names the effect for provenance and metrics. It is refined before
	// the effect runs, because it becomes half of an Origin.source.
	Source string

	// Run performs the effect, on the goroutine spawn starts for it.
	//
	// scheduledBy is the identifier of the event whose transition returned this
	// effect, or zero when the server started the transition itself. It is
	// handed over rather than re-derived because FR-58 requires every
	// library-produced error to name the causal identifier where one exists,
	// and the errors the public adapter raises against an emitted event are
	// raised before any identifier of their own is minted.
	//
	// A nil Run is a mistake rather than a no-op, and execute refuses it with a
	// failure event: an effect that never runs is a change that never happens.
	Run func(ctx context.Context, p Peer[I], scheduledBy uint64, emit Emit) error
}

type Emit func(event Event) error

type Event struct {
	// ID is the server-minted causal root. It is zero for the transitions the
	// server started on its own, where the origin source names the cause.
	ID uint64
	// ClientRef is the client's own correlation handle, echoed back so the
	// browser can match a patch to the interaction that caused it.
	ClientRef uint64
	// SeenServerSeq is the causation edge: the sequence number of the last
	// patch the user had applied when they acted.
	SeenServerSeq uint64

	// Name is the event name the application registered, such as
	// "cart.add". An unregistered name never reaches here: it is refused at
	// ingress and counted.
	Name string

	// FragmentID is the live region the interaction happened in, empty when
	// the server started the transition itself.
	FragmentID string

	// At is stamped at the actor boundary, not read by the reducer from a
	// clock. That is what lets an event log replay to a byte-identical result.
	At time.Time

	// Fields are the form values the interaction carried, in the order they
	// arrived.
	Fields []Field

	// Contributing lists events in this session whose state changes this
	// event carries. It is only ever set on an event an effect emits, where
	// the application is the only party that knows the edge — the library
	// knows which event scheduled an effect, but not which event caused the
	// value an asynchronous fan-out is delivering.
	Contributing []uint64
}

type FatalDenyError struct {
	// Reason is operator-facing, as for DenyError.
	Reason string
}

type Field struct {
	// Key is the form field's name, as the browser sent it.
	Key string

	// Value is its value, already past the refinement boundary — length
	// bounded and valid UTF-8 — and past authorization, but otherwise
	// untrusted application input.
	Value string
}

type IApp[I IIdentity] interface {
	// Init produces the session's initial state and any startup effects. It
	// runs once, as the first transition, before the first snapshot.
	Init(ctx context.Context, p Peer[I]) (state any, effects []Effect[I], err error)

	// Authorize runs before the reducer for every event, at the single
	// mailbox ingress. It is the one method called from the read pump rather
	// than from the actor goroutine, because refusing an event before it
	// occupies a mailbox slot is the entire point of where it sits.
	Authorize(ctx context.Context, p Peer[I], ev Event) error

	// Reduce is the pure state transition.
	Reduce(state any, ev Event) (any, []Effect[I])

	// Teardown runs after the actor exits, with final state.
	Teardown(ctx context.Context, p Peer[I], state any)

	// Registry returns the application's fragments.
	Registry() *render.Registry

	// Registered reports whether an event name is declared. An unregistered
	// name is refused and counted, never dispatched and never ignored.
	Registered(name string) bool

	// StateComparable reports whether the application's state type may be
	// compared with == to decide whether a transition changed anything.
	//
	// It is false for a type Go cannot compare at all, and — the part that is
	// not obvious — for one Go compares only by IDENTITY: a pointer, map,
	// slice, channel, function or interface. Those are comparable in Go's
	// sense, so a naive type switch takes the fast path on them and asks "is
	// this the same object", which a reducer that mutates in place and returns
	// the same pointer answers "yes" to. That is the ordinary Go mistake the
	// purity rule exists to forbid, and answering it wrongly freezes
	// state_version and makes P4 false (BR-7).
	//
	// It is a method rather than a value the actor derives because deriving it
	// costs reflection over the state type, and the type does not change for
	// the life of an application: the answer is computed once, where the type
	// is still a type parameter and not an opaque any.
	StateComparable() bool
}

type ID [16]byte

type IIdentity interface {
	// Subject returns a stable, non-secret identifier used for logging and
	// per-identity session limits.
	Subject() string
}

type Limits struct {
	// MaxInboundFrameBytes caps a decoded frame, applied to the connection
	// before any payload is allocated.
	MaxInboundFrameBytes int

	// MaxEventsPerSecond and EventBurst are the inbound event token bucket.
	MaxEventsPerSecond float64

	// EventBurst is that bucket's depth: how far a flurry of interactions may
	// run ahead of the sustained rate before the limiter refuses.
	EventBurst int

	// MailboxDepth bounds the actor's mailbox. It is also a memory parameter:
	// a Go buffered channel allocates its whole backing array at make time,
	// for the life of the channel, occupied or not. The mailbox holds
	// pointers for that reason.
	MailboxDepth int

	// AckChannelDepth bounds the acknowledgement channel. A full channel
	// drops, which is lossless because an acknowledgement is a cumulative
	// high-water mark: the next one supersedes the one dropped and the window
	// re-opens a round trip later.
	AckChannelDepth int

	// AckWindow is the number of unacknowledged patches allowed in flight.
	AckWindow int

	// CoalesceFlushAt is the size of the contributing-event union at which a
	// coalesced patch is emitted immediately rather than coalesced further.
	// It is the union the frame will carry, not a proxy for it: the trigger
	// counts what emitPatch is about to build, including the identifiers the
	// application contributed to the event being emitted.
	//
	// It is a flush trigger, so the schema's ceiling is unreachable and no
	// contributing event is ever dropped — but only while it stays at or below
	// MaxCoalesceFlushAt. Above that the frame the flush constructs is one the
	// schema refuses, and the trigger becomes the loss. The exported boundary
	// enforces the range; this package documents it.
	CoalesceFlushAt int

	// MinResyncInterval and ResyncBurst are the resync bucket, deliberately
	// independent of the event bucket. A resync is the one client frame that
	// triggers work proportional to the whole state, so sharing a budget with
	// ordinary events would make it an amplification vector.
	MinResyncInterval time.Duration

	// ResyncBurst is that bucket's depth. It is small deliberately: a client
	// that legitimately needs a snapshot needs one.
	ResyncBurst int

	// WriteDeadline bounds a single socket write. Exceeding it with a full
	// outbound window is what evicts a client rather than blocking the actor
	// behind it.
	WriteDeadline time.Duration

	// SlowClientGrace is how long a full window is tolerated before the
	// session is closed as a slow client. It is the gap between "stop
	// emitting" and "give up".
	SlowClientGrace time.Duration

	// HeartbeatInterval is the value announced to the client in the mount
	// snapshot: how often it should send a heartbeat.
	HeartbeatInterval time.Duration

	// HeartbeatTimeout is how long the server waits for one before treating
	// the connection as dead. It is deliberately larger than
	// HeartbeatInterval, because equality would close a session on one late
	// frame.
	HeartbeatTimeout time.Duration

	// IdleTimeout closes a session that has exchanged no application traffic,
	// heartbeats excluded — a tab left open forever is a session holding
	// memory for nobody.
	IdleTimeout time.Duration

	// EffectDrainTimeout is how long teardown waits for in-flight effects to
	// return before it reports the overrun. Teardown keeps waiting after it:
	// every effect is joined before the session ends, so an effect that
	// ignores its cancelled context holds the session's shutdown open.
	EffectDrainTimeout time.Duration

	// PanicBudget is how many times one site may panic in a session before
	// the session closes. Other sessions are unaffected either way.
	PanicBudget int
}

type Options[I IIdentity] struct {
	// Peer is the identity and session identifier this actor is bound to for
	// its whole life. Neither changes: a re-authentication is a new session.
	Peer Peer[I]

	// App is the application behaviour — mount, reduce, render, execute — as
	// the type-erased interface this package can hold without knowing the
	// state type.
	App IApp[I]

	// Limits are the resource bounds. Zero fields are filled by Normalize, so
	// a caller may set one and leave the rest.
	Limits Limits

	// Framer is the only way out to the socket: it validates and marshals, so
	// there is no path from this actor to the transport that skips the
	// outbound boundary.
	Framer *protocol.Framer

	// Close ends the connection with an enumerated code. It is the transport's
	// close, called from whichever goroutine notices, and it is idempotent.
	Close func(code protocol.CloseCode, reason string)

	// Metrics, Tracer and Logger are the instrumentation triple, and each may
	// be nil, which is the disabled configuration rather than a missing
	// dependency: every method on all three is nil-receiver safe.
	Metrics *obs.Metrics

	// Tracer starts the session and transition spans. Nil disables tracing.
	Tracer *obs.Tracer

	// Logger writes the event, patch and provenance records. Nil disables
	// logging, including the provenance stream.
	Logger *obs.Logger

	// Dev is developer mode (FR-23). Its whole effect is on the message of the
	// Error frame a contained panic produces: see Actor.devMessage. It must be
	// false in production.
	Dev bool

	// Now and Ticks are the actor's only sources of time. They are injected
	// so that a test can drive a thirty-minute idle timeout without waiting
	// thirty minutes, and so that nothing on the transition path reads a clock
	// the test cannot see.
	Now func() time.Time

	// Ticks drives the heartbeat, the idle timeout and the slow-client grace.
	// A test supplies its own channel and delivers a tick when it wants one;
	// nothing here calls time.NewTicker.
	Ticks <-chan time.Time

	// Scope is the runtime scope every effect goroutine starts in. The
	// transport passes the live UI service's sessions scope, so the service's
	// join covers every effect; the actor itself also joins its own effects
	// before Run returns. It is required.
	Scope *runtime.Scope
}

type Peer[I IIdentity] struct {
	// ID is the sixteen server-minted bytes naming this session, carried on
	// every frame in both directions.
	ID ID

	// Identity is the authenticated principal, derived once from the upgrade
	// request, as the application's own type. It never changes for the life of
	// the session.
	Identity I
}

type RetryableError struct {
	// Err is the failure being classified. It is never nil: Retryable(nil) is
	// nil rather than a marked nil.
	Err error
}