@classytic/arc 2.17.1 → 2.18.0

package/dist/{mcpPlugin-C6FViZXw.mjs → mcpPlugin-BrepZ0cV.mjs}

@@ -1,13 +1,13 @@
 import { p as isArcError, t as ArcError } from "./errors-j4aJm1Wg.mjs";
-import { t as BaseController } from "./BaseController-CgHomZ4d.mjs";
+import { t as BaseController } from "./BaseController-DPwe89qs.mjs";
 import { L as normalizePermissionResult } from "./permissions-B1Qy55fg.mjs";
 import { t as executePipeline } from "./pipe-DiCyvyPN.mjs";
-import { f as resolvePipelineSteps } from "./routerShared-nCyJGOKX.mjs";
+import { f as resolvePipelineSteps } from "./routerShared-Dl0A77Ba.mjs";
 import { r as validateAggregations } from "./validate-DFIP2VrM.mjs";
 import { n as executeAggregation } from "./buildHandler-C_SkBNF3.mjs";
 import { t as pluralize } from "./pluralize-B9M8xvy-.mjs";
 import { t as resolveActionPermission } from "./actionPermissions-Bjmvn7Eb.mjs";
-import { i as shouldRejectAdditionalProperties, r as schemaIRToZodShape, t as normalizeSchemaIR } from "./schemaIR-DAOvBWgT.mjs";
+import { i as shouldRejectAdditionalProperties, r as schemaIRToZodShape, t as normalizeSchemaIR } from "./schemaIR-Bk6Tns82.mjs";
 import { createHash, randomUUID } from "node:crypto";
 import { isHttpError, toErrorContract } from "@classytic/repo-core/errors";
 import fp from "fastify-plugin";

package/dist/{openapi-DKDs9NfD.mjs → openapi-CLZx9bwS.mjs}

@@ -2,7 +2,7 @@ import { t as getUserRoles } from "./types-DV9WDfeg.mjs";
 import { n as convertRouteSchema } from "./schemaConverter-De34B1ZG.mjs";
 import { t as pluralize } from "./pluralize-B9M8xvy-.mjs";
 import { t as resolveActionPermission } from "./actionPermissions-Bjmvn7Eb.mjs";
-import { t as buildActionBodySchema } from "./createActionRouter-BHUMb1-y.mjs";
+import { t as buildActionBodySchema } from "./createActionRouter-CRaIwB5S.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/openapi/canonical-schemas.ts
 /**

package/dist/plugins/index.d.mts

@@ -2,7 +2,7 @@ import { Kt as AnyRecord, Q as MiddlewareConfig, dt as RouteDefinition, mt as Ro
 import { a as arcCorePlugin, i as _default, n as ArcCorePluginOptions, r as PluginMeta, t as ArcCore } from "../fastify-augmentation-7LIR0nDv.mjs";
 import { _ as HealthOptions, a as MetricsCollector, c as metricsPlugin, d as ssePlugin, f as CachingOptions, g as HealthCheck, h as cachingPlugin, i as MetricEntry, l as SSEOptions, m as _default$1, n as _default$7, o as MetricsOptions, p as CachingRule, r as versioningPlugin, s as _default$4, t as VersioningOptions, u as _default$6, v as _default$3, y as healthPlugin } from "../versioning-5H4930tj.mjs";
 import { i as errorHandlerPlugin, n as ErrorMapper, r as defaultIsDuplicateKeyError, t as ErrorHandlerOptions } from "../errorHandler-DuqTqeqn.mjs";
-import { t as TracingOptions } from "../tracing-bRqqUxFO.mjs";
+import { t as TracingOptions } from "../tracing-BYQ3hsbM.mjs";
 import * as _$node_stream0 from "node:stream";
 import { PaginatedResult } from "@classytic/repo-core/pagination";
 import { FastifyInstance, FastifyPluginAsync } from "fastify";
@@ -121,11 +121,25 @@ interface RequestIdOptions {
   generator?: () => string;
   /** Whether to set response header (default: true) */
   setResponseHeader?: boolean;
