actor-ts 0.9.0

package/dist/tracing/RecordingTracer.js

@@ -0,0 +1,129 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { decodeTraceparent, encodeTraceparent, newSpanId, newTraceId, } from './Tracer.js';
+class RecordingSpan {
+    name;
+    kind;
+    _context;
+    _parent;
+    _startTimeMs;
+    tracer;
+    _ended = false;
+    _status = 'unset';
+    _statusMessage;
+    _attributes = {};
+    _exceptions = [];
+    _endTimeMs = 0;
+    constructor(name, kind, _context, _parent, _startTimeMs, initialAttributes, tracer) {
+        this.name = name;
+        this.kind = kind;
+        this._context = _context;
+        this._parent = _parent;
+        this._startTimeMs = _startTimeMs;
+        this.tracer = tracer;
+        Object.assign(this._attributes, initialAttributes);
+    }
+    context() { return this._context; }
+    setAttribute(key, value) {
+        if (!this._ended)
+            this._attributes[key] = value;
+        return this;
+    }
+    setStatus(status, message) {
+        if (!this._ended) {
+            this._status = status;
+            this._statusMessage = message;
+        }
+        return this;
+    }
+    recordException(err) {
+        if (!this._ended)
+            this._exceptions.push(err);
+        return this;
+    }
+    end(endTimeMs) {
+        if (this._ended)
+            return;
+        this._ended = true;
+        this._endTimeMs = endTimeMs ?? Date.now();
+        this.tracer._recordEnd(this.snapshot());
+    }
+    get ended() { return this._ended; }
+    /** @internal — used by the tracer when emitting the recording. */
+    snapshot() {
+        return {
+            name: this.name,
+            kind: this.kind,
+            context: this._context,
+            parent: this._parent,
+            startTimeMs: this._startTimeMs,
+            endTimeMs: this._endTimeMs,
+            attributes: { ...this._attributes },
+            status: this._status,
+            ...(this._statusMessage !== undefined ? { statusMessage: this._statusMessage } : {}),
+            exceptions: [...this._exceptions],
+        };
+    }
+}
+export class RecordingTracer {
+    storage = new AsyncLocalStorage();
+    _recorded = [];
+    onSpanEnd;
+    sampler;
+    constructor(opts = {}) {
+        this.onSpanEnd = opts.onSpanEnd;
+        this.sampler = opts.sampler ?? (() => true);
+    }
+    startSpan(name, opts) {
+        const sampled = this.sampler(name, opts);
+        // Resolve parent: explicit `null` = root, undefined = active span,
+        // a SpanContext = explicit parent.
+        let parentCtx;
+        if (opts?.parent === null) {
+            parentCtx = null;
+        }
+        else if (opts?.parent !== undefined) {
+            parentCtx = opts.parent;
+        }
+        else {
+            parentCtx = this.activeSpan()?.context() ?? null;
+        }
+        const traceId = parentCtx?.traceId ?? newTraceId();
+        const spanId = newSpanId();
+        const ctx = {
+            traceId, spanId,
+            traceFlags: sampled ? 1 : 0,
+            ...(parentCtx?.traceState ? { traceState: parentCtx.traceState } : {}),
+        };
+        return new RecordingSpan(name, opts?.kind ?? 'internal', ctx, parentCtx, opts?.startTimeMs ?? Date.now(), opts?.attributes ?? {}, this);
+    }
+    withActiveSpan(span, fn) {
+        return this.storage.run(span, fn);
+    }
+    activeSpan() {
+        return this.storage.getStore() ?? null;
+    }
+    injectContext() {
+        const span = this.activeSpan();
+        if (!span)
+            return null;
+        return { traceparent: encodeTraceparent(span.context()) };
+    }
+    extractContext(carrier) {
+        if (!carrier)
+            return null;
+        const ctx = decodeTraceparent(carrier.traceparent);
+        if (!ctx)
+            return null;
+        return carrier.tracestate ? { ...ctx, traceState: carrier.tracestate } : ctx;
+    }
+    /** Snapshot of every ended span — primarily for tests. */
+    recorded() { return [...this._recorded]; }
+    /** Clear the recording buffer.  Spans currently in flight are unaffected. */
+    reset() { this._recorded.length = 0; }
+    /** @internal — invoked from `Span.end()`. */
+    _recordEnd(span) {
+        this._recorded.push(span);
+        this.onSpanEnd?.(span);
+    }
+}
+//# sourceMappingURL=RecordingTracer.js.map

