@wavehouse/chtypes 0.5.2 → 1.0.2

package/dist/schema.js

@@ -1,571 +1,109 @@
 /**
- * A compiled schema — one tenant table's column list, compiled inside one
- * version's library, plus the engine and TTL declarations that make `rows()`
- * answer with the storage layer's verdict as well as the type layer's.
- */
-import { ChtypesError } from './errors.js';
-import { DOC_ALL, EXPORT_NONE } from './format.js';
-import { parseDocument } from './json.js';
-import { batchResultOf, filterResultOf, rowResultOf, } from './results.js';
-import { encodeSettings } from './settings.js';
-const schemaFinalizer = new FinalizationRegistry((n) => {
-    if (n.handle === null)
-        return; // closed explicitly already
-    for (const h of n.openFilters)
-        n.native.filterFree(h);
-    n.openFilters.clear();
-    for (const h of n.openBlocks)
-        n.native.blockFree(h);
-    n.openBlocks.clear();
-    n.native.schemaFree(n.handle);
-    n.handle = null;
-});
-const filterFinalizer = new FinalizationRegistry((n) => {
-    if (n.handle === null)
-        return;
-    if (n.schema.openFilters.delete(n.handle))
-        n.native.filterFree(n.handle);
-    n.handle = null;
-});
-const blockFinalizer = new FinalizationRegistry((n) => {
-    if (n.handle === null)
-        return;
-    if (n.schema.openBlocks.delete(n.handle))
-        n.native.blockFree(n.handle);
-    n.handle = null;
-});
-/**
- * A compiled schema — one tenant table's column list, compiled inside one
- * version's library. Obtained from `Library#compileDdl`; never constructed
- * directly. Release with `close()` (idempotent) or `using` / `Symbol.dispose`
- * — `close()` stays the primary path; a GC finalizer that calls it for a
- * schema nobody closed is a backstop, not a replacement, since there is no
- * promise about WHEN (or, in principle, whether) it runs.
+ * `Schema`, `Filter` and `Block`: the compiled objects of `docs/reference/bindings-v1.md` §2.
  *
- * Thread-safety: the C ABI forbids using one `chs_schema *` from two threads
- * at once; on a single JS thread every call here is synchronous, so ordinary
- * Node code satisfies that by construction. Do not share a `Schema` across
- * `worker_threads`.
- */
-export class Schema {
-    native;
-    ddl;
-    /**
-     * The declared columns as ClickHouse canonicalized them, in declaration
-     * order — flattened under `flatten_nested=1`, DEFAULT-rewritten types
-     * (`x Int64 DEFAULT NULL` compiles as `Nullable(Int64)`), ALIAS types
-     * inferred. A gateway detects EPHEMERAL columns here, at compile time
-     * (`defaultKind === 'EPHEMERAL'`), not per row.
-     */
-    columns;
-    /** The handle plus the GC-finalizer coordination state; see `SchemaNative`. */
-    n;
-    /**
-     * Every open `Filter` compiled from this handle, so `close()` can free them
-     * FIRST — the C layer does not refcount, and freeing the schema under a
-     * live filter is use-after-free (the C ABI contract §Filters, handle lifetime).
-     */
-    filters = new Set();
-    /**
-     * Every open `Block` parsed from this handle — the same non-owning rule,
-     * the same free-before-schema order (the C ABI contract §Blocks).
-     */
-    blocks = new Set();
-    /** @internal — obtained from `Library#compileDdl`. */
-    constructor(native, handle, 
-    /** The column-declaration list this schema was compiled from, verbatim. */
-    ddl) {
-        this.native = native;
-        this.ddl = ddl;
-        this.n = { native, handle, openFilters: new Set(), openBlocks: new Set() };
-        this.columns = native.columns(handle);
-        schemaFinalizer.register(this, this.n, this);
-    }
-    live() {
-        if (this.n.handle === null)
-            throw new ChtypesError('chtypes: schema is closed');
-        return this.n.handle;
-    }
-    /**
-     * Declare the table engine, so `rows()` applies the engine's own insert-time
-     * merge (`optimize_on_insert = 1`): a CollapsingMergeTree refusing an invalid
-     * Sign with code 117 before anything is stored, a SummingMergeTree summing
-     * equal keys and dropping all-zero rows, a ReplacingMergeTree deduplicating.
-     *
-     * `options.mergeTreeSettings` declares the table's MergeTree-namespace
-     * settings — see `EngineOptions` for the error contract (unknown name ⇒ the
-     * server's 115; non-default declared value ⇒ `unsupported`, never silently
-     * ignored). Absent/empty is structurally the plain engine declaration:
-     * `chs_schema_engine` takes "{}" either way.
-     *
-     * The two error classes here are the refusal/decline split and MUST be
-     * handled as peers — `UnsupportedError` is deliberately NOT
-     * `instanceof SchemaError` (docs/reference/bindings.md rule 12):
-     *
-     * @param engine - the engine expression, e.g. `"SummingMergeTree"`,
-     *   `"CollapsingMergeTree(sign)"`.
-     * @param orderBy - the sorting key, e.g. `"(day, key)"`.
-     * @param options - the MergeTree-namespace `SETTINGS` clause, if any.
-     * @throws {SchemaError} when the SERVER refused (positive code): this DDL
-     *   can never exist and the tenant has to be told. Today that is 115, an
-     *   unknown MergeTree setting name, with the server's own message verbatim.
-     * @throws {UnsupportedError} when this LIBRARY declined: an engine or
-     *   sorting key this build does not model, a known MergeTree setting
-     *   declared at a non-default value, or a guarded exception. A real server
-     *   might well have accepted it — validate cautiously, fall back to the
-     *   server, and never present the decline as a rejection.
-     */
-    setEngine(engine, orderBy, options) {
-        this.native.schemaEngine(this.live(), engine, orderBy, encodeSettings(options?.mergeTreeSettings));
-    }
-    /**
-     * Declare the table's rows TTL (`ts + INTERVAL 30 DAY`). An expired row is
-     * reported NOT STORED through the batch's `transformed` list.
-     *
-     * Column-level TTLs need no call: they are part of the declaration list.
-     *
-     * @param ttl - the rows-TTL expression, e.g. `"ts + INTERVAL 30 DAY"`. It is
-     *   validated under the handle's declared compile profile when one exists.
-     * @throws {UnsupportedError} for a TTL form this build refuses rather than
-     *   guesses: WHERE / GROUP BY TTLs, TO DISK/VOLUME moves, RECOMPRESS, any
-     *   clock-reading TTL expression, and guarded exceptions. Fall back to the
-     *   server; do not report a tenant error.
-     */
-    setTtl(ttl) {
-        this.native.schemaTtl(this.live(), ttl);
-    }
-    /**
-     * Declare the table's partition key — the `PARTITION BY` clause after the
-     * engine, e.g. `"toYYYYMM(ts)"` or `"(toDate(ts), tenant)"`
-     * (`chs_schema_partition_by`, revision 6). The key is built by the server's
-     * own CREATE-path call over this schema's columns, under the handle's
-     * compile profile. A second call REPLACES the first; `""` removes the
-     * declaration, and the schema then answers exactly as one that never
-     * declared a key.
-     *
-     * With a key declared, `row` and `rows` answer `RowResult#partitionId` for
-     * every row that would be stored and `BatchResult#partitionCount` for the
-     * batch, and a body that would split into more partitions than the call's
-     * `max_partitions_per_insert_block` allows is an ordinary `'rejected'` with
-     * `errCode` 252 (TOO_MANY_PARTS), the server's own — a verdict, never a
-     * throw.
-     *
-     * @param expr - the partition key expression, or `""` to remove it.
-     * @throws {SchemaError} when the server's own CREATE path refuses the key
-     *   (e.g. 36 BAD_ARGUMENTS for a non-deterministic key, 549
-     *   DATA_TYPE_CANNOT_BE_USED_IN_KEY) — `setEngine`'s SIGN rule, not
-     *   `setTtl`'s.
-     * @throws {UnsupportedError} when this build declines (-1, a guarded
-     *   exception), or the artifact predates `chs_schema_partition_by`. -2 is a
-     *   key the server accepts but this build will not evaluate; a
-     *   non-deterministic key is the server's own rejection, 36 BAD_ARGUMENTS.
-     */
-    setPartitionBy(expr) {
-        this.native.schemaPartitionBy(this.live(), expr);
-    }
-    /**
-     * Validate and coerce ONE row body, answering exactly as this ClickHouse
-     * version's insert path would.
-     *
-     * There is no exception for a bad row: rejection, poisoning and declines all
-     * arrive as the `RowResult`'s `outcome` (see `Outcome` for the taxonomy and
-     * the caller's obligations per arm).
-     *
-     * @param format - the wire format code (`Format`). Binary-format support
-     *   depends on the loaded artifact — probe, don't assume.
-     * @param raw - the row's bytes, exactly as they would arrive in an INSERT
-     *   body. Always bytes, never a JS string: binary formats contain NUL bytes
-     *   and text rows can carry invalid UTF-8 on purpose.
-     * @param settings - per-call settings; they win over the compile profile and
-     *   the library defaults (except a type gate the profile declared, which the
-     *   handle has already settled, as a real server's CREATE does).
-     * @param options - `RowOptions#columns` (revision 5), the INSERT column
-     *   list. `row()` takes `RowOptions`, not `RowsOptions`: the revision-3
-     *   export/doc-flag channels are meaningless on a single row, so this
-     *   method's options type simply does not offer them.
-     * @returns the `RowResult` — verdict, stored values, and every silent change.
-     * @throws {ChtypesError} when the schema is closed, or a settings value is a
-     *   JS `number`.
-     * @throws {UnsupportedError} when the artifact predates `chs_row`.
-     */
-    row(format, raw, settings, options) {
-        const doc = this.native.row(this.live(), format, raw, encodeSettings(settings), options?.columns);
-        return rowResultOf(parseDocument(doc));
-    }
-    /**
-     * Validate and coerce a whole request body, which may hold many rows.
-     *
-     * This is not `row()` in a loop and must never be implemented as one: row
-     * separation is format-specific (a quoted CSV field can contain a newline),
-     * `input_format_allow_errors_num` / `_ratio` decide whether a bad row is
-     * skipped or aborts the batch, and one batch is one clock instant for the
-     * volatile-DEFAULT guarantee.
-     *
-     * @param format - the wire format code (`Format`).
-     * @param body - the whole request body as bytes (never a JS string).
-     * @param settings - per-call settings; same precedence as `row`.
-     * @returns the `BatchResult`. When `engineRows` is present it — not `rows` —
-     *   is the stored truth, and batch-level storage transforms (`ttl_expired`,
-     *   `ttl_column_expired`) are folded into `transformed`.
-     * With `options.exportFormat` the same ONE call also serializes the batch's
-     * accepted rows through the vendored writer: `payload` carries the bytes
-     * (zero-length = emitted-empty, an accepted batch with zero accepted rows;
-     * `undefined` + `exportDeclined` = withheld, with the reason), and `spans`
-     * is index-aligned with `rows` — `payload.subarray(s.off, s.off + s.len)`
-     * IS row i's line. With `options.docFlags` the per-row documents are
-     * thinned to the selected groups; the verdict channel is never thinned.
-     * See `RowsOptions` for the defaults and `BatchResult` for the three
-     * payload states.
-     *
-     * @param format - the wire format code (`Format`).
-     * @param body - the whole request body as bytes (never a JS string).
-     * @param settings - per-call settings; same precedence as `row`.
-     * @param options - the revision-3 export/doc-flag channels, plus
-     *   `columns` (revision 5), the INSERT column list, and `rowFilter`
-     *   (revision 5, second half) — see `RowsOptions`; absent = today's full
-     *   document, byte-identical to revision 2, no list, byte-identical to
-     *   every revision before 5, and no filter, byte-identical byte for byte.
-     * @returns the `BatchResult`. When `engineRows` is present it — not `rows` —
-     *   is the stored truth, and batch-level storage transforms (`ttl_expired`,
-     *   `ttl_column_expired`) are folded into `transformed`. With
-     *   `options.rowFilter`, `rowsPassed`/`rowsCut` join the result and every
-     *   row carries its filter `verdict` beside its own `outcome`.
-     * @throws {ChtypesError} when the schema is closed, a settings value is a JS
-     *   `number`, the artifact predates `chs_rows` (a mandatory symbol), the
-     *   filter is closed, or the filter comes from a different loaded library.
-     */
-    rows(format, body, settings, options) {
-        const exportFormat = options?.exportFormat ?? EXPORT_NONE;
-        const docFlags = options?.docFlags ?? (options?.exportFormat === undefined ? DOC_ALL : 0);
-        const rowFilter = options?.rowFilter;
-        let filterHandle;
-        if (rowFilter !== undefined) {
-            if (rowFilter.nativeLib !== this.native) {
-                throw new ChtypesError('chtypes: filter and schema come from different libraries');
-            }
-            filterHandle = rowFilter.liveHandle();
-        }
-        const { doc, payload } = this.native.rows(this.live(), format, body, encodeSettings(settings), exportFormat, docFlags, options?.columns, filterHandle);
-        return batchResultOf(parseDocument(doc), payload);
-    }
-    /**
-     * Compile one boolean SQL expression over this schema's PHYSICAL columns
-     * (ordinary + MATERIALIZED; naming an ALIAS/EPHEMERAL column fails with
-     * ClickHouse's own UNKNOWN_IDENTIFIER, exactly where a real CREATE fails) —
-     * the same TreeRewriter + ExpressionAnalyzer pipeline the CONSTRAINT CHECK
-     * path runs, so comparison semantics are WHERE-side by construction:
-     * `x = 256` over UInt8 promotes (false for every row), it never wraps
-     * (the C ABI contract §Filters).
-     *
-     * The expression may contain `{name:Type}` query parameters, bound with
-     * `options.params` (revision 4) — substitution is the server's own
-     * `ReplaceQueryParameterVisitor`, run before analysis, exactly where a
-     * real server runs it; see `CompileFilterOptions` for the injection-safety
-     * and cache-discipline contract. Close the filter when done (`close()` /
-     * `Symbol.dispose`); `schema.close()` also closes every open filter FIRST,
-     * so no caller ordering can free the schema under a live filter.
-     *
-     * ENFORCEMENT GATE: nothing may enforce read-side security on this surface
-     * until the WHERE-truth rig gates green (zero over-admit, zero over-hide);
-     * until then it is a shadow/replay surface.
-     *
-     * @param expr - one boolean expression, e.g. `"x = 256"` or
-     *   `"tenant = {t:String}"`.
-     * @param options - the `{name:Type}` bindings, if any.
-     * @returns the compiled `Filter`.
-     * @throws {SchemaError} when ClickHouse itself refuses the expression —
-     *   unknown identifier (47), unknown function, an analyzer-raised
-     *   NO_COMMON_TYPE — and, since revision 4, the server's own parameter
-     *   refusals: an UNBOUND `{name:Type}` is **456** UNKNOWN_QUERY_PARAMETER
-     *   ("Substitution `name` is not set"), a value the declared type cannot
-     *   parse completely is **457** BAD_QUERY_PARAMETER — the server's own
-     *   code and message, verbatim. A bound name the expression never uses is
-     *   ignored, as a live server ignores an unused `param_*`.
-     * @throws {UnsupportedError} when this build declines: a non-deterministic
-     *   expression (clock reads — `now() > ts` —, `rand()`, server-constants;
-     *   the scan runs AFTER substitution, so a value can never smuggle one
-     *   in), or an artifact that predates the filter trio.
-     */
-    compileFilter(expr, options) {
-        const handle = this.native.filterCompile(this.live(), expr, encodeSettings(options?.params));
-        this.n.openFilters.add(handle);
-        const filter = new Filter(this.native, this, this.n, handle, expr);
-        this.filters.add(filter);
-        return filter;
-    }
-    /** @internal — `Filter#close` deregisters itself here. */
-    forgetFilter(filter) {
-        this.filters.delete(filter);
-    }
-    /**
-     * Parse a body ONCE into a `Block` (`chs_block_parse`) — the parse half of
-     * `Filter#rows`, exported so K filters can evaluate one event with no
-     * re-parse (`Filter#eval`; the C ABI contract §Blocks). Same formats and
-     * settings contract as `rows` (`settings` is the PARSE-side map: format
-     * settings, clock keys; evaluation takes none). Volatile DEFAULTs resolve
-     * against THIS call's clock instant, so
-     * `filter.eval(schema.parseBlock(...))` ≡ `filter.rows(...)` exactly when
-     * the clock is pinned (`chtypes_now_epoch_nanos`) or the schema has no
-     * volatile DEFAULT.
-     *
-     * Per-row parse failures do NOT throw — they are recorded IN the block and
-     * answer `'d'` from every filter, with the recorded error. Release
-     * with `close()` / `Symbol.dispose`; `schema.close()` closes open blocks
-     * FIRST, the C-required order.
-     *
-     * @param format - the wire format code (`Format`).
-     * @param body - the rows as bytes (never a JS string).
-     * @param settings - parse-side settings; same precedence as `Schema#rows`.
-     * @param options - `RowOptions#columns` (revision 5), the INSERT column
-     *   list read exactly as `Schema#row` reads it. `parseBlock()` takes
-     *   `RowOptions`, not `RowsOptions`: the revision-3 export/doc-flag
-     *   channels are meaningless here, so this method's options type simply
-     *   does not offer them. Filters compiled against this schema still
-     *   evaluate the schema's PHYSICAL columns, so a listed `EPHEMERAL`
-     *   column stays unreferenceable in a filter.
-     * @returns the parsed `Block`.
-     * @throws {SchemaError} on a call-level failure — an unknown setting's
-     *   115, an unsplittable body, a binary decode fault, the deferred
-     *   JSONEachRow framing verdict: a malformed body yields no block and no
-     *   partial answers.
-     * @throws {UnsupportedError} when this build declines the call, or the
-     *   artifact predates the block twin.
-     */
-    parseBlock(format, body, settings, options) {
-        const handle = this.native.blockParse(this.live(), format, body, encodeSettings(settings), options?.columns);
-        this.n.openBlocks.add(handle);
-        const block = new Block(this.native, this, this.n, handle);
-        this.blocks.add(block);
-        return block;
-    }
-    /** @internal — `Block#close` deregisters itself here. */
-    forgetBlock(block) {
-        this.blocks.delete(block);
-    }
-    /**
-     * Release the native schema. Idempotent. After it, `row` / `rows` /
-     * `setEngine` / `setTtl` / `setPartitionBy` throw `ChtypesError` ("schema
-     * is closed").
-     * Any `Filter` or `Block` still open on this schema is closed FIRST, in
-     * the same call — the handles-before-schema free order the C layer
-     * requires, enforced here so no dispose ordering can get it backwards.
-     */
-    close() {
-        for (const filter of this.filters)
-            filter.close();
-        this.filters.clear();
-        for (const block of this.blocks)
-            block.close();
-        this.blocks.clear();
-        if (this.n.handle === null)
-            return;
-        this.native.schemaFree(this.n.handle);
-        this.n.handle = null;
-        schemaFinalizer.unregister(this);
-    }
-    /** `using schema = lib.compileDdl(...)` releases it at scope exit. */
-    [Symbol.dispose]() {
-        this.close();
-    }
-}
-/**
- * One boolean SQL expression compiled against a `Schema`'s columns
- * (`chs_filter_compile`). Obtained from `Schema#compileFilter`; never
- * constructed directly.
- *
- * LIFETIME: a filter REFERENCES its schema handle — the C layer does not copy
- * and does not refcount (the C ABI contract §Filters). This binding enforces the
- * free order structurally, both ways: the `Filter` holds its `Schema` (so the
- * schema stays reachable), and `Schema#close` closes every open filter before
- * freeing the schema. `close()` is idempotent, and `using` / `Symbol.dispose`
- * work on both objects in any nesting — the schema's dispose runs the
- * filter's first when the caller forgot. A filter compiled from a schema
- * answers for THAT handle: recompile filters when the schema is recompiled.
- * A filter nobody closed is also backed by a GC finalizer, coordinated with
- * its schema's own (see `SchemaNative`) so the two can never free this
- * filter's handle out of order or twice, whichever one the GC happens to run
- * first.
+ * Every public call makes exactly one ABI call over the generated, typed
+ * layer, then decodes the document it returned (`./documents.ts`) and
+ * computes nothing. The per-call zone is the `session_timezone` key of the
+ * call's settings and nothing more (`./settings.ts`).
  *
- * THREADS: the header's rule, verbatim — one `chs_filter` "must not be used
- * from two threads at once, and a chs_filter call is ALSO a use of its schema
- * handle" (two filters over ONE schema must not run concurrently either). On
- * a single JS thread every call here is synchronous, so ordinary Node code
- * satisfies both by construction (docs/reference/bindings.md §Concurrency); do not
- * share a `Filter` — or its `Schema` — across `worker_threads`.
- *
- * ENFORCEMENT GATE: `'e'` and `'d'` verdicts are NOT answers — a
- * caller enforcing visibility MUST fail closed on both — and NO caller may
- * enforce read-side security on this surface until the WHERE-truth rig gates
- * green; until then it is a shadow/replay surface (the C ABI contract §Filters).
+ * Handles. Each object holds the generated layer's handle wrapper, whose
+ * `ptr` raises a `UsageError` naming the object once it is closed, before any
+ * C call. A filter or a block holds a counted reference to its schema inside
+ * the library, so a binding object neither holds its parent alive nor orders
+ * its frees: closing a schema while its filters are in use is legal, and
+ * `close` is idempotent. A `FinalizationRegistry` per handle class frees what
+ * the caller abandons. TypeScript runs every call synchronously on one
+ * thread, so the close guard of the other bindings reduces to this check: no
+ * call is ever in flight while `close` runs.
  */
