Spectre.Definition.Canonical (Spectre v0.3.0)

Portable, immutable envelope for declared Spectre behavior.

A canonical Definition contains a small versioned header and typed components. It is the single input to Definition identity and deterministic projections; compiled Agent and Skill definitions enter this representation through lower/2.

Summary

Types

t()

Functions

canonicalization_version()

Returns the current canonical Definition schema version.

contract_version()

Returns the current canonical Definition contract version.

decode(encoded)

Decodes and validates canonical Definition bytes.

digest(canonical)

Returns the stable lowercase SHA-256 identity digest.

encode(canonical)

Encodes a Definition into canonical bytes.

encode!(canonical)

Encodes a Definition or raises on an invalid envelope.

fetch_component(canonical, component_type)

Fetches one component by its unique type.

from_data(data)

Restores and validates an envelope from portable decoded data.

lower(source, opts \\ [])

Lowers a compiled Spectre.Definition or DSL module into the canonical IR.

lower!(source, opts \\ [])

Lowers a compiled Definition or raises with its stable failure reason.

new(canonical)

Builds and validates a canonical Definition envelope.

new!(attrs)

Builds a canonical Definition or raises with its stable validation reason.

ref(canonical)

Returns the content-addressed Ref for a Definition.

to_data(canonical)

Returns the portable envelope used for encoding and projections.

Types

t()

@type t() :: %Spectre.Definition.Canonical{
  canonicalization_version: pos_integer(),
  components: [Spectre.Definition.Component.t()],
  contract_version: pos_integer(),
  declared_version: term(),
  digest_algorithm: :sha256,
  id: term(),
  kind: :agent | :skill,
  origin: :compiled | :runtime
}

Functions

canonicalization_version()

@spec canonicalization_version() :: pos_integer()

Returns the current canonical Definition schema version.

contract_version()

@spec contract_version() :: pos_integer()

Returns the current canonical Definition contract version.

decode(encoded)

@spec decode(binary()) :: {:ok, t()} | {:error, term()}

Decodes and validates canonical Definition bytes.

digest(canonical)

@spec digest(t()) :: String.t()

Returns the stable lowercase SHA-256 identity digest.

encode(canonical)

@spec encode(t()) :: {:ok, binary()} | {:error, term()}

Encodes a Definition into canonical bytes.

encode!(canonical)

@spec encode!(t()) :: binary()

Encodes a Definition or raises on an invalid envelope.

fetch_component(canonical, component_type)

@spec fetch_component(t(), atom() | String.t()) ::
  {:ok, Spectre.Definition.Component.t()}
  | {:error, {:unknown_definition_component, term()}}

Fetches one component by its unique type.

from_data(data)

@spec from_data(map()) :: {:ok, t()} | {:error, term()}

Restores and validates an envelope from portable decoded data.

lower(source, opts \\ [])

@spec lower(
  module() | Spectre.Definition.t(),
  keyword()
) :: {:ok, t()} | {:error, term()}

Lowers a compiled Spectre.Definition or DSL module into the canonical IR.

lower!(source, opts \\ [])

@spec lower!(
  module() | Spectre.Definition.t(),
  keyword()
) :: t()

Lowers a compiled Definition or raises with its stable failure reason.

new(canonical)

@spec new(map() | keyword()) :: {:ok, t()} | {:error, term()}

Builds and validates a canonical Definition envelope.

new!(attrs)

@spec new!(map() | keyword()) :: t()

Builds a canonical Definition or raises with its stable validation reason.

ref(canonical)

@spec ref(t()) :: Spectre.Definition.Ref.t()

Returns the content-addressed Ref for a Definition.

to_data(canonical)

@spec to_data(t()) :: map()

Returns the portable envelope used for encoding and projections.