@streamotter/contracts 0.1.0-rc.1

package/src/config.ts

@@ -0,0 +1,311 @@
+import { StreamOtterError } from "./errors.ts";
+import { validateLimits } from "./limits.ts";
+import { IDENTIFIER_PATTERN, isPlainObject } from "./primitives.ts";
+import { pointer, validateParamsSchema, validateSchemaDefinition } from "./schema.ts";
+import type { ConfigIssue, ProjectConfig, Schema } from "./types.ts";
+
+export interface ConfigValidation { valid: boolean; issues: ConfigIssue[] }
+
+/** Keys that belong to deferred V2/V3 features; reported with a clear message. */
+const DEFERRED_FEATURES: Readonly<Record<string, string>> = {
+  history: "Retained history is a V2 feature and is not supported in V1.",
+  recovery: "Client recovery cursors are a V2 feature and are not supported in V1.",
+  retention: "Retention windows are a V2 feature and are not supported in V1.",
+  acknowledgement: "Application acknowledgements are a V2 feature and are not supported in V1.",
+  resume: "Resume policies are a V2 feature and are not supported in V1.",
+  replay: "Replay is a V2 feature and is not supported in V1.",
+  commands: "Commands are a V3 feature and are not supported in V1.",
+  command: "Commands are a V3 feature and are not supported in V1.",
+  gateways: "Multiple gateways are a V2 feature and are not supported in V1.",
+  cluster: "Multiple gateways are a V2 feature and are not supported in V1.",
+  schemaRegistry: "Schema Registry integration is a V2 feature and is not supported in V1.",
+  workspaces: "Team workspaces are a V3 feature and are not supported in V1.",
+  environments: "Environments are a V3 feature and are not supported in V1.",
+  transports: "Only the Socket.IO transport is supported in V1.",
+  transport: "Only the Socket.IO transport is supported in V1."
+};
+
+const ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const KAFKA_NAME_PATTERN = /^[A-Za-z0-9._-]{1,249}$/;
+const BROKER_PATTERN = /^[A-Za-z0-9.-]+:[0-9]{1,5}$|^\[[0-9A-Fa-f:.]+\]:[0-9]{1,5}$/;
+
+class Checker {
+  readonly issues: ConfigIssue[] = [];
+
+  add(path: string, code: string, message: string): void {
+    this.issues.push({ path, code, message });
+  }
+
+  /** Reports unknown keys (with deferred-feature messages) and missing required keys. */
+  keys(value: Record<string, unknown>, path: string, required: readonly string[], optional: readonly string[] = []): void {
+    for (const key of Object.keys(value)) {
+      if (required.includes(key) || optional.includes(key)) continue;
+      const deferred = DEFERRED_FEATURES[key];
+      if (deferred !== undefined) this.add(pointer(path, key), "UNSUPPORTED_FEATURE", deferred);
+      else this.add(pointer(path, key), "UNKNOWN_KEY", `Unknown key "${key}".`);
+    }
+    for (const key of required) {
+      if (!Object.hasOwn(value, key) || value[key] === undefined) this.add(pointer(path, key), "REQUIRED", `"${key}" is required.`);
+    }
+  }
+
+  object(value: unknown, path: string, label: string): value is Record<string, unknown> {
+    if (isPlainObject(value)) return true;
+    this.add(path, "INVALID_TYPE", `${label} must be an object.`);
+    return false;
+  }
+
+  identifier(value: unknown, path: string, label: string): value is string {
+    if (typeof value === "string" && IDENTIFIER_PATTERN.test(value)) return true;
+    this.add(path, "INVALID_IDENTIFIER", `${label} must match [A-Za-z][A-Za-z0-9_-]{0,63}.`);
+    return false;
+  }
+
+  nonEmptyString(value: unknown, path: string, label: string, max = 1024): value is string {
+    if (typeof value === "string" && value.length > 0 && value.length <= max) return true;
+    this.add(path, "INVALID_VALUE", `${label} must be a non-empty string of at most ${max} characters.`);
+    return false;
+  }
+
+  secretRef(value: unknown, path: string): void {
+    if (!this.object(value, path, "A secret reference")) return;
+    this.keys(value, path, ["env"]);
+    if (value["env"] !== undefined && !(typeof value["env"] === "string" && ENV_NAME_PATTERN.test(value["env"]))) {
+      this.add(pointer(path, "env"), "INVALID_VALUE", "env must name an environment variable.");
+    }
+  }
+}
+
+function isOrigin(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  try {
+    const url = new URL(value);
+    return (url.protocol === "http:" || url.protocol === "https:") && url.origin === value;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Structural, schema, and reference validation of a portable configuration.
+ * Never resolves secrets, runs handlers, or connects to brokers.
+ */
+export function validateProjectConfig(input: unknown): ConfigValidation {
+  const c = new Checker();
+  if (!c.object(input, "", "The configuration")) return { valid: false, issues: c.issues };
+  c.keys(input, "", ["configVersion", "projectId", "gateway", "connections", "sources", "schemas", "channels"], ["limits"]);
+
+  if (input["configVersion"] !== undefined && input["configVersion"] !== 1) {
+    c.add("/configVersion", "UNSUPPORTED_FEATURE", "Only configVersion 1 is supported.");
+  }
+  if (input["projectId"] !== undefined) c.identifier(input["projectId"], "/projectId", "projectId");
+
+  const gateway = input["gateway"];
+  if (gateway !== undefined && c.object(gateway, "/gateway", "gateway")) {
+    c.keys(gateway, "/gateway", ["host", "port", "path", "allowedOrigins"]);
+    if (gateway["host"] !== undefined) c.nonEmptyString(gateway["host"], "/gateway/host", "host", 253);
+    const port = gateway["port"];
+    if (port !== undefined && !(typeof port === "number" && Number.isInteger(port) && port >= 0 && port <= 65_535)) {
+      c.add("/gateway/port", "INVALID_VALUE", "port must be an integer from 0 to 65535.");
+    }
+    const path = gateway["path"];
+    if (path !== undefined && !(typeof path === "string" && /^\/[A-Za-z0-9._~\/-]*$/.test(path) && path.length <= 256)) {
+      c.add("/gateway/path", "INVALID_VALUE", "path must be an absolute URL path without a query or fragment.");
+    }
+    const origins = gateway["allowedOrigins"];
+    if (origins !== undefined) {
+      if (!Array.isArray(origins)) {
+        c.add("/gateway/allowedOrigins", "INVALID_TYPE", "allowedOrigins must be an array of exact origins.");
+      } else {
+        origins.forEach((origin, index) => {
+          if (!isOrigin(origin)) {
+            c.add(pointer("/gateway/allowedOrigins", index), "INVALID_VALUE", "Each allowed origin must be an exact http(s) origin such as https://app.example.com; wildcards are not allowed.");
+          }
+        });
+        if (new Set(origins).size !== origins.length) c.add("/gateway/allowedOrigins", "DUPLICATE", "allowedOrigins must be unique.");
+      }
+    }
+  }
+
+  const connectionIds = new Set<string>();
+  const connections = input["connections"];
+  if (connections !== undefined && c.object(connections, "/connections", "connections")) {
+    for (const [id, profile] of Object.entries(connections)) {
+      const path = pointer("/connections", id);
+      if (!c.identifier(id, path, "Connection profile IDs")) continue;
+      connectionIds.add(id);
+      if (!c.object(profile, path, "A connection profile")) continue;
+      c.keys(profile, path, ["brokers", "tls"], ["sasl"]);
+      const brokers = profile["brokers"];
+      if (brokers !== undefined) {
+        if (!Array.isArray(brokers) || brokers.length === 0) {
+          c.add(pointer(path, "brokers"), "INVALID_VALUE", "brokers must be a non-empty array of host:port strings.");
+        } else {
+          brokers.forEach((broker, index) => {
+            if (typeof broker !== "string" || !BROKER_PATTERN.test(broker)) {
+              c.add(pointer(pointer(path, "brokers"), index), "INVALID_VALUE", "Each broker must be host:port.");
+            }
+          });
+        }
+      }
+      const tls = profile["tls"];
+      if (tls !== undefined && tls !== false) {
+        if (c.object(tls, pointer(path, "tls"), "tls (false or an object)")) {
+          c.keys(tls, pointer(path, "tls"), [], ["caFile"]);
+          if (tls["caFile"] !== undefined) c.nonEmptyString(tls["caFile"], pointer(pointer(path, "tls"), "caFile"), "caFile", 4096);
+        }
+      }
+      const sasl = profile["sasl"];
+      if (sasl !== undefined && c.object(sasl, pointer(path, "sasl"), "sasl")) {
+        const saslPath = pointer(path, "sasl");
+        c.keys(sasl, saslPath, ["mechanism", "username", "password"]);
+        const mechanism = sasl["mechanism"];
+        if (mechanism !== undefined && mechanism !== "plain" && mechanism !== "scram-sha-256" && mechanism !== "scram-sha-512") {
+          c.add(pointer(saslPath, "mechanism"), "UNSUPPORTED_FEATURE", "SASL mechanism must be plain, scram-sha-256, or scram-sha-512 (OAuth is not supported in V1).");
+        }
+        if (sasl["username"] !== undefined) c.secretRef(sasl["username"], pointer(saslPath, "username"));
+        if (sasl["password"] !== undefined) c.secretRef(sasl["password"], pointer(saslPath, "password"));
+      }
+    }
+  }
+
+  const sourceIds = new Set<string>();
+  const kafkaProfiles = new Set<string>();
+  const consumerGroups = new Map<string, string>();
+  const sources = input["sources"];
+  if (sources !== undefined && c.object(sources, "/sources", "sources")) {
+    for (const [id, source] of Object.entries(sources)) {
+      const path = pointer("/sources", id);
+      if (!c.identifier(id, path, "Source IDs")) continue;
+      sourceIds.add(id);
+      if (!c.object(source, path, "A source")) continue;
+      const kind = source["kind"];
+      if (kind === "kafka") {
+        c.keys(source, path, ["kind", "generation", "connectionRef", "topics", "consumerGroup", "codec", "startFrom"]);
+        if (source["generation"] !== undefined) c.identifier(source["generation"], pointer(path, "generation"), "generation");
+        const ref = source["connectionRef"];
+        if (ref !== undefined) {
+          if (typeof ref !== "string" || !connectionIds.has(ref)) {
+            c.add(pointer(path, "connectionRef"), "UNKNOWN_REFERENCE", "connectionRef must name a configured connection profile.");
+          } else {
+            kafkaProfiles.add(ref);
+          }
+        }
+        const topics = source["topics"];
+        if (topics !== undefined) {
+          if (!Array.isArray(topics) || topics.length === 0) {
+            c.add(pointer(path, "topics"), "INVALID_VALUE", "topics must be a non-empty array.");
+          } else {
+            topics.forEach((topic, index) => {
+              if (typeof topic !== "string" || !KAFKA_NAME_PATTERN.test(topic)) {
+                c.add(pointer(pointer(path, "topics"), index), "INVALID_VALUE", "Topic names may contain letters, digits, '.', '_', and '-'.");
+              }
+            });
+            if (new Set(topics).size !== topics.length) c.add(pointer(path, "topics"), "DUPLICATE", "topics must be unique.");
+          }
+        }
+        const group = source["consumerGroup"];
+        if (group !== undefined) {
+          if (typeof group !== "string" || !KAFKA_NAME_PATTERN.test(group)) {
+            c.add(pointer(path, "consumerGroup"), "INVALID_VALUE", "consumerGroup may contain letters, digits, '.', '_', and '-'.");
+          } else {
+            const owner = consumerGroups.get(group);
+            if (owner !== undefined) {
+              c.add(pointer(path, "consumerGroup"), "CONSUMER_GROUP_CONFLICT", `Consumer group "${group}" is already used by source "${owner}"; each source needs a dedicated group.`);
+            } else {
+              consumerGroups.set(group, id);
+            }
+          }
+        }
+        if (source["codec"] !== undefined && source["codec"] !== "json") {
+          c.add(pointer(path, "codec"), "UNSUPPORTED_FEATURE", "Only the json codec is supported in V1.");
+        }
+        const startFrom = source["startFrom"];
+        if (startFrom !== undefined && startFrom !== "latest" && startFrom !== "earliest") {
+          c.add(pointer(path, "startFrom"), "INVALID_VALUE", "startFrom must be latest or earliest.");
+        }
+      } else if (kind === "fixture") {
+        c.keys(source, path, ["kind", "generation", "fixtureRef"]);
+        if (source["generation"] !== undefined) c.identifier(source["generation"], pointer(path, "generation"), "generation");
+        if (source["fixtureRef"] !== undefined) c.identifier(source["fixtureRef"], pointer(path, "fixtureRef"), "fixtureRef");
+      } else {
+        c.add(pointer(path, "kind"), "UNSUPPORTED_FEATURE", "Source kind must be kafka or fixture in V1.");
+      }
+    }
+  }
+  if (kafkaProfiles.size > 1) {
+    c.add("/sources", "MULTIPLE_CONNECTIONS", "V1 supports one Kafka connection profile per project; list multiple brokers of one cluster in that profile instead.");
+  }
+
+  const schemaDefinitions = new Map<string, Schema>();
+  const schemas = input["schemas"];
+  if (schemas !== undefined && c.object(schemas, "/schemas", "schemas")) {
+    for (const [id, schema] of Object.entries(schemas)) {
+      const path = pointer("/schemas", id);
+      if (!c.identifier(id, path, "Schema IDs")) continue;
+      if (validateSchemaDefinition(schema, path, c.issues)) schemaDefinitions.set(id, schema);
+    }
+  }
+
+  const channels = input["channels"];
+  if (channels !== undefined && c.object(channels, "/channels", "channels")) {
+    for (const [name, channel] of Object.entries(channels)) {
+      const path = pointer("/channels", name);
+      if (!c.identifier(name, path, "Channel names")) continue;
+      if (!c.object(channel, path, "A channel")) continue;
+      c.keys(channel, path, ["version", "source", "paramsSchema", "payloadSchema", "handlersRef", "delivery"]);
+      const version = channel["version"];
+      if (version !== undefined && !(typeof version === "number" && Number.isSafeInteger(version) && version > 0)) {
+        c.add(pointer(path, "version"), "INVALID_VALUE", "version must be a positive integer.");
+      }
+      const source = channel["source"];
+      if (source !== undefined && (typeof source !== "string" || !sourceIds.has(source))) {
+        c.add(pointer(path, "source"), "UNKNOWN_REFERENCE", "source must name a configured source.");
+      }
+      for (const key of ["paramsSchema", "payloadSchema"] as const) {
+        const ref = channel[key];
+        if (ref === undefined) continue;
+        if (typeof ref !== "string" || !(schemas !== undefined && isPlainObject(schemas) && Object.hasOwn(schemas, ref))) {
+          c.add(pointer(path, key), "UNKNOWN_REFERENCE", `${key} must name a configured schema.`);
+        }
+      }
+      const paramsRef = channel["paramsSchema"];
+      if (typeof paramsRef === "string") {
+        const schema = schemaDefinitions.get(paramsRef);
+        if (schema !== undefined) validateParamsSchema(schema, pointer("/schemas", paramsRef), c.issues);
+      }
+      const handlersRef = channel["handlersRef"];
+      if (handlersRef !== undefined && handlersRef !== name) {
+        c.add(pointer(path, "handlersRef"), "HANDLERS_REF_MISMATCH", "handlersRef must equal the channel name in V1.");
+      }
+      const delivery = channel["delivery"];
+      if (delivery !== undefined && c.object(delivery, pointer(path, "delivery"), "delivery")) {
+        const deliveryPath = pointer(path, "delivery");
+        c.keys(delivery, deliveryPath, ["kind", "overflow"]);
+        if (delivery["kind"] !== undefined && delivery["kind"] !== "state") {
+          c.add(pointer(deliveryPath, "kind"), "UNSUPPORTED_FEATURE",
+            delivery["kind"] === "events"
+              ? "Retained event channels (delivery.kind \"events\") are a V2 feature; V1 supports only \"state\"."
+              : "delivery.kind must be \"state\" in V1.");
+        }
+        if (delivery["overflow"] !== undefined && delivery["overflow"] !== "resync") {
+          c.add(pointer(deliveryPath, "overflow"), "UNSUPPORTED_FEATURE", "delivery.overflow must be \"resync\" in V1.");
+        }
+      }
+    }
+  }
+
+  validateLimits(input["limits"], "/limits", c.issues);
+  return { valid: c.issues.length === 0, issues: c.issues };
+}
+
+/** Throws CONFIG_INVALID with the issues attached when the configuration is invalid. */
+export function assertValidProjectConfig(input: unknown): asserts input is ProjectConfig {
+  const { valid, issues } = validateProjectConfig(input);
+  if (valid) return;
+  const summary = issues.slice(0, 3).map(issue => `${issue.path || "/"}: ${issue.message}`).join("; ");
+  throw new StreamOtterError("CONFIG_INVALID", {
+    message: `The configuration is invalid (${issues.length} issue${issues.length === 1 ? "" : "s"}): ${summary}`,
+    details: { issues: issues.map(issue => ({ path: issue.path, code: issue.code, message: issue.message })) }
+  });
+}

package/src/errors.ts

@@ -0,0 +1,118 @@
+import type { ErrorCode, Json, StreamError } from "./types.ts";
+
+/** Public, action-oriented messages. Never include topics, secrets, or payloads. */
+export const PUBLIC_MESSAGES: Readonly<Record<ErrorCode, string>> = {
+  UNAUTHENTICATED: "Authentication is required or has expired.",
+  FORBIDDEN: "This subscription is not permitted.",
+  INVALID_PARAMS: "The channel parameters are invalid.",
+  CHANNEL_NOT_FOUND: "The channel is not configured.",
+  CHANNEL_VERSION_UNSUPPORTED: "The requested channel version is not deployed.",
+  SOURCE_UNAVAILABLE: "The source is unavailable; this view may be stale.",
+  INVALID_PAYLOAD: "The data did not match its declared contract.",
+  OVERLOADED: "The gateway is over its configured limits; try again later.",
+  RESYNC_REQUIRED: "Automatic synchronization stopped; call resync() to try again.",
+  UNSUPPORTED_CAPABILITY: "The requested capability is not supported by this gateway.",
+  INVALID_REQUEST: "The request is malformed.",
+  CONFIG_INVALID: "The configuration is invalid.",
+  TIMEOUT: "The operation did not complete before its deadline.",
+  CANCELLED: "The operation was cancelled.",
+  CLIENT_CLOSED: "The client is closed; create a new client.",
+  HANDLER_FAILED: "An application handler failed.",
+  REVISION_CONFLICT: "Conflicting data was received for the same revision.",
+  TRACE_CURSOR_EXPIRED: "The trace cursor has expired; start from the latest traces.",
+  INTERNAL: "An unexpected error occurred."
+};
+
+const DEFAULT_RETRYABLE: Readonly<Record<ErrorCode, boolean>> = {
+  UNAUTHENTICATED: true,
+  FORBIDDEN: false,
+  INVALID_PARAMS: false,
+  CHANNEL_NOT_FOUND: false,
+  CHANNEL_VERSION_UNSUPPORTED: false,
+  SOURCE_UNAVAILABLE: true,
+  INVALID_PAYLOAD: false,
+  OVERLOADED: true,
+  RESYNC_REQUIRED: true,
+  UNSUPPORTED_CAPABILITY: false,
+  INVALID_REQUEST: false,
+  CONFIG_INVALID: false,
+  TIMEOUT: true,
+  CANCELLED: false,
+  CLIENT_CLOSED: false,
+  HANDLER_FAILED: true,
+  REVISION_CONFLICT: false,
+  TRACE_CURSOR_EXPIRED: false,
+  INTERNAL: true
+};
+
+export const ERROR_CODES = Object.keys(DEFAULT_RETRYABLE) as readonly ErrorCode[];
+
+export function isErrorCode(value: unknown): value is ErrorCode {
+  return typeof value === "string" && Object.hasOwn(DEFAULT_RETRYABLE, value);
+}
+
+export interface StreamErrorOptions {
+  message?: string;
+  retryable?: boolean;
+  requestId?: string;
+  details?: Readonly<Record<string, Json>>;
+}
+
+/**
+ * An Error that also satisfies the StreamError shape. SDK promises reject with
+ * it; its enumerable fields serialize to exactly the public StreamError object.
+ */
+export class StreamOtterError extends Error implements StreamError {
+  code: ErrorCode;
+  retryable: boolean;
+  requestId: string;
+  details?: Readonly<Record<string, Json>>;
+
+  constructor(code: ErrorCode, options: StreamErrorOptions = {}) {
+    super(options.message ?? PUBLIC_MESSAGES[code]);
+    Object.defineProperty(this, "message", { enumerable: true, writable: true, configurable: true, value: this.message });
+    Object.defineProperty(this, "name", { enumerable: false, value: "StreamOtterError" });
+    this.code = code;
+    this.retryable = options.retryable ?? DEFAULT_RETRYABLE[code];
+    this.requestId = options.requestId ?? "";
+    if (options.details !== undefined) this.details = options.details;
+  }
+
+  toJSON(): StreamError {
+    return toStreamError(this);
+  }
+}
+
+export function streamError(code: ErrorCode, options: StreamErrorOptions = {}): StreamError {
+  const error: StreamError = {
+    code,
+    message: options.message ?? PUBLIC_MESSAGES[code],
+    retryable: options.retryable ?? DEFAULT_RETRYABLE[code],
+    requestId: options.requestId ?? ""
+  };
+  if (options.details !== undefined) error.details = options.details;
+  return error;
+}
+
+/** Copies only the public StreamError fields. */
+export function toStreamError(error: StreamError): StreamError {
+  const copy: StreamError = { code: error.code, message: error.message, retryable: error.retryable, requestId: error.requestId };
+  if (error.details !== undefined) copy.details = error.details;
+  return copy;
+}
+
+export function isStreamError(value: unknown): value is StreamError {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Record<string, unknown>;
+  return isErrorCode(candidate["code"])
+    && typeof candidate["message"] === "string"
+    && typeof candidate["retryable"] === "boolean"
+    && typeof candidate["requestId"] === "string";
+}
+
+export function asStreamOtterError(error: StreamError): StreamOtterError {
+  if (error instanceof StreamOtterError) return error;
+  const options: StreamErrorOptions = { message: error.message, retryable: error.retryable, requestId: error.requestId };
+  if (error.details !== undefined) options.details = error.details;
+  return new StreamOtterError(error.code, options);
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export type * from "./types.ts";
+export * from "./errors.ts";
+export * from "./primitives.ts";
+export * from "./schema.ts";
+export * from "./limits.ts";
+export * from "./protocol.ts";
+export * from "./config.ts";

package/src/limits.ts

@@ -0,0 +1,78 @@
+import { pointer } from "./schema.ts";
+import type { ConfigIssue, Limits } from "./types.ts";
+
+/** Starting bounds from the specification; not published capacity claims. */
+export const DEFAULT_LIMITS: Readonly<Limits> = Object.freeze({
+  maxConnections: 1_000,
+  maxSubscriptionsPerConnection: 50,
+  maxSourceRecordBytes: 1_048_576,
+  maxDataFrameBytes: 65_536,
+  maxParamsBytes: 4_096,
+  maxPendingFramesPerSubscription: 100,
+  maxPendingBytesPerSubscription: 1_048_576,
+  maxPendingBytesPerConnection: 4_194_304,
+  maxPendingBytesGateway: 67_108_864,
+  maxMapOutputs: 100,
+  maxConcurrentSnapshots: 32,
+  handlerTimeoutMs: 2_000,
+  snapshotTimeoutMs: 10_000,
+  receiptTimeoutMs: 5_000,
+  maxSyncAttempts: 3,
+  maxTraceEntries: 10_000,
+  maxTraceBytes: 8_388_608,
+  maxControlFrameBytes: 16_384,
+  controlRequestsPerSecond: 20
+});
+
+export const LIMIT_KEYS = Object.keys(DEFAULT_LIMITS) as readonly (keyof Limits)[];
+
+export function resolveLimits(overrides: Partial<Limits> | undefined): Limits {
+  return { ...DEFAULT_LIMITS, ...(overrides ?? {}) };
+}
+
+/** Validates override values and cross-field consistency of the resolved limits. */
+export function validateLimits(input: unknown, path: string, issues: ConfigIssue[]): void {
+  if (input === undefined) return;
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    issues.push({ path, code: "INVALID_TYPE", message: "limits must be an object." });
+    return;
+  }
+  const overrides: Partial<Limits> = {};
+  let valid = true;
+  for (const [key, value] of Object.entries(input)) {
+    if (!(LIMIT_KEYS as readonly string[]).includes(key)) {
+      issues.push({ path: pointer(path, key), code: "UNKNOWN_KEY", message: `Unknown limit "${key}".` });
+      valid = false;
+      continue;
+    }
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+      issues.push({ path: pointer(path, key), code: "INVALID_VALUE", message: `${key} must be a positive integer.` });
+      valid = false;
+      continue;
+    }
+    overrides[key as keyof Limits] = value;
+  }
+  if (!valid) return;
+  const limits = resolveLimits(overrides);
+  const ordered: [keyof Limits, keyof Limits][] = [
+    ["maxDataFrameBytes", "maxPendingBytesPerSubscription"],
+    ["maxPendingBytesPerSubscription", "maxPendingBytesPerConnection"],
+    ["maxPendingBytesPerConnection", "maxPendingBytesGateway"],
+    ["maxParamsBytes", "maxControlFrameBytes"]
+  ];
+  for (const [smaller, larger] of ordered) {
+    if (limits[smaller] > limits[larger]) {
+      issues.push({
+        path: pointer(path, smaller),
+        code: "INCONSISTENT_LIMITS",
+        message: `${smaller} (${limits[smaller]}) must not exceed ${larger} (${limits[larger]}).`
+      });
+    }
+  }
+  if (limits.maxControlFrameBytes < 1_024) {
+    issues.push({ path: pointer(path, "maxControlFrameBytes"), code: "INCONSISTENT_LIMITS", message: "maxControlFrameBytes must be at least 1024." });
+  }
+  if (limits.maxDataFrameBytes < 1_024) {
+    issues.push({ path: pointer(path, "maxDataFrameBytes"), code: "INCONSISTENT_LIMITS", message: "maxDataFrameBytes must be at least 1024." });
+  }
+}

package/src/primitives.ts

@@ -0,0 +1,112 @@
+import type { Json, Revision } from "./types.ts";
+
+export const MAX_NESTING_DEPTH = 16;
+export const IDENTIFIER_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+export const REVISION_PATTERN = /^(?:0|[1-9][0-9]{0,38})$/;
+export const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const RFC3339_UTC_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/;
+
+export function isIdentifier(value: unknown): value is string {
+  return typeof value === "string" && IDENTIFIER_PATTERN.test(value);
+}
+
+export function isUuid(value: unknown): value is string {
+  return typeof value === "string" && UUID_PATTERN.test(value);
+}
+
+export function isRevision(value: unknown): value is Revision {
+  return typeof value === "string" && REVISION_PATTERN.test(value);
+}
+
+/** Numeric comparison of canonical revisions without converting to number. */
+export function compareRevisions(a: Revision, b: Revision): -1 | 0 | 1 {
+  if (a.length !== b.length) return a.length < b.length ? -1 : 1;
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+
+/** Parses a UTC RFC3339 timestamp; returns NaN when malformed. */
+export function parseUtcTimestamp(value: unknown): number {
+  if (typeof value !== "string" || !RFC3339_UTC_PATTERN.test(value)) return Number.NaN;
+  return Date.parse(value);
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value) as unknown;
+  return proto === Object.prototype || proto === null;
+}
+
+/** UTF-8 byte length without allocating an encoded copy. */
+export function utf8ByteLength(text: string): number {
+  let bytes = 0;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code < 0x80) bytes += 1;
+    else if (code < 0x800) bytes += 2;
+    else if (code >= 0xd800 && code <= 0xdbff && i + 1 < text.length) {
+      const next = text.charCodeAt(i + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) { bytes += 4; i++; } else bytes += 3;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+
+export function codePointLength(text: string): number {
+  let length = 0;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code >= 0xd800 && code <= 0xdbff && i + 1 < text.length) {
+      const next = text.charCodeAt(i + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) i++;
+    }
+    length++;
+  }
+  return length;
+}
+
+/**
+ * Checks that a value is plain JSON data within the nesting limit: finite
+ * numbers, plain objects/arrays, no undefined or functions.
+ */
+export function isJsonValue(value: unknown, depth = 1): value is Json {
+  if (depth > MAX_NESTING_DEPTH) return false;
+  if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every(item => isJsonValue(item, depth + 1));
+  if (isPlainObject(value)) return Object.values(value).every(item => isJsonValue(item, depth + 1));
+  return false;
+}
+
+/**
+ * Canonical JSON: sorted object keys, -0 normalized to 0, no whitespace.
+ * Throws on values that are not JSON data.
+ */
+export function canonicalJson(value: unknown): string {
+  return JSON.stringify(canonicalize(value, 1));
+}
+
+function canonicalize(value: unknown, depth: number): Json {
+  if (depth > MAX_NESTING_DEPTH) throw new TypeError("Value exceeds the maximum nesting depth");
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError("Non-finite numbers are not JSON data");
+    return Object.is(value, -0) ? 0 : value;
+  }
+  if (Array.isArray(value)) return value.map(item => canonicalize(item, depth + 1));
+  if (isPlainObject(value)) {
+    const sorted: { [key: string]: Json } = {};
+    for (const key of Object.keys(value).sort()) {
+      const item = value[key];
+      if (item === undefined) continue;
+      Object.defineProperty(sorted, key, { value: canonicalize(item, depth + 1), enumerable: true, writable: true, configurable: true });
+    }
+    return sorted;
+  }
+  throw new TypeError("Value is not JSON data");
+}
+
+/** Pretty canonical JSON (sorted keys, two-space indent, trailing newline) for files. */
+export function canonicalJsonPretty(value: unknown): string {
+  return `${JSON.stringify(JSON.parse(canonicalJson(value)) as Json, null, 2)}\n`;
+}

