@tickernelz/paperclip-pro-adapter-utils 2026.925.0

package/dist/duplex-frame-codec.test.js

@@ -0,0 +1,172 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { DEFAULT_MAX_DUPLEX_FRAME_BYTES, DUPLEX_FRAME_VERSION, decodeDuplexLine, encodeDuplexFrame, encodeDuplexFrameChecked, } from "./duplex-frame-codec.js";
+const fixturePath = fileURLToPath(new URL("./duplex-frame-vectors.json", import.meta.url));
+const fixture = JSON.parse(readFileSync(fixturePath, "utf8"));
+describe("duplex frame codec fixture", () => {
+    it("the fixture version matches the codec version", () => {
+        expect(fixture.frameVersion).toBe(DUPLEX_FRAME_VERSION);
+        expect(fixture.defaultMaxFrameBytes).toBe(DEFAULT_MAX_DUPLEX_FRAME_BYTES);
+    });
+    it("every category has at least one vector", () => {
+        const categories = new Set(fixture.vectors.map((vector) => vector.category));
+        for (const category of ["valid", "invalid", "versionMismatch"]) {
+            expect(categories).toContain(category);
+        }
+    });
+    for (const vector of fixture.vectors) {
+        it(`decodes the ${vector.name} vector`, () => {
+            // Every remaining vector is one complete line, so `decodeDuplexLine`
+            // reads it directly. The trailing newline in the fixture bytes is not
+            // part of the line the decoder reads.
+            const line = vector.bytes.endsWith("\n") ? vector.bytes.slice(0, -1) : vector.bytes;
+            const result = decodeDuplexLine(line);
+            const want = vector.expected[0];
+            if ("frame" in want) {
+                expect(result.ok).toBe(true);
+                if (result.ok)
+                    expect(result.frame).toEqual(want.frame);
+            }
+            else {
+                expect(result.ok).toBe(false);
+                if (!result.ok)
+                    expect(result.error.code).toBe(want.error);
+            }
+        });
+    }
+});
+describe("round-trip", () => {
+    const validVectors = fixture.vectors.filter((vector) => vector.roundTrip);
+    it("has round-trip vectors for every frame type", () => {
+        const types = new Set(validVectors.flatMap((vector) => vector.expected.flatMap((result) => "frame" in result ? [result.frame.type] : [])));
+        for (const type of ["ready", "heartbeat", "close", "error"]) {
+            expect(types).toContain(type);
+        }
+    });
+    for (const vector of validVectors) {
+        it(`re-encodes the ${vector.name} frame to the same value`, () => {
+            const want = vector.expected[0];
+            expect("frame" in want).toBe(true);
+            if (!("frame" in want))
+                return;
+            const encoded = encodeDuplexFrame(want.frame);
+            // Encode writes exactly one line: it ends with one newline and holds no
+            // interior newline, so one frame stays on one line.
+            expect(encoded.endsWith("\n")).toBe(true);
+            expect(encoded.slice(0, -1)).not.toContain("\n");
+            const decoded = decodeDuplexLine(encoded.slice(0, -1));
+            expect(decoded.ok).toBe(true);
+            if (decoded.ok)
+                expect(decoded.frame).toEqual(want.frame);
+        });
+    }
+});
+describe("ready frame schema", () => {
+    // READY is a liveness signal, not an address source. The strict schema holds
+    // exactly the frame version and the nonce.
+    it("accepts a READY frame that carries exactly the version and the nonce", () => {
+        const result = decodeDuplexLine(JSON.stringify({ version: DUPLEX_FRAME_VERSION, type: "ready", nonce: "a1b2c3d4e5f6a7b8" }));
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.frame).toEqual({
+                version: DUPLEX_FRAME_VERSION,
+                type: "ready",
+                nonce: "a1b2c3d4e5f6a7b8",
+            });
+        }
+    });
+    it.each([
+        { name: "an absent nonce", frame: { version: DUPLEX_FRAME_VERSION, type: "ready" } },
+        {
+            name: "a wrong-typed nonce",
+            frame: { version: DUPLEX_FRAME_VERSION, type: "ready", nonce: 42 },
+        },
+        {
+            name: "an extra address field",
+            frame: {
+                version: DUPLEX_FRAME_VERSION,
+                type: "ready",
+                nonce: "a1b2c3d4e5f6a7b8",
+                address: "http://127.0.0.1:47215",
+            },
+        },
+        {
+            name: "an extra port field",
+            frame: { version: DUPLEX_FRAME_VERSION, type: "ready", nonce: "a1b2c3d4e5f6a7b8", port: 47215 },
+        },
+    ])("rejects a READY frame with $name", ({ frame }) => {
+        const result = decodeDuplexLine(JSON.stringify(frame));
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("malformed_frame");
+    });
+});
+describe("size-checked encode", () => {
+    it("runs every shared encode vector and matches the expected result", () => {
+        // Every codec copy runs the same encode vectors. This copy proves it enforces
+        // the same bound the embedded gateway copy enforces.
+        for (const vector of fixture.encodeVectors) {
+            const result = encodeDuplexFrameChecked(vector.frame, vector.maxFrameBytes);
+            expect(result.ok).toBe(vector.expected.ok);
+            if (result.ok) {
+                // An ok line ends with one newline and decodes back to the same frame, so
+                // the encode guard never truncates or passes a bad frame through.
+                expect(result.line.endsWith("\n")).toBe(true);
+                expect(result.line.slice(0, -1)).not.toContain("\n");
+                const decoded = decodeDuplexLine(result.line.slice(0, -1));
+                expect(decoded.ok).toBe(true);
+                if (decoded.ok)
+                    expect(decoded.frame).toEqual(vector.frame);
+            }
+            else if (!vector.expected.ok) {
+                expect(result.error.code).toBe(vector.expected.error);
+            }
+        }
+    });
+    it("rejects an over-bound frame with a typed outcome and never throws", () => {
+        const frame = {
+            version: DUPLEX_FRAME_VERSION,
+            type: "error",
+            code: "read_timeout",
+            message: "x".repeat(2_000),
+        };
+        expect(() => encodeDuplexFrameChecked(frame, 1_000)).not.toThrow();
+        const result = encodeDuplexFrameChecked(frame, 1_000);
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("frame_too_large");
+    });
+    it("measures the bound in bytes without the trailing newline, so the boundary is inclusive", () => {
+        // Build a frame whose encoded JSON is exactly N bytes. The guard measures the
+        // JSON without the newline, so N bytes encodes and N+1 bytes fails. This is the
+        // same boundary the decoder applies, so encode and decode agree exactly.
+        // Pad the message to grow the encoded JSON by an exact byte count. Each
+        // padding character adds one byte, so the frame lands on an exact size the
+        // guard measures without the trailing newline.
+        const pad = (n) => ({
+            version: DUPLEX_FRAME_VERSION,
+            type: "error",
+            code: "boundary",
+            message: "x".repeat(n),
+        });
+        const baseBytes = Buffer.byteLength(JSON.stringify(pad(0)), "utf8");
+        const limit = baseBytes + 10;
+        const atLimit = pad(10);
+        expect(Buffer.byteLength(JSON.stringify(atLimit), "utf8")).toBe(limit);
+        const okResult = encodeDuplexFrameChecked(atLimit, limit);
+        expect(okResult.ok).toBe(true);
+        const overResult = encodeDuplexFrameChecked(pad(11), limit);
+        expect(overResult.ok).toBe(false);
+        if (!overResult.ok)
+            expect(overResult.error.code).toBe("frame_too_large");
+    });
+    it("defaults the bound to the default max frame bytes", () => {
+        const frame = { version: DUPLEX_FRAME_VERSION, type: "heartbeat" };
+        const result = encodeDuplexFrameChecked(frame);
+        expect(result.ok).toBe(true);
+        if (result.ok)
+            expect(result.line).toBe(encodeDuplexFrame(frame));
+    });
+});
+//# sourceMappingURL=duplex-frame-codec.test.js.map

