tabulark 0.0.4 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to Tabulark are documented here. The project follows
+[Semantic Versioning](https://semver.org/).
+
+## 0.2.1
+
+- Read partial viewports from oversized Parquet row groups page by page instead
+  of staging every projected column chunk. Lazy reads enforce cumulative page
+  decompression, bounded page tracking and header parsing, compressed-cache
+  peak, and decoder-restart limits before returning data to parquet-rs.
+- Bound nested Arrow display previews without changing their native values;
+  oversized list, struct, map, and union text ends with an explicit
+  `... [truncated]` marker.
+- Add a separately built, experimental document-preview source package with a
+  Worker-isolated PDFium page pipeline, bounded RGBA page rendering, and an
+  accessible framework-free paged view. It is not part of the stable root npm
+  exports or official tabular-adapter manifest.
+
+## 0.2.0
+
+- Add bounded structured diagnostics and independent diagnostic subscriptions.
+- Add logical dataset/table capability snapshots and opt-in privacy-safe
+  performance samples.
+- Add Canvas `colorScheme` support with dynamic dark mode and forced-colors
+  precedence.
+- Add opt-in `sourceMode: "large"` for local Blob/File inputs through exactly
+  `2^31` bytes across CSV, Arrow File, Parquet, XLSX, and XLS; ArrayBuffer and
+  automatic-mode limits remain unchanged.
+- Add the stable `RangeSource` capability to every official format. Readers
+  validate exact lengths and snapshots, support independent reopen/close
+  lifecycles, and address at most `4,294,967,295` bytes (`2^32 - 1`).
+- Add `tabulark/http` with a `GET Range: bytes=0-0` capability probe, strict
+  `Content-Range` and validator checks, bounded transient retries, dynamic
+  headers/credentials, and an explicit bounded-download fallback. Network and
+  authentication remain on the main thread; no URL, headers, validator, or
+  snapshot ID is exposed in Worker messages, errors, or performance samples.
+- Add source-range request coalescing, dataset singleflight, a byte-budgeted
+  range LRU, four-way maximum provider concurrency, exact reader cleanup, and
+  cross-thread memory slices (75% Worker, 12.5% source staging, 12.5%
+  retained batches/fallback).
+- Add `SOURCE_UNAVAILABLE`, `SOURCE_CHANGED`, and `RANGE_UNSUPPORTED` source
+  errors. Extend `PerformanceSample` with `sourceReads` and
+  `sourceCacheHitBytes`; `cacheHit` remains the logical batch-cache metric.
+- Move every official adapter to private Worker protocol v4 and adapter ABI v3
+  resumable operations with checked revisions, bounded multi-range actions,
+  cooperative no-I/O yields, and one-transfer batch output.
+- Make the main thread the sole decoded-batch cache owner, with immutable
+  backings, logical-table keys, singleflight misses, and independent caller
+  cancellation. Remove the Worker decoded LRU.
+- Add Rust/WASM resource ledgers and native cache admission/reclamation
+  evidence, including 100-cycle lifecycle and WebAssembly-memory high-water
+  gates.
+- Add incremental Arrow File/Stream indexing, coalesced Parquet projection
+  reads, and Rust range-backed ZIP64/CFB Excel container indexing. Excel
+  compacts only required workbook content into its bounded compatibility
+  parser.
+- Add release-blocking Chromium, Firefox, and WebKit functional projects.
+  Chromium additionally owns pixel, performance, real-clipboard, and exact
+  2 GiB evidence.
+- Add paired baseline performance gates, shipped-JavaScript shrinkage gates,
+  and a native five-container exact-size generator/workflow.
+- Add HTTP contract, virtual/sparse 4 GiB−1, cancellation/lifecycle,
+  concurrency, cache, CORS, retry, validator-change, and explicit-fallback
+  release evidence in Chromium, Firefox, and WebKit. Keep a separate measured
+  raw/Brotli size budget for the new `/http` entry point.
+- Remove the private TypeScript large-XLSX parser and its shipped artifact.
+
+Version 0.1.1 was never tagged or published; its compatible work is included
+in 0.2.0. The immutable `v0.1.0` tag is unchanged.
+
+## 0.1.0
+
+- Establish the stable browser-facing API and the official local-format adapter
+  host.
+- Add local Apache Parquet and Excel (BIFF8/XLSX) preview adapters.
+- Add spreadsheet presentation metadata for the Canvas view.
+
+## 0.0.4
+
+Published before the 0.1.0 release train.

package/README.md

@@ -1,157 +1,345 @@
 # Tabulark
 
-> A WebAssembly-first engine for fast, format-agnostic tabular data preview in the browser.
-
-**One table model for every tabular source.**
-
-**Status: pre-alpha design and prototyping.**
-
-> [!IMPORTANT]
-> Tabulark is currently in the design and prototyping stage. There is no stable
-> public API or production-ready release yet. The architecture, formats, and
-> performance characteristics described below are goals, not shipped features.
-
-## Why Tabulark?
-
-Tabular data reaches web applications through many formats, but preview
-interfaces repeatedly reimplement parsing, data transfer, caching, and
-rendering for each one.
+> **Status: 0.2.1.** The immutable `v0.1.0` tag and its registry/Pages
+> evidence remain recorded in
+> [the release evidence](docs/release-0.1.0-evidence.md); that tag is never
+> moved or reused. Version 0.2 adds bounded local and remote range sources,
+> structured diagnostics and capabilities, performance observation, and
+> synchronized Canvas themes without changing the documented 0.1.0 calling
+> patterns. Local `sourceMode: "large"` remains capped at 2 GiB; a validated
+> `RangeSource` may address at most `4,294,967,295` bytes (`2^32 - 1`).
+
+Tabulark is a WebAssembly-first browser primitive for previewing tabular data
+without uploading it. Local bytes stay local; an explicit `RangeSource` can
+read a remote object through a main-thread broker without giving its URL,
+credentials, or headers to the Worker. A module Worker owns parsing, bounded
+byte access, adapter state, cancellation, and cleanup. A Canvas viewport
+renders visible cells while a bounded semantic grid supplies keyboard and
+screen-reader access.
+
+[Try the playground](https://ronbb.github.io/tabulark/) · [Architecture](docs/architecture.md) · [API stability](docs/api-stability.md) · [Testing](docs/testing.md)
+
+## Supported local formats
+
+The 0.2.1 source tree contains four official adapters. Each adapter
+is a separate, lazily loaded WebAssembly artifact; creating an engine loads no
+WASM and opening one format does not fetch unused artifacts.
+
+| Format | Official ID | Stable entry point | 0.2 contract |
+| --- | --- | --- | --- |
+| CSV/TSV | `tabulark:delimited` | `tabulark` | Explicit delimiter, header, and strict/lenient modes |
+| Arrow IPC | `tabulark:arrow-ipc` | `tabulark/arrow` | File/Stream; none, LZ4, and Zstd IPC compression |
+| Parquet | `tabulark:parquet` | `tabulark/parquet` | Range-driven row-group/column projection and the documented codec set |
+| Excel | `tabulark:excel` | `tabulark/excel` | Excel 97–2003 BIFF8 XLS and OOXML XLSX, including static presentation |
+
+Arbitrary adapter/module URLs, public third-party adapters, persistent caches,
+ReadableStream sources, formula calculation, editing, and document-level Excel
+round-tripping are outside 0.2. Remote input is available only through the
+explicit `RangeSource` contract (or the opt-in `tabulark/http` helper).
+
+## Install and build
+
+The npm package has no production JavaScript dependencies. Its desktop release
+gate covers Chromium, Firefox, and WebKit, and it requires Node 20 or newer to
+build from source. Rust 1.85 is the minimum supported Rust version.
+
+```sh
+npm ci
+npm run build
+npm run check
+npm run test:browser
+```
 
-Tabulark is being designed as composable browser infrastructure that presents
-those sources through one format-agnostic `Table` model. It is a preview engine,
-not a spreadsheet application.
+`npm run build` creates six public JavaScript entry points, a generic Worker,
+and independent Delimited, Arrow, Parquet, and Excel WASM artifacts under
+`dist/wasm/`.
+
+## Stable JavaScript API
+
+Register only the adapters an engine may use. The allow-list is immutable for
+that engine's lifetime. Local inputs are `File`, `Blob`, and `ArrayBuffer`; an
+explicit `RangeSource` is the bounded remote (or application-owned) source
+capability.
+
+```ts
+import { createEngine, delimitedAdapter } from "tabulark";
+import { arrowIpcAdapter } from "tabulark/arrow";
+import { parquetAdapter } from "tabulark/parquet";
+import { excelAdapter } from "tabulark/excel";
+import { httpRangeSource } from "tabulark/http";
+
+const engine = await createEngine({
+  adapters: [delimitedAdapter, arrowIpcAdapter, parquetAdapter, excelAdapter],
+});
+
+const csv = await engine.open(csvFile, {
+  adapter: delimitedAdapter,
+  sourceMode: "auto", // use "large" for a local File/Blob up to 2 GiB
+  adapterOptions: {
+    dialect: "csv",
+    header: "first-row",
+    mode: "lenient",
+  },
+});
+
+const parquet = await engine.open(parquetFile, {
+  adapter: parquetAdapter,
+  adapterOptions: { sourceName: parquetFile.name },
+});
+
+const workbook = await engine.open(excelFile, {
+  adapter: excelAdapter,
+  adapterOptions: { format: "auto", sourceName: excelFile.name },
+});
+
+const remote = httpRangeSource("https://data.example.test/table.parquet", {
+  credentials: "include",
+  validation: "strong", // ETag, or Last-Modified + length when permitted
+  maxConcurrency: 2,
+});
+const remoteTable = await engine.open(remote, {
+  adapter: parquetAdapter,
+});
+```
 
-## Design principles
+In the stable API, adapter selection is explicit. Excel's `format: "auto"` and Arrow's
+`container: "auto"` inspect source bytes; filename extensions never select or
+authenticate a format.
+
+The bundled playground is a convenience layer: it uses the local file name,
+MIME type, and (when needed) a bounded signature read to choose the explicit
+adapter call for you. Applications using the stable API should continue to
+select and register an adapter themselves.
+
+`ArrayBuffer` ownership is retained by default. Set `transferInput: true` only
+when intentionally detaching an `ArrayBuffer`; using it with a `Blob` or
+`File` returns `INVALID_ARGUMENT`.
+
+`sourceMode: "auto"` keeps the conservative source policy. The opt-in
+`sourceMode: "large"` path accepts only a local `File`/`Blob` no larger than
+exactly `2,147,483,648` bytes (`2^31`, 2 GiB); it does not raise the existing
+`ArrayBuffer` staging limit or allocate a work set proportional to the file. A
+larger source fails before an open request is sent to the Worker, with
+`RESOURCE_LIMIT` details containing `resource`, `requiredBytes`, and
+`availableBytes`.
+
+`RangeSource` readers report an exact size and snapshot validator and return
+exactly the requested bytes. `TabularkEngine.open()` creates an independent
+reader for each open and closes it exactly once on failure, cancellation, or
+dataset/engine close. `sourceMode` and `transferInput` are rejected for a
+`RangeSource`. The source ceiling is exactly `4,294,967,295` bytes; a 4 GiB
+source is rejected before adapter startup. The Worker receives only an opaque
+source handle, size, and bounded transferable byte buffers. Provider requests
+are merged for overlap/adjacency, limited to four concurrent reads, and
+covered by a dataset range-cache/singleflight layer.
+
+The `tabulark/http` helper probes with `GET Range: bytes=0-0`, requires a
+precise `Content-Range` and a trusted ETag (or an explicitly allowed weak
+Last-Modified-plus-length validator), and revalidates every `206` response.
+Retries are bounded and limited to transient network/status failures. A full
+download is never implicit: `fallback: { mode: "bounded-download", maxBytes }`
+must be supplied and must fit both that bound and the engine staging budget.
+Error messages and performance samples omit URLs, query strings, headers,
+validators, and snapshot identifiers.
+
+The exact-boundary local-file release gate covers five real containers: CSV,
+Arrow File, Parquet, XLSX, and XLS. Each fixture is exactly `2^31` bytes and
+the test reads the final bounded window ending at byte `2^31 - 1`. Remote
+RangeSource gates separately use a virtual/sparse source at
+`4,294,967,295` bytes and exercise non-adjacent offsets above `2^31` without
+allocating oversized browser fixtures. Overflow and 4 GiB rejection are
+checked before adapter startup.
+
+### Tables, logical batches, and presentation
+
+```ts
+const table = await workbook.openTable(workbook.tables[0].id);
+const batch = await table.readRange({
+  rowStart: 0,
+  rowCount: 100,
+  columnStart: 0,
+  columnCount: table.metadata.schema.columns.length,
+});
+
+const nativeRows = batch.toRows();
+const displayRows = batch.toDisplayRows();
+const presentation = await table.getPresentation();
+const visiblePresentation = await table.readPresentationRange(batch.range);
+```
 
-- One `Table` abstraction for every supported data source.
-- Independently loadable source adapters, including format-specific parsers.
-- Parsing and data ownership outside the browser main thread, with WebAssembly
-  as the primary runtime for performance-sensitive components.
-- Demand-driven access instead of copying an entire dataset into JavaScript.
-- Viewport-oriented rendering, with Canvas as the first planned renderer.
-- Framework-neutral, composable building blocks.
+The stable `TableBatch` exposes logical data, its returned range, columns, and
+logical accessors. WASM buffer regions, wire descriptors, protocol versions,
+adapter ABI versions, and physical batch layout are private implementation
+details.
+
+`toRows()` preserves native values such as `bigint`, `Uint8Array`, decimals,
+temporal values, lists, structs, maps, and unions. `toDisplayRows()` returns
+only `(string | null)[][]` for rendering, accessibility, sizing, and copy.
+
+Excel tables can return a `spreadsheet-v1` presentation. It includes sheet
+visibility, frozen rows/columns, sparse row and column sizes/hidden state, a
+deduplicated static style table, range-aligned style IDs, and intersecting
+merged cells. Styles cover number formats, fonts, colors, fills, borders, and
+alignment. The high-level Canvas view uses presentation automatically:
+
+```ts
+const view = createCanvasTableView({
+  container,
+  table,
+  presentation: "auto", // default; use "ignore" for logical data only
+});
+```
 
-## Target architecture
+Forced-colors mode overrides workbook colors while retaining dimensions,
+merges, alignment, and font emphasis.
+
+Low-level painter, controller, layout, hit-testing, and selection primitives
+live under `tabulark/experimental` and carry no compatibility promise.
+
+## Format behavior
+
+### Parquet
+
+Each file exposes one table. The adapter reads the footer and metadata first,
+then only row groups and top-level projected columns intersecting a request; it
+does not stage the full file. Supported compression is uncompressed, Snappy,
+Gzip, Brotli, LZ4, LZ4_RAW, and Zstd. INT96 becomes a timezone-free nanosecond
+timestamp. LZO, encrypted Parquet, and experimental Variant/Geo types return
+`UNSUPPORTED_FEATURE`.
+
+All promised Parquet codecs in the official WebAssembly adapter use Rust
+implementations. Arrow/Parquet 59.1.0 calls the narrow `zstd` 0.13 bulk API
+directly, so the workspace supplies a Rust 1.85-compatible implementation of
+that API backed by pinned `ruzstd` 0.8.1. The release gate proves the official
+Arrow and Parquet WASM graphs contain neither `zstd-sys` nor `zstd-safe`.
+
+Cargo removes workspace patches when it publishes a crate. Therefore the
+experimental crates.io Rust features deliberately do not enable upstream's
+Zstd feature; Zstd is part of the stable JavaScript/WASM format contract, not
+the experimental Rust API contract. This prevents a crates.io consumer from
+silently receiving a C-backed implementation.
+
+### Excel
+
+Each worksheet becomes a table in workbook order with an ID such as
+`sheet-0`. Hidden and very-hidden worksheets remain addressable and preserve
+visibility. Chart, dialog, and macro sheets are skipped with a warning.
+
+Columns are named A, B, …; the first row is always data; empty cells are null.
+Excel values are display strings (`typedValues=false`). Formula cells use only
+their cached result—Tabulark never executes formulas—and missing cached values
+become null with a warning. Merged cells use the top-left value as their anchor.
+
+XLS support is deliberately limited to BIFF8. Earlier BIFF, XLSM, XLSB, ODS,
+and encrypted workbooks return `UNSUPPORTED_FEATURE`. XLS and XLSX share the
+same bounded static-presentation subset.
+
+For large XLSX, Rust indexes ZIP/ZIP64 metadata and fetches the workbook,
+relationships, shared resources, and selected worksheet ranges. For large XLS,
+Rust indexes CFB/DIFAT/FAT/miniFAT/directory data and fetches the referenced
+Workbook/Book stream ranges. In both cases it compacts only the needed content
+into a bounded workbook for the existing Calamine compatibility parser. This
+does not imply a custom XML/BIFF checkpoint engine or worksheet tile store.
+
+## Memory, cache, and lifecycle
+
+The main thread owns the only decoded-batch cache. It stores immutable backing
+objects keyed by dataset, logical table, revision, schema version, and
+normalized range; each API call receives a fresh logical facade. Concurrent
+identical misses are singleflight operations. Cancelling one caller does not
+cancel work shared by others, while cancelling every waiter sends one Worker
+cancel. A table handle may close without discarding its logical-table backing;
+dataset close or a revision/schema change evicts it.
+
+The Worker coordinates the engine-wide quota across adapters. Inside each
+Rust/WASM runtime, a checked ledger distinguishes persistent state, active
+operations, ingress/output, reclaimable native cache, and caller-owned
+telemetry. Admission clears soft native cache and retries once before returning
+`RESOURCE_LIMIT`, whose details identify required and available capacity.
+ZIP/CFB entries, decompression, worksheet dimensions, cells, styles, layout,
+merged regions, Parquet pages, and decoded batches remain bounded.
+
+Handles are nested and cleanup cascades downward:
 
 ```text
-Data source
-    -> source adapter
-    -> Worker / WebAssembly runtime
-    -> unified Table model and cache
-    -> viewport query API
-    -> renderer
-    -> application UI
+Engine
+  └─ DatasetSession
+       └─ TableHandle
+            └─ TableBatch
 ```
 
-This architecture is intentionally provisional while the first end-to-end
-prototype is being developed.
-
-## Current scaffold
-
-The repository currently contains:
-
-- A minimal Rust crate with an experimental `TableShape` value type.
-- A minimal ESM npm entry point with matching shape metadata.
-- Version synchronization and package dry-run checks.
-- GitHub Actions prepared for OIDC-based publication to crates.io and npm after
-  the initial registry bootstrap and Trusted Publisher configuration.
-
-No parser, Worker runtime, WebAssembly bridge, cache, or renderer has been
-implemented yet.
-
-## Planned data sources
-
-CSV and TSV are intended to be the first reference adapters. Longer-term
-candidates include XLSX, XLS, Parquet, Apache Arrow, Feather, SQLite query
-results, DuckDB query results, and third-party data sources.
-
-A format should not be considered supported until a released adapter is backed
-by compatibility tests.
+Close operations are idempotent. Closing a dataset closes its tables; closing
+an engine closes every dataset. Cancellation and close races settle once, and
+reservations are released on success, failure, cancellation, and close.
 
-## Non-goals
-
-Tabulark is not intended to be:
-
-- A spreadsheet editor or Excel replacement.
-- A formula calculation or workbook recalculation engine.
-- A VBA, macro, or arbitrary workbook-code runtime.
-- A pixel-perfect implementation of every Office document feature.
-- A pivot table, chart authoring, BI, or database product.
-- A mandatory all-formats bundle or complete application framework.
-
-Editing, analysis, and application-specific UI may be built on top of Tabulark,
-but they are outside the core project's scope.
-
-## Development
-
-Requirements:
-
-- Rust 1.85 or later.
-- Node.js 20 or later.
-- npm 10 or later.
+```ts
+view.destroy();
+await table.close();
+await workbook.close();
+await engine.close();
+```
 
-Run the local checks:
+## Verification
 
-```bash
+```sh
+# Rust 1.85/stable, Clippy, all features, lifecycle, fixtures, fuzz seeds
 cargo fmt --all --check
 cargo clippy --workspace --all-targets --all-features -- -D warnings
-cargo test --workspace --all-features
-cargo package --allow-dirty --locked
-npm ci
-npm run check
-```
+cargo test --workspace --all-features --locked
 
-After the first registry release, consumers will be able to install the base
-packages with:
+# Stable exports/declarations, clean package consumers, and Pages assembly
+npm run check
 
-```bash
-cargo add tabulark
-npm install tabulark
-```
+# Real module Worker/WASM, Canvas, ARIA, keyboard, copy, and forced-colors
+npm run test:browser
 
-## Repository layout
+# Independent core, Arrow, Parquet, Excel, npm, and Pages delivery budgets
+npm run benchmark:size
 
-```text
-tabulark/
-├── src/                  # Rust crate
-├── js/                   # Browser-facing ESM package entry point
-├── test/                 # JavaScript tests
-├── scripts/              # Repository validation scripts
-├── docs/                 # Vision and release documentation
-└── .github/workflows/    # CI and registry publication
+# Parquet/XLS/XLSX cold-open, range-read, and Chromium memory evidence
+npm run benchmark:formats
 ```
 
-See the [project vision](docs/vision.md) for the long-term design intent and
-[release guide](docs/releasing.md) for registry setup and publishing.
-
-## Project status
+Chromium, Firefox, and WebKit are all release-blocking desktop functional gates.
+Chromium additionally owns exact pixel snapshots, performance comparison, real
+Clipboard API coverage, and the exact-2-GiB workflow. Firefox and WebKit cover
+the four adapters, lifecycle, Blob ranges, themes, ARIA, input behavior, copy
+through a deterministic clipboard seam, and Pages smoke. The Pages post-deploy
+smoke opens CSV, Arrow IPC, Parquet, XLS, and XLSX and asserts that only used
+adapter artifacts were requested.
 
-- [ ] Validate the unified `Table` model.
-- [ ] Define the parser and Worker protocol.
-- [ ] Implement a reference CSV/TSV parser.
-- [ ] Prototype viewport-driven Canvas rendering.
-- [ ] Publish the first crates.io and npm packages.
-- [ ] Stabilize extension APIs.
+## Stability and release
 
-## Contributing
+The root, `/arrow`, `/parquet`, `/excel`, and `/http` entry points are stable
+for 0.2.x. (`/experimental` remains explicitly unstable.)
+Version 0.2 preserves the documented 0.1.0 calls and adds diagnostics,
+capability queries, performance observation, `SourceMode`, and Canvas themes.
+Rust APIs, Worker protocol v4, adapter ABI v3, wire DTOs, batch layout v1, and
+`/experimental` remain experimental/private.
 
-Tabulark is not yet ready for broad feature contributions. Design discussion,
-representative datasets, and concrete browser-preview use cases are welcome in
-[GitHub Issues](https://github.com/Ronbb/tabulark/issues).
+The `v0.1.0` tag is immutable and must never be moved or reused. npm and
+crates.io publishing is serialized behind protected GitHub Environments with
+required reviewer approval; recovery finalizes artifacts without republishing.
+See
+[docs/releasing.md](docs/releasing.md) for the immutable-release and patch
+recovery policy.
 
-## AI-assisted development
+## Repository map
 
-Tabulark makes extensive use of generative AI throughout project design,
-implementation, testing, documentation, and code review. AI-generated output is
-treated as a draft rather than trusted work: maintainers remain responsible for
-every change, and the same review, testing, security, and licensing standards
-apply regardless of how a contribution was produced.
+```text
+src/                         shared Rust model, protocol, and native adapters
+crates/tabulark-*-wasm/      four independently built WASM entry crates
+js/                          stable API, HTTP/range broker, private Worker host,
+                             batches, and view
+examples/csv-preview/        static six-format Playground
+test/fixtures/               pinned format fixtures and provenance
+test/browser/                three-browser behavior, Chromium visual/performance, and Pages smoke
+test/performance/            performance and per-artifact delivery budgets
+docs/                        architecture, testing, stability, and release policy
+```
 
 ## License
 
-Licensed under either of:
-
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
-- MIT License ([LICENSE-MIT](LICENSE-MIT))
-
-at your option.
+Dual-licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE).
+Shipped third-party material is listed in
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,37 @@
+# Third-party notices
+
+The optional `tabulark/arrow` and `tabulark/parquet` WebAssembly artifacts use
+Apache Arrow Rust 59.1.0. This includes the `arrow-*` crates used for logical
+arrays and IPC plus the `parquet` crate. Apache Arrow Rust is distributed under
+Apache-2.0, with some Arrow component crates additionally carrying MIT terms.
+
+Arrow IPC and Parquet compression support uses `brotli` (BSD-3-Clause AND MIT),
+`flate2` (MIT OR Apache-2.0), `lz4_flex` (MIT), `snap` (BSD-3-Clause), and
+`ruzstd` 0.8.1 (MIT). A narrow in-tree compatibility crate exposes
+the `zstd` 0.13 bulk API required by Arrow/Parquet while remaining Rust-only;
+its hashing dependency is `twox-hash` (MIT). `zstd-sys` and `zstd-safe` are not
+part of the official production WebAssembly dependency graph.
+
+The optional `tabulark/excel` artifact uses `calamine` 0.35.0 (MIT) for
+workbook values, formulas, and worksheet discovery. Its bounded container and
+static-presentation readers also use `cfb` (MIT), `zip` (MIT), and `quick-xml`
+(MIT).
+
+The Arrow IPC integration fixture under `test/fixtures/arrow/v1` is copied
+byte-for-byte from `apache/arrow-testing` at the revision recorded in its
+`provenance.json`. The exact upstream Apache-2.0 license is stored next to the
+fixture.
+
+The independent Parquet fixture under `test/fixtures/parquet/v1` is copied
+byte-for-byte from `apache/parquet-testing` at the pinned revision recorded in
+its `provenance.json`. Its Apache-2.0 license is stored next to the fixture.
+
+The independent XLSX fixture under `test/fixtures/excel/v1` is copied
+byte-for-byte from the XlsxWriter comparison corpus at the pinned revision
+recorded in its `provenance.json`. XlsxWriter is distributed under BSD-2-Clause;
+the upstream license is stored next to the fixture.
+
+The complete dependency versions and checksums are locked in `Cargo.lock`.
+`cargo deny check advisories licenses` is a release gate, and the release workflow emits
+an SPDX SBOM. Nothing in this notice changes the license terms supplied by an
+upstream project.

package/dist/adapters.d.ts

@@ -0,0 +1,62 @@
+import { type OfficialAdapterId } from "./official-adapter-manifest.js";
+export type { OfficialAdapterId } from "./official-adapter-manifest.js";
+export type DelimitedDialect = "csv" | "tsv";
+export type HeaderMode = "first-row" | "none";
+export type ParseMode = "lenient" | "strict";
+/** Options understood by the built-in delimited adapter. */
+export interface DelimitedAdapterOptions {
+    /** Defaults to `csv`. No filename-based selection is performed. */
+    readonly dialect?: DelimitedDialect;
+    readonly header?: HeaderMode;
+    readonly mode?: ParseMode;
+    /** One ASCII delimiter byte. Overrides the dialect default when supplied. */
+    readonly delimiter?: string;
+    /** Optional display name for the source. */
+    readonly sourceName?: string;
+}
+export type ArrowIpcContainer = "auto" | "file" | "stream";
+/** Options understood by the built-in Arrow IPC adapter. */
+export interface ArrowIpcAdapterOptions {
+    /** Defaults to `auto`; format detection belongs to the Arrow adapter. */
+    readonly container?: ArrowIpcContainer;
+    /** Optional display name for the source. */
+    readonly sourceName?: string;
+}
+/** Options understood by the built-in Parquet adapter. */
+export interface ParquetAdapterOptions {
+    /** Optional display name for the source. */
+    readonly sourceName?: string;
+}
+export type ExcelFormat = "auto" | "xls" | "xlsx";
+/** Options understood by the built-in Excel adapter. */
+export interface ExcelAdapterOptions {
+    /** Defaults to `auto`; the adapter identifies the file from its signature. */
+    readonly format?: ExcelFormat;
+    /** Optional display name for the source. */
+    readonly sourceName?: string;
+}
+/**
+ * A frozen descriptor for one built-in adapter.
+ *
+ * Descriptors select a named official artifact only. They are deliberately not
+ * factories and cannot carry a module URL or a third-party implementation.
+ */
+export interface AdapterDescriptor<Id extends OfficialAdapterId = OfficialAdapterId, Options = unknown> {
+    readonly id: Id;
+    readonly kind: "official";
+    /** Carries the option type without exposing a runtime extension point. */
+    readonly __options?: Options;
+}
+export interface AdapterRegistration {
+    readonly id: OfficialAdapterId;
+}
+/** The built-in RFC-style delimited text adapter. */
+export declare const delimitedAdapter: AdapterDescriptor<"tabulark:delimited", DelimitedAdapterOptions>;
+/** @internal Used by the stable `/arrow` entrypoint. */
+export declare function createArrowIpcAdapter(): AdapterDescriptor<"tabulark:arrow-ipc", ArrowIpcAdapterOptions>;
+/** @internal Used by the stable `/parquet` entrypoint. */
+export declare function createParquetAdapter(): AdapterDescriptor<"tabulark:parquet", ParquetAdapterOptions>;
+/** @internal Used by the stable `/excel` entrypoint. */
+export declare function createExcelAdapter(): AdapterDescriptor<"tabulark:excel", ExcelAdapterOptions>;
+/** @internal Validates and extracts the non-public Worker registration. */
+export declare function resolveOfficialAdapter(value: unknown): AdapterRegistration | undefined;

package/dist/arrow.d.ts

@@ -0,0 +1,3 @@
+export { type ArrowIpcAdapterOptions, type ArrowIpcContainer } from "./adapters.js";
+/** Opens Apache Arrow IPC File or Stream input through the lazy official Arrow artifact. */
+export declare const arrowIpcAdapter: import("./adapters.js").AdapterDescriptor<"tabulark:arrow-ipc", import("./adapters.js").ArrowIpcAdapterOptions>;