handqueue

type AspectHomeResolver interface {
	HomeFor(aspect string) (string, bool)
}

type AspectHomeResolverFunc func(aspect string) (string, bool)

type AspectTokenResolver interface {
	TokenFor(aspect string) (string, bool)
}

type AspectTokenResolverFunc func(aspect string) (string, bool)

type Config struct {
	// MaxConcurrent is the soft cap N — steady-state max-concurrent
	// worker count. Default 3 per spec §2.1. Spillover may push the
	// active count past N up to HardCeiling H for idle aspects.
	MaxConcurrent int

	// HardCeiling is the absolute cap H. Past H, dispatch arrivals
	// reject with ErrHardCeiling. If unset (or < MaxConcurrent),
	// defaults to MaxConcurrent + 1 (a defensive minimum); production
	// callers should pass roster_size + 1 per spec §2.1.
	HardCeiling int

	// DefaultDeadline overrides the spec default of 30 minutes per
	// dispatch when set; use 0 for the spec default.
	DefaultDeadline time.Duration

	// MaxDeadline overrides the spec hard maximum of 2 hours; use 0
	// for the spec default. Caller-supplied deadline_secs above this
	// is silently capped, not errored.
	MaxDeadline time.Duration

	// MaxQueueDepth caps the number of dispatches in the pending FIFO
	// (#25). Pre-cap, q.pending was unbounded — an authenticated peer
	// flooding dispatches faster than workers drained could grow the
	// queue (and the goroutines waiting on Submit) without limit. New
	// arrivals past this depth reject with ErrQueueFull. Default
	// from defaultMaxQueueDepth when zero.
	MaxQueueDepth int

	// Executor runs jobs. Required.
	Executor Executor

	// Logger is optional.
	Logger *slog.Logger

	// Now is the time source; tests inject deterministic clocks.
	// Default time.Now.
	Now func() time.Time
}

type Executor interface {
	Execute(ctx context.Context, req frames.DispatchPayload) (frames.DispatchResultPayload, error)
}

type ExecutorFunc func(ctx context.Context, req frames.DispatchPayload) (frames.DispatchResultPayload, error)

type HardCeilingError struct {
	Active  int
	SoftCap int
	Limit   int
}

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

type QueueFullError struct {
	Depth int
	Limit int
}

type SpawnExecutor struct {
	// HarnessPath is the absolute path to the harness executable.
	// If empty, defaults to looking up "harness" on PATH via
	// exec.LookPath semantics.
	HarnessPath string

	// HomeResolver maps aspect name → home folder on this host.
	HomeResolver AspectHomeResolver

	// TokenResolver maps aspect name → bearer token. Per spec §2.1
	// identity inheritance: workers authenticate to the broker as the
	// dispatching aspect (same token), so hand-posts are
	// indistinguishable from aspect-posts. Optional; if nil, falls
	// back to whatever NEXUS_TOKEN is in ExtraEnv.
	TokenResolver AspectTokenResolver

	// Env entries passed to the child, in addition to the parent's.
	// Typically carries NEXUS_UPSTREAM / NEXUS_OUTPOST so the worker
	// can dial back. Per-aspect NEXUS_TOKEN is injected by Execute
	// when TokenResolver returns one for the dispatching aspect; an
	// ExtraEnv NEXUS_TOKEN is the fallback for the no-resolver case
	// and is overridden by the resolver-supplied token when present.
	ExtraEnv []string
}

type Stats struct {
	ActiveTotal    int
	SoftCap        int
	HardCeiling    int
	QueueDepth     int
	ActiveByAspect map[string]int
}