package/dist/duplex-frame-codec.test.js.map

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

package/dist/duplex-observability.d.ts

@@ -0,0 +1,220 @@
+/**
+ * The fixed observability surface for the sandbox duplex transport.
+ *
+ * This module owns the one closed contract for every duplex telemetry sink: the
+ * span names, the counter names, the one event name, the dimension keys, and the
+ * enum values. Each name and value is a literal constant here, so the surface
+ * never drifts and a test asserts the exact set.
+ *
+ * The module also owns the provider allowlist. The `provider` dimension carries
+ * one approved public value, `daytona`. Any other plugin key maps to the constant
+ * `other`. The map runs inside this module before every sink, so a raw plugin key
+ * never reaches a span attribute, a counter label, or an event field.
+ *
+ * The module stays free of `@opentelemetry/api` and of the database. The host
+ * injects a {@link DuplexObservabilityRecorder}; the default is a no-op recorder, so
+ * the whole surface stays inert until the host binds a real recorder. Every
+ * recorder call sits inside an error swallow, so a telemetry failure never breaks
+ * the request path.
+ */
+/** The span for one duplex channel-open attempt. */
+export declare const DUPLEX_SPAN_CHANNEL_OPEN = "sandbox.duplex.channel_open";
+/** The span for one duplex request. It carries the request latency. */
+export declare const DUPLEX_SPAN_REQUEST = "sandbox.duplex.request";
+/** The one duplex transport event. The host emits it at each transport boundary. */
+export declare const DUPLEX_TRANSPORT_EVENT = "sandbox.duplex.transport";
+/** The guarded counter for one successful channel open. */
+export declare const DUPLEX_COUNTER_CHANNEL_OPEN_TOTAL = "sandbox_duplex_channel_open_total";
+/** The guarded counter for one fallback to the file bridge. */
+export declare const DUPLEX_COUNTER_FALLBACK_TOTAL = "sandbox_duplex_fallback_total";
+/** The guarded counter for one terminal channel loss. */
+export declare const DUPLEX_COUNTER_LOSS_TOTAL = "sandbox_duplex_loss_total";
+/** The guarded counter for one leaked provider session on teardown. */
+export declare const DUPLEX_COUNTER_SESSION_LEAK_TOTAL = "sandbox_duplex_session_leak_total";
+/**
+ * The closed dimension-key set. Every span attribute, counter label, and event
+ * field uses only these keys. A test asserts the exact set, so a new key never
+ * reaches a sink by accident.
+ */
+export declare const DUPLEX_DIMENSION_KEYS: readonly ["provider", "transport", "outcome", "fallback_reason", "loss_class", "loss_reason"];
+/** One dimension key from the closed set. */
+export type DuplexDimensionKey = (typeof DUPLEX_DIMENSION_KEYS)[number];
+/**
+ * The transport a record is about. `duplex` names the retired bespoke frame
+ * protocol; `http2` names the Node HTTP/2 session over the sandbox channel;
+ * `file` names the queue-file bridge.
+ */
+export type DuplexTransportValue = "duplex" | "http2" | "file";
+/** The outcome of a record. */
+export type DuplexOutcomeValue = "ok" | "error";
+/**
+ * The reason the host selected the file bridge instead of the duplex transport.
+ * The open-failure stage is split, so a reader groups a failed open by the exact
+ * stage: the process-scoped route ceiling was full (`route_busy`), the entrypoint
+ * sync failed (`entrypoint_sync_failed`), the broker construction failed
+ * (`broker_construction_failed`), or the channel open failed (`channel_open_failed`).
+ * The `preface_missing` reason names a missing or an invalid HTTP/2 client
+ * connection preface inside the bounded readiness buffer: the host found no
+ * valid preface after the accepted READY line, aborted the HTTP/2 open, and
+ * moved the run to `queue_v1` one time.
+ */
+export type DuplexFallbackReason = "gate_off" | "capability_absent" | "route_busy" | "entrypoint_sync_failed" | "broker_construction_failed" | "channel_open_failed" | "ready_invalid" | "ready_nonce_mismatch" | "ready_timeout" | "contaminated" | "preface_missing";
+/** The class of a terminal loss, relative to the first request dispatch. */
+export type DuplexLossClass = "pre_dispatch" | "post_dispatch";
+/**
+ * The closed, typed reason for a terminal channel loss. The host maps every loss
+ * cause to one of these values before any sink reads it. The set covers the
+ * loss-detection modes the transport names: a gateway stdin end of file, a
+ * provider process exit, a heartbeat timeout, and an RPC failure. It adds
+ * `write_error` for a rejected host-to-sandbox write, `transport_closed` for a
+ * reason-less provider transport close with no exit data, and `other` for an
+ * unknown cause. The host maps an unknown cause or any caught provider text to
+ * `other`, so no raw provider text reaches a sink.
+ */
+export declare const DUPLEX_LOSS_REASONS: readonly ["stdin_eof", "provider_exit", "heartbeat_timeout", "rpc_failure", "write_error", "transport_closed", "other"];
+/** One typed loss reason from the closed set. */
+export type DuplexLossReason = (typeof DUPLEX_LOSS_REASONS)[number];
+/**
+ * Map a raw loss-cause value to the closed {@link DuplexLossReason} set. Return
+ * the value when the closed set holds it. Return `other` for any other value or a
+ * missing value, so a raw provider string never reaches a sink.
+ */
+export declare function normalizeDuplexLossReason(value: string | null | undefined): DuplexLossReason;
+/**
+ * The closed set of HTTP/2 session and stream event names the host maps to a
+ * loss reason. Each name spells one distinct signal the `http2_v1` transport
+ * can observe: a session-level protocol fault, a peer GOAWAY, a stalled PING
+ * watchdog, a rejected host-to-sandbox write, a reason-less transport close,
+ * or the pseudo-terminal channel process exit.
+ */
+export declare const HTTP2_TELEMETRY_EVENT_NAMES: readonly ["session_error", "session_goaway", "session_stall", "write_error", "transport_closed", "channel_exit"];
+/** One event name from the closed HTTP/2 event set. */
+export type Http2TelemetryEventName = (typeof HTTP2_TELEMETRY_EVENT_NAMES)[number];
+/**
+ * Map one HTTP/2 session or stream event name to the closed
+ * {@link DuplexLossReason} taxonomy (accepted security fix 7). Return the
+ * mapped reason when the closed event-name set holds the value. Return
+ * `other` for any other value or a missing value, so an unknown event name or
+ * a raw provider string never reaches a sink.
+ */
+export declare function mapHttp2EventToDuplexLossReason(event: string | null | undefined): DuplexLossReason;
+/** The one approved public provider value. */
+export declare const DUPLEX_APPROVED_PROVIDER = "daytona";
+/** The constant for any provider key outside the allowlist. */
+export declare const DUPLEX_PROVIDER_OTHER = "other";
+/** The `provider` dimension value after the allowlist map. */
+export type DuplexProviderValue = typeof DUPLEX_APPROVED_PROVIDER | typeof DUPLEX_PROVIDER_OTHER;
+/**
+ * Map a raw provider key to the closed `provider` dimension value. Return the key
+ * when the allowlist holds it. Return `other` for any other value, so a raw
+ * plugin key never reaches a sink. A missing key also maps to `other`.
+ */
+export declare function normalizeDuplexProvider(key: string | null | undefined): DuplexProviderValue;
+/**
+ * The dimension bag a sink reads. Only the closed keys appear. The optional keys
+ * are present only when the record defines them, so a span or a counter never
+ * carries an empty dimension.
+ */
+export interface DuplexObservabilityDimensions {
+    provider: DuplexProviderValue;
+    transport: DuplexTransportValue;
+    outcome?: DuplexOutcomeValue;
+    fallback_reason?: DuplexFallbackReason;
+    loss_class?: DuplexLossClass;
+    loss_reason?: DuplexLossReason;
+}
+/** One span record the host records. The request span carries a latency. */
+export interface DuplexObservabilitySpanRecord {
+    name: string;
+    dimensions: DuplexObservabilityDimensions;
+    /** The request latency in milliseconds. Only the request span sets it. */
+    latencyMs?: number;
+}
+/** One counter increment the host records. */
+export interface DuplexObservabilityCounterRecord {
+    metric: string;
+    dimensions: DuplexObservabilityDimensions;
+}
+/** One event the host emits. */
+export interface DuplexObservabilityEventRecord {
+    name: string;
+    dimensions: DuplexObservabilityDimensions;
+}
+/**
+ * The injected low-level recorder. The host binds it to the existing telemetry
+ * pipeline: the span to the OTel tracer, the counter to the guarded counter
+ * store, and the event to the run-events bridge. The default is a no-op recorder.
+ * The recorder receives only already-mapped dimensions, so the raw provider key
+ * never reaches it.
+ */
+export interface DuplexObservabilityRecorder {
+    recordSpan(record: DuplexObservabilitySpanRecord): void;
+    incrementCounter(record: DuplexObservabilityCounterRecord): void;
+    emitEvent(record: DuplexObservabilityEventRecord): void;
+}
+/** A no-op recorder. Every method does nothing, so the surface stays inert. */
+export declare const NOOP_DUPLEX_OBSERVABILITY_RECORDER: DuplexObservabilityRecorder;
+/** One channel-open attempt. The caller reports exactly one terminal. */
+export interface DuplexChannelOpenAttempt {
+    /**
+     * The channel opened and readiness passed. Record the channel-open span with
+     * the `ok` outcome, increment the channel-open counter, and emit the transport
+     * event for the duplex transport.
+     */
+    ready(): void;
+    /**
+     * The channel did not open or readiness failed. Record the channel-open span
+     * with the `error` outcome, increment the fallback counter, and emit the
+     * transport event for the file bridge.
+     */
+    fallback(reason: DuplexFallbackReason): void;
+}
+/**
+ * The bound telemetry facade the call sites use. It carries the normalized
+ * provider, so a call site never passes a raw key. It maps each semantic event to
+ * the fixed names and dimensions, then calls the recorder inside an error swallow.
+ */
+export interface DuplexObservability {
+    /** Begin a channel-open attempt. The caller reports `ready` or `fallback`. */
+    startChannelOpen(): DuplexChannelOpenAttempt;
+    /**
+     * Record a fallback to the file bridge with no channel-open attempt. Use it for
+     * `gate_off` and `capability_absent`, where the host opens no channel.
+     */
+    recordFallback(reason: DuplexFallbackReason): void;
+    /** Record one duplex request span with its latency and outcome. */
+    recordRequest(record: {
+        latencyMs: number;
+        outcome: DuplexOutcomeValue;
+    }): void;
+    /**
+     * Record one terminal channel loss. The caller passes the loss class and the
+     * typed, closed loss reason. The loss counter and the transport loss event carry
+     * both dimensions. No raw provider text rides either sink.
+     */
+    recordLoss(lossClass: DuplexLossClass, lossReason: DuplexLossReason): void;
+    /** Record one leaked provider session on teardown. */
+    recordSessionLeak(): void;
+}
+/** The options for {@link createDuplexObservability}. */
+export interface DuplexObservabilityOptions {
+    /** The injected recorder. The default is the no-op recorder. */
+    recorder?: DuplexObservabilityRecorder | null;
+    /** The raw provider key. The facade maps it through the allowlist one time. */
+    providerKey?: string | null;
+    /**
+     * The transport value the facade stamps on every non-file record (a channel
+     * open, a request, a loss, a session leak). The default is `duplex`, so an
+     * existing caller that names no transport sees no change. The host passes
+     * `http2` for the `http2_v1` path.
+     */
+    transport?: DuplexTransportValue;
+}
+/**
+ * Build the bound telemetry facade. The facade normalizes the provider key one
+ * time, then reuses the mapped value for every record. Every recorder call sits
+ * inside a `try/catch`, so a throwing recorder never breaks the request path. A
+ * missing recorder yields a facade whose methods do nothing.
+ */
+export declare function createDuplexObservability(options?: DuplexObservabilityOptions): DuplexObservability;
+//# sourceMappingURL=duplex-observability.d.ts.map

