Crosswake.Compatibility.Finding (crosswake v0.2.0)

View Source

Typed restriction evidence returned by route_gated?/2 and evaluate_auth/3.

Companion implementations return {:deny, %Finding{}} to signal that a route is restricted. Core translates findings into Crosswake.Shell.Denial structs internally — companions must never construct Denial directly.

Required fields: :axis (atom identifying the policy axis, e.g. :route) and :message (human-readable explanation). Optional fields add structured evidence for logging and support surfaces.

Auth-classification fields (:code and :details)

:code carries a sub-classification string for auth-axis findings (e.g. "auth.step_up.stale_auth"). Auth companions MUST populate :code; a nil code downgrades to the string form of the denial reason at the finding_to_denial/2 boundary (documented nil-code downgrade, T-137-03).

:details carries an already-sanitized map of structured evidence for auth-axis findings. For :auth axis, finding_to_denial/2 passes :details through UNMERGED (no :axis key injected) so sanitization applied at the companion source is preserved exactly.

These two fields are additive — non-breaking to crosswake_rulestead and crosswake_rindle companions whose findings carry neither field (both default to nil / %{}).

Stability

Public stable — part of the Crosswake companion contract surface. Semver-protected under crosswake >= 0.1.0: no breaking changes to this module's struct fields, types, or callbacks without a major version bump. Companion packages (crosswake_rulestead, crosswake_rindle, etc.) may safely alias and pattern-match on this type.

Summary

Types

t()

Restriction evidence emitted by a companion's route_gated?/2 or evaluate_auth/3 callback.

Types

t()

(since 0.1.0) 
@type t() :: %Crosswake.Compatibility.Finding{
  available: String.t() | atom() | nil,
  axis: atom(),
  code: String.t() | nil,
  details: map(),
  hint: String.t() | nil,
  message: String.t(),
  required: String.t() | atom() | nil,
  route_id: String.t() | nil,
  subject: String.t() | nil
}

Restriction evidence emitted by a companion's route_gated?/2 or evaluate_auth/3 callback.