init() manages Impact
capture and explicitly selected capabilities. See application setup for lifecycle
and OpenTelemetry ownership.
Public API
Use
impact-ai/register as the managed ADK preload when it fits
your startup. Use impact-ai/otel for application-owned destinations.
impact-ai/mastra, impact-ai/realtime-events, and impact-ai/openai-x509 expose the corresponding native helpers.
Group work into an Interaction
Use oneinteraction(options, work) around a real application request. It preserves the ID you supply or
generates one at that boundary. Plain initialization, context, model calls, and manual spans leave Interaction
identity unchanged. A Session is an optional conversation or coherent job. A Product User key is an opaque
application identifier taken from the application’s verified request scope. The application supplies the key
and verifies the user. Route credentials establish Workspace and Product tenancy. You can attach a Session
without an Interaction, and stopping telemetry leaves the business conversation active.
The emitted attributes are impact.interaction.id, impact.session.id, and impact.user.id.
Their scope is the authenticated Product, independent of the ingest key or Source.
initMastra().request() observes the consumed response through
the SDK adapter. Its completion requires native terminal evidence and consumed EOF. This does not extend completion
observation to arbitrary HTTP responses or streams. See Mastra setup.
Continue work after a queue handoff
For queue work, explicitly hand completion to one application continuation after the native publisher confirms acceptance. Contributor propagation alone cannot transfer ownership:queue.publishConfirmed, acceptedResponse and the queue envelope above belong to the application. A buffered write
or an arbitrary returned object is not confirmation. confirm() is scoped to the active publishing callback and is
one-way. No confirmation leaves the request incomplete. A confirmed transfer is not undone by a later local error
or telemetry failure, and Impact never retries business work. Only the explicit transfer carrier can continue an
owner. A transfer without a Session continues without one, even if the receiver’s scope has a Session. Parallel
branches receive contributor context. One real application join retains or receives completion.
The application handles authorization and recovery, including any distributed guarantees for its business effects.
Add manual spans
span() never invokes the application callback twice. Result classification does not invoke then, next, iterator
accessors, or proxy traps. When those protocol properties cannot be inspected without running application code, the
original value is returned unchanged and terminal/output observation is marked unavailable. A safely identified custom
thenable is likewise returned untouched with its terminal output unobserved. Serialization loss is marked partial or
omitted and never replaces the application result.
Manual span() and Interaction input/output capture each contain one JSON document with application/json MIME. Decode that captured value once. JSON null, false, 0 and empty text ("") remain distinct, and text that looks like
JSON remains text. An absent value, a closed content state or a missing value/MIME pair is unavailable, not an empty or
null result.
Propagate context between services
injectContext() combines initialized defaults with the current scope and writes W3C traceparent/tracestate
plus one bounded impact-context entry. The latter is canonical UTF-8 JSON encoded as unpadded base64url, containing
version 2, optional interactionId, sessionId and domainRun. User attribution is not automatically propagated.
Identifiers are nonempty well-formed strings of at most 1,024 UTF-8 bytes. The encoded owned entry is at most
8,192 bytes. A malformed or conflicting existing entry rejects atomically: the entire carrier remains unchanged.
Use a fresh carrier per request, including when the current scope has no logical IDs.
extractContext(carrier) is pure and returns { context, nativeContext, issues } plus a validated transfer when
present. Apply contributor context with impact.context({ propagated: impact.extractContext(headers) }, work).
Malformed inbound correlation produces content-free diagnosis rather than a fabricated request. Explicit local
identity cannot silently disagree with received identity. Received data never selects tenancy or overrides local
user attribution. An existing application-owned native parent is preserved. For an application using a different
OpenTelemetry API registry, pass its public context owner once as init({ contextApi: callerContext }). Helpers use
that owner’s active and with methods without replacing a global manager or provider.
Create the gateway carrier inside each actual request’s active span and pass it through the application’s existing
per-request header option, for example fetch(gatewayUrl, { ...requestOptions, headers: impact.injectContext({}) }).
Keep native credentials and other request options under application control. Plain injection contributes correlation. It does not transfer completion ownership or install an HTTP patcher.
Add deployment and application context
context and span add information without being required for automatic provider capture. Set stable deployment
defaults with init({ context: { environment, versionId, componentId, buildId, deploymentId } }) when those values are known.
environment reports the deployment environment name (deployment.environment.name), not an authenticated
Environment UUID. versionId reports the deployed application version/ref (impact.product.version.id), such as the
actual release reference or Git commit used by the build. Its spelling does not make the value a canonical Builder
Version UUID. Supply real configured values or leave them unknown. Do not use a library version or model name to
stand in for a deployment.
componentId, agentId and agentVersionId are reported application keys. buildId and deploymentId are reported
external build/deployment references, for example actual CI or hosting IDs. These fields do not establish a Builder
Part, Version or Deploy relationship. Native provider model, agent, and session IDs describe separate provider facts.
Route credentials establish Workspace and Product tenancy. Context values are correlation claims. Keep reported environment/version/component/build/deployment metadata,
Session, Interaction, purpose, Product User and
domainRun: { kind, id } distinct. A Simulation run ID and a technical invocation ID remain distinct from the Interaction and Session IDs.
Optional typed context fields channel, locale, plan, userType and journeyStep emit
impact.correlation.channel, .locale, .plan, .user_type and .journey_step, respectively. They accept
non-empty, well-formed strings of at most 1,024 UTF-8 bytes without NUL. They do not prescribe a vocabulary or infer
values. Stable defaults may be supplied in init({ context: ... }). Within one context, a typed field wins over its
exact canonical custom key. An inner scope wins over outer/default values, including an inner custom value.
Existing custom-only values keep their validation and omission behavior. agentVersionId continues to emit
impact.agent.version.id separately from the reported deployed versionId.
Supply a known terminal Session fact on the actual terminal operation, before its span or automatic owner starts:
sessionEnding emits the raw impact.session.ending attribute and requires sessionId in the same submitted
context. It is rejected in init defaults. Nested work inherits it for the same Session. Changing the Session clears
the inherited ending unless that scope supplies a new pair, and leaving the scope restores the outer pair.
Use application-owned native trace parentage to keep the terminal operation under its intended Session. Changing
context leaves existing trace parentage intact. This field records the supplied fact, does not close
a Session or alter inferred Ending classification, and offers no post-hoc ending API. Verify the terminal span’s raw
attribute through authenticated Trace readback under that exact Session. These typed fields and the supplied ending
are not added to propagation headers or baggage.
runtime.status().runtimeId identifies this initialized SDK runtime. Impact-created evidence and Impact-routed copies carry
the same impact.runtime.id plus impact.sdk.version. There is no caller-settable context.runtimeId. Customer
records remain unchanged. Source references use code.file.path, code.function.name, code.line.number,
impact.source.basis.id and impact.source.observed.at. custom values use impact.correlation.*.
Execution provenance uses impact.execution.origin, impact.execution.input.reference and distinct
impact.<evaluation|dataset|case|experiment|replay>.id attributes, matching Python. These supplied source/business
facts do not grant authority or trigger source inspection.