+  /**
+   * Whether to read and forward W3C Trace Context headers (`traceparent`,
+   * `tracestate`). When enabled, valid incoming headers are stored in
+   * `request.traceContext` and echoed in the response. Default: `true`.
+   */
+  propagateTraceContext?: boolean;
 }
 declare module "fastify" {
   interface FastifyRequest {
     /** Unique request identifier for tracing */
     requestId: string;
+    /**
+     * W3C Trace Context parsed from the incoming `traceparent` header.
+     * `undefined` when the header was absent or malformed.
+     */
+    traceContext?: {
+      traceparent: string;
+      tracestate?: string;
+    };
   }
 }
 declare const requestIdPlugin: FastifyPluginAsync<RequestIdOptions>;

package/dist/plugins/index.mjs

@@ -1,6 +1,6 @@
 import { p as MUTATION_OPERATIONS } from "../constants-TrJVIJl0.mjs";
 import { c as getOrgId } from "../types-Bi0r0vjG.mjs";
-import { t as requestContext } from "../requestContext-SSaaTgW8.mjs";
+import { n as requestContext } from "../requestContext-DDLS3NVU.mjs";
 import { t as hasEvents } from "../typeGuards-BzkXkvVv.mjs";
 import { t as HookSystem } from "../HookSystem-Cmf7-Etp.mjs";
 import { t as ResourceRegistry } from "../ResourceRegistry-CzSzVK1m.mjs";
