interface.md

Invocation interface

Documentation / Internal package reference

Audience: in-module capability and Provider authors. Status: implemented technical calls, not a business execution engine. Package: github.com/frost-leo/fathomry/internal/invocation.

This package owns one state per accepted technical call: budgets, retained local use, typed results, independent evidence and optional observation. It does not own business retry/disposition, durable recording or a public capability API.

Capabilities and call sequence

Surface	Calling contract
Begin, BeginNested, Request	Reserve evidence before resource admission; enter native work only after acceptance
BeginClaimed, BeginNestedClaimed	Transfer exact record custody directly while retaining the same shared Inbox count/byte and resource limits; no forwarding queue
Budget.Context	Give each actual phase a caller-owned context
Call, Scope, Guard	One producer, explicit retained users and a guard before any possible early callback
Resolve, Finish, Release, Complete, Execute	Keep reporting and ending local use separate
Outcome, Result, *Receipt	Read typed facts without producer/evidence-release authority
Inbox, DeliveryRecord	Keep bounded evidence independently of the direct caller
Observer, Event, ExportOne	Optional lossy observation, not required evidence

Obtain an Access using resource.AccessFor with an explicit resource allowance, create a bounded Inbox, then Begin. Drive the SDK using appropriate phase budgets and retained use, report facts, confirm local termination, and let the independent receiver inspect/release its delivery. A rejected Begin accepts no SDK operation or receipt. An accepted call cannot be abandoned when the caller stops waiting.

Claimed entrypoints return their exact DeliveryRecord rather than enqueueing it for Inbox.Next. Use these only when another already-reserved evidence boundary owns synchronous transfer. Release is still forbidden before actual subtree termination. Queued and claimed records share one capacity; no receiver may discard a claimed record, steal another operation's FIFO receipt, or resend SDK work to retry record reception.

Ownership and zero values

The receipt is concrete *Receipt[T], not a public interface. Call/Receipt copies share one state; Scope/Guard copies retain the same lease responsibility. Do not copy owner objects such as Inbox, Observer or DeliveryRecord; use their pointers.

Nil/zero Receipt.Result returns a zero value and false; Wait methods return ErrWait. Scope{}.Hold fails with a resource admission error. Nil/zero Call methods do not invent acceptance/completion. A nil Observer disables observation; exporting needs a correctly constructed observer, context and callback.

Result metadata is copied, while generic values and native errors remain borrowed. Freeze/bound transferred data and define its concurrent use. Runtime call/result/ receipt/evidence values refuse ordinary JSON, not arbitrary nested metadata or standard Go error wrappers. No durable format is implied.

Per-call association and attempts

Request.Name uses the existing 1-64 character source-label syntax. Each call supplies Request.Correlation, a fault.Correlation value:

Field	Meaning
Call	Required logical call ID; uniqueness belongs to the caller's documented scope
Parent	Optional logical parent, not the call itself; nested calls must name their actual parent
Owner	Optional opaque caller association; not quota scope, authorization or proof of effect ownership

Nonempty correlation IDs use 1-128 ASCII letters, digits, dots, underscores or hyphens. Validation bounds representation, not identity authenticity or privacy. Background calls need a logical Call ID, not an invented Run. Source identity, original composition scope and configuration revision come from the actual record; aliases and user input do not overwrite them. Scope-label uniqueness remains composition's responsibility, not a global registration guarantee.

Run, Item and framework execution attempts do not enter this core. A real boundary must freeze their attribution before work begins and retain it for independent evidence reception, including after an early wait return. The boundary fixtures use an immutable, bounded typed envelope: envelope presence is distinct from business-data presence. They do not add a global Call-to-Run map or a production Adapter/runtime.

Call.Attempt records a genuinely intercepted SDK attempt immediately before its entry. It does not execute or retry anything. AttemptsKnown=false, MaxAttempts=0 means observations are lower bounds. Exact accounting requires proven complete instrumentation and a positive local maximum. The configured attempt allowance must include necessary cleanup; exhausting it does not establish rollback or release. Parent and child calls have separate attempt observations; do not sum physical batches or terminal Items by counting wrappers.

SDK-owned retries, authentication refresh, batching and background traffic need explicit interception, native bounds or an unsupported status. A local logical-call ceiling is not account-wide request rate control. This foundation neither introduces retries nor implements a distributed shared-limit backend.

Results and failure boundaries

Wait errors describe waiting, independently of Result.Err's primary/cleanup facts. A nil error is not proof of an external effect. Initial publication, final reporting and local subtree release are separate observations. Cancellation is not rollback or permission/evidence release. Preserve partial and unknown output explicitly.

Technical errors retain native inspection. The error/evidence architecture owns future framework attribution; no mutable current Run is stored on shared clients.

Details and executable evidence

• Budgets, completion, evidence, observation.
• Call source, result source, evidence source.
• Call example, lifetime tests, evidence tests, boundary tests.

Run go doc -all ./internal/invocation for exact declarations. Foundation: Issue #5; private boundary: Issue #15.