actor-ts 0.9.0

package/dist/testkit/internal/parallel-multi-node-bootstrap.js

@@ -0,0 +1,157 @@
+/**
+ * Generic worker-side bootstrap for `ParallelMultiNodeSpec`.  Each
+ * worker spawned by the harness runs this script; the harness drives
+ * the worker via a control-channel piggybacked on the same
+ * `postMessage` socket that `WorkerNode.join()` uses for its
+ * lifecycle handshake.
+ *
+ * Test-local actor logic is loaded via a **scenario module** —
+ * `initData.scenarioModule` is a URL passed by the harness; the
+ * bootstrap dynamically imports it and calls its `setup(ctx)` hook
+ * after the cluster joins, then dispatches `run-command` requests
+ * through the module's `commands` map.  The scenario module owns
+ * everything actor-shaped (entity classes, sharding setup, …) —
+ * the harness only ever sees JSON-serialisable command/response
+ * pairs.
+ *
+ * **Why a separate file**: the worker process can't see the test
+ * file's closures (workers run in their own JS context with their
+ * own module graph).  A standalone bootstrap that loads scenario
+ * modules by URL is the cleanest way to thread test-specific code
+ * into the worker without leaking it through `postMessage`.
+ */
+import { ActorSystem } from '../../ActorSystem.js';
+import { Cluster } from '../../cluster/Cluster.js';
+import { LogLevel, NoopLogger } from '../../Logger.js';
+import { WorkerNode } from '../../worker/WorkerNode.js';
+/* ------------------------------- main loop --------------------------- */
+async function main() {
+    const ctx = await WorkerNode.join();
+    const init = ctx.initData;
+    const system = ActorSystem.create(ctx.systemName, {
+        logger: new NoopLogger(),
+        logLevel: init.logLevel ?? LogLevel.Off,
+    });
+    const cluster = await Cluster.join(system, {
+        host: ctx.self.host,
+        port: ctx.self.port,
+        seeds: [...init.seeds],
+        transport: ctx.transport,
+        failureDetector: init.failureDetector,
+        gossipIntervalMs: init.gossipIntervalMs,
+    });
+    const scenarioCtx = {
+        role: init.role,
+        system,
+        cluster,
+        initData: init.scenarioInitData,
+        state: {},
+    };
+    // Dynamically import the scenario module (if any) and run its
+    // setup hook.  The module's URL was resolved on the main thread
+    // — we just import the string verbatim.
+    let scenario = {};
+    if (init.scenarioModule) {
+        try {
+            scenario = await import(init.scenarioModule);
+        }
+        catch (err) {
+            // Without the scenario, setup-dependent commands will fail —
+            // surface the import error early rather than at first
+            // invocation.
+            // eslint-disable-next-line no-console
+            console.error('parallel-multi-node-bootstrap: scenario import failed', err);
+        }
+    }
+    if (scenario.setup) {
+        try {
+            await scenario.setup(scenarioCtx);
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.error('parallel-multi-node-bootstrap: scenario.setup() threw', err);
+        }
+    }
+    // Wire the control channel — listen on the worker's main port for
+    // test commands.  Replies go on the same port via postMessage.
+    const g = globalThis;
+    const selfScope = g.self ?? g;
+    const post = selfScope.postMessage ?? g.postMessage;
+    const reply = (msg) => {
+        post?.call(selfScope, msg);
+    };
+    const onControl = async (data) => {
+        const msg = data;
+        if (!msg || typeof msg.kind !== 'string' || !msg.kind.startsWith('mns-test.'))
+            return;
+        switch (msg.kind) {
+            case 'mns-test.query-members': {
+                const m = msg.reqId;
+                const snap = cluster.getMembers().map((mem) => ({
+                    address: mem.address.toString(),
+                    status: mem.status,
+                    roles: Array.from(mem.roles),
+                }));
+                reply({ kind: 'mns-test.query-members-response', reqId: m, members: snap });
+                return;
+            }
+            case 'mns-test.query-leader': {
+                const reqId = msg.reqId;
+                const ldr = cluster.leader().toNullable();
+                reply({
+                    kind: 'mns-test.query-leader-response',
+                    reqId,
+                    leader: ldr ? ldr.address.toString() : null,
+                });
+                return;
+            }
+            case 'mns-test.leave': {
+                const reqId = msg.reqId;
+                try {
+                    await cluster.leave();
+                    reply({ kind: 'mns-test.leave-response', reqId });
+                }
+                catch (err) {
+                    reply({
+                        kind: 'mns-test.leave-response', reqId,
+                        error: err.message,
+                    });
+                }
+                return;
+            }
+            case 'mns-test.run-command': {
+                const reqId = msg.reqId;
+                const command = msg.command;
+                const args = msg.args;
+                const handler = scenario.commands?.[command];
+                if (!handler) {
+                    reply({
+                        kind: 'mns-test.run-command-response', reqId, result: undefined,
+                        error: `no handler for command '${command}'`,
+                    });
+                    return;
+                }
+                try {
+                    const result = await handler(args, scenarioCtx);
+                    reply({ kind: 'mns-test.run-command-response', reqId, result });
+                }
+                catch (err) {
+                    reply({
+                        kind: 'mns-test.run-command-response', reqId, result: undefined,
+                        error: err.message,
+                    });
+                }
+                return;
+            }
+        }
+    };
+    if (typeof selfScope.addEventListener === 'function') {
+        selfScope.addEventListener('message', (e) => { void onControl(e.data); });
+    }
+    ctx.ready();
+}
+void main().catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error('parallel-multi-node-bootstrap: fatal', err);
+});
+//# sourceMappingURL=parallel-multi-node-bootstrap.js.map

