@spec activate(
  GenServer.server(),
  Spectre.Definition.Candidate.Ref.t() | String.t(),
  keyword()
) ::
  {:ok, Spectre.Instance.Activation.t()} | {:error, term()}

Activates a published bootstrap or approved governed Candidate through generation CAS.

:expected_generation is mandatory and must be 0 for the first activation. Candidate, Definition, Manifest, and publication receipt are re-read from the configured Definition Store inside the Instance sequencer. Governed Candidates additionally replay exact gate and approval evidence.

@spec activation(GenServer.server()) :: Spectre.Instance.Activation.t() | nil

Returns the currently committed Definition Activation, if any.

@spec admit_event(
  GenServer.server(),
  Spectre.Event.Envelope.t() | map() | keyword(),
  keyword()
) ::
  {:ok, Spectre.Event.Envelope.t()} | {:error, term()}

Admits an ownership-based Event Envelope on the Instance sequencer.

The origin is retained as evidence. Replies and progress are owned by their continuation's pinned Definition; new input is owned by the active Definition. Unresolvable or ambiguous continuations are quarantined.

@spec admitted_events(
  GenServer.server(),
  keyword()
) :: [Spectre.Event.Envelope.t()]

Returns committed admitted Event Envelopes, newest first.

@spec agent(GenServer.server()) :: module()

Returns the compiled Agent module this Instance runs.

@spec ask(GenServer.server(), term(), keyword()) ::
  {:ok, Spectre.Result.t()} | {:error, term()}

Handles one input and returns its raw Result at the first boundary.

@spec authorize_delivery(
  GenServer.server(),
  String.t(),
  term(),
  Spectre.Operation.Delivery.Policy.t() | map() | keyword(),
  keyword()
) :: {:ok, Spectre.Operation.Delivery.Receipt.t()} | {:error, term()}

Authorizes, defers, digests or denies delivery without sending it.

@spec checkpoint(GenServer.server()) :: {:ok, String.t()} | {:error, term()}

Encodes the complete canonical Agent checkpoint as strict JSON.

@spec checkpoint_status(GenServer.server()) :: map()

Returns the redacted status of canonical checkpoint persistence.

@spec definition_lifecycle(
  GenServer.server(),
  Spectre.Definition.Ref.t() | String.t() | :active
) ::
  {:ok, Spectre.Instance.Lifecycle.t()} | {:error, term()}

Returns the current lifecycle axes for one Definition or :active.

@spec definition_store(GenServer.server()) :: Spectre.Definition.Store.config() | nil

Returns the configured Definition Store, if any.

@spec delivery_receipts(
  GenServer.server(),
  keyword()
) :: [Spectre.Operation.Delivery.Receipt.t()]

Returns redacted committed delivery receipts.

@spec drain_definition(
  GenServer.server(),
  Spectre.Definition.Ref.t() | String.t() | :active,
  keyword()
) :: {:ok, Spectre.Instance.Lifecycle.t()} | {:error, term()}

Moves a Definition to draining: continuations remain admissible, new work does not.

@spec flush_checkpoint(
  GenServer.server(),
  keyword()
) :: {:ok, non_neg_integer()} | {:error, term()}

Waits until the current canonical revision is durably checkpointed.

@spec info(GenServer.server()) :: map()

Returns a privacy-safe operational view of the Instance scheduler.

@spec loop(GenServer.server(), Spectre.Operation.Ref.t() | String.t(), keyword()) ::
  {:ok, Spectre.Operation.View.t()} | {:error, term()}

Returns a committed read-only view of one operational loop.

@spec loops(
  GenServer.server(),
  keyword()
) :: {:ok, [Spectre.Operation.View.t()]} | {:error, term()}

Lists committed Work, Vigil and controller views visible to the caller.

@spec operation_events(
  GenServer.server(),
  keyword()
) :: [Spectre.Operation.Event.t()]

Returns committed operational events without turning them into notifications.

