@prisma/streams-server 0.1.1 → 0.1.3

package/src/profiles/stateProtocol/routes.ts

@@ -0,0 +1,389 @@
+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";
+
+function countActiveTemplates(stream: string, db: StreamTouchRouteArgs["db"]): number {
+  try {
+    const row = db.db.query(`SELECT COUNT(*) as cnt FROM live_templates WHERE stream=? AND state='active';`).get(stream) as any;
+    return Number(row?.cnt ?? 0);
+  } 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);
+}
+
+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 = 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 });
+}
+
+function handleMetaRoute(args: StreamTouchRouteArgs, touchCfg: TouchConfig): Response {
+  const { stream, streamRow, db, touchManager, respond } = args;
+  const meta = touchManager.getOrCreateJournal(stream, touchCfg).getMeta();
+  const runtime = touchManager.getTouchRuntimeSnapshot({ stream, touchCfg });
+  const touchState = db.getStreamTouchState(stream);
+  return respond.json(200, {
+    ...meta,
+    coarseIntervalMs: touchCfg.coarseIntervalMs ?? 100,
+    touchCoalesceWindowMs: touchCfg.touchCoalesceWindowMs ?? 100,
+    activeTemplates: 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 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 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) {
+    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();
+    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 = touchManager.resolveTemplateEntitiesForWait({ stream, templateIdsUsed });
+    waitKeyIds = Array.from(new Set(entities.map((entity) => tableKeyIdFor(entity) >>> 0)));
+  }
+
+  if (interestMode === "fine" && effectiveWaitKind === "fineKey" && templateWaitKeyIds.length > 0) {
+    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 (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: waitKeyIds, 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);
+}

package/src/profiles/stateProtocol/types.ts

@@ -0,0 +1,6 @@
+import type { TouchConfig } from "../../touch/spec";
+
+export type StateProtocolStreamProfile = {
+  kind: "state-protocol";
+  touch?: TouchConfig;
+};

package/src/profiles/stateProtocol/validation.ts

@@ -0,0 +1,51 @@
+import { Result } from "better-result";
+import type { CachedStreamProfile, StreamProfileSpec } from "../profile";
+import {
+  cloneStreamProfileSpec,
+  expectPlainObjectResult,
+  rejectUnknownKeysResult,
+} from "../profile";
+import { validateTouchConfigResult, type TouchConfig } from "../../touch/spec";
+import type { StateProtocolStreamProfile } from "./types";
+
+export function isStateProtocolProfile(
+  profile: StreamProfileSpec | null | undefined
+): profile is StateProtocolStreamProfile {
+  return !!profile && profile.kind === "state-protocol";
+}
+
+export function getStateProtocolTouchConfig(profile: StreamProfileSpec | null | undefined): TouchConfig | null {
+  return isStateProtocolProfile(profile) && profile.touch?.enabled ? profile.touch : null;
+}
+
+export function cloneStateProtocolProfile(profile: StateProtocolStreamProfile): StateProtocolStreamProfile {
+  return cloneStreamProfileSpec(profile) as StateProtocolStreamProfile;
+}
+
+export function cloneStateProtocolCache(cache: CachedStreamProfile | null): CachedStreamProfile | null {
+  if (!cache || cache.profile.kind !== "state-protocol") return null;
+  return {
+    profile: cloneStateProtocolProfile(cache.profile as StateProtocolStreamProfile),
+    updatedAtMs: cache.updatedAtMs,
+  };
+}
+
+export function validateStateProtocolProfileResult(
+  raw: unknown,
+  path: string
+): Result<StateProtocolStreamProfile, { message: string }> {
+  const objRes = expectPlainObjectResult(raw, path);
+  if (Result.isError(objRes)) return objRes;
+  if (objRes.value.kind !== "state-protocol") {
+    return Result.err({ message: `${path}.kind must be state-protocol` });
+  }
+  const keyCheck = rejectUnknownKeysResult(objRes.value, ["kind", "touch"], path);
+  if (Result.isError(keyCheck)) return keyCheck;
+  let touch = undefined;
+  if (objRes.value.touch !== undefined) {
+    const touchRes = validateTouchConfigResult(objRes.value.touch, `${path}.touch`);
+    if (Result.isError(touchRes)) return Result.err({ message: touchRes.error.message });
+    touch = touchRes.value;
+  }
+  return Result.ok(touch ? { kind: "state-protocol", touch } : { kind: "state-protocol" });
+}

package/src/profiles/stateProtocol.ts

@@ -0,0 +1,100 @@
+import { Result } from "better-result";
+import type {
+  StreamProfileDefinition,
+  StreamProfilePersistResult,
+  StreamProfileReadResult,
+  StreamTouchCapability,
+} from "./profile";
+import { normalizeProfileContentType, parseStoredProfileJsonResult } from "./profile";
+import { deriveStateProtocolChanges } from "./stateProtocol/changes";
+import { handleStateProtocolTouchRoute } from "./stateProtocol/routes";
+import type { StateProtocolStreamProfile } from "./stateProtocol/types";
+import {
+  cloneStateProtocolCache,
+  cloneStateProtocolProfile,
+  getStateProtocolTouchConfig,
+  isStateProtocolProfile,
+  validateStateProtocolProfileResult,
+} from "./stateProtocol/validation";
+
+const STATE_PROTOCOL_TOUCH_CAPABILITY: StreamTouchCapability = {
+  getTouchConfig(profile) {
+    return getStateProtocolTouchConfig(profile);
+  },
+
+  syncState({ db, stream, profile }) {
+    if (getStateProtocolTouchConfig(profile)) db.ensureStreamTouchState(stream);
+    else db.deleteStreamTouchState(stream);
+  },
+
+  deriveCanonicalChanges(record) {
+    return deriveStateProtocolChanges(record);
+  },
+
+  async handleRoute(args) {
+    return handleStateProtocolTouchRoute(args);
+  },
+};
+
+export const STATE_PROTOCOL_STREAM_PROFILE_DEFINITION: StreamProfileDefinition = {
+  kind: "state-protocol",
+  usesStoredProfileRow: true,
+  touch: STATE_PROTOCOL_TOUCH_CAPABILITY,
+
+  defaultProfile(): StateProtocolStreamProfile {
+    return { kind: "state-protocol" };
+  },
+
+  validateResult(raw, path) {
+    return validateStateProtocolProfileResult(raw, path);
+  },
+
+  readProfileResult({ row, cached }): Result<StreamProfileReadResult, { message: string }> {
+    if (!row) {
+      return Result.ok({ profile: { kind: "state-protocol" }, cache: null });
+    }
+    const cachedCopy = cloneStateProtocolCache(cached);
+    if (cachedCopy && cachedCopy.updatedAtMs === row.updated_at_ms) {
+      return Result.ok({
+        profile: cloneStateProtocolProfile(cachedCopy.profile as StateProtocolStreamProfile),
+        cache: cachedCopy,
+      });
+    }
+    const parsedRes = parseStoredProfileJsonResult(row.profile_json);
+    if (Result.isError(parsedRes)) return parsedRes;
+    const profileRes = validateStateProtocolProfileResult(parsedRes.value, "profile");
+    if (Result.isError(profileRes)) return profileRes;
+    const profile = cloneStateProtocolProfile(profileRes.value);
+    return Result.ok({
+      profile: cloneStateProtocolProfile(profile),
+      cache: { profile, updatedAtMs: row.updated_at_ms },
+    });
+  },
+
+  persistProfileResult({ db, stream, streamRow, profile }): Result<StreamProfilePersistResult, { kind: "bad_request"; message: string; code?: string }> {
+    if (!isStateProtocolProfile(profile)) {
+      return Result.err({ kind: "bad_request", message: "invalid state-protocol profile" });
+    }
+    const contentType = normalizeProfileContentType(streamRow.content_type);
+    if (contentType !== "application/json") {
+      return Result.err({
+        kind: "bad_request",
+        message: "state-protocol profile requires application/json stream content-type",
+      });
+    }
+
+    const persistedProfile = cloneStateProtocolProfile(profile);
+    db.updateStreamProfile(stream, persistedProfile.kind);
+    db.upsertStreamProfile(stream, JSON.stringify(persistedProfile));
+    STATE_PROTOCOL_TOUCH_CAPABILITY.syncState({ db, stream, profile: persistedProfile });
+    const row = db.getStreamProfile(stream);
+    return Result.ok({
+      profile: cloneStateProtocolProfile(persistedProfile),
+      cache: {
+        profile: persistedProfile,
+        updatedAtMs: row?.updated_at_ms ?? db.nowMs(),
+      },
+      schemaRegistry: null,
+    });
+  },
+};