package/dist/testkit/internal/parallel-multi-node-bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel-multi-node-bootstrap.js","sourceRoot":"","sources":["../../../src/testkit/internal/parallel-multi-node-bootstrap.ts"],"names":[],"mappings":"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"}

package/dist/tracing/NoopTracer.d.ts

@@ -0,0 +1,11 @@
+import type { Span, SpanContext, SpanOptions, TraceCarrier, Tracer } from './Tracer.js';
+export declare class NoopTracer implements Tracer {
+    startSpan(_name: string, _opts?: SpanOptions): Span;
+    withActiveSpan<T>(_span: Span, fn: () => T): T;
+    activeSpan(): Span | null;
+    injectContext(): TraceCarrier | null;
+    extractContext(_carrier: TraceCarrier | null | undefined): SpanContext | null;
+}
+/** Module-shared singleton — every `NoopTracer` is identical anyway. */
+export declare const NOOP_TRACER: Tracer;
+//# sourceMappingURL=NoopTracer.d.ts.map

package/dist/tracing/NoopTracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NoopTracer.d.ts","sourceRoot":"","sources":["../../src/tracing/NoopTracer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,EACrD,MAAM,aAAa,CAAC;AAwBrB,qBAAa,UAAW,YAAW,MAAM;IACvC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI;IACnD,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAC9C,UAAU,IAAI,IAAI,GAAG,IAAI;IACzB,aAAa,IAAI,YAAY,GAAG,IAAI;IACpC,cAAc,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,GAAG,IAAI;CAC9E;AAED,wEAAwE;AACxE,eAAO,MAAM,WAAW,EAAE,MAAyB,CAAC"}

package/dist/tracing/NoopTracer.js

@@ -0,0 +1,29 @@
+/**
+ * The default tracer — every operation is a no-op so framework
+ * instrumentation pays nothing when tracing is not enabled.  All
+ * `Span`s share the same singleton; `injectContext` returns null;
+ * `withActiveSpan` invokes `fn` directly.
+ */
+const ZERO_CTX = Object.freeze({
+    traceId: '0'.repeat(32),
+    spanId: '0'.repeat(16),
+    traceFlags: 0,
+});
+const NOOP_SPAN = Object.freeze({
+    context: () => ZERO_CTX,
+    setAttribute: () => NOOP_SPAN,
+    setStatus: () => NOOP_SPAN,
+    recordException: () => NOOP_SPAN,
+    end: () => { },
+    ended: true,
+});
+export class NoopTracer {
+    startSpan(_name, _opts) { return NOOP_SPAN; }
+    withActiveSpan(_span, fn) { return fn(); }
+    activeSpan() { return null; }
+    injectContext() { return null; }
+    extractContext(_carrier) { return null; }
+}
+/** Module-shared singleton — every `NoopTracer` is identical anyway. */
+export const NOOP_TRACER = new NoopTracer();
+//# sourceMappingURL=NoopTracer.js.map

