@tungthedev/streams-server 0.2.0

package/src/profiles/stateProtocol/change_event_conformance.typecheck.ts

@@ -0,0 +1,35 @@
+import type { ChangeEvent, ControlEvent } from "@durable-streams/state";
+
+type Assert<T extends true> = T;
+type AssertFalse<T extends false> = T;
+type IsAssignable<From, To> = [From] extends [To] ? true : false;
+
+type PrismaWalChangeEvent = {
+  type: "public.posts";
+  key: "42";
+  value: { id: number; title: string };
+  old_value: { id: number; title: string };
+  headers: {
+    operation: "update";
+    txid: string;
+    timestamp: string;
+  };
+};
+
+type _PrismaWalChangeEventMatchesStateProtocol = Assert<
+  IsAssignable<PrismaWalChangeEvent, ChangeEvent<{ id: number; title: string }>>
+>;
+
+type _StateProtocolUsesSnakeCaseBeforeImage = Assert<"old_value" extends keyof ChangeEvent<unknown> ? true : false>;
+type _StateProtocolDoesNotUseCamelCaseBeforeImage = AssertFalse<"oldValue" extends keyof ChangeEvent<unknown> ? true : false>;
+
+type PrismaWalControlEvent = {
+  headers: {
+    control: "reset";
+    offset: string;
+  };
+};
+
+type _PrismaWalControlEventMatchesStateProtocol = Assert<
+  IsAssignable<PrismaWalControlEvent, ControlEvent>
+>;

package/src/profiles/stateProtocol/changes.ts

@@ -0,0 +1,24 @@
+import type { CanonicalChange } from "../../touch/canonical_change";
+
+export function deriveStateProtocolChanges(record: unknown): CanonicalChange[] {
+  if (!record || typeof record !== "object" || Array.isArray(record)) return [];
+  const headers = (record as any).headers;
+  if (!headers || typeof headers !== "object" || Array.isArray(headers)) return [];
+
+  if (typeof (headers as any).control === "string") return [];
+
+  const opRaw = (headers as any).operation;
+  if (typeof opRaw !== "string") return [];
+  const op = opRaw;
+  if (op !== "insert" && op !== "update" && op !== "delete") return [];
+
+  const type = (record as any).type;
+  const key = (record as any).key;
+  if (typeof type !== "string" || type.trim() === "") return [];
+  if (typeof key !== "string" || key.trim() === "") return [];
+
+  const before = Object.prototype.hasOwnProperty.call(record, "old_value") ? (record as any).old_value : undefined;
+  const after = Object.prototype.hasOwnProperty.call(record, "value") ? (record as any).value : undefined;
+
+  return [{ entity: type, key, op, before, after }];
+}

package/src/profiles/stateProtocol/ingest.ts