package/dist/duplex-observability.d.ts.map

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

package/dist/duplex-observability.js

@@ -0,0 +1,248 @@
+/**
+ * The fixed observability surface for the sandbox duplex transport.
+ *
+ * This module owns the one closed contract for every duplex telemetry sink: the
+ * span names, the counter names, the one event name, the dimension keys, and the
+ * enum values. Each name and value is a literal constant here, so the surface
+ * never drifts and a test asserts the exact set.
+ *
+ * The module also owns the provider allowlist. The `provider` dimension carries
+ * one approved public value, `daytona`. Any other plugin key maps to the constant
+ * `other`. The map runs inside this module before every sink, so a raw plugin key
+ * never reaches a span attribute, a counter label, or an event field.
+ *
+ * The module stays free of `@opentelemetry/api` and of the database. The host
+ * injects a {@link DuplexObservabilityRecorder}; the default is a no-op recorder, so
+ * the whole surface stays inert until the host binds a real recorder. Every
+ * recorder call sits inside an error swallow, so a telemetry failure never breaks
+ * the request path.
+ */
+/** The span for one duplex channel-open attempt. */
+export const DUPLEX_SPAN_CHANNEL_OPEN = "sandbox.duplex.channel_open";
+/** The span for one duplex request. It carries the request latency. */
+export const DUPLEX_SPAN_REQUEST = "sandbox.duplex.request";
+/** The one duplex transport event. The host emits it at each transport boundary. */
+export const DUPLEX_TRANSPORT_EVENT = "sandbox.duplex.transport";
+/** The guarded counter for one successful channel open. */
+export const DUPLEX_COUNTER_CHANNEL_OPEN_TOTAL = "sandbox_duplex_channel_open_total";
+/** The guarded counter for one fallback to the file bridge. */
+export const DUPLEX_COUNTER_FALLBACK_TOTAL = "sandbox_duplex_fallback_total";
+/** The guarded counter for one terminal channel loss. */
+export const DUPLEX_COUNTER_LOSS_TOTAL = "sandbox_duplex_loss_total";
+/** The guarded counter for one leaked provider session on teardown. */
+export const DUPLEX_COUNTER_SESSION_LEAK_TOTAL = "sandbox_duplex_session_leak_total";
+/**
+ * The closed dimension-key set. Every span attribute, counter label, and event
+ * field uses only these keys. A test asserts the exact set, so a new key never
+ * reaches a sink by accident.
+ */
+export const DUPLEX_DIMENSION_KEYS = [
+    "provider",
+    "transport",
+    "outcome",
+    "fallback_reason",
+    "loss_class",
+    "loss_reason",
+];
+/**
+ * The closed, typed reason for a terminal channel loss. The host maps every loss
+ * cause to one of these values before any sink reads it. The set covers the
+ * loss-detection modes the transport names: a gateway stdin end of file, a
+ * provider process exit, a heartbeat timeout, and an RPC failure. It adds
+ * `write_error` for a rejected host-to-sandbox write, `transport_closed` for a
+ * reason-less provider transport close with no exit data, and `other` for an
+ * unknown cause. The host maps an unknown cause or any caught provider text to
+ * `other`, so no raw provider text reaches a sink.
+ */
+export const DUPLEX_LOSS_REASONS = [
+    "stdin_eof",
+    "provider_exit",
+    "heartbeat_timeout",
+    "rpc_failure",
+    "write_error",
+    "transport_closed",
+    "other",
+];
+/** The host-owned closed loss-reason set. It backs {@link normalizeDuplexLossReason}. */
+const LOSS_REASONS = new Set(DUPLEX_LOSS_REASONS);
+/**
+ * Map a raw loss-cause value to the closed {@link DuplexLossReason} set. Return
+ * the value when the closed set holds it. Return `other` for any other value or a
+ * missing value, so a raw provider string never reaches a sink.
+ */
+export function normalizeDuplexLossReason(value) {
+    return typeof value === "string" && LOSS_REASONS.has(value)
+        ? value
+        : "other";
+}
+/**
+ * The closed set of HTTP/2 session and stream event names the host maps to a
+ * loss reason. Each name spells one distinct signal the `http2_v1` transport
+ * can observe: a session-level protocol fault, a peer GOAWAY, a stalled PING
+ * watchdog, a rejected host-to-sandbox write, a reason-less transport close,
+ * or the pseudo-terminal channel process exit.
+ */
+export const HTTP2_TELEMETRY_EVENT_NAMES = [
+    "session_error",
+    "session_goaway",
+    "session_stall",
+    "write_error",
+    "transport_closed",
+    "channel_exit",
+];
+/** The host-owned closed HTTP/2 event-name set. It backs {@link mapHttp2EventToDuplexLossReason}. */
+const HTTP2_EVENT_NAMES = new Set(HTTP2_TELEMETRY_EVENT_NAMES);
+/**
+ * The map from one closed HTTP/2 event name to the existing, closed
+ * {@link DuplexLossReason} taxonomy. The map reuses that one taxonomy instead
+ * of a second, HTTP/2-only reason list, so the closed-set pattern stays one
+ * set of values across every transport.
+ */
+const HTTP2_EVENT_TO_LOSS_REASON = {
+    session_error: "rpc_failure",
+    session_goaway: "transport_closed",
+    session_stall: "heartbeat_timeout",
+    write_error: "write_error",
+    transport_closed: "transport_closed",
+    channel_exit: "provider_exit",
+};
+/**
+ * Map one HTTP/2 session or stream event name to the closed
+ * {@link DuplexLossReason} taxonomy (accepted security fix 7). Return the
+ * mapped reason when the closed event-name set holds the value. Return
+ * `other` for any other value or a missing value, so an unknown event name or
+ * a raw provider string never reaches a sink.
+ */
+export function mapHttp2EventToDuplexLossReason(event) {
+    return typeof event === "string" && HTTP2_EVENT_NAMES.has(event)
+        ? HTTP2_EVENT_TO_LOSS_REASON[event]
+        : "other";
+}
+/** The one approved public provider value. */
+export const DUPLEX_APPROVED_PROVIDER = "daytona";
+/** The constant for any provider key outside the allowlist. */
+export const DUPLEX_PROVIDER_OTHER = "other";
+/** The host-owned closed provider allowlist. It holds one approved public value. */
+const APPROVED_PROVIDERS = new Set([DUPLEX_APPROVED_PROVIDER]);
+/**
+ * Map a raw provider key to the closed `provider` dimension value. Return the key
+ * when the allowlist holds it. Return `other` for any other value, so a raw
+ * plugin key never reaches a sink. A missing key also maps to `other`.
+ */
+export function normalizeDuplexProvider(key) {
+    return typeof key === "string" && APPROVED_PROVIDERS.has(key)
+        ? key
+        : DUPLEX_PROVIDER_OTHER;
+}
+/** A no-op recorder. Every method does nothing, so the surface stays inert. */
+export const NOOP_DUPLEX_OBSERVABILITY_RECORDER = {
+    recordSpan() { },
+    incrementCounter() { },
+    emitEvent() { },
+};
+/**
+ * Build the bound telemetry facade. The facade normalizes the provider key one
+ * time, then reuses the mapped value for every record. Every recorder call sits
+ * inside a `try/catch`, so a throwing recorder never breaks the request path. A
+ * missing recorder yields a facade whose methods do nothing.
+ */
+export function createDuplexObservability(options = {}) {
+    const recorder = options.recorder ?? NOOP_DUPLEX_OBSERVABILITY_RECORDER;
+    const provider = normalizeDuplexProvider(options.providerKey);
+    const transport = options.transport ?? "duplex";
+    const safeSpan = (record) => {
+        try {
+            recorder.recordSpan(record);
+        }
+        catch {
+            // Observability must not break the request path.
+        }
+    };
+    const safeCounter = (record) => {
+        try {
+            recorder.incrementCounter(record);
+        }
+        catch {
+            // Observability must not break the request path.
+        }
+    };
+    const safeEvent = (record) => {
+        try {
+            recorder.emitEvent(record);
+        }
+        catch {
+            // Observability must not break the request path.
+        }
+    };
+    const recordFallback = (reason) => {
+        const dimensions = {
+            provider,
+            transport: "file",
+            outcome: "error",
+            fallback_reason: reason,
+        };
+        safeCounter({ metric: DUPLEX_COUNTER_FALLBACK_TOTAL, dimensions });
+        safeEvent({ name: DUPLEX_TRANSPORT_EVENT, dimensions });
+    };
+    return {
+        startChannelOpen() {
+            let settled = false;
+            return {
+                ready() {
+                    if (settled)
+                        return;
+                    settled = true;
+                    const dimensions = {
+                        provider,
+                        transport,
+                        outcome: "ok",
+                    };
+                    safeSpan({ name: DUPLEX_SPAN_CHANNEL_OPEN, dimensions });
+                    safeCounter({ metric: DUPLEX_COUNTER_CHANNEL_OPEN_TOTAL, dimensions });
+                    safeEvent({ name: DUPLEX_TRANSPORT_EVENT, dimensions });
+                },
+                fallback(reason) {
+                    if (settled)
+                        return;
+                    settled = true;
+                    // The channel-open span records the failed attempt on the duplex
+                    // transport; the counter and the event record the file-bridge fallback.
+                    // The span carries `fallback_reason` on this fallback path only, so a
+                    // reader can group the failed opens by reason. `fallback_reason` is a
+                    // closed dimension key, so no new key reaches a sink.
+                    safeSpan({
+                        name: DUPLEX_SPAN_CHANNEL_OPEN,
+                        dimensions: { provider, transport, outcome: "error", fallback_reason: reason },
+                    });
+                    recordFallback(reason);
+                },
+            };
+        },
+        recordFallback,
+        recordRequest(record) {
+            safeSpan({
+                name: DUPLEX_SPAN_REQUEST,
+                dimensions: { provider, transport, outcome: record.outcome },
+                latencyMs: record.latencyMs,
+            });
+        },
+        recordLoss(lossClass, lossReason) {
+            const dimensions = {
+                provider,
+                transport,
+                outcome: "error",
+                loss_class: lossClass,
+                loss_reason: lossReason,
+            };
+            safeCounter({ metric: DUPLEX_COUNTER_LOSS_TOTAL, dimensions });
+            safeEvent({ name: DUPLEX_TRANSPORT_EVENT, dimensions });
+        },
+        recordSessionLeak() {
+            safeCounter({
+                metric: DUPLEX_COUNTER_SESSION_LEAK_TOTAL,
+                dimensions: { provider, transport, outcome: "error" },
+            });
+        },
+    };
+}
+//# sourceMappingURL=duplex-observability.js.map