Submission and completion are different events
Starting a Play can return a public run ID before work finishes. That identity lets the application observe the same execution later. It is a durable handoff, not evidence that the business result already exists. For example, a signup handler can submit enrichment and end its HTTP response. The Play may finish afterward. The application needs to connect the eventual outcome to the original signup, rather than launch a new run each time its worker restarts. A synchronous wait is a convenience for the caller. Its timeout does not cancel remote work. Explicit cancellation and observing its result are separate operations.Recovering observation differs from replaying execution
Reading a known run asks what happened to existing work. Starting another run asks for a new execution. A recovery design must preserve that distinction. Direct tool calls have a caller-owned idempotency-key contract. Reusing a valid key with the same request observes or replays the original execution; changing the request can conflict. A Play’s internal tool-call label is not that public idempotency key. Neither contract establishes exactly-once effects in every external provider. An ambiguous provider outcome can remain unresolved. Independent Play cache misses can execute again, while completed matching work can be reused.The response is an execution contract, not a universal data model
A run package distinguishes status, outputs, retained results, and datasets. The compact status response is not an inline copy of every row. Dataset rows and full retained results have their own retrieval paths. Within tool results, the scrubbed provider response and declared extraction contracts serve different needs. A declared getter is useful for a supported semantic field. Provider-specific paths require the actual inspected response shape, not an assumption that every provider nests data identically. The application also needs a domain acceptance rule. A completed lookup with no usable candidate can be a valid result, while a failed request needs a separate failure path.One owner should apply the destination result
The Play can perform an authorized destination action, or the caller can apply the final result. Both are viable designs. Having both write independently can create duplicate work or conflicting state. In the signup example, the application might own the customer profile while the Play returns research. Another integration might let the Play update approved CRM fields directly. The chosen design determines where idempotency, verification, and reconciliation belong. A callback is also an external action. Losing its response can create the same uncertainty as any other write. Authentication and destination-supported idempotency still matter even when the enrichment itself completed.Usage is another recorded outcome
An empty result does not imply zero usage. Some operations charge for requests, validation, or accepted events, and a later call can be new work. The recorded billing outcome is the evidence for a charge; an absent or pending usage record is not proof that execution was free.Apply this understanding
- Production Play integration: persist IDs, resume observation, and verify writes.
- Tool execution recovery: direct-call key and input rules.
- HTTP and Python: raw response and polling examples.
- Runtime API reference: exact response contracts.