Spectre.Router.Context (Spectre v0.3.0)

Copy Markdown View Source

Shared data passed through a Spectre router pipeline.

Router context is intentionally separate from runtime context. It is optimized for evidence collection: candidate routes, traces, errors, visible labels, and any input enrichment produced while routing.

Summary

Types

t()

Functions

add_candidate(context, candidate)

Appends a routing evidence candidate.

add_candidates(context, candidates)

Appends several routing evidence candidates.

halt(context)

Marks route evaluation as halted.

halted?(context)

Returns true when a router plug halted route evaluation.

hard_candidate?(context)

Returns true when accepted hard evidence already identifies a runnable route.

hard_candidate_locked?(context)

Returns true when hard evidence may safely short-circuit later providers.

put_arbitration(context, explanation)

Stores the canonical privacy-safe arbitration explanation.

put_error(context, error)

Appends an error event.

put_input(context, input)

Replaces the normalized input after enrichment.

put_local_result(context, result)

Stores non-terminal classifier/cache metadata for downstream plugs.

put_route(context, route)

Stores the current route in context.

put_trace(context, trace)

Appends a trace event.

Types

t()

@type t() :: %Spectre.Router.Context{
  arbitration: map() | nil,
  candidates: [Spectre.Router.Candidate.t()],
  errors: [term()],
  halted?: boolean(),
  host_context: map() | nil,
  input: Spectre.Input.t(),
  labels: [atom()],
  local_result: map() | nil,
  opts: keyword(),
  route: Spectre.Route.t() | nil,
  rules: [Spectre.Rule.t()],
  semantic_cache_query_embedding: [float()] | nil,
  traces: [term()]
}

Functions

add_candidate(context, candidate)

@spec add_candidate(t(), Spectre.Router.Candidate.t()) :: t()

Appends a routing evidence candidate.

context = Spectre.Router.Context.add_candidate(context, candidate)

add_candidates(context, candidates)

@spec add_candidates(t(), [Spectre.Router.Candidate.t()]) :: t()

Appends several routing evidence candidates.

context = Spectre.Router.Context.add_candidates(context, candidates)

halt(context)

@spec halt(t()) :: t()

Marks route evaluation as halted.

halted?(context)

@spec halted?(t()) :: boolean()

Returns true when a router plug halted route evaluation.

hard_candidate?(context)

@spec hard_candidate?(t()) :: boolean()

Returns true when accepted hard evidence already identifies a runnable route.

Expensive probabilistic providers can use this to avoid work that cannot change the default arbitration result. The arbitrator still owns the final route decision.

hard_candidate_locked?(context)

@spec hard_candidate_locked?(t()) :: boolean()

Returns true when hard evidence may safely short-circuit later providers.

This optimization is automatic for the built-in arbitrator. Custom arbitrators retain the complete evidence stream unless they explicitly set hard_short_circuit?: true.

put_arbitration(context, explanation)

@spec put_arbitration(t(), map()) :: t()

Stores the canonical privacy-safe arbitration explanation.

put_error(context, error)

@spec put_error(t(), term()) :: t()

Appends an error event.

put_input(context, input)

@spec put_input(t(), Spectre.Input.t()) :: t()

Replaces the normalized input after enrichment.

put_local_result(context, result)

@spec put_local_result(t(), map()) :: t()

Stores non-terminal classifier/cache metadata for downstream plugs.

put_route(context, route)

@spec put_route(t(), map()) :: t()

Stores the current route in context.

put_trace(context, trace)

@spec put_trace(t(), term()) :: t()

Appends a trace event.