Spectre.AgentRef (Spectre v0.3.0)

Stable logical identity of a Spectre Agent.

An Agent reference is process-, node-, Definition-, and Stack-independent. The compiled module, declared Definition version, and Stack digest are kept only as resolver hints for the 0.2 boundary; they never participate in the stable key. legacy_key/1 exposes the former key explicitly so a Checkpoint Store can perform a controlled migration instead of silently creating or merging Instances.

Summary

Types

t()

Functions

from_data(value)

Restores a stable AgentRef without creating atoms from persisted data.

from_id(id, opts \\ [])

Builds a stable reference from a portable logical id.

key(ref)

Returns the stable opaque key used by Instance routing and storage.

legacy_key(ref)

Returns the pre-0.2.3 key when the resolver hints needed to reproduce it are present.

new(agent_or_ref, opts \\ [])

Builds a stable logical reference from an Agent module or returns an existing reference.

schema_version()

Returns the current stable AgentRef schema version.

to_data(ref)

Returns the portable stable identity without making source hints authoritative.

Types

t()

@type t() :: %Spectre.AgentRef{
  definition: module() | nil,
  id: String.t(),
  schema_version: pos_integer(),
  stack_digest: String.t() | nil,
  version: pos_integer() | nil
}

Functions

from_data(value)

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

Restores a stable AgentRef without creating atoms from persisted data.

from_id(id, opts \\ [])

@spec from_id(
  term(),
  keyword()
) :: t()

Builds a stable reference from a portable logical id.

This is the durable boundary form. :definition, :version, and :stack_digest may be supplied as trusted resolver hints but are not required to route the identity.

key(ref)

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

Returns the stable opaque key used by Instance routing and storage.

legacy_key(ref)

@spec legacy_key(t()) :: {:ok, String.t()} | {:error, term()}

Returns the pre-0.2.3 key when the resolver hints needed to reproduce it are present.

The legacy key is never selected automatically as the current identity. It exists only for explicit Checkpoint Store migration.

new(agent_or_ref, opts \\ [])

@spec new(
  module() | t(),
  keyword()
) :: t()

Builds a stable logical reference from an Agent module or returns an existing reference.

The optional :id distinguishes intentionally separate logical Agents that use the same compiled source. Definition and Stack fields are resolver hints only and can change without changing key/1.

schema_version()

@spec schema_version() :: pos_integer()

Returns the current stable AgentRef schema version.

to_data(ref)

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

Returns the portable stable identity without making source hints authoritative.