stitchkit 0.80.1 → 0.82.0

package/dist/observability/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/observability/context.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAEjE,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,KAAK,EAAE,YAAY,CAAC;IACpB,4CAA4C;IAC5C,MAAM,EAAE,eAAe,CAAC;IACxB,iBAAiB;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;8EAC0E;IAC1E,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAChE;AAmBD,yDAAyD;AACzD,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE5E;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D;AAED,mEAAmE;AACnE,wBAAgB,UAAU,IAAI,MAAM,GAAG,SAAS,CAE/C;AAED,qDAAqD;AACrD,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGnD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAM5E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAG7E;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,IAAI,CAGP;AAED,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,EACvD,OAAO,GAAE,yBAA8B,GACtC,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAiBhD"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/observability/context.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnD,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAEjE,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,KAAK,EAAE,YAAY,CAAC;IACpB,4CAA4C;IAC5C,MAAM,EAAE,eAAe,CAAC;IACxB,iBAAiB;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;8EAC0E;IAC1E,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAChE;AAmBD,yDAAyD;AACzD,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE5E;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D;AAED,mEAAmE;AACnE,wBAAgB,UAAU,IAAI,MAAM,GAAG,SAAS,CAE/C;AAED,qDAAqD;AACrD,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGnD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAM7E;AAED,sGAAsG;AACtG,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC;AAEpE,MAAM,WAAW,2BAA2B;IAC1C,qEAAqE;IACrE,SAAS,CAAC,EAAE,kBAAkB,CAAC;CAChC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,OAAO,GAAE,2BAAgC,GACxC,IAAI,CAeN;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,IAAI,CAGP;AAED,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,EACvD,OAAO,GAAE,yBAA8B,GACtC,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAiBhD"}

package/dist/observability/index.d.ts

@@ -6,8 +6,9 @@
  * framework-owned HTTP completion plus canonical tool hooks into independent
  * sinks.
  */
-export { createObservability, type HttpRequestCompletion, type HttpRequestObserver, type Observability, type ObservabilityConfig, type RequestEventSinkConfig, type RequestObservabilityConfig, type SinkDrop, type SinkDropReason, type SinkError, } from './audit.js';
-export { getRequestContext, getTraceId, getUserId, type RequestContext, runWithRequestContext, setRequestDimensions, setRequestEndpoint, setRequestError, setRequestUser, type WrapRequestContextOptions, wrapInRequestContext, } from './context.js';
+export { createDimensionsProjector, createObservability, type DimensionsProjector, type DimensionsProjectorConfig, type HttpRequestCompletion, type HttpRequestObserver, type Observability, type ObservabilityConfig, type ProjectedDimensions, type RequestEventSinkConfig, type RequestObservabilityConfig, type SinkDrop, type SinkDropReason, type SinkError, } from './audit.js';
+export { type BoundedLoggerBounds, type BoundedLoggerOptions, createBoundedLogger, DEFAULT_REDACT_PATHS, } from './bounded-logger.js';
+export { type DimensionCollision, getRequestContext, getTraceId, getUserId, type RequestContext, runWithRequestContext, type SetRequestDimensionsOptions, setRequestDimensions, setRequestEndpoint, setRequestError, setRequestUser, type WrapRequestContextOptions, wrapInRequestContext, } from './context.js';
 export type { RequestEvent } from './event.js';
 export { type JsonValue, measureSize, redact, type SanitizeOptions, type SizeMeasure, sanitizePayload, truncatePreview, } from './sanitize.js';
 export { type ObservabilityDrainReport, ObservabilityDrainReportSchema, type ObservabilitySinkStatus, ObservabilitySinkStatusSchema, type ObservabilityStatus, ObservabilityStatusSchema, } from './status.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,mBAAmB,EACnB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,SAAS,GACf,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,KAAK,cAAc,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,KAAK,yBAAyB,EAC9B,oBAAoB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EACL,KAAK,SAAS,EACd,WAAW,EACX,MAAM,EACN,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,wBAAwB,EAC7B,8BAA8B,EAC9B,KAAK,uBAAuB,EAC5B,6BAA6B,EAC7B,KAAK,mBAAmB,EACxB,yBAAyB,GAC1B,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,yBAAyB,EACzB,mBAAmB,EACnB,KAAK,YAAY,GAClB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,SAAS,GACf,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,kBAAkB,EACvB,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,KAAK,cAAc,EACnB,qBAAqB,EACrB,KAAK,2BAA2B,EAChC,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,KAAK,yBAAyB,EAC9B,oBAAoB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EACL,KAAK,SAAS,EACd,WAAW,EACX,MAAM,EACN,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,wBAAwB,EAC7B,8BAA8B,EAC9B,KAAK,uBAAuB,EAC5B,6BAA6B,EAC7B,KAAK,mBAAmB,EACxB,yBAAyB,GAC1B,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,yBAAyB,EACzB,mBAAmB,EACnB,KAAK,YAAY,GAClB,MAAM,SAAS,CAAC"}

