@spfn/core 0.3.0-beta.3 → 0.3.0-beta.31

package/dist/config/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/config/schema.ts","../../src/config/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Core Package Environment Variable Schema\n *\n * Centralized schema definition for all environment variables used in @spfn/core.\n * This provides type safety, validation, and documentation for environment configuration.\n *\n * @module config/schema\n */\n\nimport {\n    defineEnvSchema,\n    envEnum,\n    envNumber,\n    envBoolean,\n    envUrl,\n    envString,\n    parsePostgresUrl,\n    parseRedisUrl,\n} from '@spfn/core/env';\n\n/**\n * Core package environment variable schema\n *\n * Defines all environment variables with:\n * - Type information\n * - Default values\n * - Validation rules\n * - Documentation\n *\n * @example\n * ```typescript\n * import { coreEnvSchema } from '@spfn/core/config';\n *\n * // Access schema information\n * console.log(coreEnvSchema.DB_POOL_MAX.description);\n * console.log(coreEnvSchema.DB_POOL_MAX.default);\n * ```\n */\nexport const coreEnvSchema = defineEnvSchema({\n    // ========================================================================\n    // Core Environment\n    // ========================================================================\n\n    NODE_ENV: envEnum(['local', 'development', 'staging', 'production', 'test'] as const, {\n        description: 'Node.js runtime environment',\n        default: 'local',\n        nextjs: true,\n    }),\n\n    // ========================================================================\n    // Database - Connection\n    // ========================================================================\n\n    DATABASE_URL: envString({\n        description: 'Primary database connection URL',\n        required: false,\n        sensitive: true,\n        validator: parsePostgresUrl,\n        examples: ['postgresql://user:password@localhost:5432/dbname'],\n    }),\n\n    DATABASE_WRITE_URL: envString({\n        description: 'Write database URL (master-replica pattern)',\n        required: false,\n        sensitive: true,\n        validator: parsePostgresUrl,\n        examples: ['postgresql://user:password@master:5432/dbname'],\n    }),\n\n    DATABASE_READ_URL: envString({\n        description: 'Read database URL (master-replica pattern)',\n        required: false,\n        sensitive: true,\n        validator: parsePostgresUrl,\n        examples: ['postgresql://user:password@replica:5432/dbname'],\n    }),\n\n    // ========================================================================\n    // Database - Connection Pool\n    // ========================================================================\n\n    DB_POOL_MAX: envNumber({\n        description: 'Maximum number of database connections in pool',\n        default: 10,\n        examples: [10, 20, 50],\n    }),\n\n    DB_POOL_READ_MAX: envNumber({\n        description: 'Maximum connections for the read-replica pool. Defaults to DB_POOL_MAX. Set lower so write.max + read.max stays under the server max_connections (each process otherwise opens up to 2 × DB_POOL_MAX when a replica is configured).',\n        required: false,\n        examples: [5, 10, 20],\n    }),\n\n    DB_POOL_IDLE_TIMEOUT: envNumber({\n        description: 'Database connection idle timeout in seconds',\n        default: 30,\n        examples: [20, 30, 60],\n    }),\n\n    // ========================================================================\n    // Database - Retry Configuration\n    // ========================================================================\n\n    DB_RETRY_MAX: envNumber({\n        description: 'Maximum number of database connection retry attempts',\n        default: 3,\n        examples: [3, 5, 10],\n    }),\n\n    DB_RETRY_INITIAL_DELAY: envNumber({\n        description: 'Initial delay between database retry attempts (milliseconds)',\n        default: 100,\n        examples: [50, 100, 200],\n    }),\n\n    DB_RETRY_MAX_DELAY: envNumber({\n        description: 'Maximum delay cap for database retry attempts (milliseconds)',\n        default: 10000,\n        examples: [5000, 10000, 30000],\n    }),\n\n    DB_RETRY_FACTOR: envNumber({\n        description: 'Exponential backoff factor for database retry delays',\n        default: 2,\n        examples: [2, 1.5, 3],\n    }),\n\n    // ========================================================================\n    // Database - Health Check\n    // ========================================================================\n\n    DB_HEALTH_CHECK_ENABLED: envBoolean({\n        description: 'Enable periodic database health checks',\n        default: true,\n        examples: [true, false],\n    }),\n\n    DB_HEALTH_CHECK_INTERVAL: envNumber({\n        description: 'Database health check interval (milliseconds)',\n        default: 60000,\n        examples: [30000, 60000, 120000],\n    }),\n\n    DB_HEALTH_CHECK_RECONNECT: envBoolean({\n        description: 'Reconnect to database on health check failure',\n        default: true,\n        examples: [true, false],\n    }),\n\n    DB_HEALTH_CHECK_MAX_RETRIES: envNumber({\n        description: 'Maximum health check retry attempts before marking as failed',\n        default: 3,\n        examples: [3, 5, 10],\n    }),\n\n    DB_HEALTH_CHECK_RETRY_INTERVAL: envNumber({\n        description: 'Interval between health check retry attempts (milliseconds)',\n        default: 5000,\n        examples: [5000, 10000, 15000],\n    }),\n\n    // ========================================================================\n    // Database - Monitoring\n    // ========================================================================\n\n    DB_MONITORING_ENABLED: envBoolean({\n        description: 'Enable database query performance monitoring',\n        default: false,\n        examples: [true, false],\n    }),\n\n    DB_MONITORING_SLOW_THRESHOLD: envNumber({\n        description: 'Slow query threshold for monitoring (milliseconds)',\n        default: 1000,\n        examples: [500, 1000, 2000],\n    }),\n\n    DB_MONITORING_LOG_QUERIES: envBoolean({\n        description: 'Log all database queries (not just slow queries)',\n        default: false,\n        examples: [true, false],\n    }),\n\n    // ========================================================================\n    // Database - Transaction\n    // ========================================================================\n\n    TRANSACTION_TIMEOUT: envNumber({\n        description: 'Transaction timeout in milliseconds',\n        default: 30000,\n        examples: [10000, 30000, 60000],\n    }),\n\n    TRANSACTION_IDLE_TIMEOUT: envNumber({\n        description: 'Max time (ms) a transaction may sit idle (no running query) before Postgres terminates it and reclaims the pooled connection. Guards against external I/O held inside a transaction starving the connection pool. 0 disables.',\n        default: 30000,\n        examples: [10000, 30000, 0],\n    }),\n\n    // ========================================================================\n    // Jobs (pg-boss)\n    // ========================================================================\n\n    JOB_POLLING_INTERVAL_SECONDS: envNumber({\n        description: 'How often each pg-boss worker polls the DB for new jobs (seconds). Lower = faster pickup, more idle SELECT load; higher = less DB chatter, slower pickup. Per-job override via job options.',\n        default: 2,\n        examples: [1, 2, 10],\n    }),\n\n    // ========================================================================\n    // Database - Development\n    // ========================================================================\n\n    DB_DEBUG_TRACE: envBoolean({\n        description: 'Enable detailed debug tracing for database operations',\n        default: false,\n        examples: [true, false],\n    }),\n\n    // ========================================================================\n    // Database - Migrations\n    // ========================================================================\n\n    SPFN_ALLOW_PENDING_MIGRATIONS: envBoolean({\n        description: 'Start the server even when a function package or the project has migrations the database has not applied. Off by default: a server booted with pending migrations fails only at request time, as an opaque 500. The flag equivalent is `spfn dev --allow-pending-migrations`.',\n        default: false,\n        examples: [true, false],\n    }),\n\n    // ========================================================================\n    // Drizzle ORM\n    // ========================================================================\n\n    DRIZZLE_SCHEMA_PATH: envString({\n        description: 'Path to Drizzle schema configuration',\n        required: false,\n        default: './src/server/entities/config.ts',\n        examples: ['./src/db/schema.ts', './src/server/entities/config.ts'],\n    }),\n\n    DRIZZLE_OUT_DIR: envString({\n        description: 'Output directory for Drizzle migrations',\n        required: false,\n        default: './drizzle',\n        examples: ['./drizzle', './migrations'],\n    }),\n\n    // ========================================================================\n    // Logger - Core\n    // ========================================================================\n\n    SPFN_LOG_LEVEL: envEnum(['debug', 'info', 'warn', 'error', 'fatal'] as const, {\n        description: 'Minimum log level to output',\n        default: 'info',\n    }),\n\n    // ========================================================================\n    // Cache (Redis/Valkey)\n    // ========================================================================\n\n    CACHE_URL: envString({\n        description: 'Single Redis/Valkey instance URL',\n        required: false,\n        sensitive: true,\n        validator: parseRedisUrl,\n        examples: ['redis://localhost:6379', 'rediss://secure.cache.com:6380'],\n    }),\n\n    CACHE_WRITE_URL: envString({\n        description: 'Master Redis/Valkey URL for writes (master-replica pattern)',\n        required: false,\n        sensitive: true,\n        validator: parseRedisUrl,\n        examples: ['redis://master:6379'],\n    }),\n\n    CACHE_READ_URL: envString({\n        description: 'Replica Redis/Valkey URL for reads (master-replica pattern)',\n        required: false,\n        sensitive: true,\n        validator: parseRedisUrl,\n        examples: ['redis://replica:6379'],\n    }),\n\n    CACHE_SENTINEL_HOSTS: envString({\n        description: 'Comma-separated Redis Sentinel hosts',\n        required: false,\n        examples: ['sentinel1:26379,sentinel2:26379'],\n    }),\n\n    CACHE_CLUSTER_NODES: envString({\n        description: 'Comma-separated Redis Cluster nodes',\n        required: false,\n        examples: ['node1:6379,node2:6379,node3:6379'],\n    }),\n\n    CACHE_MASTER_NAME: envString({\n        description: 'Redis Sentinel master name',\n        required: false,\n        examples: ['mymaster'],\n    }),\n\n    CACHE_PASSWORD: envString({\n        description: 'Redis/Valkey authentication password',\n        required: false,\n        sensitive: true,\n        examples: ['your-redis-password'],\n    }),\n\n    CACHE_TLS_REJECT_UNAUTHORIZED: envBoolean({\n        description: 'Verify TLS certificates for secure Redis connections',\n        default: true,\n        examples: [true, false],\n    }),\n\n    CACHE_MAX_RETRIES_PER_REQUEST: envNumber({\n        description: 'Max ioredis retries per command before it rejects (fail fast instead of hanging on a cache outage). ioredis default is 20.',\n        default: 3,\n        examples: [1, 3, 20],\n    }),\n\n    CACHE_ENABLE_OFFLINE_QUEUE: envBoolean({\n        description: 'Queue commands while the cache is disconnected (true) vs reject immediately for strict fail-fast (false). Default true keeps resilience to brief blips.',\n        default: true,\n        examples: [true, false],\n    }),\n\n    // ========================================================================\n    // Database - Query limits\n    // ========================================================================\n\n    DB_MAX_ROWS: envNumber({\n        description: 'Safety ceiling for rows returned by repository findMany (0 = unlimited). When >0, an unbounded query is capped and an explicit limit is clamped, guarding against accidentally loading a whole large table.',\n        default: 0,\n        examples: [0, 1000, 10000],\n    }),\n\n    // ========================================================================\n    // Server - Core\n    // ========================================================================\n\n    // PORT and HOST are deliberately absent.\n    //\n    // They were declared here with defaults of 4000 and 'localhost', and a\n    // schema default is indistinguishable from a value someone set — so\n    // `env.PORT` was never undefined, and the resolution order had to consult\n    // the environment last to avoid it winning every time. That is what made an\n    // injected port unreachable. The server's address now resolves through\n    // `@spfn/core/app-config`: SPFN_PORT, then spfn.config.js, then the\n    // default, with the default existing in exactly one place.\n    //\n    // `PORT` is also Next.js's own variable, and two processes are started.\n\n    // ========================================================================\n    // Server - Timeout\n    // ========================================================================\n\n    SERVER_TIMEOUT: envNumber({\n        description: 'Request timeout in milliseconds',\n        default: 120000,\n        examples: [60000, 120000, 300000],\n    }),\n\n    SERVER_KEEPALIVE_TIMEOUT: envNumber({\n        description: 'Keep-alive timeout in milliseconds',\n        default: 65000,\n        examples: [30000, 65000, 120000],\n    }),\n\n    SERVER_HEADERS_TIMEOUT: envNumber({\n        description: 'Headers timeout in milliseconds',\n        default: 60000,\n        examples: [30000, 60000, 120000],\n    }),\n\n    SHUTDOWN_TIMEOUT: envNumber({\n        description: 'Graceful shutdown timeout in milliseconds (must be less than k8s terminationGracePeriodSeconds minus preStop sleep, with safety margin)',\n        default: 280000,\n        examples: [30000, 120000, 280000],\n    }),\n\n    // ========================================================================\n    // Fetch (Node.js undici) - outbound HTTP request timeout\n    // ========================================================================\n\n    FETCH_CONNECT_TIMEOUT: envNumber({\n        description: 'Fetch TCP connection timeout in milliseconds (time to establish socket connection to upstream server)',\n        default: 10000,\n        examples: [5000, 10000, 30000],\n    }),\n\n    FETCH_HEADERS_TIMEOUT: envNumber({\n        description: 'Fetch headers timeout in milliseconds (time to receive response headers after request sent)',\n        default: 300000,\n        examples: [120000, 300000, 600000],\n    }),\n\n    FETCH_BODY_TIMEOUT: envNumber({\n        description: 'Fetch body timeout in milliseconds (time between body data chunks from upstream server)',\n        default: 300000,\n        examples: [120000, 300000, 600000],\n    }),\n\n    // ========================================================================\n    // Next.js Integration\n    // ========================================================================\n\n    SPFN_API_URL: envUrl({\n        description: 'SPFN API URL (used by Next.js to call backend)',\n        required: true,\n        nextjs: true,\n        examples: ['http://localhost:8790', 'https://api.your-app.com'],\n    }),\n\n    NEXT_PUBLIC_SPFN_API_URL: envUrl({\n        description: 'SPFN API URL (used by Next.js to call backend)',\n        required: true,\n        nextjs: true,\n        examples: ['http://localhost:8790', 'https://api.your-app.com'],\n    }),\n\n    SPFN_APP_URL: envUrl({\n        description: 'Next.js application URL (used by SPFN server)',\n        required: false,\n        nextjs: true,\n        examples: ['http://localhost:3790', 'https://your-app.com'],\n    }),\n\n    RPC_PROXY_TIMEOUT: envNumber({\n        description: 'RPC proxy request timeout in milliseconds (AbortController timeout for proxied requests to backend, should be shorter than FETCH_HEADERS_TIMEOUT)',\n        default: 120000,\n        nextjs: true,\n        examples: [60000, 120000, 280000],\n    }),\n\n    // ========================================================================\n    // Proxy → Backend trust (HMAC signing)\n    // ========================================================================\n\n    SPFN_PROXY_SECRET: envString({\n        description: 'Shared secret for signing proxy→backend requests (HMAC-SHA256). Read by BOTH processes — the Next.js proxy (to sign) and the SPFN backend (to verify) — so it belongs in .env.local (loaded by both; the backend reads it via loadEnv, Next.js reads it server-side without exposing it to the browser). Set the SAME value on both. Leave unset to disable proxy-guard signing.',\n        required: false,\n        sensitive: true,\n        nextjs: true,\n        examples: ['<32+ byte random hex>', 'v2:<32+ byte random hex>'],\n    }),\n\n    SPFN_PROXY_SECRET_PREVIOUS: envString({\n        description: 'Previous (grace) proxy keys still accepted for verification during rotation — comma-separated <keyId>:<secret>. The proxy never signs with these; they only keep requests signed with the prior key verifying until a rollout settles. Backend-only (verification), so it belongs in .env.server, NOT exposed to the Next.js process.',\n        required: false,\n        sensitive: true,\n        nextjs: false,\n        examples: ['v1:<old secret>', 'v1:<old>,v0:<older>'],\n    }),\n\n    TRUSTED_PROXY_HOPS: envNumber({\n        description: 'Number of trusted reverse proxies in front of the Next.js proxy (e.g. cloud LB + nginx = 2). Read by the proxy to extract the real client IP from the inbound X-Forwarded-For (counting from the right, which your own infra appends and a client cannot spoof) and forward it to the backend for rate limiting. Set it to your actual hop count; too low trusts a client-spoofable entry, too high collapses users behind a shared proxy IP.',\n        default: 1,\n        nextjs: true,\n        examples: [1, 2, 3],\n    }),\n\n    // ========================================================================\n    // Rate limiting (global default limiter)\n    // ========================================================================\n\n    RATE_LIMIT_MODE: envEnum(['off', 'on'] as const, {\n        description: 'Global default rate limiter. \"off\": only routes tagged with rateLimitPolicy() are limited. \"on\": every named-middleware route gets the default limit too (opt out per route with .skip([\\'rateLimit\\'])). Health/SSE/WebSocket endpoints are always exempt. Overridden by defineServerConfig().rateLimit({ mode }).',\n        default: 'off',\n    }),\n\n    RATE_LIMIT_DEFAULT_LIMIT: envNumber({\n        description: 'Max requests per window for the global default limiter (RATE_LIMIT_MODE=on), counted per route and per client IP.',\n        default: 100,\n        examples: [60, 100, 300],\n    }),\n\n    RATE_LIMIT_DEFAULT_WINDOW_MS: envNumber({\n        description: 'Window length in milliseconds for the global default limiter.',\n        default: 60000,\n        examples: [1000, 60000],\n    }),\n\n    RATE_LIMIT_FAIL_CLOSED: envBoolean({\n        description: 'When the cache (Redis/Valkey) backing the limiter is unavailable, reject with 429 instead of counting in-process. Default false: the limiter falls back to per-process counters, so limits still apply — but the effective limit multiplies by the instance count, since each process counts alone. Set true only where a shared count is required and refusing traffic is preferable to a looser one.',\n        default: false,\n    }),\n\n    // ========================================================================\n    // Outbound request safety (SSRF)\n    // ========================================================================\n\n    SAFE_FETCH_BLOCK_PRIVATE_IPS: envBoolean({\n        description: 'Default for safeFetch (@spfn/core/security): block outbound requests that resolve to private/reserved IP ranges, including the cloud metadata address. Keep true in production; set false only for trusted internal-network calls in development. Overridden by defineServerConfig().outboundFetch({ blockPrivateIps }).',\n        default: true,\n    }),\n});\n","/**\n * Core Package Configuration\n *\n * @example\n * ```typescript\n * import { registry } from '@spfn/core/config';\n *\n * const env = registry.validate();\n * console.log(env.DB_POOL_MAX);\n * ```\n *\n * @module config\n */\n\nimport { createEnvRegistry } from '@spfn/core/env';\nimport { coreEnvSchema } from './schema';\n\n/**\n * Core environment schema\n */\nexport { coreEnvSchema as envSchema } from './schema';\n\n/**\n * Environment registry\n *\n * @example\n * ```typescript\n * // Reset for testing\n * registry.reset();\n * ```\n */\nexport const registry = createEnvRegistry(coreEnvSchema);\n\n/**\n * Validated environment configuration\n */\nexport const env = registry.validate();\n"]}
+{"version":3,"sources":["../../src/config/schema.ts","../../src/config/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Core Package Environment Variable Schema\n *\n * Centralized schema definition for all environment variables used in @spfn/core.\n * This provides type safety, validation, and documentation for environment configuration.\n *\n * @module config/schema\n */\n\nimport {\n    defineEnvSchema,\n    envEnum,\n    envNumber,\n    envBoolean,\n    envUrl,\n    envString,\n    parsePostgresUrl,\n    parseRedisUrl,\n} from '@spfn/core/env';\n\n/**\n * Core package environment variable schema\n *\n * Defines all environment variables with:\n * - Type information\n * - Default values\n * - Validation rules\n * - Documentation\n *\n * @example\n * ```typescript\n * import { coreEnvSchema } from '@spfn/core/config';\n *\n * // Access schema information\n * console.log(coreEnvSchema.DB_POOL_MAX.description);\n * console.log(coreEnvSchema.DB_POOL_MAX.default);\n * ```\n */\nexport const coreEnvSchema = defineEnvSchema({\n    // ========================================================================\n    // Core Environment\n    // ========================================================================\n\n    NODE_ENV: envEnum(['local', 'development', 'staging', 'production', 'test'] as const, {\n        description: 'Node.js runtime environment',\n        default: 'local',\n        nextjs: true,\n    }),\n\n    // ========================================================================\n    // Database - Connection\n    // ========================================================================\n\n    DATABASE_URL: envString({\n        description: 'Primary database connection URL',\n        required: false,\n        sensitive: true,\n        validator: parsePostgresUrl,\n        examples: ['postgresql://user:password@localhost:5432/dbname'],\n    }),\n\n    DATABASE_WRITE_URL: envString({\n        description: 'Write database URL (master-replica pattern)',\n        required: false,\n        sensitive: true,\n        validator: parsePostgresUrl,\n        examples: ['postgresql://user:password@master:5432/dbname'],\n    }),\n\n    DATABASE_READ_URL: envString({\n        description: 'Read database URL (master-replica pattern)',\n        required: false,\n        sensitive: true,\n        validator: parsePostgresUrl,\n        examples: ['postgresql://user:password@replica:5432/dbname'],\n    }),\n\n    // ========================================================================\n    // Database - Connection Pool\n    // ========================================================================\n\n    DB_POOL_MAX: envNumber({\n        description: 'Maximum number of database connections in pool',\n        default: 10,\n        examples: [10, 20, 50],\n    }),\n\n    DB_POOL_READ_MAX: envNumber({\n        description: 'Maximum connections for the read-replica pool. Defaults to DB_POOL_MAX. Set lower so write.max + read.max stays under the server max_connections (each process otherwise opens up to 2 × DB_POOL_MAX when a replica is configured).',\n        required: false,\n        examples: [5, 10, 20],\n    }),\n\n    DB_POOL_IDLE_TIMEOUT: envNumber({\n        description: 'Database connection idle timeout in seconds',\n        default: 30,\n        examples: [20, 30, 60],\n    }),\n\n    // ========================================================================\n    // Database - Retry Configuration\n    // ========================================================================\n\n    DB_RETRY_MAX: envNumber({\n        description: 'Maximum number of database connection retry attempts',\n        default: 3,\n        examples: [3, 5, 10],\n    }),\n\n    DB_RETRY_INITIAL_DELAY: envNumber({\n        description: 'Initial delay between database retry attempts (milliseconds)',\n        default: 100,\n        examples: [50, 100, 200],\n    }),\n\n    DB_RETRY_MAX_DELAY: envNumber({\n        description: 'Maximum delay cap for database retry attempts (milliseconds)',\n        default: 10000,\n        examples: [5000, 10000, 30000],\n    }),\n\n    DB_RETRY_FACTOR: envNumber({\n        description: 'Exponential backoff factor for database retry delays',\n        default: 2,\n        examples: [2, 1.5, 3],\n    }),\n\n    // ========================================================================\n    // Database - Health Check\n    // ========================================================================\n\n    DB_HEALTH_CHECK_ENABLED: envBoolean({\n        description: 'Enable periodic database health checks',\n        default: true,\n        examples: [true, false],\n    }),\n\n    DB_HEALTH_CHECK_INTERVAL: envNumber({\n        description: 'Database health check interval (milliseconds)',\n        default: 60000,\n        examples: [30000, 60000, 120000],\n    }),\n\n    DB_HEALTH_CHECK_RECONNECT: envBoolean({\n        description: 'Reconnect to database on health check failure',\n        default: true,\n        examples: [true, false],\n    }),\n\n    DB_HEALTH_CHECK_MAX_RETRIES: envNumber({\n        description: 'Maximum health check retry attempts before marking as failed',\n        default: 3,\n        examples: [3, 5, 10],\n    }),\n\n    DB_HEALTH_CHECK_RETRY_INTERVAL: envNumber({\n        description: 'Interval between health check retry attempts (milliseconds)',\n        default: 5000,\n        examples: [5000, 10000, 15000],\n    }),\n\n    // ========================================================================\n    // Database - Monitoring\n    // ========================================================================\n\n    DB_MONITORING_ENABLED: envBoolean({\n        description: 'Enable database query performance monitoring',\n        default: false,\n        examples: [true, false],\n    }),\n\n    DB_MONITORING_SLOW_THRESHOLD: envNumber({\n        description: 'Slow query threshold for monitoring (milliseconds)',\n        default: 1000,\n        examples: [500, 1000, 2000],\n    }),\n\n    DB_MONITORING_LOG_QUERIES: envBoolean({\n        description: 'Log all database queries (not just slow queries)',\n        default: false,\n        examples: [true, false],\n    }),\n\n    // ========================================================================\n    // Database - Transaction\n    // ========================================================================\n\n    TRANSACTION_TIMEOUT: envNumber({\n        description: 'Transaction timeout in milliseconds',\n        default: 30000,\n        examples: [10000, 30000, 60000],\n    }),\n\n    TRANSACTION_IDLE_TIMEOUT: envNumber({\n        description: 'Max time (ms) a transaction may sit idle (no running query) before Postgres terminates it and reclaims the pooled connection. Guards against external I/O held inside a transaction starving the connection pool. 0 disables.',\n        default: 30000,\n        examples: [10000, 30000, 0],\n    }),\n\n    // ========================================================================\n    // Jobs (pg-boss)\n    // ========================================================================\n\n    JOB_POLLING_INTERVAL_SECONDS: envNumber({\n        description: 'How often each pg-boss worker polls the DB for new jobs (seconds). Lower = faster pickup, more idle SELECT load; higher = less DB chatter, slower pickup. Per-job override via job options.',\n        default: 2,\n        examples: [1, 2, 10],\n    }),\n\n    // ========================================================================\n    // Database - Development\n    // ========================================================================\n\n    DB_DEBUG_TRACE: envBoolean({\n        description: 'Enable detailed debug tracing for database operations',\n        default: false,\n        examples: [true, false],\n    }),\n\n    // ========================================================================\n    // Database - Migrations\n    // ========================================================================\n\n    SPFN_ALLOW_PENDING_MIGRATIONS: envBoolean({\n        description: 'Start the server even when a function package or the project has migrations the database has not applied. Off by default: a server booted with pending migrations fails only at request time, as an opaque 500. The flag equivalent is `spfn dev --allow-pending-migrations`.',\n        default: false,\n        examples: [true, false],\n    }),\n\n    // ========================================================================\n    // Drizzle ORM\n    // ========================================================================\n\n    DRIZZLE_SCHEMA_PATH: envString({\n        description: 'Entity registry file spfn db push/generate/studio load when src/server/entities/ holds no entity file, or when the registry exports a table no file there defines',\n        required: false,\n        default: './src/server/entities/config.ts',\n        examples: ['./src/db/schema.ts', './src/server/entities/config.ts'],\n    }),\n\n    DRIZZLE_OUT_DIR: envString({\n        description: 'Output directory for Drizzle migrations',\n        required: false,\n        default: './drizzle',\n        examples: ['./drizzle', './migrations'],\n    }),\n\n    // ========================================================================\n    // Logger - Core\n    // ========================================================================\n\n    SPFN_LOG_LEVEL: envEnum(['debug', 'info', 'warn', 'error', 'fatal'] as const, {\n        description: 'Minimum log level to output',\n        default: 'info',\n    }),\n\n    // ========================================================================\n    // Cache (Redis/Valkey)\n    // ========================================================================\n\n    CACHE_URL: envString({\n        description: 'Single Redis/Valkey instance URL',\n        required: false,\n        sensitive: true,\n        validator: parseRedisUrl,\n        examples: ['redis://localhost:6379', 'rediss://secure.cache.com:6380'],\n    }),\n\n    CACHE_WRITE_URL: envString({\n        description: 'Master Redis/Valkey URL for writes (master-replica pattern)',\n        required: false,\n        sensitive: true,\n        validator: parseRedisUrl,\n        examples: ['redis://master:6379'],\n    }),\n\n    CACHE_READ_URL: envString({\n        description: 'Replica Redis/Valkey URL for reads (master-replica pattern)',\n        required: false,\n        sensitive: true,\n        validator: parseRedisUrl,\n        examples: ['redis://replica:6379'],\n    }),\n\n    CACHE_SENTINEL_HOSTS: envString({\n        description: 'Comma-separated Redis Sentinel hosts',\n        required: false,\n        examples: ['sentinel1:26379,sentinel2:26379'],\n    }),\n\n    CACHE_CLUSTER_NODES: envString({\n        description: 'Comma-separated Redis Cluster nodes',\n        required: false,\n        examples: ['node1:6379,node2:6379,node3:6379'],\n    }),\n\n    CACHE_MASTER_NAME: envString({\n        description: 'Redis Sentinel master name',\n        required: false,\n        examples: ['mymaster'],\n    }),\n\n    CACHE_PASSWORD: envString({\n        description: 'Redis/Valkey authentication password',\n        required: false,\n        sensitive: true,\n        examples: ['your-redis-password'],\n    }),\n\n    CACHE_TLS_REJECT_UNAUTHORIZED: envBoolean({\n        description: 'Verify TLS certificates for secure Redis connections',\n        default: true,\n        examples: [true, false],\n    }),\n\n    CACHE_MAX_RETRIES_PER_REQUEST: envNumber({\n        description: 'Max ioredis retries per command before it rejects (fail fast instead of hanging on a cache outage). ioredis default is 20.',\n        default: 3,\n        examples: [1, 3, 20],\n    }),\n\n    CACHE_ENABLE_OFFLINE_QUEUE: envBoolean({\n        description: 'Queue commands while the cache is disconnected (true) vs reject immediately for strict fail-fast (false). Default true keeps resilience to brief blips.',\n        default: true,\n        examples: [true, false],\n    }),\n\n    // ========================================================================\n    // Database - Query limits\n    // ========================================================================\n\n    DB_MAX_ROWS: envNumber({\n        description: 'Safety ceiling for rows returned by repository findMany (0 = unlimited). When >0, an unbounded query is capped and an explicit limit is clamped, guarding against accidentally loading a whole large table.',\n        default: 0,\n        examples: [0, 1000, 10000],\n    }),\n\n    // ========================================================================\n    // Server - Core\n    // ========================================================================\n\n    // PORT and HOST are deliberately absent.\n    //\n    // They were declared here with defaults of 4000 and 'localhost', and a\n    // schema default is indistinguishable from a value someone set — so\n    // `env.PORT` was never undefined, and the resolution order had to consult\n    // the environment last to avoid it winning every time. That is what made an\n    // injected port unreachable. The server's address now resolves through\n    // `@spfn/core/app-config`: SPFN_PORT, then spfn.config.js, then the\n    // default, with the default existing in exactly one place.\n    //\n    // `PORT` is also Next.js's own variable, and two processes are started.\n\n    // ========================================================================\n    // Server - Timeout\n    // ========================================================================\n\n    SERVER_TIMEOUT: envNumber({\n        description: 'Request timeout in milliseconds',\n        default: 120000,\n        examples: [60000, 120000, 300000],\n    }),\n\n    SERVER_KEEPALIVE_TIMEOUT: envNumber({\n        description: 'Keep-alive timeout in milliseconds',\n        default: 65000,\n        examples: [30000, 65000, 120000],\n    }),\n\n    SERVER_HEADERS_TIMEOUT: envNumber({\n        description: 'Headers timeout in milliseconds',\n        default: 60000,\n        examples: [30000, 60000, 120000],\n    }),\n\n    SHUTDOWN_TIMEOUT: envNumber({\n        description: 'Graceful shutdown timeout in milliseconds (must be less than k8s terminationGracePeriodSeconds minus preStop sleep, with safety margin)',\n        default: 280000,\n        examples: [30000, 120000, 280000],\n    }),\n\n    // ========================================================================\n    // Fetch (Node.js undici) - outbound HTTP request timeout\n    // ========================================================================\n\n    FETCH_CONNECT_TIMEOUT: envNumber({\n        description: 'Fetch TCP connection timeout in milliseconds (time to establish socket connection to upstream server)',\n        default: 10000,\n        examples: [5000, 10000, 30000],\n    }),\n\n    FETCH_HEADERS_TIMEOUT: envNumber({\n        description: 'Fetch headers timeout in milliseconds (time to receive response headers after request sent)',\n        default: 300000,\n        examples: [120000, 300000, 600000],\n    }),\n\n    FETCH_BODY_TIMEOUT: envNumber({\n        description: 'Fetch body timeout in milliseconds (time between body data chunks from upstream server)',\n        default: 300000,\n        examples: [120000, 300000, 600000],\n    }),\n\n    // ========================================================================\n    // Next.js Integration\n    // ========================================================================\n\n    SPFN_API_URL: envUrl({\n        description: 'SPFN API URL. Next.js calls the backend on it, and the server reads it wherever it names its own origin (e.g. an OAuth 2.1 issuer, links it sends out).',\n        required: true,\n        nextjs: true,\n        examples: ['http://localhost:8790', 'https://api.your-app.com'],\n    }),\n\n    NEXT_PUBLIC_SPFN_API_URL: envUrl({\n        description: 'SPFN API URL for browser code. Next.js inlines it into the client bundle at build time; the server does not read it and falls back to SPFN_API_URL, so it is optional here.',\n        required: false,\n        nextjs: true,\n        examples: ['http://localhost:8790', 'https://api.your-app.com'],\n    }),\n\n    SPFN_APP_URL: envUrl({\n        description: 'Next.js application URL (used by SPFN server)',\n        required: false,\n        nextjs: true,\n        examples: ['http://localhost:3790', 'https://your-app.com'],\n    }),\n\n    RPC_PROXY_TIMEOUT: envNumber({\n        description: 'RPC proxy request timeout in milliseconds (AbortController timeout for proxied requests to backend, should be shorter than FETCH_HEADERS_TIMEOUT)',\n        default: 120000,\n        nextjs: true,\n        examples: [60000, 120000, 280000],\n    }),\n\n    // ========================================================================\n    // Proxy → Backend trust (HMAC signing)\n    // ========================================================================\n\n    SPFN_PROXY_SECRET: envString({\n        description: 'Shared secret for signing proxy→backend requests (HMAC-SHA256). Read by BOTH processes — the Next.js proxy (to sign) and the SPFN backend (to verify) — so it belongs in .env.local (loaded by both; the backend reads it via loadEnv, Next.js reads it server-side without exposing it to the browser). Set the SAME value on both. Leave unset to disable proxy-guard signing.',\n        required: false,\n        sensitive: true,\n        nextjs: true,\n        examples: ['<32+ byte random hex>', 'v2:<32+ byte random hex>'],\n    }),\n\n    SPFN_PROXY_SECRET_PREVIOUS: envString({\n        description: 'Previous (grace) proxy keys still accepted for verification during rotation — comma-separated <keyId>:<secret>. The proxy never signs with these; they only keep requests signed with the prior key verifying until a rollout settles. Backend-only (verification), so it belongs in .env.server, NOT exposed to the Next.js process.',\n        required: false,\n        sensitive: true,\n        nextjs: false,\n        examples: ['v1:<old secret>', 'v1:<old>,v0:<older>'],\n    }),\n\n    TRUSTED_PROXY_HOPS: envNumber({\n        description: 'Number of trusted reverse proxies in front of the Next.js proxy (e.g. cloud LB + nginx = 2). Read by the proxy to extract the real client IP from the inbound X-Forwarded-For (counting from the right, which your own infra appends and a client cannot spoof) and forward it to the backend for rate limiting. Set it to your actual hop count; too low trusts a client-spoofable entry, too high collapses users behind a shared proxy IP.',\n        default: 1,\n        nextjs: true,\n        examples: [1, 2, 3],\n    }),\n\n    // ========================================================================\n    // Rate limiting (global default limiter)\n    // ========================================================================\n\n    RATE_LIMIT_MODE: envEnum(['off', 'on'] as const, {\n        description: 'Global default rate limiter. \"off\": only routes tagged with rateLimitPolicy() are limited. \"on\": every named-middleware route gets the default limit too (opt out per route with .skip([\\'rateLimit\\'])). Health/SSE/WebSocket endpoints are always exempt. Overridden by defineServerConfig().rateLimit({ mode }).',\n        default: 'off',\n    }),\n\n    RATE_LIMIT_DEFAULT_LIMIT: envNumber({\n        description: 'Max requests per window for the global default limiter (RATE_LIMIT_MODE=on), counted per route and per client IP.',\n        default: 100,\n        examples: [60, 100, 300],\n    }),\n\n    RATE_LIMIT_DEFAULT_WINDOW_MS: envNumber({\n        description: 'Window length in milliseconds for the global default limiter.',\n        default: 60000,\n        examples: [1000, 60000],\n    }),\n\n    RATE_LIMIT_FAIL_CLOSED: envBoolean({\n        description: 'When the cache (Redis/Valkey) backing the limiter is unavailable, reject with 429 instead of counting in-process. Default false: the limiter falls back to per-process counters, so limits still apply — but the effective limit multiplies by the instance count, since each process counts alone. Set true only where a shared count is required and refusing traffic is preferable to a looser one.',\n        default: false,\n    }),\n\n    // ========================================================================\n    // Outbound request safety (SSRF)\n    // ========================================================================\n\n    SAFE_FETCH_BLOCK_PRIVATE_IPS: envBoolean({\n        description: 'Default for safeFetch (@spfn/core/security): block outbound requests that resolve to private/reserved IP ranges, including the cloud metadata address. Keep true in production; set false only for trusted internal-network calls in development. Overridden by defineServerConfig().outboundFetch({ blockPrivateIps }).',\n        default: true,\n    }),\n});\n","/**\n * Core Package Configuration\n *\n * @example\n * ```typescript\n * import { registry } from '@spfn/core/config';\n *\n * const env = registry.validate();\n * console.log(env.DB_POOL_MAX);\n * ```\n *\n * @module config\n */\n\nimport { createEnvRegistry } from '@spfn/core/env';\nimport { coreEnvSchema } from './schema';\n\n/**\n * Core environment schema\n */\nexport { coreEnvSchema as envSchema } from './schema';\n\n/**\n * Environment registry\n *\n * @example\n * ```typescript\n * // Reset for testing\n * registry.reset();\n * ```\n */\nexport const registry = createEnvRegistry(coreEnvSchema);\n\n/**\n * Validated environment configuration\n */\nexport const env = registry.validate();\n"]}

package/dist/contract/index.d.ts

@@ -1,9 +1,11 @@
-import { R as Router } from '../router-Cy7rAfmj.js';
-import { C as ContractDocument, a as ContractViolation, b as ContractOperation, c as ContractSnapshot } from '../types-CfYVhIQ9.js';
-export { d as CompatibilityPolicy, e as ContractRequest, f as ContractViolationKind, J as JsonSchema } from '../types-CfYVhIQ9.js';
+import { E as EventRouterDef } from '../router-CX5uVjmU.js';
+import { R as Router } from '../router-C57y-vz1.js';
+import { C as ContractDocument, a as ContractViolation, b as ContractOperation, c as ContractSnapshot } from '../types-5Rl11_Nb.js';
+export { d as CompatibilityPolicy, e as ContractEvent, f as ContractEvents, g as ContractRequest, h as ContractViolationKind, J as JsonSchema } from '../types-5Rl11_Nb.js';
+import '@sinclair/typebox';
 import '../define-middleware-CVKgqo8S.js';
 import 'hono';
-import '@sinclair/typebox';
+import '../route-builder-DRW-MSCJ.js';
 import 'hono/utils/http-status';
 import '../route/types.js';
 
@@ -11,7 +13,8 @@ import '../route/types.js';
  * Contract Collection
  *
  * Walks a loaded router and turns every route carrying `.contract()` into a
- * contract operation.
+ * contract operation, and every event of an event router carrying
+ * `.contract()` into a contract event.
  *
  * The router is loaded and walked rather than parsed from source. Real routes
  * build their schemas from imported values — `EmailSchema`, `FileSchema()`,
@@ -25,11 +28,14 @@ declare class ContractCollectionError extends Error {
     constructor(message: string);
 }
 /**
- * Build the contract document from a loaded router.
+ * Build the contract document from a loaded router and, optionally, the app's
+ * event router.
  *
- * Routes without `.contract()` are skipped — they are not part of the promise.
+ * Routes and events without `.contract()` are skipped — they are not part of
+ * the promise. A document with no contracted event carries no `events` key, so
+ * it is byte-identical to one collected without an event router.
  */
-declare function collectContractDocument(router: Router<any>): ContractDocument;
+declare function collectContractDocument(router: Router<any>, eventRouter?: EventRouterDef<any>): ContractDocument;
 
 /**
  * Backward-compatibility comparison
@@ -51,6 +57,10 @@ declare function collectContractDocument(router: Router<any>): ContractDocument;
  * | required → optional     | pass    | refuse   |
  * | optional → required     | refuse  | pass     |
  * | type changed            | refuse  | refuse   |
+ *
+ * An event payload flows server → client like a response, so it is compared
+ * under the response rules by the same walk, and only the violation kinds are
+ * renamed.
  */
 
 interface DocumentComparison {
@@ -62,14 +72,19 @@ interface DocumentComparison {
      * whether any released app still calls it, which is a separate check.
      */
     removedOperations: string[];
+    /**
+     * Events present in the baseline and gone from the current contract —
+     * decided against usage files exactly as a removed operation is.
+     */
+    removedEvents: string[];
 }
 /** Compare one operation that exists on both sides. */
 declare function compareOperation(before: ContractOperation, after: ContractOperation): ContractViolation[];
 /**
  * Compare a released contract against the one this build produced.
  *
- * Operations that are new in `after` need no check — nothing has been promised
- * about them yet.
+ * Operations and events that are new in `after` need no check — nothing has
+ * been promised about them yet.
  */
 declare function compareDocuments(before: ContractDocument, after: ContractDocument): DocumentComparison;
 
@@ -78,7 +93,7 @@ declare function compareDocuments(before: ContractDocument, after: ContractDocum
  *
  * Puts the pieces together: read the newest released snapshot, compare this
  * build's contract against it, and decide removals against what released
- * clients still call.
+ * clients still call or subscribe to.
  *
  * Nothing released yet is a pass — with a warning. "This is the first contract"
  * and "the release that should have written a snapshot didn't" produce the same
@@ -180,12 +195,12 @@ declare function readCurrentDocument(contractsDir: string): ContractDocument;
 declare function writeCurrentDocument(contractsDir: string, document: ContractDocument): boolean;
 
 /**
- * Usage files — who still calls an operation
+ * Usage files — who still calls an operation or subscribes to an event
  *
  * A released app is compiled and shipped; the server cannot ask it what it
- * calls. So each released client writes down the operations it uses, and those
- * files are what a removal is judged against:
- * `contracts/usage/<platform>-<appVersion>.json`.
+ * calls. So each released client writes down the operations it uses and the
+ * events it subscribes to, and those files are what a removal is judged
+ * against: `contracts/usage/<platform>-<appVersion>.json`.
  *
  * The one rule this file exists to hold: **an unreadable file and "nobody calls
  * it" are not the same answer.** An empty scan result reading as a pass is how
@@ -197,6 +212,12 @@ interface UsageRecord {
     platform: string;
     appVersion: string;
     operations: string[];
+    /**
+     * Contracted events the client subscribes to. Always set when read from a
+     * file — a file without the key subscribes to none — and optional only so a
+     * record built by hand before events were contracted still type-checks.
+     */
+    events?: string[];
     /** File this came from, for messages. */
     file: string;
 }
@@ -216,5 +237,7 @@ type UsageReadResult = {
 declare function readUsageRecords(usageDir: string): UsageReadResult;
 /** Which released clients still call `operation`. */
 declare function callersOf(operation: string, records: UsageRecord[]): UsageRecord[];
+/** Which released clients still subscribe to `event`. */
+declare function subscribersOf(event: string, records: UsageRecord[]): UsageRecord[];
 
-export { CURRENT_FILENAME, type ContractCheckResult, ContractCollectionError, ContractDocument, ContractOperation, ContractSnapshot, ContractSnapshotError, ContractViolation, type DocumentComparison, RELEASED_DIRNAME, type SnapshotFile, USAGE_DIRNAME, type UsageReadResult, type UsageRecord, callersOf, canonicalize, checkContract, collectContractDocument, compareDocuments, compareOperation, compareVersions, currentPath, formatViolations, listSnapshots, newestSnapshot, readCurrentDocument, readSnapshot, readUsageRecords, releasedDir, stableDigest, stableStringify, stableStringifyPretty, usageDir, writeCurrentDocument, writeSnapshot };
+export { CURRENT_FILENAME, type ContractCheckResult, ContractCollectionError, ContractDocument, ContractOperation, ContractSnapshot, ContractSnapshotError, ContractViolation, type DocumentComparison, RELEASED_DIRNAME, type SnapshotFile, USAGE_DIRNAME, type UsageReadResult, type UsageRecord, callersOf, canonicalize, checkContract, collectContractDocument, compareDocuments, compareOperation, compareVersions, currentPath, formatViolations, listSnapshots, newestSnapshot, readCurrentDocument, readSnapshot, readUsageRecords, releasedDir, stableDigest, stableStringify, stableStringifyPretty, subscribersOf, usageDir, writeCurrentDocument, writeSnapshot };

package/dist/contract/index.js

@@ -2,6 +2,12 @@ import { createHash } from 'crypto';
 import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, statSync } from 'fs';
 import { join } from 'path';
 
+// src/event/sse/paths.ts
+var DEFAULT_SSE_STREAM_PATH = "/events/stream";
+function sseTokenPath(streamPath) {
+  return streamPath.replace(/\/[^/]+$/, "/token");
+}
+
 // src/contract/collect.ts
 var ContractCollectionError = class extends Error {
   constructor(message) {
@@ -104,15 +110,65 @@ function addOperation(name, routeDef, trail, found) {
     }
   });
 }
-function collectContractDocument(router) {
+var RESERVED_EVENT_NAMES = /* @__PURE__ */ new Set(["connected", "ping", "subscription.granted", "subscription.revoked"]);
+function byName(a, b) {
+  return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}
+function toContractEvent(name, eventDef) {
+  const contract = eventDef._contract;
+  if (RESERVED_EVENT_NAMES.has(name)) {
+    throw new ContractCollectionError(
+      `Contracted event "${name}" uses a reserved frame name. The stream itself sends "connected", "ping", "subscription.granted" and "subscription.revoked" frames, so a client could not tell this event from them. Register the event under another key.`
+    );
+  }
+  if (!contract.since) {
+    throw new ContractCollectionError(
+      `Contracted event "${name}" has no "since" version. The version an event first appeared in is part of the promise.`
+    );
+  }
+  if (!eventDef.schema) {
+    throw new ContractCollectionError(
+      `Contracted event "${name}" declares no payload schema. Its frame carries no data, so there is nothing for the contract to describe. Declare Type.Object({}) and emit {} instead.`
+    );
+  }
+  return {
+    name,
+    since: contract.since,
+    ...contract.deprecatedIn ? { deprecatedIn: contract.deprecatedIn } : {},
+    ...contract.removedIn ? { removedIn: contract.removedIn } : {},
+    payload: toJsonSchema(eventDef.schema)
+  };
+}
+function collectEvents(eventRouter) {
+  const contracted = Object.entries(eventRouter?.events ?? {}).filter(([, eventDef]) => eventDef._contract);
+  if (contracted.length === 0) {
+    return void 0;
+  }
+  const routerContract = eventRouter._contract;
+  if (!routerContract) {
+    throw new ContractCollectionError(
+      `Event router defineEventRouter({ ${eventRouter.eventNames.join(", ")} }) contracts events but declares no .contract() of its own. Without it the contract cannot say whether a client must exchange a token before opening the stream. Add .contract({ auth: 'none' }) or .contract({ auth: 'tokenExchange' }) to the router.`
+    );
+  }
+  const streamPath = routerContract.streamPath ?? DEFAULT_SSE_STREAM_PATH;
+  return {
+    streamPath,
+    tokenPath: sseTokenPath(streamPath),
+    auth: routerContract.auth,
+    items: contracted.map(([name, eventDef]) => toContractEvent(name, eventDef)).sort(byName)
+  };
+}
+function collectContractDocument(router, eventRouter) {
   const found = /* @__PURE__ */ new Map();
   visitRouter(router, ["router"], found);
-  const operations = [...found.values()].map((entry) => entry.operation).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+  const operations = [...found.values()].map((entry) => entry.operation).sort(byName);
+  const events = collectEvents(eventRouter);
   return {
     documentVersion: 1,
     ...router._contractVersion ? { contractVersion: router._contractVersion } : {},
     compatibilityPolicy: "perOperation",
-    operations
+    operations,
+    ...events ? { events } : {}
   };
 }
 function canonicalize(value) {
@@ -279,6 +335,52 @@ function compareOperation(before, after) {
   );
   return violations;
 }
+var PAYLOAD_KINDS = {
+  "response.field-removed": "event.payload.field-removed",
+  "response.field-became-optional": "event.payload.field-became-optional",
+  "response.type-changed": "event.payload.type-changed"
+};
+function compareEvent(before, after) {
+  const found = [];
+  compareSchema(before.payload, after.payload, "payload", { operation: before.name, side: "response", violations: found });
+  return found.map(({ kind, operation, ...rest }) => ({ ...rest, kind: PAYLOAD_KINDS[kind] ?? kind, event: operation }));
+}
+function compareStream(before, after) {
+  const violations = [];
+  if (before.streamPath !== after.streamPath) {
+    violations.push({
+      kind: "events.stream-path-changed",
+      detail: `stream path moved ${before.streamPath} \u2192 ${after.streamPath}; released clients open the old one`
+    });
+  }
+  if (before.auth !== after.auth) {
+    violations.push({
+      kind: "events.auth-changed",
+      detail: `stream auth changed ${before.auth} \u2192 ${after.auth}; released clients connect the old way`
+    });
+  }
+  return violations;
+}
+function compareEvents(before, after) {
+  if (!before) {
+    return { violations: [], removedEvents: [] };
+  }
+  if (!after) {
+    return { violations: [], removedEvents: before.items.map((item) => item.name) };
+  }
+  const current = new Map(after.items.map((item) => [item.name, item]));
+  const violations = compareStream(before, after);
+  const removedEvents = [];
+  for (const item of before.items) {
+    const now = current.get(item.name);
+    if (!now) {
+      removedEvents.push(item.name);
+      continue;
+    }
+    violations.push(...compareEvent(item, now));
+  }
+  return { violations, removedEvents };
+}
 function compareDocuments(before, after) {
   const current = new Map(after.operations.map((operation) => [operation.name, operation]));
   const violations = [];
@@ -291,7 +393,12 @@ function compareDocuments(before, after) {
     }
     violations.push(...compareOperation(operation, now));
   }
-  return { violations, removedOperations };
+  const events = compareEvents(before.events, after.events);
+  return {
+    violations: [...violations, ...events.violations],
+    removedOperations,
+    removedEvents: events.removedEvents
+  };
 }
 var ContractSnapshotError = class extends Error {
   constructor(message) {
@@ -454,10 +561,15 @@ function parseRecord(file, raw) {
   if (!Array.isArray(parsed.operations) || parsed.operations.some((name) => typeof name !== "string")) {
     throw new Error('"operations" must be an array of operation names');
   }
+  const events = parsed.events ?? [];
+  if (!Array.isArray(events) || events.some((name) => typeof name !== "string")) {
+    throw new Error('"events" must be an array of event names');
+  }
   return {
     platform: parsed.platform,
     appVersion: parsed.appVersion,
     operations: parsed.operations,
+    events,
     file
   };
 }
@@ -489,6 +601,9 @@ function readUsageRecords(usageDir2) {
 function callersOf(operation, records) {
   return records.filter((record) => record.operations.includes(operation));
 }
+function subscribersOf(event, records) {
+  return records.filter((record) => (record.events ?? []).includes(event));
+}
 
 // src/contract/check.ts
 function checkContract(contractsDir, current) {
@@ -514,45 +629,54 @@ function checkContract(contractsDir, current) {
       }]
     };
   }
-  const { violations, removedOperations } = compareDocuments(previous, current);
+  const { violations, removedOperations, removedEvents } = compareDocuments(previous, current);
   return {
     baselineVersion: baseline.version,
     warnings: [],
-    violations: [...violations, ...judgeRemovals(contractsDir, removedOperations)]
+    violations: [...violations, ...judgeRemovals(contractsDir, removedOperations, removedEvents)]
   };
 }
-function judgeRemovals(contractsDir, removedOperations) {
-  if (removedOperations.length === 0) {
+function judgeRemovals(contractsDir, removedOperations, removedEvents) {
+  const removed = [...removedOperations, ...removedEvents];
+  if (removed.length === 0) {
     return [];
   }
   const usage = readUsageRecords(usageDir(contractsDir));
   if (!usage.decidable) {
     return [{
       kind: "usage.undecidable",
-      detail: `${removedOperations.join(", ")} would be removed, but no released client's call list could be read (${usage.reason}). Not knowing who calls an operation is not the same as knowing nobody does.`
+      detail: `${removed.join(", ")} would be removed, but no released client's usage list could be read (${usage.reason}). Not knowing who uses it is not the same as knowing nobody does.`
     }];
   }
-  const violations = [];
-  for (const operation of removedOperations) {
-    const callers = callersOf(operation, usage.records);
-    if (callers.length === 0) {
-      continue;
-    }
-    violations.push({
-      kind: "usage.still-called",
-      operation,
-      detail: "still called by " + callers.map((caller) => `${caller.platform} ${caller.appVersion}`).join(", ")
-    });
+  return [
+    ...removedOperations.flatMap((operation) => stillUsed(
+      { kind: "usage.still-called", operation },
+      "still called by",
+      callersOf(operation, usage.records)
+    )),
+    ...removedEvents.flatMap((event) => stillUsed(
+      { kind: "usage.still-subscribed", event },
+      "still subscribed to by",
+      subscribersOf(event, usage.records)
+    ))
+  ];
+}
+function stillUsed(subject, verb, users) {
+  if (users.length === 0) {
+    return [];
   }
-  return violations;
+  return [{
+    ...subject,
+    detail: `${verb} ${users.map((user) => `${user.platform} ${user.appVersion}`).join(", ")}`
+  }];
 }
 function formatViolations(violations) {
   return violations.map((violation) => {
-    const where = [violation.operation, violation.location].filter(Boolean).join(" ");
+    const where = [violation.operation ?? violation.event, violation.location].filter(Boolean).join(" ");
     return `  - [${violation.kind}]${where ? ` ${where}` : ""}: ${violation.detail}`;
   }).join("\n");
 }
 
-export { CURRENT_FILENAME, ContractCollectionError, ContractSnapshotError, RELEASED_DIRNAME, USAGE_DIRNAME, callersOf, canonicalize, checkContract, collectContractDocument, compareDocuments, compareOperation, compareVersions, currentPath, formatViolations, listSnapshots, newestSnapshot, readCurrentDocument, readSnapshot, readUsageRecords, releasedDir, stableDigest, stableStringify, stableStringifyPretty, usageDir, writeCurrentDocument, writeSnapshot };
+export { CURRENT_FILENAME, ContractCollectionError, ContractSnapshotError, RELEASED_DIRNAME, USAGE_DIRNAME, callersOf, canonicalize, checkContract, collectContractDocument, compareDocuments, compareOperation, compareVersions, currentPath, formatViolations, listSnapshots, newestSnapshot, readCurrentDocument, readSnapshot, readUsageRecords, releasedDir, stableDigest, stableStringify, stableStringifyPretty, subscribersOf, usageDir, writeCurrentDocument, writeSnapshot };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map