package/dist/tracing/NoopTracer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NoopTracer.js","sourceRoot":"","sources":["../../src/tracing/NoopTracer.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH,MAAM,QAAQ,GAAgB,MAAM,CAAC,MAAM,CAAC;IAC1C,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;IACvB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;IACtB,UAAU,EAAE,CAAC;CACd,CAAC,CAAC;AAEH,MAAM,SAAS,GAAS,MAAM,CAAC,MAAM,CAAC;IACpC,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ;IACvB,YAAY,EAAE,GAAG,EAAE,CAAC,SAAS;IAC7B,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS;IAC1B,eAAe,EAAE,GAAG,EAAE,CAAC,SAAS;IAChC,GAAG,EAAE,GAAG,EAAE,GAAe,CAAC;IAC1B,KAAK,EAAE,IAAI;CACZ,CAAoB,CAAC;AAEtB,MAAM,OAAO,UAAU;IACrB,SAAS,CAAC,KAAa,EAAE,KAAmB,IAAU,OAAO,SAAS,CAAC,CAAC,CAAC;IACzE,cAAc,CAAI,KAAW,EAAE,EAAW,IAAO,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IAC/D,UAAU,KAAkB,OAAO,IAAI,CAAC,CAAC,CAAC;IAC1C,aAAa,KAA0B,OAAO,IAAI,CAAC,CAAC,CAAC;IACrD,cAAc,CAAC,QAAyC,IAAwB,OAAO,IAAI,CAAC,CAAC,CAAC;CAC/F;AAED,wEAAwE;AACxE,MAAM,CAAC,MAAM,WAAW,GAAW,IAAI,UAAU,EAAE,CAAC"}