+import { DocFlags, EXPORT_NONE } from './abi1/index.js';
+import { decodeBatch, decodeFilterResult, decodeRow, decodeSchemaDescription, } from './documents.js';
+import { bytesIn, encodeColumns, encodeParams, encodeSettings } from './settings.js';
+function bodyIn(body) {
+    if (typeof body === 'string')
+        throw new TypeError('chtypes: a body is bytes (a Uint8Array); it never accepts the text type');
+    return body;
+}
+const filterHandles = new WeakMap();
+/** A compiled `WHERE`-style expression bound to a schema. It holds its own zone, fixed at compile. */
 export class Filter {
-    native;
-    schema;
-    expr;
-    /** The handle plus the GC-finalizer coordination state; see `FilterNative`. */
-    n;
-    /** @internal — obtained from `Schema#compileFilter`. */
-    constructor(native, schema, schemaNative, handle, 
-    /** The expression text as compiled, for logging and cache keys. */
-    expr) {
-        this.native = native;
-        this.schema = schema;
-        this.expr = expr;
-        this.n = { native, schema: schemaNative, handle };
-        filterFinalizer.register(this, this.n, this);
-    }
-    /** @internal — the loaded library this filter's handle belongs to, for
-     * `Schema#rows(options.rowFilter)`'s cross-library check. */
-    get nativeLib() {
-        return this.native;
-    }
-    /** @internal — the live handle, for `Schema#rows(options.rowFilter)`. */
-    liveHandle() {
-        if (this.n.handle === null)
-            throw new ChtypesError('chtypes: filter is closed');
-        return this.n.handle;
-    }
-    /**
-     * Evaluate the filter over a body of rows (`chs_filter_rows`) — the same
-     * formats and settings contract as `Schema#rows`, ONE C call. Rows are
-     * evaluated INDEPENDENTLY (there is no INSERT to abort):
-     * `input_format_allow_errors_*` does not apply, a bad text row declines
-     * (`'d'`) and the tail resyncs so verdict indexes keep matching input
-     * rows, and volatile DEFAULTs resolve against one clock instant per call.
-     *
-     * @param format - the wire format code (`Format`).
-     * @param body - the rows as bytes (never a JS string).
-     * @param settings - per-call settings; same precedence as `Schema#rows`.
-     * @returns the `FilterResult` — the call-level outcome, and one verdict per
-     *   row when it is `'ok'`.
-     * @throws {ChtypesError} when the filter is closed, or a settings value is
-     *   a JS `number`.
-     */
-    rows(format, body, settings) {
-        if (this.n.handle === null)
-            throw new ChtypesError('chtypes: filter is closed');
-        const doc = this.native.filterRows(this.n.handle, format, body, encodeSettings(settings));
-        return filterResultOf(parseDocument(doc));
-    }
-    /**
-     * Evaluate this filter over an already-parsed `Block` (`chs_filter_eval`)
-     * — the SAME result document `rows` returns: same `FilterResult` fields,
-     * same verdicts, same `errors` rule (a row the parse recorded as
-     * unparseable answers `'d'` with the recorded error). Evaluation is
-     * a pure function of (filter, block): no settings, and the block is
-     * neither consumed nor mutated, so one block can be evaluated by K filters
-     * sequentially with no re-parse — the live-SSE call shape.
-     *
-     * Filter and block MUST come from the SAME schema: a mismatched pair
-     * answers a REJECTED result (code 1002) — the C layer's loud refusal,
-     * never undefined behavior. A pair from two different libraries throws
-     * `ChtypesError`: no handle ever crosses a dlopen'd image boundary.
-     *
-     * @param block - a `Block` from `Schema#parseBlock`.
-     * @returns the `FilterResult`, exactly as `rows` would answer it.
-     * @throws {ChtypesError} when the filter or block is closed, or they come
-     *   from two different libraries.
-     */
+    #calls;
+    #h;
+    /** Not for callers: use `Schema.compileFilter`. */
+    constructor(calls, handle) {
+        this.#calls = calls;
+        this.#h = handle;
+        filterHandles.set(this, handle);
+    }
+    /** Evaluate over a body. */
+    rows(format, body, options = {}) {
+        return decodeFilterResult(this.#calls.filterEvalBody(this.#h, format, bodyIn(body), encodeSettings(options.settings, options.sessionTimezone)));
+    }
+    /** Evaluate over a parsed block. The filter brings its zone and the block brought its parse zone, so there are no settings here. */
     eval(block) {
-        if (this.n.handle === null)
-            throw new ChtypesError('chtypes: filter is closed');
-        if (block.nativeLib !== this.native) {
-            throw new ChtypesError('chtypes: filter and block come from different libraries');
-        }
-        const doc = this.native.filterEval(this.n.handle, block.liveHandle());
-        return filterResultOf(parseDocument(doc));
+        return decodeFilterResult(this.#calls.filterEvalBlock(this.#h, blockHandles.get(block)));
     }
-    /**
-     * Release the native filter (`chs_filter_free`). Idempotent, and also
-     * performed by the schema's own `close()` — filters first, then the schema,
-     * the C-required order. Also the backstop a GC finalizer calls for a filter
-     * nobody closed — see `SchemaNative`; the `openFilters.delete` guard is
-     * what makes it safe to run whether `close()`, this filter's own finalizer,
-     * or the schema's finalizer gets here first.
-     */
+    /** Release this filter; idempotent. */
     close() {
-        if (this.n.handle === null)
-            return;
-        if (this.n.schema.openFilters.delete(this.n.handle)) {
-            this.native.filterFree(this.n.handle);
-        }
-        this.n.handle = null;
-        this.schema.forgetFilter(this);
-        filterFinalizer.unregister(this);
+        this.#h.close();
     }
-    /** `using filter = schema.compileFilter(...)` releases it at scope exit. */
     [Symbol.dispose]() {
         this.close();
     }
 }
-/**
- * One body, parsed ONCE under one schema handle and one clock instant
- * (`chs_block_parse`). Obtained from `Schema#parseBlock`; evaluated by
- * `Filter#eval`. The parse-once/eval-many twin of `Filter#rows`
- * (the C ABI contract §Blocks): the live-SSE hot path is K filters × 1 event, and
- * the block sheds the re-parse.
- *
- * LIFETIME: a block REFERENCES its schema handle exactly as a filter does —
- * the C layer does not copy and does not refcount. This binding enforces the
- * free order structurally, both ways: the `Block` holds its `Schema` (so the
- * schema stays reachable), and `Schema#close` closes every open block before
- * freeing the schema — `using` / `Symbol.dispose` work on all three objects
- * in any nesting, and the schema's dispose runs the block's first when the
- * caller forgot. A block may be evaluated by MANY filters, sequentially;
- * evaluation does not consume or mutate it. Recompile blocks when the schema
- * is recompiled.
- *
- * THREADS: one block must not be used from two threads at once, and an eval
- * is a use of BOTH handles. On a single JS thread every call here is
- * synchronous, so ordinary Node code satisfies both by construction; do not
- * share a `Block` — or its `Schema` — across `worker_threads`.
- *
- * A block nobody closed is also backed by a GC finalizer, coordinated with
- * its schema's own (see `SchemaNative`) so the two can never free this
- * block's handle out of order or twice, whichever one the GC happens to run
- * first.
- */
+const blockHandles = new WeakMap();
+/** A body parsed once, evaluated by any number of filters. */
 export class Block {
-    native;
-    schema;
-    /** The handle plus the GC-finalizer coordination state; see `BlockNative`. */
-    n;
-    /** @internal — obtained from `Schema#parseBlock`. */
-    constructor(native, schema, schemaNative, handle) {
-        this.native = native;
-        this.schema = schema;
-        this.n = { native, schema: schemaNative, handle };
-        blockFinalizer.register(this, this.n, this);
+    #h;
+    /** Not for callers: use `Schema.parseBlock`. */
+    constructor(handle) {
+        this.#h = handle;
+        blockHandles.set(this, handle);
     }
-    /** @internal — the loaded library this block's handle belongs to. */
-    get nativeLib() {
-        return this.native;
+    /** Release this block; idempotent. */
+    close() {
+        this.#h.close();
     }
-    /** @internal — the live handle, for `Filter#eval`. */
-    liveHandle() {
-        if (this.n.handle === null)
-            throw new ChtypesError('chtypes: block is closed');
-        return this.n.handle;
+    [Symbol.dispose]() {
+        this.close();
     }
-    /**
-     * Release the native block (`chs_block_free`). Idempotent, and also
-     * performed by the schema's own `close()` — blocks first, then the schema,
-     * the C-required order. Also the backstop a GC finalizer calls for a block
-     * nobody closed — see `SchemaNative`; the `openBlocks.delete` guard is what
-     * makes it safe to run whether `close()`, this block's own finalizer, or
-     * the schema's finalizer gets here first.
-     */
+}
+/** A compiled `CREATE TABLE`: describe it, preview rows and bodies against it, compile filters and parse blocks over it. */
+export class Schema {
+    #calls;
+    #h;
+    /** Not for callers: use `Library.compileTable`. */
+    constructor(calls, handle) {
+        this.#calls = calls;
+        this.#h = handle;
+    }
+    /** The columns, in declared order. */
+    describe() {
+        return decodeSchemaDescription(this.#calls.schemaDescribe(this.#h));
+    }
+    /** One row. */
+    row(format, body, options = {}) {
+        return decodeRow(this.#calls.previewRow(this.#h, format, bodyIn(body), encodeSettings(options.settings, options.sessionTimezone), encodeColumns(options.columns)));
+    }
+    /** A whole body. */
+    rows(format, body, options = {}) {
+        const filter = options.rowFilter === undefined ? null : filterHandles.get(options.rowFilter);
+        const exporting = options.exportFormat !== undefined;
+        const out = this.#calls.previewBatch(this.#h, format, bodyIn(body), encodeSettings(options.settings, options.sessionTimezone), encodeColumns(options.columns), filter, exporting ? options.exportFormat : EXPORT_NONE, options.docFlags ?? DocFlags.All);
+        return decodeBatch(out.out, exporting ? out.outExport : undefined);
+    }
+    /** Compile a filter. Its zone is fixed here. */
+    compileFilter(expr, options = {}) {
+        return new Filter(this.#calls, this.#calls.filterCreate(this.#h, bytesIn(expr), encodeParams(options.params), encodeSettings(options.settings, options.sessionTimezone)));
+    }
+    /** Parse a body once. */
+    parseBlock(format, body, options = {}) {
+        return new Block(this.#calls.blockCreate(this.#h, format, bodyIn(body), encodeSettings(options.settings, options.sessionTimezone), encodeColumns(options.columns)));
+    }
+    /** Release this schema; idempotent. Filters and blocks made from it keep working. */
     close() {
-        if (this.n.handle === null)
-            return;
-        if (this.n.schema.openBlocks.delete(this.n.handle)) {
-            this.native.blockFree(this.n.handle);
-        }
-        this.n.handle = null;
-        this.schema.forgetBlock(this);
-        blockFinalizer.unregister(this);
+        this.#h.close();
     }
-    /** `using block = schema.parseBlock(...)` releases it at scope exit. */
     [Symbol.dispose]() {
         this.close();
     }