Spectre.Morph.Surface (Spectre v0.3.0)

Copy Markdown View Source

Canonical, closed declaration of the changes an Agent is willing to review.

A Surface is a ceiling over proposals, never an authority grant. The governance Composer still intersects it with Manifest authority and host policy. Runtime data cannot add operation types, widen scopes, or increase prompt budgets after the Definition has been published.

The value object in this module owns transport normalization and identity. Enforcement lives in Spectre.Morph.Surface.Policy, while mandatory replay cases are derived by Spectre.Morph.Surface.EvaluationObligations.

Summary

Types

approval_requirement()

The minimum approval source required by the Agent Surface.

t()

The normalized immutable proposal ceiling sealed in Definition identity.

Functions

allows?(surface, operation)

Returns whether the Surface permits proposing an operation type.

applicability_ceilings(surface, mount_ids)

Builds exact applicability ceilings for the affected mount identifiers.

digest(surface)

Returns the canonical Surface digest used in audit evidence.

from_canonical(canonical)

Reads and validates the immutable Surface of an Agent Definition.

from_data(data)

Restores a Surface from decoded canonical data.

new(surface)

Builds a normalized proposal Surface.

new!(attrs)

Builds a Surface or raises ArgumentError with its validation reason.

operation_types()

Returns the complete closed vocabulary of Morph proposal operations.

schema_ref()

Returns the stable schema reference for the canonical component.

to_data(surface)

Returns the transport-stable data sealed into Definition identity.

Types

approval_requirement()

@type approval_requirement() :: :host_policy | :human

The minimum approval source required by the Agent Surface.

t()

@type t() :: %Spectre.Morph.Surface{
  approval_requirement: approval_requirement(),
  operation_types: [String.t()],
  prompt_token_ceiling: pos_integer(),
  schema_version: pos_integer(),
  scope_ceiling: [String.t()]
}

The normalized immutable proposal ceiling sealed in Definition identity.

Functions

allows?(surface, operation)

@spec allows?(t(), atom() | String.t()) :: boolean()

Returns whether the Surface permits proposing an operation type.

applicability_ceilings(surface, mount_ids)

@spec applicability_ceilings(t(), [String.t()]) :: map()

Builds exact applicability ceilings for the affected mount identifiers.

digest(surface)

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

Returns the canonical Surface digest used in audit evidence.

from_canonical(canonical)

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

Reads and validates the immutable Surface of an Agent Definition.

from_data(data)

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

Restores a Surface from decoded canonical data.

new(surface)

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

Builds a normalized proposal Surface.

Atom keys are accepted only as an Elixir authoring convenience. Transport data uses the exact string-key schema returned by to_data/1.

new!(attrs)

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

Builds a Surface or raises ArgumentError with its validation reason.

operation_types()

@spec operation_types() :: [String.t()]

Returns the complete closed vocabulary of Morph proposal operations.

schema_ref()

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

Returns the stable schema reference for the canonical component.

to_data(surface)

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

Returns the transport-stable data sealed into Definition identity.