@runtime-digital-twin/sdk 1.0.0

package/dist/event-envelope.js

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * Base event envelope - all trace events must include these fields
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBaseEvent = createBaseEvent;
+exports.validateBaseEnvelope = validateBaseEnvelope;
+const fs_1 = require("fs");
+const path_1 = require("path");
+/**
+ * Resolve service name from environment variable, package.json, or fallback
+ */
+function resolveServiceName() {
+    // 1. Check environment variable (required in production)
+    const envServiceName = process.env.SERVICE_NAME;
+    if (envServiceName) {
+        return envServiceName;
+    }
+    // 2. Try to read from package.json (dev fallback)
+    try {
+        // Try to find package.json in common locations
+        const possiblePaths = [
+            (0, path_1.join)(process.cwd(), 'package.json'),
+            (0, path_1.join)(__dirname, '..', 'package.json'),
+            (0, path_1.join)(__dirname, '..', '..', 'package.json'),
+        ];
+        for (const pkgPath of possiblePaths) {
+            try {
+                const pkgContent = (0, fs_1.readFileSync)(pkgPath, 'utf8');
+                const pkg = JSON.parse(pkgContent);
+                if (pkg.name) {
+                    return pkg.name;
+                }
+            }
+            catch {
+                // Continue to next path
+            }
+        }
+    }
+    catch {
+        // Fall through to fallback
+    }
+    // 3. Fallback
+    return 'unknown-service';
+}
+/**
+ * Create a base event envelope with required fields
+ *
+ * @param type - Event type (e.g., 'http.request.inbound')
+ * @param timestamp - Event timestamp (milliseconds since epoch)
+ * @param traceId - Trace ID
+ * @param spanId - Span ID
+ * @param parentSpanId - Parent span ID (null for root spans)
+ * @param serviceName - Optional service name (will be resolved if not provided)
+ * @param additionalFields - Additional event-specific fields
+ * @returns Complete event object with base envelope + additional fields
+ */
+function createBaseEvent(type, timestamp, traceId, spanId, parentSpanId, serviceName, additionalFields) {
+    const resolvedServiceName = serviceName || resolveServiceName();
+    const baseEnvelope = {
+        type,
+        timestamp,
+        traceId,
+        spanId,
+        parentSpanId,
+        serviceName: resolvedServiceName,
+    };
+    // Merge additional fields, ensuring base envelope fields take precedence
+    return {
+        ...additionalFields,
+        ...baseEnvelope,
+    };
+}
+/**
+ * Validate that an event has all required base envelope fields
+ */
+function validateBaseEnvelope(event) {
+    const errors = [];
+    if (!event.type || typeof event.type !== 'string') {
+        errors.push('Missing or invalid "type" field');
+    }
+    if (typeof event.timestamp !== 'number') {
+        errors.push('Missing or invalid "timestamp" field (must be number)');
+    }
+    if (!event.traceId || typeof event.traceId !== 'string') {
+        errors.push('Missing or invalid "traceId" field');
+    }
+    if (!event.spanId || typeof event.spanId !== 'string') {
+        errors.push('Missing or invalid "spanId" field');
+    }
+    if (event.parentSpanId !== null && typeof event.parentSpanId !== 'string') {
+        errors.push('Invalid "parentSpanId" field (must be string or null)');
+    }
+    if (!event.serviceName || typeof event.serviceName !== 'string') {
+        errors.push('Missing or invalid "serviceName" field');
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}

package/dist/fastify-plugin.d.ts

@@ -0,0 +1,29 @@
+import { FastifyPluginAsync } from "fastify";
+import { TraceBundle } from "./trace-bundle-writer";
+export interface FastifyTracingOptions {
+    serviceName: string;
+    serviceVersion?: string;
+    environment?: string;
+    traceDir?: string;
+    headerAllowlist?: string[];
+    maxBodySize?: number;
+    enabled?: boolean;
+    uploadUrl?: string;
+    apiKey?: string;
+    uploadOnComplete?: boolean;
+}
+declare module "fastify" {
+    interface FastifyRequest {
+        traceBundle?: TraceBundle;
+        traceSpanId?: string;
+        traceStartTime?: number;
+        traceRequestBodyHash?: string | null;
+    }
+}
+/**
+ * Fastify plugin for capturing HTTP request/response traces
+ */
+export declare const fastifyTracing: FastifyPluginAsync<FastifyTracingOptions>;
+declare const _default: FastifyPluginAsync<FastifyTracingOptions>;
+export default _default;
+//# sourceMappingURL=fastify-plugin.d.ts.map

package/dist/fastify-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastify-plugin.d.ts","sourceRoot":"","sources":["../src/fastify-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAgC,MAAM,SAAS,CAAC;AAE3E,OAAO,EAKL,WAAW,EACZ,MAAM,uBAAuB,CAAC;AAY/B,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB,WAAW,CAAC,EAAE,WAAW,CAAC;QAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACtC;CACF;AAID;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,kBAAkB,CAAC,qBAAqB,CAsRpE,CAAC;;AAGF,wBAGG"}

package/dist/fastify-plugin.js

@@ -0,0 +1,243 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fastifyTracing = void 0;
+const fastify_plugin_1 = __importDefault(require("fastify-plugin"));
+const trace_bundle_writer_1 = require("./trace-bundle-writer");
+const http_wrapper_1 = require("./http-wrapper");
+const redaction_1 = require("./redaction");
+const shape_digest_utils_1 = require("./shape-digest-utils");
+const trace_uploader_1 = require("./trace-uploader");
+const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024; // 10MB
+/**
+ * Fastify plugin for capturing HTTP request/response traces
+ */
+const fastifyTracing = async (fastify, options) => {
+    const { serviceName, serviceVersion, environment, traceDir, headerAllowlist, maxBodySize = DEFAULT_MAX_BODY_SIZE, enabled = true, uploadUrl, apiKey, uploadOnComplete = true, } = options;
+    if (!enabled) {
+        fastify.log.info("[SDK] Tracing is disabled");
+        return;
+    }
+    if (!serviceName) {
+        fastify.log.warn("[SDK] serviceName is required for tracing");
+        return;
+    }
+    // Hook: onRequest - initialize trace but don't write request event yet (body not available)
+    fastify.addHook("onRequest", async (request, reply) => {
+        try {
+            // Check for trace context propagation headers
+            const incomingTraceId = request.headers['x-wraith-trace-id'];
+            const incomingParentSpanId = request.headers['x-wraith-parent-span-id'];
+            // Create trace bundle for this request
+            // Use incoming traceId if present (cross-service propagation), otherwise generate new one
+            const traceBundle = await (0, trace_bundle_writer_1.createTrace)({
+                serviceName,
+                serviceVersion,
+                environment,
+                traceDir,
+                traceId: incomingTraceId, // Will be undefined if header not present, triggering new traceId generation
+            });
+            const spanId = (0, trace_bundle_writer_1.generateSpanId)();
+            const startTime = Date.now();
+            // Store on request for later use
+            request.traceBundle = traceBundle;
+            request.traceSpanId = spanId;
+            request.traceStartTime = startTime;
+            request.traceRequestBodyHash = null; // Will be set in preHandler
+            // Store incoming parent span ID for use in preHandler
+            request.traceIncomingParentSpanId = incomingParentSpanId || null;
+        }
+        catch (error) {
+            // Fail-open: log error but don't crash
+            fastify.log.error(`[SDK] Failed to initialize trace: ${error}`);
+        }
+    });
+    // Hook: preHandler - capture inbound request with body (body is now parsed by Fastify)
+    fastify.addHook("preHandler", async (request, reply) => {
+        const traceBundle = request.traceBundle;
+        const spanId = request.traceSpanId;
+        const startTime = request.traceStartTime;
+        if (!traceBundle || !spanId || !startTime)
+            return;
+        // Set trace context for this request (so wrapped fetch can access it)
+        (0, http_wrapper_1.setTraceContext)(traceBundle, spanId);
+        try {
+            // Capture request body (now available after Fastify parsing)
+            let requestBody = null;
+            if (request.body) {
+                if (typeof request.body === "string") {
+                    requestBody = request.body;
+                }
+                else if (Buffer.isBuffer(request.body)) {
+                    requestBody = request.body;
+                }
+                else {
+                    requestBody = JSON.stringify(request.body);
+                }
+            }
+            // Process body (hash + optional blob)
+            const { bodyHash, bodyBlob } = await (0, trace_bundle_writer_1.processBody)(requestBody, traceBundle.writeBlob);
+            request.traceRequestBodyHash = bodyHash;
+            // Filter headers (redaction is applied automatically)
+            const filteredHeaders = (0, trace_bundle_writer_1.filterHeaders)(request.headers, headerAllowlist);
+            // Extract and redact query params
+            const rawQuery = request.query || {};
+            const query = (0, redaction_1.redactQueryParams)(rawQuery);
+            // Get incoming parent span ID (from cross-service propagation)
+            const incomingParentSpanId = request.traceIncomingParentSpanId;
+            // Compute shape digest for request body (async, non-blocking)
+            const contentType = (0, shape_digest_utils_1.getContentType)(request.headers);
+            const mode = (0, shape_digest_utils_1.getShapeDigestMode)();
+            const sampleRate = (0, shape_digest_utils_1.getShapeDigestSampleRate)();
+            // Use requestBody if available, otherwise fall back to request.body with proper typing
+            const bodyForDigest = requestBody ?? request.body;
+            const requestShapeDigest = await (0, shape_digest_utils_1.computeBodyShapeDigest)(bodyForDigest, contentType, { mode, sampleRate });
+            const requestContentType = contentType || undefined;
+            const bodyForSize = requestBody ?? request.body;
+            const requestSizeBytes = (0, shape_digest_utils_1.getBodySizeBytes)(bodyForSize);
+            // Write http.request.inbound event (now with body!)
+            await traceBundle.writeEvent({
+                type: "http.request.inbound",
+                timestamp: startTime,
+                spanId,
+                parentSpanId: incomingParentSpanId, // Use propagated parentSpanId if present, otherwise null (root span)
+                method: request.method,
+                path: request.url.split("?")[0], // Path without query
+                query,
+                headers: filteredHeaders,
+                bodyHash,
+                bodyBlob,
+                ...(requestShapeDigest && { requestShapeDigest }),
+                ...(requestContentType && { requestContentType }),
+                ...(requestSizeBytes !== undefined && { requestSizeBytes }),
+            });
+        }
+        catch (error) {
+            fastify.log.error(`[SDK] Failed to capture inbound request: ${error}`);
+        }
+    });
+    // Hook: onSend - capture response
+    fastify.addHook("onSend", async (request, reply, payload) => {
+        const traceBundle = request.traceBundle;
+        const spanId = request.traceSpanId;
+        const startTime = request.traceStartTime;
+        if (!traceBundle || !spanId || !startTime) {
+            return;
+        }
+        try {
+            const endTime = Date.now();
+            const durationMs = endTime - startTime;
+            // Process response body
+            let responseBody = null;
+            if (payload) {
+                if (Buffer.isBuffer(payload)) {
+                    responseBody = payload;
+                }
+                else if (typeof payload === "string") {
+                    responseBody = payload;
+                }
+                else {
+                    responseBody = JSON.stringify(payload);
+                }
+                // Check size limit
+                const bodySize = Buffer.isBuffer(responseBody)
+                    ? responseBody.length
+                    : responseBody.length;
+                if (bodySize > maxBodySize) {
+                    responseBody = null; // Skip large bodies
+                    fastify.log.debug(`[SDK] Response body too large (${bodySize} bytes), skipping`);
+                }
+            }
+            const { bodyHash, bodyBlob } = await (0, trace_bundle_writer_1.processBody)(responseBody, traceBundle.writeBlob);
+            // Filter response headers (convert numbers to strings)
+            const responseHeaders = {};
+            const rawHeaders = reply.getHeaders();
+            for (const [key, value] of Object.entries(rawHeaders)) {
+                responseHeaders[key] = String(value);
+            }
+            const filteredHeaders = (0, trace_bundle_writer_1.filterHeaders)(responseHeaders, headerAllowlist);
+            // Write http.response.inbound event
+            await traceBundle.writeEvent({
+                type: "http.response.inbound",
+                timestamp: endTime,
+                spanId,
+                parentSpanId: null,
+                statusCode: reply.statusCode,
+                headers: filteredHeaders,
+                bodyHash,
+                bodyBlob,
+                durationMs,
+            });
+            // Complete trace with inbound request summary
+            await traceBundle.complete({
+                method: request.method,
+                path: request.url.split("?")[0],
+                headers: (0, trace_bundle_writer_1.filterHeaders)(request.headers, headerAllowlist),
+                bodyHash: request.traceRequestBodyHash || undefined,
+            });
+            // Auto-upload trace if configured
+            if (uploadUrl && apiKey && uploadOnComplete !== false) {
+                // Upload asynchronously (don't block response)
+                const actualTraceDir = traceDir || './traces';
+                (0, trace_uploader_1.uploadTrace)({
+                    uploadUrl,
+                    apiKey,
+                    traceDir: actualTraceDir,
+                    traceId: traceBundle.traceId,
+                    serviceName,
+                    serviceVersion,
+                    environment,
+                }).then(result => {
+                    if (result.success) {
+                        fastify.log.info(`[SDK] Trace uploaded: ${result.traceId}`);
+                    }
+                    else {
+                        fastify.log.warn(`[SDK] Trace upload failed: ${result.error}`);
+                    }
+                }).catch(error => {
+                    fastify.log.error(`[SDK] Trace upload error: ${error}`);
+                });
+            }
+            // Clear trace context
+            (0, http_wrapper_1.setTraceContext)(null, null);
+        }
+        catch (error) {
+            // Fail-open: log error but don't crash
+            fastify.log.error(`[SDK] Failed to capture response: ${error}`);
+            // Clear trace context even on error
+            (0, http_wrapper_1.setTraceContext)(null, null);
+        }
+    });
+    // Hook: onError - capture errors
+    fastify.addHook("onError", async (request, reply, error) => {
+        const traceBundle = request.traceBundle;
+        const spanId = request.traceSpanId;
+        if (!traceBundle || !spanId) {
+            return;
+        }
+        try {
+            await traceBundle.writeEvent({
+                type: "error",
+                timestamp: Date.now(),
+                spanId,
+                parentSpanId: null,
+                error: {
+                    name: error.name || "Error",
+                    message: error.message || String(error),
+                    stack: error.stack || undefined,
+                },
+            });
+        }
+        catch (err) {
+            fastify.log.error(`[SDK] Failed to capture error: ${err}`);
+        }
+    });
+};
+exports.fastifyTracing = fastifyTracing;
+// Wrap with fastify-plugin to prevent encapsulation (hooks apply to all routes)
+exports.default = (0, fastify_plugin_1.default)(exports.fastifyTracing, {
+    name: "@runtime-digital-twin/fastify-tracing",
+    fastify: "4.x",
+});

package/dist/http-sentinels.d.ts

@@ -0,0 +1,39 @@
+/**
+ * HTTP Response Sentinels
+ *
+ * Automatic contract checking for outbound HTTP responses.
+ * Emits state.invariant events based on response characteristics.
+ */
+import type { ShapeDigest } from "@runtime-digital-twin/core";
+export type SentinelsMode = "off" | "observe" | "enforce";
+/**
+ * Get sentinels mode from environment
+ */
+export declare function getSentinelsMode(): SentinelsMode;
+/**
+ * Check if sentinels are enabled
+ */
+export declare function areSentinelsEnabled(): boolean;
+/**
+ * Check if sentinels are in enforce mode
+ */
+export declare function isEnforceMode(): boolean;
+/**
+ * Custom error for sentinel violations in enforce mode
+ */
+export declare class SentinelViolationError extends Error {
+    readonly invariantName: string;
+    readonly severity: "warn" | "error";
+    constructor(invariantName: string, severity: "warn" | "error", message: string);
+}
+/**
+ * Check and emit sentinels for outbound HTTP response
+ *
+ * @param responseShapeDigest - Shape digest of response body
+ * @param statusCode - HTTP status code
+ * @param responseBody - Response body (for checking if empty)
+ * @param spanId - Span ID to attach invariant to (should be requestSpanId)
+ * @param parentSpanId - Parent span ID
+ */
+export declare function checkResponseSentinels(responseShapeDigest: ShapeDigest | null | undefined, statusCode: number, responseBody: string | null | undefined, spanId: string, parentSpanId: string | null): Promise<void>;
+//# sourceMappingURL=http-sentinels.d.ts.map

package/dist/http-sentinels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-sentinels.d.ts","sourceRoot":"","sources":["../src/http-sentinels.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE9D,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC;AAE1D;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAMhD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,aAAa,EAAE,MAAM;aACrB,QAAQ,EAAE,MAAM,GAAG,OAAO;gBAD1B,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GAAG,OAAO,EAC1C,OAAO,EAAE,MAAM;CAKlB;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,mBAAmB,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,EACnD,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACvC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GAAG,IAAI,GAC1B,OAAO,CAAC,IAAI,CAAC,CAoJf"}

package/dist/http-sentinels.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * HTTP Response Sentinels
+ *
+ * Automatic contract checking for outbound HTTP responses.
+ * Emits state.invariant events based on response characteristics.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SentinelViolationError = void 0;
+exports.getSentinelsMode = getSentinelsMode;
+exports.areSentinelsEnabled = areSentinelsEnabled;
+exports.isEnforceMode = isEnforceMode;
+exports.checkResponseSentinels = checkResponseSentinels;
+const invariants_1 = require("./invariants");
+/**
+ * Get sentinels mode from environment
+ */
+function getSentinelsMode() {
+    const mode = process.env.WRAITH_SENTINELS_MODE?.toLowerCase();
+    if (mode === "off" || mode === "observe" || mode === "enforce") {
+        return mode;
+    }
+    return "observe"; // default
+}
+/**
+ * Check if sentinels are enabled
+ */
+function areSentinelsEnabled() {
+    return getSentinelsMode() !== "off";
+}
+/**
+ * Check if sentinels are in enforce mode
+ */
+function isEnforceMode() {
+    return getSentinelsMode() === "enforce";
+}
+/**
+ * Custom error for sentinel violations in enforce mode
+ */
+class SentinelViolationError extends Error {
+    invariantName;
+    severity;
+    constructor(invariantName, severity, message) {
+        super(message);
+        this.invariantName = invariantName;
+        this.severity = severity;
+        this.name = "SentinelViolationError";
+    }
+}
+exports.SentinelViolationError = SentinelViolationError;
+/**
+ * Check and emit sentinels for outbound HTTP response
+ *
+ * @param responseShapeDigest - Shape digest of response body
+ * @param statusCode - HTTP status code
+ * @param responseBody - Response body (for checking if empty)
+ * @param spanId - Span ID to attach invariant to (should be requestSpanId)
+ * @param parentSpanId - Parent span ID
+ */
+async function checkResponseSentinels(responseShapeDigest, statusCode, responseBody, spanId, parentSpanId) {
+    if (process.env.DEBUG_HTTP_SENTINELS) {
+        console.log('[SENTINELS] checkResponseSentinels called:', {
+            hasShapeDigest: !!responseShapeDigest,
+            statusCode,
+            hasBody: !!responseBody,
+            spanId,
+            parentSpanId,
+        });
+    }
+    if (!areSentinelsEnabled()) {
+        if (process.env.DEBUG_HTTP_SENTINELS) {
+            console.log('[SENTINELS] Sentinels disabled');
+        }
+        return;
+    }
+    const enforceMode = isEnforceMode();
+    const errors = [];
+    if (process.env.DEBUG_HTTP_SENTINELS) {
+        console.log('[SENTINELS] Mode:', enforceMode ? 'enforce' : 'observe');
+    }
+    // Sentinel 1: Forbidden nulls in JSON response
+    if (responseShapeDigest &&
+        responseShapeDigest.kind === "json" &&
+        responseShapeDigest.nullPaths &&
+        responseShapeDigest.nullPaths.length > 0) {
+        const topNullPaths = responseShapeDigest.nullPaths.slice(0, 3);
+        if (process.env.DEBUG_HTTP_SENTINELS) {
+            console.log('[SENTINELS] Emitting forbidden_null invariant:', {
+                nullPaths: topNullPaths,
+                spanId,
+                parentSpanId,
+            });
+        }
+        try {
+            await (0, invariants_1.emitInvariant)({
+                name: "http.response.forbidden_null",
+                passed: false,
+                severity: "warn",
+                details: {
+                    paths: topNullPaths,
+                    expected: "no null values in response",
+                    observed: `null values found at: ${topNullPaths.join(", ")}`,
+                },
+            }, spanId, // Use the provided spanId (requestSpanId)
+            parentSpanId // Use the provided parentSpanId
+            );
+            if (process.env.DEBUG_HTTP_SENTINELS) {
+                console.log('[SENTINELS] Invariant emitted successfully');
+            }
+        }
+        catch (error) {
+            if (process.env.DEBUG_HTTP_SENTINELS) {
+                console.error('[SENTINELS] Failed to emit invariant:', error);
+            }
+            throw error;
+        }
+        if (enforceMode) {
+            errors.push(new SentinelViolationError("http.response.forbidden_null", "warn", `Response contains null values at: ${topNullPaths.join(", ")}`));
+        }
+    }
+    // Sentinel 2: Empty object response (status 200 but object with 0 keys)
+    if (statusCode === 200 &&
+        responseShapeDigest &&
+        responseShapeDigest.kind === "json" &&
+        responseShapeDigest.topLevelType === "object" &&
+        (!responseShapeDigest.keys || responseShapeDigest.keys.length === 0)) {
+        await (0, invariants_1.emitInvariant)({
+            name: "http.response.empty_object",
+            passed: false,
+            severity: "warn",
+            details: {
+                expected: "non-empty object or different response type",
+                observed: "empty object {}",
+            },
+        }, spanId, parentSpanId);
+    }
+    // Sentinel 3: Status 204 with non-empty body
+    if (statusCode === 204 && responseBody && responseBody.trim().length > 0) {
+        await (0, invariants_1.emitInvariant)({
+            name: "http.response.204_with_body",
+            passed: false,
+            severity: "warn",
+            details: {
+                expected: "no body for 204 No Content",
+                observed: `body has ${responseBody.length} bytes`,
+            },
+        }, spanId, parentSpanId);
+    }
+    // Sentinel 4: 5xx status codes
+    if (statusCode >= 500) {
+        await (0, invariants_1.emitInvariant)({
+            name: "http.response.5xx",
+            passed: false,
+            severity: "error",
+            details: {
+                expected: "status code < 500",
+                observed: `status code ${statusCode}`,
+            },
+        }, spanId, parentSpanId);
+        if (enforceMode) {
+            errors.push(new SentinelViolationError("http.response.5xx", "error", `Outbound HTTP call returned 5xx status: ${statusCode}`));
+        }
+    }
+    // In enforce mode, throw errors for critical violations
+    if (enforceMode && errors.length > 0) {
+        // Throw the first error (or combine if needed)
+        throw errors[0];
+    }
+}

package/dist/http-wrapper.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Set the current trace context (called by Fastify plugin)
+ * Note: This uses enterWith which sets the context for the current async execution
+ */
+export declare function setTraceContext(bundle: {
+    traceId: string;
+    writeEvent: (event: any) => Promise<void>;
+    writeBlob: (content: string | object) => Promise<string>;
+} | null, spanId: string | null): void;
+/**
+ * Get the current trace context
+ */
+export declare function getTraceContext(): {
+    bundle: {
+        traceId: string;
+        writeEvent: (event: any) => Promise<void>;
+        writeBlob: (content: string | object) => Promise<string>;
+    } | null;
+    spanId: string | null;
+};
+/**
+ * Wrap fetch/undici to capture outbound HTTP calls
+ */
+export declare function wrapFetch(originalFetch: typeof fetch): typeof fetch;
+//# sourceMappingURL=http-wrapper.d.ts.map

package/dist/http-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-wrapper.d.ts","sourceRoot":"","sources":["../src/http-wrapper.ts"],"names":[],"mappings":"AAwBA;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,EACvI,MAAM,EAAE,MAAM,GAAG,IAAI,QAQtB;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI;IACjC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;QAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IACxI,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAMA;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,aAAa,EAAE,OAAO,KAAK,GAAG,OAAO,KAAK,CA2dnE"}