runApplication with your existing entry point.
Select a target and deployment
SupplytargetId when more than one target is available. Explicit targetRevision and productVersionId override
the reported application-version fallback and the response must echo them exactly. These selectors request an existing
callable/deployment binding. They can be opaque references or actual deployed commits. The registry checks the authorized
caller, target, version/material and placement before dispatch. A matching echoed string alone neither creates nor proves
a canonical Builder Version. A canonical Builder Version UUID identifies an existing whole-material snapshot. Observed
metadata is linked only through the owning service’s actual Deploy binding. A key with Simulations but no Traces creates no managed
telemetry exporter. Existing fully explicit endpoint, credential, target/revision, Environment and Product Version
registration is also awaited. Configuration is validated and snapshotted before the optional transport is loaded. An explicit capture-off runtime with no ingest configuration can
still use that expert registration path.
Product-key registration defaults environmentLabel from the initialized context.environment. Pass
environmentLabel: 'development' to override it for a registration. The SDK snapshots and sends the exact label in
both Simulation discovery and the socket hello, separately from discovery’s canonical Environment UUID. If neither
value is supplied, the label is absent. Scoped telemetry context and discovery do not supply it. Fully explicit
registration can also supply environmentLabel. The platform owns validation of deployment placement before Test dispatch. The supplied label alone grants no invocation authority.
Track work and progress
Declare the application’s actual capabilities. Input defaults to text. Streaming, multi-turn and tools default to false. Awaiting Product-key registration resolves configuration.target.status() distinguishes connecting/ready/closing/closed, in-flight
work and pending acknowledgements. The concurrency limit defaults to 8 (maximum 100). Completed work holds its replay
slot until the platform acknowledges the terminal record. The runtime accepts at most 32 registrations.
The request contains structured/text input, supplied history, identity, deadline, effect scope and optional prior-response,
starting-state and actual application continuation references. emit({ type, payload }) supports text_delta, tool_call, tool_result and status. It snapshots JSON progress in a bounded 64-frame/4-MiB acknowledgement window per invocation. An exhausted window
stops further progress and reports uncertain execution without a sequence gap. Each real invocationId remains distinct
from Run, case, turn, accepted-request, lease, idempotency and logical Interaction identity. Before the handler runs,
the SDK reports that technical invocation context and retains it in metadata['impact.simulation.invocation.id'].
Native trace identity is not itself a Product readback claim.
Join Simulation with application requests
Registration contributes the suppliedinteractionId, sessionId, user.id and trusted Simulated origin to a technical
invocation span. It does not create another completion owner. The target invokes the same application request function
used by ordinary traffic: that function calls interaction() for a new request or resolves actual stored application
state and calls continueInteraction() for an explicit transfer. The accepted request’s key is a declared association.
Use actual application observation to establish how work was grouped. An application-supplied result Interaction key is
preserved, never overwritten with the request key. A different explicit key produces the content-free
interaction_association_mismatch status with requested/reported keys, and the completion frame retains the reported
key. It does not retry work, repair grouping or claim logical success. Without an explicit application result key,
the required completion frame echoes only the accepted request’s declared association. That echo does not prove an
application wrapper ended the Interaction. The original accepted request remains intact.
Resume application work
A waiting application may returncontinuation: handle. A later request carries
continuation: { previousInvocationId, handle }. The opaque handle is preserved verbatim and bounded to 4,000 UTF-16
units. The application validates its pending state, predecessor and authorization. Persist the carrier with the pending
work, confirm that write, and use the same application request function when resuming it.
Handle reconnect, cancellation, and replay
Reconnect replays retained observations with a renewed lease and never calls the handler again. Cancellation delivers anAbortSignal. The application must honor it. Observed cancellation does not claim rollback or terminal cancellation
when the application completes instead. await target.close() closes this registration. Runtime shutdown closes all
its registrations. Starting state, cleanup and resource isolation remain application-owned.
Replays with the same accepted-request key and body converge through the original request deadline, including
after terminal acknowledgement. A changed body conflicts. Each registration retains at most 1,024 active or
unexpired terminal identities. At that bound, new offers receive retryable busy rather than evicting an identity
that could repeat an effect. Expired requests cannot run again. This is in-memory protection for the registration,
not durable recovery across process restart. Explicit endpoints require HTTPS/WSS except on loopback. Missing or
malformed request/lease correlation closes the protocol before application effects.