package/dist/observability/index.js

@@ -10,7 +10,7 @@ import {
   redact,
   sanitizePayload,
   truncatePreview
-} from "../index-dxjjv399.js";
+} from "../index-xbppf54a.js";
 import {
   getRequestContext,
   getTraceId,
@@ -21,25 +21,55 @@ import {
   setRequestError,
   setRequestUser,
   wrapInRequestContext
-} from "../index-dwf1f2ap.js";
+} from "../index-vsbzgd7b.js";
+import"../index-f9mb610r.js";
+import {
+  recordedErrorMessage
+} from "../index-7evdsyez.js";
+import"../index-2bxcmqkb.js";
+import"../index-6k1937bx.js";
+import"../index-0w9abg87.js";
 import {
   childSpan,
   createTraceContext,
   formatTraceparent,
   parseTraceparent,
-  recordedErrorMessage,
   resolvePropagationContext,
   resolveTraceContext
-} from "../index-fxz0v7vg.js";
-import"../index-y01f4223.js";
-import"../index-6k1937bx.js";
-import"../index-0w9abg87.js";
+} from "../index-zcgf3gqf.js";
 import"../index-kzfs85xp.js";
 import {
   isRecord
 } from "../index-77fekveh.js";
 
 // src/observability/audit.ts
+function writeProjectedDimensions(dimensions, collision) {
+  if (!dimensions)
+    return;
+  const materialized = {};
+  for (const [key, value] of Object.entries(dimensions)) {
+    if (value !== undefined)
+      materialized[key] = value;
+  }
+  if (Object.keys(materialized).length > 0) {
+    setRequestDimensions(materialized, { collision });
+  }
+}
+function createDimensionsProjector(config) {
+  const collision = config.collision ?? "overwrite";
+  return Object.freeze({
+    request(ctx, endpoint) {
+      writeProjectedDimensions(config.request?.(ctx, endpoint), collision);
+    },
+    result(ctx, result, endpoint) {
+      writeProjectedDimensions(config.result?.(ctx, result, endpoint), collision);
+      return result;
+    },
+    error(ctx, error, endpoint) {
+      writeProjectedDimensions(config.error?.(ctx, error, endpoint), collision);
+    }
+  });
+}
 function toolErrorMessage(result) {
   const { details, hint } = result;
   if (isRecord(details) && typeof details.message === "string") {
@@ -222,6 +252,103 @@ function createObservability(config) {
     }
   };
 }