package/dist/tracing/OtelAdapter.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Bridge from the framework's {@link Tracer} to the OpenTelemetry
+ * API (#63).
+ *
+ * The framework instruments actor message handling, cross-wire
+ * envelopes, and cluster transport against its own minimal
+ * {@link Tracer} interface — no SDK dependency.  Production users
+ * who want their spans in Jaeger / Tempo / Honeycomb / Datadog need
+ * an adapter to `@opentelemetry/api`.  Without one each user writes
+ * the same plumbing; this file ships it once.
+ *
+ * The adapter delegates everything: `startSpan` to the real OTel
+ * `Tracer.startSpan`, `withActiveSpan` to `context.with` over an
+ * OTel context with the wrapped span attached, `injectContext`/
+ * `extractContext` to OTel's W3C-compatible `propagation.inject` /
+ * `.extract`.  Net effect: every actor-ts span shows up in the
+ * user's OTel SDK, with `traceparent` flowing across the wire to
+ * downstream services that speak W3C Trace Context.
+ *
+ * **Optional peer dep**: `@opentelemetry/api` is not a hard dep of
+ * the framework.  Users who want this adapter pass their existing
+ * import (`import * as otel from '@opentelemetry/api'`) into
+ * `otelTracer({ api: otel })` — same passthrough pattern as the
+ * prom-client adapter (#64).  Structural typing on the OTel surface
+ * means we never `import '@opentelemetry/api'` ourselves.
+ */
+import type { AttributeValue, Tracer } from './Tracer.js';
+export interface OtelSpanContextLike {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly traceFlags: number;
+    readonly traceState?: string;
+    readonly isRemote?: boolean;
+}
+export interface OtelSpanLike {
+    spanContext(): OtelSpanContextLike;
+    setAttribute(key: string, value: AttributeValue): OtelSpanLike;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): OtelSpanLike;
+    recordException(err: Error | string, time?: number): void;
+    end(time?: number): void;
+    isRecording(): boolean;
+}
+export interface OtelContextLike {
+    readonly __opaque?: never;
+}
+export interface OtelTracerLike {
+    startSpan(name: string, options?: {
+        kind?: number;
+        attributes?: Record<string, AttributeValue>;
+        startTime?: number;
+        root?: boolean;
+    }, ctx?: OtelContextLike): OtelSpanLike;
+}
+export interface OtelTraceApi {
+    getTracer(name: string, version?: string): OtelTracerLike;
+    setSpan(ctx: OtelContextLike, span: OtelSpanLike): OtelContextLike;
+    getSpan(ctx: OtelContextLike): OtelSpanLike | undefined;
+    getActiveSpan(): OtelSpanLike | undefined;
+    getSpanContext(ctx: OtelContextLike): OtelSpanContextLike | undefined;
+    setSpanContext(ctx: OtelContextLike, sc: OtelSpanContextLike): OtelContextLike;
+    wrapSpanContext(sc: OtelSpanContextLike): OtelSpanLike;
+}
+export interface OtelContextApi {
+    active(): OtelContextLike;
+    with<F extends (...args: never[]) => unknown>(ctx: OtelContextLike, fn: F): ReturnType<F>;
+    /** OTel exports `ROOT_CONTEXT` as a top-level constant; some shims also rehang it here. */
+    readonly ROOT_CONTEXT?: OtelContextLike;
+}
+export interface OtelPropagationApi {
+    inject(ctx: OtelContextLike, carrier: Record<string, string>): void;
+    extract(ctx: OtelContextLike, carrier: Record<string, string | undefined>): OtelContextLike;
+}
+export interface OtelApiLike {
+    readonly trace: OtelTraceApi;
+    readonly context: OtelContextApi;
+    readonly propagation: OtelPropagationApi;
+    readonly SpanStatusCode: {
+        readonly UNSET: number;
+        readonly OK: number;
+        readonly ERROR: number;
+    };
+    readonly SpanKind: {
+        readonly INTERNAL: number;
+        readonly SERVER: number;
+        readonly CLIENT: number;
+        readonly PRODUCER: number;
+        readonly CONSUMER: number;
+    };
+    /** Optional — re-export of the root context constant if the SDK exposes it on the namespace. */
+    readonly ROOT_CONTEXT?: OtelContextLike;
+}
+export interface OtelAdapterOptions {
+    /** The `@opentelemetry/api` namespace (`import * as otel from '@opentelemetry/api'`). */
+    readonly api: OtelApiLike;
+    /** Optional pre-built tracer; defaults to `api.trace.getTracer(tracerName, tracerVersion)`. */
+    readonly tracer?: OtelTracerLike;
+    /** Tracer name passed to `getTracer`.  Default: `'actor-ts'`. */
+    readonly tracerName?: string;
+    /** Tracer version passed to `getTracer`. */
+    readonly tracerVersion?: string;
+}
+export declare function otelTracer(opts: OtelAdapterOptions): Tracer;
+//# sourceMappingURL=OtelAdapter.d.ts.map

package/dist/tracing/OtelAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OtelAdapter.d.ts","sourceRoot":"","sources":["../../src/tracing/OtelAdapter.ts"],"names":[],"mappings":"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"}

package/dist/tracing/OtelAdapter.js

@@ -0,0 +1,164 @@
+/**
+ * Bridge from the framework's {@link Tracer} to the OpenTelemetry
+ * API (#63).
+ *
+ * The framework instruments actor message handling, cross-wire
+ * envelopes, and cluster transport against its own minimal
+ * {@link Tracer} interface — no SDK dependency.  Production users
+ * who want their spans in Jaeger / Tempo / Honeycomb / Datadog need
+ * an adapter to `@opentelemetry/api`.  Without one each user writes
+ * the same plumbing; this file ships it once.
+ *
+ * The adapter delegates everything: `startSpan` to the real OTel
+ * `Tracer.startSpan`, `withActiveSpan` to `context.with` over an
+ * OTel context with the wrapped span attached, `injectContext`/
+ * `extractContext` to OTel's W3C-compatible `propagation.inject` /
+ * `.extract`.  Net effect: every actor-ts span shows up in the
+ * user's OTel SDK, with `traceparent` flowing across the wire to
+ * downstream services that speak W3C Trace Context.
+ *
+ * **Optional peer dep**: `@opentelemetry/api` is not a hard dep of
+ * the framework.  Users who want this adapter pass their existing
+ * import (`import * as otel from '@opentelemetry/api'`) into
+ * `otelTracer({ api: otel })` — same passthrough pattern as the
+ * prom-client adapter (#64).  Structural typing on the OTel surface
+ * means we never `import '@opentelemetry/api'` ourselves.
+ */
+/* ------------------------------- adapter ------------------------------- */
+export function otelTracer(opts) {
+    const { api } = opts;
+    const otelTracerInstance = opts.tracer ?? api.trace.getTracer(opts.tracerName ?? 'actor-ts', opts.tracerVersion);
+    const SPAN_KIND_MAP = {
+        internal: api.SpanKind.INTERNAL,
+        server: api.SpanKind.SERVER,
+        client: api.SpanKind.CLIENT,
+        producer: api.SpanKind.PRODUCER,
+        consumer: api.SpanKind.CONSUMER,
+    };
+    /**
+     * Resolve `ROOT_CONTEXT` whether the SDK exports it at the top level
+     * of the namespace or hangs it off `context`.  Falls back to `active()`
+     * when neither is exposed — at startSpan time before any scope is
+     * active that's equivalent.
+     */
+    function rootContext() {
+        return api.ROOT_CONTEXT ?? api.context.ROOT_CONTEXT ?? api.context.active();
+    }
+    /** Translate an OTel `SpanContext` to our shape (drop `isRemote`, keep `traceState`). */
+    function pickSpanContext(sc) {
+        return {
+            traceId: sc.traceId,
+            spanId: sc.spanId,
+            traceFlags: sc.traceFlags,
+            ...(sc.traceState ? { traceState: sc.traceState } : {}),
+        };
+    }
+    /** Wrap an OTel span in our `Span` interface.  Cheap; safe to call repeatedly. */
+    function wrapSpan(otelSpan) {
+        let ended = false;
+        const wrapper = {
+            context() { return pickSpanContext(otelSpan.spanContext()); },
+            setAttribute(key, value) {
+                if (!ended)
+                    otelSpan.setAttribute(key, value);
+                return wrapper;
+            },
+            setStatus(status, message) {
+                if (!ended) {
+                    otelSpan.setStatus({
+                        code: status === 'ok' ? api.SpanStatusCode.OK : api.SpanStatusCode.ERROR,
+                        ...(message !== undefined ? { message } : {}),
+                    });
+                }
+                return wrapper;
+            },
+            recordException(err) {
+                if (!ended)
+                    otelSpan.recordException(err);
+                return wrapper;
+            },
+            end(endTimeMs) {
+                if (ended)
+                    return;
+                ended = true;
+                otelSpan.end(endTimeMs);
+            },
+            get ended() { return ended; },
+        };
+        otelOf.set(wrapper, otelSpan);
+        return wrapper;
+    }
+    // Wrap-to-OTel back-reference.  `withActiveSpan` reads from this map
+    // to put the right OTel span on the OTel context; lookups fall back
+    // gracefully (just-run-fn) when the user passes a span we didn't create.
+    const otelOf = new WeakMap();
+    return {
+        startSpan(name, opts2) {
+            let ctx = api.context.active();
+            if (opts2?.parent === null) {
+                // Explicit root.  Pass `root: true` to OTel so its sampling
+                // decision treats this as a new trace; switch the context to
+                // ROOT just to make sure no ambient parent leaks in.
+                ctx = rootContext();
+            }
+            else if (opts2?.parent) {
+                // Explicit parent SpanContext: install it on a fresh context.
+                ctx = api.trace.setSpanContext(rootContext(), {
+                    traceId: opts2.parent.traceId,
+                    spanId: opts2.parent.spanId,
+                    traceFlags: opts2.parent.traceFlags,
+                    ...(opts2.parent.traceState ? { traceState: opts2.parent.traceState } : {}),
+                    isRemote: true,
+                });
+            }
+            const otelSpan = otelTracerInstance.startSpan(name, {
+                ...(opts2?.kind ? { kind: SPAN_KIND_MAP[opts2.kind] } : {}),
+                ...(opts2?.attributes ? { attributes: { ...opts2.attributes } } : {}),
+                ...(opts2?.startTimeMs !== undefined ? { startTime: opts2.startTimeMs } : {}),
+                ...(opts2?.parent === null ? { root: true } : {}),
+            }, ctx);
+            return wrapSpan(otelSpan);
+        },
+        withActiveSpan(span, fn) {
+            const otelSpan = otelOf.get(span);
+            if (!otelSpan) {
+                // Not one of ours — degrade to running `fn` without OTel
+                // context propagation.  Better than throwing; covers the
+                // (unusual) case where the caller mixed adapter outputs.
+                return fn();
+            }
+            const ctx = api.trace.setSpan(api.context.active(), otelSpan);
+            return api.context.with(ctx, fn);
+        },
+        activeSpan() {
+            const otelSpan = api.trace.getActiveSpan();
+            if (!otelSpan)
+                return null;
+            return wrapSpan(otelSpan);
+        },
+        injectContext() {
+            const carrier = {};
+            api.propagation.inject(api.context.active(), carrier);
+            const traceparent = carrier['traceparent'];
+            if (!traceparent)
+                return null;
+            return {
+                traceparent,
+                ...(carrier['tracestate'] ? { tracestate: carrier['tracestate'] } : {}),
+            };
+        },
+        extractContext(carrier) {
+            if (!carrier)
+                return null;
+            const newCtx = api.propagation.extract(rootContext(), {
+                traceparent: carrier.traceparent,
+                ...(carrier.tracestate ? { tracestate: carrier.tracestate } : {}),
+            });
+            const sc = api.trace.getSpanContext(newCtx);
+            if (!sc)
+                return null;
+            return pickSpanContext(sc);
+        },
+    };
+}
+//# sourceMappingURL=OtelAdapter.js.map

package/dist/tracing/OtelAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OtelAdapter.js","sourceRoot":"","sources":["../../src/tracing/OtelAdapter.ts"],"names":[],"mappings":"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"}

package/dist/tracing/RecordingTracer.d.ts

@@ -0,0 +1,54 @@
+import type { AttributeValue, Span, SpanContext, SpanKind, SpanOptions, SpanStatus, TraceCarrier, Tracer } from './Tracer.js';
+/**
+ * Reference {@link Tracer} implementation.  Generates real ids,
+ * tracks span hierarchy via parent context, propagates the active
+ * span through `AsyncLocalStorage`, and records ended spans into an
+ * in-memory buffer for assertions.
+ *
+ * Production usage: the recorder list is your sink.  For full
+ * OpenTelemetry export, pass each completed span through to the OTel
+ * SDK in `onSpanEnd` — or write a thin adapter that delegates the
+ * `Tracer` calls to `@opentelemetry/api.trace.getTracer(...)`.
+ *
+ * This impl is **not** an OpenTelemetry SDK — it doesn't sample,
+ * batch, or export.  Its role is the in-process backbone for
+ * actor-ts's instrumentation; the SDK boundary lives in the
+ * adapter layer.
+ */
+export interface RecordedSpan {
+    readonly name: string;
+    readonly kind: SpanKind;
+    readonly context: SpanContext;
+    readonly parent: SpanContext | null;
+    readonly startTimeMs: number;
+    readonly endTimeMs: number;
+    readonly attributes: Readonly<Record<string, AttributeValue>>;
+    readonly status: SpanStatus;
+    readonly statusMessage?: string;
+    readonly exceptions: ReadonlyArray<Error>;
+}
+export interface RecordingTracerOptions {
+    /** Hook invoked when a span ends — wire to your exporter here. */
+    readonly onSpanEnd?: (span: RecordedSpan) => void;
+    /** Sampling decision per span.  Default `() => true` (sample all). */
+    readonly sampler?: (name: string, opts: SpanOptions | undefined) => boolean;
+}
+export declare class RecordingTracer implements Tracer {
+    private readonly storage;
+    private readonly _recorded;
+    private readonly onSpanEnd?;
+    private readonly sampler;
+    constructor(opts?: RecordingTracerOptions);
+    startSpan(name: string, opts?: SpanOptions): Span;
+    withActiveSpan<T>(span: Span, fn: () => T): T;
+    activeSpan(): Span | null;
+    injectContext(): TraceCarrier | null;
+    extractContext(carrier: TraceCarrier | null | undefined): SpanContext | null;
+    /** Snapshot of every ended span — primarily for tests. */
+    recorded(): ReadonlyArray<RecordedSpan>;
+    /** Clear the recording buffer.  Spans currently in flight are unaffected. */
+    reset(): void;
+    /** @internal — invoked from `Span.end()`. */
+    _recordEnd(span: RecordedSpan): void;
+}
+//# sourceMappingURL=RecordingTracer.d.ts.map

package/dist/tracing/RecordingTracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordingTracer.d.ts","sourceRoot":"","sources":["../../src/tracing/RecordingTracer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,cAAc,EACd,IAAI,EACJ,WAAW,EACX,QAAQ,EACR,WAAW,EACX,UAAU,EACV,YAAY,EACZ,MAAM,EACP,MAAM,aAAa,CAAC;AAQrB;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IAC9D,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,sBAAsB;IACrC,kEAAkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC;IAClD,sEAAsE;IACtE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,KAAK,OAAO,CAAC;CAC7E;AAoED,qBAAa,eAAgB,YAAW,MAAM;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAA+B;IAC1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2D;gBAEvE,IAAI,GAAE,sBAA2B;IAK7C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,IAAI;IA8BjD,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAI7C,UAAU,IAAI,IAAI,GAAG,IAAI;IAIzB,aAAa,IAAI,YAAY,GAAG,IAAI;IAMpC,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,GAAG,IAAI;IAO5E,0DAA0D;IAC1D,QAAQ,IAAI,aAAa,CAAC,YAAY,CAAC;IAEvC,6EAA6E;IAC7E,KAAK,IAAI,IAAI;IAEb,6CAA6C;IAC7C,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;CAIrC"}