Companion Contract

View Source

Reference — This guide enumerates the stable public surface that companion packages may depend on. For implementing a companion, see Companion Integrations. For declaring compatibility ranges, see Companion Compatibility Contract.

Contract Surface

The following five modules are the public companion contract surface, semver-stable under crosswake >= 0.1.0.

ModuleRoleWhat companion code does with itStability tier
Crosswake.CompanionBehaviourDeclare @behaviour Crosswake.Companion and implement all 6 callbacksPublic stable
Crosswake.Companion.StateReturn typeReturn from report_state/0Public stable
Crosswake.Compatibility.FindingReturn typeReturn {:deny, %Finding{}} from route_gated?/2Public stable
Crosswake.Compatibility.TargetInput typeReceive as argument in route_gated?/2 and kill_switch_active?/1Public stable
Crosswake.Manifest.Types.RouteEntryInput typeReceive as argument in route_gated?/2Public stable

Stability Tiers

  • Public stable — semver-protected under crosswake >= 0.1.0. No breaking changes to struct fields, types, or callbacks without a major version bump.
  • Private — @moduledoc false. Not part of any public API. May change without notice.

What Is Not Contract

Any module carrying @moduledoc false is internal to Crosswake core and must not be aliased or pattern-matched in companion code. Specifically:

  • Crosswake.Shell.Denial — core-owned envelope. Companions return {:deny, Finding.t()} from route_gated?/2; core translates findings into Denial structs internally. Companions must never construct or reference Denial directly, including Denial.reasons/0 — that function is for core operators, not companion authors. Emit your own denial-code strings via Finding.t().
  • All other Crosswake.Manifest.Types.* nested modules (Root, Host, Crosswake.Manifest.Types.Compatibility, Capability, etc.) — internal.
  • Eval machinery: Crosswake.Compatibility (the parent module), its internal functions and private helpers.

Declaring Compatibility

Companion packages declare the crosswake version range they are compatible with. See Companion Compatibility Contract for the required format.

Telemetry Events

Crosswake emits the following static companion span event names that companion implementations may observe (source of truth: Crosswake.Companion moduledoc):

  • [:crosswake, :companion, :validate_dependency, :start | :stop | :exception]

  • [:crosswake, :companion, :route_gate, :start | :stop | :exception]

  • [:crosswake, :companion, :kill_switch, :start | :stop | :exception]

All events carry %{companion_id: atom(), route_id: binary() | nil} metadata.