+// src/observability/bounded-logger.ts
+var DEFAULT_REDACT_PATHS = Object.freeze([
+  "*.password",
+  "*.token",
+  "*.cookie",
+  "*.authorization",
+  "*.secret",
+  "**.password",
+  "**.token",
+  "**.cookie",
+  "**.authorization",
+  "**.secret"
+]);
+function asLogRecord(value) {
+  if (isRecord(value)) {
+    if (value._truncated === true) {
+      return {
+        message: "[truncated log entry]",
+        data: {
+          _truncated: true,
+          _originalBytes: value._originalBytes,
+          preview: value.preview
+        }
+      };
+    }
+    const message = typeof value.message === "string" ? value.message : "[sanitized log entry]";
+    const data = value.data;
+    return { message, ...isRecord(data) ? { data } : {} };
+  }
+  return { message: "[truncated log entry]", data: { entry: value } };
+}
+function byteLength(value) {
+  return measureSize(value).responseBytes;
+}
+function fitLogRecord(record, maxBytes) {
+  let message = record.message;
+  let data = record.data ? { ...record.data } : undefined;
+  while (byteLength({ message, data }) > maxBytes) {
+    if (typeof data?.preview === "string" && data.preview.length > 0) {
+      const points = Array.from(data.preview);
+      data.preview = points.length <= 1 ? "" : `${points.slice(0, points.length / 2).join("")}…`;
+      continue;
+    }
+    if (message.length > 16) {
+      const points = Array.from(message);
+      message = `${points.slice(0, points.length / 2).join("")}…`;
+      continue;
+    }
+    data = { _truncated: true };
+    message = "[truncated]";
+    break;
+  }
+  return { message, ...data && { data } };
+}
+function createBoundedLogger(options) {
+  const entryBytes = options.bounds?.entryBytes ?? 65536;
+  if (!Number.isSafeInteger(entryBytes) || entryBytes < 128) {
+    throw new TypeError("createBoundedLogger entryBytes must be an integer of at least 128");
+  }
+  const write = (level, message, data) => {
+    try {
+      const context = getRequestContext();
+      const enriched = {
+        ...data,
+        ...context?.trace.traceId !== undefined && { traceId: context.trace.traceId },
+        ...context?.trace.spanId !== undefined && { spanId: context.trace.spanId },
+        ...context?.userId !== undefined && { userId: context.userId },
+        ...context?.dimensions !== undefined && { dimensions: context.dimensions }
+      };
+      const value = sanitizePayload({ message, data: enriched }, {
+        sensitiveKeys: options.redact?.keys,
+        includeDefaultSensitiveKeys: true,
+        sensitivePaths: [
+          ...DEFAULT_REDACT_PATHS,
+          ...(options.redact?.paths ?? []).map((path) => `data.${path}`)
+        ],
+        sensitiveUrlPatterns: options.sensitiveUrlPatterns,
+        maxStringLength: options.bounds?.stringLength ?? 4000,
+        maxCollectionLength: options.bounds?.collectionLength ?? 100,
+        maxDepth: options.bounds?.depth ?? 6,
+        maxBytes: entryBytes
+      });
+      const sanitized = fitLogRecord(asLogRecord(value), entryBytes);
+      const result = options.sink[level](sanitized.message, sanitized.data);
+      if (result instanceof Promise)
+        result.catch(() => {
+          return;
+        });
+    } catch {}
+  };
+  return {
+    info: (message, data) => write("info", message, data),
+    warn: (message, data) => write("warn", message, data),
+    error: (message, data) => write("error", message, data),
+    debug: (message, data) => write("debug", message, data)
+  };
+}
 export {
   wrapInRequestContext,
   truncatePreview,
@@ -242,8 +369,11 @@ export {
   formatTraceparent,
   createTraceContext,
   createObservability,
+  createDimensionsProjector,
+  createBoundedLogger,
   childSpan,
   ObservabilityStatusSchema,
   ObservabilitySinkStatusSchema,
-  ObservabilityDrainReportSchema
+  ObservabilityDrainReportSchema,
+  DEFAULT_REDACT_PATHS
 };

package/dist/observability/sanitize.d.ts

@@ -11,10 +11,27 @@ export interface SanitizeOptions {
      * `X-Api-Key` are masked while `authorId` and `sessionCount` survive.
      */
     sensitiveKeys?: RegExp;
+    /** Augment, rather than replace, the built-in sensitive-key matcher. */
+    includeDefaultSensitiveKeys?: boolean;
+    /** Dot paths to mask. `*` matches one segment and `**` matches any suffix. */
+    sensitivePaths?: readonly string[];
+    /** Patterns whose matching portions are masked in every string, including messages. */
+    sensitiveUrlPatterns?: readonly RegExp[];
     /** Cap on the serialised payload — anything larger collapses to a preview. Default 16 KB. */
     maxBytes?: number;
     /** Recursion limit — deeper nesting collapses to a marker. Default 20. */
     maxDepth?: number;
+    /** Maximum UTF-16 string length before an explicit truncation marker. */
+    maxStringLength?: number;
+    /** Maximum members retained from an array, map, set, or object. */
+    maxCollectionLength?: number;
+    /**
+     * Maximum values visited in one walk. The ancestor check stops cycles, not
+     * a shared acyclic subtree reached from many parents — a diamond-shaped
+     * object of a few hundred keys can mean billions of visits — so past this
+     * budget the rest collapses to a marker. Default 20 000.
+     */
+    maxNodes?: number;
 }
 /** The result of `measureSize`. */
 export interface SizeMeasure {

package/dist/observability/sanitize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/observability/sanitize.ts"],"names":[],"mappings":"AAOA,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,8BAA8B;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,cAAc,CAAC,EAAE,IAAI,CAAC;CACvB;AAwED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,eAAoB,GAAG,SAAS,CAsG/E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,SAAoB,GAAG,SAAS,CAgBzF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,eAAoB,GAC5B,SAAS,GAAG,IAAI,CAOlB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAqBvD"}
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/observability/sanitize.ts"],"names":[],"mappings":"AAOA,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC,8EAA8E;IAC9E,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,uFAAuF;IACvF,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,8BAA8B;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,cAAc,CAAC,EAAE,IAAI,CAAC;CACvB;AAyED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,eAAoB,GAAG,SAAS,CAiM/E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,SAAoB,GAAG,SAAS,CAgBzF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,eAAoB,GAC5B,SAAS,GAAG,IAAI,CAOlB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAqBvD"}

package/dist/primitives.js

@@ -1,4 +1,4 @@
-import"./index-y01f4223.js";
+import"./index-2bxcmqkb.js";
 import {
   ManagedFileRefSchema
 } from "./index-6k1937bx.js";

package/dist/react/query-client.d.ts

@@ -0,0 +1,33 @@
+import { type MutationCacheConfig, QueryClient, type QueryClientConfig } from '@tanstack/react-query';
+export interface ApiErrorRetryConfig {
+    /** Maximum retries after the initial query attempt. */
+    attempts?: number;
+    /** Application codes which are never retried. */
+    never?: readonly string[];
+    /** Inclusive HTTP status ranges which are retryable. */
+    statusRanges?: readonly (readonly [from: number, to: number])[];
+    /** Whether an unclassified non-API error is treated as a network failure. */
+    network?: boolean;
+}
+/** Build a React Query retry predicate from Stitchkit's cross-bundle API error model. */
+export declare function apiErrorRetry(config?: ApiErrorRetryConfig): (failureCount: number, error: unknown) => boolean;
+export type QueryClientServerCache = (factory: () => QueryClient) => () => QueryClient;
+export type QueryRetryValue = NonNullable<NonNullable<QueryClientConfig['defaultOptions']>['queries']>['retry'];
+export interface QueryClientFactoryConfig {
+    /** Full TanStack QueryClient config; defaults are merged by section. */
+    queryClient?: QueryClientConfig;
+    /** Query retry policy; mutations remain non-retryable unless explicitly overridden. */
+    retry?: ApiErrorRetryConfig | QueryRetryValue;
+    /** Optional shared mutation error observer. */
+    onMutationError?: MutationCacheConfig['onError'];
+    /** Request-local cache adapter, normally React's `cache`. */
+    serverCache?: QueryClientServerCache;
+    /** Deterministic environment seam; defaults to TanStack's environment manager. */
+    server?: () => boolean;
+}
+/**
+ * Create one request-local server QueryClient and one factory-local browser singleton.
+ * No server cache is invented: the host supplies React `cache` (or an equivalent adapter).
+ */
+export declare function createQueryClientFactory(config?: QueryClientFactoryConfig): () => QueryClient;
+//# sourceMappingURL=query-client.d.ts.map

package/dist/react/query-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-client.d.ts","sourceRoot":"","sources":["../../src/react/query-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,mBAAmB,EACxB,WAAW,EACX,KAAK,iBAAiB,EACvB,MAAM,uBAAuB,CAAC;AAG/B,MAAM,WAAW,mBAAmB;IAClC,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,wDAAwD;IACxD,YAAY,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;IAChE,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AASD,yFAAyF;AACzF,wBAAgB,aAAa,CAAC,MAAM,GAAE,mBAAwB,kBAuBtC,MAAM,SAAS,OAAO,KAAG,OAAO,CAQvD;AAED,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,EAAE,MAAM,WAAW,KAAK,MAAM,WAAW,CAAC;AACvF,MAAM,MAAM,eAAe,GAAG,WAAW,CACvC,WAAW,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS,CAAC,CAC5D,CAAC,OAAO,CAAC,CAAC;AAEX,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,uFAAuF;IACvF,KAAK,CAAC,EAAE,mBAAmB,GAAG,eAAe,CAAC;IAC9C,+CAA+C;IAC/C,eAAe,CAAC,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;IACjD,6DAA6D;IAC7D,WAAW,CAAC,EAAE,sBAAsB,CAAC;IACrC,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,GAAE,wBAA6B,GACpC,MAAM,WAAW,CAgDnB"}

package/dist/react.d.ts

@@ -1,4 +1,5 @@
 export { type CacheBridge, type CacheBridgeConfig, type CacheBridgeContext, type CacheBridgeHandler, type CacheBridgeHandlers, type CacheBridgeSocket, createCacheBridge, createRealtimeCacheBridge, type RealtimeCacheBridgeConfig, } from './react/cache-bridge.js';
 export { type CursorQueryConfig, createCursorQuery } from './react/cursor-query.js';
 export { createEntityCacheHandlers, type DeletedPayload, type EntityCacheConfig, type EntityCacheEvent, type EntityCacheHandlers, type EntityCacheKey, type EntityCacheListConfig, type EntityCacheListShape, type EntityCacheMembership, type EntityCacheMembershipPolicy, type EntityCacheTotalDeltaInput, type EntityCacheTotalPolicy, } from './react/entity-cache.js';
+export { type ApiErrorRetryConfig, apiErrorRetry, createQueryClientFactory, type QueryClientFactoryConfig, type QueryClientServerCache, type QueryRetryValue, } from './react/query-client.js';
 //# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,iBAAiB,EACjB,yBAAyB,EACzB,KAAK,yBAAyB,GAC/B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EACL,yBAAyB,EACzB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,GAC5B,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,iBAAiB,EACjB,yBAAyB,EACzB,KAAK,yBAAyB,GAC/B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EACL,yBAAyB,EACzB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,GAC5B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,mBAAmB,EACxB,aAAa,EACb,wBAAwB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,KAAK,eAAe,GACrB,MAAM,sBAAsB,CAAC"}

package/dist/react.js

@@ -1,3 +1,8 @@
+import {
+  ApiError,
+  isAbortLikeError
+} from "./index-3xwxfj4z.js";
+import"./index-zcgf3gqf.js";
 import {
   isRecord
 } from "./index-77fekveh.js";
@@ -313,9 +318,86 @@ function hasStringId(value) {
 function idOf(payload, getId) {
   return hasStringId(payload) ? payload.id : getId(payload);
 }
+// src/react/query-client.ts
+import {
+  defaultShouldDehydrateQuery,
+  environmentManager,
+  MutationCache,
+  QueryClient
+} from "@tanstack/react-query";
+var DEFAULT_NEVER_RETRY = [
+  "UNAUTHORIZED",
+  "FORBIDDEN",
+  "VALIDATION_ERROR",
+  "REQUEST_ABORTED"
+];
+function apiErrorRetry(config = {}) {
+  const attempts = config.attempts ?? 1;
+  if (!Number.isSafeInteger(attempts) || attempts < 0) {
+    throw new Error(`apiErrorRetry attempts must be a non-negative safe integer, received ${attempts}`);
+  }
+  const never = new Set(config.never ?? DEFAULT_NEVER_RETRY);
+  const statusRanges = config.statusRanges ?? [[500, 599]];
+  for (const [from, to] of statusRanges) {
+    if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to) || from < 100 || to > 599 || from > to) {
+      throw new Error(`apiErrorRetry status range must be an inclusive HTTP range, received ${from}..${to}`);
+    }
+  }
+  return (failureCount, error) => {
+    if (failureCount >= attempts)
+      return false;
+    if (isAbortLikeError(error))
+      return false;
+    if (!ApiError.is(error))
+      return config.network ?? true;
+    if (never.has(error.code))
+      return false;
+    if (error.status === 0)
+      return config.network ?? true;
+    return statusRanges.some(([from, to]) => error.status >= from && error.status <= to);
+  };
+}
+function createQueryClientFactory(config = {}) {
+  const supplied = config.queryClient ?? {};
+  if (config.onMutationError && supplied.mutationCache) {
+    throw new Error("createQueryClientFactory cannot combine onMutationError with queryClient.mutationCache");
+  }
+  const suppliedDefaults = supplied.defaultOptions ?? {};
+  const queryRetry = typeof config.retry === "object" || config.retry === undefined ? apiErrorRetry(config.retry) : config.retry;
+  const create = () => new QueryClient({
+    ...supplied,
+    ...config.onMutationError ? { mutationCache: new MutationCache({ onError: config.onMutationError }) } : {},
+    defaultOptions: {
+      ...suppliedDefaults,
+      queries: {
+        ...suppliedDefaults.queries,
+        retry: suppliedDefaults.queries?.retry ?? queryRetry
+      },
+      mutations: {
+        ...suppliedDefaults.mutations,
+        retry: suppliedDefaults.mutations?.retry ?? false
+      },
+      dehydrate: {
+        ...suppliedDefaults.dehydrate,
+        shouldDehydrateQuery: suppliedDefaults.dehydrate?.shouldDehydrateQuery ?? ((query) => defaultShouldDehydrateQuery(query) || query.state.status === "pending")
+      }
+    }
+  });
+  const getServer = config.serverCache ? config.serverCache(create) : create;
+  const isServer = config.server ?? (() => environmentManager.isServer());
+  let browserClient;
+  return () => {
+    if (isServer())
+      return getServer();
+    browserClient ??= create();
+    return browserClient;
+  };
+}
 export {
   createRealtimeCacheBridge,
+  createQueryClientFactory,
   createEntityCacheHandlers,
   createCursorQuery,
-  createCacheBridge
+  createCacheBridge,
+  apiErrorRetry
 };

package/dist/realtime/registry.d.ts

@@ -0,0 +1,93 @@
+import type { RealtimeServer } from '../server/realtime.js';
+import type { RealtimeEmitArguments, RealtimeEventRegistry } from './contract.js';
+declare const authorizedRoom: unique symbol;
+/**
+ * A room reference minted by the registry. The token proves the name went
+ * through *this* registry — a string from elsewhere cannot be emitted to by
+ * accident. Whether a given socket may be in the room is decided per socket
+ * by `rooms(identity)` at connect time and checked again on `join`.
+ */
+export interface AuthorizedSocketRoom {
+    readonly name: string;
+    readonly [authorizedRoom]: true;
+}
+export interface SocketRegistryConnection<TOutbound extends RealtimeEventRegistry, TIdentity> {
+    readonly raw: {
+        readonly id: string;
+        readonly data: TIdentity;
+        join(room: string): void | Promise<void>;
+        leave(room: string): void | Promise<void>;
+        on(event: 'disconnect', handler: () => void): unknown;
+        off?(event: 'disconnect', handler: () => void): unknown;
+    };
+    readonly events: {
+        emit<TEvent extends keyof TOutbound & string>(event: TEvent, ...args: RealtimeEmitArguments<TOutbound[TEvent]>): boolean;
+    };
+}
+export interface SocketRegistryServer<TOutbound extends RealtimeEventRegistry, TIdentity> {
+    onConnection(handler: (connection: SocketRegistryConnection<TOutbound, TIdentity>) => void | Promise<void>): () => void;
+}
+export type SocketReplayFrame<TOutbound extends RealtimeEventRegistry> = {
+    [TEvent in keyof TOutbound & string]: {
+        readonly event: TEvent;
+        readonly args: RealtimeEmitArguments<TOutbound[TEvent]>;
+    };
+}[keyof TOutbound & string];
+export interface SocketRegistrySnapshot<TIdentity> {
+    readonly revision: number;
+    readonly connections: readonly {
+        readonly socketId: string;
+        readonly identity: TIdentity;
+        readonly rooms: readonly string[];
+        readonly replaying: boolean;
+    }[];
+    readonly rooms: Readonly<Record<string, readonly string[]>>;
+}
+export interface SocketRegistryOptions<TOutbound extends RealtimeEventRegistry, TIdentity> {
+    /** Rooms this already-authenticated identity may join. */
+    rooms(identity: TIdentity): Iterable<string> | Promise<Iterable<string>>;
+    /**
+     * Produce a coherent replay generation. Frames are captured before any are
+     * emitted; live frames are buffered until the generation is complete.
+     */
+    replay?(context: {
+        readonly identity: TIdentity;
+        readonly rooms: readonly AuthorizedSocketRoom[];
+        readonly revision: unknown;
+    }): readonly SocketReplayFrame<TOutbound>[] | Promise<readonly SocketReplayFrame<TOutbound>[]>;
+    /** Stable application revision surrounding replay generation. */
+    revision?(): unknown | Promise<unknown>;
+    /**
+     * Called when a coherent replay could not be delivered: the revision kept
+     * moving for `replayAttempts` tries, or more than `maxBufferedFrames` live
+     * frames arrived while one snapshot was open. The socket is still a member
+     * of its rooms; the application decides what a resync means for it.
+     */
+    onResyncRequired?(socketId: string, identity: TIdentity): void | Promise<void>;
+    replayAttempts?: number;
+    /**
+     * Live frames held per socket while its replay snapshot is open. Beyond
+     * this the attempt is abandoned rather than delivering a history with a
+     * hole — the buffer never grows without bound. Default `1_000`.
+     */
+    maxBufferedFrames?: number;
+}
+export interface SocketRegistry<TOutbound extends RealtimeEventRegistry, TIdentity> {
+    /** The token for a room name; an empty room is a valid `emitTo` target (0 recipients). */
+    room(name: string): AuthorizedSocketRoom;
+    join(socketId: string, room: AuthorizedSocketRoom): Promise<void>;
+    leave(socketId: string, room: AuthorizedSocketRoom): Promise<void>;
+    emitTo<TEvent extends keyof TOutbound & string>(room: AuthorizedSocketRoom, event: TEvent, ...args: RealtimeEmitArguments<TOutbound[TEvent]>): number;
+    resync(socketId: string): Promise<boolean>;
+    snapshot(): SocketRegistrySnapshot<TIdentity>;
+    unbind(): Promise<void>;
+}
+/**
+ * Add authorized membership and coherent replay to an existing authenticated
+ * realtime server. Validation and transport emission stay owned by the
+ * connection supplied by `bindRealtimeServer`.
+ */
+export declare function bindSocketRegistry<TOutbound extends RealtimeEventRegistry, TInbound extends RealtimeEventRegistry, TIdentity>(server: RealtimeServer<TOutbound, TInbound, TIdentity>, options: SocketRegistryOptions<TOutbound, TIdentity>): SocketRegistry<TOutbound, TIdentity>;
+export declare function bindSocketRegistry<TOutbound extends RealtimeEventRegistry, TIdentity>(server: SocketRegistryServer<TOutbound, TIdentity>, options: SocketRegistryOptions<TOutbound, TIdentity>): SocketRegistry<TOutbound, TIdentity>;
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/realtime/registry.d.ts.map

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

package/dist/release/header.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The response header that names the frontend build the server considers
+ * current. Set on every response of a handler configured with a release
+ * marker — success, error, raw route — so a client learns about a release
+ * from whatever it was already asking, with no socket and no polling of its
+ * own. Exposed through CORS by default, like `X-Request-Id`.
+ */
+export declare const RELEASE_HEADER = "X-Build-Id";
+//# sourceMappingURL=header.d.ts.map

package/dist/release/header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header.d.ts","sourceRoot":"","sources":["../../src/release/header.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,eAAe,CAAC"}

package/dist/release/marker.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The server's knowledge of which frontend build is current.
+ *
+ * `read` is the application's: a file the release wrote (`.next/BUILD_ID` of
+ * the *active* release root, not the process's own cwd — a frontend-only
+ * release leaves the backend in an older immutable root), an environment
+ * variable, anything. It returns `null` where there is no release — a dev
+ * server under HMR — and then the marker stays silent: no header, no event.
+ *
+ * `refresh()` is the one operation with a side effect: it re-reads, and if
+ * the answer changed, tells every subscriber. A deploy signal calls it; so
+ * does every socket connection, so a broadcast the process missed while it
+ * was down is repaired by the next client that connects. → ADR 0167.
+ */
+export interface ReleaseMarker {
+    /** The last build id read, or `null` when there is no release to name. */
+    current(): string | null;
+    /** Re-read; `changed` when the id differs from the last one seen. */
+    refresh(): ReleaseRefresh;
+    /** Hear every change; returns the unsubscribe. */
+    subscribe(listener: (buildId: string | null) => void): () => void;
+}
+export interface ReleaseRefresh {
+    changed: boolean;
+    buildId: string | null;
+}
+export interface ReleaseMarkerConfig {
+    /** The current build id, or `null` when there is none. A throw counts as `null`. */
+    read: () => string | null;
+    /**
+     * Hear a `read` that threw or returned something that is not a build id, and
+     * a subscriber that threw — the marker itself never does, because it is
+     * called from a signal handler and a socket's `connection` event, where an
+     * escaped exception ends the process or the connect.
+     */
+    onError?: (error: unknown) => void;
+}
+export declare function createReleaseMarker(config: ReleaseMarkerConfig): ReleaseMarker;
+//# sourceMappingURL=marker.d.ts.map

