arrowbase 0.1.1

package/dist/collection-DGlKgOGi.d.ts

@@ -0,0 +1,1932 @@
+/**
+ * Column type codes.
+ *
+ * Fixed-width (Phase 1):
+ *   Bool, Int/UInt 8..64, Float 32/64
+ *
+ * Variable-width (Phase 3):
+ *   Utf8     — raw UTF-8 strings, offsets + values heap
+ *   DictUtf8 — dictionary-encoded UTF-8; per-row stores a u32 dictionary
+ *              code, with a sidecar string table (JS-side in v1).
+ *
+ * Values are stable integers — they are written to the column table in SAB
+ * and must not change without a schema-fingerprint bump.
+ */
+declare const ColumnTypeCode: {
+    readonly Bool: 1;
+    readonly Int8: 2;
+    readonly Int16: 3;
+    readonly Int32: 4;
+    readonly Int64: 5;
+    readonly UInt8: 6;
+    readonly UInt16: 7;
+    readonly UInt32: 8;
+    readonly UInt64: 9;
+    readonly Float32: 10;
+    readonly Float64: 11;
+    readonly Utf8: 12;
+    readonly DictUtf8: 13;
+    readonly Binary: 14;
+    readonly List: 15;
+    readonly Struct: 16;
+    readonly Point: 17;
+    readonly LineString: 18;
+    readonly Polygon: 19;
+};
+type ColumnTypeCode = (typeof ColumnTypeCode)[keyof typeof ColumnTypeCode];
+type ColumnTypeName = 'bool' | 'int8' | 'int16' | 'int32' | 'int64' | 'uint8' | 'uint16' | 'uint32' | 'uint64' | 'float32' | 'float64' | 'utf8' | 'dict_utf8' | 'binary' | 'list' | 'struct' | 'point' | 'linestring' | 'polygon';
+/** True for variable-width columns that need a values heap. */
+declare function isVariableWidth(code: ColumnTypeCode): boolean;
+/** True for dictionary-encoded columns that need a JS-side dict table. */
+declare function isDictionary(code: ColumnTypeCode): boolean;
+/**
+ * Byte width of a single element for fixed-width columns. For variable-width
+ * columns (Utf8), returns the offsets array element width (i32 = 4).
+ * Dict columns store a u32 code per row (= 4).
+ */
+declare function byteWidthOf(code: ColumnTypeCode): number;
+/** JS value type for each column type. */
+type PointValue = readonly [lng: number, lat: number];
+type LineStringValue = readonly PointValue[];
+type PolygonValue = readonly LineStringValue[];
+type ValueOf<T extends ColumnTypeName> = T extends 'bool' ? boolean : T extends 'int64' | 'uint64' ? bigint : T extends 'utf8' | 'dict_utf8' ? string : T extends 'binary' ? Uint8Array : T extends 'list' ? readonly unknown[] : T extends 'struct' ? Record<string, unknown> : T extends 'point' ? PointValue : T extends 'linestring' ? LineStringValue : T extends 'polygon' ? PolygonValue : number;
+
+/** User-facing column definition. */
+interface ColumnDef {
+    type: ColumnTypeName;
+    /** If false (default), nulls are not allowed and no validity bitmap is kept. */
+    nullable?: boolean;
+    /**
+     * For `utf8`/`binary` columns: total bytes reserved for the values
+     * heap. For `list<utf8>`/`list<binary>` columns: bytes reserved for
+     * the **child** heap. Defaults to `32 * capacity` otherwise.
+     */
+    valuesHeapBytes?: number;
+    /** Required when `type === 'list'`. The child element type. */
+    items?: ColumnDef;
+    /** Required when `type === 'struct'`. Map of field name → def. */
+    fields?: Record<string, ColumnDef>;
+    /** For polygon columns: append first point when a ring is open. */
+    autoCloseRings?: boolean;
+}
+/** User-facing schema definition input. */
+interface SchemaInput {
+    name: string;
+    /**
+     * Primary key must be a `uint32` column in Phase 1. Defaults to `__id`
+     * if present.
+     */
+    primaryKey?: string;
+    columns: Record<string, ColumnDef>;
+}
+/** Compiled, immutable schema describing a collection's columns. */
+interface CompiledColumn {
+    readonly name: string;
+    readonly index: number;
+    readonly type: ColumnTypeName;
+    readonly typeCode: ColumnTypeCode;
+    /**
+     * For fixed-width columns: byte width of a single element.
+     * For Utf8/Binary: byte width of the offsets-array element (i32 = 4).
+     * For DictUtf8: byte width of a code (u32 = 4).
+     * For List: byte width of the offsets-array element (i32 = 4).
+     * For Struct: 0 (no primary buffer — fields carry the storage).
+     */
+    readonly byteWidth: number;
+    readonly nullable: boolean;
+    /**
+     * For utf8/binary columns: total bytes reserved in the values heap.
+     * For list<utf8>/list<binary> columns: bytes reserved for the child heap.
+     * Undefined uses the default (32 bytes per row).
+     */
+    readonly valuesHeapBytes: number | undefined;
+    /**
+     * For List columns: the compiled child element column. `index === -1`
+     * on the child to signal "this is not a top-level column". Its
+     * `byteWidth` drives child-array allocation. Child is always a leaf
+     * type (primitive, utf8, dict_utf8, binary, or bool) in v1.
+     */
+    readonly childColumn?: CompiledColumn;
+    /**
+     * For Struct columns: child field columns in declaration order. Each
+     * field column has `index` ≥ 0 but is *not* present in the top-level
+     * `columns` array of the parent schema — fields live only on their
+     * struct parent. Nested structs and list-fields are rejected in v1.
+     */
+    readonly fields?: readonly CompiledColumn[];
+    readonly fieldsByName?: ReadonlyMap<string, CompiledColumn>;
+    /** Polygon-only storage option. */
+    readonly autoCloseRings?: boolean;
+}
+interface CompiledSchema {
+    readonly name: string;
+    readonly primaryKey: string;
+    readonly primaryKeyIndex: number;
+    readonly columns: readonly CompiledColumn[];
+    readonly columnsByName: ReadonlyMap<string, CompiledColumn>;
+    readonly fingerprint: bigint;
+}
+/**
+ * Compile a user schema into the immutable layout used by allocators and
+ * collections. Validates:
+ *   - non-empty column set
+ *   - no duplicate names
+ *   - PK exists and has type uint32 (Phase 1 constraint)
+ *   - all column types are supported
+ */
+declare function defineSchema(input: SchemaInput): CompiledSchema;
+
+/**
+ * Ref proxies — `@tanstack/db` parity (Layer C.2).
+ *
+ * A ref proxy is a JS Proxy that records every property access as a
+ * path segment, materialized into a `PropRef` by `toExpression`.
+ * Every builder callback (`where`, `select`, `orderBy`, etc.) is
+ * passed either:
+ *   - a root proxy (multiple aliases): `({ users, posts }) => eq(users.id, posts.userId)`
+ *   - a single-row proxy: `(row) => row.name`
+ *   - a with-selected proxy: `({ posts, $selected }) => $selected.count`
+ *
+ * Runtime matches `@tanstack/db/query/builder/ref-proxy.js` gesture-
+ * for-gesture; type layer is looser (we use `any` in a few places
+ * where upstream's inference is too deep for our scope). The
+ * conformance test in C.11 catches meaningful regressions.
+ */
+
+/**
+ * Brand carried by every ref-proxy leaf. Matches upstream's
+ * `RefProxy<T>` shape; `__path` is the access trail.
+ */
+interface RefProxy<T = unknown> {
+    /** @internal */
+    readonly __refProxy: true;
+    /** @internal */
+    readonly __path: Array<string>;
+    /** @internal — phantom type for TS inference. */
+    readonly __type: T;
+}
+/**
+ * A leaf in a ref proxy tree — wraps a scalar `T` and carries
+ * `__path` + `__refProxy`. Used by the deep-mapped
+ * `SingleRowRefProxy` to type column access.
+ */
+type RefLeaf<T = unknown> = RefProxy<T> & {
+    readonly __refLeaf: true;
+};
+/**
+ * Virtual row properties exposed on every single-row proxy for
+ * parity with `@tanstack/db`. Runtime compilation of these is
+ * Layer H; Layer C accepts them structurally so callers can write
+ * code referencing `row.$key` etc. without tripping the IR.
+ */
+type VirtualPropsRefProxy<TKey extends string | number = string | number> = {
+    readonly $synced: RefLeaf<boolean>;
+    readonly $origin: RefLeaf<'sync' | 'optimistic'>;
+    readonly $key: RefLeaf<TKey>;
+    readonly $collectionId: RefLeaf<string>;
+};
+/**
+ * Deep-mapped: each scalar column becomes a `RefLeaf<T>`; each
+ * object column recurses. Matches `@tanstack/db`'s
+ * `SingleRowRefProxy` shape. Used for single-row callbacks
+ * (`fn.select`, `fn.where`, `fn.having`) and inside index
+ * expression evaluators.
+ */
+type SingleRowRefProxy<T, TKey extends string | number = string | number> = T extends Record<string, unknown> ? {
+    readonly [K in keyof T]: T[K] extends Record<string, unknown> ? SingleRowRefProxy<T[K], TKey> & RefProxy<T[K]> : RefLeaf<T[K]>;
+} & RefProxy<T> & VirtualPropsRefProxy<TKey> : RefProxy<T> & VirtualPropsRefProxy<TKey>;
+/** TanStack-style public ref alias. */
+type Ref<T = unknown> = T extends Record<string, unknown> ? SingleRowRefProxy<T> : RefLeaf<T>;
+/**
+ * Create a single-row ref proxy. Every property access records a
+ * path segment and returns a nested proxy (memoized per-path).
+ *
+ * Matches `@tanstack/db`'s `createSingleRowRefProxy<T>()` runtime
+ * byte-for-byte (modulo style).
+ */
+declare function createSingleRowRefProxy<T extends Record<string, unknown> = Record<string, unknown>>(): SingleRowRefProxy<T>;
+/**
+ * Root-level ref proxy shape: each declared alias is exposed as a
+ * `SingleRowRefProxy<T[alias]>`. The root itself is branded as a
+ * `RefProxy`.
+ */
+type RootRefProxy<T extends Record<string, Record<string, unknown>>> = RefProxy<T> & {
+    readonly [K in keyof T]: SingleRowRefProxy<T[K]>;
+};
+/**
+ * Create a root ref proxy scoped to a set of table aliases. The
+ * root proxy exposes each alias as a nested single-row proxy;
+ * path segments accumulate alias + column + (nested...) and are
+ * materialized by `toExpression`.
+ *
+ * Matches `@tanstack/db`'s `createRefProxy<T>(aliases)` runtime.
+ */
+declare function createRefProxy<T extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>>(aliases: Array<string>): RootRefProxy<T>;
+/**
+ * Create a root ref proxy augmented with a `$selected` namespace.
+ * Used inside `having` callbacks where the preceding `select` has
+ * introduced named columns that HAVING can reference by alias.
+ *
+ * Paths rooted at `$selected` are emitted as
+ * `['$selected', ...rest]`; the compiler then resolves them
+ * against the resolved SELECT shape.
+ */
+declare function createRefProxyWithSelected<T extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>>(aliases: Array<string>): RootRefProxy<T> & {
+    $selected: SingleRowRefProxy<Record<string, unknown>>;
+};
+/**
+ * Type guard: is `value` a ref proxy?
+ */
+declare function isRefProxy(value: unknown): value is RefProxy;
+/**
+ * Convert a value to a `BasicExpression`:
+ *
+ * - A ref proxy becomes a `PropRef` of its recorded path.
+ * - An existing IR expression (ref/val/func/agg) is returned as-is.
+ * - `ToArrayWrapper` / `ConcatToArrayWrapper` (Layer F) throws —
+ *   matches upstream's guard; we don't have those wrappers yet so
+ *   the guard is a no-op-in-practice today.
+ * - Any other value is wrapped as a `Value` literal.
+ */
+declare function toExpression<T = unknown>(value: T): BasicExpression;
+/**
+ * Wrap a literal as a `Value` expression. Matches
+ * `@tanstack/db`'s `val(v)`. Useful for distinguishing a literal
+ * from a ref-proxy in contexts where both appear — e.g.
+ * `eq(users.id, val(1))` vs `eq(users.id, 1)` (the second is
+ * identical in practice because `toExpression` wraps literals,
+ * but `val()` makes intent explicit in generated code).
+ */
+declare function val<T>(value: T): BasicExpression<T>;
+
+/**
+ * TanStack DB-compatible type surface.
+ *
+ * We mirror `@tanstack/db`'s public type vocabulary here so that every
+ * layer of ArrowBase can import from a single internal module instead
+ * of redeclaring types. Types live here; runtime lives in
+ * `src/collection/*` and elsewhere. Nothing in this file imports
+ * `@tanstack/db` at runtime.
+ *
+ * Kept intentionally minimal for Layer B. Layer C (query) and Layer E
+ * (transactions) will expand this file.
+ */
+/** Operation type in a ChangeMessage. Matches @tanstack/db. */
+type OperationType = 'insert' | 'update' | 'delete';
+/**
+ * Arbitrary function type. Matches @tanstack/db's `Fn`.
+ */
+type Fn = (...args: Array<unknown>) => unknown;
+/**
+ * Record of utility functions attached to a collection via
+ * `CollectionConfig.utils`. Matches @tanstack/db's `UtilsRecord`.
+ * Intentionally `any` on the value side so each util can carry its
+ * own narrow signature at the call site.
+ */
+type UtilsRecord = Record<string, any>;
+/**
+ * String collation config for sort operations. Matches
+ * `@tanstack/db`'s `StringCollationConfig` discriminated union.
+ */
+type StringCollationConfig = {
+    stringSort?: 'lexical';
+} | {
+    stringSort?: 'locale';
+    locale?: string;
+    localeOptions?: object;
+};
+interface SpatialIndexOptions$1 {
+    readonly column: string;
+    readonly type: 'rtree';
+    readonly eager?: boolean;
+}
+type SpatialIndexConfig$1 = SpatialIndexOptions$1 | readonly SpatialIndexOptions$1[];
+/**
+ * A single change emitted by `subscribeChanges`. Matches @tanstack/db's
+ * `ChangeMessage<T, TKey>` field-for-field.
+ *
+ * - `key` — primary key of the row affected.
+ * - `value` — current row value after the mutation (for delete, the
+ *   final state, i.e. tombstone for soft-deletes or the pre-removal
+ *   snapshot for hard-deletes).
+ * - `previousValue` — row state immediately before an update. Absent
+ *   for inserts and deletes (TanStack DB also omits it for inserts;
+ *   for deletes `value` IS the pre-delete row, matching their shape).
+ * - `type` — 'insert' | 'update' | 'delete'.
+ * - `metadata` — optional free-form bag; used by sync adapters to
+ *   attach origin info.
+ */
+interface ChangeMessage<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
+    key: TKey;
+    value: T;
+    previousValue?: T;
+    type: OperationType;
+    metadata?: Record<string, unknown>;
+}
+type DeleteKeyMessage<TKey extends string | number = string | number> = Omit<ChangeMessage<any, TKey>, 'value' | 'previousValue' | 'type'> & {
+    type: 'delete';
+};
+type ChangeMessageOrDeleteKeyMessage<T extends object = Record<string, unknown>, TKey extends string | number = string | number> = Omit<ChangeMessage<T, TKey>, 'key'> | DeleteKeyMessage<TKey>;
+type OptimisticChangeMessage<T extends object = Record<string, unknown>, TKey extends string | number = string | number> = (ChangeMessage<T, TKey> & {
+    isActive?: boolean;
+}) | (DeleteKeyMessage<TKey> & {
+    isActive?: boolean;
+});
+/**
+ * Options for `subscribeChanges`. Matches @tanstack/db's
+ * `SubscribeChangesOptions` for the public surface.
+ *
+ * `includeInitialState`: when `true`, the callback is invoked once
+ * synchronously with a snapshot of the current rows as `insert`
+ * messages before any subsequent mutation-driven calls.
+ */
+interface SubscribeChangesOptions {
+    includeInitialState?: boolean;
+    /** Callback form lowered to `whereExpression` for filtering/subset/index planning. */
+    where?: (row: SingleRowRefProxy<Record<string, unknown>>) => unknown;
+    /** Precompiled where expression used by query/live internals. */
+    whereExpression?: BasicExpression<boolean>;
+}
+/**
+ * Options for `currentStateAsChanges`.
+ *
+ * Reduced from @tanstack/db in Layer B — `where` / `orderBy` / `limit`
+ * /  `optimizedOnly` are query-builder concepts and land in Layer C.
+ * The B signature still accepts the full shape structurally so Layer
+ * C can add behavior without changing the method signature.
+ */
+interface CurrentStateAsChangesOptions {
+    where?: BasicExpression<boolean>;
+    whereExpression?: BasicExpression<boolean>;
+    orderBy?: OrderBy;
+    limit?: number;
+    optimizedOnly?: boolean;
+}
+/**
+ * Handle returned from `subscribeChanges`. Calling `unsubscribe()`
+ * detaches the listener. Additional event-emitter methods (`status`,
+ * event handlers) are added in a later layer.
+ */
+interface CollectionSubscription {
+    readonly status: 'ready' | 'loadingSubset';
+    unsubscribe(): void;
+}
+/**
+ * Metadata passed alongside a single mutation. Matches
+ * `@tanstack/db`'s `OperationConfig`.
+ */
+interface OperationConfig {
+    metadata?: Record<string, unknown>;
+    /** Apply optimistic updates immediately. Defaults to true. */
+    optimistic?: boolean;
+}
+/** Insert-specific config. Superset of `OperationConfig`. */
+interface InsertConfig extends OperationConfig {
+}
+interface Deferred<T> {
+    readonly promise: Promise<T>;
+    resolve(value: T | PromiseLike<T>): void;
+    reject(reason?: unknown): void;
+    readonly settled: boolean;
+}
+/**
+ * Transaction-state tag. Matches @tanstack/db.
+ */
+type TransactionState = 'pending' | 'persisting' | 'completed' | 'failed';
+interface TransactionCollectionLike {
+    readonly id: string;
+    readonly _state?: {
+        onTransactionStateChange?: () => void;
+        pendingSyncedTransactions?: ReadonlyArray<unknown>;
+        commitPendingTransactions?: () => void;
+    };
+}
+type ResolveTransactionChanges<T extends object = Record<string, unknown>, TOperation extends OperationType = OperationType> = TOperation extends 'delete' ? T : Partial<T>;
+/**
+ * One entry in a pending transaction. Matches @tanstack/db's public
+ * mutation record shape closely enough for Layer E transaction APIs.
+ */
+interface PendingMutation<T extends object = Record<string, unknown>, TOperation extends OperationType = OperationType, TCollection extends TransactionCollectionLike = TransactionCollectionLike> {
+    mutationId: string;
+    original: TOperation extends 'insert' ? {} : T;
+    modified: T;
+    changes: ResolveTransactionChanges<T, TOperation>;
+    globalKey: string;
+    key: unknown;
+    type: TOperation;
+    metadata: unknown;
+    syncMetadata: Record<string, unknown>;
+    optimistic: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+    collection: TCollection;
+}
+type NonEmptyArray<T> = [T, ...Array<T>];
+interface Transaction$1<T extends object = Record<string, unknown>> {
+    readonly id: string;
+    state: TransactionState;
+    readonly mutationFn: MutationFn<T>;
+    readonly mutations: Array<PendingMutation<T>>;
+    readonly isPersisted: Deferred<Transaction$1<T>>;
+    readonly autoCommit: boolean;
+    readonly createdAt: Date;
+    readonly sequenceNumber: number;
+    readonly metadata: Record<string, unknown>;
+    readonly error?: {
+        message: string;
+        error: Error;
+    };
+    setState(newState: TransactionState): void;
+    mutate(callback: () => void | PromiseLike<void>): Transaction$1<T>;
+    applyMutations(mutations: Array<PendingMutation<any>>): void;
+    rollback(config?: {
+        isSecondaryRollback?: boolean;
+    }): Transaction$1<T>;
+    touchCollection(): void;
+    commit(): Promise<Transaction$1<T>>;
+    compareCreatedAt(other: Transaction$1<any>): number;
+}
+type TransactionWithMutations<T extends object = Record<string, unknown>, TOperation extends OperationType = OperationType> = Omit<Transaction$1<T>, 'mutations'> & {
+    mutations: NonEmptyArray<PendingMutation<T, TOperation>>;
+};
+type MutationFnParams<T extends object = Record<string, unknown>> = {
+    transaction: TransactionWithMutations<T>;
+};
+type MutationFn<T extends object = Record<string, unknown>> = (params: MutationFnParams<T>) => Promise<unknown>;
+interface TransactionConfig<T extends object = Record<string, unknown>> {
+    id?: string;
+    autoCommit?: boolean;
+    mutationFn: MutationFn<T>;
+    metadata?: Record<string, unknown>;
+}
+/** Options for createOptimisticAction. Mirrors @tanstack/db's helper. */
+interface CreateOptimisticActionsOptions<TVars = unknown, T extends object = Record<string, unknown>> extends Omit<TransactionConfig<T>, 'mutationFn'> {
+    /** Function to apply optimistic updates locally before the mutation completes. */
+    onMutate: (vars: TVars) => void;
+    /** Function to execute the mutation on the server. */
+    mutationFn: (vars: TVars, params: MutationFnParams<T>) => Promise<unknown>;
+}
+interface BaseStrategy<TName extends string = string> {
+    _type: TName;
+    execute: <T extends object = Record<string, unknown>>(fn: () => Transaction$1<T>) => void | Promise<void>;
+    cleanup: () => void;
+}
+interface DebounceStrategyOptions {
+    wait: number;
+    leading?: boolean;
+    trailing?: boolean;
+}
+interface DebounceStrategy extends BaseStrategy<'debounce'> {
+    options: DebounceStrategyOptions;
+}
+interface QueueStrategyOptions {
+    wait?: number;
+    maxSize?: number;
+    addItemsTo?: 'front' | 'back';
+    getItemsFrom?: 'front' | 'back';
+}
+interface QueueStrategy extends BaseStrategy<'queue'> {
+    options?: QueueStrategyOptions;
+}
+interface ThrottleStrategyOptions {
+    wait: number;
+    leading?: boolean;
+    trailing?: boolean;
+}
+interface ThrottleStrategy extends BaseStrategy<'throttle'> {
+    options: ThrottleStrategyOptions;
+}
+interface BatchStrategyOptions {
+    maxSize?: number;
+    wait?: number;
+    getShouldExecute?: (items: Array<unknown>) => boolean;
+}
+interface BatchStrategy extends BaseStrategy<'batch'> {
+    options?: BatchStrategyOptions;
+}
+type Strategy = DebounceStrategy | QueueStrategy | ThrottleStrategy | BatchStrategy;
+type StrategyOptions<T extends Strategy> = T extends DebounceStrategy ? DebounceStrategyOptions : T extends QueueStrategy ? QueueStrategyOptions : T extends ThrottleStrategy ? ThrottleStrategyOptions : T extends BatchStrategy ? BatchStrategyOptions : never;
+interface PacedMutationsConfig<TVariables = unknown, T extends object = Record<string, unknown>> {
+    onMutate: (variables: TVariables) => void;
+    mutationFn: MutationFn<T>;
+    strategy: Strategy;
+    metadata?: Record<string, unknown>;
+}
+interface LoadSubsetOptions {
+    /** The where expression to filter the data. */
+    where?: unknown;
+    /** The order-by clause to sort the data. */
+    orderBy?: unknown;
+    /** Maximum rows to load. */
+    limit?: number;
+    /** Cursor expressions for cursor-based pagination. */
+    cursor?: unknown;
+    /** Row offset for offset-based pagination. */
+    offset?: number;
+    /** Subscription that triggered the load, when available. */
+    subscription?: unknown;
+}
+type LoadSubsetFn = (options: LoadSubsetOptions) => true | Promise<void>;
+type UnloadSubsetFn = (options: LoadSubsetOptions) => void;
+interface SyncParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
+    /** The collection the sync is attached to. Typed loosely to avoid a circular import. */
+    collection: unknown;
+    begin: (options?: {
+        immediate?: boolean;
+    }) => void;
+    write: (message: ChangeMessageOrDeleteKeyMessage<T, TKey>) => void;
+    commit: () => void;
+    markReady: () => void;
+    truncate: () => void;
+}
+/**
+ * Sync adapter protocol. Matches the subset of `@tanstack/db`'s
+ * `SyncConfig` that Layer B consumers can plug into. The actual
+ * `sync` function will be invoked by Layer E's transaction flow;
+ * for now we only accept + store the reference.
+ */
+interface SyncConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
+    sync: (params: SyncParams<T, TKey>) => void | (() => void);
+}
+/**
+ * Parameters passed to collection mutation-handler callbacks.
+ * `onInsert`/`onUpdate`/`onDelete` receive this.
+ */
+interface CollectionMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TOperation extends OperationType = OperationType> {
+    transaction: TransactionWithMutations<T, TOperation>;
+    collection: unknown;
+}
+type InsertMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number> = CollectionMutationFnParams<T, TKey, 'insert'>;
+type UpdateMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number> = CollectionMutationFnParams<T, TKey, 'update'>;
+type DeleteMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number> = CollectionMutationFnParams<T, TKey, 'delete'>;
+type InsertMutationFn<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TReturn = unknown> = (params: InsertMutationFnParams<T, TKey>) => Promise<TReturn>;
+type UpdateMutationFn<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TReturn = unknown> = (params: UpdateMutationFnParams<T, TKey>) => Promise<TReturn>;
+type DeleteMutationFn<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TReturn = unknown> = (params: DeleteMutationFnParams<T, TKey>) => Promise<TReturn>;
+interface LocalOnlyCollectionUtils extends UtilsRecord {
+    acceptMutations: (transaction: {
+        mutations: Array<PendingMutation<Record<string, unknown>>>;
+    }) => void;
+}
+interface LocalOnlyCollectionConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number> extends Omit<CreateCollectionConfig<T, TKey>, 'gcTime' | 'startSync' | 'sync' | 'utils'> {
+    initialData?: Array<T>;
+}
+type LocalOnlyCollectionOptionsResult<T extends object = Record<string, unknown>, TKey extends string | number = string | number> = CreateCollectionConfig<T, TKey> & {
+    gcTime: 0;
+    startSync: true;
+    initialData?: Array<T>;
+    utils: LocalOnlyCollectionUtils;
+};
+type StorageApi = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+type StorageEventApi = {
+    addEventListener: (type: 'storage', listener: (event: StorageEvent) => void) => void;
+    removeEventListener: (type: 'storage', listener: (event: StorageEvent) => void) => void;
+};
+interface Parser {
+    parse: (data: string) => unknown;
+    stringify: (data: unknown) => string;
+}
+type ClearStorageFn = () => void;
+type GetStorageSizeFn = () => number;
+interface LocalStorageCollectionUtils extends UtilsRecord {
+    clearStorage: ClearStorageFn;
+    getStorageSize: GetStorageSizeFn;
+    acceptMutations: (transaction: {
+        mutations: Array<PendingMutation<Record<string, unknown>>>;
+    }) => void;
+}
+interface LocalStorageCollectionConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number> extends Omit<CreateCollectionConfig<T, TKey>, 'sync' | 'utils'> {
+    storageKey: string;
+    storage?: StorageApi;
+    storageEventApi?: StorageEventApi;
+    parser?: Parser;
+}
+type LocalStorageCollectionOptionsResult<T extends object = Record<string, unknown>, TKey extends string | number = string | number> = CreateCollectionConfig<T, TKey> & {
+    id: string;
+    sync: SyncConfig<T, TKey>;
+    utils: LocalStorageCollectionUtils;
+};
+/**
+ * `createCollection` config shape. A hybrid of @tanstack/db's
+ * `CollectionConfig` and ArrowBase's native `CollectionOptions`
+ * (we need `schema` + `capacity` because our store is columnar).
+ *
+ * Non-essential TanStack fields (`gcTime`/`startSync`/`syncMode`/
+ * `compare`/`singleResult`) are accepted structurally but currently
+ * unused by Layer B. Layer E wires `sync`/`onInsert`/`onUpdate`/
+ * `onDelete`; Layer D wires `autoIndex`/`defaultIndexType`.
+ */
+interface CreateCollectionConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
+    /**
+     * ArrowBase compiled schema (required). TanStack DB's
+     * `StandardSchemaV1`-based schema support will land in Layer C;
+     * Layer B requires the compiled columnar layout.
+     *
+     * Typed as `unknown` here to avoid circular imports — the factory
+     * narrows it to `CompiledSchema` at runtime.
+     */
+    schema: unknown;
+    /** Row capacity. Required — ArrowBase is fixed-capacity. */
+    capacity: number;
+    id?: string;
+    /**
+     * Function to extract the primary key. If omitted, reads the
+     * schema's declared PK column. Passing a function overrides.
+     */
+    getKey?: (item: T) => TKey;
+    gcTime?: number;
+    startSync?: boolean;
+    syncMode?: 'eager' | 'on-demand';
+    autoIndex?: 'off' | 'eager';
+    defaultIndexType?: IndexConstructor<TKey>;
+    sync?: SyncConfig<T, TKey>;
+    utils?: UtilsRecord;
+    compareOptions?: StringCollationConfig;
+    onInsert?: InsertMutationFn<T, TKey>;
+    onUpdate?: UpdateMutationFn<T, TKey>;
+    onDelete?: DeleteMutationFn<T, TKey>;
+    undoCapacity?: number;
+    softDelete?: boolean;
+    spatialIndex?: SpatialIndexConfig$1;
+}
+
+/**
+ * Query IR — `@tanstack/db` parity.
+ *
+ * This module mirrors `@tanstack/db/dist/esm/query/ir.d.ts` field-for-
+ * field. Expression classes carry `type` brands matching upstream
+ * ('collectionRef', 'queryRef', 'ref', 'val', 'func', 'agg',
+ * 'includesSubquery') so that code that walks the IR by `type` tag
+ * works identically on either runtime.
+ *
+ * We deliberately do NOT import from `@tanstack/db` here — Layer C
+ * has zero runtime dep on upstream (types only). Field names are
+ * kept identical for structural interop; semantic behavior for
+ * Layer-C-unsupported features (IncludesSubquery, residual WHERE) is
+ * defined but not yet compiled.
+ */
+
+/** A row keyed by source alias. Mirrors `@tanstack/db`'s `NamespacedRow`. */
+type NamespacedRow = Record<string, Record<string, unknown>>;
+/**
+ * Root IR shape for a query. Every builder emits a `QueryIR` via
+ * `_getQuery()`; every compiler consumes one. Matches
+ * `@tanstack/db`'s `QueryIR` field-for-field.
+ */
+interface QueryIR {
+    from: From;
+    select?: Select;
+    join?: Join;
+    where?: Array<Where>;
+    groupBy?: GroupBy;
+    having?: Array<Having>;
+    orderBy?: OrderBy;
+    limit?: Limit;
+    offset?: Offset;
+    distinct?: true;
+    singleResult?: true;
+    /**
+     * Functional SELECT — JS closure invoked per row. Bypasses the
+     * vectorized compile path; used by `builder.fn.select(cb)`.
+     */
+    fnSelect?: (row: NamespacedRow) => unknown;
+    /**
+     * Functional WHERE — JS closure invoked per row. ANDed with any
+     * structural `where` entries. Populated by `builder.fn.where(cb)`.
+     */
+    fnWhere?: Array<(row: NamespacedRow) => unknown>;
+    /**
+     * Functional HAVING — evaluated against grouped rows. Populated by
+     * `builder.fn.having(cb)`.
+     */
+    fnHaving?: Array<(row: NamespacedRow) => unknown>;
+}
+/**
+ * Materialization strategy for `IncludesSubquery`. Layer F owns
+ * the runtime; Layer C accepts the tag structurally.
+ */
+type IncludesMaterialization = 'collection' | 'array' | 'concat' | 'single';
+/**
+ * Synthetic field name used by `IncludesSubquery` scalar paths.
+ * Matches upstream literal ('__includes_scalar__').
+ */
+declare const INCLUDES_SCALAR_FIELD = "__includes_scalar__";
+type From = CollectionRef | QueryRef;
+type Select = {
+    [alias: string]: BasicExpression | Aggregate | Select | IncludesSubquery;
+};
+type Join = Array<JoinClause>;
+interface JoinClause {
+    from: CollectionRef | QueryRef;
+    type: 'left' | 'right' | 'inner' | 'outer' | 'full' | 'cross';
+    left: BasicExpression;
+    right: BasicExpression;
+}
+/**
+ * A WHERE clause entry. Either a bare expression or a
+ * `{ expression, residual? }` object. The `residual` flag marks
+ * a predicate that the optimizer couldn't push into an index scan
+ * — present for interop; Layer C treats residual and non-residual
+ * identically (Layer D's index optimizer will start emitting them).
+ */
+type Where = BasicExpression<boolean> | {
+    expression: BasicExpression<boolean>;
+    residual?: boolean;
+};
+type GroupBy = Array<BasicExpression>;
+type Having = Where;
+type OrderBy = Array<OrderByClause>;
+interface OrderByClause {
+    expression: BasicExpression;
+    compareOptions: CompareOptions;
+}
+type OrderByDirection = 'asc' | 'desc';
+/**
+ * Full compare options for an orderBy expression. Extends the
+ * shared string-collation config with direction + null-sort mode.
+ * Matches `@tanstack/db`'s `CompareOptions`.
+ */
+type CompareOptions = StringCollationConfig & {
+    direction: OrderByDirection;
+    nulls: 'first' | 'last';
+};
+type Limit = number;
+type Offset = number;
+/**
+ * Common base for every IR expression node. Carries a `type` brand
+ * checked by `isExpressionLike` and the compiler's walk.
+ */
+declare abstract class BaseExpression<T = unknown> {
+    abstract type: string;
+    /** @internal — phantom type carrier for TS inference. */
+    readonly __returnType: T;
+}
+/** Reference to a base Collection at a given alias. */
+declare class CollectionRef extends BaseExpression {
+    collection: Collection;
+    alias: string;
+    readonly type: "collectionRef";
+    constructor(collection: Collection, alias: string);
+}
+/** Reference to a subquery (nested `QueryIR`) at a given alias. */
+declare class QueryRef extends BaseExpression {
+    query: QueryIR;
+    alias: string;
+    readonly type: "queryRef";
+    constructor(query: QueryIR, alias: string);
+}
+/** Column / property reference. `path = ['alias', 'col', 'nested']`. */
+declare class PropRef<T = unknown> extends BaseExpression<T> {
+    path: Array<string>;
+    readonly type: "ref";
+    constructor(path: Array<string>);
+}
+/** Literal value wrapped as an expression. */
+declare class Value<T = unknown> extends BaseExpression<T> {
+    value: T;
+    readonly type: "val";
+    constructor(value: T);
+}
+/**
+ * Scalar function call. `name` is one of the upstream operator
+ * literals ('eq' / 'gt' / 'upper' / etc.); `args` are expressions.
+ */
+declare class Func<T = unknown> extends BaseExpression<T> {
+    name: string;
+    args: Array<BasicExpression>;
+    readonly type: "func";
+    constructor(name: string, args: Array<BasicExpression>);
+}
+type BasicExpression<T = unknown> = PropRef<T> | Value<T> | Func<T>;
+/**
+ * Aggregate function call. Separated from `Func` because aggregates
+ * can appear in `select` / `having` but not in `where`. Name is
+ * 'count' / 'sum' / 'avg' / 'min' / 'max'.
+ */
+declare class Aggregate<T = unknown> extends BaseExpression<T> {
+    name: string;
+    args: Array<BasicExpression>;
+    readonly type: "agg";
+    constructor(name: string, args: Array<BasicExpression>);
+}
+/**
+ * Correlated subquery projected into a parent select clause.
+ * Full runtime lands in Layer F (IVM); the class shape is shipped
+ * now so IR walkers can skip it cleanly.
+ */
+declare class IncludesSubquery extends BaseExpression {
+    /** Child query, with the correlation predicate stripped. */
+    query: QueryIR;
+    /** Parent-side correlation ref (e.g. `project.id`). */
+    correlationField: PropRef;
+    /** Child-side correlation ref (e.g. `issue.projectId`). */
+    childCorrelationField: PropRef;
+    /** Result field name on the parent row (e.g. `"issues"`). */
+    fieldName: string;
+    /** Parent-scope WHERE clauses to apply post-join. */
+    parentFilters?: Array<Where> | undefined;
+    /** Parent-scope refs consumed by `parentFilters`. */
+    parentProjection?: Array<PropRef> | undefined;
+    /** Shape of the projected result. Default 'collection'. */
+    materialization: IncludesMaterialization;
+    /** Field name when materialization is 'concat' scalar. */
+    scalarField?: string | undefined;
+    readonly type: "includesSubquery";
+    constructor(
+    /** Child query, with the correlation predicate stripped. */
+    query: QueryIR, 
+    /** Parent-side correlation ref (e.g. `project.id`). */
+    correlationField: PropRef, 
+    /** Child-side correlation ref (e.g. `issue.projectId`). */
+    childCorrelationField: PropRef, 
+    /** Result field name on the parent row (e.g. `"issues"`). */
+    fieldName: string, 
+    /** Parent-scope WHERE clauses to apply post-join. */
+    parentFilters?: Array<Where> | undefined, 
+    /** Parent-scope refs consumed by `parentFilters`. */
+    parentProjection?: Array<PropRef> | undefined, 
+    /** Shape of the projected result. Default 'collection'. */
+    materialization?: IncludesMaterialization, 
+    /** Field name when materialization is 'concat' scalar. */
+    scalarField?: string | undefined);
+}
+/**
+ * Detects whether `value` is an IR expression object. Used by ref-
+ * proxy conversion and compiler walks. Matches upstream semantics.
+ */
+declare function isExpressionLike(value: unknown): boolean;
+/** Extract the boolean expression from a `Where` entry. */
+declare function getWhereExpression(where: Where): BasicExpression<boolean>;
+/**
+ * Extract the expression from a `Having` entry. HAVING clauses may
+ * contain aggregates, unlike plain WHERE.
+ */
+declare function getHavingExpression(having: Having): BasicExpression | Aggregate;
+/** Is this `Where` entry marked residual (post-index-scan)? */
+declare function isResidualWhere(where: Where): boolean;
+/** Wrap a bare boolean expression as a residual `Where`. */
+declare function createResidualWhere(expression: BasicExpression<boolean>): Where;
+/**
+ * Walk a `PropRef`'s first alias segment back through any
+ * enclosing `QueryRef`s to reach the underlying `Collection` and
+ * the remaining column-path. Returns `undefined` if the ref can't
+ * be resolved to a collection (e.g. it points at a computed
+ * SELECT field; Layer F's optimizer is the only caller today).
+ */
+declare function followRef(query: QueryIR, ref: PropRef<unknown>, collection: Collection): {
+    collection: Collection;
+    path: Array<string>;
+} | undefined;
+
+type ir_Aggregate<T = unknown> = Aggregate<T>;
+declare const ir_Aggregate: typeof Aggregate;
+type ir_BasicExpression<T = unknown> = BasicExpression<T>;
+type ir_CollectionRef = CollectionRef;
+declare const ir_CollectionRef: typeof CollectionRef;
+type ir_CompareOptions = CompareOptions;
+type ir_From = From;
+type ir_Func<T = unknown> = Func<T>;
+declare const ir_Func: typeof Func;
+type ir_GroupBy = GroupBy;
+type ir_Having = Having;
+declare const ir_INCLUDES_SCALAR_FIELD: typeof INCLUDES_SCALAR_FIELD;
+type ir_IncludesMaterialization = IncludesMaterialization;
+type ir_IncludesSubquery = IncludesSubquery;
+declare const ir_IncludesSubquery: typeof IncludesSubquery;
+type ir_Join = Join;
+type ir_JoinClause = JoinClause;
+type ir_Limit = Limit;
+type ir_NamespacedRow = NamespacedRow;
+type ir_Offset = Offset;
+type ir_OrderBy = OrderBy;
+type ir_OrderByClause = OrderByClause;
+type ir_OrderByDirection = OrderByDirection;
+type ir_PropRef<T = unknown> = PropRef<T>;
+declare const ir_PropRef: typeof PropRef;
+type ir_QueryIR = QueryIR;
+type ir_QueryRef = QueryRef;
+declare const ir_QueryRef: typeof QueryRef;
+type ir_Select = Select;
+type ir_Value<T = unknown> = Value<T>;
+declare const ir_Value: typeof Value;
+type ir_Where = Where;
+declare const ir_createResidualWhere: typeof createResidualWhere;
+declare const ir_followRef: typeof followRef;
+declare const ir_getHavingExpression: typeof getHavingExpression;
+declare const ir_getWhereExpression: typeof getWhereExpression;
+declare const ir_isExpressionLike: typeof isExpressionLike;
+declare const ir_isResidualWhere: typeof isResidualWhere;
+declare namespace ir {
+  export { ir_Aggregate as Aggregate, type ir_BasicExpression as BasicExpression, ir_CollectionRef as CollectionRef, type ir_CompareOptions as CompareOptions, type ir_From as From, ir_Func as Func, type ir_GroupBy as GroupBy, type ir_Having as Having, ir_INCLUDES_SCALAR_FIELD as INCLUDES_SCALAR_FIELD, type ir_IncludesMaterialization as IncludesMaterialization, ir_IncludesSubquery as IncludesSubquery, type ir_Join as Join, type ir_JoinClause as JoinClause, type ir_Limit as Limit, type ir_NamespacedRow as NamespacedRow, type ir_Offset as Offset, type ir_OrderBy as OrderBy, type ir_OrderByClause as OrderByClause, type ir_OrderByDirection as OrderByDirection, ir_PropRef as PropRef, type ir_QueryIR as QueryIR, ir_QueryRef as QueryRef, type ir_Select as Select, ir_Value as Value, type ir_Where as Where, ir_createResidualWhere as createResidualWhere, ir_followRef as followRef, ir_getHavingExpression as getHavingExpression, ir_getWhereExpression as getWhereExpression, ir_isExpressionLike as isExpressionLike, ir_isResidualWhere as isResidualWhere };
+}
+
+/**
+ * Expression helpers — `@tanstack/db` parity (Layer C.3).
+ *
+ * Each helper returns a `BasicExpression` (PropRef / Value / Func)
+ * or `Aggregate` node. Comparison / logical / string / numeric /
+ * null / aggregate helpers all route literals and ref-proxies
+ * through `toExpression`.
+ *
+ * Runtime behavior matches `@tanstack/db/query/builder/functions.js`.
+ * Type layer is loosened (we type operands as `unknown`) because
+ * upstream's deep inference machinery (`ComparisonOperand`,
+ * `AggregateReturnType`, `CoalesceReturnType`, etc.) is Layer-G work;
+ * users still get good IDE support because the return types (`Func`,
+ * `Aggregate`) are narrow IR nodes, and the builder callbacks
+ * receive typed ref proxies.
+ *
+ * Also exports:
+ *   - `operators`           — runtime array of all operator names.
+ *   - `comparisonFunctions` — subset that indexes can accept.
+ *   - `OperatorName`        — union of operator literals.
+ *   - `ToArrayWrapper` / `ConcatToArrayWrapper` / `toArray` — IR
+ *     wrappers for sub-query projection. Compiled in Layer C.5.
+ */
+
+declare function eq(left: unknown, right: unknown): BasicExpression<boolean>;
+declare function gt(left: unknown, right: unknown): BasicExpression<boolean>;
+declare function gte(left: unknown, right: unknown): BasicExpression<boolean>;
+declare function lt(left: unknown, right: unknown): BasicExpression<boolean>;
+declare function lte(left: unknown, right: unknown): BasicExpression<boolean>;
+declare function and(left: unknown, right: unknown, ...rest: Array<unknown>): BasicExpression<boolean>;
+declare function or(left: unknown, right: unknown, ...rest: Array<unknown>): BasicExpression<boolean>;
+declare function not(value: unknown): BasicExpression<boolean>;
+declare function isUndefined(value: unknown): BasicExpression<boolean>;
+declare function isNull(value: unknown): BasicExpression<boolean>;
+/**
+ * `inArray(value, array)` — operator name is `'in'` in IR (matches
+ * upstream) even though the helper is named `inArray`.
+ */
+declare function inArray(value: unknown, array: unknown): BasicExpression<boolean>;
+declare function like(left: unknown, right: unknown): BasicExpression<boolean>;
+declare function ilike(left: unknown, right: unknown): BasicExpression<boolean>;
+declare function upper(arg: unknown): BasicExpression<string | null | undefined>;
+declare function lower(arg: unknown): BasicExpression<string | null | undefined>;
+declare function length(arg: unknown): BasicExpression<number | null | undefined>;
+/**
+ * `concat(...args)` — string concatenation. When a single
+ * `ToArrayWrapper` argument is passed (subquery projection), wraps
+ * it in `ConcatToArrayWrapper` so the compiler projects into a
+ * joined string. Multiple `ToArrayWrapper` args are not supported
+ * (matches upstream error).
+ */
+declare function concat(...args: Array<unknown>): BasicExpression<string> | ConcatToArrayWrapper;
+declare function add(left: unknown, right: unknown): BasicExpression<number | null | undefined>;
+declare function subtract(left: unknown, right: unknown): BasicExpression<number>;
+declare function multiply(left: unknown, right: unknown): BasicExpression<number>;
+declare function divide(left: unknown, right: unknown): BasicExpression<number | null>;
+declare function coalesce(first: unknown, ...rest: Array<unknown>): BasicExpression;
+/** Scalar CASE WHEN expression. Conditions and values alternate; an odd final
+ * argument is the default value. Without a default, unmatched rows yield null. */
+declare function caseWhen(...args: Array<unknown>): BasicExpression;
+declare function count(arg: unknown): Aggregate<number>;
+declare function avg(arg: unknown): Aggregate<number | null | undefined>;
+declare function sum(arg: unknown): Aggregate<number | null | undefined>;
+declare function min(arg: unknown): Aggregate;
+declare function max(arg: unknown): Aggregate;
+/** Comparison operators accepted by index implementations. */
+declare const comparisonFunctions: readonly ["eq", "gt", "gte", "lt", "lte", "in", "like", "ilike"];
+/** All supported operator names. Matches upstream. */
+declare const operators: readonly ["eq", "gt", "gte", "lt", "lte", "in", "like", "ilike", "and", "or", "not", "isNull", "isUndefined", "upper", "lower", "length", "concat", "add", "subtract", "multiply", "divide", "coalesce", "caseWhen", "count", "avg", "sum", "min", "max"];
+type OperatorName = (typeof operators)[number];
+/**
+ * Marker for `toArray(q)` — materializes a sub-query as an array
+ * projected into the parent SELECT. Compile path lands in C.5;
+ * the class is shipped now so type-resolution in builder / helpers
+ * works.
+ */
+declare class ToArrayWrapper<_T = unknown> {
+    readonly query: unknown;
+    readonly __brand: "ToArrayWrapper";
+    readonly _type: 'toArray';
+    readonly _result: _T;
+    constructor(query: unknown);
+}
+/**
+ * Marker for `concat(toArray(q))` — string-joins the projected
+ * sub-query rows. Compile path lands in C.5.
+ */
+declare class ConcatToArrayWrapper<_T = unknown> {
+    readonly query: unknown;
+    readonly __brand: "ConcatToArrayWrapper";
+    readonly _type: 'concatToArray';
+    readonly _result: _T;
+    constructor(query: unknown);
+}
+declare class MaterializeWrapper<_T = unknown, _IsSingle extends boolean = boolean> {
+    readonly query: unknown;
+    readonly __brand: "MaterializeWrapper";
+    readonly _type: 'materialize';
+    readonly _result: _T;
+    readonly _isSingle: _IsSingle;
+    constructor(query: unknown);
+}
+/**
+ * Wrap a QueryBuilder as an array-result sub-query. Used as a
+ * SELECT field value: `select(({p, children}) => ({ p, children:
+ * toArray(children) }))`. Compile path in C.5.
+ */
+declare function toArray(query: unknown): ToArrayWrapper;
+declare function materialize(query: unknown): MaterializeWrapper;
+
+interface RangeQueryOptions {
+    from?: unknown;
+    to?: unknown;
+    fromInclusive?: boolean;
+    toInclusive?: boolean;
+}
+
+/** Operations that index implementations can support. */
+declare const IndexOperation: readonly ["eq", "gt", "gte", "lt", "lte", "in", "like", "ilike"];
+type IndexOperation = (typeof comparisonFunctions)[number];
+/** Statistics about index usage and performance. */
+interface IndexStats {
+    readonly entryCount: number;
+    readonly lookupCount: number;
+    readonly averageLookupTime: number;
+    readonly lastUpdated: Date;
+}
+interface IndexInterface<TKey extends string | number = string | number> {
+    add(key: TKey, item: unknown): void;
+    remove(key: TKey, item: unknown): void;
+    update(key: TKey, oldItem: unknown, newItem: unknown): void;
+    build(entries: Iterable<[TKey, unknown]>): void;
+    clear(): void;
+    lookup(operation: IndexOperation, value: unknown): Set<TKey>;
+    equalityLookup(value: unknown): Set<TKey>;
+    inArrayLookup(values: Array<unknown>): Set<TKey>;
+    rangeQuery(options?: RangeQueryOptions): Set<TKey>;
+    rangeQueryReversed(options?: RangeQueryOptions): Set<TKey>;
+    take(n: number, from?: unknown, filterFn?: (key: TKey) => boolean): Array<TKey>;
+    takeFromStart(n: number, filterFn?: (key: TKey) => boolean): Array<TKey>;
+    takeReversed(n: number, from?: unknown, filterFn?: (key: TKey) => boolean): Array<TKey>;
+    takeReversedFromEnd(n: number, filterFn?: (key: TKey) => boolean): Array<TKey>;
+    get keyCount(): number;
+    get orderedEntriesArray(): Array<[unknown, Set<TKey>]>;
+    get orderedEntriesArrayReversed(): Array<[unknown, Set<TKey>]>;
+    get indexedKeysSet(): Set<TKey>;
+    get valueMapData(): Map<unknown, Set<TKey>>;
+    supports(operation: IndexOperation): boolean;
+    matchesField(fieldPath: Array<string>): boolean;
+    matchesCompareOptions(compareOptions: CompareOptions): boolean;
+    matchesDirection(direction: OrderByDirection): boolean;
+    getStats(): IndexStats;
+}
+/** Base abstract class that all index types extend. */
+declare abstract class BaseIndex<TKey extends string | number = string | number> implements IndexInterface<TKey> {
+    readonly id: number;
+    readonly name?: string;
+    readonly expression: BasicExpression;
+    abstract readonly supportedOperations: Set<IndexOperation>;
+    protected lookupCount: number;
+    protected totalLookupTime: number;
+    protected lastUpdated: Date;
+    protected compareOptions: CompareOptions;
+    constructor(id: number, expression: BasicExpression, name?: string, options?: unknown);
+    abstract add(key: TKey, item: unknown): void;
+    abstract remove(key: TKey, item: unknown): void;
+    abstract update(key: TKey, oldItem: unknown, newItem: unknown): void;
+    abstract build(entries: Iterable<[TKey, unknown]>): void;
+    abstract clear(): void;
+    abstract lookup(operation: IndexOperation, value: unknown): Set<TKey>;
+    abstract equalityLookup(value: unknown): Set<TKey>;
+    abstract inArrayLookup(values: Array<unknown>): Set<TKey>;
+    abstract rangeQuery(options?: RangeQueryOptions): Set<TKey>;
+    abstract rangeQueryReversed(options?: RangeQueryOptions): Set<TKey>;
+    abstract take(n: number, from?: unknown, filterFn?: (key: TKey) => boolean): Array<TKey>;
+    abstract takeFromStart(n: number, filterFn?: (key: TKey) => boolean): Array<TKey>;
+    abstract takeReversed(n: number, from?: unknown, filterFn?: (key: TKey) => boolean): Array<TKey>;
+    abstract takeReversedFromEnd(n: number, filterFn?: (key: TKey) => boolean): Array<TKey>;
+    abstract get keyCount(): number;
+    abstract get orderedEntriesArray(): Array<[unknown, Set<TKey>]>;
+    abstract get orderedEntriesArrayReversed(): Array<[unknown, Set<TKey>]>;
+    abstract get indexedKeysSet(): Set<TKey>;
+    abstract get valueMapData(): Map<unknown, Set<TKey>>;
+    protected abstract initialize(options?: unknown): void;
+    supports(operation: IndexOperation): boolean;
+    matchesField(fieldPath: Array<string>): boolean;
+    /** Checks compare options; direction ignored because ReverseIndex can flip traversal. */
+    matchesCompareOptions(compareOptions: CompareOptions): boolean;
+    matchesDirection(direction: OrderByDirection): boolean;
+    getStats(): IndexStats;
+    protected evaluateIndexExpression(item: unknown): unknown;
+    protected trackLookup(startTime: number): void;
+    protected updateTimestamp(): void;
+}
+/** Type for index constructors. */
+type IndexConstructor<TKey extends string | number = string | number> = new (id: number, expression: BasicExpression, name?: string, options?: any) => BaseIndex<TKey>;
+
+interface IndexOptions<TIndexType extends IndexConstructor = IndexConstructor> {
+    /** Optional name for the index. */
+    name?: string;
+    /** Index implementation to instantiate, e.g. BasicIndex or BTreeIndex. */
+    indexType?: TIndexType;
+    /** Options passed to the index constructor. */
+    options?: TIndexType extends new (id: number, expr: any, name?: string, options?: infer O) => unknown ? O : never;
+}
+
+/**
+ * Change event emitted by Collection after each mutation, consumed by the
+ * reactive query engine.
+ *
+ * `columns` is an explicit set of column names that were written. Deletions
+ * (soft) touch `__deleted` only; rollbacks may emit `columns: 'all'` when a
+ * rollback re-inserts a snapshot.
+ */
+type ChangeOp = 'insert' | 'update' | 'delete' | 'rollback' | 'compact';
+interface ChangeEvent {
+    readonly op: ChangeOp;
+    readonly rowId: number;
+    /** Columns written by this mutation, or 'all' when unknown / broad. */
+    readonly columns: ReadonlySet<string> | 'all';
+    /** Monotonic collection global version after the mutation. */
+    readonly globalVersion: number;
+    /**
+     * Current row snapshot after the mutation.
+     *
+     * For `insert` and `update` ops: the full row as it exists post-mutation.
+     * For `delete` op (soft or hard): the final row state — for soft-deletes
+     *   this is the row with `__deleted: true`; for hard-deletes it's the
+     *   last snapshot before removal (taken from the undo log).
+     * For `rollback` and `compact`: may be undefined if the snapshot would
+     *   be expensive to reconstruct and no consumer needs it.
+     *
+     * Exists so `subscribeChanges` adapters (TanStack DB `ChangeMessage`
+     * shape) can emit the `value` field without re-reading the collection,
+     * which is critical for delete events where the row is gone.
+     */
+    readonly value?: Readonly<Record<string, unknown>>;
+    /**
+     * For `update` ops only: the subset of columns as they were before the
+     * mutation. Keys match the entries in `columns`. Absent for other ops.
+     */
+    readonly previousValue?: Readonly<Record<string, unknown>>;
+    /**
+     * Optional decomposed high-level changes for broad events like rollback.
+     * Kept structurally typed here to avoid coupling the low-level emitter to
+     * TanStack-facing public types.
+     */
+    readonly changes?: ReadonlyArray<{
+        key: number;
+        value: Readonly<Record<string, unknown>>;
+        previousValue?: Readonly<Record<string, unknown>>;
+        type: 'insert' | 'update' | 'delete';
+    }>;
+}
+type ChangeListener = (event: ChangeEvent) => void;
+/**
+ * Simple synchronous emitter. Listeners are invoked in insertion order. An
+ * error thrown by a listener is caught and logged so subsequent listeners
+ * still run — this keeps mutation correctness independent of query bugs.
+ */
+declare class ChangeEmitter {
+    private listeners;
+    subscribe(listener: ChangeListener): () => void;
+    emit(event: ChangeEvent): void;
+    get size(): number;
+}
+
+type MutateCallbackResult = void | PromiseLike<void>;
+declare function createTransaction<T extends object = Record<string, unknown>>(config: TransactionConfig<T>): Transaction<T>;
+declare function getActiveTransaction(): Transaction | undefined;
+declare class Transaction<T extends object = Record<string, unknown>> {
+    readonly id: string;
+    readonly mutationFn: MutationFn<T>;
+    readonly mutations: Array<PendingMutation<T>>;
+    readonly isPersisted: Deferred<Transaction<T>>;
+    readonly autoCommit: boolean;
+    readonly createdAt: Date;
+    readonly sequenceNumber: number;
+    readonly metadata: Record<string, unknown>;
+    private readonly rollbackHandlers;
+    state: TransactionState;
+    error?: {
+        message: string;
+        error: Error;
+    };
+    constructor(config: TransactionConfig<T>);
+    setState(newState: TransactionState): void;
+    mutate(callback: () => MutateCallbackResult): Transaction<T>;
+    addRollbackHandler(handler: () => void): void;
+    applyMutations(mutations: Array<PendingMutation<any>>): void;
+    rollback(config?: {
+        isSecondaryRollback?: boolean;
+    }): Transaction<T>;
+    touchCollection(): void;
+    commit(): Promise<Transaction<T>>;
+    compareCreatedAt(other: Transaction<any>): number;
+}
+
+/**
+ * Per-column append-only byte heap used by Utf8 columns. Strings are written
+ * contiguously; each row owns a `[start, end)` byte range stored externally
+ * in the column's offsets buffer. Updates always append fresh bytes at the
+ * tail — old bytes are leaked until a future compaction pass.
+ *
+ * The heap is a Uint8Array view onto the segment; we own only the bump
+ * cursor and encoder/decoder.
+ */
+declare class ValuesHeap {
+    private cursor;
+    private readonly bytes;
+    private readonly encoder;
+    private readonly decoder;
+    constructor(bytes: Uint8Array);
+    /** Current bump position (= first free byte). */
+    get used(): number;
+    /** Total capacity in bytes. */
+    get capacity(): number;
+    /** Read-only view of the underlying byte buffer. Used by snapshot export. */
+    get rawBytes(): Uint8Array;
+    /** Append raw bytes; returns their `[start, end)` range. */
+    appendBytes(src: Uint8Array): {
+        start: number;
+        end: number;
+    };
+    /**
+     * Encode `value` as UTF-8 and append to the heap. Returns the byte range
+     * `[start, end)` where the encoded bytes live.
+     */
+    append(value: string): {
+        start: number;
+        end: number;
+    };
+    /** Decode a `[start, end)` byte range back to a string. */
+    read(start: number, end: number): string;
+    /** Read a `[start, end)` range as a copy of raw bytes. */
+    readBytes(start: number, end: number): Uint8Array;
+    /**
+     * Copy bytes `[start, end)` from this heap directly into `dest` starting
+     * at `destOffset`. No allocation. Used by compaction to shuffle live
+     * ranges without a per-row Uint8Array allocation.
+     */
+    copyInto(start: number, end: number, dest: Uint8Array, destOffset: number): void;
+    /**
+     * Reset the cursor to zero. The caller must have already copied any live
+     * ranges elsewhere. Used by `Collection.compact()`.
+     */
+    resetEmpty(): void;
+    /**
+     * Overwrite the heap with `src[0..length)` starting at byte 0 and set
+     * the cursor to `length`. Caller guarantees `length <= capacity`. Used
+     * by `Collection.compact()` to swap a rebuilt heap back in place.
+     */
+    rewrite(src: Uint8Array, length: number): void;
+}
+/**
+ * Side table for a dictionary-encoded Utf8 column. Code 0 is the first
+ * interned string — nulls are signalled via the column's validity bitmap,
+ * not via a reserved code.
+ *
+ * Dictionary is append-only in Phase 3. A later phase may add reference
+ * counts and compaction.
+ */
+declare class Dictionary {
+    private codeByString;
+    private stringByCode;
+    /** Number of distinct strings currently interned. */
+    get size(): number;
+    /** Return the code for `s`, interning it if absent. */
+    intern(s: string): number;
+    /** Return the code for `s`, or undefined if not interned. */
+    lookup(s: string): number | undefined;
+    /** Decode a code back to its string. Throws on unknown codes. */
+    decode(code: number): string;
+    /** Iterate all (code, string) pairs in insertion order. */
+    entries(): IterableIterator<[number, string]>;
+}
+
+type Point = readonly [lng: number, lat: number];
+
+type BBox = readonly [minX: number, minY: number, maxX: number, maxY: number];
+
+type LineString = readonly Point[];
+
+type LinearRing = readonly Point[];
+type Polygon = readonly LinearRing[];
+
+/** Row value for a schema with primitive + utf8 + binary + list + struct + geo columns. */
+type RowValue = Record<string, number | bigint | boolean | string | Uint8Array | readonly unknown[] | Record<string, unknown> | Point | LineString | Polygon | null>;
+/**
+ * Collection lifecycle status. Mirrors `@tanstack/db`'s
+ * `CollectionStatus` union bit-for-bit:
+ *
+ * - `idle`       — created but sync not started (used only with
+ *                  `startSync: false` sync configs).
+ * - `loading`    — sync has started and is loading.
+ * - `ready`      — collection is usable; data available.
+ * - `error`      — sync initialization failed.
+ * - `cleaned-up` — resources released; no further use.
+ *
+ * In-memory collections (our current default) start in `'ready'` and
+ * only transition to `'cleaned-up'` via `cleanup()`.
+ */
+type CollectionStatus = 'idle' | 'loading' | 'ready' | 'error' | 'cleaned-up';
+/**
+ * Payload for the `status:change` event. Matches @tanstack/db's
+ * `CollectionStatusChangeEvent`.
+ */
+interface CollectionStatusChangeEvent {
+    type: 'status:change';
+    collection: Collection;
+    previousStatus: CollectionStatus;
+    status: CollectionStatus;
+}
+/**
+ * Payload for `subscribers:change`. Fires whenever the number of
+ * `subscribeChanges` subscribers grows or shrinks.
+ */
+interface CollectionSubscribersChangeEvent {
+    type: 'subscribers:change';
+    collection: Collection;
+    previousSubscriberCount: number;
+    subscriberCount: number;
+}
+/**
+ * Payload for `truncate`. Fires when the backing sync source has
+ * instructed us to drop all rows (e.g. after a must-refetch
+ * signal). Currently unused at the collection layer but exposed
+ * for parity; Layer E wires it up.
+ */
+interface CollectionTruncateEvent {
+    type: 'truncate';
+    collection: Collection;
+}
+/**
+ * All events a Collection can emit. Matches @tanstack/db's
+ * `AllCollectionEvents` in shape (minus index-add/remove, which
+ * land in Layer D, and loadingSubset, which is subset-load-only).
+ */
+type CollectionEvents = {
+    'status:change': CollectionStatusChangeEvent;
+    'subscribers:change': CollectionSubscribersChangeEvent;
+    truncate: CollectionTruncateEvent;
+    'status:idle': CollectionStatusChangeEvent;
+    'status:loading': CollectionStatusChangeEvent;
+    'status:ready': CollectionStatusChangeEvent;
+    'status:error': CollectionStatusChangeEvent;
+    'status:cleaned-up': CollectionStatusChangeEvent;
+};
+type IndexExpressionCallback = (row: SingleRowRefProxy<Record<string, unknown>>) => unknown;
+type CollectionIndexOptions = IndexOptions<IndexConstructor<number>>;
+type AutoIndexMode = 'off' | 'eager';
+interface SpatialIndexOptions {
+    readonly column: string;
+    readonly type: 'rtree';
+    readonly eager?: boolean;
+}
+type SpatialIndexConfig = SpatialIndexOptions | readonly SpatialIndexOptions[];
+interface CollectionRuntimeConfig {
+    autoIndex: AutoIndexMode;
+    defaultIndexType?: IndexConstructor<number>;
+    spatialIndex?: SpatialIndexConfig;
+}
+interface CollectionOptions {
+    /** Maximum number of rows the collection can hold. Required in Phase 1. */
+    capacity: number;
+    /** Undo ring capacity in entries. Default 4096. */
+    undoCapacity?: number;
+    /**
+     * When true, `delete(id)` sets a `__deleted` flag and keeps the row slot.
+     * The column must be declared in the schema as `{ type: 'bool' }`.
+     * Defaults to true if `__deleted` column exists, else false.
+     */
+    softDelete?: boolean;
+    /**
+     * Optional stable identifier for the collection. Mirrors
+     * `@tanstack/db`'s `CollectionConfig.id`. Defaults to
+     * `${schema.name}:${monotonicCounter}`. Used for debugging,
+     * devtools, and as a key in broadcast/sync adapters.
+     */
+    id?: string;
+    /**
+     * Utility functions attached to this collection. Exposed via the
+     * `utils` getter. Callers can use these to plumb collection-specific
+     * helpers (e.g. `refetch`, `setState`) without subclassing. Matches
+     * `@tanstack/db`'s `CollectionConfig.utils`.
+     */
+    utils?: UtilsRecord;
+    /**
+     * String collation config — influences `orderBy` over string
+     * columns. Currently stored and echoed through `compareOptions`; the
+     * query layer picks it up in Layer C. Matches `@tanstack/db`'s
+     * `CollectionConfig.compareOptions`.
+     */
+    compareOptions?: StringCollationConfig;
+    /** Auto-index strategy. `eager` creates indexes for simple subscribed where expressions. */
+    autoIndex?: AutoIndexMode;
+    /** Default index implementation used by auto-index and option-less createIndex. */
+    defaultIndexType?: IndexConstructor<number>;
+    /** Optional R-tree index config for point/linestring/polygon envelopes. */
+    spatialIndex?: SpatialIndexConfig;
+}
+type TypedValueArray = Int8Array | Int16Array | Int32Array | Uint8Array | Uint16Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
+/**
+ * Internal scan-view entry exposed via `_internalScanColumns()` for the
+ * vectorized kernel. Not part of the public API surface — may change.
+ */
+interface ScanColumn {
+    readonly name: string;
+    readonly typeCode: ColumnTypeCode;
+    readonly nullable: boolean;
+    readonly validity: Uint8Array | null;
+    readonly values: TypedValueArray;
+    readonly heap: ValuesHeap | null;
+    readonly dictionary: Dictionary | null;
+}
+/**
+ * Tree-shaped view emitted by `bulkColumnViewsTree()` for the snapshot
+ * exporter. Internal surface — subject to change.
+ */
+interface TreeView {
+    readonly name: string;
+    readonly type: ColumnTypeName;
+    readonly typeCode: ColumnTypeCode;
+    readonly nullable: boolean;
+    readonly validity: Uint8Array | null;
+    readonly primaryBuffer: Uint8Array;
+    readonly heap: Uint8Array | null;
+    readonly dictionaryEntries: readonly string[] | null;
+    readonly listChildElements?: number;
+    readonly listChild?: TreeView;
+    readonly fields?: readonly TreeView[];
+}
+/**
+ * Phase 1 Collection: fixed-capacity, fixed-width primitive columns, dense
+ * `uint32` PK, single-writer. No cross-worker attach yet (Segment is created
+ * locally); the SAB buffer is exposed via `getSegmentBuffer()` for future
+ * worker handoff.
+ */
+declare class Collection {
+    readonly schema: CompiledSchema;
+    readonly capacity: number;
+    private readonly segment;
+    private readonly columns;
+    private readonly columnList;
+    private readonly rowIndex;
+    private readonly undo;
+    private readonly pkColumn;
+    private readonly deletedColumn;
+    private readonly softDelete;
+    private readonly emitter;
+    /**
+     * TanStack-DB-compatible high-level event emitter. Handles
+     * `status:change`, `subscribers:change`, `truncate`, `index:added`,
+     * `index:removed`, and per-status events. Separate from the
+     * low-level per-mutation `ChangeEmitter` above because the event
+     * cadences differ: mutation events fire on every row touch; these
+     * fire on lifecycle transitions.
+     */
+    private readonly events;
+    /** Active secondary indexes keyed by monotonically assigned index id. */
+    private readonly _indexes;
+    /** Active geometry-envelope spatial indexes keyed by column name. */
+    private readonly _spatialIndexes;
+    private _nextIndexId;
+    /**
+     * Tracks external subscribers created via `subscribeChanges`. Used
+     * by `subscriberCount` getter and emitted via `subscribers:change`.
+     */
+    private _subscriberCount;
+    /** Dense row cursor: next row slot to use. */
+    private rowCursor;
+    /** Monotonic collection-wide version counter. */
+    private _globalVersion;
+    /** Stable identifier (see `id` getter). */
+    private readonly _id;
+    /** Utils record (see `utils` getter). */
+    private readonly _utils;
+    /** Compare options for string orderBy (see `compareOptions` getter). */
+    private readonly _compareOptions;
+    /** TanStack-shaped runtime collection config needed by index planning. */
+    private readonly _config;
+    /** Undo marks registered for optimistic transaction rollbacks. */
+    private readonly transactionRollbackMarks;
+    /** Attached sync source lifecycle state. */
+    private syncStarted;
+    private syncCleanup;
+    private constructor();
+    static create(schema: CompiledSchema, options: CollectionOptions): Collection;
+    /** Monotonic counter for default `id` assignment. */
+    private static _idCounter;
+    /** Number of live (non-deleted) rows. */
+    get size(): number;
+    /** Raw row slot count (including tombstoned rows for soft-delete). */
+    get rowCount(): number;
+    get globalVersion(): number;
+    /** Runtime collection config (TanStack-shaped subset). */
+    get config(): Readonly<CollectionRuntimeConfig>;
+    /** Read the version counter for a single column. */
+    columnVersion(name: string): number;
+    /** Expose the underlying segment buffer (for future worker handoff). */
+    getSegmentBuffer(): SharedArrayBuffer | ArrayBuffer;
+    /** Subscribe to mutation events. Returns an unsubscribe function. */
+    subscribe(listener: ChangeListener): () => void;
+    /** Count of active `subscribeChanges` subscribers. */
+    get subscriberCount(): number;
+    /**
+     * Subscribe to collection changes as TanStack DB `ChangeMessage[]`
+     * batches. The callback receives an array of change messages;
+     * batches contain a single message in Layer B (one message per
+     * mutation). Layer E's transaction machinery will coalesce
+     * multiple mutations into a single array when a tx commits.
+     *
+     * When `options.includeInitialState` is true, the callback is
+     * invoked synchronously with one `insert` message per current
+     * live row before any mutation-driven calls.
+     *
+     * Returns a `CollectionSubscription` handle; call `unsubscribe()`
+     * to detach. Reading `subscriberCount` also reflects the count.
+     */
+    subscribeChanges(callback: (changes: ChangeMessage<RowValue, number>[]) => void, options?: SubscribeChangesOptions): CollectionSubscription;
+    /**
+     * Return the current live state as an array of `insert`
+     * `ChangeMessage`s. Analogous to @tanstack/db's
+     * `currentStateAsChanges()`. Options are accepted for future
+     * compat (where / orderBy / limit) but are no-ops in Layer B;
+     * Layer C wires them up to the query path.
+     */
+    currentStateAsChanges(_options?: CurrentStateAsChangesOptions): ChangeMessage<RowValue, number>[];
+    /**
+     * Map a low-level `ChangeEvent` to a TanStack `ChangeMessage`.
+     * Returns null for `rollback`/`compact` — those don't have a 1:1
+     * representation in TanStack DB's model (they'd decompose into a
+     * series of inverse inserts/updates/deletes). Layer E will handle
+     * that decomposition; for now consumers that care must observe
+     * the low-level `subscribe()` channel.
+     */
+    private _changeEventToMessage;
+    private filterAndFlipSubscriptionChanges;
+    private _subscribeWhereExpression;
+    /** Type-safe event subscription. Returns an unsubscribe fn. */
+    on<K extends keyof CollectionEvents>(event: K, callback: (payload: CollectionEvents[K]) => void): () => void;
+    /** Subscribe for one emission of `event`. Returns unsubscribe fn. */
+    once<K extends keyof CollectionEvents>(event: K, callback: (payload: CollectionEvents[K]) => void): () => void;
+    /** Remove a specific `on`/`once` listener. */
+    off<K extends keyof CollectionEvents>(event: K, callback: (payload: CollectionEvents[K]) => void): void;
+    /**
+     * Await the next emission of `event`. Rejects with a timeout error
+     * if `timeout` ms elapse first. Matches @tanstack/db semantics.
+     */
+    waitFor<K extends keyof CollectionEvents>(event: K, timeout?: number): Promise<CollectionEvents[K]>;
+    /** List all column names in declaration order. */
+    columnNames(): readonly string[];
+    /** True when the collection has a soft-delete column active. */
+    get hasSoftDelete(): boolean;
+    /**
+     * Expose underlying buffer views to the snapshot exporter. Rows are
+     * emitted up to `rowCursor`, so consumers copy the *used* subregion
+     * of each typed-array buffer (not the whole allocated capacity). This
+     * keeps snapshots proportional to live data.
+     */
+    bulkColumnViews(): ReadonlyArray<{
+        name: string;
+        type: ColumnTypeName;
+        typeCode: ColumnTypeCode;
+        nullable: boolean;
+        validity: Uint8Array | null;
+        primaryBuffer: Uint8Array;
+        heap: Uint8Array | null;
+        dictionaryEntries: readonly string[] | null;
+    }>;
+    /**
+     * Tree-shaped column view for the snapshot exporter. Mirrors the
+     * compiled schema: list columns carry a `listChild` view; struct
+     * columns carry a `fields` array. Each leaf view is slice-copied
+     * up to the collection's current row cursor (for leaves) or list
+     * child cursor (for list children) so the snapshot size is
+     * proportional to live data.
+     */
+    bulkColumnViewsTree(): ReadonlyArray<TreeView>;
+    private buildTreeView;
+    /** Internal: restore the monotonic `globalVersion` after a snapshot import. */
+    _restoreGlobalVersionForSnapshot(version: number): void;
+    /**
+     * Internal low-level scan view for the query kernel. Exposes raw
+     * typed-array references + heap + dictionary so the kernel can read
+     * values by (column, row ordinal) without allocating a row object.
+     *
+     * The returned arrays are live views into the collection's storage.
+     * Do not mutate them. Their validity is bounded by the next mutation
+     * that may resize the segment (today the segment capacity is fixed,
+     * so views remain stable for the lifetime of the collection — but
+     * this is an implementation detail that can change).
+     */
+    _internalScanColumns(): readonly ScanColumn[];
+    /**
+     * Internal: yield live row ordinals (respecting soft-delete) in PK
+     * insertion order. The kernel iterates these to drive vectorized scans.
+     */
+    _internalLiveOrdinals(options?: {
+        includeSoftDeleted?: boolean;
+    }): IterableIterator<number>;
+    /**
+     * Internal: yield live row ordinals whose primary keys are in `keys`, preserving scan order.
+     */
+    _internalLiveOrdinalsForKeys(keys: ReadonlySet<number>): IterableIterator<number>;
+    /** Search an attached geometry-envelope index. Returns row ordinals. */
+    _internalSearchSpatialIndex(column: string, query: BBox): Uint32Array | undefined;
+    /** Resolve a primary key to its current row ordinal without materializing a row. */
+    _internalRowOrdinalForKey(key: number): number | undefined;
+    /** Evaluate a bbox predicate directly against the cached geometry envelope. */
+    _internalGeometryBboxMatches(column: string, row: number, query: BBox, mode: 'intersects' | 'within'): boolean;
+    /** Evaluate point distance directly against coordinate buffers. */
+    _internalPointDWithin(column: string, row: number, point: Point, meters: number): boolean;
+    /**
+     * Internal: read a single cell at (column, row) for the kernel. Used
+     * to materialize projected rows only after filter + sort + limit
+     * have produced a final ordinal list.
+     */
+    _internalReadCell(colName: string, row: number): RowValue[string];
+    /**
+     * Introspection view for devtools. Returns per-column metadata
+     * (version, null count, heap usage, dictionary sample) without
+     * exposing live buffers. `nullCount` walks the validity bitmap once
+     * per nullable column — O(rowCursor) total. Safe to call on a hot
+     * path but not a no-op.
+     */
+    describeColumnViews(): ReadonlyArray<{
+        name: string;
+        type: ColumnTypeName;
+        nullable: boolean;
+        version: number;
+        nullCount: number;
+        heap: {
+            used: number;
+            capacity: number;
+        } | null;
+        dictionaryEntries: readonly string[] | null;
+    }>;
+    insert(row: RowValue, config?: InsertConfig): Transaction<RowValue>;
+    update(id: number, patch: Partial<RowValue>): Transaction<RowValue>;
+    update(id: number, callback: (draft: RowValue) => void): Transaction<RowValue>;
+    update(id: number, config: OperationConfig, callback: Partial<RowValue> | ((draft: RowValue) => void)): Transaction<RowValue>;
+    delete(id: number, config?: OperationConfig): Transaction<RowValue>;
+    private applyCollectionMutation;
+    private registerTransactionRollback;
+    private shouldConfirmSyncedUpdates;
+    private callCollectionMutationHandler;
+    private createPendingMutation;
+    private resolveUpdatePatch;
+    private patchFromCallback;
+    private insertRaw;
+    private updateRaw;
+    private deleteRaw;
+    get(id: number): RowValue | undefined;
+    /**
+     * Iterate rows as plain JS objects.
+     *
+     * By default, soft-deleted rows are excluded. Pass
+     * `{ includeSoftDeleted: true }` to include them — useful for sync
+     * adapters that want to mirror tombstones to downstream stores.
+     */
+    rows(options?: {
+        includeSoftDeleted?: boolean;
+    }): IterableIterator<RowValue>;
+    /** Cached `Map<pk, row>` view. Built lazily on first read. */
+    private _stateCache;
+    /** `globalVersion` at the moment `_stateCache` was built. */
+    private _stateCacheVersion;
+    /** Cached dense `row[]` view. Built lazily on first read. */
+    private _toArrayCache;
+    /** `globalVersion` at the moment `_toArrayCache` was built. */
+    private _toArrayCacheVersion;
+    private _status;
+    private _firstReadyListeners;
+    private _firstReadyFired;
+    /** Promises awaiting `preload()` / `stateWhenReady()` / etc. */
+    private _readyPromise;
+    private _readyResolve;
+    /**
+     * Current lifecycle status of the collection. For in-memory
+     * collections this starts as `'ready'` and stays there until
+     * `cleanup()` transitions to `'cleaned-up'`.
+     */
+    get status(): CollectionStatus;
+    /** `true` iff status is `'ready'`. */
+    isReady(): boolean;
+    /**
+     * Register a callback that fires exactly once, the first time the
+     * collection becomes ready. If the collection is already ready, the
+     * callback is invoked on the next microtask (never synchronously, so
+     * ordering is predictable and matches @tanstack/db).
+     *
+     * Duplicate registrations are allowed; each registered callback
+     * fires at most once.
+     */
+    onFirstReady(callback: () => void): void;
+    /**
+     * Internal helper for lifecycle machinery to mark the collection as
+     * ready. Not exposed publicly — callers use the sync-config
+     * `markReady` callback instead. For in-memory collections this is
+     * invoked once during construction.
+     */
+    private _markReady;
+    /**
+     * Returns a promise that resolves when the collection is ready.
+     * Resolves immediately if already ready. No-op for in-memory
+     * collections after the first construction microtask.
+     */
+    preload(): Promise<void>;
+    /**
+     * Request eager synchronous start of any attached sync source. For
+     * pure in-memory collections this is a no-op; the hook exists so
+     * sync-backed subclasses / configs can override it without breaking
+     * the TanStack surface.
+     */
+    startSyncImmediate(): void;
+    private primaryKeyFromMessage;
+    private patchFromSyncValue;
+    private applySyncMessage;
+    private truncateFromSync;
+    /**
+     * Resolves with a Map snapshot of the collection once ready. After
+     * the collection is ready this is equivalent to reading `state`
+     * (still reuses the lazy cache).
+     */
+    stateWhenReady(): Promise<Map<number, RowValue>>;
+    /**
+     * Resolves with a dense array snapshot once ready.
+     */
+    toArrayWhenReady(): Promise<RowValue[]>;
+    /** Stable collection identifier. Matches @tanstack/db's `Collection.id`. */
+    get id(): string;
+    /**
+     * Collection-scoped utility record. Callers can plumb helper
+     * functions (e.g. `refetch`, `reset`, `prefetchPage`) via
+     * `CollectionOptions.utils`. The getter returns the live record;
+     * mutating it after construction is NOT recommended but not
+     * forbidden (matches @tanstack/db).
+     */
+    get utils(): UtilsRecord;
+    /**
+     * String collation config for orderBy on string columns. Matches
+     * `@tanstack/db`'s `Collection.compareOptions`. Defaults to
+     * `{ stringSort: 'lexical' }` when not configured.
+     */
+    get compareOptions(): StringCollationConfig;
+    /**
+     * Whether a sync-layer subset load is in flight. Always `false`
+     * for in-memory collections (no subset loading). Present for
+     * @tanstack/db parity; sync-backed collections override.
+     */
+    get isLoadingSubset(): boolean;
+    /** Secondary indexes attached to this collection. */
+    get indexes(): ReadonlyMap<number, IndexInterface<number>>;
+    createIndex(callback: IndexExpressionCallback, options?: CollectionIndexOptions): IndexInterface<number>;
+    /**
+     * Return the primary key value of a row-shaped item. Matches
+     * `@tanstack/db`'s `Collection.getKeyFromItem(item)`. Reads the
+     * schema's PK column from the given row.
+     *
+     * @throws ValidationError if the PK column is missing from `item`.
+     */
+    getKeyFromItem(item: Readonly<RowValue>): number;
+    /**
+     * Validate a data record against the collection schema. Matches
+     * `@tanstack/db`'s `Collection.validateData(data, type, key?)`.
+     *
+     * For `'insert'`: every column declared in the schema must be
+     * present (or nullable-null) and typed correctly.
+     * For `'update'`: only provided columns are checked; the PK column
+     * must NOT appear in the patch.
+     *
+     * Returns the validated data (same shape as input on success).
+     * Throws `ValidationError` on failure — matches the reference's
+     * `TOutput | never` return shape.
+     */
+    validateData(data: unknown, type: 'insert' | 'update', _key?: number): RowValue;
+    /**
+     * Release resources: detach every `subscribeChanges`/`on` listener,
+     * drop cached state, clear the undo ring, transition status to
+     * `'cleaned-up'`. Idempotent; subsequent mutations will still work
+     * but no longer notify external subscribers.
+     *
+     * Matches `@tanstack/db`'s `Collection.cleanup()`. Async for
+     * parity; the in-memory implementation completes after a single
+     * microtask so `await cleanup()` returns on the next tick.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Return true if the collection contains a live (non-soft-deleted)
+     * row with the given primary key.
+     */
+    has(id: number): boolean;
+    /**
+     * Iterate primary keys of live rows in insertion order.
+     *
+     * Matches `Map.prototype.keys()` shape.
+     */
+    keys(): IterableIterator<number>;
+    /**
+     * Iterate live row values. Identical to `rows()` with default
+     * options — provided under the TanStack DB-compatible name.
+     */
+    values(): IterableIterator<RowValue>;
+    /**
+     * Iterate `[pk, row]` tuples for live rows.
+     *
+     * Matches `Map.prototype.entries()` shape.
+     */
+    entries(): IterableIterator<[number, RowValue]>;
+    /**
+     * Apply `callback(value, key, index)` to every live row. `index` is
+     * the 0-based position in the live sequence (not the underlying row
+     * slot).
+     */
+    forEach(callback: (value: RowValue, key: number, index: number) => void): void;
+    /**
+     * Like `Array.prototype.map`, but over live rows. Returns a dense
+     * array. Matches `@tanstack/db` CollectionImpl.map.
+     */
+    map<U>(callback: (value: RowValue, key: number, index: number) => U): U[];
+    /**
+     * Map of live rows keyed by primary key. Materialized lazily on
+     * first access and cached until the next mutation bumps
+     * `globalVersion`.
+     *
+     * Reading `.state` N times between mutations builds the map once.
+     * Never use it if you only need to iterate — `values()` / `rows()`
+     * stream without materializing the Map.
+     */
+    /**
+     * Lazily materialized snapshot of the live-row state as a
+     * `Map<PK, row>`. Matches `@tanstack/db`'s `Collection.state` both
+     * in shape and in semantics: the returned Map IS the internal
+     * cache, not a clone — mutating it is undefined behavior (same
+     * caveat as upstream). The cache is invalidated on every write,
+     * so a fresh Map materializes lazily on the next read.
+     *
+     * The `Map` return type is widened (vs `ReadonlyMap`) for
+     * TanStack parity; prefer `values()` / `entries()` / `has()` /
+     * `get()` for mutation-proof access.
+     */
+    get state(): Map<number, RowValue>;
+    /**
+     * Dense array of live rows in insertion order. Materialized lazily
+     * on first access and cached until the next mutation bumps
+     * `globalVersion`.
+     *
+     * Matches `@tanstack/db`'s `Collection.toArray` shape and
+     * semantics: the returned array IS the cache — mutating it is
+     * undefined behavior. Prefer `values()` / `rows()` for iteration.
+     *
+     * Repeated reads between mutations are O(1).
+     */
+    get toArray(): RowValue[];
+    /** Take a mark; use with `rollback(mark)` to undo everything after. */
+    beginTransaction(): number;
+    /**
+     * Roll back all mutations that happened at or after `mark`, newest-first.
+     * Throws `UndoError` if the ring has wrapped past `mark`.
+     */
+    rollback(mark: number): void;
+    /**
+     * Compact the collection:
+     *   1. Drop any soft-deleted rows (they remain in the segment as zombies
+     *      until compact runs).
+     *   2. Re-pack remaining live rows into a dense [0, liveCount) row slot
+     *      range, preserving their relative order by existing row index.
+     *   3. Rebuild utf8/binary values heaps, discarding bytes that are not
+     *      referenced by a live row (reclaims space leaked by prior updates).
+     *   4. Invalidate the undo ring (old row indices become meaningless).
+     *   5. Bump all column versions + emit a single 'compact' ChangeEvent so
+     *      reactive queries recompute.
+     *
+     * Returns `{ reclaimedRows, reclaimedHeapBytes }` for observability.
+     */
+    compact(): {
+        reclaimedRows: number;
+        reclaimedHeapBytes: number;
+    };
+    _internalConfirmSyncedMutations(mutations: Array<PendingMutation<RowValue>>): void;
+    private rollbackRecordToChange;
+    private applyInverse;
+    private initializeSpatialIndexes;
+    private spatialBboxCache;
+    private liveRowOrdinalsForSpatialIndex;
+    private markSpatialRowDirty;
+    private markSpatialRowDeleted;
+    private rebuildSpatialIndexes;
+    private rebuildSpatialIndexColumn;
+    private addToIndexes;
+    private removeFromIndexes;
+    private updateIndexes;
+    private rebuildIndexes;
+    private isSoftDeletedValue;
+    private writeCell;
+    private readCell;
+    private readBool;
+    private writeListCell;
+    private writeListElement;
+    private readListCell;
+    private listChildTypedBytes;
+    private readListElement;
+    private writeStructCell;
+    private readStructCell;
+    private snapshotRow;
+    private coerceUint32;
+    private coerceBoolNumber;
+}
+
+export { type Point as $, Aggregate as A, type BasicExpression as B, Collection as C, type DeleteMutationFn as D, type SubscribeChangesOptions as E, type CollectionSubscription as F, type GroupBy as G, type Having as H, type InsertMutationFn as I, BaseIndex as J, IndexOperation as K, type LocalOnlyCollectionConfig as L, MaterializeWrapper as M, type RangeQueryOptions as N, type OrderBy as O, type PacedMutationsConfig as P, type QueueStrategyOptions as Q, type RowValue as R, type SyncConfig as S, type Transaction$1 as T, type UpdateMutationFn as U, type IndexInterface as V, type Where as W, type OrderByDirection as X, type IndexStats as Y, type CollectionStatus as Z, type BBox as _, type CompiledSchema as a, type StrategyOptions as a$, type OperatorName as a0, type ColumnTypeName as a1, type BaseStrategy as a2, type BatchStrategy as a3, type BatchStrategyOptions as a4, ChangeEmitter as a5, type ChangeEvent as a6, type ChangeListener as a7, type ChangeMessageOrDeleteKeyMessage as a8, type ChangeOp as a9, type JoinClause as aA, type Limit as aB, type LineString as aC, type LoadSubsetFn as aD, type LocalOnlyCollectionUtils as aE, type LocalStorageCollectionUtils as aF, type MutationFn as aG, type MutationFnParams as aH, type NamespacedRow as aI, type NonEmptyArray as aJ, type Offset as aK, type OperationConfig as aL, type OperationType as aM, type OptimisticChangeMessage as aN, type OrderByClause as aO, type Parser as aP, type PendingMutation as aQ, type Polygon as aR, QueryRef as aS, type Ref as aT, type RefLeaf as aU, type RefProxy as aV, type ResolveTransactionChanges as aW, type SchemaInput as aX, type StorageApi as aY, type StorageEventApi as aZ, type Strategy as a_, type ClearStorageFn as aa, type CollectionEvents as ab, type CollectionMutationFnParams as ac, type CollectionOptions as ad, CollectionRef as ae, type CollectionStatusChangeEvent as af, type CollectionSubscribersChangeEvent as ag, type CollectionTruncateEvent as ah, type ColumnDef as ai, ColumnTypeCode as aj, type CompiledColumn as ak, type CurrentStateAsChangesOptions as al, type Deferred as am, type DeleteKeyMessage as an, type DeleteMutationFnParams as ao, Dictionary as ap, type Fn as aq, type From as ar, Func as as, type GetStorageSizeFn as at, INCLUDES_SCALAR_FIELD as au, ir as av, type IndexOptions as aw, type InsertConfig as ax, type InsertMutationFnParams as ay, type Join as az, type IndexConstructor as b, Transaction as b0, type TransactionCollectionLike as b1, type TransactionConfig as b2, type TransactionState as b3, type TransactionWithMutations as b4, type UnloadSubsetFn as b5, type UpdateMutationFnParams as b6, Value as b7, type ValueOf as b8, ValuesHeap as b9, isDictionary as bA, isExpressionLike as bB, isNull as bC, isRefProxy as bD, isResidualWhere as bE, isUndefined as bF, isVariableWidth as bG, length as bH, like as bI, lower as bJ, lt as bK, lte as bL, materialize as bM, max as bN, min as bO, multiply as bP, not as bQ, operators as bR, or as bS, subtract as bT, sum as bU, toArray as bV, toExpression as bW, upper as bX, val as bY, type VirtualPropsRefProxy as ba, add as bb, and as bc, avg as bd, byteWidthOf as be, caseWhen as bf, coalesce as bg, comparisonFunctions as bh, concat as bi, count as bj, createRefProxy as bk, createRefProxyWithSelected as bl, createResidualWhere as bm, createSingleRowRefProxy as bn, createTransaction as bo, defineSchema as bp, divide as bq, eq as br, followRef as bs, getActiveTransaction as bt, getHavingExpression as bu, getWhereExpression as bv, gt as bw, gte as bx, ilike as by, inArray as bz, type CreateCollectionConfig as c, type CreateOptimisticActionsOptions as d, type DebounceStrategyOptions as e, type DebounceStrategy as f, type QueueStrategy as g, type ThrottleStrategyOptions as h, type ThrottleStrategy as i, type LocalOnlyCollectionOptionsResult as j, type LocalStorageCollectionConfig as k, type LocalStorageCollectionOptionsResult as l, type QueryIR as m, type Select as n, IncludesSubquery as o, type RootRefProxy as p, type SingleRowRefProxy as q, ToArrayWrapper as r, ConcatToArrayWrapper as s, type CompareOptions as t, PropRef as u, type IncludesMaterialization as v, type LoadSubsetOptions as w, type UtilsRecord as x, type StringCollationConfig as y, type ChangeMessage as z };