@spec pause_loop(
  GenServer.server(),
  Spectre.Operation.Ref.t() | String.t(),
  keyword()
) ::
  {:ok, Spectre.Operation.View.t()} | {:error, term()}

Requests a reversible pause, at a safe boundary by default.

@spec put_delivery_consent(
  GenServer.server(),
  Spectre.Operation.Delivery.Consent.t() | map() | keyword(),
  keyword()
) :: {:ok, Spectre.Operation.Delivery.Consent.t()} | {:error, term()}

Stores revocable proactive-delivery consent for this Subject.

@spec quarantined_events(
  GenServer.server(),
  keyword()
) :: [Spectre.Event.Envelope.t()]

Returns quarantined Event Envelopes, newest first.

@spec reconcile_checkpoint(
  GenServer.server(),
  keyword()
) :: {:ok, non_neg_integer()} | {:error, term()}

Explicitly reconciles a checkpoint write whose commit outcome was ambiguous.

@spec record_delivery(
  GenServer.server(),
  String.t(),
  :authorized | :delivered | :failed,
  term(),
  keyword()
) :: {:ok, Spectre.Operation.Delivery.Receipt.t()} | {:error, term()}

Re-authorizes a deferred/digest receipt or records its transport outcome.

@spec ref(GenServer.server()) :: Spectre.Instance.Ref.t()

Returns the logical Instance reference.

@spec register_vigil(GenServer.server(), module(), term(), keyword()) ::
  {:ok, Spectre.Operation.Ref.t(), Spectre.Operation.View.t()}
  | {:error, term()}

Registers a durable Vigil owned by this Agent Instance.

@spec renew_loop(
  GenServer.server(),
  Spectre.Operation.Ref.t() | String.t(),
  non_neg_integer(),
  keyword()
) :: {:ok, Spectre.Operation.View.t()} | {:error, term()}

Renews the declared expiry of a nonterminal loop.

@spec resolve_loop(
  GenServer.server(),
  Spectre.Operation.Ref.t() | String.t() | map() | keyword() | nil,
  keyword()
) :: {:ok, Spectre.Operation.View.t()} | {:error, term()}

Resolves exactly one visible loop or returns an explicit ambiguity.

@spec resume(GenServer.server(), Spectre.Run.Ref.t(), term(), keyword()) ::
  {:ok, Spectre.Turn.t()} | {:error, term()}

Resumes an owned Run through a revision-fenced Runtime command.

Effect execution is dispatched outside the actor and returns through the canonical {:spectre, :invocation_result, invocation_id, receipt} mailbox message before the actor applies the returned Run.

@spec resume_loop(
  GenServer.server(),
  Spectre.Operation.Ref.t() | String.t(),
  keyword()
) ::
  {:ok, Spectre.Operation.View.t()} | {:error, term()}

Resumes a reversibly paused operational loop.

@spec revoke_definition(
  GenServer.server(),
  Spectre.Definition.Ref.t() | String.t() | :active,
  keyword()
) :: {:ok, Spectre.Instance.Lifecycle.t()} | {:error, term()}

Revokes current Definition authority and advances its authority epoch.

@spec revoke_delivery_consent(GenServer.server(), String.t(), keyword()) ::
  {:ok, Spectre.Operation.Delivery.Consent.t()} | {:error, term()}

Revokes previously stored proactive-delivery consent.

@spec rollback(
  GenServer.server(),
  Spectre.Definition.Candidate.Ref.t() | String.t(),
  keyword()
) ::
  {:ok, Spectre.Instance.Activation.t()} | {:error, term()}

Rolls activation back to an explicitly selected ancestor Candidate.

@spec run(GenServer.server(), String.t() | Spectre.Run.Ref.t()) ::
  {:ok, map()} | {:error, term()}

Returns a compact view of one retained Run or tombstone.

@spec skill_state(GenServer.server(), atom() | String.t(), keyword()) ::
  {:ok, Spectre.Skill.StateBinding.t()} | {:error, term()}

Returns the active or explicitly selected branch for a stable Skill id.