package/dist/release/marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker.d.ts","sourceRoot":"","sources":["../../src/release/marker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,OAAO,IAAI,MAAM,GAAG,IAAI,CAAC;IACzB,qEAAqE;IACrE,OAAO,IAAI,cAAc,CAAC;IAC1B,kDAAkD;IAClD,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACnE;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,oFAAoF;IACpF,IAAI,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAUD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,aAAa,CAqD9E"}

package/dist/release/socket.d.ts

@@ -0,0 +1,57 @@
+import type { ReleaseMarker } from './marker.js';
+import type { ReleaseWatcher } from './watcher.js';
+/**
+ * The little of a Socket.IO server this binding uses — structural, no peer
+ * import.
+ *
+ * `emit` is declared over `string` because the event name is configurable. A
+ * **typed** `Server<ClientToServer, ServerToClient>` narrows its own `emit` to
+ * the names in its map, so it satisfies this only once that map declares the
+ * event — `release: (payload: { buildId: string | null }) => void`, or whatever
+ * `options.event` renames it to. Until then the compiler reports a structural
+ * mismatch between two large socket.io types, which reads like a defect in this
+ * binding and is a missing line in the application's event map. Adding it is
+ * step 3 of the guide's adoption list for exactly this reason: the same
+ * declaration is what lets the application's own `on` know the event.
+ */
+export interface ReleaseSocketServer {
+    on(event: 'connection', handler: (socket: ReleaseSocketEmitter) => void): unknown;
+    emit(event: string, payload: {
+        buildId: string | null;
+    }): unknown;
+}
+export interface ReleaseSocketEmitter {
+    emit(event: string, payload: {
+        buildId: string | null;
+    }): unknown;
+}
+/**
+ * The little of a Socket.IO client this feed uses. Two dialects: a raw
+ * socket.io client subscribes with `on` and unsubscribes with `off`; the
+ * stitchkit client's `on` returns the unsubscribe itself. Both fit.
+ */
+export interface ReleaseSocketListener {
+    on(event: string, handler: (payload: {
+        buildId: string | null;
+    }) => void): unknown;
+    off?(event: string, handler: (payload: {
+        buildId: string | null;
+    }) => void): unknown;
+}
+export interface ReleaseSocketOptions {
+    /** Event name on the wire. Default `release`. */
+    event?: string;
+}
+/**
+ * Tell every socket which build is current: each connection on arrival, and
+ * everyone when the marker changes. A connection first `refresh()`es the
+ * marker — the safety net: a deploy signal the process missed while it was
+ * down is repaired by the next client that connects, because that connect
+ * re-reads the file.
+ */
+export declare function bindReleaseToSocketServer(io: ReleaseSocketServer, marker: ReleaseMarker, options?: ReleaseSocketOptions & {
+    refreshOnConnection?: boolean;
+}): () => void;
+/** Feed a watcher from the socket event the server binding emits. */
+export declare function observeReleaseFromSocket(socket: ReleaseSocketListener, watcher: ReleaseWatcher, options?: ReleaseSocketOptions): () => void;
+//# sourceMappingURL=socket.d.ts.map

package/dist/release/socket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../../src/release/socket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,mBAAmB;IAClC,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC;IAClF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC;CACnE;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC;CACnE;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAAK,IAAI,GAAG,OAAO,CAAC;IACnF,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAAK,IAAI,GAAG,OAAO,CAAC;CACtF;AAED,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,mBAAmB,EACvB,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,oBAAoB,GAAG;IAAE,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAAO,GACrE,MAAM,IAAI,CAcZ;AAED,qEAAqE;AACrE,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,oBAAyB,GACjC,MAAM,IAAI,CAQZ"}