package/dist/tracing/RecordingTracer.js.map

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

package/dist/tracing/Tracer.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Minimal distributed-tracing API (#10).  The framework instruments
+ * actor `onReceive`, cross-wire envelopes, and cluster transport
+ * against this interface — users plug in either the built-in
+ * {@link RecordingTracer} (handy for tests) or an adapter around
+ * `@opentelemetry/api`'s tracer for full OTel export.
+ *
+ * Goals:
+ *   - **Zero overhead when disabled.**  The default `NoopTracer`
+ *     short-circuits every operation; framework hot paths
+ *     never allocate spans or look up async-storage if tracing
+ *     hasn't been enabled.
+ *   - **No SDK dependency.**  `actor-ts` doesn't pull in
+ *     `@opentelemetry/sdk-*`; users bring their own.
+ *   - **W3C-compatible cross-wire.**  Span contexts serialise to
+ *     the W3C `traceparent` / `tracestate` shape so downstream
+ *     OTel-aware services receive a coherent trace.
+ *   - **MDC integration.**  When tracing is active, each span's
+ *     `traceId` / `spanId` are merged into the {@link LogContext}
+ *     scope so log lines stamped during span execution include
+ *     them automatically.
+ */
+/** Allowed attribute primitive types — matches OTel's spec. */
+export type AttributeValue = string | number | boolean;
+export interface SpanContext {
+    /** 32 hex chars — the trace identifier shared across hops. */
+    readonly traceId: string;
+    /** 16 hex chars — the per-span identifier. */
+    readonly spanId: string;
+    /** Bit 0 = sampled.  We support sampled / not-sampled only. */
+    readonly traceFlags: number;
+    /** Optional W3C tracestate — opaque vendor-specific. */
+    readonly traceState?: string;
+}
+export type SpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer';
+export type SpanStatus = 'unset' | 'ok' | 'error';
+export interface SpanOptions {
+    /**
+     * Parent span context.  `undefined` means "use the active span".
+     * `null` explicitly creates a root span.
+     */
+    readonly parent?: SpanContext | null;
+    readonly attributes?: Readonly<Record<string, AttributeValue>>;
+    readonly kind?: SpanKind;
+    /** Override the span start time — defaults to `Date.now()`. */
+    readonly startTimeMs?: number;
+}
+export interface Span {
+    /** The span's own context — what children would inherit. */
+    context(): SpanContext;
+    setAttribute(key: string, value: AttributeValue): this;
+    setStatus(status: 'ok' | 'error', message?: string): this;
+    recordException(err: Error): this;
+    /** End the span.  Idempotent — second call is a no-op. */
+    end(endTimeMs?: number): void;
+    /** True after `end()` has been called. */
+    readonly ended: boolean;
+}
+export interface Tracer {
+    startSpan(name: string, opts?: SpanOptions): Span;
+    /** Run `fn` with `span` as the active span (read by `activeSpan()`). */
+    withActiveSpan<T>(span: Span, fn: () => T): T;
+    /** Active span on this async stack, or `null` outside any active scope. */
+    activeSpan(): Span | null;
+    /**
+     * Serialise the active span's context to a W3C-style carrier — used
+     * by the cluster transport to thread context across the wire.
+     * Returns `null` when no span is active or the tracer is a noop.
+     */
+    injectContext(): TraceCarrier | null;
+    /** Inverse of `injectContext` — recover a `SpanContext` from a carrier. */
+    extractContext(carrier: TraceCarrier | null | undefined): SpanContext | null;
+}
+/**
+ * Wire-shape for cross-process span propagation.  Mirrors the W3C
+ * Trace Context working group's `traceparent` / `tracestate` headers
+ * — see {@link encodeTraceparent} / {@link decodeTraceparent}.
+ */
+export interface TraceCarrier {
+    readonly traceparent: string;
+    readonly tracestate?: string;
+}
+/**
+ * Encode a `SpanContext` as a W3C `traceparent` header value:
+ *
+ *     00-<traceId>-<spanId>-<flags>
+ *
+ * Version `00` is the only one currently defined.
+ */
+export declare function encodeTraceparent(ctx: SpanContext): string;
+/**
+ * Decode a `traceparent` value back into a `SpanContext`.  Returns
+ * `null` for any malformed input — callers treat that as "no parent".
+ */
+export declare function decodeTraceparent(s: string): SpanContext | null;
+/** Generate a fresh trace id — 16 random bytes hex-encoded. */
+export declare function newTraceId(): string;
+/** Generate a fresh span id — 8 random bytes hex-encoded. */
+export declare function newSpanId(): string;
+//# sourceMappingURL=Tracer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Tracer.d.ts","sourceRoot":"","sources":["../../src/tracing/Tracer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEvD,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;AAClF,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC;AAElD,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,IAAI;IACnB,4DAA4D;IAC5D,OAAO,IAAI,WAAW,CAAC;IACvB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IACvD,SAAS,CAAC,MAAM,EAAE,IAAI,GAAG,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1D,eAAe,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,CAAC;IAClC,0DAA0D;IAC1D,GAAG,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,MAAM;IACrB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAElD,wEAAwE;IACxE,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAE9C,2EAA2E;IAC3E,UAAU,IAAI,IAAI,GAAG,IAAI,CAAC;IAE1B;;;;OAIG;IACH,aAAa,IAAI,YAAY,GAAG,IAAI,CAAC;IAErC,2EAA2E;IAC3E,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,GAAG,IAAI,CAAC;CAC9E;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAID;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAG1D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAW/D;AAID,+DAA+D;AAC/D,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,6DAA6D;AAC7D,wBAAgB,SAAS,IAAI,MAAM,CAElC"}

package/dist/tracing/Tracer.js

@@ -0,0 +1,76 @@
+/**
+ * Minimal distributed-tracing API (#10).  The framework instruments
+ * actor `onReceive`, cross-wire envelopes, and cluster transport
+ * against this interface — users plug in either the built-in
+ * {@link RecordingTracer} (handy for tests) or an adapter around
+ * `@opentelemetry/api`'s tracer for full OTel export.
+ *
+ * Goals:
+ *   - **Zero overhead when disabled.**  The default `NoopTracer`
+ *     short-circuits every operation; framework hot paths
+ *     never allocate spans or look up async-storage if tracing
+ *     hasn't been enabled.
+ *   - **No SDK dependency.**  `actor-ts` doesn't pull in
+ *     `@opentelemetry/sdk-*`; users bring their own.
+ *   - **W3C-compatible cross-wire.**  Span contexts serialise to
+ *     the W3C `traceparent` / `tracestate` shape so downstream
+ *     OTel-aware services receive a coherent trace.
+ *   - **MDC integration.**  When tracing is active, each span's
+ *     `traceId` / `spanId` are merged into the {@link LogContext}
+ *     scope so log lines stamped during span execution include
+ *     them automatically.
+ */
+/* ----------------------- W3C traceparent codec ------------------------- */
+/**
+ * Encode a `SpanContext` as a W3C `traceparent` header value:
+ *
+ *     00-<traceId>-<spanId>-<flags>
+ *
+ * Version `00` is the only one currently defined.
+ */
+export function encodeTraceparent(ctx) {
+    const flags = (ctx.traceFlags & 0xff).toString(16).padStart(2, '0');
+    return `00-${ctx.traceId}-${ctx.spanId}-${flags}`;
+}
+/**
+ * Decode a `traceparent` value back into a `SpanContext`.  Returns
+ * `null` for any malformed input — callers treat that as "no parent".
+ */
+export function decodeTraceparent(s) {
+    if (typeof s !== 'string')
+        return null;
+    const parts = s.split('-');
+    if (parts.length !== 4)
+        return null;
+    const [version, traceId, spanId, flagsHex] = parts;
+    if (version !== '00')
+        return null;
+    if (!/^[0-9a-f]{32}$/.test(traceId))
+        return null;
+    if (!/^[0-9a-f]{16}$/.test(spanId))
+        return null;
+    if (!/^[0-9a-f]{2}$/.test(flagsHex))
+        return null;
+    if (traceId === '0'.repeat(32) || spanId === '0'.repeat(16))
+        return null;
+    return { traceId, spanId, traceFlags: parseInt(flagsHex, 16) };
+}
+/* ------------------------- Span context helpers ------------------------- */
+/** Generate a fresh trace id — 16 random bytes hex-encoded. */
+export function newTraceId() {
+    return randomHex(16);
+}
+/** Generate a fresh span id — 8 random bytes hex-encoded. */
+export function newSpanId() {
+    return randomHex(8);
+}
+function randomHex(byteLength) {
+    const buf = new Uint8Array(byteLength);
+    // crypto.getRandomValues is universally available on Bun, Node, Deno.
+    globalThis.crypto.getRandomValues(buf);
+    let out = '';
+    for (const b of buf)
+        out += b.toString(16).padStart(2, '0');
+    return out;
+}
+//# sourceMappingURL=Tracer.js.map

package/dist/tracing/Tracer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tracer.js","sourceRoot":"","sources":["../../src/tracing/Tracer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAyEH,6EAA6E;AAE7E;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAgB;IAChD,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACpE,OAAO,MAAM,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,MAAM,IAAI,KAAK,EAAE,CAAC;AACpD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,CAAS;IACzC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACvC,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,GAAG,KAAyC,CAAC;IACvF,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAChD,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,OAAO,KAAK,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IACzE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,EAAE,CAAC;AACjE,CAAC;AAED,8EAA8E;AAE9E,+DAA+D;AAC/D,MAAM,UAAU,UAAU;IACxB,OAAO,SAAS,CAAC,EAAE,CAAC,CAAC;AACvB,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,SAAS;IACvB,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC;AACtB,CAAC;AAED,SAAS,SAAS,CAAC,UAAkB;IACnC,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC;IACvC,sEAAsE;IACtE,UAAU,CAAC,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,GAAG;QAAE,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC5D,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/tracing/TracingExtension.d.ts

@@ -0,0 +1,32 @@
+import type { ActorSystem } from '../ActorSystem.js';
+import { type Extension, type ExtensionId } from '../Extension.js';
+import type { Tracer } from './Tracer.js';
+/**
+ * `system.extension(TracingExtensionId)` accessor.  Hands back the
+ * currently-installed {@link Tracer} (defaults to the noop), so
+ * framework instrumentation can call `tracerOf(system).activeSpan()`
+ * etc. without conditional checks.  Opt in by calling `enable(tracer)`
+ * with either a `RecordingTracer` (for tests) or an adapter around
+ * `@opentelemetry/api`'s tracer.
+ */
+export declare class TracingExtension implements Extension {
+    private readonly _system;
+    private tracer;
+    constructor(_system: ActorSystem);
+    /** Currently-installed tracer (noop until `enable(...)` is called). */
+    get(): Tracer;
+    /** Plug in a tracer.  Idempotent if you re-pass the same instance. */
+    enable(tracer: Tracer): Tracer;
+    /** True if a real (non-noop) tracer is installed. */
+    isEnabled(): boolean;
+    /** Reset back to the noop — primarily for tests. */
+    disable(): void;
+}
+export declare const TracingExtensionId: ExtensionId<TracingExtension>;
+/**
+ * Convenience accessor used by framework instrumentation.  Cheap on
+ * the no-tracer hot path because the extension chain returns a
+ * cached `TracingExtension` and `get()` returns the singleton noop.
+ */
+export declare function tracerOf(system: ActorSystem): Tracer;
+//# sourceMappingURL=TracingExtension.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TracingExtension.d.ts","sourceRoot":"","sources":["../../src/tracing/TracingExtension.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAe,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEhF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;GAOG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAGpC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,MAAM,CAAuB;gBAER,OAAO,EAAE,WAAW;IAEjD,uEAAuE;IACvE,GAAG,IAAI,MAAM;IAEb,sEAAsE;IACtE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAK9B,qDAAqD;IACrD,SAAS,IAAI,OAAO;IAEpB,oDAAoD;IACpD,OAAO,IAAI,IAAI;CAChB;AAED,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,gBAAgB,CAI1D,CAAC;AAEJ;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAEpD"}

package/dist/tracing/TracingExtension.js

@@ -0,0 +1,38 @@
+import { extensionId } from '../Extension.js';
+import { NOOP_TRACER } from './NoopTracer.js';
+/**
+ * `system.extension(TracingExtensionId)` accessor.  Hands back the
+ * currently-installed {@link Tracer} (defaults to the noop), so
+ * framework instrumentation can call `tracerOf(system).activeSpan()`
+ * etc. without conditional checks.  Opt in by calling `enable(tracer)`
+ * with either a `RecordingTracer` (for tests) or an adapter around
+ * `@opentelemetry/api`'s tracer.
+ */
+export class TracingExtension {
+    _system;
+    tracer = NOOP_TRACER;
+    constructor(_system) {
+        this._system = _system;
+    }
+    /** Currently-installed tracer (noop until `enable(...)` is called). */
+    get() { return this.tracer; }
+    /** Plug in a tracer.  Idempotent if you re-pass the same instance. */
+    enable(tracer) {
+        this.tracer = tracer;
+        return tracer;
+    }
+    /** True if a real (non-noop) tracer is installed. */
+    isEnabled() { return this.tracer !== NOOP_TRACER; }
+    /** Reset back to the noop — primarily for tests. */
+    disable() { this.tracer = NOOP_TRACER; }
+}
+export const TracingExtensionId = extensionId('actor-ts/tracing', (system) => new TracingExtension(system));
+/**
+ * Convenience accessor used by framework instrumentation.  Cheap on
+ * the no-tracer hot path because the extension chain returns a
+ * cached `TracingExtension` and `get()` returns the singleton noop.
+ */
+export function tracerOf(system) {
+    return system.extension(TracingExtensionId).get();
+}
+//# sourceMappingURL=TracingExtension.js.map

package/dist/tracing/TracingExtension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TracingExtension.js","sourceRoot":"","sources":["../../src/tracing/TracingExtension.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAoC,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG9C;;;;;;;GAOG;AACH,MAAM,OAAO,gBAAgB;IAGE;IAFrB,MAAM,GAAW,WAAW,CAAC;IAErC,YAA6B,OAAoB;QAApB,YAAO,GAAP,OAAO,CAAa;IAAG,CAAC;IAErD,uEAAuE;IACvE,GAAG,KAAa,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAErC,sEAAsE;IACtE,MAAM,CAAC,MAAc;QACnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,qDAAqD;IACrD,SAAS,KAAc,OAAO,IAAI,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC;IAE5D,oDAAoD;IACpD,OAAO,KAAW,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC;CAC/C;AAED,MAAM,CAAC,MAAM,kBAAkB,GAC7B,WAAW,CACT,kBAAkB,EAClB,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,gBAAgB,CAAC,MAAM,CAAC,CACzC,CAAC;AAEJ;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAmB;IAC1C,OAAO,MAAM,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC,GAAG,EAAE,CAAC;AACpD,CAAC"}

package/dist/tracing/index.d.ts

@@ -0,0 +1,9 @@
+export type { Tracer, Span, SpanContext, SpanOptions, SpanKind, SpanStatus, AttributeValue, TraceCarrier, } from './Tracer.js';
+export { encodeTraceparent, decodeTraceparent, newTraceId, newSpanId, } from './Tracer.js';
+export { NoopTracer, NOOP_TRACER } from './NoopTracer.js';
+export { RecordingTracer } from './RecordingTracer.js';
+export type { RecordedSpan, RecordingTracerOptions, } from './RecordingTracer.js';
+export { TracingExtension, TracingExtensionId, tracerOf, } from './TracingExtension.js';
+export { otelTracer } from './OtelAdapter.js';
+export type { OtelAdapterOptions, OtelApiLike, OtelContextApi, OtelContextLike, OtelPropagationApi, OtelSpanContextLike, OtelSpanLike, OtelTraceApi, OtelTracerLike, } from './OtelAdapter.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tracing/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,MAAM,EACN,IAAI,EACJ,WAAW,EACX,WAAW,EACX,QAAQ,EACR,UAAU,EACV,cAAc,EACd,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,SAAS,GACV,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EACV,YAAY,EACZ,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,QAAQ,GACT,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EACV,kBAAkB,EAClB,WAAW,EACX,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,cAAc,GACf,MAAM,kBAAkB,CAAC"}

package/dist/tracing/index.js

@@ -0,0 +1,6 @@
+export { encodeTraceparent, decodeTraceparent, newTraceId, newSpanId, } from './Tracer.js';
+export { NoopTracer, NOOP_TRACER } from './NoopTracer.js';
+export { RecordingTracer } from './RecordingTracer.js';
+export { TracingExtension, TracingExtensionId, tracerOf, } from './TracingExtension.js';
+export { otelTracer } from './OtelAdapter.js';
+//# sourceMappingURL=index.js.map

package/dist/tracing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tracing/index.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,SAAS,GACV,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAKvD,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,QAAQ,GACT,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/typed/Behavior.d.ts

@@ -0,0 +1,78 @@
+import type { TypedActorContext } from './TypedActorContext.js';
+import type { SupervisorStrategy } from '../Supervision.js';
+/**
+ * Signals are lifecycle/system events delivered to a behavior's onSignal
+ * handler — enough to react to children terminating or to the actor
+ * itself stopping.
+ */
+export type Signal = {
+    readonly kind: 'post-stop';
+} | {
+    readonly kind: 'pre-restart';
+    readonly reason: Error;
+} | {
+    readonly kind: 'terminated';
+    readonly ref: import('../ActorRef.js').ActorRef;
+};
+/**
+ * A Behavior describes how to handle the next message (and optionally
+ * lifecycle signals).  Behaviors are values, not classes — the runtime
+ * interprets the discriminant and calls back into user code.
+ */
+export type Behavior<T> = ReceiveBehavior<T> | SetupBehavior<T> | WithTimersBehavior<T> | WithStashBehavior<T> | SuperviseBehavior<T> | SameBehavior | StoppedBehavior | UnhandledBehavior | EmptyBehavior | IgnoreBehavior;
+export interface ReceiveBehavior<T> {
+    readonly kind: 'receive';
+    readonly handler: (ctx: TypedActorContext<T>, msg: T) => Behavior<T>;
+    readonly onSignal?: (ctx: TypedActorContext<T>, signal: Signal) => Behavior<T>;
+}
+export interface SetupBehavior<T> {
+    readonly kind: 'setup';
+    readonly factory: (ctx: TypedActorContext<T>) => Behavior<T>;
+}
+export interface WithTimersBehavior<T> {
+    readonly kind: 'with-timers';
+    readonly factory: (timers: import('../ActorContext.js').TimerScheduler<T>) => Behavior<T>;
+}
+export interface WithStashBehavior<T> {
+    readonly kind: 'with-stash';
+    readonly capacity: number;
+    readonly factory: (stash: StashBuffer<T>) => Behavior<T>;
+}
+export interface SuperviseBehavior<T> {
+    readonly kind: 'supervise';
+    readonly child: Behavior<T>;
+    readonly strategy: SupervisorStrategy;
+}
+export interface SameBehavior {
+    readonly kind: 'same';
+}
+export interface StoppedBehavior {
+    readonly kind: 'stopped';
+}
+export interface UnhandledBehavior {
+    readonly kind: 'unhandled';
+}
+export interface EmptyBehavior {
+    readonly kind: 'empty';
+}
+export interface IgnoreBehavior {
+    readonly kind: 'ignore';
+}
+/**
+ * Lightweight stash interface handed to `Behaviors.withStash` factories.
+ * Thin wrapper over the OO `context.stash()` API so the typed DSL keeps
+ * the same guarantees (FIFO, capacity, overflow error).
+ */
+export interface StashBuffer<T> {
+    /** Stash the current message; must be called during a user message. */
+    stash(message: T): void;
+    /** Replay the buffered messages back onto the mailbox. */
+    unstashAll(): void;
+    /** True if the buffer holds any message. */
+    readonly isEmpty: boolean;
+    /** True if the buffer is at capacity. */
+    readonly isFull: boolean;
+    /** Current number of stashed messages. */
+    readonly size: number;
+}
+//# sourceMappingURL=Behavior.d.ts.map

package/dist/typed/Behavior.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Behavior.d.ts","sourceRoot":"","sources":["../../src/typed/Behavior.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D;;;;GAIG;AACH,MAAM,MAAM,MAAM,GACd;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,gBAAgB,EAAE,QAAQ,CAAA;CAAE,CAAC;AAErF;;;;GAIG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAClB,eAAe,CAAC,CAAC,CAAC,GAClB,aAAa,CAAC,CAAC,CAAC,GAChB,kBAAkB,CAAC,CAAC,CAAC,GACrB,iBAAiB,CAAC,CAAC,CAAC,GACpB,iBAAiB,CAAC,CAAC,CAAC,GACpB,YAAY,GACZ,eAAe,GACf,iBAAiB,GACjB,aAAa,GACb,cAAc,CAAC;AAEnB,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC;CAChF;AAED,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,oBAAoB,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC;CAC3F;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;CACvC;AAED,MAAM,WAAW,YAAY;IAAG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CAAE;AACxD,MAAM,WAAW,eAAe;IAAG,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CAAE;AAC9D,MAAM,WAAW,iBAAiB;IAAG,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAAE;AAClE,MAAM,WAAW,aAAa;IAAG,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CAAE;AAC1D,MAAM,WAAW,cAAc;IAAG,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CAAE;AAE5D;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,uEAAuE;IACvE,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;IACxB,0DAA0D;IAC1D,UAAU,IAAI,IAAI,CAAC;IACnB,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB"}

package/dist/typed/Behavior.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Behavior.js.map

package/dist/typed/Behavior.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Behavior.js","sourceRoot":"","sources":["../../src/typed/Behavior.ts"],"names":[],"mappings":""}

package/dist/typed/Behaviors.d.ts

@@ -0,0 +1,60 @@
+import type { SupervisorStrategy } from '../Supervision.js';
+import type { TimerScheduler } from '../ActorContext.js';
+import type { Behavior, ReceiveBehavior, StashBuffer, Signal } from './Behavior.js';
+import type { TypedActorContext } from './TypedActorContext.js';
+/**
+ * Fluent builder returned by `Behaviors.supervise(...)` so users can write
+ * `Behaviors.supervise(b).onFailure(strategy)`.
+ */
+export interface SuperviseBuilder<T> {
+    onFailure(strategy: SupervisorStrategy): Behavior<T>;
+}
+/**
+ * Factory for building Behaviors — the functional facade over the OO
+ * Actor API.  Use these combinators to compose an actor's logic as a tree
+ * of values rather than as an imperative class.
+ */
+export declare const Behaviors: {
+    /**
+     * Run `factory` once with the actor's context; the returned Behavior is
+     * the first one the actor adopts.  Use this to capture `ctx.self` or spawn
+     * children in the "constructor".
+     */
+    setup<T>(factory: (ctx: TypedActorContext<T>) => Behavior<T>): Behavior<T>;
+    /** Standard receive — gets both context and message. */
+    receive<T>(handler: (ctx: TypedActorContext<T>, msg: T) => Behavior<T>): ReceiveBehavior<T>;
+    /** Receive with an additional signal handler. */
+    receiveWithSignal<T>(handler: (ctx: TypedActorContext<T>, msg: T) => Behavior<T>, onSignal: (ctx: TypedActorContext<T>, signal: Signal) => Behavior<T>): ReceiveBehavior<T>;
+    /** Receive when you don't need the context — message-only shortcut. */
+    receiveMessage<T>(handler: (msg: T) => Behavior<T>): ReceiveBehavior<T>;
+    /** Expose the per-actor TimerScheduler to the behavior. */
+    withTimers<T>(factory: (timers: TimerScheduler<T>) => Behavior<T>): Behavior<T>;
+    /**
+     * Expose a capacity-bounded stash buffer.  The inner behavior can stash
+     * user messages (e.g. during init) and call `stash.unstashAll()` later.
+     */
+    withStash<T>(capacity: number, factory: (stash: StashBuffer<T>) => Behavior<T>): Behavior<T>;
+    /**
+     * Wrap a behavior with a supervisor strategy.  Any error thrown from the
+     * wrapped handler is routed through `strategy` — the behavior is restarted
+     * (reset to its initial form), stopped, resumed, or escalated.
+     */
+    supervise<T>(child: Behavior<T>): SuperviseBuilder<T>;
+    /** Sentinel: keep the current behavior. */
+    readonly same: Behavior<never>;
+    /** Sentinel: stop the actor. */
+    readonly stopped: Behavior<never>;
+    /** Sentinel: mark the message as unhandled (goes to dead letters). */
+    readonly unhandled: Behavior<never>;
+    /** Sentinel: accept messages but do nothing — useful as a placeholder. */
+    readonly empty: Behavior<never>;
+    /** Sentinel: drop every incoming message silently. */
+    readonly ignore: Behavior<never>;
+};
+/** Re-exports for callers that prefer named imports. */
+export declare const same: <T>() => Behavior<T>;
+export declare const stopped: <T>() => Behavior<T>;
+export declare const unhandled: <T>() => Behavior<T>;
+export declare const empty: <T>() => Behavior<T>;
+export declare const ignore: <T>() => Behavior<T>;
+//# sourceMappingURL=Behaviors.d.ts.map

package/dist/typed/Behaviors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Behaviors.d.ts","sourceRoot":"","sources":["../../src/typed/Behaviors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EACV,QAAQ,EACR,eAAe,EAEf,WAAW,EAKX,MAAM,EACP,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAahE;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,SAAS,CAAC,QAAQ,EAAE,kBAAkB,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;CACtD;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS;IACpB;;;;OAIG;UACG,CAAC,WAAW,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;IAI1E,wDAAwD;YAChD,CAAC,WACE,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,GAC1D,eAAe,CAAC,CAAC,CAAC;IAIrB,iDAAiD;sBAC/B,CAAC,WACR,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,YACjD,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,GACnE,eAAe,CAAC,CAAC,CAAC;IAIrB,uEAAuE;mBACxD,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;IAIvE,2DAA2D;eAChD,CAAC,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;IAI/E;;;OAGG;cACO,CAAC,YAAY,MAAM,WAAW,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;IAI5F;;;;OAIG;cACO,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC;IAQrD,2CAA2C;mBAC/B,QAAQ,CAAC,KAAK,CAAC;IAE3B,gCAAgC;sBACjB,QAAQ,CAAC,KAAK,CAAC;IAE9B,sEAAsE;wBACrD,QAAQ,CAAC,KAAK,CAAC;IAEhC,0EAA0E;oBAC7D,QAAQ,CAAC,KAAK,CAAC;IAE5B,sDAAsD;qBACxC,QAAQ,CAAC,KAAK,CAAC;CAC9B,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,IAAI,GAAI,CAAC,OAAK,QAAQ,CAAC,CAAC,CAAkC,CAAC;AACxE,eAAO,MAAM,OAAO,GAAI,CAAC,OAAK,QAAQ,CAAC,CAAC,CAAqC,CAAC;AAC9E,eAAO,MAAM,SAAS,GAAI,CAAC,OAAK,QAAQ,CAAC,CAAC,CAAuC,CAAC;AAClF,eAAO,MAAM,KAAK,GAAI,CAAC,OAAK,QAAQ,CAAC,CAAC,CAAmC,CAAC;AAC1E,eAAO,MAAM,MAAM,GAAI,CAAC,OAAK,QAAQ,CAAC,CAAC,CAAoC,CAAC"}