@wavehouse/sdk 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -241,7 +241,22 @@ interface Column {
     name: string;
     type: string;
     is_nullable: boolean;
+    /** Whether the column declares any default at all — see `default_kind`. */
     has_default: boolean;
+    /**
+     * How the default is declared, when there is one: `DEFAULT`, `MATERIALIZED`,
+     * `ALIAS` or `EPHEMERAL`. Omitted when the column declares none.
+     *
+     * `MATERIALIZED` and `ALIAS` columns are computed by ClickHouse and cannot be
+     * inserted — a record naming one is rejected — so they never appear in an
+     * ingest envelope or an SSE `schema` frame, though they are still reported
+     * here and are still queryable.
+     */
+    default_kind?: string;
+    /** 1-based ordinal in the table's declaration order — the order `columns` itself is in. Always present. */
+    position: number;
+    /** The column's DEFAULT expression, absent when it declares none. */
+    default_expression?: string;
 }
 interface TableSchema {
     name: string;
@@ -298,17 +313,24 @@ interface ParamDef {
 }
 interface Policy {
     default_role?: string;
+    admin_role?: string;
     tables: Record<string, TablePolicy>;
 }
-interface TablePolicy {
-    select?: Record<string, RolePermissions>;
-    insert?: Record<string, RolePermissions>;
-}
+/**
+ * Access control for one table, keyed by role name. A role appears once per
+ * table and states what it may do; omit `select` to deny reads, omit `insert`
+ * to deny writes.
+ */
+type TablePolicy = Record<string, RolePermissions>;
 interface RolePermissions {
+    select?: SelectPermissions;
+    insert?: InsertPermissions;
+}
+/** A role's read grant on a table. */
+interface SelectPermissions {
     allow_columns?: string[];
     deny_columns?: string[];
     filter?: Record<string, PolicyFilter>;
-    check?: Record<string, PolicyFilter>;
     allowed_aggregations?: string[];
     denied_aggregations?: string[];
     /** Caps the query result LIMIT. 0 = no limit. */
@@ -328,6 +350,12 @@ interface RolePermissions {
      */
     max_memory_usage?: number | string;
 }
+/** A role's write grant on a table. */
+interface InsertPermissions {
+    allow_columns?: string[];
+    deny_columns?: string[];
+    check?: Record<string, PolicyFilter>;
+}
 interface PolicyFilter {
     _eq?: string;
     _neq?: string;
@@ -335,8 +363,31 @@ interface PolicyFilter {
     _lt?: string;
     _in?: string;
 }
-interface ValidationResult {
-    valid: boolean;
+/** One validation finding from the server's settings directory. */
+interface SettingsFinding {
+    severity: "error" | "warning";
+    /**
+     * Settings file the finding is about; absent for directory-level findings.
+     * In a directory of tenant folders it leads with the folder
+     * (`acme/policies.json`).
+     */
+    file?: string;
+    /** Dotted JSON path within the file; absent for whole-file findings. */
+    path?: string;
+    message: string;
+}
+/** Body of POST /v1/ops/settings/reload. */
+interface SettingsReloadResult {
+    /**
+     * Whether everything the reload covered was adopted; false leaves the
+     * previous settings in effect. Over a directory of tenant folders false can
+     * mean adopted in part: the tenants with an error among their `findings`
+     * were not adopted and are no longer served, and the rest were — `findings`
+     * carries every folder's warnings too.
+     */
+    adopted: boolean;
+    /** Every finding from the validation pass (warnings included on success). */
+    findings: SettingsFinding[];
 }
 /**
  * Options for a single call, passed to `.fetch()`.
@@ -364,6 +415,24 @@ interface PipeRequestOptions {
     /** Not supported on pipes — pass `limit` as a pipe parameter instead. */
     limit?: never;
 }
+/**
+ * Options for a call to one of the admin routes that address a tenant:
+ * `wh.pipes.list()`, `wh.pipes.get()`, `wh.settings.reload()`,
+ * `wh.schema.list()`, `wh.schema.refresh()`, `wh.from(t).schema()`,
+ * `wh.dlq.list()`, `wh.dlq.table()` and `wh.sql()`.
+ */
+interface OpsRequestOptions {
+    signal?: AbortSignal;
+    /**
+     * The tenant the call addresses, sent as `?tenant=`. The admin routes ignore
+     * the `X-Tenant-ID` header, so `options.headers` cannot select one. Omitted,
+     * the reads, the refresh and `sql()` serve the default tenant (`0`) and
+     * `reload()` reloads every tenant. An id the server does not accept — the
+     * empty string included — is a `400`, never a silent fallback to the
+     * default.
+     */
+    tenant?: string;
+}
 interface StreamOptions {
     since?: string;
     signal?: AbortSignal;
@@ -433,14 +502,13 @@ declare class DLQNamespace {
     private readonly _ctx;
     private readonly _createStream;
     constructor(ctx: HttpContext, createStream: CreateStreamFn$3);
-    /** Get DLQ statistics (message counts per table). */
-    list(opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<DLQStats>>;
-    /** Get DLQ stats filtered by table name. */
-    table(name: string, opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<DLQStats>>;
+    /**
+     * Get DLQ statistics (message counts per table) — of `opts.tenant`, the
+     * default tenant without it. A tenant with no dead-letter queue is a `404`.
+     */
+    list(opts?: OpsRequestOptions): Promise<Result<DLQStats>>;
+    /** Get DLQ stats filtered by table name — of `opts.tenant`, the default tenant without it. */
+    table(name: string, opts?: OpsRequestOptions): Promise<Result<DLQStats>>;
     /** Subscribe to live DLQ events. */
     stream(opts?: StreamOptions): StreamController;
 }
@@ -466,58 +534,63 @@ declare class PipeRef<Row = Record<string, unknown>> implements PromiseLike<Resu
     stream(opts?: StreamOptions): StreamController<Row>;
     then<TResult1 = Result<Row[]>, TResult2 = never>(onfulfilled?: ((value: Result<Row[]>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
 }
-/** Admin namespace for managing named query pipes. */
+/**
+ * Admin namespace for reading named query pipes.
+ *
+ * Pipes are defined in the server's settings directory (`pipes.json`, with
+ * every `allowed_roles` entry declared in `roles.json`); the files are the only
+ * way to define or change a pipe. Edit the files and the server re-adopts them on change, on
+ * SIGHUP, or on `wh.settings.reload()` (POST /v1/ops/settings/reload).
+ */
 declare class PipesNamespace {
     private readonly _ctx;
     constructor(ctx: HttpContext);
-    /** List all registered pipes. */
-    list(opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<Pipe[]>>;
-    /** Get a single pipe definition by name. */
-    get(name: string, opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<Pipe>>;
-    /** Create or update a pipe. */
-    set(name: string, def: Omit<Pipe, "name">, opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<void>>;
-    /** Delete a pipe by name. */
-    delete(name: string, opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<void>>;
+    /** List all registered pipes — of `opts.tenant`, the default tenant without it. */
+    list(opts?: OpsRequestOptions): Promise<Result<Pipe[]>>;
+    /** Get a single pipe definition by name — of `opts.tenant`, the default tenant without it. */
+    get(name: string, opts?: OpsRequestOptions): Promise<Result<Pipe>>;
 }
 
-/** Namespace for access control policy management. Requires the admin role (the configured `admin_role`, `"admin"` by default). */
-declare class PolicyNamespace {
+/** Namespace for schema introspection. */
+declare class SchemaNamespace {
     private readonly _ctx;
     constructor(ctx: HttpContext);
-    /** Get the current access control policy. */
-    get(opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<Policy>>;
-    /** Replace the entire access control policy. */
-    set(policy: Policy, opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<void>>;
-    /** Validate a policy without applying it (dry run). */
-    validate(policy: Policy, opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<ValidationResult>>;
+    /**
+     * List all table schemas discovered from ClickHouse — `opts.tenant`'s, the
+     * default tenant's without it. A `503` with `Retry-After` is a tenant whose
+     * first discovery has not succeeded yet.
+     */
+    list(opts?: OpsRequestOptions): Promise<Result<Schemas>>;
+    /**
+     * Force a schema refresh from ClickHouse system.columns — of `opts.tenant`,
+     * the default tenant without it.
+     */
+    refresh(opts?: OpsRequestOptions): Promise<Result<void>>;
 }
 
-/** Namespace for schema introspection. */
-declare class SchemaNamespace {
+/**
+ * Namespace for the server's hot-reloadable settings directory. Requires the
+ * admin role (the configured `admin_role`, `"admin"` by default).
+ *
+ * Policy (`policies.json`), roles (`roles.json`), and pipes (`pipes.json`)
+ * are defined in that directory; files are the only write path. The server
+ * re-adopts them on file change and on SIGHUP, and `reload()` triggers the
+ * same path on demand.
+ */
+declare class SettingsNamespace {
     private readonly _ctx;
     constructor(ctx: HttpContext);
-    /** List all table schemas discovered from ClickHouse. */
-    list(opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<Schemas>>;
-    /** Force a schema refresh from ClickHouse system.columns. */
-    refresh(opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<void>>;
+    /**
+     * Re-validate and adopt the settings directory (POST /v1/ops/settings/reload).
+     * Resolves with `{ adopted: true, findings }` when adopted (warnings
+     * included); a rejected directory is a 422 error whose `details` carries the
+     * same `{ adopted: false, findings }` body, and the previous settings stay
+     * in effect.
+     *
+     * `opts.tenant` reloads that tenant's folder alone; without it the whole
+     * directory is reloaded.
+     */
+    reload(opts?: OpsRequestOptions): Promise<Result<SettingsReloadResult>>;
 }
 
 /** Namespace for the SDK's content-free server-online check. */
@@ -662,8 +735,10 @@ declare class TableRef<Row = Record<string, unknown>> {
      * rest of the batch — per-record outcomes come back in the result
      * (`failed` / `results`), and `ok` is true only when every record succeeded.
      *
-     * The array path sends one request regardless of size; bounded-concurrency
-     * chunking of very large arrays is tracked separately (#196). For NDJSON you
+     * The array path sends one request regardless of size, so it is bound by the
+     * server's 16 MiB request-body cap (an over-cap array is a `413` with nothing
+     * ingested); bounded-concurrency chunking of very large arrays is tracked
+     * separately (#196). For NDJSON you
      * already have (a file or stream), use {@link insertNDJSON}.
      */
     insert(data: Partial<Row> | Partial<Row>[], opts?: {
@@ -675,9 +750,11 @@ declare class TableRef<Row = Record<string, unknown>> {
      * file or a stream produced by another system. For in-memory rows, prefer
      * {@link insert}.
      *
-     * Non-string sources are read fully into memory before sending (the server
-     * streams the parse). Returns the same per-record batch summary as an array
-     * `insert`.
+     * Non-string sources are read fully into memory before sending. The server
+     * buffers the whole body too, so the request-body cap applies to NDJSON
+     * exactly as to any other shape — an upload over it is a `413` with nothing
+     * ingested, and must be split across several calls. Returns the same
+     * per-record batch summary as an array `insert`.
      */
     insertNDJSON(source: NDJSONSource, opts?: {
         signal?: AbortSignal;
@@ -689,10 +766,8 @@ declare class TableRef<Row = Record<string, unknown>> {
      * as the success arm with `ok = failed === 0`.
      */
     private _sendNDJSON;
-    /** Fetch the schema for this table. */
-    schema(opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<TableSchema>>;
+    /** Fetch the schema for this table — under `opts.tenant`, the default tenant without it. */
+    schema(opts?: OpsRequestOptions): Promise<Result<TableSchema>>;
     /** Subscribe to live events for this table. */
     stream(opts?: StreamOptions): StreamController<Row>;
 }
@@ -704,14 +779,14 @@ declare class WaveHouseClient<DB extends Database = Database> {
     readonly _ctx: HttpContext;
     /** Schema introspection namespace. */
     readonly schema: SchemaNamespace;
-    /** Access control policy namespace (admin). */
-    readonly policy: PolicyNamespace;
     /** Dead Letter Queue namespace. */
     readonly dlq: DLQNamespace;
     /** System health/readiness namespace. */
     readonly sys: SysNamespace;
     /** Named query pipes admin namespace. */
     readonly pipes: PipesNamespace;
+    /** Settings directory namespace (admin). */
+    readonly settings: SettingsNamespace;
     constructor(config: ClientConfig<DB>);
     /** Get a table reference for building queries, inserts, and streams. */
     from<T extends TableName<DB>>(table: T): TableRef<RowType<DB, T>>;
@@ -723,15 +798,15 @@ declare class WaveHouseClient<DB extends Database = Database> {
      * `service` role). The endpoint proxies straight to ClickHouse's HTTP
      * interface so any ClickHouse-accepted SQL works; positional `?` param
      * binding is NOT supported — inline literals or use the structured query
-     * builder for safe binding. See sql.ts for details.
+     * builder for safe binding. See sql.ts for details. `opts.tenant` names the
+     * tenant whose ClickHouse the SQL runs against, the default tenant without
+     * it.
      */
-    sql<Row = Record<string, unknown>>(query: string, opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<Row[]>>;
+    sql<Row = Record<string, unknown>>(query: string, opts?: OpsRequestOptions): Promise<Result<Row[]>>;
     /** @internal Create a stream for the given table. */
     private _createStream;
 }
 /** Create a new WaveHouse client instance. */
 declare function createClient<DB extends Database = Database>(config: ClientConfig<DB>): WaveHouseClient<DB>;
 
-export { type Aggregation, type ClientConfig, type ClientOptions, type Column, DLQNamespace, type DLQStats, type Database, type FetchLike, type FilterOp, type InsertRecordResult, type InsertResult, LiveQuery, type NDJSONSource, type OrderClause, type ParamDef, type Pipe, PipeRef, type PipeRequestOptions, PipesNamespace, type Policy, type PolicyFilter, PolicyNamespace, QueryBuilder, type QueryFilter, type RequestOptions, type Result, type RolePermissions, SchemaNamespace, type Schemas, StreamController, type StreamEvent, type StreamOptions, type StreamStatus, type StreamSubscriber, type StructuredQuery, SysNamespace, type TablePolicy, TableRef, type TableSchema, type TimeRange, type ValidationResult, WaveHouseClient, type WaveHouseError, createClient };
+export { type Aggregation, type ClientConfig, type ClientOptions, type Column, DLQNamespace, type DLQStats, type Database, type FetchLike, type FilterOp, type InsertPermissions, type InsertRecordResult, type InsertResult, LiveQuery, type NDJSONSource, type OpsRequestOptions, type OrderClause, type ParamDef, type Pipe, PipeRef, type PipeRequestOptions, PipesNamespace, type Policy, type PolicyFilter, QueryBuilder, type QueryFilter, type RequestOptions, type Result, type RolePermissions, SchemaNamespace, type Schemas, type SelectPermissions, type SettingsFinding, SettingsNamespace, type SettingsReloadResult, StreamController, type StreamEvent, type StreamOptions, type StreamStatus, type StreamSubscriber, type StructuredQuery, SysNamespace, type TablePolicy, TableRef, type TableSchema, type TimeRange, WaveHouseClient, type WaveHouseError, createClient };

package/dist/index.d.ts

@@ -241,7 +241,22 @@ interface Column {
     name: string;
     type: string;
     is_nullable: boolean;
+    /** Whether the column declares any default at all — see `default_kind`. */
     has_default: boolean;
+    /**
+     * How the default is declared, when there is one: `DEFAULT`, `MATERIALIZED`,
+     * `ALIAS` or `EPHEMERAL`. Omitted when the column declares none.
+     *
+     * `MATERIALIZED` and `ALIAS` columns are computed by ClickHouse and cannot be
+     * inserted — a record naming one is rejected — so they never appear in an
+     * ingest envelope or an SSE `schema` frame, though they are still reported
+     * here and are still queryable.
+     */
+    default_kind?: string;
+    /** 1-based ordinal in the table's declaration order — the order `columns` itself is in. Always present. */
+    position: number;
+    /** The column's DEFAULT expression, absent when it declares none. */
+    default_expression?: string;
 }
 interface TableSchema {
     name: string;
@@ -298,17 +313,24 @@ interface ParamDef {
 }
 interface Policy {
     default_role?: string;
+    admin_role?: string;
     tables: Record<string, TablePolicy>;
 }
-interface TablePolicy {
-    select?: Record<string, RolePermissions>;
-    insert?: Record<string, RolePermissions>;
-}
+/**
+ * Access control for one table, keyed by role name. A role appears once per
+ * table and states what it may do; omit `select` to deny reads, omit `insert`
+ * to deny writes.
+ */
+type TablePolicy = Record<string, RolePermissions>;
 interface RolePermissions {
+    select?: SelectPermissions;
+    insert?: InsertPermissions;
+}
+/** A role's read grant on a table. */
+interface SelectPermissions {
     allow_columns?: string[];
     deny_columns?: string[];
     filter?: Record<string, PolicyFilter>;
-    check?: Record<string, PolicyFilter>;
     allowed_aggregations?: string[];
     denied_aggregations?: string[];
     /** Caps the query result LIMIT. 0 = no limit. */
@@ -328,6 +350,12 @@ interface RolePermissions {
      */
     max_memory_usage?: number | string;
 }
+/** A role's write grant on a table. */
+interface InsertPermissions {
+    allow_columns?: string[];
+    deny_columns?: string[];
+    check?: Record<string, PolicyFilter>;
+}
 interface PolicyFilter {
     _eq?: string;
     _neq?: string;
@@ -335,8 +363,31 @@ interface PolicyFilter {
     _lt?: string;
     _in?: string;
 }
-interface ValidationResult {
-    valid: boolean;
+/** One validation finding from the server's settings directory. */
+interface SettingsFinding {
+    severity: "error" | "warning";
+    /**
+     * Settings file the finding is about; absent for directory-level findings.
+     * In a directory of tenant folders it leads with the folder
+     * (`acme/policies.json`).
+     */
+    file?: string;
+    /** Dotted JSON path within the file; absent for whole-file findings. */
+    path?: string;
+    message: string;
+}
+/** Body of POST /v1/ops/settings/reload. */
+interface SettingsReloadResult {
+    /**
+     * Whether everything the reload covered was adopted; false leaves the
+     * previous settings in effect. Over a directory of tenant folders false can
+     * mean adopted in part: the tenants with an error among their `findings`
+     * were not adopted and are no longer served, and the rest were — `findings`
+     * carries every folder's warnings too.
+     */
+    adopted: boolean;
+    /** Every finding from the validation pass (warnings included on success). */
+    findings: SettingsFinding[];
 }
 /**
  * Options for a single call, passed to `.fetch()`.
@@ -364,6 +415,24 @@ interface PipeRequestOptions {
     /** Not supported on pipes — pass `limit` as a pipe parameter instead. */
     limit?: never;
 }
+/**
+ * Options for a call to one of the admin routes that address a tenant:
+ * `wh.pipes.list()`, `wh.pipes.get()`, `wh.settings.reload()`,
+ * `wh.schema.list()`, `wh.schema.refresh()`, `wh.from(t).schema()`,
+ * `wh.dlq.list()`, `wh.dlq.table()` and `wh.sql()`.
+ */
+interface OpsRequestOptions {
+    signal?: AbortSignal;
+    /**
+     * The tenant the call addresses, sent as `?tenant=`. The admin routes ignore
+     * the `X-Tenant-ID` header, so `options.headers` cannot select one. Omitted,
+     * the reads, the refresh and `sql()` serve the default tenant (`0`) and
+     * `reload()` reloads every tenant. An id the server does not accept — the
+     * empty string included — is a `400`, never a silent fallback to the
+     * default.
+     */
+    tenant?: string;
+}
 interface StreamOptions {
     since?: string;
     signal?: AbortSignal;
@@ -433,14 +502,13 @@ declare class DLQNamespace {
     private readonly _ctx;
     private readonly _createStream;
     constructor(ctx: HttpContext, createStream: CreateStreamFn$3);
-    /** Get DLQ statistics (message counts per table). */
-    list(opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<DLQStats>>;
-    /** Get DLQ stats filtered by table name. */
-    table(name: string, opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<DLQStats>>;
+    /**
+     * Get DLQ statistics (message counts per table) — of `opts.tenant`, the
+     * default tenant without it. A tenant with no dead-letter queue is a `404`.
+     */
+    list(opts?: OpsRequestOptions): Promise<Result<DLQStats>>;
+    /** Get DLQ stats filtered by table name — of `opts.tenant`, the default tenant without it. */
+    table(name: string, opts?: OpsRequestOptions): Promise<Result<DLQStats>>;
     /** Subscribe to live DLQ events. */
     stream(opts?: StreamOptions): StreamController;
 }
@@ -466,58 +534,63 @@ declare class PipeRef<Row = Record<string, unknown>> implements PromiseLike<Resu
     stream(opts?: StreamOptions): StreamController<Row>;
     then<TResult1 = Result<Row[]>, TResult2 = never>(onfulfilled?: ((value: Result<Row[]>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
 }
-/** Admin namespace for managing named query pipes. */
+/**
+ * Admin namespace for reading named query pipes.
+ *
+ * Pipes are defined in the server's settings directory (`pipes.json`, with
+ * every `allowed_roles` entry declared in `roles.json`); the files are the only
+ * way to define or change a pipe. Edit the files and the server re-adopts them on change, on
+ * SIGHUP, or on `wh.settings.reload()` (POST /v1/ops/settings/reload).
+ */
 declare class PipesNamespace {
     private readonly _ctx;
     constructor(ctx: HttpContext);
-    /** List all registered pipes. */
-    list(opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<Pipe[]>>;
-    /** Get a single pipe definition by name. */
-    get(name: string, opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<Pipe>>;
-    /** Create or update a pipe. */
-    set(name: string, def: Omit<Pipe, "name">, opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<void>>;
-    /** Delete a pipe by name. */
-    delete(name: string, opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<void>>;
+    /** List all registered pipes — of `opts.tenant`, the default tenant without it. */
+    list(opts?: OpsRequestOptions): Promise<Result<Pipe[]>>;
+    /** Get a single pipe definition by name — of `opts.tenant`, the default tenant without it. */
+    get(name: string, opts?: OpsRequestOptions): Promise<Result<Pipe>>;
 }
 
-/** Namespace for access control policy management. Requires the admin role (the configured `admin_role`, `"admin"` by default). */
-declare class PolicyNamespace {
+/** Namespace for schema introspection. */
+declare class SchemaNamespace {
     private readonly _ctx;
     constructor(ctx: HttpContext);
-    /** Get the current access control policy. */
-    get(opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<Policy>>;
-    /** Replace the entire access control policy. */
-    set(policy: Policy, opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<void>>;
-    /** Validate a policy without applying it (dry run). */
-    validate(policy: Policy, opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<ValidationResult>>;
+    /**
+     * List all table schemas discovered from ClickHouse — `opts.tenant`'s, the
+     * default tenant's without it. A `503` with `Retry-After` is a tenant whose
+     * first discovery has not succeeded yet.
+     */
+    list(opts?: OpsRequestOptions): Promise<Result<Schemas>>;
+    /**
+     * Force a schema refresh from ClickHouse system.columns — of `opts.tenant`,
+     * the default tenant without it.
+     */
+    refresh(opts?: OpsRequestOptions): Promise<Result<void>>;
 }
 
-/** Namespace for schema introspection. */
-declare class SchemaNamespace {
+/**
+ * Namespace for the server's hot-reloadable settings directory. Requires the
+ * admin role (the configured `admin_role`, `"admin"` by default).
+ *
+ * Policy (`policies.json`), roles (`roles.json`), and pipes (`pipes.json`)
+ * are defined in that directory; files are the only write path. The server
+ * re-adopts them on file change and on SIGHUP, and `reload()` triggers the
+ * same path on demand.
+ */
+declare class SettingsNamespace {
     private readonly _ctx;
     constructor(ctx: HttpContext);
-    /** List all table schemas discovered from ClickHouse. */
-    list(opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<Schemas>>;
-    /** Force a schema refresh from ClickHouse system.columns. */
-    refresh(opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<void>>;
+    /**
+     * Re-validate and adopt the settings directory (POST /v1/ops/settings/reload).
+     * Resolves with `{ adopted: true, findings }` when adopted (warnings
+     * included); a rejected directory is a 422 error whose `details` carries the
+     * same `{ adopted: false, findings }` body, and the previous settings stay
+     * in effect.
+     *
+     * `opts.tenant` reloads that tenant's folder alone; without it the whole
+     * directory is reloaded.
+     */
+    reload(opts?: OpsRequestOptions): Promise<Result<SettingsReloadResult>>;
 }
 
 /** Namespace for the SDK's content-free server-online check. */
@@ -662,8 +735,10 @@ declare class TableRef<Row = Record<string, unknown>> {
      * rest of the batch — per-record outcomes come back in the result
      * (`failed` / `results`), and `ok` is true only when every record succeeded.
      *
-     * The array path sends one request regardless of size; bounded-concurrency
-     * chunking of very large arrays is tracked separately (#196). For NDJSON you
+     * The array path sends one request regardless of size, so it is bound by the
+     * server's 16 MiB request-body cap (an over-cap array is a `413` with nothing
+     * ingested); bounded-concurrency chunking of very large arrays is tracked
+     * separately (#196). For NDJSON you
      * already have (a file or stream), use {@link insertNDJSON}.
      */
     insert(data: Partial<Row> | Partial<Row>[], opts?: {
@@ -675,9 +750,11 @@ declare class TableRef<Row = Record<string, unknown>> {
      * file or a stream produced by another system. For in-memory rows, prefer
      * {@link insert}.
      *
-     * Non-string sources are read fully into memory before sending (the server
-     * streams the parse). Returns the same per-record batch summary as an array
-     * `insert`.
+     * Non-string sources are read fully into memory before sending. The server
+     * buffers the whole body too, so the request-body cap applies to NDJSON
+     * exactly as to any other shape — an upload over it is a `413` with nothing
+     * ingested, and must be split across several calls. Returns the same
+     * per-record batch summary as an array `insert`.
      */
     insertNDJSON(source: NDJSONSource, opts?: {
         signal?: AbortSignal;
@@ -689,10 +766,8 @@ declare class TableRef<Row = Record<string, unknown>> {
      * as the success arm with `ok = failed === 0`.
      */
     private _sendNDJSON;
-    /** Fetch the schema for this table. */
-    schema(opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<TableSchema>>;
+    /** Fetch the schema for this table — under `opts.tenant`, the default tenant without it. */
+    schema(opts?: OpsRequestOptions): Promise<Result<TableSchema>>;
     /** Subscribe to live events for this table. */
     stream(opts?: StreamOptions): StreamController<Row>;
 }
@@ -704,14 +779,14 @@ declare class WaveHouseClient<DB extends Database = Database> {
     readonly _ctx: HttpContext;
     /** Schema introspection namespace. */
     readonly schema: SchemaNamespace;
-    /** Access control policy namespace (admin). */
-    readonly policy: PolicyNamespace;
     /** Dead Letter Queue namespace. */
     readonly dlq: DLQNamespace;
     /** System health/readiness namespace. */
     readonly sys: SysNamespace;
     /** Named query pipes admin namespace. */
     readonly pipes: PipesNamespace;
+    /** Settings directory namespace (admin). */
+    readonly settings: SettingsNamespace;
     constructor(config: ClientConfig<DB>);
     /** Get a table reference for building queries, inserts, and streams. */
     from<T extends TableName<DB>>(table: T): TableRef<RowType<DB, T>>;
@@ -723,15 +798,15 @@ declare class WaveHouseClient<DB extends Database = Database> {
      * `service` role). The endpoint proxies straight to ClickHouse's HTTP
      * interface so any ClickHouse-accepted SQL works; positional `?` param
      * binding is NOT supported — inline literals or use the structured query
-     * builder for safe binding. See sql.ts for details.
+     * builder for safe binding. See sql.ts for details. `opts.tenant` names the
+     * tenant whose ClickHouse the SQL runs against, the default tenant without
+     * it.
      */
-    sql<Row = Record<string, unknown>>(query: string, opts?: {
-        signal?: AbortSignal;
-    }): Promise<Result<Row[]>>;
+    sql<Row = Record<string, unknown>>(query: string, opts?: OpsRequestOptions): Promise<Result<Row[]>>;
     /** @internal Create a stream for the given table. */
     private _createStream;
 }
 /** Create a new WaveHouse client instance. */
 declare function createClient<DB extends Database = Database>(config: ClientConfig<DB>): WaveHouseClient<DB>;
 
-export { type Aggregation, type ClientConfig, type ClientOptions, type Column, DLQNamespace, type DLQStats, type Database, type FetchLike, type FilterOp, type InsertRecordResult, type InsertResult, LiveQuery, type NDJSONSource, type OrderClause, type ParamDef, type Pipe, PipeRef, type PipeRequestOptions, PipesNamespace, type Policy, type PolicyFilter, PolicyNamespace, QueryBuilder, type QueryFilter, type RequestOptions, type Result, type RolePermissions, SchemaNamespace, type Schemas, StreamController, type StreamEvent, type StreamOptions, type StreamStatus, type StreamSubscriber, type StructuredQuery, SysNamespace, type TablePolicy, TableRef, type TableSchema, type TimeRange, type ValidationResult, WaveHouseClient, type WaveHouseError, createClient };
+export { type Aggregation, type ClientConfig, type ClientOptions, type Column, DLQNamespace, type DLQStats, type Database, type FetchLike, type FilterOp, type InsertPermissions, type InsertRecordResult, type InsertResult, LiveQuery, type NDJSONSource, type OpsRequestOptions, type OrderClause, type ParamDef, type Pipe, PipeRef, type PipeRequestOptions, PipesNamespace, type Policy, type PolicyFilter, QueryBuilder, type QueryFilter, type RequestOptions, type Result, type RolePermissions, SchemaNamespace, type Schemas, type SelectPermissions, type SettingsFinding, SettingsNamespace, type SettingsReloadResult, StreamController, type StreamEvent, type StreamOptions, type StreamStatus, type StreamSubscriber, type StructuredQuery, SysNamespace, type TablePolicy, TableRef, type TableSchema, type TimeRange, WaveHouseClient, type WaveHouseError, createClient };