@semilayer/core 0.1.0 → 0.1.2

package/dist/index.d.cts

@@ -4,7 +4,7 @@ type FacetName = (typeof FACET_NAMES)[number];
 declare const FUTURE_FACETS: readonly ["dedup", "classify"];
 declare const FIELD_TYPES: readonly ["text", "number", "boolean", "date", "json", "enum", "relation"];
 type FieldType = (typeof FIELD_TYPES)[number];
-declare const INGEST_JOB_TYPES: readonly ["full", "incremental", "delete", "records"];
+declare const INGEST_JOB_TYPES: readonly ["full", "incremental", "delete", "records", "sync"];
 type IngestJobType = (typeof INGEST_JOB_TYPES)[number];
 declare const LENS_STATUSES: readonly ["paused", "indexing", "ready", "error"];
 type LensStatus = (typeof LENS_STATUSES)[number];
@@ -106,8 +106,31 @@ interface AuthConfig {
         rules?: LensRules;
     };
 }
+/** Keys whose values are AccessRule. `stream` lives on LensRules but has its own shape. */
 type LensRuleKey = FacetName | 'query';
-type LensRules = Partial<Record<LensRuleKey, AccessRule>>;
+/**
+ * Per-lens streaming configuration. Streaming is a transport, not a facet —
+ * it lives under `rules.stream` so it can be enabled, scoped to certain modes,
+ * or capped per-lens.
+ *
+ * - `enabled` defaults to `true` — streaming is on for any lens that has at
+ *   least one supported facet.
+ * - `modes` defaults to both `['chunked', 'live']`. Restrict to disable a mode.
+ * - `maxLiveSubscriptions` is a per-lens cap on top of the org-wide tier limit.
+ *
+ * The canonical `StreamMode` type lives in `./stream.ts`.
+ */
+interface StreamRules {
+    enabled?: boolean;
+    modes?: Array<'chunked' | 'live'>;
+    maxLiveSubscriptions?: number;
+}
+interface LensRules {
+    search?: AccessRule;
+    similar?: AccessRule;
+    query?: AccessRule;
+    stream?: StreamRules;
+}
 interface EmbeddingConfig {
     provider: string;
     model: string;
@@ -298,12 +321,19 @@ interface IngestJobPayload {
     environmentId: string;
     lensName: string;
     sourceName: string;
-    type: 'full' | 'incremental' | 'delete';
+    type: 'full' | 'incremental' | 'delete' | 'records' | 'sync';
     cursor?: string;
     /** True when triggered by a platform admin (bypasses quotas) */
     adminInvoked?: boolean;
     /** OIDC sub of the user who triggered this job */
     invokedBy?: string;
+    /**
+     * Smart sync only — when true, the sync handler wipes the partition first
+     * and then re-runs the full scan. Equivalent to the legacy "rebuild" flow.
+     * When false (default) the handler dedups against existing hashes and
+     * tombstones rows that disappeared from the source.
+     */
+    rebuild?: boolean;
 }
 /**
  * Full job data for v0.1 standalone/test mode.
@@ -356,7 +386,7 @@ interface LensStatusInfo {
     vectorCount: number;
     totalRows?: number;
     lastIngestAt?: Date;
-    lastIngestType?: 'full' | 'incremental';
+    lastIngestType?: 'full' | 'incremental' | 'sync' | 'records';
     cursor?: string;
     error?: string;
     rateLimit?: RateLimitState;
@@ -434,6 +464,11 @@ interface Member {
 }
 interface IngestRun {
     id: string;
+    /**
+     * Which ingest path produced this run. Null for legacy rows from before
+     * the type column existed.
+     */
+    type: 'full' | 'incremental' | 'records' | 'sync' | null;
     status: IngestStatus;
     recordsProcessed: number;
     recordsFailed: number;
@@ -444,6 +479,17 @@ interface IngestRun {
     invokedBy: string | null;
     createdAt: ISODateString;
 }
+/**
+ * Paginated response envelope used by list endpoints that grow with usage
+ * (ingest runs, jobs, etc.). `total` is the count after any filters are
+ * applied — use it to drive pagination UI without re-counting client-side.
+ */
+interface Page<T> {
+    items: T[];
+    total: number;
+    limit: number;
+    offset: number;
+}
 interface Tier {
     id: string;
     name: string;
@@ -465,6 +511,14 @@ interface Tier {
     orgsPerUser: number | null;
     /** Step 12 — per-minute ingest webhook rate limit. */
     ingestWebhooksPerMinute: number | null;
+    /** Streaming — concurrent WebSocket connections per org (per-pod enforced). */
+    concurrentWsConnections: number | null;
+    /** Streaming — sliding window of rows emitted via streaming per hour. */
+    wsRowsPerHour: number | null;
+    /** Streaming — concurrent live tail subscriptions per org. */
+    wsLiveSubscriptions: number | null;
+    /** Streaming — WS control-frame budget per minute (separate from apiRequestsPerMinute). */
+    wsOpsPerMinute: number | null;
     features: Record<string, unknown>;
     displayOrder: number;
     isDefault: boolean;
@@ -485,6 +539,11 @@ interface TierOverride {
     membersPerOrg: number | null;
     orgsPerUser: number | null;
     ingestWebhooksPerMinute: number | null;
+    /** Streaming — see Tier. Null = inherit from tier; explicit value overrides. */
+    concurrentWsConnections: number | null;
+    wsRowsPerHour: number | null;
+    wsLiveSubscriptions: number | null;
+    wsOpsPerMinute: number | null;
     features: Record<string, unknown> | null;
     note: string | null;
     createdAt: ISODateString;
@@ -926,6 +985,11 @@ interface TierFull {
     membersPerOrg: number | null;
     orgsPerUser: number | null;
     ingestWebhooksPerMinute: number | null;
+    /** Streaming — see Tier. */
+    concurrentWsConnections: number | null;
+    wsRowsPerHour: number | null;
+    wsLiveSubscriptions: number | null;
+    wsOpsPerMinute: number | null;
     features: Record<string, unknown>;
     displayOrder: number;
     isDefault: boolean;
@@ -1012,6 +1076,11 @@ interface TierOverrideRequest {
     membersPerOrg?: number | null;
     orgsPerUser?: number | null;
     ingestWebhooksPerMinute?: number | null;
+    /** Streaming — see Tier. Null = inherit from tier. */
+    concurrentWsConnections?: number | null;
+    wsRowsPerHour?: number | null;
+    wsLiveSubscriptions?: number | null;
+    wsOpsPerMinute?: number | null;
     features?: Record<string, unknown> | null;
     note?: string | null;
 }
@@ -1024,9 +1093,165 @@ interface QuotaErrorResponse {
     upgradeUrl: string;
 }
 
+declare const STREAM_MODES: readonly ["chunked", "live"];
+type StreamMode = (typeof STREAM_MODES)[number];
+declare const LIVE_TAIL_MODES: readonly ["push", "polling", "unsupported"];
+type LiveTailMode = (typeof LIVE_TAIL_MODES)[number];
+/** WebSocket op names sent from client to server in the `op` field. */
+declare const STREAM_OPS: readonly ["search.stream", "query.stream", "subscribe", "observe", "unsubscribe"];
+type StreamOp = (typeof STREAM_OPS)[number];
+/** Frame `type` values for both directions. */
+declare const STREAM_FRAME_TYPES: readonly ["row", "done", "error", "event", "ping", "pong"];
+type StreamFrameType = (typeof STREAM_FRAME_TYPES)[number];
+/** Subscription event kinds (mirrors ingest write operations). */
+declare const STREAM_EVENT_KINDS: readonly ["insert", "update", "delete"];
+type StreamEventKind = (typeof STREAM_EVENT_KINDS)[number];
+/** Error codes carried in `error` frames. */
+declare const STREAM_ERROR_CODES: readonly ["rate_limited", "forbidden", "bad_request", "not_found", "internal"];
+type StreamErrorCode = (typeof STREAM_ERROR_CODES)[number];
+/**
+ * WebSocket close codes.
+ *
+ * Reserved codes (1xxx) follow RFC 6455. The 4xxx range is application-defined.
+ */
+declare const STREAM_CLOSE_CODES: {
+    /** Normal close — client called .close() or server finished. */
+    readonly normal: 1000;
+    /** Server-side internal error. */
+    readonly internal: 1011;
+    /** Auth failed during the upgrade handshake. */
+    readonly authFailed: 4401;
+    /** Lens forbids streaming (rules.stream.enabled === false or modes[] excludes the requested mode). */
+    readonly forbidden: 4403;
+    /** Rate-limited at handshake — over `concurrentWsConnections` for the org. */
+    readonly rateLimited: 4290;
+    /** Mid-stream `wsRowsPerHour` quota exceeded. */
+    readonly quotaExceeded: 4291;
+};
+type StreamCloseCode = (typeof STREAM_CLOSE_CODES)[keyof typeof STREAM_CLOSE_CODES];
+interface StreamSearchParams extends SearchParams {
+    /** Optional batch size hint — server may ignore. Default: 50. */
+    batchSize?: number;
+}
+interface StreamQueryParams extends QueryParams {
+    /** Optional batch size hint — server may ignore. Default: 100. */
+    batchSize?: number;
+}
+interface SubscribeParams {
+    /**
+     * Optional in-process filter applied to events before they're emitted.
+     * v0.1: simple equality only. Complex predicate pushdown is a v0.2 feature.
+     */
+    filter?: Record<string, unknown>;
+}
+/**
+ * One control frame sent from client to server. Multiple ops can ride a single
+ * WebSocket connection — `id` is the multiplexing key the server echoes back
+ * on response frames.
+ */
+interface StreamOpFrame {
+    id: string;
+    op: StreamOp;
+    params?: StreamSearchParams | StreamQueryParams | SubscribeParams | Record<string, unknown>;
+}
+interface StreamMeta {
+    count: number;
+    durationMs: number;
+}
+/** A row from a chunked search/query stream. */
+interface StreamRowFrame<T = Record<string, unknown>> {
+    id: string;
+    type: 'row';
+    data: T;
+}
+/** Terminal frame for a chunked op — no more rows will arrive for this id. */
+interface StreamDoneFrame {
+    id: string;
+    type: 'done';
+    meta: StreamMeta;
+}
+/** Subscription event — pushed for each matching ingest write. */
+interface StreamEventFrame<T = Record<string, unknown>> {
+    id: string;
+    type: 'event';
+    kind: StreamEventKind;
+    record: T;
+}
+/** Error attached to a specific op id (or global if id omitted). */
+interface StreamErrorFrame {
+    id?: string;
+    type: 'error';
+    code: StreamErrorCode;
+    message: string;
+}
+/** Server heartbeat. Client must reply with a `pong` frame. */
+interface StreamPingFrame {
+    type: 'ping';
+}
+/** Client heartbeat reply. */
+interface StreamPongFrame {
+    type: 'pong';
+}
+/** Discriminated union of every frame the server can send. */
+type StreamFrame<T = Record<string, unknown>> = StreamRowFrame<T> | StreamDoneFrame | StreamEventFrame<T> | StreamErrorFrame | StreamPingFrame | StreamPongFrame;
+/** What `BeamClient.subscribe()` yields per event. */
+interface StreamEvent<M = Record<string, unknown>> {
+    kind: StreamEventKind;
+    record: M;
+}
+/** What `BeamClient.streamSearch()` yields per row. */
+type StreamSearchRow<M = Record<string, unknown>> = SearchResult<M>;
+interface DeriveLiveTailModeInput {
+    /** Lens rules — if `rules.stream.modes` excludes `'live'`, the mode is `unsupported`. */
+    rules?: LensRules;
+    /** Lens sync interval — presence implies polling-mode ingest. */
+    syncInterval?: SyncInterval;
+    /** Source feature flags from the bridge. */
+    bridgeFeatures?: SourceFeature[];
+    /**
+     * Whether at least one ingest key (ik_) exists for the lens. This is a
+     * runtime fact (DB-derived) — callers must look it up before invoking.
+     */
+    acceptsIngestKey: boolean;
+}
+/**
+ * Is streaming enabled at all for this lens? Returns false only when the lens
+ * config explicitly opts out via `rules.stream.enabled === false`. Default: true.
+ *
+ * This is the question the worker asks before populating the live tail buffer:
+ * if a lens has streaming disabled, no one can subscribe, so there is no point
+ * paying for the INSERT + NOTIFY.
+ */
+declare function isStreamingEnabled(rules?: LensRules): boolean;
+/**
+ * Is the `live` stream mode allowed for this lens? Returns false if streaming
+ * is fully disabled OR if `rules.stream.modes` is set and excludes `'live'`.
+ * Default: true.
+ *
+ * This is the gate for the worker's observation pathway. When false, the worker
+ * skips the live tail buffer entirely — observation is microweight, but it is
+ * not zero, and there is no value populating a buffer subscribers can never read.
+ */
+declare function isLiveTailModeEnabled(rules?: LensRules): boolean;
+/**
+ * Derive the live-tail mode for a lens.
+ *
+ * Live tail rides our **own ingest write path**, not bridge-native CDC. So as
+ * long as records are being written to `vectors.embeddings` by *some* ingest
+ * pathway, live tail works:
+ *
+ * - `'push'` — the lens accepts `ik_` ingest webhooks → near-realtime fan-out
+ * - `'polling'` — the bridge supports incremental sync and a syncInterval is set
+ *   → smooth-but-bursty fan-out at the polling cadence
+ * - `'unsupported'` — neither path is available, OR `rules.stream.modes`
+ *   explicitly excludes `'live'`. The Console Explorer disables the live tab
+ *   and the `subscribe` op returns a forbidden close code.
+ */
+declare function deriveLiveTailMode(input: DeriveLiveTailModeInput): LiveTailMode;
+
 declare function getDeploymentMode(): DeploymentMode;
 declare function isSaasMode(): boolean;
 
 declare function defineConfig(config: SemiLayerConfig): SemiLayerConfig;
 
-export { type AccessRule, type AccessRuleResult, type AdminAssignUserBody, type AdminCashSnapshot, type AdminMrrSnapshot, type AdminOrgUsage, type AdminStripeEventRow, type AdminTopConsumerRow, type AdminTopConsumersResponse, type AdminUserDetail, type AdminUserListItem, type AdminUserListResponse, type AdminUserOrgMembership, type ApiKeyInfo, type AuditLogEntry, type AuthConfig, type AuthOrg, type AuthUser, type BannedIp, type BannedUser, type BannerData, type BillingCycleInfo, type BillingPlan, type BillingRedirectResponse, type BillingSnapshot, type Bridge, type BridgeConstructor, type BridgeRow, type BuiltinTransform, type CancelSubscriptionRequest, type CheckoutRequest, type ClaimCheck, type ClassifyFacetConfig, type ConfigExportResponse, type CreateEnvResponse, type CreateProjectResponse, DEPLOYMENT_MODES, type DailyMetrics, type DedupFacetConfig, type DeploymentMode, type DriftLensInfo, type DriftResponse, type EmbeddingConfig, type EmbeddingField, type Environment, type EnvironmentAuthConfig, type EnvsResponse, FACET_NAMES, FIELD_TYPES, FUTURE_FACETS, type FacetConfig, type FacetName, type FailedJobInfo, type FeedbackDetail, type FeedbackItem, type FieldConfig, type FieldType, INGEST_JOB_TYPES, INGEST_STATUSES, type ISODateString, type InAppNotification, type IngestControl, type IngestErrorEntry, type IngestJobData, type IngestJobPayload, type IngestJobType, type IngestRun, type IngestStatus, type InviteInfo, type Invoice, type JwtClaims, type JwtConfig, KEY_PREFIXES, LENS_STATUSES, type Lens, type LensComparison, type LensConfig, type LensCreateResponse, type LensRuleKey, type LensRules, type LensStatus, type LensStatusInfo, MERGE_STRATEGIES, type MeResponse, type Member, type MergeStrategy, type MetricPoint, type NewKeyPair, type NotificationPreferenceSummary, type OrderByClause, type Org, type OrgDetailResponse, type OrgListItem, type PendingInvite, type PendingInvitesResponse, type PlatformAdmin, type PlatformStats, type Project, type ProjectWithEnvs, type PushIngestJob, type PushLensSummary, type PushResponse, type QueryOptions, type QueryParams, type QueryResponse, type QueryResult, type QueueCounts, type QuotaErrorResponse, type RateLimitState, type ReadOptions, type ReadResult, SOURCE_FEATURES, type SearchFacetConfig, type SearchParams, type SearchResponse, type SearchResult, type SemiLayerConfig, type SimilarFacetConfig, type SimilarParams, type SimilarResponse, type Source, type SourceConfig, type SourceFeature, type StatusEnvironment, type StatusResponse, type SyncInterval, type SystemHealth, TRANSFORM_TYPES, type TargetColumnInfo, type TargetSchema, type Tier, type TierFull, type TierOverride, type TierOverrideRequest, type TierSummary, type TiersResponse, type TransformSpec, type TransformType, type TransportMode, type TransportOptions, type UsageMetricSnapshot, type WhereClause, canonicalHash, defineConfig, getDeploymentMode, isSaasMode, mapDbTypeToFieldType, resolveEmbeddingFieldNames, resolveEmbeddingFields, resolveSourceColumns, validateConfig };
+export { type AccessRule, type AccessRuleResult, type AdminAssignUserBody, type AdminCashSnapshot, type AdminMrrSnapshot, type AdminOrgUsage, type AdminStripeEventRow, type AdminTopConsumerRow, type AdminTopConsumersResponse, type AdminUserDetail, type AdminUserListItem, type AdminUserListResponse, type AdminUserOrgMembership, type ApiKeyInfo, type AuditLogEntry, type AuthConfig, type AuthOrg, type AuthUser, type BannedIp, type BannedUser, type BannerData, type BillingCycleInfo, type BillingPlan, type BillingRedirectResponse, type BillingSnapshot, type Bridge, type BridgeConstructor, type BridgeRow, type BuiltinTransform, type CancelSubscriptionRequest, type CheckoutRequest, type ClaimCheck, type ClassifyFacetConfig, type ConfigExportResponse, type CreateEnvResponse, type CreateProjectResponse, DEPLOYMENT_MODES, type DailyMetrics, type DedupFacetConfig, type DeploymentMode, type DeriveLiveTailModeInput, type DriftLensInfo, type DriftResponse, type EmbeddingConfig, type EmbeddingField, type Environment, type EnvironmentAuthConfig, type EnvsResponse, FACET_NAMES, FIELD_TYPES, FUTURE_FACETS, type FacetConfig, type FacetName, type FailedJobInfo, type FeedbackDetail, type FeedbackItem, type FieldConfig, type FieldType, INGEST_JOB_TYPES, INGEST_STATUSES, type ISODateString, type InAppNotification, type IngestControl, type IngestErrorEntry, type IngestJobData, type IngestJobPayload, type IngestJobType, type IngestRun, type IngestStatus, type InviteInfo, type Invoice, type JwtClaims, type JwtConfig, KEY_PREFIXES, LENS_STATUSES, LIVE_TAIL_MODES, type Lens, type LensComparison, type LensConfig, type LensCreateResponse, type LensRuleKey, type LensRules, type LensStatus, type LensStatusInfo, type LiveTailMode, MERGE_STRATEGIES, type MeResponse, type Member, type MergeStrategy, type MetricPoint, type NewKeyPair, type NotificationPreferenceSummary, type OrderByClause, type Org, type OrgDetailResponse, type OrgListItem, type Page, type PendingInvite, type PendingInvitesResponse, type PlatformAdmin, type PlatformStats, type Project, type ProjectWithEnvs, type PushIngestJob, type PushLensSummary, type PushResponse, type QueryOptions, type QueryParams, type QueryResponse, type QueryResult, type QueueCounts, type QuotaErrorResponse, type RateLimitState, type ReadOptions, type ReadResult, SOURCE_FEATURES, STREAM_CLOSE_CODES, STREAM_ERROR_CODES, STREAM_EVENT_KINDS, STREAM_FRAME_TYPES, STREAM_MODES, STREAM_OPS, type SearchFacetConfig, type SearchParams, type SearchResponse, type SearchResult, type SemiLayerConfig, type SimilarFacetConfig, type SimilarParams, type SimilarResponse, type Source, type SourceConfig, type SourceFeature, type StatusEnvironment, type StatusResponse, type StreamCloseCode, type StreamDoneFrame, type StreamErrorCode, type StreamErrorFrame, type StreamEvent, type StreamEventFrame, type StreamEventKind, type StreamFrame, type StreamFrameType, type StreamMeta, type StreamMode, type StreamOp, type StreamOpFrame, type StreamPingFrame, type StreamPongFrame, type StreamQueryParams, type StreamRowFrame, type StreamRules, type StreamSearchParams, type StreamSearchRow, type SubscribeParams, type SyncInterval, type SystemHealth, TRANSFORM_TYPES, type TargetColumnInfo, type TargetSchema, type Tier, type TierFull, type TierOverride, type TierOverrideRequest, type TierSummary, type TiersResponse, type TransformSpec, type TransformType, type TransportMode, type TransportOptions, type UsageMetricSnapshot, type WhereClause, canonicalHash, defineConfig, deriveLiveTailMode, getDeploymentMode, isLiveTailModeEnabled, isSaasMode, isStreamingEnabled, mapDbTypeToFieldType, resolveEmbeddingFieldNames, resolveEmbeddingFields, resolveSourceColumns, validateConfig };

package/dist/index.d.ts

@@ -4,7 +4,7 @@ type FacetName = (typeof FACET_NAMES)[number];
 declare const FUTURE_FACETS: readonly ["dedup", "classify"];
 declare const FIELD_TYPES: readonly ["text", "number", "boolean", "date", "json", "enum", "relation"];
 type FieldType = (typeof FIELD_TYPES)[number];
-declare const INGEST_JOB_TYPES: readonly ["full", "incremental", "delete", "records"];
+declare const INGEST_JOB_TYPES: readonly ["full", "incremental", "delete", "records", "sync"];
 type IngestJobType = (typeof INGEST_JOB_TYPES)[number];
 declare const LENS_STATUSES: readonly ["paused", "indexing", "ready", "error"];
 type LensStatus = (typeof LENS_STATUSES)[number];
@@ -106,8 +106,31 @@ interface AuthConfig {
         rules?: LensRules;
     };
 }
+/** Keys whose values are AccessRule. `stream` lives on LensRules but has its own shape. */
 type LensRuleKey = FacetName | 'query';
-type LensRules = Partial<Record<LensRuleKey, AccessRule>>;
+/**
+ * Per-lens streaming configuration. Streaming is a transport, not a facet —
+ * it lives under `rules.stream` so it can be enabled, scoped to certain modes,
+ * or capped per-lens.
+ *
+ * - `enabled` defaults to `true` — streaming is on for any lens that has at
+ *   least one supported facet.
+ * - `modes` defaults to both `['chunked', 'live']`. Restrict to disable a mode.
+ * - `maxLiveSubscriptions` is a per-lens cap on top of the org-wide tier limit.
+ *
+ * The canonical `StreamMode` type lives in `./stream.ts`.
+ */
+interface StreamRules {
+    enabled?: boolean;
+    modes?: Array<'chunked' | 'live'>;
+    maxLiveSubscriptions?: number;
+}
+interface LensRules {
+    search?: AccessRule;
+    similar?: AccessRule;
+    query?: AccessRule;
+    stream?: StreamRules;
+}
 interface EmbeddingConfig {
     provider: string;
     model: string;
@@ -298,12 +321,19 @@ interface IngestJobPayload {
     environmentId: string;
     lensName: string;
     sourceName: string;
-    type: 'full' | 'incremental' | 'delete';
+    type: 'full' | 'incremental' | 'delete' | 'records' | 'sync';
     cursor?: string;
     /** True when triggered by a platform admin (bypasses quotas) */
     adminInvoked?: boolean;
     /** OIDC sub of the user who triggered this job */
     invokedBy?: string;
+    /**
+     * Smart sync only — when true, the sync handler wipes the partition first
+     * and then re-runs the full scan. Equivalent to the legacy "rebuild" flow.
+     * When false (default) the handler dedups against existing hashes and
+     * tombstones rows that disappeared from the source.
+     */
+    rebuild?: boolean;
 }
 /**
  * Full job data for v0.1 standalone/test mode.
@@ -356,7 +386,7 @@ interface LensStatusInfo {
     vectorCount: number;
     totalRows?: number;
     lastIngestAt?: Date;
-    lastIngestType?: 'full' | 'incremental';
+    lastIngestType?: 'full' | 'incremental' | 'sync' | 'records';
     cursor?: string;
     error?: string;
     rateLimit?: RateLimitState;
@@ -434,6 +464,11 @@ interface Member {
 }
 interface IngestRun {
     id: string;
+    /**
+     * Which ingest path produced this run. Null for legacy rows from before
+     * the type column existed.
+     */
+    type: 'full' | 'incremental' | 'records' | 'sync' | null;
     status: IngestStatus;
     recordsProcessed: number;
     recordsFailed: number;
@@ -444,6 +479,17 @@ interface IngestRun {
     invokedBy: string | null;
     createdAt: ISODateString;
 }
+/**
+ * Paginated response envelope used by list endpoints that grow with usage
+ * (ingest runs, jobs, etc.). `total` is the count after any filters are
+ * applied — use it to drive pagination UI without re-counting client-side.
+ */
+interface Page<T> {
+    items: T[];
+    total: number;
+    limit: number;
+    offset: number;
+}
 interface Tier {
     id: string;
     name: string;
@@ -465,6 +511,14 @@ interface Tier {
     orgsPerUser: number | null;
     /** Step 12 — per-minute ingest webhook rate limit. */
     ingestWebhooksPerMinute: number | null;
+    /** Streaming — concurrent WebSocket connections per org (per-pod enforced). */
+    concurrentWsConnections: number | null;
+    /** Streaming — sliding window of rows emitted via streaming per hour. */
+    wsRowsPerHour: number | null;
+    /** Streaming — concurrent live tail subscriptions per org. */
+    wsLiveSubscriptions: number | null;
+    /** Streaming — WS control-frame budget per minute (separate from apiRequestsPerMinute). */
+    wsOpsPerMinute: number | null;
     features: Record<string, unknown>;
     displayOrder: number;
     isDefault: boolean;
@@ -485,6 +539,11 @@ interface TierOverride {
     membersPerOrg: number | null;
     orgsPerUser: number | null;
     ingestWebhooksPerMinute: number | null;
+    /** Streaming — see Tier. Null = inherit from tier; explicit value overrides. */
+    concurrentWsConnections: number | null;
+    wsRowsPerHour: number | null;
+    wsLiveSubscriptions: number | null;
+    wsOpsPerMinute: number | null;
     features: Record<string, unknown> | null;
     note: string | null;
     createdAt: ISODateString;
@@ -926,6 +985,11 @@ interface TierFull {
     membersPerOrg: number | null;
     orgsPerUser: number | null;
     ingestWebhooksPerMinute: number | null;
+    /** Streaming — see Tier. */
+    concurrentWsConnections: number | null;
+    wsRowsPerHour: number | null;
+    wsLiveSubscriptions: number | null;
+    wsOpsPerMinute: number | null;
     features: Record<string, unknown>;
     displayOrder: number;
     isDefault: boolean;
@@ -1012,6 +1076,11 @@ interface TierOverrideRequest {
     membersPerOrg?: number | null;
     orgsPerUser?: number | null;
     ingestWebhooksPerMinute?: number | null;
+    /** Streaming — see Tier. Null = inherit from tier. */
+    concurrentWsConnections?: number | null;
+    wsRowsPerHour?: number | null;
+    wsLiveSubscriptions?: number | null;
+    wsOpsPerMinute?: number | null;
     features?: Record<string, unknown> | null;
     note?: string | null;
 }
@@ -1024,9 +1093,165 @@ interface QuotaErrorResponse {
     upgradeUrl: string;
 }
 
+declare const STREAM_MODES: readonly ["chunked", "live"];
+type StreamMode = (typeof STREAM_MODES)[number];
+declare const LIVE_TAIL_MODES: readonly ["push", "polling", "unsupported"];
+type LiveTailMode = (typeof LIVE_TAIL_MODES)[number];
+/** WebSocket op names sent from client to server in the `op` field. */
+declare const STREAM_OPS: readonly ["search.stream", "query.stream", "subscribe", "observe", "unsubscribe"];
+type StreamOp = (typeof STREAM_OPS)[number];
+/** Frame `type` values for both directions. */
+declare const STREAM_FRAME_TYPES: readonly ["row", "done", "error", "event", "ping", "pong"];
+type StreamFrameType = (typeof STREAM_FRAME_TYPES)[number];
+/** Subscription event kinds (mirrors ingest write operations). */
+declare const STREAM_EVENT_KINDS: readonly ["insert", "update", "delete"];
+type StreamEventKind = (typeof STREAM_EVENT_KINDS)[number];
+/** Error codes carried in `error` frames. */
+declare const STREAM_ERROR_CODES: readonly ["rate_limited", "forbidden", "bad_request", "not_found", "internal"];
+type StreamErrorCode = (typeof STREAM_ERROR_CODES)[number];
+/**
+ * WebSocket close codes.
+ *
+ * Reserved codes (1xxx) follow RFC 6455. The 4xxx range is application-defined.
+ */
+declare const STREAM_CLOSE_CODES: {
+    /** Normal close — client called .close() or server finished. */
+    readonly normal: 1000;
+    /** Server-side internal error. */
+    readonly internal: 1011;
+    /** Auth failed during the upgrade handshake. */
+    readonly authFailed: 4401;
+    /** Lens forbids streaming (rules.stream.enabled === false or modes[] excludes the requested mode). */
+    readonly forbidden: 4403;
+    /** Rate-limited at handshake — over `concurrentWsConnections` for the org. */
+    readonly rateLimited: 4290;
+    /** Mid-stream `wsRowsPerHour` quota exceeded. */
+    readonly quotaExceeded: 4291;
+};
+type StreamCloseCode = (typeof STREAM_CLOSE_CODES)[keyof typeof STREAM_CLOSE_CODES];
+interface StreamSearchParams extends SearchParams {
+    /** Optional batch size hint — server may ignore. Default: 50. */
+    batchSize?: number;
+}
+interface StreamQueryParams extends QueryParams {
+    /** Optional batch size hint — server may ignore. Default: 100. */
+    batchSize?: number;
+}
+interface SubscribeParams {
+    /**
+     * Optional in-process filter applied to events before they're emitted.
+     * v0.1: simple equality only. Complex predicate pushdown is a v0.2 feature.
+     */
+    filter?: Record<string, unknown>;
+}
+/**
+ * One control frame sent from client to server. Multiple ops can ride a single
+ * WebSocket connection — `id` is the multiplexing key the server echoes back
+ * on response frames.
+ */
+interface StreamOpFrame {
+    id: string;
+    op: StreamOp;
+    params?: StreamSearchParams | StreamQueryParams | SubscribeParams | Record<string, unknown>;
+}
+interface StreamMeta {
+    count: number;
+    durationMs: number;
+}
+/** A row from a chunked search/query stream. */
+interface StreamRowFrame<T = Record<string, unknown>> {
+    id: string;
+    type: 'row';
+    data: T;
+}
+/** Terminal frame for a chunked op — no more rows will arrive for this id. */
+interface StreamDoneFrame {
+    id: string;
+    type: 'done';
+    meta: StreamMeta;
+}
+/** Subscription event — pushed for each matching ingest write. */
+interface StreamEventFrame<T = Record<string, unknown>> {
+    id: string;
+    type: 'event';
+    kind: StreamEventKind;
+    record: T;
+}
+/** Error attached to a specific op id (or global if id omitted). */
+interface StreamErrorFrame {
+    id?: string;
+    type: 'error';
+    code: StreamErrorCode;
+    message: string;
+}
+/** Server heartbeat. Client must reply with a `pong` frame. */
+interface StreamPingFrame {
+    type: 'ping';
+}
+/** Client heartbeat reply. */
+interface StreamPongFrame {
+    type: 'pong';
+}
+/** Discriminated union of every frame the server can send. */
+type StreamFrame<T = Record<string, unknown>> = StreamRowFrame<T> | StreamDoneFrame | StreamEventFrame<T> | StreamErrorFrame | StreamPingFrame | StreamPongFrame;
+/** What `BeamClient.subscribe()` yields per event. */
+interface StreamEvent<M = Record<string, unknown>> {
+    kind: StreamEventKind;
+    record: M;
+}
+/** What `BeamClient.streamSearch()` yields per row. */
+type StreamSearchRow<M = Record<string, unknown>> = SearchResult<M>;
+interface DeriveLiveTailModeInput {
+    /** Lens rules — if `rules.stream.modes` excludes `'live'`, the mode is `unsupported`. */
+    rules?: LensRules;
+    /** Lens sync interval — presence implies polling-mode ingest. */
+    syncInterval?: SyncInterval;
+    /** Source feature flags from the bridge. */
+    bridgeFeatures?: SourceFeature[];
+    /**
+     * Whether at least one ingest key (ik_) exists for the lens. This is a
+     * runtime fact (DB-derived) — callers must look it up before invoking.
+     */
+    acceptsIngestKey: boolean;
+}
+/**
+ * Is streaming enabled at all for this lens? Returns false only when the lens
+ * config explicitly opts out via `rules.stream.enabled === false`. Default: true.
+ *
+ * This is the question the worker asks before populating the live tail buffer:
+ * if a lens has streaming disabled, no one can subscribe, so there is no point
+ * paying for the INSERT + NOTIFY.
+ */
+declare function isStreamingEnabled(rules?: LensRules): boolean;
+/**
+ * Is the `live` stream mode allowed for this lens? Returns false if streaming
+ * is fully disabled OR if `rules.stream.modes` is set and excludes `'live'`.
+ * Default: true.
+ *
+ * This is the gate for the worker's observation pathway. When false, the worker
+ * skips the live tail buffer entirely — observation is microweight, but it is
+ * not zero, and there is no value populating a buffer subscribers can never read.
+ */
+declare function isLiveTailModeEnabled(rules?: LensRules): boolean;
+/**
+ * Derive the live-tail mode for a lens.
+ *
+ * Live tail rides our **own ingest write path**, not bridge-native CDC. So as
+ * long as records are being written to `vectors.embeddings` by *some* ingest
+ * pathway, live tail works:
+ *
+ * - `'push'` — the lens accepts `ik_` ingest webhooks → near-realtime fan-out
+ * - `'polling'` — the bridge supports incremental sync and a syncInterval is set
+ *   → smooth-but-bursty fan-out at the polling cadence
+ * - `'unsupported'` — neither path is available, OR `rules.stream.modes`
+ *   explicitly excludes `'live'`. The Console Explorer disables the live tab
+ *   and the `subscribe` op returns a forbidden close code.
+ */
+declare function deriveLiveTailMode(input: DeriveLiveTailModeInput): LiveTailMode;
+
 declare function getDeploymentMode(): DeploymentMode;
 declare function isSaasMode(): boolean;
 
 declare function defineConfig(config: SemiLayerConfig): SemiLayerConfig;
 
-export { type AccessRule, type AccessRuleResult, type AdminAssignUserBody, type AdminCashSnapshot, type AdminMrrSnapshot, type AdminOrgUsage, type AdminStripeEventRow, type AdminTopConsumerRow, type AdminTopConsumersResponse, type AdminUserDetail, type AdminUserListItem, type AdminUserListResponse, type AdminUserOrgMembership, type ApiKeyInfo, type AuditLogEntry, type AuthConfig, type AuthOrg, type AuthUser, type BannedIp, type BannedUser, type BannerData, type BillingCycleInfo, type BillingPlan, type BillingRedirectResponse, type BillingSnapshot, type Bridge, type BridgeConstructor, type BridgeRow, type BuiltinTransform, type CancelSubscriptionRequest, type CheckoutRequest, type ClaimCheck, type ClassifyFacetConfig, type ConfigExportResponse, type CreateEnvResponse, type CreateProjectResponse, DEPLOYMENT_MODES, type DailyMetrics, type DedupFacetConfig, type DeploymentMode, type DriftLensInfo, type DriftResponse, type EmbeddingConfig, type EmbeddingField, type Environment, type EnvironmentAuthConfig, type EnvsResponse, FACET_NAMES, FIELD_TYPES, FUTURE_FACETS, type FacetConfig, type FacetName, type FailedJobInfo, type FeedbackDetail, type FeedbackItem, type FieldConfig, type FieldType, INGEST_JOB_TYPES, INGEST_STATUSES, type ISODateString, type InAppNotification, type IngestControl, type IngestErrorEntry, type IngestJobData, type IngestJobPayload, type IngestJobType, type IngestRun, type IngestStatus, type InviteInfo, type Invoice, type JwtClaims, type JwtConfig, KEY_PREFIXES, LENS_STATUSES, type Lens, type LensComparison, type LensConfig, type LensCreateResponse, type LensRuleKey, type LensRules, type LensStatus, type LensStatusInfo, MERGE_STRATEGIES, type MeResponse, type Member, type MergeStrategy, type MetricPoint, type NewKeyPair, type NotificationPreferenceSummary, type OrderByClause, type Org, type OrgDetailResponse, type OrgListItem, type PendingInvite, type PendingInvitesResponse, type PlatformAdmin, type PlatformStats, type Project, type ProjectWithEnvs, type PushIngestJob, type PushLensSummary, type PushResponse, type QueryOptions, type QueryParams, type QueryResponse, type QueryResult, type QueueCounts, type QuotaErrorResponse, type RateLimitState, type ReadOptions, type ReadResult, SOURCE_FEATURES, type SearchFacetConfig, type SearchParams, type SearchResponse, type SearchResult, type SemiLayerConfig, type SimilarFacetConfig, type SimilarParams, type SimilarResponse, type Source, type SourceConfig, type SourceFeature, type StatusEnvironment, type StatusResponse, type SyncInterval, type SystemHealth, TRANSFORM_TYPES, type TargetColumnInfo, type TargetSchema, type Tier, type TierFull, type TierOverride, type TierOverrideRequest, type TierSummary, type TiersResponse, type TransformSpec, type TransformType, type TransportMode, type TransportOptions, type UsageMetricSnapshot, type WhereClause, canonicalHash, defineConfig, getDeploymentMode, isSaasMode, mapDbTypeToFieldType, resolveEmbeddingFieldNames, resolveEmbeddingFields, resolveSourceColumns, validateConfig };
+export { type AccessRule, type AccessRuleResult, type AdminAssignUserBody, type AdminCashSnapshot, type AdminMrrSnapshot, type AdminOrgUsage, type AdminStripeEventRow, type AdminTopConsumerRow, type AdminTopConsumersResponse, type AdminUserDetail, type AdminUserListItem, type AdminUserListResponse, type AdminUserOrgMembership, type ApiKeyInfo, type AuditLogEntry, type AuthConfig, type AuthOrg, type AuthUser, type BannedIp, type BannedUser, type BannerData, type BillingCycleInfo, type BillingPlan, type BillingRedirectResponse, type BillingSnapshot, type Bridge, type BridgeConstructor, type BridgeRow, type BuiltinTransform, type CancelSubscriptionRequest, type CheckoutRequest, type ClaimCheck, type ClassifyFacetConfig, type ConfigExportResponse, type CreateEnvResponse, type CreateProjectResponse, DEPLOYMENT_MODES, type DailyMetrics, type DedupFacetConfig, type DeploymentMode, type DeriveLiveTailModeInput, type DriftLensInfo, type DriftResponse, type EmbeddingConfig, type EmbeddingField, type Environment, type EnvironmentAuthConfig, type EnvsResponse, FACET_NAMES, FIELD_TYPES, FUTURE_FACETS, type FacetConfig, type FacetName, type FailedJobInfo, type FeedbackDetail, type FeedbackItem, type FieldConfig, type FieldType, INGEST_JOB_TYPES, INGEST_STATUSES, type ISODateString, type InAppNotification, type IngestControl, type IngestErrorEntry, type IngestJobData, type IngestJobPayload, type IngestJobType, type IngestRun, type IngestStatus, type InviteInfo, type Invoice, type JwtClaims, type JwtConfig, KEY_PREFIXES, LENS_STATUSES, LIVE_TAIL_MODES, type Lens, type LensComparison, type LensConfig, type LensCreateResponse, type LensRuleKey, type LensRules, type LensStatus, type LensStatusInfo, type LiveTailMode, MERGE_STRATEGIES, type MeResponse, type Member, type MergeStrategy, type MetricPoint, type NewKeyPair, type NotificationPreferenceSummary, type OrderByClause, type Org, type OrgDetailResponse, type OrgListItem, type Page, type PendingInvite, type PendingInvitesResponse, type PlatformAdmin, type PlatformStats, type Project, type ProjectWithEnvs, type PushIngestJob, type PushLensSummary, type PushResponse, type QueryOptions, type QueryParams, type QueryResponse, type QueryResult, type QueueCounts, type QuotaErrorResponse, type RateLimitState, type ReadOptions, type ReadResult, SOURCE_FEATURES, STREAM_CLOSE_CODES, STREAM_ERROR_CODES, STREAM_EVENT_KINDS, STREAM_FRAME_TYPES, STREAM_MODES, STREAM_OPS, type SearchFacetConfig, type SearchParams, type SearchResponse, type SearchResult, type SemiLayerConfig, type SimilarFacetConfig, type SimilarParams, type SimilarResponse, type Source, type SourceConfig, type SourceFeature, type StatusEnvironment, type StatusResponse, type StreamCloseCode, type StreamDoneFrame, type StreamErrorCode, type StreamErrorFrame, type StreamEvent, type StreamEventFrame, type StreamEventKind, type StreamFrame, type StreamFrameType, type StreamMeta, type StreamMode, type StreamOp, type StreamOpFrame, type StreamPingFrame, type StreamPongFrame, type StreamQueryParams, type StreamRowFrame, type StreamRules, type StreamSearchParams, type StreamSearchRow, type SubscribeParams, type SyncInterval, type SystemHealth, TRANSFORM_TYPES, type TargetColumnInfo, type TargetSchema, type Tier, type TierFull, type TierOverride, type TierOverrideRequest, type TierSummary, type TiersResponse, type TransformSpec, type TransformType, type TransportMode, type TransportOptions, type UsageMetricSnapshot, type WhereClause, canonicalHash, defineConfig, deriveLiveTailMode, getDeploymentMode, isLiveTailModeEnabled, isSaasMode, isStreamingEnabled, mapDbTypeToFieldType, resolveEmbeddingFieldNames, resolveEmbeddingFields, resolveSourceColumns, validateConfig };