@@ -0,0 +1,115 @@
+import { Result } from "better-result";
+import { parseOffsetResult } from "../../offset";
+import type { PreparedJsonRecord } from "../profile";
+import { expectPlainObjectResult, rejectUnknownKeysResult } from "../profile";
+
+const CHANGE_KEYS = ["type", "key", "value", "old_value", "headers"] as const;
+const CHANGE_HEADER_KEYS = ["operation", "txid", "timestamp"] as const;
+const CONTROL_KEYS = ["headers"] as const;
+const CONTROL_HEADER_KEYS = ["control", "offset"] as const;
+
+function isDateTimeString(value: string): boolean {
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/.test(value)) {
+    return false;
+  }
+  return !Number.isNaN(Date.parse(value));
+}
+
+function nonEmptyStringFieldResult(
+  value: unknown,
+  path: string
+): Result<string, { message: string }> {
+  if (typeof value !== "string" || value.trim() === "") {
+    return Result.err({ message: `${path} must be a non-empty string` });
+  }
+  return Result.ok(value);
+}
+
+function validateChangeRecordResult(
+  record: Record<string, unknown>,
+  headers: Record<string, unknown>
+): Result<PreparedJsonRecord, { message: string }> {
+  const keyCheck = rejectUnknownKeysResult(record, CHANGE_KEYS, "state-protocol record");
+  if (Result.isError(keyCheck)) return keyCheck;
+
+  const headerKeyCheck = rejectUnknownKeysResult(headers, CHANGE_HEADER_KEYS, "state-protocol record.headers");
+  if (Result.isError(headerKeyCheck)) return headerKeyCheck;
+
+  const typeRes = nonEmptyStringFieldResult(record.type, "state-protocol record.type");
+  if (Result.isError(typeRes)) return typeRes;
+
+  const keyRes = nonEmptyStringFieldResult(record.key, "state-protocol record.key");
+  if (Result.isError(keyRes)) return keyRes;
+
+  const operation = headers.operation;
+  if (operation !== "insert" && operation !== "update" && operation !== "delete") {
+    return Result.err({ message: "state-protocol record.headers.operation must be insert, update, or delete" });
+  }
+
+  if ((operation === "insert" || operation === "update") && !Object.prototype.hasOwnProperty.call(record, "value")) {
+    return Result.err({ message: `state-protocol ${operation} records must include value` });
+  }
+
+  if (Object.prototype.hasOwnProperty.call(headers, "txid")) {
+    const txidRes = nonEmptyStringFieldResult(headers.txid, "state-protocol record.headers.txid");
+    if (Result.isError(txidRes)) return txidRes;
+  }
+
+  if (Object.prototype.hasOwnProperty.call(headers, "timestamp")) {
+    if (typeof headers.timestamp !== "string" || !isDateTimeString(headers.timestamp)) {
+      return Result.err({ message: "state-protocol record.headers.timestamp must be a valid RFC 3339 timestamp" });
+    }
+  }
+
+  return Result.ok({ value: record, routingKey: null });
+}
+
+function validateControlRecordResult(
+  record: Record<string, unknown>,
+  headers: Record<string, unknown>
+): Result<PreparedJsonRecord, { message: string }> {
+  const keyCheck = rejectUnknownKeysResult(record, CONTROL_KEYS, "state-protocol record");
+  if (Result.isError(keyCheck)) return keyCheck;
+
+  const headerKeyCheck = rejectUnknownKeysResult(headers, CONTROL_HEADER_KEYS, "state-protocol record.headers");
+  if (Result.isError(headerKeyCheck)) return headerKeyCheck;
+
+  const control = headers.control;
+  if (control !== "snapshot-start" && control !== "snapshot-end" && control !== "reset") {
+    return Result.err({ message: "state-protocol record.headers.control must be snapshot-start, snapshot-end, or reset" });
+  }
+
+  if (Object.prototype.hasOwnProperty.call(headers, "offset")) {
+    if (typeof headers.offset !== "string") {
+      return Result.err({ message: "state-protocol record.headers.offset must be a valid stream offset string" });
+    }
+    const offsetRes = parseOffsetResult(headers.offset);
+    if (Result.isError(offsetRes)) {
+      return Result.err({ message: "state-protocol record.headers.offset must be a valid stream offset string" });
+    }
+  }
+
+  return Result.ok({ value: record, routingKey: null });
+}
+
+export function validateStateProtocolRecordResult(value: unknown): Result<PreparedJsonRecord, { message: string }> {
+  const recordRes = expectPlainObjectResult(value, "state-protocol record");
+  if (Result.isError(recordRes)) {
+    return Result.err({ message: "state-protocol records must be JSON objects" });
+  }
+
+  const headersRes = expectPlainObjectResult(recordRes.value.headers, "state-protocol record.headers");
+  if (Result.isError(headersRes)) {
+    return Result.err({ message: "state-protocol record.headers must be an object" });
+  }
+
+  const hasControl = Object.prototype.hasOwnProperty.call(headersRes.value, "control");
+  const hasOperation = Object.prototype.hasOwnProperty.call(headersRes.value, "operation");
+
+  if (hasControl && hasOperation) {
+    return Result.err({ message: "state-protocol record.headers cannot mix control and operation" });
+  }
+  if (hasControl) return validateControlRecordResult(recordRes.value, headersRes.value);
+  if (hasOperation) return validateChangeRecordResult(recordRes.value, headersRes.value);
+  return Result.err({ message: "state-protocol record.headers must contain operation or control" });
+}

package/src/profiles/stateProtocol/routes.ts

