Backplane.AgentRuntime.Goal (backplane_agent_runtime v1.10.49)

Copy Markdown

Optional persistent thread goal owner. Host owns storage, user provenance and ordinary Session admission.

Summary

Functions

attribution(goal, binding)

bind(goal, attrs)

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

clear(goal, instruction)

committed(goal, event)

delegate(goal, parent_binding, attrs)

fork_snapshot(goal, target_thread)

get(goal)

idle(goal, generation)

restore(goal)

set(goal, mutation, instruction)

settle_unstarted_admission(goal, admission, reason, attestation)

Durably settles an exact released admission whose executor ended before Runtime admission.

Only the owner may attest to the closed evidence map containing the exact admission, executor: :confirmed_down, runtime_admission: :never_started, future_start: :fenced and effects: :none_dispatched. The host must correlate actual executor termination and permanently seal that token/generation at the same boundary as admission, including startup children and queued work. Missing Runtime state alone is not evidence. Keep the seal on storage errors.

Reasons are :preparation_failed, :superseded and :cancelled; only cancellation also durably defers continuation. Returns {:ok, {:settled, reason}} after an exact Store acknowledgement, including historical retries, or {:ok, {:not_settled, :stale | :bound | :started | :execution_observed}}. Persistence errors do not confirm settlement. This API never starts a turn.

snapshot(goal)

start_link(opts)

tool(goal, operation)

unbind(goal, binding)

withdraw_admission(goal, expected_admission, reason)

Withdraws an exact admission after its owner atomically prevents its release.

Pass the admission returned by idle/2, including :host_generation and the runtime-minted :reservation_token. :superseded clears only that reservation; :cancelled also durably defers automatic continuation without pausing the Goal.

Returns {:ok, {:withdrawn, reason}} or {:ok, {:not_withdrawn, :stale | :started}}. A matching committed start for the admitted run/incarnation prevents withdrawal even when the host's logical turn ID differs from the Runtime's minted turn ID. Once host release wins, ordinary Runtime cancellation is required, even before Goal sees that receipt, except for the explicitly host-attested no-start path in settle_unstarted_admission/4.

This owner-only call cannot fence the host's execution queue. Before calling, the host must atomically invalidate the exact token/generation against release and must never execute a successfully withdrawn reservation. Unknown storage acknowledgement is not withdrawal confirmation; reconcile before proceeding.