package/src/protocol.ts

@@ -0,0 +1,41 @@
+import type { Capabilities } from "./types.ts";
+
+export const PROTOCOL_VERSION = 1 as const;
+export const DEFAULT_SOCKET_PATH = "/streamotter/socket.io";
+export const DEFAULT_GATEWAY_PORT = 7400;
+export const DEFAULT_MANAGEMENT_PORT = 7401;
+
+export const CAPABILITIES: Capabilities = Object.freeze({
+  protocolVersion: PROTOCOL_VERSION,
+  configVersions: Object.freeze([1] as const),
+  transport: "socket.io",
+  deliveryModes: Object.freeze(["state"] as const),
+  operations: Object.freeze(["subscribe", "unsubscribe", "resync", "receipt"] as const)
+});
+
+export const EVENTS = Object.freeze({
+  hello: "so:hello",
+  state: "so:state",
+  data: "so:data",
+  error: "so:error",
+  subscribe: "so:subscribe",
+  unsubscribe: "so:unsubscribe",
+  resync: "so:resync",
+  receipt: "so:receipt"
+} as const);
+
+/** Protocol timings fixed by the V1 specification. */
+export const HELLO_TIMEOUT_MS = 10_000;
+export const CONTROL_CALLBACK_TIMEOUT_MS = 5_000;
+export const UNSUBSCRIBE_TIMEOUT_MS = 5_000;
+export const GET_TOKEN_TIMEOUT_MS = 10_000;
+export const DEFAULT_READY_TIMEOUT_MS = 30_000;
+export const TOKEN_REFRESH_LEAD_MS = 30_000;
+export const RECONNECT_BASE_MS = 500;
+export const RECONNECT_CAP_MS = 30_000;
+export const MAX_TOKEN_BYTES = 8_192;
+export const REQUEST_CACHE_ENTRIES = 256;
+export const REQUEST_CACHE_TTL_MS = 60_000;
+export const STARTUP_DEADLINE_MS = 30_000;
+export const DEFAULT_STOP_TIMEOUT_MS = 10_000;
+export const PREVIEW_TOKEN_TTL_MS = 5 * 60_000;