@tungthedev/streams-server 0.2.0

package/src/profiles/otelTraces.ts

@@ -0,0 +1,390 @@
+import { Result } from "better-result";
+import type {
+  CachedStreamProfile,
+  StreamProfileDefinition,
+  StreamProfilePersistResult,
+  StreamProfileReadResult,
+  StreamProfileSpec,
+  UnifiedTimelineItem,
+} from "./profile";
+import {
+  cloneStreamProfileSpec,
+  expectPlainObjectResult,
+  normalizeProfileContentType,
+  parseStoredProfileJsonResult,
+  rejectUnknownKeysResult,
+  isPlainObject,
+} from "./profile";
+import { buildOtelTracesDefaultRegistry } from "./otelTraces/schema";
+import {
+  DEFAULT_ATTRIBUTE_LIMITS,
+  DEFAULT_OTLP_LIMITS,
+  DEFAULT_STORE_CONFIG,
+  normalizeOtelTraceRecordResult,
+  type DbStatementMode,
+  type OtelTraceAttributeLimits,
+  type OtelTraceOtlpLimits,
+  type OtelTraceStoreConfig,
+  type OtelTracesStreamProfile,
+  type UrlMode,
+} from "./otelTraces/normalize";
+import { decodeOtlpTraceExportRequestResult } from "./otelTraces/otlp";
+
+export type { OtelTracesStreamProfile };
+
+function cloneOtelTracesProfile(profile: OtelTracesStreamProfile): OtelTracesStreamProfile {
+  return cloneStreamProfileSpec(profile) as OtelTracesStreamProfile;
+}
+
+function cloneOtelTracesCache(cache: CachedStreamProfile | null): CachedStreamProfile | null {
+  if (!cache || cache.profile.kind !== "otel-traces") return null;
+  return {
+    profile: cloneOtelTracesProfile(cache.profile as OtelTracesStreamProfile),
+    updatedAtMs: cache.updatedAtMs,
+  };
+}
+
+function isOtelTracesProfile(profile: StreamProfileSpec | null | undefined): profile is OtelTracesStreamProfile {
+  return !!profile && profile.kind === "otel-traces";
+}
+
+function parseStringArrayResult(raw: unknown, path: string, maxItems: number): Result<string[] | undefined, { message: string }> {
+  if (raw === undefined) return Result.ok(undefined);
+  if (!Array.isArray(raw)) return Result.err({ message: `${path} must be an array of strings` });
+  if (raw.length > maxItems) return Result.err({ message: `${path} too large (max ${maxItems})` });
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const item of raw) {
+    if (typeof item !== "string") return Result.err({ message: `${path} must be an array of strings` });
+    const value = item.trim();
+    if (value === "") return Result.err({ message: `${path} must not contain empty strings` });
+    const key = value.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(path.endsWith("redactKeys") ? key : value);
+  }
+  return Result.ok(out);
+}
+
+function parsePositiveIntResult(raw: unknown, path: string, fallback: number): Result<number, { message: string }> {
+  if (raw === undefined) return Result.ok(fallback);
+  if (typeof raw !== "number" || !Number.isFinite(raw) || !Number.isInteger(raw) || raw <= 0) {
+    return Result.err({ message: `${path} must be a positive integer` });
+  }
+  return Result.ok(raw);
+}
+
+function parseAttributeLimitsResult(raw: unknown, path: string): Result<Partial<OtelTraceAttributeLimits> | undefined, { message: string }> {
+  if (raw === undefined) return Result.ok(undefined);
+  const objRes = expectPlainObjectResult(raw, path);
+  if (Result.isError(objRes)) return objRes;
+  const keyCheck = rejectUnknownKeysResult(
+    objRes.value,
+    ["maxAttributeValueBytes", "maxAttributesPerSpan", "maxEventsPerSpan", "maxLinksPerSpan", "maxStatementBytes"],
+    path
+  );
+  if (Result.isError(keyCheck)) return keyCheck;
+  const out: Partial<OtelTraceAttributeLimits> = {};
+  for (const key of Object.keys(DEFAULT_ATTRIBUTE_LIMITS) as Array<keyof OtelTraceAttributeLimits>) {
+    const valueRes = parsePositiveIntResult(objRes.value[key], `${path}.${key}`, DEFAULT_ATTRIBUTE_LIMITS[key]);
+    if (Result.isError(valueRes)) return valueRes;
+    if (objRes.value[key] !== undefined) out[key] = valueRes.value;
+  }
+  return Result.ok(Object.keys(out).length > 0 ? out : undefined);
+}
+
+function parseOtlpLimitsResult(raw: unknown, path: string): Result<Partial<OtelTraceOtlpLimits> | undefined, { message: string }> {
+  if (raw === undefined) return Result.ok(undefined);
+  const objRes = expectPlainObjectResult(raw, path);
+  if (Result.isError(objRes)) return objRes;
+  const keyCheck = rejectUnknownKeysResult(
+    objRes.value,
+    [
+      "maxCompressedBytes",
+      "maxDecodedBytes",
+      "maxResourceSpansPerRequest",
+      "maxScopeSpansPerRequest",
+      "maxSpansPerRequest",
+      "maxAnyValueDepth",
+      "maxArrayValuesPerAnyValue",
+      "maxKvListValuesPerAnyValue",
+    ],
+    path
+  );
+  if (Result.isError(keyCheck)) return keyCheck;
+  const out: Partial<OtelTraceOtlpLimits> = {};
+  for (const key of Object.keys(DEFAULT_OTLP_LIMITS) as Array<keyof OtelTraceOtlpLimits>) {
+    const valueRes = parsePositiveIntResult(objRes.value[key], `${path}.${key}`, DEFAULT_OTLP_LIMITS[key]);
+    if (Result.isError(valueRes)) return valueRes;
+    if (objRes.value[key] !== undefined) out[key] = valueRes.value;
+  }
+  return Result.ok(Object.keys(out).length > 0 ? out : undefined);
+}
+
+function parseStoreResult(raw: unknown, path: string): Result<Partial<OtelTraceStoreConfig> | undefined, { message: string }> {
+  if (raw === undefined) return Result.ok(undefined);
+  const objRes = expectPlainObjectResult(raw, path);
+  if (Result.isError(objRes)) return objRes;
+  const keyCheck = rejectUnknownKeysResult(objRes.value, ["rawResourceAttributes", "rawSpanAttributes", "rawEvents", "rawLinks"], path);
+  if (Result.isError(keyCheck)) return keyCheck;
+  const out: Partial<OtelTraceStoreConfig> = {};
+  for (const key of Object.keys(DEFAULT_STORE_CONFIG) as Array<keyof OtelTraceStoreConfig>) {
+    const value = objRes.value[key];
+    if (value === undefined) continue;
+    if (typeof value !== "boolean") return Result.err({ message: `${path}.${key} must be boolean` });
+    out[key] = value;
+  }
+  return Result.ok(Object.keys(out).length > 0 ? out : undefined);
+}
+
+function parseDbStatementModeResult(raw: unknown, path: string): Result<DbStatementMode | undefined, { message: string }> {
+  if (raw === undefined) return Result.ok(undefined);
+  if (raw === "drop" || raw === "raw") return Result.ok(raw);
+  return Result.err({ message: `${path} must be drop or raw` });
+}
+
+function parseUrlModeResult(raw: unknown, path: string): Result<UrlMode | undefined, { message: string }> {
+  if (raw === undefined) return Result.ok(undefined);
+  if (raw === "drop_query" || raw === "raw") return Result.ok(raw);
+  return Result.err({ message: `${path} must be drop_query or raw` });
+}
+
+function parseStreamNameResult(raw: unknown, path: string): Result<string | undefined, { message: string }> {
+  if (raw === undefined) return Result.ok(undefined);
+  if (typeof raw !== "string") return Result.err({ message: `${path} must be a string` });
+  const value = raw.trim();
+  if (value === "") return Result.err({ message: `${path} must not be empty` });
+  return Result.ok(value);
+}
+
+function parseOtelTracesObservabilityResult(raw: unknown, path: string): Result<OtelTracesStreamProfile["observability"] | undefined, { message: string }> {
+  if (raw === undefined) return Result.ok(undefined);
+  const objRes = expectPlainObjectResult(raw, path);
+  if (Result.isError(objRes)) return objRes;
+  const keyCheck = rejectUnknownKeysResult(objRes.value, ["request"], path);
+  if (Result.isError(keyCheck)) return keyCheck;
+
+  if (objRes.value.request === undefined) return Result.ok(undefined);
+  const requestRes = expectPlainObjectResult(objRes.value.request, `${path}.request`);
+  if (Result.isError(requestRes)) return requestRes;
+  const requestKeyCheck = rejectUnknownKeysResult(requestRes.value, ["eventsStream"], `${path}.request`);
+  if (Result.isError(requestKeyCheck)) return requestKeyCheck;
+  const eventsStreamRes = parseStreamNameResult(requestRes.value.eventsStream, `${path}.request.eventsStream`);
+  if (Result.isError(eventsStreamRes)) return eventsStreamRes;
+  if (!eventsStreamRes.value) return Result.ok(undefined);
+
+  return Result.ok({
+    request: {
+      eventsStream: eventsStreamRes.value,
+    },
+  });
+}
+
+function validateOtelTracesProfileResult(raw: unknown, path: string): Result<OtelTracesStreamProfile, { message: string }> {
+  const objRes = expectPlainObjectResult(raw, path);
+  if (Result.isError(objRes)) return objRes;
+  if (objRes.value.kind !== "otel-traces") return Result.err({ message: `${path}.kind must be otel-traces` });
+  const keyCheck = rejectUnknownKeysResult(
+    objRes.value,
+    ["kind", "redactKeys", "requestIdAttributes", "attributeLimits", "store", "dbStatementMode", "urlMode", "otlpLimits", "observability"],
+    path
+  );
+  if (Result.isError(keyCheck)) return keyCheck;
+  const redactKeysRes = parseStringArrayResult(objRes.value.redactKeys, `${path}.redactKeys`, 64);
+  if (Result.isError(redactKeysRes)) return redactKeysRes;
+  const requestIdAttributesRes = parseStringArrayResult(objRes.value.requestIdAttributes, `${path}.requestIdAttributes`, 64);
+  if (Result.isError(requestIdAttributesRes)) return requestIdAttributesRes;
+  const limitsRes = parseAttributeLimitsResult(objRes.value.attributeLimits, `${path}.attributeLimits`);
+  if (Result.isError(limitsRes)) return limitsRes;
+  const storeRes = parseStoreResult(objRes.value.store, `${path}.store`);
+  if (Result.isError(storeRes)) return storeRes;
+  const dbStatementModeRes = parseDbStatementModeResult(objRes.value.dbStatementMode, `${path}.dbStatementMode`);
+  if (Result.isError(dbStatementModeRes)) return dbStatementModeRes;
+  const urlModeRes = parseUrlModeResult(objRes.value.urlMode, `${path}.urlMode`);
+  if (Result.isError(urlModeRes)) return urlModeRes;
+  const otlpLimitsRes = parseOtlpLimitsResult(objRes.value.otlpLimits, `${path}.otlpLimits`);
+  if (Result.isError(otlpLimitsRes)) return otlpLimitsRes;
+  const observabilityRes = parseOtelTracesObservabilityResult(objRes.value.observability, `${path}.observability`);
+  if (Result.isError(observabilityRes)) return observabilityRes;
+  const profile: OtelTracesStreamProfile = { kind: "otel-traces" };
+  if (redactKeysRes.value) profile.redactKeys = redactKeysRes.value;
+  if (requestIdAttributesRes.value) profile.requestIdAttributes = requestIdAttributesRes.value;
+  if (limitsRes.value) profile.attributeLimits = limitsRes.value;
+  if (storeRes.value) profile.store = storeRes.value;
+  if (dbStatementModeRes.value) profile.dbStatementMode = dbStatementModeRes.value;
+  if (urlModeRes.value) profile.urlMode = urlModeRes.value;
+  if (otlpLimitsRes.value) profile.otlpLimits = otlpLimitsRes.value;
+  if (observabilityRes.value) profile.observability = observabilityRes.value;
+  return Result.ok(profile);
+}
+
+function getString(record: Record<string, unknown>, key: string): string | null {
+  const value = record[key];
+  return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+
+function getNumber(record: Record<string, unknown>, key: string): number | null {
+  const value = record[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function severityForSpan(record: Record<string, unknown>): "debug" | "info" | "warn" | "error" {
+  const status = isPlainObject(record.status) ? getString(record.status, "code") : null;
+  const error = isPlainObject(record.error) && record.error.isError === true;
+  return status === "error" || error ? "error" : "info";
+}
+
+function spanEventIsException(event: Record<string, unknown>): boolean {
+  const eventName = getString(event, "name")?.toLowerCase() ?? "";
+  if (eventName === "exception") return true;
+  const attributes = isPlainObject(event.attributes) ? event.attributes : {};
+  return getString(attributes, "exception.type") != null || getString(attributes, "exception.message") != null;
+}
+
+function buildOtelTimelineItems(args: { stream: string; offset?: string; record: unknown }): UnifiedTimelineItem[] {
+  if (!isPlainObject(args.record)) return [];
+  const record = args.record;
+  const traceId = getString(record, "traceId");
+  const spanId = getString(record, "spanId");
+  const parentSpanId = getString(record, "parentSpanId");
+  const requestId = getString(record, "requestId");
+  const service = getString(record, "service");
+  const title = getString(record, "name") ?? spanId ?? "span";
+  const timestamp = getString(record, "timestamp");
+  const endTimestamp = getString(record, "endTimestamp");
+  const duration = getNumber(record, "duration");
+  const severity = severityForSpan(record);
+  const source = { stream: args.stream, offset: args.offset, profile: "otel-traces" };
+  const ids = { requestId, traceId, spanId, parentSpanId };
+  const out: UnifiedTimelineItem[] = [];
+  if (timestamp) {
+    out.push({
+      kind: "otel.span.start",
+      time: timestamp,
+      duration,
+      service,
+      title,
+      severity,
+      ids,
+      source,
+      data: record,
+    });
+  }
+  if (Array.isArray(record.events)) {
+    for (const event of record.events) {
+      if (!isPlainObject(event)) continue;
+      const eventTime = getString(event, "timestamp");
+      const eventName = getString(event, "name") ?? "span event";
+      if (!eventTime) continue;
+      const isException = spanEventIsException(event);
+      out.push({
+        kind: isException ? "otel.exception" : "otel.span.event",
+        time: eventTime,
+        service,
+        title: eventName,
+        severity: isException ? "error" : severity,
+        ids,
+        source,
+        data: event,
+      });
+    }
+  }
+  if (endTimestamp) {
+    out.push({
+      kind: "otel.span.end",
+      time: endTimestamp,
+      duration,
+      service,
+      title,
+      severity,
+      ids,
+      source,
+      data: record,
+    });
+  }
+  return out;
+}
+
+export const OTEL_TRACES_STREAM_PROFILE_DEFINITION: StreamProfileDefinition = {
+  kind: "otel-traces",
+  usesStoredProfileRow: true,
+
+  defaultProfile(): OtelTracesStreamProfile {
+    return { kind: "otel-traces" };
+  },
+
+  validateResult(raw, path) {
+    return validateOtelTracesProfileResult(raw, path);
+  },
+
+  readProfileResult({ row, cached }): Result<StreamProfileReadResult, { message: string }> {
+    if (!row) return Result.ok({ profile: { kind: "otel-traces" }, cache: null });
+    const cachedCopy = cloneOtelTracesCache(cached);
+    if (cachedCopy && cachedCopy.updatedAtMs === row.updated_at_ms) {
+      return Result.ok({
+        profile: cloneOtelTracesProfile(cachedCopy.profile as OtelTracesStreamProfile),
+        cache: cachedCopy,
+      });
+    }
+    const parsedRes = parseStoredProfileJsonResult(row.profile_json);
+    if (Result.isError(parsedRes)) return parsedRes;
+    const profileRes = validateOtelTracesProfileResult(parsedRes.value, "profile");
+    if (Result.isError(profileRes)) return profileRes;
+    const profile = cloneOtelTracesProfile(profileRes.value);
+    return Result.ok({
+      profile: cloneOtelTracesProfile(profile),
+      cache: { profile, updatedAtMs: row.updated_at_ms },
+    });
+  },
+
+  persistProfileResult({ stream, streamRow, profile }): Result<StreamProfilePersistResult, { kind: "bad_request"; message: string; code?: string }> {
+    if (!isOtelTracesProfile(profile)) return Result.err({ kind: "bad_request", message: "invalid otel-traces profile" });
+    const contentType = normalizeProfileContentType(streamRow.content_type);
+    if (contentType !== "application/json") {
+      return Result.err({
+        kind: "bad_request",
+        message: "otel-traces profile requires application/json stream content-type",
+      });
+    }
+    if (streamRow.profile !== "otel-traces" && streamRow.next_offset > 0n) {
+      return Result.err({
+        kind: "bad_request",
+        message: "otel-traces profile must be installed before appending data",
+      });
+    }
+
+    const persistedProfile = cloneOtelTracesProfile(profile);
+    const registry = buildOtelTracesDefaultRegistry(stream);
+    return Result.ok({
+      profile: cloneOtelTracesProfile(persistedProfile),
+      cache: {
+        profile: persistedProfile,
+        updatedAtMs: 0n,
+      },
+      schemaRegistry: registry,
+      streamProfile: persistedProfile.kind,
+      profileJson: JSON.stringify(persistedProfile),
+      touchState: streamRow.profile === "state-protocol" ? "delete" : "preserve",
+    });
+  },
+
+  jsonIngest: {
+    prepareRecordResult({ profile, value }) {
+      if (!isOtelTracesProfile(profile)) return Result.err({ message: "invalid otel-traces profile" });
+      return normalizeOtelTraceRecordResult(profile, value);
+    },
+  },
+
+  otlpTraces: {
+    decodeExportRequestResult({ profile, stream, contentType, contentEncoding, body, maxDecodedBytes }) {
+      if (!isOtelTracesProfile(profile)) return Result.err({ status: 400, message: "invalid otel-traces profile" });
+      return decodeOtlpTraceExportRequestResult({ stream, profile, contentType, contentEncoding, body, maxDecodedBytes });
+    },
+  },
+
+  correlation: {
+    toTimelineItems(args) {
+      return buildOtelTimelineItems(args);
+    },
+  },
+};

package/src/profiles/profile.ts

@@ -0,0 +1,284 @@
+import { Result } from "better-result";
+import type { SchemaRegistry } from "../schema/registry";
+import type { StreamReadRow as StreamRow } from "../store/segment_read_store";
+import type { ProfileTouchStatePlan } from "../store/profile_touch_store";
+import type { MaybePromise } from "../store/capabilities";
+import type { ProfileTouchControlStore, TouchRouteStore } from "../store/touch_store";
+import type { TouchProcessorManager } from "../touch/manager";
+import type { CanonicalChange } from "../touch/canonical_change";
+import type { TouchConfig } from "../touch/spec";
+import type { AggSummaryState } from "../search/agg_format";
+
+export const STREAM_PROFILE_API_VERSION = "durable.streams/profile/v1" as const;
+export const DEFAULT_STREAM_PROFILE = "generic" as const;
+
+export type StreamProfileKind = string;
+
+export type StreamProfileSpec = {
+  kind: StreamProfileKind;
+  [key: string]: unknown;
+};
+
+export type StreamProfileResource = {
+  apiVersion: typeof STREAM_PROFILE_API_VERSION;
+  profile: StreamProfileSpec;
+};
+
+export type StreamProfileMutationError = {
+  kind: "bad_request";
+  message: string;
+  code?: string;
+};
+
+export type StreamProfileReadError = {
+  kind: "invalid_profile";
+  message: string;
+  code?: string;
+};
+
+export type StreamProfileValidationError = {
+  message: string;
+};
+
+export type StoredProfileRow = {
+  stream: string;
+  profile_json: string;
+  updated_at_ms: bigint;
+};
+
+export type CachedStreamProfile = {
+  profile: StreamProfileSpec;
+  updatedAtMs: bigint;
+};
+
+export type StreamProfileReadResult = {
+  profile: StreamProfileSpec;
+  cache: CachedStreamProfile | null;
+};
+
+export type StreamProfilePersistResult = {
+  profile: StreamProfileSpec;
+  cache: CachedStreamProfile | null;
+  schemaRegistry?: SchemaRegistry | null;
+  streamProfile: string | null;
+  profileJson: string | null;
+  touchState: ProfileTouchStatePlan;
+};
+
+export type PersistProfileArgs = {
+  stream: string;
+  streamRow: StreamRow;
+  profile: StreamProfileSpec;
+};
+
+export type PreparedJsonRecord = {
+  value: unknown;
+  routingKey: string | null;
+};
+
+export type OtlpTraceExportResponseEncoding = "protobuf" | "json";
+
+export type OtlpTraceExportResult = {
+  records: PreparedJsonRecord[];
+  acceptedSpans: number;
+  rejectedSpans: number;
+  warnings: string[];
+  responseEncoding: OtlpTraceExportResponseEncoding;
+};
+
+export type OtlpTraceExportError = {
+  message: string;
+  status?: 400 | 413 | 415;
+};
+
+export type UnifiedTimelineItem = {
+  kind: "evlog.event" | "otel.span.start" | "otel.span.end" | "otel.span.event" | "otel.exception";
+  time: string;
+  duration?: number | null;
+  service?: string | null;
+  title: string;
+  severity: "debug" | "info" | "warn" | "error";
+  ids: {
+    requestId?: string | null;
+    traceId?: string | null;
+    spanId?: string | null;
+    parentSpanId?: string | null;
+  };
+  source: {
+    stream: string;
+    offset?: string;
+    profile: string;
+  };
+  data: unknown;
+};
+
+export type MetricsCompanionRecord = {
+  metric: string;
+  unit: string;
+  metricKind: string;
+  temporality: string;
+  windowStartMs: number;
+  windowEndMs: number;
+  intervalMs: number;
+  stream: string | null;
+  instance: string | null;
+  attributes: Record<string, string>;
+  dimensionPairs: string[];
+  dimensionKey: string | null;
+  seriesKey: string;
+  summary: AggSummaryState;
+};
+
+export type NormalizedMetricsRecord = PreparedJsonRecord & {
+  value: Record<string, unknown>;
+  companion: MetricsCompanionRecord;
+};
+
+export type StreamTouchRoute =
+  | { kind: "meta" }
+  | { kind: "wait" }
+  | { kind: "templates_activate" };
+
+export type StreamProfileTouchResponder = {
+  json(status: number, body: any, headers?: HeadersInit): Response;
+  badRequest(message: string): Response;
+  internalError(message?: string): Response;
+  notFound(message?: string): Response;
+};
+
+export type StreamTouchRouteStore = TouchRouteStore;
+
+export type StreamTouchRouteArgs = {
+  route: StreamTouchRoute;
+  req: Request;
+  stream: string;
+  streamRow: StreamRow;
+  profile: StreamProfileSpec;
+  db: StreamTouchRouteStore;
+  touchManager: TouchProcessorManager;
+  respond: StreamProfileTouchResponder;
+};
+
+export interface StreamTouchCapability {
+  getTouchConfig(profile: StreamProfileSpec): TouchConfig | null;
+  syncState(args: { db: ProfileTouchControlStore; stream: string; profile: StreamProfileSpec }): MaybePromise<void>;
+  deriveCanonicalChanges(record: unknown, profile: StreamProfileSpec): CanonicalChange[];
+  handleRoute?(args: StreamTouchRouteArgs): Promise<Response>;
+}
+
+export interface StreamProfileJsonIngestCapability {
+  prepareRecordResult(args: { stream: string; profile: StreamProfileSpec; value: unknown }): Result<PreparedJsonRecord, StreamProfileValidationError>;
+}
+
+export interface StreamProfileOtlpTracesCapability {
+  decodeExportRequestResult(args: {
+    stream: string;
+    profile: StreamProfileSpec;
+    contentType: string;
+    contentEncoding: string | null;
+    body: Uint8Array;
+    maxDecodedBytes: number;
+  }): Result<OtlpTraceExportResult, OtlpTraceExportError>;
+}
+
+export interface StreamProfileCorrelationCapability {
+  toTimelineItems(args: { stream: string; offset?: string; record: unknown }): UnifiedTimelineItem[];
+}
+
+export interface StreamProfileMetricsCapability {
+  normalizeRecordResult(args: {
+    stream: string;
+    profile: StreamProfileSpec;
+    value: unknown;
+  }): Result<NormalizedMetricsRecord, StreamProfileValidationError>;
+}
+
+export interface StreamProfileDefinition {
+  kind: StreamProfileKind;
+  usesStoredProfileRow: boolean;
+  defaultProfile(): StreamProfileSpec;
+  validateResult(raw: unknown, path: string): Result<StreamProfileSpec, StreamProfileValidationError>;
+  readProfileResult(args: { row: StoredProfileRow | null; cached: CachedStreamProfile | null }): Result<StreamProfileReadResult, StreamProfileValidationError>;
+  persistProfileResult(args: PersistProfileArgs): Result<StreamProfilePersistResult, StreamProfileMutationError>;
+  touch?: StreamTouchCapability;
+  jsonIngest?: StreamProfileJsonIngestCapability;
+  otlpTraces?: StreamProfileOtlpTracesCapability;
+  correlation?: StreamProfileCorrelationCapability;
+  metrics?: StreamProfileMetricsCapability;
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export function expectPlainObjectResult(
+  value: unknown,
+  path: string
+): Result<Record<string, unknown>, StreamProfileValidationError> {
+  if (!isPlainObject(value)) return Result.err({ message: `${path} must be an object` });
+  return Result.ok(value);
+}
+
+export function rejectUnknownKeysResult(
+  obj: Record<string, unknown>,
+  allowed: readonly string[],
+  path: string
+): Result<void, StreamProfileValidationError> {
+  const allowedSet = new Set(allowed);
+  for (const key of Object.keys(obj)) {
+    if (!allowedSet.has(key)) return Result.err({ message: `${path}.${key} is not supported` });
+  }
+  return Result.ok(undefined);
+}
+
+export function normalizeProfileContentType(value: string | null): string | null {
+  if (!value) return null;
+  const base = value.split(";")[0]?.trim().toLowerCase();
+  return base ? base : null;
+}
+
+export function parseStoredProfileJsonResult(raw: string): Result<unknown, StreamProfileValidationError> {
+  try {
+    return Result.ok(JSON.parse(raw));
+  } catch (e: any) {
+    return Result.err({ message: String(e?.message ?? e) });
+  }
+}
+
+export function readProfileKindResult(
+  raw: unknown,
+  path = "profile"
+): Result<StreamProfileKind, StreamProfileValidationError> {
+  const objRes = expectPlainObjectResult(raw, path);
+  if (Result.isError(objRes)) return objRes;
+  const kind = typeof objRes.value.kind === "string" ? objRes.value.kind.trim() : "";
+  if (kind !== "") return Result.ok(kind);
+  return Result.err({ message: `${path}.kind must be a non-empty string` });
+}
+
+export function parseProfileUpdateEnvelopeResult(body: unknown): Result<unknown, StreamProfileValidationError> {
+  const bodyRes = expectPlainObjectResult(body, "profile update");
+  if (Result.isError(bodyRes)) {
+    return Result.err({ message: "profile update must be a JSON object" });
+  }
+  const keyCheck = rejectUnknownKeysResult(bodyRes.value, ["apiVersion", "profile"], "profileUpdate");
+  if (Result.isError(keyCheck)) return keyCheck;
+  if (bodyRes.value.apiVersion !== undefined && bodyRes.value.apiVersion !== STREAM_PROFILE_API_VERSION) {
+    return Result.err({ message: "invalid profile apiVersion" });
+  }
+  if (!Object.prototype.hasOwnProperty.call(bodyRes.value, "profile")) {
+    return Result.err({ message: "missing profile" });
+  }
+  return Result.ok(bodyRes.value.profile);
+}
+
+export function cloneStreamProfileSpec(profile: StreamProfileSpec): StreamProfileSpec {
+  return structuredClone(profile);
+}
+
+export function buildStreamProfileResource(profile: StreamProfileSpec): StreamProfileResource {
+  return {
+    apiVersion: STREAM_PROFILE_API_VERSION,
+    profile: cloneStreamProfileSpec(profile),
+  };
+}