Skip to main content
Simulation registers an existing application entry with Impact Testing when your deployment offers Simulation. Enable the Product key’s Simulations grant, initialize with the actual deployed application version, then explicitly register the entry. The SDK resolves its authorized connection and one unambiguous enabled target. Replace runApplication with your existing entry point.

Select a target and deployment

Supply targetId 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 supplied interactionId, 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 return continuation: 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 an AbortSignal. 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.