tabulark 0.0.4 → 0.2.1

package/dist/model.d.ts

@@ -0,0 +1,392 @@
+import { BATCH_LAYOUT_VERSION } from "./protocol.js";
+export declare const DEFAULT_MEMORY_BUDGET_BYTES: number;
+export declare const MAX_ARRAY_BUFFER_BYTES: number;
+export declare const MAX_RANGE_CELLS = 250000;
+export declare const DEFAULT_TO_ROWS_CELL_LIMIT = 10000;
+export declare const MAX_NESTING_DEPTH = 64;
+export declare const MAX_SOURCES = 2;
+export declare const MAX_ACTIVE_RANGES = 2;
+export declare const MAX_RANGE_WAITERS = 8;
+export interface MemoryBudgetLimits {
+    readonly memoryBudgetBytes: number;
+    /** Cross-thread accounting slices used by RangeSource brokers. */
+    readonly workerBudgetBytes: number;
+    readonly mainThreadSourceBytes: number;
+    readonly mainThreadRetainedBytes: number;
+    readonly sourceRangeCacheBytes: number;
+    /** Shared retained capacity allocated among the adapters actually registered. */
+    readonly adapterRuntimePoolBytes: number;
+    /** Maximum transient/decoded budget retained by one active adapter operation. */
+    readonly operationBudgetBytes: number;
+    readonly indexBudgetBytes: number;
+    readonly adapterTileCacheBudgetBytes: number;
+    readonly mainThreadRangeCacheBytes: number;
+    readonly maxFieldBytes: number;
+    readonly maxBatchBytes: number;
+    readonly maxArrayBufferBytes: number;
+    readonly maxSources: number;
+    readonly maxActiveRanges: number;
+    readonly maxRangeWaiters: number;
+}
+/** Derives every bounded runtime allocation from one engine-wide budget. */
+export declare function deriveMemoryBudgetLimits(memoryBudgetBytes: number): MemoryBudgetLimits;
+export type MemoryResourceKind = "adapter-runtime" | "source-staging" | "compressed-page" | "decompression" | "batch";
+export interface MemoryReservation {
+    readonly resource: MemoryResourceKind;
+    readonly bytes: number;
+    release(): void;
+}
+/**
+ * Single-accounting ledger for Worker-owned bounded allocations.
+ *
+ * A reservation is deliberately idempotent so cancellation, close and failure
+ * races can all execute their normal cleanup paths without double accounting.
+ */
+export declare class MemoryReservationLedger {
+    #private;
+    constructor(capacityBytes: number);
+    get capacityBytes(): number;
+    get usedBytes(): number;
+    get availableBytes(): number;
+    reserve(resource: MemoryResourceKind, bytes: number): MemoryReservation;
+}
+export type AxisExtent = Readonly<{
+    kind: "exact";
+    value: number;
+}> | Readonly<{
+    kind: "at-least";
+    value: number;
+}> | Readonly<{
+    kind: "unknown";
+}>;
+export interface TableExtent {
+    readonly rows: AxisExtent;
+    readonly columns: AxisExtent;
+}
+export type TimeUnit = "second" | "millisecond" | "microsecond" | "nanosecond";
+export type IntervalUnit = "year-month" | "day-time" | "month-day-nano";
+export interface ArrowField {
+    readonly name: string;
+    readonly nullable: boolean;
+    readonly dataType: ArrowDataType;
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+interface SimpleDataType<Type extends string> {
+    readonly type: Type;
+}
+/** A recursive representation of every arrow-schema 59.1.0 built-in DataType. */
+export type ArrowDataType = SimpleDataType<"null" | "unknown" | "boolean" | "int8" | "int16" | "int32" | "int64" | "uint8" | "uint16" | "uint32" | "uint64" | "float16" | "float32" | "float64" | "date32" | "date64" | "binary" | "large-binary" | "binary-view" | "utf8" | "large-utf8" | "utf8-view"> | Readonly<{
+    type: "timestamp";
+    unit: TimeUnit;
+    timezone?: string;
+}> | Readonly<{
+    type: "time32" | "time64" | "duration";
+    unit: TimeUnit;
+}> | Readonly<{
+    type: "interval";
+    unit: IntervalUnit;
+}> | Readonly<{
+    type: "fixed-size-binary";
+    byteWidth: number;
+}> | Readonly<{
+    type: "decimal32" | "decimal64" | "decimal128" | "decimal256";
+    precision: number;
+    scale: number;
+}> | Readonly<{
+    type: "list" | "large-list" | "list-view" | "large-list-view";
+    field: ArrowField;
+}> | Readonly<{
+    type: "fixed-size-list";
+    field: ArrowField;
+    listSize: number;
+}> | Readonly<{
+    type: "struct";
+    fields: readonly ArrowField[];
+}> | Readonly<{
+    type: "union";
+    mode: "sparse" | "dense";
+    fields: readonly Readonly<{
+        typeId: number;
+        field: ArrowField;
+    }>[];
+}> | Readonly<{
+    type: "dictionary";
+    indexType: ArrowDataType;
+    valueType: ArrowDataType;
+    ordered?: boolean;
+}> | Readonly<{
+    type: "map";
+    entries: ArrowField;
+    keysSorted: boolean;
+}> | Readonly<{
+    type: "run-end-encoded";
+    runEnds: ArrowField;
+    values: ArrowField;
+}> | Readonly<{
+    type: "extension";
+    name: string;
+    metadata?: string;
+    storageType: ArrowDataType;
+}>;
+export interface ColumnSchema {
+    readonly id: string;
+    readonly name: string;
+    readonly index: number;
+    readonly dataType: ArrowDataType;
+    readonly nullable: boolean;
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+export interface TableCapabilities {
+    readonly randomAccess: "indexed-prefix" | "full";
+    readonly typedValues: boolean;
+    readonly search: boolean;
+    readonly sort: boolean;
+    readonly filter: boolean;
+    readonly multiTable: boolean;
+    readonly [name: string]: unknown;
+}
+export interface TableMetadata {
+    readonly tableId: string;
+    readonly name: string;
+    readonly revision: number;
+    readonly extent: Readonly<TableExtent>;
+    readonly schema: Readonly<{
+        readonly version: number;
+        readonly columns: readonly Readonly<ColumnSchema>[];
+    }>;
+    readonly capabilities: Readonly<TableCapabilities>;
+}
+export type WorksheetVisibility = "visible" | "hidden" | "very-hidden";
+/** One sparse row or column override supplied by a spreadsheet presentation. */
+export interface PresentationAxisEntry {
+    readonly index: number;
+    /** CSS pixel extent when the source supplies an explicit dimension. */
+    readonly size?: number;
+    readonly hidden?: boolean;
+}
+export interface PresentationColor {
+    /** CSS-compatible resolved color, when the workbook supplied one. */
+    readonly css?: string;
+}
+export interface PresentationFont {
+    readonly family?: string;
+    readonly size?: number;
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly underline?: boolean;
+    readonly color?: PresentationColor;
+}
+export interface PresentationBorderSide {
+    readonly style?: "none" | "thin" | "medium" | "thick" | "dashed" | "dotted" | "double";
+    readonly color?: PresentationColor;
+}
+/** Static cell styling that 0.1 preserves from spreadsheet input. */
+export interface PresentationStyle {
+    readonly numberFormat?: string;
+    readonly font?: PresentationFont;
+    readonly foregroundColor?: PresentationColor;
+    readonly backgroundColor?: PresentationColor;
+    readonly fillColor?: PresentationColor;
+    readonly borders?: Readonly<{
+        readonly top?: PresentationBorderSide;
+        readonly right?: PresentationBorderSide;
+        readonly bottom?: PresentationBorderSide;
+        readonly left?: PresentationBorderSide;
+    }>;
+    readonly horizontalAlignment?: "general" | "left" | "center" | "right" | "justify";
+    readonly verticalAlignment?: "top" | "center" | "bottom" | "justify";
+    readonly wrapText?: boolean;
+}
+export interface MergedCellRegion {
+    readonly rowStart: number;
+    readonly rowEnd: number;
+    readonly columnStart: number;
+    readonly columnEnd: number;
+}
+/**
+ * Presentation metadata for a worksheet. It is intentionally static: formula
+ * calculation and document round-tripping are outside the 0.1 contract.
+ */
+export interface SpreadsheetPresentation {
+    readonly kind: "spreadsheet-v1";
+    readonly tableId: string;
+    readonly revision: number;
+    readonly visibility: WorksheetVisibility;
+    readonly frozenRows: number;
+    readonly frozenColumns: number;
+    readonly rows: readonly PresentationAxisEntry[];
+    readonly columns: readonly PresentationAxisEntry[];
+    /** Deduplicated styles addressed by `SpreadsheetPresentationRange.styleIds`. */
+    readonly styles: readonly PresentationStyle[];
+}
+export type TablePresentation = SpreadsheetPresentation;
+export interface SpreadsheetPresentationRange {
+    readonly kind: "spreadsheet-v1";
+    readonly tableId: string;
+    readonly revision: number;
+    readonly range: Readonly<ReturnedRange>;
+    /** Rows and columns are exactly aligned with `range`; null means no style. */
+    readonly styleIds: readonly (readonly (number | null)[])[];
+    readonly mergedCells: readonly MergedCellRegion[];
+    /** Sparse layout entries that intersect this requested range. */
+    readonly rows: readonly PresentationAxisEntry[];
+    readonly columns: readonly PresentationAxisEntry[];
+}
+export type PresentationRange = SpreadsheetPresentationRange;
+export interface TableDescriptor {
+    readonly id: string;
+    readonly name: string;
+}
+export interface RangeRequest {
+    readonly rowStart: number;
+    readonly rowCount: number;
+    readonly columnStart: number;
+    readonly columnCount: number;
+}
+export interface ReturnedRange extends RangeRequest {
+}
+/** A byte region in the batch's deduplicated buffer pool. */
+export interface BatchBufferRegion {
+    readonly buffer: number;
+    readonly byteOffset?: number;
+    readonly byteLength?: number;
+    /** First bit for bitmap regions; ignored for byte-oriented regions. */
+    readonly bitOffset?: number;
+}
+/** UTF-8 text generated by Rust for rendering, ARIA, width measurement and copy. */
+export interface DisplayColumnDescriptor {
+    readonly encoding: "utf8";
+    readonly data: BatchBufferRegion;
+    readonly offsets: BatchBufferRegion;
+    readonly validity?: BatchBufferRegion;
+    /** Logical offset into the display arrays, for sliced batches. */
+    readonly offset?: number;
+}
+/**
+ * Recursive Arrow ArrayData layout. Buffer regions always point into the
+ * enclosing TableBatch buffer pool; encoded dictionaries and run ends remain
+ * visible in this descriptor even though `toRows()` returns logical values.
+ */
+export interface NativeColumnDescriptor {
+    /** Rust ArrayData layout encoding (for example `dictionary` or `run-end-encoded`). */
+    readonly encoding?: string;
+    readonly dataType: ArrowDataType;
+    readonly length: number;
+    readonly offset?: number;
+    readonly validity?: BatchBufferRegion;
+    readonly values?: BatchBufferRegion;
+    readonly offsets?: BatchBufferRegion;
+    readonly sizes?: BatchBufferRegion;
+    readonly data?: BatchBufferRegion;
+    readonly typeIds?: BatchBufferRegion;
+    readonly unionOffsets?: BatchBufferRegion;
+    readonly variadicBuffers?: readonly BatchBufferRegion[];
+    readonly children?: readonly NativeColumnDescriptor[];
+    readonly dictionary?: NativeColumnDescriptor;
+    readonly runEnds?: NativeColumnDescriptor;
+    readonly typeId?: number;
+}
+/** @internal Layout-v1 column descriptor received from an official WASM runtime. */
+export interface WireTableBatchColumn {
+    readonly columnId: string;
+    readonly native: NativeColumnDescriptor;
+    readonly display: DisplayColumnDescriptor;
+}
+export interface DecimalValue {
+    readonly kind: "decimal";
+    readonly unscaled: bigint;
+    readonly precision: number;
+    readonly scale: number;
+}
+export interface TemporalValue {
+    readonly kind: "date32" | "date64" | "time32" | "time64" | "timestamp" | "duration";
+    readonly value: number | bigint;
+    readonly unit?: TimeUnit;
+    readonly timezone?: string;
+}
+export interface IntervalValue {
+    readonly kind: "interval";
+    readonly unit: IntervalUnit;
+    readonly months?: number;
+    readonly days?: number;
+    readonly milliseconds?: number;
+    readonly nanoseconds?: bigint;
+}
+export interface UnionValue {
+    readonly kind: "union";
+    readonly typeId: number;
+    readonly value: NativeValue | null;
+}
+export interface MapEntryValue {
+    readonly key: NativeValue | null;
+    readonly value: NativeValue | null;
+}
+export interface NativeListValue extends ReadonlyArray<NativeValue | null> {
+}
+export interface NativeStructValue {
+    readonly [name: string]: NativeValue | null;
+}
+export interface NativeMapValue extends ReadonlyArray<Readonly<MapEntryValue>> {
+}
+export type NativeValue = boolean | number | bigint | string | Uint8Array | DecimalValue | TemporalValue | IntervalValue | UnionValue | NativeListValue | NativeStructValue | NativeMapValue;
+export interface ToRowsOptions {
+    /** Maximum decoded cells. Defaults to 10,000. */
+    readonly maxCells?: number;
+}
+/**
+ * Logical, column-oriented access to one returned batch column.
+ *
+ * Values are indexed relative to `TableBatch.range.rowStart`; physical buffer
+ * regions and adapter transport details intentionally remain private.
+ */
+export interface TableBatchColumn {
+    readonly columnId: string;
+    readonly columnIndex: number;
+    readonly rowCount: number;
+    getValue(rowOffset: number): NativeValue | null;
+    getDisplayValue(rowOffset: number): string | null;
+    toValues(options?: ToRowsOptions): (NativeValue | null)[];
+    toDisplayValues(options?: ToRowsOptions): (string | null)[];
+}
+/** Stable logical batch contract. Wire buffers and ABI layout stay private. */
+export interface TableBatch {
+    readonly tableId: string;
+    readonly revision: number;
+    readonly schemaVersion: number;
+    readonly range: Readonly<ReturnedRange>;
+    readonly columns: readonly TableBatchColumn[];
+    readonly complete: boolean;
+    toRows(options?: ToRowsOptions): (NativeValue | null)[][];
+    toDisplayRows(options?: ToRowsOptions): (string | null)[][];
+}
+export type WireBatchBuffer = ArrayBuffer | ArrayBufferView;
+export interface WireTableBatch {
+    readonly layoutVersion: typeof BATCH_LAYOUT_VERSION;
+    readonly tableId: string;
+    readonly revision: number;
+    readonly schemaVersion: number;
+    readonly range: ReturnedRange;
+    readonly buffers: readonly WireBatchBuffer[];
+    readonly columns: readonly WireTableBatchColumn[];
+    readonly complete: boolean;
+}
+/** Owns and validates one generic layout-v1 batch received from the Worker. */
+export declare class ColumnarTableBatch implements TableBatch {
+    #private;
+    readonly tableId: string;
+    readonly revision: number;
+    readonly schemaVersion: number;
+    readonly range: Readonly<ReturnedRange>;
+    readonly columns: readonly TableBatchColumn[];
+    readonly complete: boolean;
+    constructor(value: WireTableBatch);
+    toRows(options?: ToRowsOptions): (NativeValue | null)[][];
+    toDisplayRows(options?: ToRowsOptions): (string | null)[][];
+}
+export declare function validateRange(request: RangeRequest): RangeRequest;
+export declare function normalizeMetadata(value: TableMetadata): Readonly<TableMetadata>;
+/** Normalizes a protocol DataType and rejects cycles or excessive nesting. */
+export declare function normalizeDataType(value: unknown, depth?: number): ArrowDataType;
+export declare function assertNonNegativeSafeInteger(value: unknown, name: string): asserts value is number;
+export declare function assertPositiveSafeInteger(value: unknown, name: string): asserts value is number;
+export {};

package/dist/official-adapter-manifest.d.ts

@@ -0,0 +1,31 @@
+export type OfficialAdapterId = "tabulark:delimited" | "tabulark:arrow-ipc" | "tabulark:parquet" | "tabulark:excel";
+export type OfficialSourceAccess = "streaming" | "range" | "staged";
+export interface OfficialAdapterManifestEntry {
+    readonly id: OfficialAdapterId;
+    readonly entrypoint: "." | "./arrow" | "./parquet" | "./excel";
+    readonly exportName: string;
+    readonly wasm: Readonly<{
+        readonly packageName: string;
+        readonly crateArtifact: string;
+        readonly outputName: string;
+        readonly outputDirectory: string;
+        readonly modulePath: string;
+        readonly runtimeExport: "WasmRuntime";
+    }>;
+    readonly options: Readonly<{
+        readonly allowedKeys: readonly string[];
+    }>;
+    readonly resources: Readonly<{
+        readonly sourceAccess: OfficialSourceAccess;
+        readonly supportsPresentation: boolean;
+        readonly runtimeWeight: number;
+    }>;
+}
+/** Runtime IDs are derived from the manifest rather than repeated in code. */
+export declare const OFFICIAL_ADAPTER_IDS: readonly OfficialAdapterId[];
+/** The sole internal source of truth for built-in IDs, artifacts and host policy. */
+export declare const OFFICIAL_ADAPTER_MANIFEST: readonly OfficialAdapterManifestEntry[];
+export declare function isOfficialAdapterId(value: unknown): value is OfficialAdapterId;
+export declare function officialAdapterManifestEntry(id: OfficialAdapterId): OfficialAdapterManifestEntry;
+/** Resolves an official wrapper relative to the bundle that hosts this code. */
+export declare function officialAdapterModuleUrl(id: OfficialAdapterId): string;

package/dist/parquet.d.ts

@@ -0,0 +1,3 @@
+export { type ParquetAdapterOptions } from "./adapters.js";
+/** Opens Apache Parquet input through the lazy official Parquet WASM artifact. */
+export declare const parquetAdapter: import("./adapters.js").AdapterDescriptor<"tabulark:parquet", import("./adapters.js").ParquetAdapterOptions>;

package/dist/parquet.js

@@ -0,0 +1,2 @@
+var OFFICIAL_ADAPTER=Symbol.for("tabulark.official-adapter.v2");function createOfficialAdapter(id){const marker=Object.freeze({id});return Object.freeze({id,kind:"official",[OFFICIAL_ADAPTER]:marker})}var delimitedAdapter=createOfficialAdapter("tabulark:delimited");function createParquetAdapter(){return createOfficialAdapter("tabulark:parquet")}var parquetAdapter=createParquetAdapter();export{parquetAdapter};
+//# sourceMappingURL=parquet.js.map

package/dist/parquet.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../js/adapters.ts", "../js/parquet.ts"],
+  "sourcesContent": ["import {\n  isOfficialAdapterId,\n  officialAdapterManifestEntry,\n  type OfficialAdapterId,\n} from \"./official-adapter-manifest.js\";\n\nexport type { OfficialAdapterId } from \"./official-adapter-manifest.js\";\n\nexport type DelimitedDialect = \"csv\" | \"tsv\";\nexport type HeaderMode = \"first-row\" | \"none\";\nexport type ParseMode = \"lenient\" | \"strict\";\n\n/** Options understood by the built-in delimited adapter. */\nexport interface DelimitedAdapterOptions {\n  /** Defaults to `csv`. No filename-based selection is performed. */\n  readonly dialect?: DelimitedDialect;\n  readonly header?: HeaderMode;\n  readonly mode?: ParseMode;\n  /** One ASCII delimiter byte. Overrides the dialect default when supplied. */\n  readonly delimiter?: string;\n  /** Optional display name for the source. */\n  readonly sourceName?: string;\n}\n\nexport type ArrowIpcContainer = \"auto\" | \"file\" | \"stream\";\n\n/** Options understood by the built-in Arrow IPC adapter. */\nexport interface ArrowIpcAdapterOptions {\n  /** Defaults to `auto`; format detection belongs to the Arrow adapter. */\n  readonly container?: ArrowIpcContainer;\n  /** Optional display name for the source. */\n  readonly sourceName?: string;\n}\n\n/** Options understood by the built-in Parquet adapter. */\nexport interface ParquetAdapterOptions {\n  /** Optional display name for the source. */\n  readonly sourceName?: string;\n}\n\nexport type ExcelFormat = \"auto\" | \"xls\" | \"xlsx\";\n\n/** Options understood by the built-in Excel adapter. */\nexport interface ExcelAdapterOptions {\n  /** Defaults to `auto`; the adapter identifies the file from its signature. */\n  readonly format?: ExcelFormat;\n  /** Optional display name for the source. */\n  readonly sourceName?: string;\n}\n\n/**\n * A frozen descriptor for one built-in adapter.\n *\n * Descriptors select a named official artifact only. They are deliberately not\n * factories and cannot carry a module URL or a third-party implementation.\n */\nexport interface AdapterDescriptor<\n  Id extends OfficialAdapterId = OfficialAdapterId,\n  Options = unknown,\n> {\n  readonly id: Id;\n  readonly kind: \"official\";\n  /** Carries the option type without exposing a runtime extension point. */\n  readonly __options?: Options;\n}\n\ninterface InternalAdapterDescriptor<\n  Id extends OfficialAdapterId = OfficialAdapterId,\n  Options = unknown,\n> extends AdapterDescriptor<Id, Options> {\n  readonly [OFFICIAL_ADAPTER]: Readonly<{ readonly id: Id }>;\n}\n\n/**\n * A process-global symbol permits descriptors from separately bundled stable\n * entrypoints to be recognized. It conveys no capability: the manifest below\n * still owns the selected module URL and resource policy.\n */\nconst OFFICIAL_ADAPTER = Symbol.for(\"tabulark.official-adapter.v2\");\n\nexport interface AdapterRegistration {\n  readonly id: OfficialAdapterId;\n}\n\nfunction createOfficialAdapter<Id extends OfficialAdapterId, Options>(\n  id: Id,\n): AdapterDescriptor<Id, Options> {\n  const marker = Object.freeze({ id });\n  return Object.freeze({\n    id,\n    kind: \"official\" as const,\n    [OFFICIAL_ADAPTER]: marker,\n  }) as InternalAdapterDescriptor<Id, Options>;\n}\n\n/** The built-in RFC-style delimited text adapter. */\nexport const delimitedAdapter = createOfficialAdapter<\n  \"tabulark:delimited\",\n  DelimitedAdapterOptions\n>(\"tabulark:delimited\");\n\n/** @internal Used by the stable `/arrow` entrypoint. */\nexport function createArrowIpcAdapter(): AdapterDescriptor<\"tabulark:arrow-ipc\", ArrowIpcAdapterOptions> {\n  return createOfficialAdapter<\"tabulark:arrow-ipc\", ArrowIpcAdapterOptions>(\"tabulark:arrow-ipc\");\n}\n\n/** @internal Used by the stable `/parquet` entrypoint. */\nexport function createParquetAdapter(): AdapterDescriptor<\"tabulark:parquet\", ParquetAdapterOptions> {\n  return createOfficialAdapter<\"tabulark:parquet\", ParquetAdapterOptions>(\"tabulark:parquet\");\n}\n\n/** @internal Used by the stable `/excel` entrypoint. */\nexport function createExcelAdapter(): AdapterDescriptor<\"tabulark:excel\", ExcelAdapterOptions> {\n  return createOfficialAdapter<\"tabulark:excel\", ExcelAdapterOptions>(\"tabulark:excel\");\n}\n\n/** @internal Validates and extracts the non-public Worker registration. */\nexport function resolveOfficialAdapter(value: unknown): AdapterRegistration | undefined {\n  if (!isRecord(value) || !Object.isFrozen(value) || !isOfficialAdapterId(value.id) || value.kind !== \"official\") {\n    return undefined;\n  }\n  const marker = value[OFFICIAL_ADAPTER];\n  if (!isRecord(marker) || marker.id !== value.id) {\n    return undefined;\n  }\n  // A marker may be recreated by another bundle, but it conveys no URL or\n  // implementation capability: it can select only a manifest-owned ID.\n  officialAdapterManifestEntry(value.id);\n  return Object.freeze({ id: value.id });\n}\n\nfunction isRecord(value: unknown): value is Record<PropertyKey, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n", "export { type ParquetAdapterOptions } from \"./adapters.js\";\n\nimport { createParquetAdapter } from \"./adapters.js\";\n\n/** Opens Apache Parquet input through the lazy official Parquet WASM artifact. */\nexport const parquetAdapter = createParquetAdapter();\n"],
+  "mappings": "AA8EA,IAAM,iBAAmB,OAAO,IAAI,8BAA8B,EAMlE,SAAS,sBACP,GACgC,CAChC,MAAM,OAAS,OAAO,OAAO,CAAE,EAAG,CAAC,EACnC,OAAO,OAAO,OAAO,CACnB,GACA,KAAM,WACN,CAAC,gBAAgB,EAAG,MACtB,CAAC,CACH,CAGO,IAAM,iBAAmB,sBAG9B,oBAAoB,EAQf,SAAS,sBAAqF,CACnG,OAAO,sBAAiE,kBAAkB,CAC5F,CCxGO,IAAM,eAAiB,qBAAqB",
+  "names": []
+}

package/dist/protocol.d.ts

@@ -0,0 +1,54 @@
+/** Version 4 introduces resumable, revisioned operations and main-thread batch ownership. */
+export declare const PROTOCOL_VERSION: 4;
+/** Version of the private, built-in Rust adapter contract. */
+export declare const ADAPTER_API_VERSION: 3;
+/** Version of the descriptor + deduplicated-buffer batch transport. */
+export declare const BATCH_LAYOUT_VERSION: 1;
+export type ProtocolVersion = typeof PROTOCOL_VERSION;
+export type Operation = "hello" | "openSource" | "listTables" | "openTable" | "getMetadata" | "getPresentation" | "readPresentationRange" | "readRange" | "cancel" | "closeTable" | "closeSource" | "shutdown";
+export interface ProtocolRequest<T = unknown> {
+    readonly protocolVersion: ProtocolVersion;
+    readonly requestId: string;
+    readonly op: Operation;
+    readonly payload: T;
+}
+export type ResponseKind = "hello" | "dataset" | "tables" | "table" | "metadata" | "presentation" | "presentationRange" | "batch" | "acknowledged";
+export interface ProtocolResult<T = unknown> {
+    readonly kind: ResponseKind;
+    readonly data?: T;
+}
+export interface ProtocolSuccess<T = unknown> {
+    readonly protocolVersion: ProtocolVersion;
+    readonly requestId: string;
+    readonly status: "success";
+    readonly result: ProtocolResult<T>;
+}
+export interface SerializedError {
+    readonly code: string;
+    readonly message: string;
+    readonly retryable: boolean;
+    readonly details?: unknown;
+}
+export interface ProtocolFailure {
+    readonly protocolVersion: ProtocolVersion;
+    readonly requestId: string;
+    readonly status: "failure";
+    readonly error: SerializedError;
+}
+export type ProtocolResponse<T = unknown> = ProtocolSuccess<T> | ProtocolFailure;
+export type RuntimeEventName = "progress" | "metadata" | "warning" | "closed" | "runtimeError";
+export interface ProtocolEvent<T = unknown> {
+    readonly protocolVersion: ProtocolVersion;
+    readonly requestId?: string;
+    readonly event: RuntimeEventName;
+    /** Required for dataset/table events; omitted only by a process-wide runtimeError. */
+    readonly datasetHandle?: string;
+    readonly tableHandle?: string;
+    readonly tableId?: string;
+    /** Revision associated with a table-scoped event, when known. */
+    readonly revision?: number;
+    readonly payload: T;
+}
+export declare function isProtocolResponse(value: unknown): value is ProtocolResponse;
+export declare function isProtocolEvent(value: unknown): value is ProtocolEvent;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/range-cache.d.ts

@@ -0,0 +1,47 @@
+import type { RangeRequest, WireTableBatch, WireTableBatchColumn } from "./model.js";
+export declare class PermitQueueFullError extends Error {
+    readonly maxWaiters: number;
+    constructor(maxWaiters: number);
+}
+/** A small FIFO permit queue whose pending acquisitions can be cancelled by key. */
+export declare class AsyncPermitQueue {
+    #private;
+    constructor(maxActive: number, maxWaiters: number);
+    acquire(key: string): Promise<() => void>;
+    cancel(key: string, reason: unknown): boolean;
+}
+/** A byte-bounded least-recently-used cache. */
+export declare class ByteLruCache<T> {
+    #private;
+    constructor(maxBytes: number, options?: Readonly<{
+        maxEntries?: number;
+        minimumEntryBytes?: number;
+        onRemove?: (key: string, value: T, byteLength: number) => void;
+    }>);
+    get maxBytes(): number;
+    get maxEntries(): number;
+    get(key: string): T | undefined;
+    set(key: string, value: T, byteLength: number, maxBytes?: number): void;
+    /** Evicts least-recently-used entries until the requested live cap is met. */
+    trimTo(maxBytes: number): void;
+    deleteWhere(predicate: (key: string, value: T) => boolean): void;
+    clear(): void;
+}
+export declare function rangeCacheKey(datasetHandle: string, tableId: string, revision: number, schemaVersion: number, range: RangeRequest): string;
+export declare function rangeCacheKeyBelongsToDataset(key: string, datasetHandle: string): boolean;
+export declare function rangeCacheKeyBelongsToTable(key: string, datasetHandle: string, tableId: string): boolean;
+export declare function rangeCacheKeyMatchesVersion(key: string, revision: number, schemaVersion: number): boolean;
+/**
+ * Main-thread-owned immutable backing for a logical batch.
+ *
+ * The ArrayBuffers arrive as independently transferable Worker output and are
+ * intentionally not cloned here. They remain unreachable through the public
+ * batch facade; binary getters perform their own defensive copy.
+ */
+export type BatchBacking = Omit<WireTableBatch, "buffers" | "columns" | "range"> & Readonly<{
+    range: Readonly<WireTableBatch["range"]>;
+    buffers: readonly ArrayBuffer[];
+    columns: readonly WireTableBatchColumn[];
+}>;
+export declare function createBatchBacking(batch: WireTableBatch): BatchBacking;
+export declare function wireBatchByteLength(batch: WireTableBatch): number;

package/dist/range-source.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Bounded, repeatable byte-range sources.
+ *
+ * A RangeSource is intentionally a very small host-side capability.  The
+ * worker never receives the implementation (or a URL); it is given an opaque
+ * reader handle by the client and asks the host for bounded byte ranges.
+ */
+/** The largest addressable source (2^32 - 1 bytes). */
+export declare const MAX_RANGE_SOURCE_BYTES = 4294967295;
+/** A half-open byte interval [offset, offset + length). */
+export interface ByteRange {
+    readonly offset: number;
+    readonly length: number;
+}
+/** A stable identity for one opened view of a source. */
+export interface RangeSourceSnapshot {
+    readonly id: string;
+    readonly strength: "strong" | "weak";
+}
+/** Options supplied to every reader operation. */
+export interface RangeSourceReadOptions {
+    readonly signal: AbortSignal;
+}
+/** A reader returned by a RangeSource.open() call. */
+export interface RangeSourceReader {
+    /** Exact source size in bytes. */
+    readonly size: number;
+    /** Validator captured while opening the source. */
+    readonly snapshot: RangeSourceSnapshot;
+    /** Maximum number of provider reads that may run concurrently. Defaults to 1. */
+    readonly maxConcurrency?: number;
+    /** Reads exactly range.length bytes, or rejects. */
+    read(range: ByteRange, options: RangeSourceReadOptions): Promise<ArrayBuffer | ArrayBufferView>;
+    /** Releases all resources. Calling close more than once is harmless. */
+    close(): Promise<void> | void;
+}
+/** Open-time limits owned by the engine. */
+export interface RangeSourceOpenOptions {
+    readonly signal: AbortSignal;
+    readonly maxSourceBytes: number;
+    readonly maxStagingBytes: number;
+}
+/** A repeatably openable source addressed by bounded byte ranges. */
+export interface RangeSource {
+    readonly kind: "range";
+    readonly name?: string;
+    open(options: RangeSourceOpenOptions): Promise<RangeSourceReader>;
+}
+/** Runtime check used at the public engine boundary. */
+export declare function isRangeSource(value: unknown): value is RangeSource;
+/**
+ * Validates a byte range without coercing values.  Keeping this check in one
+ * place prevents unsafe floating-point arithmetic at both HTTP and Worker
+ * boundaries.
+ */
+export declare function validateByteRange(range: unknown, size: number): asserts range is ByteRange;
+/** Validates and freezes a reader snapshot. */
+export declare function normalizeRangeSourceSnapshot(value: unknown): RangeSourceSnapshot;
+/** Validates a reader object returned by an adapter/broker. */
+export declare function validateRangeSourceReader(value: unknown): value is RangeSourceReader;
+/** Converts an ArrayBuffer or view to a fresh, exact-length ArrayBuffer. */
+export declare function copyRangeBytes(value: ArrayBuffer | ArrayBufferView): ArrayBuffer;
+/** Returns whether a value is a safe non-negative integer. */
+export declare function isSafeNonNegativeInteger(value: unknown): value is number;

package/dist/rpc-client.d.ts

@@ -0,0 +1,31 @@
+import { TabularkError } from "./errors.js";
+import { type Operation, type ProtocolEvent, type ResponseKind } from "./protocol.js";
+type EventListener = (event: ProtocolEvent) => void;
+type FailureListener = (error: TabularkError) => void;
+/** Private messages exchanged by the Worker source-byte broker. */
+export type SourceBrokerListener = (value: unknown) => void;
+interface RequestOptions {
+    readonly transfer?: Transferable[];
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    /** Private opt-in operation telemetry callback. */
+    readonly measure?: boolean;
+    readonly onTelemetry?: (telemetry: OperationTelemetry | undefined) => void;
+}
+export interface OperationTelemetry {
+    readonly bytesRead: number;
+    readonly peakReservationBytes: number;
+    readonly sourceReads: number;
+    readonly sourceCacheHitBytes: number;
+}
+/** Main-thread request multiplexer for one dedicated Worker. */
+export declare class WorkerRpcClient {
+    #private;
+    constructor(worker: Worker, onEvent: EventListener, onFailure?: FailureListener, onSourceMessage?: SourceBrokerListener);
+    /** Sends one private broker response without exposing the Worker object. */
+    postMessage(value: unknown, transfer?: Transferable[]): void;
+    request<T>(op: Operation, payload: unknown, expectedKind: ResponseKind, options?: RequestOptions): Promise<T>;
+    shutdown(timeoutMs?: number, options?: Pick<RequestOptions, "measure" | "onTelemetry">): Promise<void>;
+    terminate(error?: TabularkError, notifyFailure?: boolean): void;
+}
+export {};

package/dist/source.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Host-side source policy shared by the stable client and its Worker.
+ *
+ * This is deliberately a binary constant (rather than a decimal "2G" value):
+ * the large-source contract is exactly 2 * 1024^3 bytes.  Keeping the value
+ * in one module prevents the client and Worker from drifting at the boundary.
+ */
+export declare const MAX_LARGE_SOURCE_BYTES: number;
+export { MAX_RANGE_SOURCE_BYTES, isRangeSource, validateByteRange, validateRangeSourceReader, copyRangeBytes, } from "./range-source.js";
+export type { ByteRange, RangeSource, RangeSourceOpenOptions, RangeSourceReader, RangeSourceReadOptions, RangeSourceSnapshot, } from "./range-source.js";
+/** Selects the bounded default path or the large local-Blob path. */
+export type SourceMode = "auto" | "large";
+export declare function isSourceMode(value: unknown): value is SourceMode;