@@ -0,0 +1,511 @@
+import { Result } from "better-result";
+import { encodeOffset } from "../../offset";
+import { parseTouchCursor } from "../../touch/touch_journal";
+import { touchKeyIdFromRoutingKeyResult } from "../../touch/touch_key_id";
+import { tableKeyIdFor, templateKeyIdFor } from "../../touch/live_keys";
+import type { TemplateDecl } from "../../touch/live_templates";
+import type { TouchConfig } from "../../touch/spec";
+import type { StreamTouchRouteArgs } from "../profile";
+import { getStateProtocolTouchConfig } from "./validation";
+
+const EXACT_FINE_WAIT_MAX_KEYS = 16;
+
+async function countActiveTemplates(stream: string, db: StreamTouchRouteArgs["db"]): Promise<number> {
+  try {
+    return await db.countActiveLiveTemplates(stream);
+  } catch {
+    return 0;
+  }
+}
+
+function parseInactivityTtlResult(
+  raw: unknown,
+  defaultValue: number,
+  fieldPath: string
+): Result<number, { message: string }> {
+  if (raw === undefined) return Result.ok(defaultValue);
+  if (typeof raw === "number" && Number.isFinite(raw) && raw >= 0) {
+    return Result.ok(Math.floor(raw));
+  }
+  return Result.err({ message: `${fieldPath} must be a non-negative number (ms)` });
+}
+
+function parseTemplateDeclsResult(raw: unknown, fieldPath: string): Result<TemplateDecl[], { message: string }> {
+  if (!Array.isArray(raw) || raw.length === 0) {
+    return Result.err({ message: `${fieldPath} must be a non-empty array` });
+  }
+  if (raw.length > 256) return Result.err({ message: `${fieldPath} too large (max 256)` });
+
+  const templates: TemplateDecl[] = [];
+  for (const t of raw) {
+    const entity = typeof t?.entity === "string" ? t.entity.trim() : "";
+    const fieldsRaw = t?.fields;
+    if (entity === "" || !Array.isArray(fieldsRaw) || fieldsRaw.length === 0 || fieldsRaw.length > 3) {
+      return Result.err({ message: `${fieldPath} contains invalid template definitions` });
+    }
+
+    const fields: TemplateDecl["fields"] = [];
+    for (const f of fieldsRaw) {
+      const name = typeof f?.name === "string" ? f.name.trim() : "";
+      const encoding = f?.encoding;
+      if (name === "") {
+        return Result.err({ message: `${fieldPath} contains invalid template definitions` });
+      }
+      fields.push({ name, encoding });
+    }
+    if (fields.length !== fieldsRaw.length) {
+      return Result.err({ message: `${fieldPath} contains invalid template definitions` });
+    }
+    templates.push({ entity, fields });
+  }
+  return Result.ok(templates);
+}
+
+function parseWaitTimeoutMsQueryResult(raw: string | null, defaultValue: number, fieldPath: string): Result<number, { message: string }> {
+  if (raw == null || raw.trim() === "") return Result.ok(defaultValue);
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return Result.err({ message: `${fieldPath} must be a number (ms)` });
+  return Result.ok(Math.max(0, Math.min(120_000, Math.floor(n))));
+}
+
+function normalizeExactFineWaitKeys(keys: string[]): string[] {
+  if (keys.length === 0 || keys.length > EXACT_FINE_WAIT_MAX_KEYS) return [];
+  const normalized = Array.from(new Set(keys.map((key) => key.trim().toLowerCase())));
+  if (!normalized.every((key) => /^[0-9a-f]{16}$/.test(key))) return [];
+  return normalized;
+}
+
+async function handleTemplatesActivateRoute(args: StreamTouchRouteArgs, touchCfg: TouchConfig): Promise<Response> {
+  const { req, stream, streamRow, touchManager, respond } = args;
+  if (req.method !== "POST") return respond.badRequest("unsupported method");
+
+  let body: any;
+  try {
+    body = await req.json();
+  } catch {
+    return respond.badRequest("activate body must be valid JSON");
+  }
+
+  const templatesRes = parseTemplateDeclsResult(body?.templates, "activate.templates");
+  if (Result.isError(templatesRes)) return respond.badRequest(templatesRes.error.message);
+
+  const inactivityTtlRes = parseInactivityTtlResult(
+    body?.inactivityTtlMs,
+    touchCfg.templates?.defaultInactivityTtlMs ?? 60 * 60 * 1000,
+    "activate.inactivityTtlMs"
+  );
+  if (Result.isError(inactivityTtlRes)) return respond.badRequest(inactivityTtlRes.error.message);
+
+  const limits = {
+    maxActiveTemplatesPerStream: touchCfg.templates?.maxActiveTemplatesPerStream ?? 2048,
+    maxActiveTemplatesPerEntity: touchCfg.templates?.maxActiveTemplatesPerEntity ?? 256,
+  };
+  const activeFromTouchOffset = touchManager.getOrCreateJournal(stream, touchCfg).getCursor();
+  const res = await touchManager.activateTemplates({
+    stream,
+    touchCfg,
+    baseStreamNextOffset: streamRow.next_offset,
+    activeFromTouchOffset,
+    templates: templatesRes.value,
+    inactivityTtlMs: inactivityTtlRes.value,
+  });
+
+  return respond.json(200, { activated: res.activated, denied: res.denied, limits });
+}
+
+async function buildMetaRoutePayload(args: StreamTouchRouteArgs, touchCfg: TouchConfig) {
+  const { stream, streamRow, db, touchManager } = args;
+  const meta = touchManager.getOrCreateJournal(stream, touchCfg).getMeta();
+  const runtime = touchManager.getTouchRuntimeSnapshot({ stream, touchCfg });
+  const touchState = await db.getStreamTouchState(stream);
+  return {
+    ...meta,
+    settled: meta.pendingKeys === 0 && runtime.lagSourceOffsets === 0,
+    coarseIntervalMs: touchCfg.coarseIntervalMs ?? 100,
+    touchCoalesceWindowMs: touchCfg.touchCoalesceWindowMs ?? 100,
+    activeTemplates: await countActiveTemplates(stream, db),
+    lagSourceOffsets: runtime.lagSourceOffsets,
+    touchMode: runtime.touchMode,
+    walScannedThrough: touchState ? encodeOffset(streamRow.epoch, touchState.processed_through) : null,
+    bucketMaxSourceOffsetSeq: meta.bucketMaxSourceOffsetSeq,
+    hotFineKeys: runtime.hotFineKeys,
+    hotTemplates: runtime.hotTemplates,
+    hotFineKeysActive: runtime.hotFineKeysActive,
+    hotFineKeysGrace: runtime.hotFineKeysGrace,
+    hotTemplatesActive: runtime.hotTemplatesActive,
+    hotTemplatesGrace: runtime.hotTemplatesGrace,
+    fineWaitersActive: runtime.fineWaitersActive,
+    coarseWaitersActive: runtime.coarseWaitersActive,
+    broadFineWaitersActive: runtime.broadFineWaitersActive,
+    hotKeyFilteringEnabled: runtime.hotKeyFilteringEnabled,
+    hotTemplateFilteringEnabled: runtime.hotTemplateFilteringEnabled,
+    scanRowsTotal: runtime.scanRowsTotal,
+    scanBatchesTotal: runtime.scanBatchesTotal,
+    scannedButEmitted0BatchesTotal: runtime.scannedButEmitted0BatchesTotal,
+    processedThroughDeltaTotal: runtime.processedThroughDeltaTotal,
+    touchesEmittedTotal: runtime.touchesEmittedTotal,
+    touchesTableTotal: runtime.touchesTableTotal,
+    touchesTemplateTotal: runtime.touchesTemplateTotal,
+    fineTouchesDroppedDueToBudgetTotal: runtime.fineTouchesDroppedDueToBudgetTotal,
+    fineTouchesSkippedColdTemplateTotal: runtime.fineTouchesSkippedColdTemplateTotal,
+    fineTouchesSkippedColdKeyTotal: runtime.fineTouchesSkippedColdKeyTotal,
+    fineTouchesSkippedTemplateBucketTotal: runtime.fineTouchesSkippedTemplateBucketTotal,
+    waitTouchedTotal: runtime.waitTouchedTotal,
+    waitTimeoutTotal: runtime.waitTimeoutTotal,
+    waitStaleTotal: runtime.waitStaleTotal,
+    journalFlushesTotal: runtime.journalFlushesTotal,
+    journalNotifyWakeupsTotal: runtime.journalNotifyWakeupsTotal,
+    journalNotifyWakeMsTotal: runtime.journalNotifyWakeMsTotal,
+    journalNotifyWakeMsMax: runtime.journalNotifyWakeMsMax,
+    journalTimeoutsFiredTotal: runtime.journalTimeoutsFiredTotal,
+    journalTimeoutSweepMsTotal: runtime.journalTimeoutSweepMsTotal,
+  };
+}
+
+async function handleMetaRoute(args: StreamTouchRouteArgs, touchCfg: TouchConfig): Promise<Response> {
+  const { req, respond } = args;
+  if (req.method !== "GET") return respond.badRequest("unsupported method");
+
+  const url = new URL(req.url);
+  const settleRaw = url.searchParams.get("settle");
+  if (settleRaw !== null && settleRaw !== "flush") {
+    return respond.badRequest("meta.settle must be 'flush' when provided");
+  }
+
+  const timeoutMsRes = parseWaitTimeoutMsQueryResult(url.searchParams.get("timeoutMs"), 30_000, "meta.timeoutMs");
+  if (Result.isError(timeoutMsRes)) return respond.badRequest(timeoutMsRes.error.message);
+
+  if (settleRaw !== "flush") {
+    return respond.json(200, await buildMetaRoutePayload(args, touchCfg));
+  }
+
+  const deadlineMs = Date.now() + timeoutMsRes.value;
+  for (;;) {
+    const payload = await buildMetaRoutePayload(args, touchCfg);
+    if (payload.settled || Date.now() >= deadlineMs) {
+      return respond.json(200, payload);
+    }
+    if (req.signal.aborted) return new Response(null, { status: 204 });
+    const remainingMs = Math.max(1, deadlineMs - Date.now());
+    await new Promise<void>((resolve) => {
+      const waitMs = Math.min(25, remainingMs);
+      const timer = setTimeout(() => {
+        req.signal.removeEventListener("abort", onAbort);
+        resolve();
+      }, waitMs);
+      const onAbort = () => {
+        clearTimeout(timer);
+        req.signal.removeEventListener("abort", onAbort);
+        resolve();
+      };
+      req.signal.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+}
+
+async function handleWaitRoute(args: StreamTouchRouteArgs, touchCfg: TouchConfig): Promise<Response> {
+  const { req, stream, streamRow, touchManager, respond } = args;
+  if (req.method !== "POST") return respond.badRequest("unsupported method");
+
+  const waitStartMs = Date.now();
+  let body: any;
+  try {
+    body = await req.json();
+  } catch {
+    return respond.badRequest("wait body must be valid JSON");
+  }
+
+  const keysRaw = body?.keys;
+  if (keysRaw !== undefined && (!Array.isArray(keysRaw) || !keysRaw.every((k: any) => typeof k === "string" && k.trim() !== ""))) {
+    return respond.badRequest("wait.keys must be a non-empty string array when provided");
+  }
+  const keys = Array.isArray(keysRaw) ? Array.from(new Set(keysRaw.map((k: string) => k.trim()))) : [];
+  if (keys.length > 1024) return respond.badRequest("wait.keys too large (max 1024)");
+
+  const keyIdsRaw = body?.keyIds;
+  const keyIds =
+    Array.isArray(keyIdsRaw) && keyIdsRaw.length > 0
+      ? Array.from(
+          new Set(
+            keyIdsRaw
+              .map((x: any) => Number(x))
+              .filter((n: number) => Number.isFinite(n) && Number.isInteger(n) && n >= 0 && n <= 0xffffffff)
+          )
+        ).map((n) => n >>> 0)
+      : [];
+  if (Array.isArray(keyIdsRaw) && keyIds.length !== keyIdsRaw.length) {
+    return respond.badRequest("wait.keyIds must be a non-empty uint32 array when provided");
+  }
+  if (keys.length === 0 && keyIds.length === 0) return respond.badRequest("wait requires keys or keyIds");
+  if (keyIds.length > 1024) return respond.badRequest("wait.keyIds too large (max 1024)");
+
+  const exactRaw = body?.exact;
+  if (exactRaw !== undefined && typeof exactRaw !== "boolean") return respond.badRequest("wait.exact must be a boolean when provided");
+  const exactRequested = exactRaw === true;
+
+  const cursorRaw = body?.cursor;
+  if (typeof cursorRaw !== "string" || cursorRaw.trim() === "") return respond.badRequest("wait.cursor must be a non-empty string");
+  const cursor = cursorRaw.trim();
+
+  const timeoutMsRaw = body?.timeoutMs;
+  const timeoutMs =
+    timeoutMsRaw === undefined
+      ? 30_000
+      : typeof timeoutMsRaw === "number" && Number.isFinite(timeoutMsRaw)
+        ? Math.max(0, Math.min(120_000, timeoutMsRaw))
+        : null;
+  if (timeoutMs == null) return respond.badRequest("wait.timeoutMs must be a number (ms)");
+
+  const templateIdsUsedRaw = body?.templateIdsUsed;
+  if (Array.isArray(templateIdsUsedRaw) && !templateIdsUsedRaw.every((x: any) => typeof x === "string" && x.trim() !== "")) {
+    return respond.badRequest("wait.templateIdsUsed must be a string array");
+  }
+  const templateIdsUsed =
+    Array.isArray(templateIdsUsedRaw) && templateIdsUsedRaw.length > 0
+      ? Array.from(new Set(templateIdsUsedRaw.map((s: any) => (typeof s === "string" ? s.trim() : "")).filter((s: string) => s !== "")))
+      : [];
+
+  const interestModeRaw = body?.interestMode;
+  if (interestModeRaw !== undefined && interestModeRaw !== "fine" && interestModeRaw !== "coarse") {
+    return respond.badRequest("wait.interestMode must be 'fine' or 'coarse'");
+  }
+  const interestMode: "fine" | "coarse" = interestModeRaw === "coarse" ? "coarse" : "fine";
+
+  if (interestMode === "fine" && templateIdsUsed.length > 0) {
+    await touchManager.heartbeatTemplates({ stream, touchCfg, templateIdsUsed });
+  }
+
+  const declareTemplatesRaw = body?.declareTemplates;
+  if (Array.isArray(declareTemplatesRaw) && declareTemplatesRaw.length > 0) {
+    const templatesRes = parseTemplateDeclsResult(declareTemplatesRaw, "wait.declareTemplates");
+    if (Result.isError(templatesRes)) return respond.badRequest(templatesRes.error.message);
+
+    const inactivityTtlRes = parseInactivityTtlResult(
+      body?.inactivityTtlMs,
+      touchCfg.templates?.defaultInactivityTtlMs ?? 60 * 60 * 1000,
+      "wait.inactivityTtlMs"
+    );
+    if (Result.isError(inactivityTtlRes)) return respond.badRequest(inactivityTtlRes.error.message);
+
+    const activeFromTouchOffset = touchManager.getOrCreateJournal(stream, touchCfg).getCursor();
+    await touchManager.activateTemplates({
+      stream,
+      touchCfg,
+      baseStreamNextOffset: streamRow.next_offset,
+      activeFromTouchOffset,
+      templates: templatesRes.value,
+      inactivityTtlMs: inactivityTtlRes.value,
+    });
+  }
+
+  const journal = touchManager.getOrCreateJournal(stream, touchCfg);
+  const runtime = touchManager.getTouchRuntimeSnapshot({ stream, touchCfg });
+
+  let rawFineKeyIds = keyIds;
+  if (keyIds.length === 0) {
+    const parsedKeyIds: number[] = [];
+    for (const key of keys) {
+      const keyIdRes = touchKeyIdFromRoutingKeyResult(key);
+      if (Result.isError(keyIdRes)) return respond.internalError();
+      parsedKeyIds.push(keyIdRes.value);
+    }
+    rawFineKeyIds = parsedKeyIds;
+  }
+
+  const templateWaitKeyIds = templateIdsUsed.length > 0 ? Array.from(new Set(templateIdsUsed.map((templateId) => templateKeyIdFor(templateId) >>> 0))) : [];
+  let waitKeyIds = rawFineKeyIds;
+  let effectiveWaitKind: "fineKey" | "templateKey" | "tableKey" = "fineKey";
+
+  if (interestMode === "coarse") {
+    effectiveWaitKind = "tableKey";
+  } else if (runtime.touchMode === "restricted" && templateIdsUsed.length > 0) {
+    effectiveWaitKind = "templateKey";
+  } else if (runtime.touchMode === "coarseOnly" && templateIdsUsed.length > 0) {
+    effectiveWaitKind = "tableKey";
+  }
+
+  if (effectiveWaitKind === "templateKey") {
+    waitKeyIds = templateWaitKeyIds;
+  } else if (effectiveWaitKind === "tableKey" && templateIdsUsed.length > 0) {
+    const entities = await touchManager.resolveTemplateEntitiesForWait({ stream, templateIdsUsed });
+    waitKeyIds = Array.from(new Set(entities.map((entity) => tableKeyIdFor(entity) >>> 0)));
+  }
+
+  if (exactRequested && (interestMode !== "fine" || effectiveWaitKind !== "fineKey")) {
+    return respond.badRequest("wait.exact requires fine interest while runtime is in fine-key mode");
+  }
+
+  const exactFineRoutingKeys =
+    exactRequested && interestMode === "fine" && effectiveWaitKind === "fineKey" ? normalizeExactFineWaitKeys(keys) : [];
+  if (exactRequested && exactFineRoutingKeys.length === 0) {
+    return respond.badRequest("wait.exact requires 1 to 16 literal 64-bit routing keys");
+  }
+  const useExactFineKeyMatch = exactFineRoutingKeys.length > 0;
+  const exactFallbackKeyIds =
+    interestMode === "fine" && effectiveWaitKind === "fineKey" && templateWaitKeyIds.length > 0 ? templateWaitKeyIds : [];
+
+  if (interestMode === "fine" && effectiveWaitKind === "fineKey" && templateWaitKeyIds.length > 0 && !useExactFineKeyMatch) {
+    const merged = new Set<number>();
+    for (const keyId of waitKeyIds) merged.add(keyId >>> 0);
+    for (const keyId of templateWaitKeyIds) merged.add(keyId >>> 0);
+    waitKeyIds = Array.from(merged);
+  }
+
+  if (waitKeyIds.length === 0) {
+    waitKeyIds = rawFineKeyIds;
+    effectiveWaitKind = "fineKey";
+  }
+
+  const hotInterestKeyIds = interestMode === "fine" ? rawFineKeyIds : waitKeyIds;
+  const releaseHotInterest = touchManager.beginHotWaitInterest({
+    stream,
+    touchCfg,
+    keyIds: hotInterestKeyIds,
+    templateIdsUsed,
+    interestMode,
+  });
+
+  try {
+    let sinceGen: number;
+    if (cursor === "now") {
+      sinceGen = journal.getGeneration();
+    } else {
+      const parsed = parseTouchCursor(cursor);
+      if (!parsed) return respond.badRequest("wait.cursor must be in the form <epochHex>:<generation> or 'now'");
+      if (parsed.epoch !== journal.getEpoch()) {
+        const latencyMs = Date.now() - waitStartMs;
+        touchManager.recordWaitMetrics({ stream, touchCfg, keysCount: waitKeyIds.length, outcome: "stale", latencyMs });
+        return respond.json(200, {
+          stale: true,
+          cursor: journal.getCursor(),
+          epoch: journal.getEpoch(),
+          generation: journal.getGeneration(),
+          effectiveWaitKind,
+          bucketMaxSourceOffsetSeq: journal.getLastFlushedSourceOffsetSeq().toString(),
+          flushAtMs: journal.getLastFlushAtMs(),
+          bucketStartMs: journal.getLastBucketStartMs(),
+          error: { code: "stale", message: "cursor epoch mismatch; rerun/re-subscribe and start from cursor" },
+        });
+      }
+      sinceGen = parsed.generation;
+    }
+
+    const nowGen = journal.getGeneration();
+    if (sinceGen > nowGen) sinceGen = nowGen;
+
+    if (useExactFineKeyMatch) {
+      const exactTouched = journal.exactTouchedSinceAny(exactFineRoutingKeys, sinceGen);
+      if (exactTouched === true) {
+        const latencyMs = Date.now() - waitStartMs;
+        touchManager.recordWaitMetrics({ stream, touchCfg, keysCount: waitKeyIds.length, outcome: "touched", latencyMs });
+        return respond.json(200, {
+          touched: true,
+          cursor: journal.getCursor(),
+          effectiveWaitKind,
+          bucketMaxSourceOffsetSeq: journal.getLastFlushedSourceOffsetSeq().toString(),
+          flushAtMs: journal.getLastFlushAtMs(),
+          bucketStartMs: journal.getLastBucketStartMs(),
+        });
+      }
+      const fallbackTouched =
+        exactFallbackKeyIds.length > 0 ? journal.maybeTouchedSinceAny(exactFallbackKeyIds, sinceGen) : false;
+      if (fallbackTouched) {
+        const latencyMs = Date.now() - waitStartMs;
+        touchManager.recordWaitMetrics({ stream, touchCfg, keysCount: waitKeyIds.length, outcome: "touched", latencyMs });
+        return respond.json(200, {
+          touched: true,
+          cursor: journal.getCursor(),
+          effectiveWaitKind,
+          bucketMaxSourceOffsetSeq: journal.getLastFlushedSourceOffsetSeq().toString(),
+          flushAtMs: journal.getLastFlushAtMs(),
+          bucketStartMs: journal.getLastBucketStartMs(),
+        });
+      }
+      if (exactTouched === false) {
+        // Exact recent history covers this cursor range and saw none of the watched keys.
+      } else if (journal.maybeTouchedSinceAny(waitKeyIds, sinceGen)) {
+        const latencyMs = Date.now() - waitStartMs;
+        touchManager.recordWaitMetrics({ stream, touchCfg, keysCount: waitKeyIds.length, outcome: "touched", latencyMs });
+        return respond.json(200, {
+          touched: true,
+          cursor: journal.getCursor(),
+          effectiveWaitKind,
+          bucketMaxSourceOffsetSeq: journal.getLastFlushedSourceOffsetSeq().toString(),
+          flushAtMs: journal.getLastFlushAtMs(),
+          bucketStartMs: journal.getLastBucketStartMs(),
+        });
+      }
+    } else if (journal.maybeTouchedSinceAny(waitKeyIds, sinceGen)) {
+      const latencyMs = Date.now() - waitStartMs;
+      touchManager.recordWaitMetrics({ stream, touchCfg, keysCount: waitKeyIds.length, outcome: "touched", latencyMs });
+      return respond.json(200, {
+        touched: true,
+        cursor: journal.getCursor(),
+        effectiveWaitKind,
+        bucketMaxSourceOffsetSeq: journal.getLastFlushedSourceOffsetSeq().toString(),
+        flushAtMs: journal.getLastFlushAtMs(),
+        bucketStartMs: journal.getLastBucketStartMs(),
+      });
+    }
+
+    const deadline = Date.now() + timeoutMs;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      const latencyMs = Date.now() - waitStartMs;
+      touchManager.recordWaitMetrics({ stream, touchCfg, keysCount: waitKeyIds.length, outcome: "timeout", latencyMs });
+      return respond.json(200, {
+        touched: false,
+        cursor: journal.getCursor(),
+        effectiveWaitKind,
+        bucketMaxSourceOffsetSeq: journal.getLastFlushedSourceOffsetSeq().toString(),
+        flushAtMs: journal.getLastFlushAtMs(),
+        bucketStartMs: journal.getLastBucketStartMs(),
+      });
+    }
+
+    const afterGen = journal.getGeneration();
+    const hit = await journal.waitForAny({
+      keys: useExactFineKeyMatch ? exactFallbackKeyIds : waitKeyIds,
+      exactKeys: useExactFineKeyMatch ? exactFineRoutingKeys : null,
+      afterGeneration: afterGen,
+      timeoutMs: remaining,
+      signal: req.signal,
+    });
+    if (req.signal.aborted) return new Response(null, { status: 204 });
+
+    if (hit == null) {
+      const latencyMs = Date.now() - waitStartMs;
+      touchManager.recordWaitMetrics({ stream, touchCfg, keysCount: waitKeyIds.length, outcome: "timeout", latencyMs });
+      return respond.json(200, {
+        touched: false,
+        cursor: journal.getCursor(),
+        effectiveWaitKind,
+        bucketMaxSourceOffsetSeq: journal.getLastFlushedSourceOffsetSeq().toString(),
+        flushAtMs: journal.getLastFlushAtMs(),
+        bucketStartMs: journal.getLastBucketStartMs(),
+      });
+    }
+
+    const latencyMs = Date.now() - waitStartMs;
+    touchManager.recordWaitMetrics({ stream, touchCfg, keysCount: waitKeyIds.length, outcome: "touched", latencyMs });
+    return respond.json(200, {
+      touched: true,
+      cursor: journal.getCursor(),
+      effectiveWaitKind,
+      bucketMaxSourceOffsetSeq: hit.bucketMaxSourceOffsetSeq.toString(),
+      flushAtMs: hit.flushAtMs,
+      bucketStartMs: hit.bucketStartMs,
+    });
+  } finally {
+    releaseHotInterest();
+  }
+}
+
+export async function handleStateProtocolTouchRoute(args: StreamTouchRouteArgs): Promise<Response> {
+  const { route, profile, respond } = args;
+  const touchCfg = getStateProtocolTouchConfig(profile);
+  if (!touchCfg) return respond.notFound("touch not enabled");
+  if (route.kind === "templates_activate") return handleTemplatesActivateRoute(args, touchCfg);
+  if (route.kind === "meta") return handleMetaRoute(args, touchCfg);
+  return handleWaitRoute(args, touchCfg);
+}