@spec skill_state_branches(GenServer.server(), atom() | String.t(), keyword()) ::
  {:ok, [Spectre.Skill.StateBinding.t()]} | {:error, term()}

Lists non-purged Skill-state branches newest-generation first.

@spec start_controller(GenServer.server(), module(), term(), keyword()) ::
  {:ok, Spectre.Operation.Ref.t(), Spectre.Operation.View.t()}
  | {:error, term()}

Starts a library-owned controller on the shared operational runtime.

@spec start_execution(
  GenServer.server(),
  Spectre.Execution.Materialization.t(),
  keyword()
) ::
  {:ok, Spectre.Operation.Ref.t(), Spectre.Operation.View.t()}
  | {:error, term()}

Starts a verified data-driven Work on the shared operational runtime.

@spec start_link([option()]) :: GenServer.on_start()

Starts the unique local Instance for an Agent and Subject.

@spec start_work(GenServer.server(), module(), term(), keyword()) ::
  {:ok, Spectre.Operation.Ref.t(), Spectre.Operation.View.t()}
  | {:error, term()}

Starts a precise Work owned by this Agent Instance.

This is a host boundary. Operational Runners and their isolated executor processes cannot call it; a Directive starts Work through a declared Agent-side reducer intent.

@spec stop_loop(
  GenServer.server(),
  Spectre.Operation.Ref.t() | String.t(),
  term(),
  keyword()
) ::
  {:ok, Spectre.Operation.View.t()} | {:error, term()}

Stops an operational loop terminally; it cannot be resumed.

@spec trace_id(GenServer.server()) :: {:ok, String.t()} | {:error, term()}

Returns the Instance's trace identifier.

One trace spans one Instance generation: a new id is minted whenever the agent process (re)starts, which matches journal session semantics. Returns {:error, reason} instead of raising when the Instance is unreachable, so hosts can fall back to their own identifier.

{:ok, trace_id} = Spectre.Instance.trace_id(instance)

@spec transition_definition_lifecycle(
  GenServer.server(),
  Spectre.Definition.Ref.t() | String.t() | :active,
  Spectre.Instance.Lifecycle.axis(),
  atom(),
  keyword()
) :: {:ok, Spectre.Instance.Lifecycle.t()} | {:error, term()}

Transitions one Definition lifecycle axis through revision CAS.

@spec transition_skill_state_retention(
  GenServer.server(),
  atom() | String.t(),
  String.t(),
  Spectre.Skill.StateBinding.retention(),
  keyword()
) :: {:ok, Spectre.Skill.StateBinding.t()} | {:error, term()}

Transitions one dormant Skill-state branch through the retention lifecycle.

@spec trigger_loop(
  GenServer.server(),
  Spectre.Operation.Ref.t() | String.t(),
  term(),
  keyword()
) ::
  {:ok, Spectre.Operation.View.t()} | {:error, term()}

Delivers a declared timer/event/human trigger to a waiting loop.

Echo view.wait_ref.id as :wait_id and view.wait_ref.generation as :generation. Definitions using strict trigger correlation require both.

@spec turn(GenServer.server(), term(), keyword()) ::
  {:ok, Spectre.Turn.t()} | {:error, term()}

Handles one input and returns its public Turn projection.

@spec update_and_resume_loop(
  GenServer.server(),
  Spectre.Operation.Ref.t() | String.t(),
  term(),
  keyword()
) :: {:ok, Spectre.Operation.View.t()} | {:error, term()}

Pauses, updates and resumes a loop as one durable correlated intention.

@spec update_loop(
  GenServer.server(),
  Spectre.Operation.Ref.t() | String.t(),
  term(),
  keyword()
) ::
  {:ok, Spectre.Operation.View.t()} | {:error, term()}

Commits an update through the controller's deterministic reducer.

@spec update_skill_state(GenServer.server(), atom() | String.t(), term(), keyword()) ::
  {:ok, Spectre.Skill.StateBinding.t()} | {:error, term()}

Updates one active Skill-state branch through schema, generation and revision fences.