@tungthedev/streams-server 0.2.0

package/src/app_core.ts

@@ -0,0 +1,3144 @@
+import { mkdirSync } from "node:fs";
+import { createHash } from "node:crypto";
+import type { Config } from "./config";
+import { IngestQueue, type ProducerInfo, type AppendRow, type AppendResult } from "./ingest";
+import type { ObjectStore } from "./objectstore/interface";
+import type { StreamReader, ReadBatch, ReaderError, SearchHit, SearchResultBatch } from "./reader";
+import { StreamNotifier } from "./notifier";
+import { encodeOffset, parseOffsetResult, offsetToSeqOrNeg1, canonicalizeOffset, type ParsedOffset } from "./offset";
+import { parseDurationMsResult } from "./util/duration";
+import { Metrics } from "./metrics";
+import { parseTimestampMsResult } from "./util/time";
+import { cleanupTempSegments } from "./util/cleanup";
+import { MetricsEmitter } from "./metrics_emitter";
+import {
+  SchemaRegistryStore,
+  parseSchemaUpdateResult,
+  type SchemaRegistry,
+  type SchemaRegistryMutationError,
+  type SchemaRegistryReadError,
+} from "./schema/registry";
+import { decodeJsonPayloadWithRegistryResult } from "./schema/read_json";
+import { resolvePointerResult } from "./util/json_pointer";
+import { ExpirySweeper } from "./expiry_sweeper";
+import type { StatsCollector } from "./stats";
+import type { TouchProcessorStore } from "./store/touch_store";
+import type { ObjectStoreAccountingStore, StorageStatsStore } from "./store/stats_accounting_store";
+import { FullModeDetailsBuilder, type LocalStorageUsage } from "./details/full_mode_details";
+import type { FullModeDetailsStore } from "./store/full_mode_details_store";
+import { BackpressureGate } from "./backpressure";
+import { MemoryPressureMonitor } from "./memory";
+import { RuntimeMemorySampler } from "./runtime_memory_sampler";
+import { TouchProcessorManager } from "./touch/manager";
+import type { SegmentDiskCache } from "./segment/cache";
+import { ConcurrencyGate } from "./concurrency_gate";
+import {
+  buildProcessMemoryBreakdown,
+  type RuntimeHighWaterMark,
+  type RuntimeMemoryHighWaterSnapshot,
+  type RuntimeMemorySubsystemSnapshot,
+  type RuntimeMemorySnapshot,
+} from "./runtime_memory";
+import type { SegmenterController } from "./segment/segmenter_workers";
+import type { UploaderController } from "./uploader";
+import type { StreamIndexLookup } from "./index/indexer";
+import { ForegroundActivityTracker } from "./foreground_activity";
+import { Result } from "better-result";
+import { parseReadFilterResult } from "./read_filter";
+import { parseSearchRequestBodyResult, parseSearchRequestQueryResult } from "./search/query";
+import { parseAggregateRequestBodyResult } from "./search/aggregate";
+import {
+  StreamProfileStore,
+  parseProfileUpdateResult,
+  resolveCorrelationCapability,
+  resolveOtlpTracesCapability,
+  resolveJsonIngestCapability,
+  resolveTouchCapability,
+  type PreparedJsonRecord,
+  type StreamTouchRoute,
+} from "./profiles";
+import { encodeOtlpTraceExportResponse } from "./profiles/otelTraces/otlp";
+import {
+  buildObserveSummary,
+  buildTimeSearchClauses,
+  buildTraceDetails,
+  choosePrimaryEvent,
+  compactEvlogRecord,
+  compactTimelineItem,
+  compactTraceSpanRecord,
+  combineSearchClauses,
+  parseObserveRequestResult,
+  quoteSearchValue,
+  sortTimeline,
+  summarizeSearchCoverage,
+  summarizeSearchQueryCoverage,
+  type ObserveSearchQueryCoverage,
+} from "./observe/request";
+import { buildRequestObservabilityPairingDescriptor } from "./observe/pairing";
+import { dsError } from "./util/ds_error.ts";
+import type { SchemaPublicationStore } from "./store/schema_publication";
+import { requireWalControlPlaneStore, type WalControlPlaneStore } from "./store/capabilities";
+import type { StreamRow } from "./store/rows";
+
+export type AppDebugStore = {
+  close?: () => void | Promise<void>;
+};
+
+function withNosniff(headers: HeadersInit = {}): HeadersInit {
+  return {
+    "x-content-type-options": "nosniff",
+    ...headers,
+  };
+}
+
+function json(status: number, body: any, headers: HeadersInit = {}): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+      ...withNosniff(headers),
+    },
+  });
+}
+
+const OVERLOAD_RETRY_AFTER_SECONDS = "1";
+const UNAVAILABLE_RETRY_AFTER_SECONDS = "5";
+const APPEND_REQUEST_TIMEOUT_MS = 3_000;
+const HTTP_RESOLVER_TIMEOUT_MS = 5_000;
+const SEARCH_REQUEST_TIMEOUT_MS = 3_000;
+const TIMEOUT_SENTINEL = Symbol("request-timeout");
+const DEFAULT_TOUCH_JOURNAL_FILTER_BYTES = 4 * (1 << 22);
+
+type TimeoutSentinel = typeof TIMEOUT_SENTINEL;
+
+function retryAfterHeaders(seconds: string, headers: HeadersInit = {}): HeadersInit {
+  return {
+    "retry-after": seconds,
+    ...headers,
+  };
+}
+
+function clampSearchRequestTimeoutMs(timeoutMs: number | null): number {
+  return timeoutMs == null ? SEARCH_REQUEST_TIMEOUT_MS : Math.min(timeoutMs, SEARCH_REQUEST_TIMEOUT_MS);
+}
+
+async function awaitWithCooperativeTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T | TimeoutSentinel> {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<TimeoutSentinel>((resolve) => {
+        timer = setTimeout(() => resolve(TIMEOUT_SENTINEL), timeoutMs);
+      }),
+    ]);
+  } finally {
+    if (timer != null) clearTimeout(timer);
+  }
+}
+
+function isAbortLikeError(error: unknown): boolean {
+  return typeof error === "object" && error != null && "name" in error && (error as { name?: unknown }).name === "AbortError";
+}
+
+function searchResponseHeaders(search: SearchResultBatch): HeadersInit {
+  return {
+    "search-timed-out": search.timedOut ? "true" : "false",
+    "search-timeout-ms": String(search.timeoutMs ?? SEARCH_REQUEST_TIMEOUT_MS),
+    "search-took-ms": String(search.tookMs),
+    "search-total-relation": search.total.relation,
+    "search-coverage-complete": search.coverage.complete ? "true" : "false",
+    "search-indexed-segments": String(search.coverage.indexedSegments),
+    "search-indexed-segment-time-ms": String(search.coverage.indexedSegmentTimeMs),
+    "search-fts-section-get-ms": String(search.coverage.ftsSectionGetMs),
+    "search-fts-decode-ms": String(search.coverage.ftsDecodeMs),
+    "search-fts-clause-estimate-ms": String(search.coverage.ftsClauseEstimateMs),
+    "search-scanned-segments": String(search.coverage.scannedSegments),
+    "search-scanned-segment-time-ms": String(search.coverage.scannedSegmentTimeMs),
+    "search-scanned-tail-docs": String(search.coverage.scannedTailDocs),
+    "search-scanned-tail-time-ms": String(search.coverage.scannedTailTimeMs),
+    "search-exact-candidate-time-ms": String(search.coverage.exactCandidateTimeMs),
+    "search-candidate-doc-ids": String(search.coverage.candidateDocIds),
+    "search-decoded-records": String(search.coverage.decodedRecords),
+    "search-json-parse-time-ms": String(search.coverage.jsonParseTimeMs),
+    "search-segment-payload-bytes-fetched": String(search.coverage.segmentPayloadBytesFetched),
+    "search-sort-time-ms": String(search.coverage.sortTimeMs),
+    "search-peak-hits-held": String(search.coverage.peakHitsHeld),
+    "search-index-families-used": search.coverage.indexFamiliesUsed.join(","),
+  };
+}
+
+function internalError(message = "internal server error"): Response {
+  return json(500, { error: { code: "internal", message } });
+}
+
+function badRequest(msg: string): Response {
+  return json(400, { error: { code: "bad_request", message: msg } });
+}
+
+function unsupportedMediaType(msg: string): Response {
+  return json(415, { error: { code: "unsupported_media_type", message: msg } });
+}
+
+function notFound(msg = "not_found"): Response {
+  return json(404, { error: { code: "not_found", message: msg } });
+}
+
+function readerErrorResponse(err: ReaderError): Response {
+  if (err.kind === "not_found") return notFound();
+  if (err.kind === "gone") return notFound("stream expired");
+  if (err.kind === "internal") return internalError();
+  return badRequest(err.message);
+}
+
+function schemaMutationErrorResponse(err: SchemaRegistryMutationError): Response {
+  if (err.kind === "version_mismatch") return conflict(err.message);
+  return badRequest(err.message);
+}
+
+function schemaReadErrorResponse(_err: SchemaRegistryReadError): Response {
+  return internalError();
+}
+
+function conflict(msg: string, headers: HeadersInit = {}): Response {
+  return json(409, { error: { code: "conflict", message: msg } }, headers);
+}
+
+function tooLarge(msg: string): Response {
+  return json(413, { error: { code: "payload_too_large", message: msg } });
+}
+
+function unavailable(msg = "server shutting down"): Response {
+  return json(503, { error: { code: "unavailable", message: msg } }, retryAfterHeaders(UNAVAILABLE_RETRY_AFTER_SECONDS));
+}
+
+function overloaded(msg = "ingest queue full", code = "overloaded"): Response {
+  return json(429, { error: { code, message: msg } }, retryAfterHeaders(OVERLOAD_RETRY_AFTER_SECONDS));
+}
+
+function requestTimeout(msg = "request timed out"): Response {
+  return json(408, { error: { code: "request_timeout", message: msg } });
+}
+
+function appendTimeout(): Response {
+  return json(408, {
+    error: {
+      code: "append_timeout",
+      message: "append timed out; append outcome is unknown, check Stream-Next-Offset before retrying",
+    },
+  });
+}
+
+async function cancelRequestBody(req: Request): Promise<void> {
+  const body = req.body;
+  if (!body) return;
+  try {
+    await body.cancel("request rejected");
+    return;
+  } catch {
+    // ignore and try a reader-based cancel below
+  }
+  try {
+    const reader = body.getReader();
+    await reader.cancel("request rejected");
+  } catch {
+    // ignore
+  }
+}
+
+function normalizeContentType(value: string | null): string | null {
+  if (!value) return null;
+  const base = value.split(";")[0]?.trim().toLowerCase();
+  return base ? base : null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function isJsonContentType(value: string | null): boolean {
+  return normalizeContentType(value) === "application/json";
+}
+
+function isTextContentType(value: string | null): boolean {
+  const norm = normalizeContentType(value);
+  return norm === "application/json" || (norm != null && norm.startsWith("text/"));
+}
+
+function parseStreamClosedHeader(value: string | null): boolean {
+  return value != null && value.trim().toLowerCase() === "true";
+}
+
+function parseStreamSeqHeader(value: string | null): Result<string | null, { message: string }> {
+  if (value == null) return Result.ok(null);
+  const v = value.trim();
+  if (v.length === 0) return Result.err({ message: "invalid Stream-Seq" });
+  return Result.ok(v);
+}
+
+function parseStreamTtlSeconds(value: string): Result<number, { message: string }> {
+  const s = value.trim();
+  if (/^(0|[1-9][0-9]*)$/.test(s)) return Result.ok(Number(s));
+  if (/^(0|[1-9][0-9]*)(ms|s|m|h|d)$/.test(s)) {
+    const msRes = parseDurationMsResult(s);
+    if (Result.isError(msRes)) return Result.err({ message: msRes.error.message });
+    const ms = msRes.value;
+    if (ms % 1000 !== 0) return Result.err({ message: "invalid Stream-TTL" });
+    return Result.ok(Math.floor(ms / 1000));
+  }
+  return Result.err({ message: "invalid Stream-TTL" });
+}
+
+function parseNonNegativeInt(value: string): number | null {
+  if (!/^[0-9]+$/.test(value)) return null;
+  const n = Number(value);
+  if (!Number.isFinite(n)) return null;
+  return n;
+}
+
+function splitSseLines(data: string): string[] {
+  if (data === "") return [""];
+  return data.split(/\r\n|\r|\n/);
+}
+
+function encodeSseEvent(eventType: string, data: string): string {
+  const lines = splitSseLines(data);
+  let out = `event: ${eventType}\n`;
+  for (const line of lines) {
+    out += `data:${line}\n`;
+  }
+  out += `\n`;
+  return out;
+}
+
+const INTERNAL_METRICS_STREAM = "__stream_metrics__";
+
+function computeCursor(nowMs: number, provided: string | null): string {
+  let cursor = Math.floor(nowMs / 1000);
+  if (provided && /^[0-9]+$/.test(provided)) {
+    const n = Number(provided);
+    if (Number.isFinite(n) && n >= cursor) cursor = n + 1;
+  }
+  return String(cursor);
+}
+
+function concatPayloads(parts: Uint8Array[]): Buffer {
+  return Buffer.concat(parts.map((part) => Buffer.from(part.buffer, part.byteOffset, part.byteLength)));
+}
+
+function bodyBufferFromBytes(bytes: Uint8Array): ArrayBuffer {
+  const buffer = bytes.buffer;
+  if (bytes.byteOffset === 0 && bytes.byteLength === buffer.byteLength) {
+    return buffer as ArrayBuffer;
+  }
+  return buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+}
+
+const JSON_TEXT_DECODER = new TextDecoder();
+const JSON_TEXT_ENCODER = new TextEncoder();
+
+function keyBytesFromString(s: string | null): Uint8Array | null {
+  if (s == null) return null;
+  return JSON_TEXT_ENCODER.encode(s);
+}
+
+function extractRoutingKey(reg: SchemaRegistry, value: any): Result<Uint8Array | null, { message: string }> {
+  if (!reg.routingKey) return Result.ok(null);
+  const { jsonPointer, required } = reg.routingKey;
+  const resolvedRes = resolvePointerResult(value, jsonPointer);
+  if (Result.isError(resolvedRes)) return Result.err({ message: resolvedRes.error.message });
+  const resolved = resolvedRes.value;
+  if (!resolved.exists) {
+    if (required) return Result.err({ message: "routing key missing" });
+    return Result.ok(null);
+  }
+  if (typeof resolved.value !== "string") return Result.err({ message: "routing key must be string" });
+  return Result.ok(keyBytesFromString(resolved.value));
+}
+
+function timestampToIsoString(value: bigint | null): string | null {
+  return value == null ? null : new Date(Number(value)).toISOString();
+}
+
+function weakEtag(namespace: string, body: string): string {
+  const hash = createHash("sha1").update(body).digest("hex");
+  return `W/"${namespace}:${hash}"`;
+}
+
+
+export type App<TDebugStore extends AppDebugStore = AppDebugStore> = {
+  fetch: (req: Request) => Promise<Response>;
+  close: () => Promise<void>;
+  ready: Promise<void>;
+  deps: {
+    config: Config;
+    db?: TDebugStore;
+    os?: ObjectStore;
+    ingest: IngestQueue;
+    notifier: StreamNotifier;
+    reader: StreamReader;
+    segmenter?: SegmenterController;
+    uploader?: UploaderController;
+    indexer?: StreamIndexLookup;
+    metrics: Metrics;
+    registry: SchemaRegistryStore;
+    profiles: StreamProfileStore;
+    touch?: TouchProcessorManager;
+    stats?: StatsCollector;
+    storageStats?: StorageStatsStore;
+    objectStoreAccounting?: ObjectStoreAccountingStore;
+    backpressure?: BackpressureGate;
+    memory?: MemoryPressureMonitor;
+    concurrency?: {
+      ingest: ConcurrencyGate;
+      read: ConcurrencyGate;
+      search: ConcurrencyGate;
+      asyncIndex: ConcurrencyGate;
+    };
+    memorySampler?: RuntimeMemorySampler;
+  };
+};
+
+export type CreateAppRuntimeArgs = {
+  config: Config;
+  controlStore: WalControlPlaneStore;
+  ingest: IngestQueue;
+  notifier: StreamNotifier;
+  registry: SchemaRegistryStore;
+  profiles: StreamProfileStore;
+  touch?: TouchProcessorManager;
+  stats?: StatsCollector;
+  backpressure?: BackpressureGate;
+  memory: MemoryPressureMonitor;
+  asyncIndexGate: ConcurrencyGate;
+  foregroundActivity: ForegroundActivityTracker;
+  metrics: Metrics;
+  memorySampler?: RuntimeMemorySampler;
+};
+
+type FullModeRuntimeDeps = {
+  store: ObjectStore;
+  segmenter: SegmenterController;
+  uploader: UploaderController;
+  segmentDiskCache?: SegmentDiskCache;
+  sizeReconciler?: {
+    start(): void;
+    stop(): void;
+  };
+  manifestPublication?: {
+    publishDeletedStreamManifest(stream: string): Promise<void>;
+  };
+  getLocalStorageUsage?: (stream: string) => {
+    segment_cache_bytes: number;
+    routing_index_cache_bytes: number;
+    exact_index_cache_bytes: number;
+    lexicon_index_cache_bytes: number;
+    companion_cache_bytes: number;
+  };
+};
+
+type AppRuntimeDeps = {
+  reader: StreamReader;
+  indexer?: StreamIndexLookup;
+  schemaPublication?: SchemaPublicationStore;
+  fullMode?: FullModeRuntimeDeps;
+  getRuntimeMemorySnapshot?: () => RuntimeMemorySubsystemSnapshot;
+  start(): void;
+};
+
+export type CreateAppCoreOptions<TDebugStore extends AppDebugStore = AppDebugStore> = {
+  store: WalControlPlaneStore;
+  debugStore?: TDebugStore;
+  touchStore?: TouchProcessorStore;
+  touchUseWorkers?: boolean;
+  storageStatsStore?: StorageStatsStore;
+  objectStoreAccountingStore?: ObjectStoreAccountingStore;
+  detailsStore?: FullModeDetailsStore;
+  detailsStorageBackend?: "sqlite" | "postgres";
+  lifecycleHooks?: {
+    beforeRuntimeCreate?(): void;
+    afterInternalMetricsProfileEnsured?(): void;
+    getInitialBackpressureBytes?(): number;
+  };
+  stats?: StatsCollector;
+  createRuntime(args: CreateAppRuntimeArgs): AppRuntimeDeps;
+};
+
+function validateRuntimeCapabilityBundle(
+  controlStore: WalControlPlaneStore,
+  touchStore: TouchProcessorStore | undefined,
+  storageStatsStore: StorageStatsStore | undefined,
+  objectStoreAccountingStore: ObjectStoreAccountingStore | undefined,
+  detailsStore: FullModeDetailsStore | undefined,
+  runtime: AppRuntimeDeps
+): void {
+  const caps = controlStore.capabilities;
+  if (caps.indexes && !runtime.indexer) throw dsError("index capability requires an index runtime");
+  if (caps.schemaPublication && !runtime.schemaPublication) throw dsError("schema publication capability requires a schema publication runtime");
+  if (caps.manifests && !runtime.fullMode?.manifestPublication) throw dsError("manifest capability requires a full-mode manifest runtime");
+  if (caps.storageStats && !storageStatsStore) throw dsError("storage stats capability requires a storage stats store");
+  if (caps.objectStoreAccounting && !objectStoreAccountingStore) throw dsError("object-store accounting capability requires an accounting store");
+  if ((caps.storageStats || caps.objectStoreAccounting || caps.indexes) && !detailsStore) {
+    throw dsError("details/index capabilities require a full-mode details store");
+  }
+  if (caps.touch && !touchStore) throw dsError("touch capability requires a touch metadata store");
+  if (caps.internalMetrics && !caps.builtinProfiles) throw dsError("internal metrics capability requires built-in profile support");
+}
+
+function reduceConcurrencyLimit(limit: number): number {
+  return Math.max(1, Math.ceil(Math.max(1, limit) / 2));
+}
+
+function gateSnapshot(configuredLimit: number, gate: ConcurrencyGate) {
+  return {
+    configured_limit: configuredLimit,
+    current_limit: gate.getLimit(),
+    active: gate.getActive(),
+    queued: gate.getQueued(),
+  };
+}
+
+function unsupportedCapability(name: string): Response {
+  return json(501, { error: { code: "unsupported_capability", message: `${name} capability is not available` } });
+}
+
+export function createAppCore<TDebugStore extends AppDebugStore = AppDebugStore>(
+  cfg: Config,
+  opts: CreateAppCoreOptions<TDebugStore>
+): App<TDebugStore> {
+  mkdirSync(cfg.rootDir, { recursive: true });
+  cleanupTempSegments(cfg.rootDir);
+
+  const controlStore = requireWalControlPlaneStore(opts.store);
+  const debugStore = opts.debugStore;
+  const touchStore = opts.touchStore;
+  const storageStatsStore = opts.storageStatsStore;
+  const objectStoreAccountingStore = opts.objectStoreAccountingStore;
+  const detailsStore = opts.detailsStore;
+  opts.lifecycleHooks?.beforeRuntimeCreate?.();
+  const stats = opts.stats;
+  const metrics = new Metrics();
+  const backpressure =
+    cfg.localBacklogMaxBytes > 0
+      ? new BackpressureGate(cfg.localBacklogMaxBytes, opts.lifecycleHooks?.getInitialBackpressureBytes?.() ?? 0)
+      : undefined;
+  const memorySampler =
+    cfg.memorySamplerPath != null
+      ? new RuntimeMemorySampler(cfg.memorySamplerPath, {
+          intervalMs: cfg.memorySamplerIntervalMs,
+          scope: "main",
+        })
+      : undefined;
+  const ingestGate = new ConcurrencyGate(cfg.ingestConcurrency);
+  const readGate = new ConcurrencyGate(cfg.readConcurrency);
+  const searchGate = new ConcurrencyGate(cfg.searchConcurrency);
+  const asyncIndexGate = new ConcurrencyGate(cfg.asyncIndexConcurrency);
+  const foregroundActivity = new ForegroundActivityTracker();
+  const memory = new MemoryPressureMonitor(cfg.memoryLimitBytes, {
+    onSample: (rss, overLimit) => {
+      metrics.record("process.rss.bytes", rss, "bytes");
+      if (overLimit) metrics.record("process.rss.over_limit", 1, "count");
+      searchGate.setLimit(overLimit ? reduceConcurrencyLimit(cfg.searchConcurrency) : cfg.searchConcurrency);
+      asyncIndexGate.setLimit(overLimit ? reduceConcurrencyLimit(cfg.asyncIndexConcurrency) : cfg.asyncIndexConcurrency);
+    },
+    heapSnapshotPath: cfg.heapSnapshotPath ?? undefined,
+  });
+  let httpAppendGcBytesSinceLast = 0;
+  let httpAppendGcLastMs = 0;
+  const maybeCollectAfterHttpAppend = (bodyBytes: number): void => {
+    if (cfg.memoryLimitBytes <= 0 || bodyBytes <= 0) return;
+    const limit = cfg.memoryLimitBytes;
+    httpAppendGcBytesSinceLast += Math.max(0, Math.floor(bodyBytes));
+    const usage = process.memoryUsage();
+    const smallMemoryPreset = limit <= 1024 * 1024 * 1024;
+    const byteCadence = smallMemoryPreset ? 8 * 1024 * 1024 : 64 * 1024 * 1024;
+    const abovePressureBand =
+      usage.rss > limit * 0.55 ||
+      usage.external > limit * 0.2 ||
+      usage.arrayBuffers > limit * 0.15;
+    if (!abovePressureBand && httpAppendGcBytesSinceLast < byteCadence) return;
+    const now = Date.now();
+    if (now - httpAppendGcLastMs < 1_000) return;
+    const gc = (globalThis as { Bun?: { gc?: (force?: boolean) => void } }).Bun?.gc;
+    if (typeof gc !== "function") return;
+    httpAppendGcLastMs = now;
+    httpAppendGcBytesSinceLast = 0;
+    try {
+      gc(true);
+    } catch {
+      try {
+        gc();
+      } catch {
+        return;
+      }
+    }
+  };
+  const appendResponseHeaders = (headers: HeadersInit = {}): HeadersInit => {
+    if (cfg.memoryLimitBytes > 0 && cfg.memoryLimitBytes <= 1024 * 1024 * 1024) {
+      return withNosniff({
+        ...headers,
+        connection: "close",
+      });
+    }
+    return withNosniff(headers);
+  };
+  const ingest = new IngestQueue(cfg, controlStore, stats, backpressure, metrics);
+  const notifier = new StreamNotifier();
+  const registry = new SchemaRegistryStore(controlStore);
+  const profiles = new StreamProfileStore(controlStore, { touchEnabled: !!touchStore });
+  const touch =
+    touchStore && controlStore.capabilities.touch
+      ? new TouchProcessorManager(cfg, touchStore, ingest, notifier, profiles, backpressure, { useWorkers: opts.touchUseWorkers })
+      : undefined;
+  const runtime = opts.createRuntime({
+    config: cfg,
+    controlStore,
+    ingest,
+    notifier,
+    registry,
+    profiles,
+    touch,
+    stats,
+    backpressure,
+    memory,
+    asyncIndexGate,
+    foregroundActivity,
+    metrics,
+    memorySampler,
+  });
+  validateRuntimeCapabilityBundle(controlStore, touchStore, storageStatsStore, objectStoreAccountingStore, detailsStore, runtime);
+  const {
+    reader,
+    indexer,
+    schemaPublication,
+    fullMode,
+    getRuntimeMemorySnapshot,
+  } = runtime;
+  const getLocalStorageUsage = fullMode?.getLocalStorageUsage;
+  const detailsBuilder =
+    detailsStore
+      ? new FullModeDetailsBuilder({
+          detailsStore,
+          storageBackend: opts.detailsStorageBackend,
+          storageStatsStore,
+          objectStoreAccountingStore,
+          getLocalStorageUsage: getLocalStorageUsage as ((stream: string) => Partial<LocalStorageUsage>) | undefined,
+        })
+      : undefined;
+  memorySampler?.start();
+  memory.start();
+  ingest.start();
+  const runtimeHighWater: RuntimeMemoryHighWaterSnapshot = {
+    process: {},
+    process_breakdown: {},
+    sqlite: {},
+    runtime_bytes: {},
+    runtime_totals: {},
+  };
+
+  const observeHighWaterValue = (target: Record<string, RuntimeHighWaterMark>, key: string, value: number, at: string): void => {
+    const next = Math.max(0, Math.floor(value));
+    const existing = target[key];
+    if (!existing || next > existing.value) {
+      target[key] = {
+        value: next,
+        at,
+      };
+    }
+  };
+
+  const buildRuntimeBytes = (runtimeMemory: RuntimeMemorySnapshot): Record<string, Record<string, number>> => {
+    const groups: Record<string, Record<string, number>> = {};
+    for (const [kind, values] of Object.entries(runtimeMemory.subsystems)) {
+      if (kind === "counts") continue;
+      groups[kind] = values;
+    }
+    return groups;
+  };
+
+  const buildTopStreamContributors = async (limit = 5) => {
+    const safeLimit = Math.max(1, Math.min(limit, 20));
+    const localStorageRows: Array<{
+      stream: string;
+      bytes: number;
+      wal_retained_bytes: number;
+      segment_cache_bytes: number;
+      index_cache_bytes: number;
+    }> = [];
+    const pendingWalRows: Array<{ stream: string; pending_wal_bytes: number; pending_rows: number }> = [];
+    let offset = 0;
+    const pageSize = 1000;
+    for (;;) {
+      const rows = await controlStore.listStreams(pageSize, offset);
+      if (rows.length === 0) break;
+      for (const row of rows) {
+        if (controlStore.isDeleted(row)) continue;
+        const usage = getLocalStorageUsage?.(row.stream) ?? { segment_cache_bytes: 0 };
+        const walRetainedBytes = Number(row.pending_bytes);
+        const segmentCacheBytes = Math.max(0, Math.floor(Number((usage as Record<string, number>).segment_cache_bytes ?? 0)));
+        const indexCacheBytes = Math.max(
+          0,
+          Math.floor(
+            Number((usage as Record<string, number>).routing_index_cache_bytes ?? 0) +
+              Number((usage as Record<string, number>).exact_index_cache_bytes ?? 0) +
+              Number((usage as Record<string, number>).lexicon_index_cache_bytes ?? 0) +
+              Number((usage as Record<string, number>).companion_cache_bytes ?? 0)
+          )
+        );
+        localStorageRows.push({
+          stream: row.stream,
+          bytes: Math.max(0, walRetainedBytes + segmentCacheBytes + indexCacheBytes),
+          wal_retained_bytes: Math.max(0, walRetainedBytes),
+          segment_cache_bytes: segmentCacheBytes,
+          index_cache_bytes: indexCacheBytes,
+        });
+        pendingWalRows.push({
+          stream: row.stream,
+          pending_wal_bytes: Math.max(0, walRetainedBytes),
+          pending_rows: Math.max(0, Number(row.pending_rows)),
+        });
+      }
+      if (rows.length < pageSize) break;
+      offset += rows.length;
+    }
+    localStorageRows.sort((a, b) => b.bytes - a.bytes || a.stream.localeCompare(b.stream));
+    pendingWalRows.sort((a, b) => b.pending_wal_bytes - a.pending_wal_bytes || a.stream.localeCompare(b.stream));
+    return {
+      local_storage_bytes: localStorageRows.slice(0, safeLimit),
+      pending_wal_bytes: pendingWalRows.slice(0, safeLimit),
+      touch_journal_filter_bytes: touch?.getTopStreams(safeLimit) ?? [],
+      notifier_waiters: notifier.getTopStreams(safeLimit),
+    };
+  };
+
+  const buildRuntimeMemorySnapshot = (): RuntimeMemorySnapshot => {
+    const processUsage = process.memoryUsage();
+    const subsystemSnapshot = getRuntimeMemorySnapshot?.() ?? {
+      subsystems: {
+        heap_estimates: {},
+        mapped_files: {},
+        disk_caches: {},
+        configured_budgets: {},
+        pipeline_buffers: {},
+        sqlite_runtime: {},
+        counts: {},
+      },
+      totals: {
+        heap_estimate_bytes: 0,
+        mapped_file_bytes: 0,
+        disk_cache_bytes: 0,
+        configured_budget_bytes: 0,
+        pipeline_buffer_bytes: 0,
+        sqlite_runtime_bytes: 0,
+      },
+    };
+    const sqliteRuntimeBytes = subsystemSnapshot.subsystems.sqlite_runtime ?? {};
+    const runtimeCounts = subsystemSnapshot.subsystems.counts ?? {};
+    const snapshot: RuntimeMemorySnapshot = {
+      process: {
+        rss_bytes: processUsage.rss,
+        heap_total_bytes: processUsage.heapTotal,
+        heap_used_bytes: processUsage.heapUsed,
+        external_bytes: processUsage.external,
+        array_buffers_bytes: processUsage.arrayBuffers,
+      },
+      process_breakdown: buildProcessMemoryBreakdown({
+        process: {
+          rss_bytes: processUsage.rss,
+          heap_total_bytes: processUsage.heapTotal,
+          heap_used_bytes: processUsage.heapUsed,
+          external_bytes: processUsage.external,
+          array_buffers_bytes: processUsage.arrayBuffers,
+        },
+        mappedFileBytes: subsystemSnapshot.totals.mapped_file_bytes,
+        sqliteRuntimeBytes: Number(sqliteRuntimeBytes["sqlite_memory_used_bytes"] ?? 0),
+      }),
+      sqlite: {
+        available: Number(runtimeCounts["sqlite_open_connections"] ?? 0) > 0 || Number(sqliteRuntimeBytes["sqlite_memory_used_bytes"] ?? 0) > 0,
+        source:
+          Number(runtimeCounts["sqlite_open_connections"] ?? 0) > 0 || Number(sqliteRuntimeBytes["sqlite_memory_used_bytes"] ?? 0) > 0
+            ? "sqlite3_status64"
+            : "unavailable",
+        memory_used_bytes: Math.max(0, Math.floor(Number(sqliteRuntimeBytes["sqlite_memory_used_bytes"] ?? 0))),
+        memory_highwater_bytes: Math.max(
+          0,
+          Math.floor(Number(sqliteRuntimeBytes["sqlite_memory_highwater_bytes"] ?? 0))
+        ),
+        pagecache_used_slots: Math.max(0, Math.floor(Number(runtimeCounts["sqlite_pagecache_used_slots"] ?? 0))),
+        pagecache_used_slots_highwater: Math.max(
+          0,
+          Math.floor(Number(runtimeCounts["sqlite_pagecache_used_slots_highwater"] ?? 0))
+        ),
+        pagecache_overflow_bytes: Math.max(
+          0,
+          Math.floor(Number(sqliteRuntimeBytes["sqlite_pagecache_overflow_bytes"] ?? 0))
+        ),
+        pagecache_overflow_highwater_bytes: Math.max(
+          0,
+          Math.floor(Number(sqliteRuntimeBytes["sqlite_pagecache_overflow_highwater_bytes"] ?? 0))
+        ),
+        malloc_count: Math.max(0, Math.floor(Number(runtimeCounts["sqlite_malloc_count"] ?? 0))),
+        malloc_count_highwater: Math.max(
+          0,
+          Math.floor(Number(runtimeCounts["sqlite_malloc_count_highwater"] ?? 0))
+        ),
+        open_connections: Math.max(0, Math.floor(Number(runtimeCounts["sqlite_open_connections"] ?? 0))),
+        prepared_statements: Math.max(
+          0,
+          Math.floor(Number(runtimeCounts["sqlite_prepared_statements"] ?? 0))
+        ),
+      },
+      gc: memory.getGcStats(),
+      subsystems: subsystemSnapshot.subsystems,
+      totals: subsystemSnapshot.totals,
+    };
+    const ts = new Date().toISOString();
+    for (const [key, value] of Object.entries(snapshot.process)) observeHighWaterValue(runtimeHighWater.process, key, value, ts);
+    for (const [key, value] of Object.entries(snapshot.process_breakdown)) {
+      if (typeof value === "number") observeHighWaterValue(runtimeHighWater.process_breakdown, key, value, ts);
+    }
+    for (const [key, value] of Object.entries(snapshot.sqlite)) {
+      if (typeof value === "number") observeHighWaterValue(runtimeHighWater.sqlite, key, value, ts);
+    }
+    for (const [kind, values] of Object.entries(buildRuntimeBytes(snapshot))) {
+      const bucket = (runtimeHighWater.runtime_bytes[kind] ??= {});
+      for (const [key, value] of Object.entries(values)) observeHighWaterValue(bucket, key, value, ts);
+    }
+    for (const [key, value] of Object.entries(snapshot.totals)) observeHighWaterValue(runtimeHighWater.runtime_totals, key, value, ts);
+    if (snapshot.sqlite.memory_used_bytes > 0) observeHighWaterValue(runtimeHighWater.sqlite, "memory_used_bytes", snapshot.sqlite.memory_used_bytes, ts);
+    if (snapshot.sqlite.pagecache_overflow_bytes > 0)
+      observeHighWaterValue(runtimeHighWater.sqlite, "pagecache_overflow_bytes", snapshot.sqlite.pagecache_overflow_bytes, ts);
+    if (snapshot.sqlite.pagecache_used_slots > 0)
+      observeHighWaterValue(runtimeHighWater.sqlite, "pagecache_used_slots", snapshot.sqlite.pagecache_used_slots, ts);
+    if (snapshot.sqlite.malloc_count > 0) observeHighWaterValue(runtimeHighWater.sqlite, "malloc_count", snapshot.sqlite.malloc_count, ts);
+    return snapshot;
+  };
+
+  const buildLeakCandidateCounters = (): Record<string, number> => {
+    const runtimeMemory = buildRuntimeMemorySnapshot();
+    const runtimeCounts = runtimeMemory.subsystems.counts ?? {};
+    const countValue = (name: string): number => {
+      const raw = Number(runtimeCounts[name] ?? 0);
+      if (!Number.isFinite(raw)) return 0;
+      return Math.max(0, Math.floor(raw));
+    };
+    const touchMemory = touch?.getMemoryStats() ?? {
+      journals: 0,
+      journalsCreatedTotal: 0,
+      journalFilterBytesTotal: 0,
+      fineLagCoarseOnlyStreams: 0,
+      touchModeStreams: 0,
+      fineTokenBucketStreams: 0,
+      hotFineStreams: 0,
+      lagSourceOffsetStreams: 0,
+      restrictedTemplateBucketStreams: 0,
+      runtimeTotalsStreams: 0,
+      zeroRowBacklogStreakStreams: 0,
+      templateLastSeenEntries: 0,
+      templateDirtyLastSeenEntries: 0,
+      templateRateStateStreams: 0,
+      liveMetricsCounterStreams: 0,
+    };
+    const notifierMemory = notifier.getMemoryStats();
+    const metricsMemory = metrics.getMemoryStats();
+    return {
+      "tieredstore.mem.leak_candidate.segment_cache.pinned_entries": countValue("segment_pinned_files"),
+      "tieredstore.mem.leak_candidate.lexicon_file_cache.pinned_entries": countValue("lexicon_pinned_files"),
+      "tieredstore.mem.leak_candidate.companion_file_cache.pinned_entries": countValue("companion_pinned_files"),
+      "tieredstore.mem.leak_candidate.routing_run_disk_cache.pinned_entries": countValue("routing_run_disk_cache_pinned_entries"),
+      "tieredstore.mem.leak_candidate.exact_run_disk_cache.pinned_entries": countValue("exact_run_disk_cache_pinned_entries"),
+      "tieredstore.mem.leak_candidate.touch.journals.active_count": touchMemory.journals,
+      "tieredstore.mem.leak_candidate.touch.journals.created_total": touchMemory.journalsCreatedTotal,
+      "tieredstore.mem.leak_candidate.touch.journals.filter_bytes_total": touchMemory.journalFilterBytesTotal,
+      "tieredstore.mem.leak_candidate.touch.journal.default_filter_bytes": DEFAULT_TOUCH_JOURNAL_FILTER_BYTES,
+      "tieredstore.mem.leak_candidate.touch.maps.fine_lag_coarse_only_streams": touchMemory.fineLagCoarseOnlyStreams,
+      "tieredstore.mem.leak_candidate.touch.maps.touch_mode_streams": touchMemory.touchModeStreams,
+      "tieredstore.mem.leak_candidate.touch.maps.fine_token_bucket_streams": touchMemory.fineTokenBucketStreams,
+      "tieredstore.mem.leak_candidate.touch.maps.hot_fine_streams": touchMemory.hotFineStreams,
+      "tieredstore.mem.leak_candidate.touch.maps.lag_source_offset_streams": touchMemory.lagSourceOffsetStreams,
+      "tieredstore.mem.leak_candidate.touch.maps.restricted_template_bucket_streams": touchMemory.restrictedTemplateBucketStreams,
+      "tieredstore.mem.leak_candidate.touch.maps.runtime_totals_streams": touchMemory.runtimeTotalsStreams,
+      "tieredstore.mem.leak_candidate.touch.maps.zero_row_backlog_streams": touchMemory.zeroRowBacklogStreakStreams,
+      "tieredstore.mem.leak_candidate.live_template.last_seen_entries": touchMemory.templateLastSeenEntries,
+      "tieredstore.mem.leak_candidate.live_template.dirty_last_seen_entries": touchMemory.templateDirtyLastSeenEntries,
+      "tieredstore.mem.leak_candidate.live_template.rate_state_streams": touchMemory.templateRateStateStreams,
+      "tieredstore.mem.leak_candidate.live_metrics.counter_streams": touchMemory.liveMetricsCounterStreams,
+      "tieredstore.mem.leak_candidate.notifier.latest_seq_streams": notifierMemory.latestSeqStreams,
+      "tieredstore.mem.leak_candidate.notifier.details_version_streams": notifierMemory.detailsVersionStreams,
+      "tieredstore.mem.leak_candidate.metrics.series": metricsMemory.seriesCount,
+      "tieredstore.mem.leak_candidate.secondary_index.stream_idle_ticks_streams": countValue("secondary_index_stream_idle_ticks"),
+      "tieredstore.mem.leak_candidate.mock_r2.in_memory_bytes": countValue("mock_r2_in_memory_bytes"),
+      "tieredstore.mem.leak_candidate.mock_r2.object_count": countValue("mock_r2_object_count"),
+    };
+  };
+
+  const buildServerMem = async () => {
+    const runtimeMemory = buildRuntimeMemorySnapshot();
+    return {
+      ts: new Date().toISOString(),
+      process: runtimeMemory.process,
+      process_breakdown: runtimeMemory.process_breakdown,
+      sqlite: runtimeMemory.sqlite,
+      gc: runtimeMemory.gc,
+      high_water: runtimeHighWater,
+      counters: buildLeakCandidateCounters(),
+      runtime_counts: runtimeMemory.subsystems.counts,
+      runtime_bytes: buildRuntimeBytes(runtimeMemory),
+      runtime_totals: runtimeMemory.totals,
+      top_streams: await buildTopStreamContributors(),
+    };
+  };
+  memorySampler?.setSubsystemProvider(() => buildRuntimeMemorySnapshot().subsystems);
+  const buildServerDetails = async () => {
+    const runtimeMemory = buildRuntimeMemorySnapshot();
+    return {
+      auto_tune: {
+        enabled: cfg.autoTunePresetMb != null,
+        requested_memory_mb: cfg.autoTuneRequestedMemoryMb,
+        preset_mb: cfg.autoTunePresetMb,
+        effective_memory_limit_mb: cfg.autoTuneEffectiveMemoryLimitMb,
+      },
+      configured_limits: {
+        caches: {
+          sqlite_cache_bytes: cfg.sqliteCacheBytes,
+          worker_sqlite_cache_bytes: cfg.workerSqliteCacheBytes,
+          index_run_memory_cache_bytes: cfg.indexRunMemoryCacheBytes,
+          index_run_disk_cache_bytes: cfg.indexRunCacheMaxBytes,
+          lexicon_index_cache_bytes: cfg.lexiconIndexCacheMaxBytes,
+          segment_cache_bytes: cfg.segmentCacheMaxBytes,
+          companion_toc_cache_bytes: cfg.searchCompanionTocCacheBytes,
+          companion_section_cache_bytes: cfg.searchCompanionSectionCacheBytes,
+          companion_file_cache_bytes: cfg.searchCompanionFileCacheMaxBytes,
+        },
+        concurrency: {
+          ingest: cfg.ingestConcurrency,
+          read: cfg.readConcurrency,
+          search: cfg.searchConcurrency,
+          async_index: cfg.asyncIndexConcurrency,
+          upload: cfg.uploadConcurrency,
+          index_build: cfg.indexBuildConcurrency,
+          index_compact: cfg.indexCompactionConcurrency,
+        },
+        ingest: {
+          max_batch_requests: cfg.ingestMaxBatchRequests,
+          max_batch_bytes: cfg.ingestMaxBatchBytes,
+          max_queue_requests: cfg.ingestMaxQueueRequests,
+          max_queue_bytes: cfg.ingestMaxQueueBytes,
+          busy_timeout_ms: cfg.ingestBusyTimeoutMs,
+          local_backlog_max_bytes: cfg.localBacklogMaxBytes,
+        },
+        search: {
+          companion_batch_segments: cfg.searchCompanionBuildBatchSegments,
+          companion_yield_blocks: cfg.searchCompanionYieldBlocks,
+          wal_overlay_quiet_period_ms: cfg.searchWalOverlayQuietPeriodMs,
+          wal_overlay_max_bytes: cfg.searchWalOverlayMaxBytes,
+        },
+        segmenting: {
+          segment_max_bytes: cfg.segmentMaxBytes,
+          segment_target_rows: cfg.segmentTargetRows,
+          segmenter_workers: cfg.segmenterWorkers,
+        },
+        timeouts: {
+          append_request_timeout_ms: APPEND_REQUEST_TIMEOUT_MS,
+          search_request_timeout_ms: SEARCH_REQUEST_TIMEOUT_MS,
+          resolver_timeout_ms: HTTP_RESOLVER_TIMEOUT_MS,
+          object_store_timeout_ms: cfg.objectStoreTimeoutMs,
+        },
+        memory: {
+          pressure_limit_bytes: cfg.memoryLimitBytes,
+        },
+      },
+      runtime: {
+        memory: {
+          pressure_active: memory.isOverLimit(),
+          pressure_limit_bytes: memory.getLimitBytes(),
+          last_rss_bytes: memory.getLastRssBytes(),
+          max_rss_bytes: memory.getMaxRssBytes(),
+          process: runtimeMemory.process,
+          process_breakdown: runtimeMemory.process_breakdown,
+          sqlite: runtimeMemory.sqlite,
+          gc: runtimeMemory.gc,
+          subsystems: runtimeMemory.subsystems,
+          totals: runtimeMemory.totals,
+          high_water: runtimeHighWater,
+        },
+        ingest_queue: {
+          requests: ingest.getQueueStats().requests,
+          bytes: ingest.getQueueStats().bytes,
+          full: ingest.isQueueFull(),
+        },
+        local_backpressure: {
+          enabled: backpressure?.enabled() ?? false,
+          current_bytes: backpressure?.getCurrentBytes() ?? 0,
+          max_bytes: backpressure?.getMaxBytes() ?? 0,
+          over_limit: backpressure?.isOverLimit() ?? false,
+        },
+        uploads: {
+          pending_segments: fullMode?.uploader.countSegmentsWaiting() ?? 0,
+        },
+        concurrency: {
+          ingest: gateSnapshot(cfg.ingestConcurrency, ingestGate),
+          read: gateSnapshot(cfg.readConcurrency, readGate),
+          search: gateSnapshot(cfg.searchConcurrency, searchGate),
+          async_index: gateSnapshot(cfg.asyncIndexConcurrency, asyncIndexGate),
+        },
+        top_streams: await buildTopStreamContributors(),
+      },
+    };
+  };
+  const collectRuntimeMetrics = () => {
+    const queue = ingest.getQueueStats();
+    const emitGate = (name: string, configuredLimit: number, gate: ConcurrencyGate) => {
+      metrics.record("tieredstore.concurrency.limit", configuredLimit, "count", { gate: name, kind: "configured" });
+      metrics.record("tieredstore.concurrency.limit", gate.getLimit(), "count", { gate: name, kind: "effective" });
+      metrics.record("tieredstore.concurrency.active", gate.getActive(), "count", { gate: name });
+      metrics.record("tieredstore.concurrency.queued", gate.getQueued(), "count", { gate: name });
+    };
+    emitGate("ingest", cfg.ingestConcurrency, ingestGate);
+    emitGate("read", cfg.readConcurrency, readGate);
+    emitGate("search", cfg.searchConcurrency, searchGate);
+    emitGate("async_index", cfg.asyncIndexConcurrency, asyncIndexGate);
+    metrics.record("tieredstore.ingest.queue.capacity.requests", cfg.ingestMaxQueueRequests, "count");
+    metrics.record("tieredstore.ingest.queue.capacity.bytes", cfg.ingestMaxQueueBytes, "bytes");
+    metrics.record("tieredstore.upload.pending_segments", fullMode?.uploader.countSegmentsWaiting() ?? 0, "count");
+    metrics.record("tieredstore.upload.concurrency.limit", cfg.uploadConcurrency, "count");
+    if (cfg.memoryLimitBytes > 0) metrics.record("process.memory.limit.bytes", cfg.memoryLimitBytes, "bytes");
+    const lastRss = memory.getLastRssBytes();
+    if (lastRss > 0) metrics.record("process.rss.current.bytes", lastRss, "bytes");
+    const maxRss = memory.snapshotMaxRssBytes();
+    if (maxRss > 0) metrics.record("process.rss.max_interval.bytes", maxRss, "bytes");
+    const runtimeMemory = buildRuntimeMemorySnapshot();
+    metrics.record("process.heap.total.bytes", runtimeMemory.process.heap_total_bytes, "bytes");
+    metrics.record("process.heap.used.bytes", runtimeMemory.process.heap_used_bytes, "bytes");
+    metrics.record("process.external.bytes", runtimeMemory.process.external_bytes, "bytes");
+    metrics.record("process.array_buffers.bytes", runtimeMemory.process.array_buffers_bytes, "bytes");
+    if (runtimeMemory.process_breakdown.rss_anon_bytes != null) {
+      metrics.record("process.memory.rss.anon.bytes", runtimeMemory.process_breakdown.rss_anon_bytes, "bytes");
+    }
+    if (runtimeMemory.process_breakdown.rss_file_bytes != null) {
+      metrics.record("process.memory.rss.file.bytes", runtimeMemory.process_breakdown.rss_file_bytes, "bytes");
+    }
+    if (runtimeMemory.process_breakdown.rss_shmem_bytes != null) {
+      metrics.record("process.memory.rss.shmem.bytes", runtimeMemory.process_breakdown.rss_shmem_bytes, "bytes");
+    }
+    if (runtimeMemory.process_breakdown.unattributed_anon_bytes != null) {
+      metrics.record("process.memory.unattributed_anon.bytes", runtimeMemory.process_breakdown.unattributed_anon_bytes, "bytes");
+    }
+    metrics.record("process.memory.js_managed.bytes", runtimeMemory.process_breakdown.js_managed_bytes, "bytes");
+    metrics.record(
+      "process.memory.js_external_non_array_buffers.bytes",
+      runtimeMemory.process_breakdown.js_external_non_array_buffers_bytes,
+      "bytes"
+    );
+    metrics.record("process.memory.unattributed.bytes", runtimeMemory.process_breakdown.unattributed_rss_bytes, "bytes");
+    metrics.record("tieredstore.sqlite.memory.used.bytes", runtimeMemory.sqlite.memory_used_bytes, "bytes");
+    metrics.record("tieredstore.sqlite.memory.high_water.bytes", runtimeMemory.sqlite.memory_highwater_bytes, "bytes");
+    metrics.record("tieredstore.sqlite.pagecache.used", runtimeMemory.sqlite.pagecache_used_slots, "count");
+    metrics.record("tieredstore.sqlite.pagecache.high_water", runtimeMemory.sqlite.pagecache_used_slots_highwater, "count");
+    metrics.record("tieredstore.sqlite.pagecache.overflow.bytes", runtimeMemory.sqlite.pagecache_overflow_bytes, "bytes");
+    metrics.record(
+      "tieredstore.sqlite.pagecache.overflow.high_water.bytes",
+      runtimeMemory.sqlite.pagecache_overflow_highwater_bytes,
+      "bytes"
+    );
+    metrics.record("tieredstore.sqlite.malloc.count", runtimeMemory.sqlite.malloc_count, "count");
+    metrics.record("tieredstore.sqlite.malloc.high_water.count", runtimeMemory.sqlite.malloc_count_highwater, "count");
+    metrics.record("tieredstore.sqlite.open_connections", runtimeMemory.sqlite.open_connections, "count");
+    metrics.record("tieredstore.sqlite.prepared_statements", runtimeMemory.sqlite.prepared_statements, "count");
+    for (const [kind, values] of Object.entries(runtimeMemory.subsystems)) {
+      if (kind === "counts") continue;
+      for (const [subsystem, value] of Object.entries(values)) {
+        metrics.record("tieredstore.memory.subsystem.bytes", value, "bytes", { kind, subsystem });
+      }
+    }
+    for (const [subsystem, value] of Object.entries(runtimeMemory.subsystems.counts)) {
+      metrics.record("tieredstore.memory.subsystem.count", value, "count", { subsystem });
+    }
+    metrics.record("tieredstore.memory.tracked.bytes", runtimeMemory.totals.heap_estimate_bytes, "bytes", { kind: "heap_estimate" });
+    metrics.record("tieredstore.memory.tracked.bytes", runtimeMemory.totals.mapped_file_bytes, "bytes", { kind: "mapped_file" });
+    metrics.record("tieredstore.memory.tracked.bytes", runtimeMemory.totals.disk_cache_bytes, "bytes", { kind: "disk_cache" });
+    metrics.record("tieredstore.memory.tracked.bytes", runtimeMemory.totals.configured_budget_bytes, "bytes", { kind: "configured_budget" });
+    metrics.record("tieredstore.memory.tracked.bytes", runtimeMemory.totals.pipeline_buffer_bytes, "bytes", { kind: "pipeline_buffer" });
+    metrics.record("tieredstore.memory.tracked.bytes", runtimeMemory.totals.sqlite_runtime_bytes, "bytes", { kind: "sqlite_runtime" });
+    const memLeakCounters = buildLeakCandidateCounters();
+    for (const [metricName, value] of Object.entries(memLeakCounters)) {
+      const unit = metricName.endsWith("_bytes") ? "bytes" : "count";
+      metrics.record(metricName, value, unit);
+    }
+    metrics.record("process.gc.forced.count", runtimeMemory.gc.forced_gc_count, "count");
+    metrics.record("process.gc.reclaimed.bytes", runtimeMemory.gc.forced_gc_reclaimed_bytes_total, "bytes", { kind: "total" });
+    if (runtimeMemory.gc.last_forced_gc_reclaimed_bytes != null) {
+      metrics.record("process.gc.reclaimed.bytes", runtimeMemory.gc.last_forced_gc_reclaimed_bytes, "bytes", { kind: "last" });
+    }
+    if (runtimeMemory.gc.last_forced_gc_at_ms != null) {
+      metrics.record("process.gc.last_forced_at_ms", runtimeMemory.gc.last_forced_gc_at_ms, "count");
+    }
+    metrics.record("process.heap.snapshot.count", runtimeMemory.gc.heap_snapshots_written, "count");
+    if (runtimeMemory.gc.last_heap_snapshot_at_ms != null) {
+      metrics.record("process.heap.snapshot.last_at_ms", runtimeMemory.gc.last_heap_snapshot_at_ms, "count");
+    }
+    for (const [metricName, entry] of Object.entries(runtimeHighWater.process)) {
+      metrics.record("process.memory.high_water.bytes", entry.value, "bytes", { metric: metricName });
+    }
+    for (const [metricName, entry] of Object.entries(runtimeHighWater.process_breakdown)) {
+      metrics.record("process.memory.high_water.bytes", entry.value, "bytes", { metric: metricName });
+    }
+    for (const [metricName, entry] of Object.entries(runtimeHighWater.runtime_totals)) {
+      metrics.record("tieredstore.memory.high_water.bytes", entry.value, "bytes", { kind: "runtime_total", metric: metricName });
+    }
+    for (const [kind, entries] of Object.entries(runtimeHighWater.runtime_bytes)) {
+      for (const [metricName, entry] of Object.entries(entries)) {
+        metrics.record("tieredstore.memory.high_water.bytes", entry.value, "bytes", {
+          kind: "runtime_subsystem",
+          subsystem_kind: kind,
+          metric: metricName,
+        });
+      }
+    }
+    for (const [metricName, entry] of Object.entries(runtimeHighWater.sqlite)) {
+      const unit =
+        metricName.includes("bytes") || metricName.includes("memory") || metricName.includes("overflow") ? "bytes" : "count";
+      metrics.record("tieredstore.sqlite.high_water", entry.value, unit, { metric: metricName });
+    }
+    metrics.record("process.memory.pressure", memory.isOverLimit() ? 1 : 0, "count");
+    if (backpressure) {
+      metrics.record("tieredstore.backpressure.current.bytes", backpressure.getCurrentBytes(), "bytes");
+      metrics.record("tieredstore.backpressure.limit.bytes", backpressure.getMaxBytes(), "bytes");
+      metrics.record("tieredstore.backpressure.pressure", backpressure.isOverLimit() ? 1 : 0, "count");
+    }
+    if (cfg.autoTunePresetMb != null) {
+      metrics.record("tieredstore.auto_tune.preset_mb", cfg.autoTunePresetMb, "count");
+    }
+    if (cfg.autoTuneEffectiveMemoryLimitMb != null) {
+      metrics.record("tieredstore.auto_tune.effective_memory_limit_mb", cfg.autoTuneEffectiveMemoryLimitMb, "count");
+    }
+  };
+  const metricsEmitter = new MetricsEmitter(metrics, ingest, cfg.metricsFlushIntervalMs, {
+    onAppended: ({ lastOffset, stream }) => {
+      notifier.notify(stream, lastOffset);
+      notifier.notifyDetailsChanged(stream);
+    },
+    collectRuntimeMetrics,
+  });
+  const expirySweeper = new ExpirySweeper(cfg, controlStore);
+  let closing = false;
+
+  const startupPromise = (async () => {
+    let metricsProfileRes: Awaited<ReturnType<StreamProfileStore["updateProfileResult"]>> | null = null;
+    if (controlStore.capabilities.internalMetrics) {
+      await controlStore.ensureStream(INTERNAL_METRICS_STREAM, { contentType: "application/json", profile: "metrics" });
+      opts.lifecycleHooks?.afterInternalMetricsProfileEnsured?.();
+      metricsProfileRes = await profiles.updateProfileResult(INTERNAL_METRICS_STREAM, { kind: "metrics" });
+      if (Result.isError(metricsProfileRes)) {
+        throw dsError(`failed to initialize ${INTERNAL_METRICS_STREAM} profile: ${metricsProfileRes.error.message}`);
+      }
+    }
+    if (closing) return;
+    runtime.start();
+    if (controlStore.capabilities.internalMetrics) metricsEmitter.start();
+    expirySweeper.start();
+    touch?.start();
+    fullMode?.sizeReconciler?.start();
+    if (schemaPublication && metricsProfileRes && Result.isOk(metricsProfileRes) && metricsProfileRes.value.schemaRegistry) {
+      void schemaPublication
+        .publishProfileSchemaRegistry(INTERNAL_METRICS_STREAM, metricsProfileRes.value.schemaRegistry)
+        .catch(() => {
+          // background best-effort; next manifest publication will reconcile
+      });
+    }
+  })();
+  const ready = startupPromise.catch((err) => {
+    throw err;
+  });
+  void ready.catch(() => {});
+
+  const getLiveStreamResult = async (stream: string): Promise<Result<StreamRow, { status: 404; message: string }>> => {
+    const srow = await controlStore.getStream(stream);
+    if (!srow || controlStore.isDeleted(srow)) return Result.err({ status: 404, message: "not_found" });
+    if (srow.expires_at_ms != null && controlStore.nowMs() > srow.expires_at_ms) {
+      return Result.err({ status: 404, message: "stream expired" });
+    }
+    return Result.ok(srow as StreamRow);
+  };
+
+  const liveStreamOrResponse = async (stream: string): Promise<StreamRow | Response> => {
+    const srowRes = await getLiveStreamResult(stream);
+    if (Result.isOk(srowRes)) return srowRes.value;
+    return srowRes.error.message === "stream expired" ? notFound("stream expired") : notFound();
+  };
+
+  const buildJsonRows = async (
+    stream: string,
+    bodyBytes: Uint8Array,
+    routingKeyHeader: string | null,
+    allowEmptyArray: boolean
+  ): Promise<Result<{ rows: AppendRow[] }, { status: 400 | 500; message: string }>> => {
+    const regRes = await registry.getRegistryResult(stream);
+    if (Result.isError(regRes)) {
+      return Result.err({ status: 500, message: regRes.error.message });
+    }
+    const profileRes = await profiles.getProfileResult(stream);
+    if (Result.isError(profileRes)) {
+      return Result.err({ status: 500, message: profileRes.error.message });
+    }
+    const reg = regRes.value;
+    const jsonIngest = resolveJsonIngestCapability(profileRes.value);
+    const text = JSON_TEXT_DECODER.decode(bodyBytes);
+    let arr: any;
+    try {
+      arr = JSON.parse(text);
+    } catch {
+      return Result.err({ status: 400, message: "invalid JSON" });
+    }
+    if (!Array.isArray(arr)) arr = [arr];
+    if (arr.length === 0 && !allowEmptyArray) return Result.err({ status: 400, message: "empty JSON array" });
+    if (reg.routingKey && routingKeyHeader) {
+      return Result.err({ status: 400, message: "Stream-Key not allowed when routingKey is configured" });
+    }
+
+    const validator = reg.currentVersion > 0 ? registry.getValidatorForVersion(reg, reg.currentVersion) : null;
+    if (reg.currentVersion > 0 && !validator) {
+      return Result.err({ status: 500, message: "schema validator missing" });
+    }
+
+    const rows: AppendRow[] = [];
+    for (const v of arr) {
+      let value = v;
+      let profileRoutingKey: Uint8Array | null = null;
+      if (jsonIngest) {
+        const preparedRes = jsonIngest.prepareRecordResult({ stream, profile: profileRes.value, value: v });
+        if (Result.isError(preparedRes)) return Result.err({ status: 400, message: preparedRes.error.message });
+        value = preparedRes.value.value;
+        profileRoutingKey = keyBytesFromString(preparedRes.value.routingKey);
+      }
+      if (validator && !validator(value)) {
+        const msg = validator.errors ? validator.errors.map((e) => e.message).join("; ") : "schema validation failed";
+        return Result.err({ status: 400, message: msg });
+      }
+      const rkRes = reg.routingKey
+        ? extractRoutingKey(reg, value)
+        : Result.ok(routingKeyHeader != null ? keyBytesFromString(routingKeyHeader) : profileRoutingKey);
+      if (Result.isError(rkRes)) return Result.err({ status: 400, message: rkRes.error.message });
+      rows.push({
+        routingKey: rkRes.value,
+        contentType: "application/json",
+        payload: JSON_TEXT_ENCODER.encode(JSON.stringify(value)),
+      });
+    }
+    return Result.ok({ rows });
+  };
+
+  const buildPreparedJsonRows = async (
+    stream: string,
+    records: PreparedJsonRecord[]
+  ): Promise<Result<{ rows: AppendRow[] }, { status: 400 | 500; message: string }>> => {
+    const regRes = await registry.getRegistryResult(stream);
+    if (Result.isError(regRes)) return Result.err({ status: 500, message: regRes.error.message });
+    const reg = regRes.value;
+    const validator = reg.currentVersion > 0 ? registry.getValidatorForVersion(reg, reg.currentVersion) : null;
+    if (reg.currentVersion > 0 && !validator) {
+      return Result.err({ status: 500, message: "schema validator missing" });
+    }
+    const rows: AppendRow[] = [];
+    for (const record of records) {
+      if (validator && !validator(record.value)) {
+        const msg = validator.errors ? validator.errors.map((e) => e.message).join("; ") : "schema validation failed";
+        return Result.err({ status: 400, message: msg });
+      }
+      rows.push({
+        routingKey: keyBytesFromString(record.routingKey),
+        contentType: "application/json",
+        payload: JSON_TEXT_ENCODER.encode(JSON.stringify(record.value)),
+      });
+    }
+    return Result.ok({ rows });
+  };
+
+  const buildAppendRowsResult = async (
+    stream: string,
+    bodyBytes: Uint8Array,
+    contentType: string,
+    routingKeyHeader: string | null,
+    allowEmptyJsonArray: boolean
+  ): Promise<Result<{ rows: AppendRow[] }, { status: 400 | 500; message: string }>> => {
+    if (isJsonContentType(contentType)) {
+      return buildJsonRows(stream, bodyBytes, routingKeyHeader, allowEmptyJsonArray);
+    }
+    const regRes = await registry.getRegistryResult(stream);
+    if (Result.isError(regRes)) return Result.err({ status: 500, message: regRes.error.message });
+    const reg = regRes.value;
+    if (reg.currentVersion > 0) return Result.err({ status: 400, message: "stream requires JSON" });
+    return Result.ok({
+      rows: [
+        {
+          routingKey: keyBytesFromString(routingKeyHeader),
+          contentType,
+          payload: bodyBytes,
+        },
+      ],
+    });
+  };
+
+  const enqueueAppend = (args: {
+    stream: string;
+    baseAppendMs: bigint;
+    rows: AppendRow[];
+    contentType: string | null;
+    close: boolean;
+    streamSeq?: string | null;
+    producer?: ProducerInfo | null;
+  }) =>
+    ingest.append({
+      stream: args.stream,
+      baseAppendMs: args.baseAppendMs,
+      rows: args.rows,
+      contentType: args.contentType,
+      streamSeq: args.streamSeq,
+      producer: args.producer,
+      close: args.close,
+    });
+
+  const awaitAppendWithTimeout = async (appendPromise: Promise<AppendResult>): Promise<AppendResult | Response> => {
+    const appendResult = await awaitWithCooperativeTimeout(appendPromise, APPEND_REQUEST_TIMEOUT_MS);
+    return appendResult === TIMEOUT_SENTINEL ? appendTimeout() : appendResult;
+  };
+
+  const recordAppendOutcome = (args: {
+    stream: string;
+    lastOffset: bigint;
+    appendedRows: number;
+    metricsBytes: number;
+    ingestedBytes: number;
+    touched: boolean;
+    closed: boolean;
+  }): void => {
+    if (args.appendedRows > 0) {
+      metrics.recordAppend(args.metricsBytes, args.appendedRows);
+      notifier.notify(args.stream, args.lastOffset);
+      notifier.notifyDetailsChanged(args.stream);
+      touch?.notify(args.stream);
+    }
+    if (stats) {
+      if (args.touched) stats.recordStreamTouched(args.stream);
+      if (args.appendedRows > 0) stats.recordIngested(args.ingestedBytes);
+    }
+    if (args.closed) {
+      notifier.notifyDetailsChanged(args.stream);
+      notifier.notifyClose(args.stream);
+    }
+  };
+
+  const decodeJsonRecords = async (
+    stream: string,
+    records: Array<{ offset: bigint; payload: Uint8Array }>
+  ): Promise<Result<{ values: any[] }, { status: 400 | 500; message: string }>> => {
+    const regRes = await registry.getRegistryResult(stream);
+    if (Result.isError(regRes)) return Result.err({ status: 500, message: regRes.error.message });
+    const values: any[] = [];
+    for (const r of records) {
+      const valueRes = decodeJsonPayloadWithRegistryResult(registry, regRes.value, r.offset, r.payload);
+      if (Result.isError(valueRes)) return valueRes;
+      values.push(valueRes.value);
+    }
+    return Result.ok({ values });
+  };
+
+  const encodeStoredJsonArrayResult = async (
+    stream: string,
+    records: Array<{ payload: Uint8Array }>
+  ): Promise<Result<Buffer | null, { status: 400 | 500; message: string }>> => {
+    const regRes = await registry.getRegistryResult(stream);
+    if (Result.isError(regRes)) return Result.err({ status: 500, message: regRes.error.message });
+    if (regRes.value.currentVersion !== 0) return Result.ok(null);
+    const parts: Buffer[] = [Buffer.from("[")];
+    for (let i = 0; i < records.length; i++) {
+      if (i > 0) parts.push(Buffer.from(","));
+      const payload = records[i]!.payload;
+      parts.push(Buffer.from(payload.buffer, payload.byteOffset, payload.byteLength));
+    }
+    parts.push(Buffer.from("]"));
+    return Result.ok(Buffer.concat(parts));
+  };
+
+  type DetailsSnapshot = { etag: string; body: string; version: bigint };
+
+  const buildDetailsSnapshotResult = async (
+    stream: string,
+    mode: "details" | "index_status"
+  ): Promise<Result<DetailsSnapshot, { status: 404 | 500; message: string }>> => {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const beforeVersion = notifier.currentDetailsVersion(stream);
+      const srowRes = await getLiveStreamResult(stream);
+      if (Result.isError(srowRes)) return srowRes;
+      const srow = srowRes.value;
+
+      const regRes = await registry.getRegistryResult(stream);
+      if (Result.isError(regRes)) return Result.err({ status: 500, message: regRes.error.message });
+      const profileRes = await profiles.getProfileResourceResult(stream, srow);
+      if (Result.isError(profileRes)) return Result.err({ status: 500, message: profileRes.error.message });
+
+      if (!detailsBuilder) return Result.err({ status: 500, message: "full-mode details store is not available" });
+      const payload = await detailsBuilder.buildPayload({
+        stream,
+        row: srow,
+        registry: regRes.value,
+        profileResource: profileRes.value,
+        mode,
+      });
+      const body = JSON.stringify(payload);
+      const afterVersion = notifier.currentDetailsVersion(stream);
+      if (beforeVersion === afterVersion) {
+        return Result.ok({
+          etag: weakEtag(mode, body),
+          body,
+          version: afterVersion,
+        });
+      }
+    }
+
+    return Result.err({ status: 500, message: "details changed too quickly" });
+  };
+
+  const fetch = async (req: Request): Promise<Response> => {
+    if (closing) {
+      return unavailable();
+    }
+    const requestAbortController = new AbortController();
+    const abortFromClient = () => requestAbortController.abort(req.signal.reason);
+    let timedOut = false;
+    if (req.signal.aborted) requestAbortController.abort(req.signal.reason);
+    else req.signal.addEventListener("abort", abortFromClient, { once: true });
+    try {
+      const runWithGate = async <T>(gate: ConcurrencyGate, fn: () => Promise<T>): Promise<T> =>
+        gate.run(fn, requestAbortController.signal);
+      const runForeground = async <T>(fn: () => Promise<T>): Promise<T> => {
+        const leaveForeground = foregroundActivity.enter();
+        try {
+          return await fn();
+        } finally {
+          leaveForeground();
+        }
+      };
+      const runForegroundWithGate = async <T>(gate: ConcurrencyGate, fn: () => Promise<T>): Promise<T> =>
+        runForeground(() => runWithGate(gate, fn));
+      const requestPromise = (async (): Promise<Response> => {
+      await ready;
+      let url: URL;
+      try {
+        url = new URL(req.url, "http://localhost");
+      } catch {
+        return badRequest("invalid url");
+      }
+      const path = url.pathname;
+
+      const handleOtlpTracesIngest = async (stream: string, autoCreate: boolean): Promise<Response> => {
+        if (req.method !== "POST") return badRequest("unsupported method");
+        const contentType = req.headers.get("content-type");
+        if (!contentType) return badRequest("missing content-type");
+        const leaveAppendPhase = memorySampler?.enter("append", {
+          route: "otlp_traces",
+          stream,
+          content_type: normalizeContentType(contentType) ?? contentType,
+        });
+        try {
+          return await runWithGate(ingestGate, async () => {
+            let srow = await controlStore.getStream(stream);
+            if (!srow && autoCreate) {
+              srow = await controlStore.ensureStream(stream, { contentType: "application/json" });
+              const profileRes = await profiles.updateProfileResult(stream, { kind: "otel-traces" });
+              if (Result.isError(profileRes)) return badRequest(profileRes.error.message);
+              try {
+                if (profileRes.value.schemaRegistry) {
+                  if (schemaPublication) await schemaPublication.publishProfileSchemaRegistry(stream, profileRes.value.schemaRegistry);
+                }
+              } catch {
+                return json(500, { error: { code: "internal", message: "profile upload failed" } });
+              }
+              indexer?.enqueue(stream);
+              notifier.notifyDetailsChanged(stream);
+              srow = await controlStore.getStream(stream);
+            }
+            if (!srow || controlStore.isDeleted(srow)) return notFound();
+            if (srow.expires_at_ms != null && controlStore.nowMs() > srow.expires_at_ms) return notFound("stream expired");
+
+            const profileRes = await profiles.getProfileResult(stream, srow);
+            if (Result.isError(profileRes)) return internalError("invalid stream profile");
+            const capability = resolveOtlpTracesCapability(profileRes.value);
+            if (!capability) return badRequest("stream profile does not support OTLP traces");
+
+            const ab = await req.arrayBuffer();
+            if (ab.byteLength > cfg.appendMaxBodyBytes) return tooLarge(`body too large (max ${cfg.appendMaxBodyBytes})`);
+            const bodyBytes = new Uint8Array(ab);
+            const decodedRes = capability.decodeExportRequestResult({
+              stream,
+              profile: profileRes.value,
+              contentType,
+              contentEncoding: req.headers.get("content-encoding"),
+              body: bodyBytes,
+              maxDecodedBytes: cfg.appendMaxBodyBytes,
+            });
+            if (Result.isError(decodedRes)) {
+              if (decodedRes.error.status === 415) return unsupportedMediaType(decodedRes.error.message);
+              if (decodedRes.error.status === 413) return tooLarge(decodedRes.error.message);
+              return badRequest(decodedRes.error.message);
+            }
+
+            const rowsRes = await buildPreparedJsonRows(stream, decodedRes.value.records);
+            if (Result.isError(rowsRes)) {
+              if (rowsRes.error.status === 500) return internalError(rowsRes.error.message);
+              return badRequest(rowsRes.error.message);
+            }
+            const rows = rowsRes.value.rows;
+            let appendHeaders: Record<string, string> = {};
+            if (rows.length > 0) {
+              const appendResOrResponse = await awaitAppendWithTimeout(enqueueAppend({
+                stream,
+                baseAppendMs: controlStore.nowMs(),
+                rows,
+                contentType: "application/json",
+                close: false,
+              }));
+              if (appendResOrResponse instanceof Response) return appendResOrResponse;
+              const appendRes = appendResOrResponse;
+              if (Result.isError(appendRes)) {
+                if (appendRes.error.kind === "overloaded") return overloaded();
+                if (appendRes.error.kind === "gone") return notFound("stream expired");
+                if (appendRes.error.kind === "not_found") return notFound();
+                if (appendRes.error.kind === "content_type_mismatch") return conflict("content-type mismatch");
+                return json(500, { error: { code: "internal", message: "append failed" } });
+              }
+              const appendBytes = rows.reduce((acc, row) => acc + row.payload.byteLength, 0);
+              recordAppendOutcome({
+                stream,
+                lastOffset: appendRes.value.lastOffset,
+                appendedRows: appendRes.value.appendedRows,
+                metricsBytes: appendBytes,
+                ingestedBytes: bodyBytes.byteLength,
+                touched: true,
+                closed: appendRes.value.closed,
+              });
+              appendHeaders = {
+                "stream-next-offset": encodeOffset(srow.epoch, appendRes.value.lastOffset),
+              };
+            }
+
+            const encoded = encodeOtlpTraceExportResponse(decodedRes.value);
+            const responseBody = encoded.body instanceof Uint8Array ? bodyBufferFromBytes(encoded.body) : encoded.body;
+            return new Response(responseBody, {
+              status: 200,
+              headers: withNosniff({
+                "content-type": encoded.contentType,
+                "cache-control": "no-store",
+                ...appendHeaders,
+              }),
+            });
+          });
+        } finally {
+          leaveAppendPhase?.();
+        }
+      };
+
+      const handleObserveRequest = async (): Promise<Response> => {
+        if (req.method !== "POST") return badRequest("unsupported method");
+        let body: unknown;
+        try {
+          body = await req.json();
+        } catch {
+          return badRequest("observe request must be valid JSON");
+        }
+        const requestRes = parseObserveRequestResult(body);
+        if (Result.isError(requestRes)) return badRequest(requestRes.error.message);
+        const observeReq = requestRes.value;
+
+        const loadCorrelationCapability = async (
+          stream: string,
+          role: "events" | "traces"
+        ): Promise<ReturnType<typeof resolveCorrelationCapability> | Response> => {
+          const srow = await controlStore.getStream(stream);
+          if (!srow || controlStore.isDeleted(srow)) return notFound();
+          if (srow.expires_at_ms != null && controlStore.nowMs() > srow.expires_at_ms) return notFound("stream expired");
+          const profileRes = await profiles.getProfileResult(stream, srow);
+          if (Result.isError(profileRes)) return internalError("invalid stream profile");
+          if (role === "events" && profileRes.value.kind !== "evlog") {
+            return badRequest(`streams.events must reference an evlog stream; ${stream} has profile ${profileRes.value.kind}`);
+          }
+          if (role === "traces" && profileRes.value.kind !== "otel-traces") {
+            return badRequest(`streams.traces must reference an otel-traces stream; ${stream} has profile ${profileRes.value.kind}`);
+          }
+          const capability = resolveCorrelationCapability(profileRes.value);
+          if (!capability) return badRequest(`stream ${stream} profile does not support observability correlation`);
+          const regRes = await registry.getRegistryResult(stream);
+          if (Result.isError(regRes)) return internalError(regRes.error.message);
+          if (!regRes.value.search) return badRequest(`stream ${stream} does not have search configured`);
+          return capability;
+        };
+
+        const eventCorrelation =
+          observeReq.include.events && observeReq.streams.events ? await loadCorrelationCapability(observeReq.streams.events, "events") : null;
+        if (eventCorrelation instanceof Response) return eventCorrelation;
+        const traceCorrelation =
+          observeReq.include.trace && observeReq.streams.traces ? await loadCorrelationCapability(observeReq.streams.traces, "traces") : null;
+        if (traceCorrelation instanceof Response) return traceCorrelation;
+
+        const runPagedSearch = async (
+          stream: string,
+          q: string,
+          limit: number,
+          sort: string[]
+        ): Promise<{ hits: SearchHit[]; batches: SearchResultBatch[]; limitReached: boolean; query: ObserveSearchQueryCoverage } | Response> => {
+          const regRes = await registry.getRegistryResult(stream);
+          if (Result.isError(regRes)) return internalError(regRes.error.message);
+          const hits: SearchHit[] = [];
+          const batches: SearchResultBatch[] = [];
+          const seenOffsets = new Set<string>();
+          let searchAfter: unknown[] | null = null;
+          let limitReached = false;
+          while (hits.length < limit) {
+            const size = Math.min(500, limit - hits.length);
+            const requestBody: Record<string, unknown> = {
+              q,
+              size,
+              sort,
+              timeout_ms: SEARCH_REQUEST_TIMEOUT_MS,
+            };
+            if (searchAfter) requestBody.search_after = searchAfter;
+            const parsedRes = parseSearchRequestBodyResult(regRes.value, requestBody);
+            if (Result.isError(parsedRes)) return badRequest(parsedRes.error.message);
+            const request = {
+              ...parsedRes.value,
+              timeoutMs: clampSearchRequestTimeoutMs(parsedRes.value.timeoutMs),
+            };
+            const searchRes = await runForegroundWithGate(searchGate, () => reader.searchResult({ stream, request }));
+            if (Result.isError(searchRes)) return readerErrorResponse(searchRes.error);
+            batches.push(searchRes.value);
+            for (const hit of searchRes.value.hits) {
+              if (seenOffsets.has(hit.offset)) continue;
+              seenOffsets.add(hit.offset);
+              hits.push(hit);
+              if (hits.length >= limit) break;
+            }
+            if (!searchRes.value.nextSearchAfter || searchRes.value.hits.length === 0) break;
+            searchAfter = searchRes.value.nextSearchAfter;
+            if (hits.length >= limit) {
+              limitReached = true;
+              break;
+            }
+          }
+          return { hits, batches, limitReached, query: summarizeSearchQueryCoverage(q, batches, hits, limitReached) };
+        };
+
+        const timeClauses = buildTimeSearchClauses(observeReq.time);
+        const lookupClause = (field: "req" | "trace" | "span", value: string) => `${field}:${quoteSearchValue(value)}`;
+        const eventSort = ["timestamp:desc", "offset:desc"];
+        const traceSort = ["timestamp:asc", "spanId:asc"];
+        let eventHits: SearchHit[] = [];
+        let eventBatches: SearchResultBatch[] = [];
+        const eventQueries: ObserveSearchQueryCoverage[] = [];
+        let eventLimitReached = false;
+        let traceHits: SearchHit[] = [];
+        let traceBatches: SearchResultBatch[] = [];
+        const traceQueries: ObserveSearchQueryCoverage[] = [];
+        let traceLimitReached = false;
+        const candidateTraceIds = new Set<string>();
+        const addTraceIdsFromHits = (hits: SearchHit[]) => {
+          for (const hit of hits) {
+            if (!isRecord(hit.source)) continue;
+            const traceId = typeof hit.source.traceId === "string" ? hit.source.traceId : null;
+            if (traceId) candidateTraceIds.add(traceId);
+          }
+        };
+        const appendSearch = (
+          target: "events" | "traces",
+          result: { hits: SearchHit[]; batches: SearchResultBatch[]; limitReached: boolean; query: ObserveSearchQueryCoverage }
+        ) => {
+          const stream = result.batches[0]?.stream ?? "";
+          if (target === "events") {
+            const seen = new Set(eventHits.map((hit) => `${(hit as SearchHit & { stream?: string }).stream ?? ""}\0${hit.offset}`));
+            for (const hit of result.hits) {
+              const key = `${stream}\0${hit.offset}`;
+              if (seen.has(key)) continue;
+              seen.add(key);
+              eventHits.push({ ...hit, stream } as SearchHit);
+            }
+            eventBatches.push(...result.batches);
+            eventQueries.push(result.query);
+            eventLimitReached = eventLimitReached || result.limitReached || eventHits.length >= observeReq.limits.events && !!result.batches.at(-1)?.nextSearchAfter;
+          } else {
+            const seen = new Set(traceHits.map((hit) => `${(hit as SearchHit & { stream?: string }).stream ?? ""}\0${hit.offset}`));
+            for (const hit of result.hits) {
+              const key = `${stream}\0${hit.offset}`;
+              if (seen.has(key)) continue;
+              seen.add(key);
+              traceHits.push({ ...hit, stream } as SearchHit);
+            }
+            traceBatches.push(...result.batches);
+            traceQueries.push(result.query);
+            traceLimitReached = traceLimitReached || result.limitReached || traceHits.length >= observeReq.limits.spans && !!result.batches.at(-1)?.nextSearchAfter;
+          }
+        };
+
+        const searchEvents = async (field: "req" | "trace" | "span", value: string): Promise<Response | null> => {
+          if (!observeReq.include.events || !observeReq.streams.events) return null;
+          if (eventHits.length >= observeReq.limits.events) return null;
+          const q = combineSearchClauses(lookupClause(field, value), ...timeClauses);
+          const result = await runPagedSearch(observeReq.streams.events, q, observeReq.limits.events - eventHits.length, eventSort);
+          if (result instanceof Response) return result;
+          appendSearch("events", result);
+          addTraceIdsFromHits(result.hits);
+          return null;
+        };
+
+        const searchTraces = async (field: "req" | "trace" | "span", value: string): Promise<Response | null> => {
+          if (!observeReq.include.trace || !observeReq.streams.traces) return null;
+          if (traceHits.length >= observeReq.limits.spans) return null;
+          const q = combineSearchClauses(lookupClause(field, value), ...timeClauses);
+          const result = await runPagedSearch(observeReq.streams.traces, q, observeReq.limits.spans - traceHits.length, traceSort);
+          if (result instanceof Response) return result;
+          appendSearch("traces", result);
+          addTraceIdsFromHits(result.hits);
+          return null;
+        };
+
+        if (observeReq.lookup.requestId) {
+          const eventResponse = await searchEvents("req", observeReq.lookup.requestId);
+          if (eventResponse) return eventResponse;
+          if (candidateTraceIds.size > 0) {
+            for (const traceId of candidateTraceIds) {
+              const traceResponse = await searchTraces("trace", traceId);
+              if (traceResponse) return traceResponse;
+            }
+          } else {
+            const traceResponse = await searchTraces("req", observeReq.lookup.requestId);
+            if (traceResponse) return traceResponse;
+          }
+        } else if (observeReq.lookup.traceId) {
+          candidateTraceIds.add(observeReq.lookup.traceId);
+          const traceResponse = await searchTraces("trace", observeReq.lookup.traceId);
+          if (traceResponse) return traceResponse;
+          const eventResponse = await searchEvents("trace", observeReq.lookup.traceId);
+          if (eventResponse) return eventResponse;
+        } else if (observeReq.lookup.spanId) {
+          const traceResponse = await searchTraces("span", observeReq.lookup.spanId);
+          if (traceResponse) return traceResponse;
+          if (candidateTraceIds.size > 0) {
+            for (const traceId of Array.from(candidateTraceIds)) {
+              const fullTraceResponse = await searchTraces("trace", traceId);
+              if (fullTraceResponse) return fullTraceResponse;
+              const eventResponse = await searchEvents("trace", traceId);
+              if (eventResponse) return eventResponse;
+            }
+          } else {
+            const eventResponse = await searchEvents("span", observeReq.lookup.spanId);
+            if (eventResponse) return eventResponse;
+          }
+        }
+
+        const eventCoverage = summarizeSearchCoverage(eventBatches, eventHits, eventLimitReached, eventQueries);
+        const traceCoverage = summarizeSearchCoverage(traceBatches, traceHits, traceLimitReached, traceQueries);
+        const trace = buildTraceDetails(
+          traceHits.map((hit) => hit.source),
+          { spanLimitReached: traceCoverage.limit_reached, coverageComplete: traceCoverage.complete }
+        );
+        const primaryEventHit = choosePrimaryEvent(eventHits, trace.traceId ?? observeReq.lookup.traceId);
+        const primaryEvent = primaryEventHit && isRecord(primaryEventHit.source) ? primaryEventHit.source : null;
+        const timeline: unknown[] = [];
+        if (observeReq.include.timeline) {
+          const items: any[] = [];
+          if (eventCorrelation && observeReq.streams.events) {
+            for (const hit of eventHits) {
+              items.push(...eventCorrelation.toTimelineItems({ stream: observeReq.streams.events, offset: hit.offset, record: hit.source }));
+            }
+          }
+          if (traceCorrelation && observeReq.streams.traces) {
+            for (const hit of traceHits) {
+              items.push(...traceCorrelation.toTimelineItems({ stream: observeReq.streams.traces, offset: hit.offset, record: hit.source }));
+            }
+          }
+          timeline.push(...sortTimeline(items));
+        }
+        const responsePrimaryEvent = observeReq.include.raw ? primaryEvent : compactEvlogRecord(primaryEvent);
+        const responseEventMatches = eventHits.map((hit) => ({
+          offset: hit.offset,
+          source: observeReq.include.raw ? hit.source : compactEvlogRecord(hit.source),
+        }));
+        const responseTraceSpans = observeReq.include.raw ? trace.spans : trace.spans.map((span) => compactTraceSpanRecord(span));
+        const responseTimeline = observeReq.include.raw ? timeline : timeline.map((item) => compactTimelineItem(item));
+
+        const warnings: string[] = [];
+        if (observeReq.include.trace && traceHits.length === 0) warnings.push("no trace spans found");
+        if (observeReq.include.events && eventHits.length === 0) warnings.push("no evlog events found");
+        if (eventCoverage.limit_reached) warnings.push("event limit reached");
+        if (traceCoverage.limit_reached) warnings.push("span limit reached");
+        if (!eventCoverage.complete && eventCoverage.searched) warnings.push("event search coverage incomplete");
+        if (!traceCoverage.complete && traceCoverage.searched) warnings.push("trace search coverage incomplete");
+        if (trace.missingParents.length > 0) warnings.push("trace has missing parent spans");
+
+        return json(200, {
+          lookup: {
+            requestId:
+              observeReq.lookup.requestId ??
+              (primaryEvent && typeof primaryEvent.requestId === "string" ? primaryEvent.requestId : null) ??
+              null,
+            traceId: observeReq.lookup.traceId ?? trace.traceId,
+            spanId: observeReq.lookup.spanId,
+          },
+          summary: buildObserveSummary({ lookup: observeReq.lookup, primaryEvent, trace }),
+          evlog: observeReq.include.events
+            ? {
+                stream: observeReq.streams.events ?? null,
+                primary: responsePrimaryEvent,
+                matches: responseEventMatches,
+              }
+            : null,
+          trace: observeReq.include.trace
+            ? {
+                stream: observeReq.streams.traces ?? null,
+                traceId: trace.traceId,
+                rootSpanId: trace.rootSpanId,
+                spans: responseTraceSpans,
+                tree: trace.tree,
+                serviceMap: trace.serviceMap,
+                criticalPath: trace.criticalPath,
+                errors: trace.errors,
+                partial: trace.partial,
+                missingParents: trace.missingParents,
+                duplicateSpans: trace.duplicateSpans,
+              }
+            : null,
+          timeline: responseTimeline,
+          coverage: {
+            events: eventCoverage,
+            traces: traceCoverage,
+            warnings,
+          },
+        });
+      };
+
+      if (path === "/health") {
+        return json(200, { ok: true });
+      }
+      if (path === "/metrics") {
+        return json(200, metrics.snapshot());
+      }
+      if (req.method === "GET" && path === "/v1/server/_details") {
+        return json(200, await buildServerDetails());
+      }
+      if (req.method === "GET" && path === "/v1/server/_mem") {
+        return json(200, await buildServerMem());
+      }
+      if (path === "/v1/traces") {
+        if (!controlStore.capabilities.builtinProfiles) return unsupportedCapability("built-in profile");
+        const stream = cfg.otlpTracesStream;
+        if (!stream) return badRequest("DS_OTLP_TRACES_STREAM is not configured");
+        return handleOtlpTracesIngest(stream, cfg.otlpAutoCreate);
+      }
+      if (path === "/v1/observe/request") {
+        if (!controlStore.capabilities.indexes) return unsupportedCapability("observe");
+        return handleObserveRequest();
+      }
+
+      // /v1/streams
+      if (req.method === "GET" && path === "/v1/streams") {
+        const limit = Number(url.searchParams.get("limit") ?? "100");
+        const offset = Number(url.searchParams.get("offset") ?? "0");
+        const rows = await controlStore.listStreams(Math.max(0, Math.min(limit, 1000)), Math.max(0, offset));
+        const out = [];
+        for (const r of rows) {
+          const profileRes = await profiles.getProfileResult(r.stream, r);
+          if (Result.isError(profileRes)) return internalError("invalid stream profile");
+          const profile = profileRes.value;
+          const observability = buildRequestObservabilityPairingDescriptor(r.stream, profile);
+          out.push({
+            name: r.stream,
+            created_at: new Date(Number(r.created_at_ms)).toISOString(),
+            expires_at: r.expires_at_ms == null ? null : new Date(Number(r.expires_at_ms)).toISOString(),
+            epoch: r.epoch,
+            next_offset: r.next_offset.toString(),
+            sealed_through: r.sealed_through.toString(),
+            uploaded_through: r.uploaded_through.toString(),
+            profile: profile.kind,
+            ...(observability ? { observability } : {}),
+          });
+        }
+        return json(200, out);
+      }
+
+      // /v1/stream/:name[/_schema|/_profile|/_details|/_index_status] (accept encoded or raw slashes in name)
+      const streamPrefix = "/v1/stream/";
+      if (path.startsWith(streamPrefix)) {
+        const rawRest = path.slice(streamPrefix.length);
+        const rest = rawRest.replace(/\/+$/, "");
+        if (rest.length === 0) return badRequest("missing stream name");
+        const segments = rest.split("/");
+        let isSchema = false;
+        let isProfile = false;
+        let isSearch = false;
+        let isAggregate = false;
+        let isDetails = false;
+        let isIndexStatus = false;
+        let isRoutingKeys = false;
+        let isOtlpTraces = false;
+        let pathKeyParam: string | null = null;
+        let touchMode: StreamTouchRoute | null = null;
+        if (
+          segments.length >= 3 &&
+          segments[segments.length - 3] === "_otlp" &&
+          segments[segments.length - 2] === "v1" &&
+          segments[segments.length - 1] === "traces"
+        ) {
+          isOtlpTraces = true;
+          segments.splice(segments.length - 3, 3);
+        } else if (segments[segments.length - 1] === "_schema") {
+          isSchema = true;
+          segments.pop();
+        } else if (segments[segments.length - 1] === "_profile") {
+          isProfile = true;
+          segments.pop();
+        } else if (segments[segments.length - 1] === "_search") {
+          isSearch = true;
+          segments.pop();
+        } else if (segments[segments.length - 1] === "_aggregate") {
+          isAggregate = true;
+          segments.pop();
+        } else if (segments[segments.length - 1] === "_details") {
+          isDetails = true;
+          segments.pop();
+        } else if (segments[segments.length - 1] === "_index_status") {
+          isIndexStatus = true;
+          segments.pop();
+        } else if (segments[segments.length - 1] === "_routing_keys") {
+          isRoutingKeys = true;
+          segments.pop();
+        } else if (
+          segments.length >= 3 &&
+          segments[segments.length - 3] === "touch" &&
+          segments[segments.length - 2] === "templates" &&
+          segments[segments.length - 1] === "activate"
+        ) {
+          touchMode = { kind: "templates_activate" };
+          segments.splice(segments.length - 3, 3);
+        } else if (segments.length >= 2 && segments[segments.length - 2] === "touch" && segments[segments.length - 1] === "meta") {
+          touchMode = { kind: "meta" };
+          segments.splice(segments.length - 2, 2);
+        } else if (segments.length >= 2 && segments[segments.length - 2] === "touch" && segments[segments.length - 1] === "wait") {
+          touchMode = { kind: "wait" };
+          segments.splice(segments.length - 2, 2);
+        } else if (segments.length >= 2 && segments[segments.length - 2] === "pk") {
+          pathKeyParam = decodeURIComponent(segments[segments.length - 1]);
+          segments.splice(segments.length - 2, 2);
+        }
+        const streamPart = segments.join("/");
+        if (streamPart.length === 0) return badRequest("missing stream name");
+        const stream = decodeURIComponent(streamPart);
+
+        if (isOtlpTraces) {
+          if (!controlStore.capabilities.builtinProfiles) return unsupportedCapability("built-in profile");
+          return handleOtlpTracesIngest(stream, false);
+        }
+
+        if (isSchema) {
+          const srow = await controlStore.getStream(stream);
+          if (!srow || controlStore.isDeleted(srow)) return notFound();
+          if (srow.expires_at_ms != null && controlStore.nowMs() > srow.expires_at_ms) return notFound("stream expired");
+
+          if (req.method === "GET") {
+            const regRes = await registry.getRegistryResult(stream);
+            if (Result.isError(regRes)) return schemaReadErrorResponse(regRes.error);
+            return json(200, regRes.value);
+          }
+          if (req.method === "POST") {
+            let body: unknown;
+            try {
+              body = await req.json();
+            } catch {
+              return badRequest("schema update must be valid JSON");
+            }
+            const updateRes = parseSchemaUpdateResult(body);
+            if (Result.isError(updateRes)) return badRequest(updateRes.error.message);
+            const update = updateRes.value;
+            if (update.search !== undefined && !controlStore.capabilities.indexes) {
+              return unsupportedCapability("index");
+            }
+            if (update.schema === undefined && update.routingKey !== undefined && update.search === undefined) {
+              const regRes = await registry.updateRoutingKeyResult(stream, update.routingKey ?? null);
+              if (Result.isError(regRes)) return schemaMutationErrorResponse(regRes.error);
+              try {
+                if (schemaPublication) await schemaPublication.uploadSchemaRegistry(stream, regRes.value);
+              } catch {
+                return json(500, { error: { code: "internal", message: "schema upload failed" } });
+              }
+              indexer?.enqueue(stream);
+              notifier.notifyDetailsChanged(stream);
+              return json(200, regRes.value);
+            }
+            if (update.schema === undefined && update.search !== undefined && update.routingKey === undefined) {
+              const regRes = await registry.updateSearchResult(stream, update.search ?? null);
+              if (Result.isError(regRes)) return schemaMutationErrorResponse(regRes.error);
+              try {
+                if (schemaPublication) await schemaPublication.uploadSchemaRegistry(stream, regRes.value);
+              } catch {
+                return json(500, { error: { code: "internal", message: "schema upload failed" } });
+              }
+              indexer?.enqueue(stream);
+              notifier.notifyDetailsChanged(stream);
+              return json(200, regRes.value);
+            }
+            const regRes = await registry.updateRegistryResult(stream, {
+              schema: update.schema,
+              lens: update.lens,
+              routingKey: update.routingKey ?? undefined,
+              search: update.search,
+            });
+            if (Result.isError(regRes)) return schemaMutationErrorResponse(regRes.error);
+            try {
+              if (schemaPublication) await schemaPublication.uploadSchemaRegistry(stream, regRes.value);
+            } catch {
+              return json(500, { error: { code: "internal", message: "schema upload failed" } });
+            }
+            indexer?.enqueue(stream);
+            notifier.notifyDetailsChanged(stream);
+            return json(200, regRes.value);
+          }
+          return badRequest("unsupported method");
+        }
+
+        if (isProfile) {
+          const srowOrResponse = await liveStreamOrResponse(stream);
+          if (srowOrResponse instanceof Response) return srowOrResponse;
+          const srow = srowOrResponse;
+
+          if (req.method === "GET") {
+            const profileRes = await profiles.getProfileResourceResult(stream, srow);
+            if (Result.isError(profileRes)) return internalError("invalid stream profile");
+            return json(200, profileRes.value);
+          }
+
+          if (req.method === "POST") {
+            let body: any;
+            try {
+              body = await req.json();
+            } catch {
+              return badRequest("profile update must be valid JSON");
+            }
+            const nextProfileRes = parseProfileUpdateResult(body);
+            if (Result.isError(nextProfileRes)) return badRequest(nextProfileRes.error.message);
+            if (nextProfileRes.value.kind !== "generic" && !controlStore.capabilities.builtinProfiles) {
+              return unsupportedCapability("built-in profile");
+            }
+            const profileRes = await profiles.updateProfileResult(stream, nextProfileRes.value);
+            if (Result.isError(profileRes)) return badRequest(profileRes.error.message);
+            try {
+              if (profileRes.value.schemaRegistry) {
+                if (schemaPublication) await schemaPublication.publishProfileSchemaRegistry(stream, profileRes.value.schemaRegistry);
+              }
+            } catch {
+              return json(500, { error: { code: "internal", message: "profile upload failed" } });
+            }
+            indexer?.enqueue(stream);
+            notifier.notifyDetailsChanged(stream);
+            return json(200, profileRes.value.resource);
+          }
+
+          return badRequest("unsupported method");
+        }
+
+        if (isDetails || isIndexStatus) {
+          if (req.method !== "GET") return badRequest("unsupported method");
+          if (isDetails && !controlStore.capabilities.storageStats) return unsupportedCapability("storage stats");
+          if (isDetails && !controlStore.capabilities.objectStoreAccounting) return unsupportedCapability("object-store accounting");
+          if (isIndexStatus && !controlStore.capabilities.indexes) return unsupportedCapability("index");
+          const liveParam = url.searchParams.get("live") ?? "";
+          let longPoll = false;
+          if (liveParam === "" || liveParam === "false" || liveParam === "0") longPoll = false;
+          else if (liveParam === "long-poll" || liveParam === "true" || liveParam === "1") longPoll = true;
+          else return badRequest("invalid live mode");
+
+          const timeout = url.searchParams.get("timeout") ?? url.searchParams.get("timeout_ms");
+          let timeoutMs: number | null = null;
+          if (timeout) {
+            if (/^[0-9]+$/.test(timeout)) {
+              timeoutMs = Number(timeout);
+            } else {
+              const timeoutRes = parseDurationMsResult(timeout);
+              if (Result.isError(timeoutRes)) return badRequest("invalid timeout");
+              timeoutMs = timeoutRes.value;
+            }
+          }
+
+          const loadSnapshot = async (): Promise<Response | DetailsSnapshot> => {
+            const snapshotRes = await buildDetailsSnapshotResult(stream, isIndexStatus ? "index_status" : "details");
+            if (Result.isError(snapshotRes)) {
+              if (snapshotRes.error.status === 404) {
+                return snapshotRes.error.message === "stream expired" ? notFound("stream expired") : notFound();
+              }
+              return internalError(snapshotRes.error.message);
+            }
+            return snapshotRes.value;
+          };
+
+          let snapshotOrResponse = await loadSnapshot();
+          if (snapshotOrResponse instanceof Response) return snapshotOrResponse;
+          let snapshot = snapshotOrResponse;
+          const ifNoneMatch = req.headers.get("if-none-match");
+
+          if (!longPoll) {
+            if (ifNoneMatch && ifNoneMatch === snapshot.etag) {
+              return new Response(null, {
+                status: 304,
+                headers: withNosniff({ "cache-control": "no-store", etag: snapshot.etag }),
+              });
+            }
+            return new Response(snapshot.body, {
+              status: 200,
+              headers: withNosniff({
+                "content-type": "application/json; charset=utf-8",
+                "cache-control": "no-store",
+                etag: snapshot.etag,
+              }),
+            });
+          }
+
+          if (!ifNoneMatch || ifNoneMatch !== snapshot.etag) {
+            return new Response(snapshot.body, {
+              status: 200,
+              headers: withNosniff({
+                "content-type": "application/json; charset=utf-8",
+                "cache-control": "no-store",
+                etag: snapshot.etag,
+              }),
+            });
+          }
+
+          const deadline = Date.now() + (timeoutMs ?? 3000);
+          while (ifNoneMatch === snapshot.etag) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+              return new Response(null, {
+                status: 304,
+                headers: withNosniff({ "cache-control": "no-store", etag: snapshot.etag }),
+              });
+            }
+            await notifier.waitForDetailsChange(stream, snapshot.version, remaining, req.signal);
+            if (req.signal.aborted) return new Response(null, { status: 204 });
+            snapshotOrResponse = await loadSnapshot();
+            if (snapshotOrResponse instanceof Response) return snapshotOrResponse;
+            snapshot = snapshotOrResponse;
+          }
+
+          return new Response(snapshot.body, {
+            status: 200,
+            headers: withNosniff({
+              "content-type": "application/json; charset=utf-8",
+              "cache-control": "no-store",
+              etag: snapshot.etag,
+            }),
+          });
+        }
+
+        if (isRoutingKeys) {
+          if (!controlStore.capabilities.indexes) return unsupportedCapability("routing key index");
+          const srowOrResponse = await liveStreamOrResponse(stream);
+          if (srowOrResponse instanceof Response) return srowOrResponse;
+          const srow = srowOrResponse;
+          if (req.method !== "GET") return badRequest("unsupported method");
+          const regRes = await registry.getRegistryResult(stream);
+          if (Result.isError(regRes)) return internalError();
+          if (regRes.value.routingKey == null) return badRequest("routing key not configured");
+          const limitRaw = url.searchParams.get("limit");
+          const limit = limitRaw == null ? 100 : Number(limitRaw);
+          if (!Number.isFinite(limit) || limit <= 0 || !Number.isInteger(limit) || limit > 500) return badRequest("invalid limit");
+          const after = url.searchParams.get("after");
+          const listRes = indexer?.listRoutingKeysResult
+            ? await runForeground(() => indexer.listRoutingKeysResult!(stream, after, limit))
+            : Result.err({ kind: "invalid_lexicon_index", message: "routing key lexicon unavailable" });
+          if (Result.isError(listRes)) return internalError(listRes.error.message);
+          return json(200, {
+            stream,
+            source: {
+              kind: "routing_key",
+              name: "",
+            },
+            took_ms: listRes.value.tookMs,
+            coverage: {
+              complete: listRes.value.coverage.complete,
+              indexed_segments: listRes.value.coverage.indexedSegments,
+              scanned_uploaded_segments: listRes.value.coverage.scannedUploadedSegments,
+              scanned_local_segments: listRes.value.coverage.scannedLocalSegments,
+              scanned_wal_rows: listRes.value.coverage.scannedWalRows,
+              possible_missing_uploaded_segments: listRes.value.coverage.possibleMissingUploadedSegments,
+              possible_missing_local_segments: listRes.value.coverage.possibleMissingLocalSegments,
+            },
+            timing: {
+              lexicon_run_get_ms: listRes.value.timing.lexiconRunGetMs,
+              lexicon_decode_ms: listRes.value.timing.lexiconDecodeMs,
+              lexicon_enumerate_ms: listRes.value.timing.lexiconEnumerateMs,
+              lexicon_merge_ms: listRes.value.timing.lexiconMergeMs,
+              fallback_scan_ms: listRes.value.timing.fallbackScanMs,
+              fallback_segment_get_ms: listRes.value.timing.fallbackSegmentGetMs,
+              fallback_wal_scan_ms: listRes.value.timing.fallbackWalScanMs,
+              lexicon_runs_loaded: listRes.value.timing.lexiconRunsLoaded,
+            },
+            keys: listRes.value.keys,
+            next_after: listRes.value.nextAfter,
+          });
+        }
+
+        if (isSearch) {
+          if (!controlStore.capabilities.indexes) return unsupportedCapability("search");
+          const srowOrResponse = await liveStreamOrResponse(stream);
+          if (srowOrResponse instanceof Response) return srowOrResponse;
+          const srow = srowOrResponse;
+
+          const regRes = await registry.getRegistryResult(stream);
+          if (Result.isError(regRes)) return internalError();
+
+          const respondSearch = async (requestBody: unknown, fromQuery: boolean): Promise<Response> => {
+            const requestRes = fromQuery
+              ? parseSearchRequestQueryResult(regRes.value, url.searchParams)
+              : parseSearchRequestBodyResult(regRes.value, requestBody);
+            if (Result.isError(requestRes)) return badRequest(requestRes.error.message);
+            const request = {
+              ...requestRes.value,
+              timeoutMs: clampSearchRequestTimeoutMs(requestRes.value.timeoutMs),
+            };
+            const searchRes = await runForegroundWithGate(searchGate, () => reader.searchResult({ stream, request }));
+            if (Result.isError(searchRes)) return readerErrorResponse(searchRes.error);
+            const status = searchRes.value.timedOut ? 408 : 200;
+            return json(status, {
+              stream,
+              snapshot_end_offset: searchRes.value.snapshotEndOffset,
+              took_ms: searchRes.value.tookMs,
+              timed_out: searchRes.value.timedOut,
+              timeout_ms: searchRes.value.timeoutMs,
+              coverage: {
+                mode: searchRes.value.coverage.mode,
+                complete: searchRes.value.coverage.complete,
+                stream_head_offset: searchRes.value.coverage.streamHeadOffset,
+                visible_through_offset: searchRes.value.coverage.visibleThroughOffset,
+                visible_through_primary_timestamp_max: searchRes.value.coverage.visibleThroughPrimaryTimestampMax,
+                oldest_omitted_append_at: searchRes.value.coverage.oldestOmittedAppendAt,
+                possible_missing_events_upper_bound: searchRes.value.coverage.possibleMissingEventsUpperBound,
+                possible_missing_uploaded_segments: searchRes.value.coverage.possibleMissingUploadedSegments,
+                possible_missing_sealed_rows: searchRes.value.coverage.possibleMissingSealedRows,
+                possible_missing_wal_rows: searchRes.value.coverage.possibleMissingWalRows,
+                indexed_segments: searchRes.value.coverage.indexedSegments,
+                indexed_segment_time_ms: searchRes.value.coverage.indexedSegmentTimeMs,
+                fts_section_get_ms: searchRes.value.coverage.ftsSectionGetMs,
+                fts_decode_ms: searchRes.value.coverage.ftsDecodeMs,
+                fts_clause_estimate_ms: searchRes.value.coverage.ftsClauseEstimateMs,
+                scanned_segments: searchRes.value.coverage.scannedSegments,
+                scanned_segment_time_ms: searchRes.value.coverage.scannedSegmentTimeMs,
+                scanned_tail_docs: searchRes.value.coverage.scannedTailDocs,
+                scanned_tail_time_ms: searchRes.value.coverage.scannedTailTimeMs,
+                exact_candidate_time_ms: searchRes.value.coverage.exactCandidateTimeMs,
+                candidate_doc_ids: searchRes.value.coverage.candidateDocIds,
+                decoded_records: searchRes.value.coverage.decodedRecords,
+                json_parse_time_ms: searchRes.value.coverage.jsonParseTimeMs,
+                segment_payload_bytes_fetched: searchRes.value.coverage.segmentPayloadBytesFetched,
+                sort_time_ms: searchRes.value.coverage.sortTimeMs,
+                peak_hits_held: searchRes.value.coverage.peakHitsHeld,
+                index_families_used: searchRes.value.coverage.indexFamiliesUsed,
+              },
+              total: searchRes.value.total,
+              hits: searchRes.value.hits,
+              next_search_after: searchRes.value.nextSearchAfter,
+            }, searchResponseHeaders(searchRes.value));
+          };
+
+          if (req.method === "GET") {
+            return respondSearch(null, true);
+          }
+
+          if (req.method === "POST") {
+            let body: unknown;
+            try {
+              body = await req.json();
+            } catch {
+              return badRequest("search request must be valid JSON");
+            }
+            return respondSearch(body, false);
+          }
+
+          return badRequest("unsupported method");
+        }
+
+        if (isAggregate) {
+          if (!controlStore.capabilities.indexes) return unsupportedCapability("aggregate");
+          const srowOrResponse = await liveStreamOrResponse(stream);
+          if (srowOrResponse instanceof Response) return srowOrResponse;
+          const srow = srowOrResponse;
+          if (req.method !== "POST") return badRequest("unsupported method");
+
+          const regRes = await registry.getRegistryResult(stream);
+          if (Result.isError(regRes)) return internalError();
+
+          let body: unknown;
+          try {
+            body = await req.json();
+          } catch {
+            return badRequest("aggregate request must be valid JSON");
+          }
+
+          const requestRes = parseAggregateRequestBodyResult(regRes.value, body);
+          if (Result.isError(requestRes)) return badRequest(requestRes.error.message);
+          const aggregateRes = await runForegroundWithGate(searchGate, () => reader.aggregateResult({ stream, request: requestRes.value }));
+          if (Result.isError(aggregateRes)) return readerErrorResponse(aggregateRes.error);
+          return json(200, {
+            stream,
+            rollup: aggregateRes.value.rollup,
+            from: aggregateRes.value.from,
+            to: aggregateRes.value.to,
+            interval: aggregateRes.value.interval,
+              coverage: {
+                mode: aggregateRes.value.coverage.mode,
+                complete: aggregateRes.value.coverage.complete,
+                stream_head_offset: aggregateRes.value.coverage.streamHeadOffset,
+                visible_through_offset: aggregateRes.value.coverage.visibleThroughOffset,
+                visible_through_primary_timestamp_max: aggregateRes.value.coverage.visibleThroughPrimaryTimestampMax,
+                oldest_omitted_append_at: aggregateRes.value.coverage.oldestOmittedAppendAt,
+                possible_missing_events_upper_bound: aggregateRes.value.coverage.possibleMissingEventsUpperBound,
+                possible_missing_uploaded_segments: aggregateRes.value.coverage.possibleMissingUploadedSegments,
+                possible_missing_sealed_rows: aggregateRes.value.coverage.possibleMissingSealedRows,
+              possible_missing_wal_rows: aggregateRes.value.coverage.possibleMissingWalRows,
+              used_rollups: aggregateRes.value.coverage.usedRollups,
+              indexed_segments: aggregateRes.value.coverage.indexedSegments,
+              scanned_segments: aggregateRes.value.coverage.scannedSegments,
+              scanned_tail_docs: aggregateRes.value.coverage.scannedTailDocs,
+              index_families_used: aggregateRes.value.coverage.indexFamiliesUsed,
+            },
+            buckets: aggregateRes.value.buckets,
+          });
+        }
+
+        if (touchMode) {
+          if (!controlStore.capabilities.touch || !touch || !touchStore) return unsupportedCapability("touch");
+          const srowOrResponse = await liveStreamOrResponse(stream);
+          if (srowOrResponse instanceof Response) return srowOrResponse;
+          const srow = srowOrResponse;
+
+          const profileRes = await profiles.getProfileResult(stream, srow);
+          if (Result.isError(profileRes)) return internalError("invalid stream profile");
+          const touchCapability = resolveTouchCapability(profileRes.value);
+          if (!touchCapability?.handleRoute) return notFound("touch not enabled");
+          return touchCapability.handleRoute({
+            route: touchMode,
+            req,
+            stream,
+            streamRow: srow,
+            profile: profileRes.value,
+            db: touchStore,
+            touchManager: touch,
+            respond: { json, badRequest, internalError, notFound },
+          });
+        }
+
+        // Stream lifecycle.
+        if (req.method === "PUT") {
+          const streamClosed = parseStreamClosedHeader(req.headers.get("stream-closed"));
+          const ttlHeader = req.headers.get("stream-ttl");
+          const expiresHeader = req.headers.get("stream-expires-at");
+          if (ttlHeader && expiresHeader) return badRequest("only one of Stream-TTL or Stream-Expires-At is allowed");
+
+          let ttlSeconds: number | null = null;
+          let expiresAtMs: bigint | null = null;
+          if (ttlHeader) {
+            const ttlRes = parseStreamTtlSeconds(ttlHeader);
+            if (Result.isError(ttlRes)) return badRequest(ttlRes.error.message);
+            ttlSeconds = ttlRes.value;
+            expiresAtMs = controlStore.nowMs() + BigInt(ttlSeconds) * 1000n;
+          } else if (expiresHeader) {
+            const expiresRes = parseTimestampMsResult(expiresHeader);
+            if (Result.isError(expiresRes)) return badRequest(expiresRes.error.message);
+            expiresAtMs = expiresRes.value;
+          }
+
+          const contentType = normalizeContentType(req.headers.get("content-type")) ?? "application/octet-stream";
+          const routingKeyHeader = req.headers.get("stream-key");
+          const leaveAppendPhase = memorySampler?.enter("append", {
+            route: "put",
+            stream,
+            content_type: contentType,
+          });
+          try {
+            return await runWithGate(ingestGate, async () => {
+              const ab = await req.arrayBuffer();
+              if (ab.byteLength > cfg.appendMaxBodyBytes) return tooLarge(`body too large (max ${cfg.appendMaxBodyBytes})`);
+              const bodyBytes = new Uint8Array(ab);
+
+              let srow = await controlStore.getStream(stream);
+              if (srow && controlStore.isDeleted(srow)) {
+                await controlStore.hardDeleteStream(stream);
+                srow = null;
+              }
+              if (srow && srow.expires_at_ms != null && controlStore.nowMs() > srow.expires_at_ms) {
+                await controlStore.hardDeleteStream(stream);
+                srow = null;
+              }
+
+              if (srow) {
+                const existingClosed = srow.closed !== 0;
+                const existingContentType = normalizeContentType(srow.content_type) ?? srow.content_type;
+                const ttlMatch =
+                  ttlSeconds != null
+                    ? srow.ttl_seconds != null && srow.ttl_seconds === ttlSeconds
+                    : expiresAtMs != null
+                      ? srow.ttl_seconds == null && srow.expires_at_ms != null && srow.expires_at_ms === expiresAtMs
+                      : srow.ttl_seconds == null && srow.expires_at_ms == null;
+                if (existingContentType !== contentType || existingClosed !== streamClosed || !ttlMatch) {
+                  return conflict("stream config mismatch");
+                }
+
+                const tailOffset = encodeOffset(srow.epoch, srow.next_offset - 1n);
+                const headers: Record<string, string> = {
+                  "content-type": existingContentType,
+                  "stream-next-offset": tailOffset,
+                };
+                if (existingClosed) headers["stream-closed"] = "true";
+                if (srow.expires_at_ms != null) headers["stream-expires-at"] = new Date(Number(srow.expires_at_ms)).toISOString();
+                return new Response(null, { status: 200, headers: appendResponseHeaders(headers) });
+              }
+
+              await controlStore.ensureStream(stream, { contentType, expiresAtMs, ttlSeconds, closed: false });
+              notifier.notifyDetailsChanged(stream);
+              let lastOffset = -1n;
+              let appendedRows = 0;
+              let closedNow = false;
+
+              if (bodyBytes.byteLength > 0) {
+                const rowsRes = await buildAppendRowsResult(stream, bodyBytes, contentType, routingKeyHeader, true);
+                if (Result.isError(rowsRes)) {
+                  if (rowsRes.error.status === 500) return internalError();
+                  return badRequest(rowsRes.error.message);
+                }
+                const rows = rowsRes.value.rows;
+                appendedRows = rows.length;
+                if (rows.length > 0 || streamClosed) {
+                  const appendResOrResponse = await awaitAppendWithTimeout(enqueueAppend({
+                    stream,
+                    baseAppendMs: controlStore.nowMs(),
+                    rows,
+                    contentType,
+                    close: streamClosed,
+                  }));
+                  if (appendResOrResponse instanceof Response) return appendResOrResponse;
+                  const appendRes = appendResOrResponse;
+                  if (Result.isError(appendRes)) {
+                    if (appendRes.error.kind === "overloaded") return overloaded();
+                    return json(500, { error: { code: "internal", message: "append failed" } });
+                  }
+                  lastOffset = appendRes.value.lastOffset;
+                  closedNow = appendRes.value.closed;
+                }
+              } else if (streamClosed) {
+                const appendResOrResponse = await awaitAppendWithTimeout(enqueueAppend({
+                  stream,
+                  baseAppendMs: controlStore.nowMs(),
+                  rows: [],
+                  contentType,
+                  close: true,
+                }));
+                if (appendResOrResponse instanceof Response) return appendResOrResponse;
+                const appendRes = appendResOrResponse;
+                if (Result.isError(appendRes)) {
+                  if (appendRes.error.kind === "overloaded") return overloaded();
+                  return json(500, { error: { code: "internal", message: "close failed" } });
+                }
+                lastOffset = appendRes.value.lastOffset;
+                closedNow = appendRes.value.closed;
+              }
+
+              recordAppendOutcome({
+                stream,
+                lastOffset,
+                appendedRows,
+                metricsBytes: bodyBytes.byteLength,
+                ingestedBytes: bodyBytes.byteLength,
+                touched: bodyBytes.byteLength > 0 || streamClosed,
+                closed: closedNow,
+              });
+
+              const createdRow = (await controlStore.getStream(stream))!;
+              const tailOffset = encodeOffset(createdRow.epoch, createdRow.next_offset - 1n);
+              const headers: Record<string, string> = {
+                "content-type": contentType,
+                "stream-next-offset": appendedRows > 0 || streamClosed ? encodeOffset(createdRow.epoch, lastOffset) : tailOffset,
+                location: req.url,
+              };
+              if (streamClosed || closedNow) headers["stream-closed"] = "true";
+              if (createdRow.expires_at_ms != null) headers["stream-expires-at"] = new Date(Number(createdRow.expires_at_ms)).toISOString();
+              return new Response(null, { status: 201, headers: appendResponseHeaders(headers) });
+            });
+          } finally {
+            leaveAppendPhase?.();
+          }
+        }
+
+        if (req.method === "DELETE") {
+          const deleted = await controlStore.deleteStream(stream);
+          if (!deleted) return notFound();
+          notifier.notifyDetailsChanged(stream);
+          notifier.notifyClose(stream);
+          await fullMode?.manifestPublication?.publishDeletedStreamManifest(stream);
+          return new Response(null, { status: 204, headers: withNosniff() });
+        }
+
+        if (req.method === "HEAD") {
+          const srowOrResponse = await liveStreamOrResponse(stream);
+          if (srowOrResponse instanceof Response) return srowOrResponse;
+          const srow = srowOrResponse;
+          const tailOffset = encodeOffset(srow.epoch, srow.next_offset - 1n);
+          const headers: Record<string, string> = {
+            "content-type": normalizeContentType(srow.content_type) ?? srow.content_type,
+            "stream-next-offset": tailOffset,
+            "stream-end-offset": tailOffset,
+            "cache-control": "no-store",
+          };
+          if (srow.closed !== 0) headers["stream-closed"] = "true";
+          if (srow.ttl_seconds != null && srow.expires_at_ms != null) {
+            const remainingMs = Number(srow.expires_at_ms - controlStore.nowMs());
+            const remaining = Math.max(0, Math.ceil(remainingMs / 1000));
+            headers["stream-ttl"] = String(remaining);
+          }
+          if (srow.expires_at_ms != null) headers["stream-expires-at"] = new Date(Number(srow.expires_at_ms)).toISOString();
+          return new Response(null, { status: 200, headers: withNosniff(headers) });
+        }
+
+        if (req.method === "POST") {
+          const srowOrResponse = await liveStreamOrResponse(stream);
+          if (srowOrResponse instanceof Response) return srowOrResponse;
+          const srow = srowOrResponse;
+
+          const streamClosed = parseStreamClosedHeader(req.headers.get("stream-closed"));
+          const streamContentType = normalizeContentType(srow.content_type) ?? srow.content_type;
+
+          const producerId = req.headers.get("producer-id");
+          const producerEpochHeader = req.headers.get("producer-epoch");
+          const producerSeqHeader = req.headers.get("producer-seq");
+          let producer: ProducerInfo | null = null;
+          if (producerId != null || producerEpochHeader != null || producerSeqHeader != null) {
+            if (!producerId || producerId.trim() === "") return badRequest("invalid Producer-Id");
+            if (!producerEpochHeader || !producerSeqHeader) return badRequest("missing producer headers");
+            const epoch = parseNonNegativeInt(producerEpochHeader);
+            const seq = parseNonNegativeInt(producerSeqHeader);
+            if (epoch == null || seq == null) return badRequest("invalid producer headers");
+            producer = { id: producerId, epoch, seq };
+          }
+
+          let streamSeq: string | null = null;
+          const streamSeqRes = parseStreamSeqHeader(req.headers.get("stream-seq"));
+          if (Result.isError(streamSeqRes)) return badRequest(streamSeqRes.error.message);
+          streamSeq = streamSeqRes.value;
+
+          const tsHdr = req.headers.get("stream-timestamp");
+          let baseAppendMs = controlStore.nowMs();
+          if (tsHdr) {
+            const tsRes = parseTimestampMsResult(tsHdr);
+            if (Result.isError(tsRes)) return badRequest(tsRes.error.message);
+            baseAppendMs = tsRes.value;
+          }
+
+          const leaveAppendPhase = memorySampler?.enter("append", {
+            route: "post",
+            stream,
+            stream_content_type: streamContentType,
+          });
+          let appendBodyBytesForGc = 0;
+          try {
+            const response = await runWithGate(ingestGate, async () => {
+              const ab = await req.arrayBuffer();
+              if (ab.byteLength > cfg.appendMaxBodyBytes) return tooLarge(`body too large (max ${cfg.appendMaxBodyBytes})`);
+              const bodyBytes = new Uint8Array(ab);
+              appendBodyBytesForGc = bodyBytes.byteLength;
+
+              const isCloseOnly = streamClosed && bodyBytes.byteLength === 0;
+              if (bodyBytes.byteLength === 0 && !streamClosed) return badRequest("empty body");
+
+              let reqContentType = normalizeContentType(req.headers.get("content-type"));
+              if (!isCloseOnly && !reqContentType) return badRequest("missing content-type");
+
+              const routingKeyHeader = req.headers.get("stream-key");
+              let rows: AppendRow[] = [];
+              if (!isCloseOnly) {
+                const rowsRes = await buildAppendRowsResult(stream, bodyBytes, reqContentType!, routingKeyHeader, false);
+                if (Result.isError(rowsRes)) {
+                  if (rowsRes.error.status === 500) return internalError();
+                  return badRequest(rowsRes.error.message);
+                }
+                rows = rowsRes.value.rows;
+              }
+
+              const appendResOrResponse = await awaitAppendWithTimeout(enqueueAppend({
+                stream,
+                baseAppendMs,
+                rows,
+                contentType: reqContentType ?? streamContentType,
+                streamSeq,
+                producer,
+                close: streamClosed,
+              }));
+              if (appendResOrResponse instanceof Response) return appendResOrResponse;
+              const appendRes = appendResOrResponse;
+
+              if (Result.isError(appendRes)) {
+                const err = appendRes.error;
+                if (err.kind === "overloaded") return overloaded();
+                if (err.kind === "gone") return notFound("stream expired");
+                if (err.kind === "not_found") return notFound();
+                if (err.kind === "content_type_mismatch") return conflict("content-type mismatch");
+                if (err.kind === "stream_seq") {
+                  return conflict("sequence mismatch", {
+                    "stream-expected-seq": err.expected,
+                    "stream-received-seq": err.received,
+                  });
+                }
+                if (err.kind === "closed") {
+                  const headers: Record<string, string> = {
+                    "stream-next-offset": encodeOffset(srow.epoch, err.lastOffset),
+                    "stream-closed": "true",
+                  };
+                  return new Response(null, { status: 409, headers: appendResponseHeaders(headers) });
+                }
+                if (err.kind === "producer_stale_epoch") {
+                  return new Response(null, {
+                    status: 403,
+                    headers: appendResponseHeaders({ "producer-epoch": String(err.producerEpoch) }),
+                  });
+                }
+                if (err.kind === "producer_gap") {
+                  return new Response(null, {
+                    status: 409,
+                    headers: appendResponseHeaders({
+                      "producer-expected-seq": String(err.expected),
+                      "producer-received-seq": String(err.received),
+                    }),
+                  });
+                }
+                if (err.kind === "producer_epoch_seq") return badRequest("invalid producer sequence");
+                return json(500, { error: { code: "internal", message: "append failed" } });
+              }
+              const res = appendRes.value;
+
+              const appendBytes = rows.reduce((acc, r) => acc + r.payload.byteLength, 0);
+              recordAppendOutcome({
+                stream,
+                lastOffset: res.lastOffset,
+                appendedRows: res.appendedRows,
+                metricsBytes: appendBytes,
+                ingestedBytes: bodyBytes.byteLength,
+                touched: true,
+                closed: res.closed,
+              });
+
+              const headers: Record<string, string> = {
+                "stream-next-offset": encodeOffset(srow.epoch, res.lastOffset),
+              };
+              if (res.closed) headers["stream-closed"] = "true";
+              if (producer && res.producer) {
+                headers["producer-epoch"] = String(res.producer.epoch);
+                headers["producer-seq"] = String(res.producer.seq);
+              }
+
+              const status = producer && res.appendedRows > 0 ? 200 : 204;
+              return new Response(null, { status, headers: appendResponseHeaders(headers) });
+            });
+            maybeCollectAfterHttpAppend(appendBodyBytesForGc);
+            return response;
+          } finally {
+            leaveAppendPhase?.();
+          }
+        }
+
+        if (req.method === "GET") {
+          const srowOrResponse = await liveStreamOrResponse(stream);
+          if (srowOrResponse instanceof Response) return srowOrResponse;
+          const srow = srowOrResponse;
+
+          const streamContentType = normalizeContentType(srow.content_type) ?? srow.content_type;
+          const isJsonStream = streamContentType === "application/json";
+
+          const fmtParam = url.searchParams.get("format");
+          let format: "raw" | "json" = isJsonStream ? "json" : "raw";
+          if (fmtParam) {
+            if (fmtParam !== "raw" && fmtParam !== "json") return badRequest("invalid format");
+            format = fmtParam as "raw" | "json";
+          }
+          if (format === "json" && !isJsonStream) return badRequest("invalid format");
+
+          const pathKey = pathKeyParam ?? null;
+          const key = pathKey ?? url.searchParams.get("key");
+          const rawFilter = url.searchParams.get("filter");
+          let filterInput: string | null = null;
+          let filter = null;
+          if (rawFilter != null) {
+            if (!isJsonStream) return badRequest("filter requires application/json stream content-type");
+            filterInput = rawFilter.trim();
+            const regRes = await registry.getRegistryResult(stream);
+            if (Result.isError(regRes)) return internalError();
+            const filterRes = parseReadFilterResult(regRes.value, filterInput);
+            if (Result.isError(filterRes)) return badRequest(filterRes.error.message);
+            filter = filterRes.value;
+          }
+
+          const liveParam = url.searchParams.get("live") ?? "";
+          const cursorParam = url.searchParams.get("cursor");
+          let mode: "catchup" | "long-poll" | "sse";
+          if (liveParam === "" || liveParam === "false" || liveParam === "0") mode = "catchup";
+          else if (liveParam === "long-poll" || liveParam === "true" || liveParam === "1") mode = "long-poll";
+          else if (liveParam === "sse") mode = "sse";
+          else return badRequest("invalid live mode");
+          if (filter && mode === "sse") return badRequest("filter does not support live=sse");
+
+          const timeout = url.searchParams.get("timeout") ?? url.searchParams.get("timeout_ms");
+          let timeoutMs: number | null = null;
+          if (timeout) {
+            if (/^[0-9]+$/.test(timeout)) {
+              timeoutMs = Number(timeout);
+            } else {
+              const timeoutRes = parseDurationMsResult(timeout);
+              if (Result.isError(timeoutRes)) return badRequest("invalid timeout");
+              timeoutMs = timeoutRes.value;
+            }
+          }
+
+          const hasOffsetParam = url.searchParams.has("offset");
+          let offset = url.searchParams.get("offset");
+          if (hasOffsetParam && (!offset || offset.trim() === "")) return badRequest("missing offset");
+          const sinceParam = url.searchParams.get("since");
+          if (!offset && sinceParam) {
+            const sinceRes = parseTimestampMsResult(sinceParam);
+            if (Result.isError(sinceRes)) return badRequest(sinceRes.error.message);
+            const seekRes = await reader.seekOffsetByTimestampResult(stream, sinceRes.value, key ?? null);
+            if (Result.isError(seekRes)) return readerErrorResponse(seekRes.error);
+            offset = seekRes.value;
+          }
+
+          if (!offset) {
+            if (mode === "catchup") offset = "-1";
+            else return badRequest("missing offset");
+          }
+
+          let parsedOffset: ParsedOffset | null = null;
+          if (offset !== "now") {
+            const offsetRes = parseOffsetResult(offset);
+            if (Result.isError(offsetRes)) return badRequest(offsetRes.error.message);
+            parsedOffset = offsetRes.value;
+          }
+
+          const ifNoneMatch = req.headers.get("if-none-match");
+
+          const sendBatch = async (batch: ReadBatch, cacheControl: string | null, includeEtag: boolean): Promise<Response> => {
+            const upToDate = batch.nextOffsetSeq === batch.endOffsetSeq;
+            const closedAtTail = srow.closed !== 0 && upToDate;
+            const etag = includeEtag
+              ? `W/\"slice:${canonicalizeOffset(offset!)}:${batch.nextOffset}:key=${key ?? ""}:fmt=${format}:filter=${filterInput ? encodeURIComponent(filterInput) : ""}\"`
+              : null;
+            const baseHeaders: Record<string, string> = {
+              "stream-next-offset": batch.nextOffset,
+              "stream-end-offset": batch.endOffset,
+              "cross-origin-resource-policy": "cross-origin",
+            };
+            if (upToDate) baseHeaders["stream-up-to-date"] = "true";
+            if (closedAtTail) baseHeaders["stream-closed"] = "true";
+            if (cacheControl) baseHeaders["cache-control"] = cacheControl;
+            if (etag) baseHeaders["etag"] = etag;
+            if (srow.expires_at_ms != null) baseHeaders["stream-expires-at"] = new Date(Number(srow.expires_at_ms)).toISOString();
+            if (batch.filterScanLimitReached) {
+              baseHeaders["stream-filter-scan-limit-reached"] = "true";
+              baseHeaders["stream-filter-scan-limit-bytes"] = String(batch.filterScanLimitBytes ?? 0);
+              baseHeaders["stream-filter-scanned-bytes"] = String(batch.filterScannedBytes ?? 0);
+            }
+
+            if (etag && ifNoneMatch && ifNoneMatch === etag) {
+              return new Response(null, { status: 304, headers: withNosniff(baseHeaders) });
+            }
+
+            if (format === "json") {
+              const encodedRes = await encodeStoredJsonArrayResult(stream, batch.records);
+              if (Result.isError(encodedRes)) {
+                if (encodedRes.error.status === 500) return internalError();
+                return badRequest(encodedRes.error.message);
+              }
+              if (encodedRes.value) {
+                metrics.recordRead(encodedRes.value.byteLength, batch.records.length);
+                const headers: Record<string, string> = {
+                  "content-type": "application/json",
+                  ...baseHeaders,
+                };
+                return new Response(bodyBufferFromBytes(encodedRes.value), { status: 200, headers: withNosniff(headers) });
+              }
+
+              const decoded = await decodeJsonRecords(stream, batch.records);
+              if (Result.isError(decoded)) {
+                if (decoded.error.status === 500) return internalError();
+                return badRequest(decoded.error.message);
+              }
+              const body = JSON.stringify(decoded.value.values);
+              metrics.recordRead(body.length, decoded.value.values.length);
+              const headers: Record<string, string> = {
+                "content-type": "application/json",
+                ...baseHeaders,
+              };
+              return new Response(body, { status: 200, headers: withNosniff(headers) });
+            }
+
+            const outBytes = concatPayloads(batch.records.map((r) => r.payload));
+            metrics.recordRead(outBytes.byteLength, batch.records.length);
+            const headers: Record<string, string> = {
+              "content-type": streamContentType,
+              ...baseHeaders,
+            };
+            return new Response(bodyBufferFromBytes(outBytes), { status: 200, headers: withNosniff(headers) });
+          };
+
+          if (mode === "sse") {
+            const baseCursor = srow.closed !== 0 ? null : computeCursor(Date.now(), cursorParam);
+            const dataEncoding = isTextContentType(streamContentType) ? "text" : "base64";
+            const startOffsetSeq = offset === "now" ? srow.next_offset - 1n : offsetToSeqOrNeg1(parsedOffset!);
+            const startOffset = offset === "now" ? encodeOffset(srow.epoch, startOffsetSeq) : canonicalizeOffset(offset);
+
+            const encoder = new TextEncoder();
+            let aborted = false;
+            const abortController = new AbortController();
+            const streamBody = new ReadableStream({
+              start(controller) {
+                (async () => {
+                  const fail = (message: string): void => {
+                    if (aborted) return;
+                    aborted = true;
+                    abortController.abort();
+                    controller.error(new Error(message));
+                  };
+                  let currentOffset = startOffset;
+                  let currentSeq = startOffsetSeq;
+                  let first = true;
+                  while (!aborted) {
+                    let batch: ReadBatch;
+                    if (offset === "now" && first) {
+                      batch = {
+                        stream,
+                        format,
+                        key: key ?? null,
+                        requestOffset: startOffset,
+                        endOffset: startOffset,
+                        nextOffset: startOffset,
+                        endOffsetSeq: currentSeq,
+                        nextOffsetSeq: currentSeq,
+                        records: [],
+                      };
+                    } else {
+                      const batchRes = await runForegroundWithGate(readGate, () =>
+                        reader.readResult({ stream, offset: currentOffset, key: key ?? null, format, filter })
+                      );
+                      if (Result.isError(batchRes)) {
+                        fail(batchRes.error.message);
+                        return;
+                      }
+                      batch = batchRes.value;
+                    }
+                    first = false;
+
+                    let ssePayload = "";
+
+                    if (batch.records.length > 0) {
+                      let dataPayload = "";
+                      if (format === "json") {
+                        const encodedRes = await encodeStoredJsonArrayResult(stream, batch.records);
+                        if (Result.isError(encodedRes)) {
+                          fail(encodedRes.error.message);
+                          return;
+                        }
+                        if (encodedRes.value) {
+                          dataPayload = new TextDecoder().decode(encodedRes.value);
+                        } else {
+                          const decoded = await decodeJsonRecords(stream, batch.records);
+                          if (Result.isError(decoded)) {
+                            fail(decoded.error.message);
+                            return;
+                          }
+                          dataPayload = JSON.stringify(decoded.value.values);
+                        }
+                      } else {
+                        const outBytes = concatPayloads(batch.records.map((r) => r.payload));
+                        dataPayload =
+                          dataEncoding === "base64"
+                            ? Buffer.from(outBytes).toString("base64")
+                            : new TextDecoder().decode(outBytes);
+                      }
+                      ssePayload += encodeSseEvent("data", dataPayload);
+                    }
+
+                    const upToDate = batch.nextOffsetSeq === batch.endOffsetSeq;
+                    const latest = await controlStore.getStream(stream);
+                    const closedNow = !!latest && latest.closed !== 0 && upToDate;
+
+                    const control: Record<string, any> = { streamNextOffset: batch.nextOffset };
+                    if (upToDate) control.upToDate = true;
+                    if (closedNow) control.streamClosed = true;
+                    if (!closedNow && baseCursor) control.streamCursor = baseCursor;
+                    ssePayload += encodeSseEvent("control", JSON.stringify(control));
+                    controller.enqueue(encoder.encode(ssePayload));
+
+                    if (closedNow) break;
+                    currentOffset = batch.nextOffset;
+                    currentSeq = batch.nextOffsetSeq;
+                    if (!upToDate) continue;
+
+                    const sseWaitMs = timeoutMs == null ? 30_000 : timeoutMs;
+                    await notifier.waitFor(stream, currentSeq, sseWaitMs, abortController.signal);
+                  }
+                  if (!aborted) controller.close();
+                })().catch((err) => {
+                  if (!aborted) controller.error(err);
+                });
+              },
+              cancel() {
+                aborted = true;
+                abortController.abort();
+              },
+            });
+
+            const headers: Record<string, string> = {
+              "content-type": "text/event-stream",
+              "cache-control": "no-cache",
+              "cross-origin-resource-policy": "cross-origin",
+              "stream-next-offset": startOffset,
+              "stream-end-offset": encodeOffset(srow.epoch, srow.next_offset - 1n),
+            };
+            if (dataEncoding === "base64") headers["stream-sse-data-encoding"] = "base64";
+            return new Response(streamBody, { status: 200, headers: withNosniff(headers) });
+          }
+
+          const defaultLongPollTimeoutMs = 3000;
+
+          if (offset === "now") {
+            const tailOffset = encodeOffset(srow.epoch, srow.next_offset - 1n);
+            if (srow.closed !== 0) {
+              if (mode === "long-poll") {
+                const headers: Record<string, string> = {
+                "stream-next-offset": tailOffset,
+                "stream-end-offset": tailOffset,
+                "stream-up-to-date": "true",
+                "stream-closed": "true",
+                "cache-control": "no-store",
+              };
+              if (srow.expires_at_ms != null) headers["stream-expires-at"] = new Date(Number(srow.expires_at_ms)).toISOString();
+              return new Response(null, { status: 204, headers: withNosniff(headers) });
+            }
+            const headers: Record<string, string> = {
+              "content-type": streamContentType,
+                "stream-next-offset": tailOffset,
+              "stream-end-offset": tailOffset,
+              "stream-up-to-date": "true",
+              "stream-closed": "true",
+              "cache-control": "no-store",
+              "cross-origin-resource-policy": "cross-origin",
+            };
+            if (srow.expires_at_ms != null) headers["stream-expires-at"] = new Date(Number(srow.expires_at_ms)).toISOString();
+            const body = format === "json" ? "[]" : "";
+            return new Response(body, { status: 200, headers: withNosniff(headers) });
+          }
+
+            if (mode === "long-poll") {
+              const deadline = Date.now() + (timeoutMs ?? defaultLongPollTimeoutMs);
+              let currentOffset = tailOffset;
+              while (true) {
+                const batchRes = await runForegroundWithGate(readGate, () =>
+                  reader.readResult({ stream, offset: currentOffset, key: key ?? null, format, filter })
+                );
+                if (Result.isError(batchRes)) return readerErrorResponse(batchRes.error);
+                const batch = batchRes.value;
+                if (batch.records.length > 0 || batch.filterScanLimitReached) {
+                  const cursor = computeCursor(Date.now(), cursorParam);
+                  const resp = await sendBatch(batch, "no-store", false);
+                  const headers = new Headers(resp.headers);
+                  headers.set("stream-cursor", cursor);
+                  return new Response(resp.body, { status: resp.status, headers });
+                }
+                const latest = await controlStore.getStream(stream);
+                if (latest && latest.closed !== 0 && batch.nextOffsetSeq === batch.endOffsetSeq) {
+                  const latestTail = encodeOffset(latest.epoch, latest.next_offset - 1n);
+                  const headers: Record<string, string> = {
+                    "stream-next-offset": latestTail,
+                    "stream-end-offset": latestTail,
+                    "stream-up-to-date": "true",
+                    "stream-closed": "true",
+                    "cache-control": "no-store",
+                  };
+                  if (latest.expires_at_ms != null) headers["stream-expires-at"] = new Date(Number(latest.expires_at_ms)).toISOString();
+                  return new Response(null, { status: 204, headers: withNosniff(headers) });
+                }
+                const remaining = deadline - Date.now();
+                if (remaining <= 0) break;
+                currentOffset = batch.nextOffset;
+                await notifier.waitFor(stream, batch.endOffsetSeq, remaining, req.signal);
+                if (req.signal.aborted) return new Response(null, { status: 204 });
+              }
+              const latest = await controlStore.getStream(stream);
+              const latestTail = latest ? encodeOffset(latest.epoch, latest.next_offset - 1n) : tailOffset;
+              const headers: Record<string, string> = {
+                "stream-next-offset": latestTail,
+                "stream-end-offset": latestTail,
+                "stream-up-to-date": "true",
+                "cache-control": "no-store",
+              };
+              if (latest && latest.closed !== 0) headers["stream-closed"] = "true";
+              else headers["stream-cursor"] = computeCursor(Date.now(), cursorParam);
+              if (latest && latest.expires_at_ms != null) headers["stream-expires-at"] = new Date(Number(latest.expires_at_ms)).toISOString();
+              return new Response(null, { status: 204, headers: withNosniff(headers) });
+            }
+
+            const headers: Record<string, string> = {
+              "content-type": streamContentType,
+              "stream-next-offset": tailOffset,
+              "stream-end-offset": tailOffset,
+              "stream-up-to-date": "true",
+              "cache-control": "no-store",
+              "cross-origin-resource-policy": "cross-origin",
+            };
+            const body = format === "json" ? "[]" : "";
+            return new Response(body, { status: 200, headers: withNosniff(headers) });
+          }
+
+          if (mode === "long-poll") {
+            const deadline = Date.now() + (timeoutMs ?? defaultLongPollTimeoutMs);
+            let currentOffset = offset;
+            while (true) {
+              const batchRes = await runForegroundWithGate(readGate, () =>
+                reader.readResult({ stream, offset: currentOffset, key: key ?? null, format, filter })
+              );
+              if (Result.isError(batchRes)) return readerErrorResponse(batchRes.error);
+              const batch = batchRes.value;
+              if (batch.records.length > 0 || batch.filterScanLimitReached) {
+                const cursor = computeCursor(Date.now(), cursorParam);
+                const resp = await sendBatch(batch, "no-store", false);
+                const headers = new Headers(resp.headers);
+                headers.set("stream-cursor", cursor);
+                return new Response(resp.body, { status: resp.status, headers });
+              }
+              const latest = await controlStore.getStream(stream);
+              if (latest && latest.closed !== 0 && batch.nextOffsetSeq === batch.endOffsetSeq) {
+                const latestTail = encodeOffset(latest.epoch, latest.next_offset - 1n);
+                const headers: Record<string, string> = {
+                  "stream-next-offset": latestTail,
+                  "stream-end-offset": latestTail,
+                  "stream-up-to-date": "true",
+                  "stream-closed": "true",
+                  "cache-control": "no-store",
+                };
+                if (latest.expires_at_ms != null) headers["stream-expires-at"] = new Date(Number(latest.expires_at_ms)).toISOString();
+                return new Response(null, { status: 204, headers: withNosniff(headers) });
+              }
+              const remaining = deadline - Date.now();
+              if (remaining <= 0) break;
+              currentOffset = batch.nextOffset;
+              await notifier.waitFor(stream, batch.endOffsetSeq, remaining, req.signal);
+              if (req.signal.aborted) return new Response(null, { status: 204 });
+            }
+            const latest = await controlStore.getStream(stream);
+            const latestTail = latest ? encodeOffset(latest.epoch, latest.next_offset - 1n) : currentOffset;
+            const headers: Record<string, string> = {
+              "stream-next-offset": latestTail,
+              "stream-end-offset": latestTail,
+              "stream-up-to-date": "true",
+              "cache-control": "no-store",
+            };
+            if (latest && latest.closed !== 0) headers["stream-closed"] = "true";
+            else headers["stream-cursor"] = computeCursor(Date.now(), cursorParam);
+            if (latest && latest.expires_at_ms != null) headers["stream-expires-at"] = new Date(Number(latest.expires_at_ms)).toISOString();
+            return new Response(null, { status: 204, headers: withNosniff(headers) });
+          }
+
+          const batchRes = await runForegroundWithGate(readGate, () =>
+            reader.readResult({ stream, offset, key: key ?? null, format, filter })
+          );
+          if (Result.isError(batchRes)) return readerErrorResponse(batchRes.error);
+          const batch = batchRes.value;
+          const cacheControl = "immutable, max-age=31536000";
+          return sendBatch(batch, cacheControl, true);
+        }
+
+        return badRequest("unsupported method");
+      }
+
+      return notFound();
+        })();
+      const resolved = await awaitWithCooperativeTimeout(requestPromise, HTTP_RESOLVER_TIMEOUT_MS);
+      if (resolved === TIMEOUT_SENTINEL) {
+        timedOut = true;
+        requestAbortController.abort(new Error("request timed out"));
+        void requestPromise.catch(() => {});
+        await cancelRequestBody(req);
+        return requestTimeout();
+      }
+      return resolved;
+    } catch (e: any) {
+      if (isAbortLikeError(e)) {
+        if (timedOut) return requestTimeout();
+        return new Response(null, { status: 204 });
+      }
+      const msg = String(e?.message ?? e);
+      if (!closing && !msg.includes("Statement has finalized")) {
+        // eslint-disable-next-line no-console
+        console.error("request failed", e);
+      }
+      return internalError();
+    } finally {
+      req.signal.removeEventListener("abort", abortFromClient);
+    }
+  };
+
+  const close = async () => {
+    closing = true;
+    await ready.catch(() => {});
+    // Await the worker-thread pools so their threads are fully gone before we
+    // return. The host process (e.g. @prisma/dev) frees other native resources
+    // -- PGlite's WebAssembly JIT pages -- right after this resolves; a worker
+    // thread still tearing down at that moment races V8's process-global JIT
+    // bookkeeping and can abort the process on Linux.
+    await touch?.stop();
+    await fullMode?.segmenter.stop(true);
+    await fullMode?.uploader.stop(true);
+    await indexer?.stop();
+    await metricsEmitter.stop();
+    await expirySweeper.stop();
+    fullMode?.sizeReconciler?.stop();
+    await ingest.stop();
+    memorySampler?.stop();
+    memory.stop();
+    await controlStore.close();
+    if (debugStore && debugStore !== (controlStore as unknown as AppDebugStore) && typeof debugStore.close === "function") await debugStore.close();
+  };
+
+  return {
+    fetch,
+    close,
+    ready,
+    deps: {
+      config: cfg,
+      db: debugStore,
+      os: fullMode?.store,
+      ingest,
+      notifier,
+      reader,
+      segmenter: fullMode?.segmenter,
+      uploader: fullMode?.uploader,
+      indexer,
+      metrics,
+      registry,
+      profiles,
+      touch,
+      stats,
+      storageStats: storageStatsStore,
+      objectStoreAccounting: objectStoreAccountingStore,
+      backpressure,
+      memory,
+      concurrency: {
+        ingest: ingestGate,
+        read: readGate,
+        search: searchGate,
+        asyncIndex: asyncIndexGate,
+      },
+      memorySampler,
+    },
+  };
+}