@spec after_actions(module()) :: [map()]

Returns every Agent and mounted-Skill action hook after logical binding.

@spec before_actions(module()) :: [map()]

Returns the Agent's pre-execution action guards after logical binding.

Guards are Agent-owned infrastructure: Skills cannot contribute them.

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

Lowers a compiled Agent or Skill module into its portable canonical IR.

This snapshots governed prompt assets, replaces executable callbacks with compiled code references, and returns the content-addressable Definition envelope used by projections.

@spec canonical!(
  module(),
  keyword()
) :: Spectre.Definition.Canonical.t()

Returns the canonical Definition or raises with its stable lowering reason.

@spec fetch(module()) :: {:ok, t()} | {:error, term()}

Returns the compiled definition exposed by a DSL module.

Legacy Agent modules that only expose the original metadata callbacks are normalized into a definition so runtime callers have one access path.

@spec fetch!(module()) :: t()

Returns a definition or raises an ArgumentError with a stable reason.

@spec for_scope(module(), scope()) :: {:ok, t()} | {:error, term()}

Resolves the definition active for a route scope.

@spec for_scope!(module(), scope()) :: t()

Returns the definition for a scope or raises an ArgumentError.

@spec injections(module(), scope()) :: [term()]

Returns Agent injections followed by the active Skill injections.

Scope-specific ordering is handled later by Spectre.Prompt.Plan; this function only selects definitions participating in the current route.

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

Composes the compiled source into a sealed Definition Manifest V2.

Stack V1 declarations are treated as requests and intersected with the trusted :authority_ceiling. Omitting that ceiling produces no grants.

@spec manifest!(
  module(),
  keyword()
) :: Spectre.Definition.Manifest.t()

Composes a compiled Definition Manifest or raises.

@spec mount(module(), scope()) :: Spectre.Skill.Mount.t() | nil

Returns the mount for a scope when it exists.

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

Builds a normalized compiled definition.

@spec policy(module(), term()) :: {:ok, map(), scope()} | {:error, term()}

Resolves a policy reference to its definition and owning scope.

Legacy atom references resolve in Agent scope. Skill policy references are represented as {{:skill, mount_id}, policy_name}.

@spec policy_name(term()) :: atom() | nil

Returns the local policy name from a scoped reference.

@spec policy_ref(scope(), atom()) :: atom() | {scope(), atom()}

Returns a stable policy reference for a scope.

@spec policy_scope(term()) :: scope()

Returns the scope carried by a policy reference.

@spec prompt_root(module(), scope()) :: {:ok, String.t()} | {:error, term()}

Resolves an owning module's prompt root within an Agent composition.

@spec protections(module()) :: [map()]

Returns every protection visible to an Agent with Skill action bindings and scoped policy references applied.

@spec rules(module()) :: [map()]

Returns every rule visible to an Agent with mount ownership materialized.