@@ -34,8 +34,14 @@ const arcCorePlugin = async (fastify, opts = {}) => {
 	fastify.addHook("preHandler", (request, _reply, done) => {
 		const store = requestContext.get();
 		if (store) {
-			store.user = request.user ?? null;
+			const req = request;
+			store.user = req.user ?? null;
 			store.organizationId = request.scope?.kind === "member" ? request.scope.organizationId : request.scope?.kind === "elevated" ? request.scope.organizationId : void 0;
+			const tc = req.traceContext;
+			if (tc?.traceparent) {
+				store.traceparent = tc.traceparent;
+				if (tc.tracestate) store.tracestate = tc.tracestate;
+			}
 		}
 		done();
 	});
@@ -410,9 +416,28 @@ var health_default = fp(healthPlugin, {
 *   console.log(request.id); // UUID
 * });
 */
+/** W3C traceparent format: `version-traceid-parentid-flags` */
+const TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/i;
+/** W3C spec: version ff is reserved and invalid; trace/parent IDs must not be all zeros */
+const TRACEID_ZEROS = "0".repeat(32);
+const PARENTID_ZEROS = "0".repeat(16);
+/** tracestate: printable ASCII, <= 512 bytes */
+const TRACESTATE_MAX = 512;
+function isValidTraceparent(tp) {
+	const m = TRACEPARENT_RE.exec(tp);
+	if (!m) return false;
+	const version = m[1] ?? "";
+	const traceId = m[2] ?? "";
+	const parentId = m[3] ?? "";
+	if (version.toLowerCase() === "ff") return false;
+	if (traceId.toLowerCase() === TRACEID_ZEROS) return false;
+	if (parentId.toLowerCase() === PARENTID_ZEROS) return false;
+	return true;
+}
 const requestIdPlugin = async (fastify, opts = {}) => {
-	const { header = "x-request-id", generator = randomUUID, setResponseHeader = true } = opts;
+	const { header = "x-request-id", generator = randomUUID, setResponseHeader = true, propagateTraceContext = true } = opts;
 	if (!fastify.hasRequestDecorator("requestId")) fastify.decorateRequest("requestId", "");
+	if (!fastify.hasRequestDecorator("traceContext")) fastify.decorateRequest("traceContext", void 0);
 	fastify.addHook("onRequest", async (request, reply) => {
 		const incomingId = request.headers[header];
 		const sanitized = typeof incomingId === "string" ? incomingId.trim() : "";
@@ -420,6 +445,22 @@ const requestIdPlugin = async (fastify, opts = {}) => {
 		request.id = requestId;
 		request.requestId = requestId;
 		if (setResponseHeader) reply.header(header, requestId);
+		if (propagateTraceContext) {
+			const rawTraceparent = request.headers["traceparent"];
+			const rawTracestate = request.headers["tracestate"];
+			if (typeof rawTraceparent === "string") {
+				const tp = rawTraceparent.trim();
+				if (isValidTraceparent(tp)) {
+					const ts = typeof rawTracestate === "string" && rawTracestate.length > 0 && rawTracestate.length <= TRACESTATE_MAX ? rawTracestate : void 0;
+					request.traceContext = {
+						traceparent: tp,
+						...ts ? { tracestate: ts } : {}
+					};
+					reply.header("traceparent", tp);
+					if (ts) reply.header("tracestate", ts);
+				}
+			}
+		}
 	});
 	fastify.log?.debug?.("Request ID plugin registered");
 };

package/dist/plugins/tracing-entry.d.mts

@@ -1,2 +1,2 @@
-import { a as traced, i as isTracingAvailable, n as _default, r as createSpan, t as TracingOptions } from "../tracing-bRqqUxFO.mjs";
+import { a as traced, i as isTracingAvailable, n as _default, r as createSpan, t as TracingOptions } from "../tracing-BYQ3hsbM.mjs";
 export { type TracingOptions, createSpan, isTracingAvailable, traced, _default as tracingPlugin };

package/dist/plugins/tracing-entry.mjs

@@ -58,7 +58,7 @@ try {
 function createTracerProvider(options) {
 	if (!isAvailable || !NodeTracerProvider || !BatchSpanProcessor || !OTLPTraceExporter) return null;
 	const { serviceName = "@classytic/arc", serviceVersion, exporterUrl = "http://localhost:4318/v1/traces" } = options;
-	const resolvedVersion = serviceVersion ?? "2.17.1";
+	const resolvedVersion = serviceVersion ?? "2.18.0";
 	const exporter = new OTLPTraceExporter({ url: exporterUrl });
 	const provider = new NodeTracerProvider({ resource: { attributes: {
 		"service.name": serviceName,

package/dist/presets/filesUpload.d.mts

@@ -1,7 +1,7 @@
 import { rt as PresetResult } from "../index-C1JSBan-.mjs";
 import { i as RequestScope } from "../types-CfapW2t8.mjs";
 import { c as PermissionCheck } from "../fields-DqZLp5d6.mjs";
-import { a as StorageReadResult, i as StorageReadRange, n as StorageContext, o as StorageUploadInput, r as StorageFile, t as Storage } from "../storage-HcAgP5Ni.mjs";
+import { a as StorageReadResult, i as StorageReadRange, n as StorageContext, o as StorageUploadInput, r as StorageFile, t as Storage } from "../storage-BFmamN5m.mjs";
 
 //#region src/presets/filesUpload.d.ts
 interface FilesUploadPresetRoutes {

package/dist/pushref-registry-Bq_-EVsC.d.mts

@@ -0,0 +1,435 @@
+//#region src/integrations/websocket/dead-queue.d.ts
+/**
+ * Per-connection dead queue — ring buffer holding the last N outbound
+ * critical messages so a reconnecting client can RESUME and have any
+ * messages missed during the disconnect replayed in order.
+ *
+ * Modelled on Mattermost's `deadQueueSize = 128` ring (web_conn.go). Only
+ * `send()`-class (critical, ordered) frames go in; `sendRealtime()` frames
+ * are by definition droppable so replaying them on resume gives the user
+ * a stale snapshot — better to wait for the next live update.
+ *
+ * Each entry carries the monotonic sequence number assigned by the
+ * envelope wrapper. Resume semantics:
+ *
+ *   client → { type: 'resume', lastSeq: N, pushRef: '...' }
+ *   server →   if (N+1 is still in the ring): replay (N+1..tail)
+ *              else:                          { type: 'resume_gap' }
+ *
+ * The gap response forces the host to do a fresh sync — losing 128+
+ * messages mid-disconnect is rare enough that a re-fetch is acceptable
+ * UX; trying to "patch over" a lost message silently is the bad path.
+ */
+interface DeadQueueEntry {
+  seq: number;
+  /** Already-serialized envelope JSON ready to write to the socket. */
+  payload: string;
+}
+declare class DeadQueue {
+  private buffer;
+  private head;
+  private count;
+  private capacity;
+  constructor(capacity?: number);
+  push(entry: DeadQueueEntry): void;
+  /**
+   * Return entries with seq strictly greater than `lastSeq`, in order,
+   * OR `null` if the gap is too large (entry with seq = lastSeq + 1 has
+   * already been evicted from the ring — caller should signal `resume_gap`).
+   */
+  drainAfter(lastSeq: number): DeadQueueEntry[] | null;
+  size(): number;
+  /** Highest seq currently in the ring (or 0 if empty). */
+  highestSeq(): number;
+  clear(): void;
+  /**
+   * Return all entries in chronological order. Used by the registry's
+   * `persist()` to flush the live ring to the external store. Allocates
+   * a fresh array — caller owns it (mutations don't affect the ring).
+   */
+  snapshot(): DeadQueueEntry[];
+}
+//#endregion
+//#region src/integrations/websocket/envelope.d.ts
+/**
+ * Per-pushRef envelope state. One instance per logical session — when
+ * a client reconnects under the same pushRef within TTL, the same
+ * EnvelopeWriter is rehydrated so its `nextSeq` counter and dead queue
+ * round-trip across reconnects.
+ *
+ * The constructor accepts `{ nextSeq }` for the rehydration path —
+ * `PushRefRegistry.hydrateEnvelope` passes the persisted counter so
+ * the next wrap() picks up where the previous socket left off (no
+ * seq collisions, no replay gaps).
+ */
+declare class EnvelopeWriter {
+  private nextSeq;
+  private dead;
+  constructor(deadQueue: DeadQueue, opts?: {
+    nextSeq?: number;
+  });
+  /**
+   * Wrap a payload, assign next seq, persist to dead queue. Returns the
+   * JSON-stringified envelope ready for the socket.
+   */
+  wrap(payload: unknown): string;
+  /**
+   * Replay entries strictly greater than `lastSeq`. Returns either the
+   * array of payloads to write, OR `null` if the gap is unrecoverable
+   * (caller emits `resume_gap`).
+   */
+  drainAfter(lastSeq: number): string[] | null;
+  highestSeq(): number;
+  /** Peek the next sequence to be assigned (without consuming). */
+  peekNextSeq(): number;
+  /** Snapshot the dead queue contents for persistence. */
+  snapshotDeadQueue(): DeadQueueEntry[];
+}
+//#endregion
+//#region src/integrations/websocket/pushref-registry.d.ts
+/** Stable principal string. Format: `u:<userId>`, `c:<clientId>`, `anon`, or `conn:<pushRef>`. */
+type Principal = string;
+/**
+ * Outcome of `claim()`. Note the `generation` and `supersededActive`
+ * fields — they exist so the connection layer can detect AND fence a
+ * stale active connection elsewhere in the cluster:
+ *
+ *   - `generation`        — monotonic per-pushRef counter. Bumped on
+ *                           every successful claim. Lets the connection
+ *                           tag its outbound writes with its own
+ *                           generation, so the OLD live connection (if
+ *                           any) can recognize it's been superseded.
+ *
+ *   - `supersededActive`  — true when the claim happened while the
+ *                           previous entry was still `active`. Triggers
+ *                           the fence path: caller closes any local
+ *                           socket bound to this pushRef AND publishes
+ *                           a cluster-wide fence so other nodes do too.
+ *
+ * Without this, two sockets in different processes can hold live
+ * EnvelopeWriters for the same pushRef and race nextSeq + persist
+ * (the 2.17.2 review's HIGH-2 finding). The fence mechanism makes
+ * "newest claim wins" a hard invariant — the old socket is closed at
+ * 4011 before any further writes can land.
+ */
+type ClaimOutcome = {
+  outcome: "new";
+  envelope?: EnvelopeWriter;
+  generation: number;
+} | {
+  outcome: "resumed";
+  envelope?: EnvelopeWriter;
+  generation: number;
+  supersededActive: boolean;
+} | {
+  outcome: "rejected";
+  reason: "principal_mismatch" | "capacity";
+};
+/**
+ * Snapshot of a single registry entry — what gets persisted in an
+ * external store. `nextSeq` and `deadQueue` are tracked separately so
+ * a reconnecting client picks up exactly where it left off (no seq
+ * collisions, no replay gaps).
+ */
+interface SerializedEntry {
+  principal: Principal;
+  nextSeq: number;
+  deadQueue: DeadQueueEntry[];
+  expiresAt: number;
+  active: boolean;
+  envelopeMode: "raw" | "seq";
+  deadQueueSize: number;
+  /**
+   * Monotonic per-pushRef generation counter. Incremented on every
+   * successful claim (new or resumed). The connection layer stamps
+   * its writes with the generation in force at handshake time so a
+   * stale live connection on another node can be fenced — its
+   * generation is now strictly less than the latest.
+   */
+  generation: number;
+}
+/**
+ * Persistence contract for cross-instance pushRef state.
+ *
+ * Implementations MUST guarantee atomic claim semantics — concurrent
+ * claims for the same pushRef from different nodes resolve to exactly
+ * one `new` / `resumed` outcome; the loser sees `rejected`.
+ *
+ * `stage` and `bumpActive` are mutation primitives the registry uses
+ * for the offline-staging and reconnect paths; implementations may
+ * optimize them (e.g. Redis HSET partial updates) but the default
+ * implementation just reads the entry, mutates, writes back.
+ */
+/** Outcome of a fenced write — `stale` means the caller's generation lost. */
+type FencedWriteOutcome = "ok" | "missing" | "stale";
+/**
+ * Partial snapshot used by `releaseIfGen` / `persistIfGen` to flush the
+ * live envelope's nextSeq + dead queue back to the store atomically.
+ * Optional — caller may skip when no live envelope state exists (raw mode).
+ */
+interface EnvelopeSnapshot {
+  nextSeq: number;
+  deadQueue: DeadQueueEntry[];
+}
+interface PushRefStore {
+  get(pushRef: string): Promise<SerializedEntry | undefined>;
+  set(pushRef: string, entry: SerializedEntry): Promise<void>;
+  delete(pushRef: string): Promise<void>;
+  /**
+   * Generation-fenced release. The 2.17.2 review surfaced this race:
+   * after Node A is fenced by Node B's claim (generation = N+1), Node
+   * A's close handler still fires `release(pushRef)` synchronously.
+   * Without a generation check the release silently mutates Node B's
+   * entry — marks it inactive, overwrites dead queue with Node A's
+   * stale snapshot.
+   *
+   * The atomic contract:
+   *   - If `stored.generation === expectedGeneration`: mark inactive,
+   *     write snapshot (if provided), extend expiresAt — return `ok`.
+   *   - If different: no-op, return `stale`.
+   *   - If entry is absent: return `missing`.
+   *
+   * Implementations route this to native CAS — Redis uses a Lua script
+   * so the test + write is single-roundtrip; Memory uses sync compare
+   * inside the event-loop turn.
+   */
+  releaseIfGen(args: {
+    pushRef: string;
+    expectedGeneration: number;
+    snapshot?: EnvelopeSnapshot;
+    expiresAt: number;
+  }): Promise<FencedWriteOutcome>;
+  /**
+   * Generation-fenced persist. Used by the room manager after each
+   * critical send to round-trip the live envelope state to the store
+   * so a reconnect to ANY node picks up the latest dead queue. Same
+   * CAS contract as `releaseIfGen` — stale writes from a fenced
+   * connection are dropped.
+   */
+  persistIfGen(args: {
+    pushRef: string;
+    expectedGeneration: number;
+    snapshot: EnvelopeSnapshot;
+    expiresAt: number;
+  }): Promise<FencedWriteOutcome>;
+  /**
+   * Atomic offline-stage for a single payload. Used by the plugin's
+   * `app.ws.send({pushRef})` path when no live socket is attached —
+   * the payload is wrapped (seq + timestamp) into the dead queue so a
+   * reconnect's RESUME replays it.
+   *
+   * Why this can't be `get + mutate + set`:
+   *
+   *   The 2.17.2 review (HIGH) — between the read and the write, another
+   *   node can claim the pushRef and become the new active owner. A
+   *   non-atomic stage would then overwrite the freshly-claimed active
+   *   entry with the stale "inactive + old snapshot" view, losing the
+   *   new owner's generation bump and any frames it had already written.
+   *
+   * The atomic contract — performed under a single Lua EVAL on Redis,
+   * synchronously within the event-loop turn on Memory:
+   *
+   *   1. Read the entry. If missing → return 'missing'.
+   *   2. If `active === true` → return 'active' (caller routes to live
+   *      delivery instead; staging is for OFFLINE sessions only).
+   *   3. If `envelopeMode !== 'seq'` → return 'raw' (no envelope means
+   *      nothing to stage into).
+   *   4. Compute seq = entry.nextSeq, bump nextSeq.
+   *   5. Wrap the payload: `{seq, t, msg: payload}` and JSON-encode.
+   *   6. Append `{seq, payload: encoded}` to deadQueue. Trim to ring size.
+   *   7. Extend expiresAt. Write back.
+   *
+   * The wrap step happens INSIDE the atomic primitive because seq has
+   * to come from the just-read entry — the registry layer cannot
+   * pre-compute it without re-introducing the very race we're closing.
+   */
+  stageIfInactive(args: {
+    pushRef: string; /** Raw payload (NOT pre-wrapped). The store assigns seq + wraps atomically. */
+    payload: unknown; /** Server timestamp (ms) — passed in so tests can pin the clock. */
+    timestamp: number;
+    expiresAt: number;
+  }): Promise<"ok" | "missing" | "active" | "raw">;
+  /**
+   * Atomic claim. Implementations route to native primitives:
+   *   - Memory: single-threaded check-and-set
+   *   - Redis: Lua script (EVAL) testing principal then HMSET
+   *   - SQL: upsert with check constraint
+   *
+   * `mintFresh()` constructs a SerializedEntry for the new-claim path —
+   * called only when no existing entry is found and the store has decided
+   * to create one. (Lets the registry layer own the envelope-mint policy.)
+   */
+  claim(args: {
+    pushRef: string;
+    principal: Principal;
+    now: number;
+    ttlMs: number;
+    mintFresh: () => SerializedEntry;
+    maxEntries: number;
+    countNonExpired: () => Promise<number>;
+  }): Promise<{
+    outcome: "new" | "resumed" | "rejected";
+    entry?: SerializedEntry;
+    /**
+     * `true` when the previous entry was still marked active at the
+     * moment of claim — caller MUST fence the previous owner so two
+     * live sockets can't race the same envelope state.
+     */
+    supersededActive?: boolean;
+  }>;
+  /** Periodic GC — remove inactive entries past TTL. Returns count removed. */
+  gc(now: number): Promise<number>;
+  /** Total entries (active + inactive). */
+  size(): Promise<number>;
+  /** Cleanup any background resources (subscriptions, timers). */
+  close?(): Promise<void>;
+}
+interface PushRefRegistryOptions {
+  ttlMs?: number;
+  maxEntries?: number;
+  /** Inject the store implementation. Defaults to `MemoryPushRefStore`. */
+  store?: PushRefStore;
+  /** Optional clock injection — tests can pin time. */
+  now?: () => number;
+}
+/**
+ * Default in-memory store — the previous single-instance registry's
+ * behavior, repackaged behind the `PushRefStore` interface so the
+ * registry layer doesn't care whether it's local or distributed.
+ *
+ * All methods are technically synchronous but return promises to
+ * conform to the interface. Cost: one microtask per call. Negligible.
+ */
+declare class MemoryPushRefStore implements PushRefStore {
+  private entries;
+  get(pushRef: string): Promise<SerializedEntry | undefined>;
+  set(pushRef: string, entry: SerializedEntry): Promise<void>;
+  delete(pushRef: string): Promise<void>;
+  claim(args: {
+    pushRef: string;
+    principal: Principal;
+    now: number;
+    ttlMs: number;
+    mintFresh: () => SerializedEntry;
+    maxEntries: number;
+    countNonExpired: () => Promise<number>;
+  }): Promise<{
+    outcome: "new" | "resumed" | "rejected";
+    entry?: SerializedEntry;
+    supersededActive?: boolean;
+  }>;
+  releaseIfGen(args: {
+    pushRef: string;
+    expectedGeneration: number;
+    snapshot?: EnvelopeSnapshot;
+    expiresAt: number;
+  }): Promise<FencedWriteOutcome>;
+  persistIfGen(args: {
+    pushRef: string;
+    expectedGeneration: number;
+    snapshot: EnvelopeSnapshot;
+    expiresAt: number;
+  }): Promise<FencedWriteOutcome>;
+  stageIfInactive(args: {
+    pushRef: string;
+    payload: unknown;
+    timestamp: number;
+    expiresAt: number;
+  }): Promise<"ok" | "missing" | "active" | "raw">;
+  gc(now: number): Promise<number>;
+  size(): Promise<number>;
+  /** Test-only inspection — not in the PushRefStore interface. */
+  inspect(pushRef: string): Readonly<SerializedEntry> | undefined;
+  private evictOldestInactive;
+}
+/**
+ * Registry — the high-level interface connection.ts calls. Owns the
+ * envelope-mint policy (envelope writers are LIVE objects with mutable
+ * dead queues — they can't be reconstructed from a serialized snapshot
+ * exactly because the `nextSeq` counter and ring buffer must round-trip
+ * with full fidelity).
+ *
+ * The hot path:
+ *
+ *   1. `claim(pushRef, principal, deadQueueSize)` resolves the
+ *      cross-connection state. On `new`, an EnvelopeWriter is minted
+ *      around a fresh DeadQueue. On `resumed`, the EnvelopeWriter is
+ *      reconstructed from the persisted nextSeq + deadQueue contents.
+ *
+ *   2. The connection lifecycle calls `release()` on close — starts the
+ *      TTL countdown.
+ *
+ *   3. `stageForResume()` writes a payload into the orphan envelope
+ *      when no live socket is attached (the offline-send path).
+ *
+ *   4. `persist()` flushes the in-memory EnvelopeWriter back to the
+ *      store after each write — keeps the store in sync so a reconnect
+ *      to a different node sees the latest dead queue. For the memory
+ *      store this is a no-op; for Redis it's a HMSET write.
+ */
+declare class PushRefRegistry {
+  private store;
+  private ttlMs;
+  private maxEntries;
+  private now;
+  /**
+   * Live envelope writers indexed by pushRef. Stays in sync with the
+   * store via persist() after every wrap(). On `claim('resumed')`,
+   * rehydrated from the store's snapshot.
+   */
+  private liveEnvelopes;
+  constructor(opts?: PushRefRegistryOptions);
+  claim(pushRef: string, principal: Principal, opts: {
+    envelopeMode: "raw" | "seq";
+    deadQueueSize: number;
+  }): Promise<ClaimOutcome>;
+  /**
+   * Mark the connection inactive (TTL countdown starts). Caller MUST
+   * pass the generation they captured at claim time — the store does
+   * a compare-and-set and silently no-ops if the entry has since been
+   * superseded by a higher-generation claim (i.e. another node took
+   * ownership while our close handler was pending).
+   *
+   * This closes the race the 2.17.2 review surfaced: previously, a
+   * stale release could overwrite Node B's freshly-claimed entry with
+   * Node A's outdated snapshot.
+   *
+   * Returns the outcome for callers that want to log fenced writes.
+   */
+  release(pushRef: string, expectedGeneration: number): Promise<FencedWriteOutcome>;
+  evict(pushRef: string): Promise<void>;
+  /**
+   * Stage a payload into the orphan envelope when no live socket is
+   * attached. Atomic — routes through `store.stageIfInactive` which
+   * does the read + wrap + write under a single Lua EVAL (Redis) or
+   * synchronous event-loop turn (Memory). This closes the 2.17.2
+   * stage-vs-claim race where a get-then-set could overwrite a freshly
+   * claimed higher-generation entry with the stale inactive snapshot.
+   *
+   * Returns `true` only when the payload was actually staged. `false`
+   * for any of:
+   *   - entry missing (unknown / GC'd pushRef)
+   *   - entry is currently active (route via room manager instead)
+   *   - envelope mode is `'raw'` (no dead queue to stage into)
+   */
+  stageForResume(pushRef: string, payload: unknown): Promise<boolean>;
+  /**
+   * Generation-fenced persist. Called by the room-manager hook after
+   * every wrap() so the persisted snapshot stays in sync with the live
+   * envelope. Caller passes the connection's generation; a stale
+   * persist (after the connection was fenced) silently no-ops at the
+   * store level — never overwrites the newer owner's state.
+   *
+   * Returns the outcome for callers that want to log fenced writes.
+   */
+  persist(pushRef: string, expectedGeneration: number): Promise<FencedWriteOutcome>;
+  size(): Promise<number>;
+  gc(): Promise<number>;
+  close(): Promise<void>;
+  /** Diagnostics — read-only. */
+  inspect(pushRef: string): Promise<Readonly<SerializedEntry> | undefined>;
+  /** Reconstruct an EnvelopeWriter from a persisted snapshot. */
+  private hydrateEnvelope;
+}
+//#endregion
+export { PushRefRegistry as a, SerializedEntry as c, Principal as i, EnvelopeWriter as l, FencedWriteOutcome as n, PushRefRegistryOptions as o, MemoryPushRefStore as r, PushRefStore as s, EnvelopeSnapshot as t };

package/dist/{requestContext-SSaaTgW8.mjs → requestContext-DDLS3NVU.mjs}

@@ -64,5 +64,30 @@ const requestContext = {
 	*/
 	storage
 };
+/**
+* Returns the W3C Trace Context headers (`traceparent`, `tracestate`) from
+* the current request context as a plain `Record<string, string>`, suitable
+* for passing to `OutboxWriteOptions.headers` or forwarding to downstream
+* HTTP clients.
+*
+* Returns `undefined` when called outside a request scope or when no trace
+* context was propagated by the upstream caller.
+*
+* @example
+* ```typescript
+* // Propagate trace context through the outbox so downstream consumers
+* // can stitch together distributed traces.
+* const traceHeaders = getTraceHeaders();
+* await outbox.store(event, { headers: traceHeaders });
+* ```
+*/
+function getTraceHeaders() {
+	const store = requestContext.get();
+	if (!store) return void 0;
+	const headers = {};
+	if (store.traceparent) headers["traceparent"] = store.traceparent;
+	if (store.tracestate) headers["tracestate"] = store.tracestate;
+	return Object.keys(headers).length > 0 ? headers : void 0;
+}
 //#endregion
-export { requestContext as t };
+export { requestContext as n, getTraceHeaders as t };

package/dist/{routerShared-nCyJGOKX.mjs → routerShared-Dl0A77Ba.mjs}

@@ -1,7 +1,7 @@
 import { h as SYSTEM_FIELDS } from "./constants-TrJVIJl0.mjs";
 import { f as createError, r as ForbiddenError } from "./errors-j4aJm1Wg.mjs";
 import { b as isElevated, c as getOrgId, g as getUserId, n as PUBLIC_SCOPE, x as isMember } from "./types-Bi0r0vjG.mjs";
-import { t as requestContext } from "./requestContext-SSaaTgW8.mjs";
+import { n as requestContext } from "./requestContext-DDLS3NVU.mjs";
 import { I as evaluateAndApplyPermission, M as applyFieldWritePermissions, P as resolveEffectiveRoles, j as applyFieldReadPermissions } from "./permissions-B1Qy55fg.mjs";
 import { t as getUserRoles } from "./types-DV9WDfeg.mjs";
 import { t as executePipeline } from "./pipe-DiCyvyPN.mjs";