@chartcoach/catalog 0.1.6 → 0.2.0

package/LICENSE

@@ -1,21 +1,201 @@
-MIT License
-
-Copyright (c) 2026 chartcoach Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 chartcoach contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,67 +1,353 @@
 # @chartcoach/catalog
 
-JavaScript models and parsers for chartcoach catalog artifacts.
+`@chartcoach/catalog` fetches a selected or exact Guideline Catalog release,
+verifies its files, and returns immutable `Guideline` values for querying,
+reading, and citation.
 
-Read the package docs at [docs.chartcoach.dev/javascript](https://docs.chartcoach.dev/javascript).
-Read about the cataloging scheme at [docs.chartcoach.dev/catalog](https://docs.chartcoach.dev/catalog).
+chartcoach is alpha software. `openCatalog` requires a browser or server
+runtime with `fetch`, Web Crypto, `AbortSignal.timeout`, and `AbortSignal.any`.
+Node.js consumers require Node 22.19 or later.
+`loadCatalog` verifies release files that the application already holds.
+`loadCatalogData` parses descriptor-free bundle data.
 
-Install the package from an application root:
+## Query and read guidance
 
 ```bash
 npm install @chartcoach/catalog
 ```
 
 ```ts
-import { DEFAULT_CATALOG, loadCatalog } from "@chartcoach/catalog"
+import { openCatalog } from "@chartcoach/catalog";
 
-const entries = await (await fetch(DEFAULT_CATALOG.entriesUrl)).arrayBuffer()
-const manifestText = await (await fetch(DEFAULT_CATALOG.manifestUrl)).text()
+const catalog = await openCatalog();
+const candidates = catalog.query({ contains: "direct labels", limit: 5 });
+const ids = candidates.map(({ id }) => id);
+const records = catalog.read({ ids, sourceDetail: "minimal" });
+const citations = catalog.cite({ ids });
+const info = await catalog.describe();
 
-const catalog = await loadCatalog({ entries, manifestText })
-const guideline = catalog.require("compare-percentages-with-bars-not-pies")
+console.log(records[0]?.title);
 ```
 
-`@chartcoach/catalog` accepts bytes that the caller already acquired. Use
-`fetch`, `fs.readFile`, `Bun.file`, `Deno.readFile`, or a test fixture to read
-the artifacts, then pass `entries` and optional manifest data to `loadCatalog`.
+```text
+Directly label colored series instead of relying on a color key
+```
+
+`query`, `read`, and `cite` run synchronously over the loaded `Catalog`.
+`describe` is asynchronous because it computes SHA-256 digests and can fetch
+selected profile metadata.
+
+Reference parsing and APA citations use [RefKit](https://peter-gy.github.io/refkit/).
+The module initializes its WebAssembly engine during import. Browser builds must
+serve RefKit's bundled `.wasm` asset at its module-relative URL. A restrictive
+[Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)
+must allow `'wasm-unsafe-eval'` in `script-src` and the asset origin in `connect-src`.
+
+`contains` matches a contiguous phrase in the ID, title, or description,
+ignoring case and normalizing whitespace, hyphens, and underscores. For empty
+matches, shorten the phrase or follow [Find guidelines](https://docs.chartcoach.dev/querying)
+to query section text with the application's data engine.
+
+## Choose a release URL
+
+`openCatalog(location, { fetch, signal })` accepts an absolute HTTP or HTTPS URL:
+
+| Location       | Behavior                                      |
+| -------------- | --------------------------------------------- |
+| `catalog.json` | Follows the currently selected public release |
+| `release.json` | Keeps one release digest across calls         |
+| Omitted        | Opens the official selected catalog           |
+
+The loader verifies the release digest, then checks the byte count and SHA-256
+hash of `MANIFEST.md` and `entries.parquet` before parsing them. Pass a custom
+`fetch` implementation when the runtime does not use `globalThis.fetch`. Pass
+an `AbortSignal` to cancel descriptor and artifact requests.
+The returned catalog exposes the verified descriptor as `catalog.release` and
+its sanitized exact `release.json` URL as `catalog.releaseUrl`.
+
+## Load files your app already has
+
+`loadCatalogData` accepts Parquet bytes and manifest text:
 
 ```ts
-import { readFile } from "node:fs/promises"
-import { loadCatalog } from "@chartcoach/catalog"
+import { readFile } from "node:fs/promises";
+import { loadCatalogData } from "@chartcoach/catalog";
 
+const catalog = await loadCatalogData({
+  entries: await readFile("dist/catalog/entries.parquet"),
+  manifestText: await readFile("dist/catalog/MANIFEST.md", "utf8"),
+});
+```
+
+`loadCatalogData` validates the manifest vocabulary and guideline fields.
+Release integrity remains caller-owned because this input contains no
+`release.json`.
+
+Use `loadCatalog` when the application already has a parsed release and the
+files listed by its descriptor:
+
+```ts
+import { readFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { loadCatalog, parseCatalogRelease } from "@chartcoach/catalog";
+
+const releasePath = "dist/release/release.json";
+const release = parseCatalogRelease(JSON.parse(await readFile(releasePath, "utf8")));
 const catalog = await loadCatalog({
-  entries: await readFile("entries.parquet"),
-  manifestText: await readFile("MANIFEST.md", "utf8"),
-})
+  release,
+  releaseUrl: pathToFileURL(releasePath),
+  entries: await readFile("dist/release/entries.parquet"),
+  manifest: await readFile("dist/release/MANIFEST.md"),
+});
+```
+
+`loadCatalog` verifies the release digest and both core files before returning
+a catalog with its exact release URL. Each core file is capped at 64 MiB.
+
+## Catalog methods
+
+| Method                                 | Result                                                                           |
+| -------------------------------------- | -------------------------------------------------------------------------------- |
+| `query(options?)`                      | Compact guideline entry candidates. The default limit is 50.                     |
+| `read({ ids, roles?, sourceDetail? })` | Guideline entry records with ordered sections and parsed sources.                |
+| `cite({ ids, urlTemplate? })`          | Guideline links, formatted guideline citations, and structured source citations. |
+| `table(name)`                          | Cached, immutable rows for a canonical catalog table.                            |
+| `describe({ profile?, signal? })`      | Catalog identity, table schemas and counts, vocabulary, and profile information. |
+| `get(id)`                              | A `Guideline` or `undefined`.                                                    |
+| `require(id)`                          | A `Guideline` or a `CatalogError` with code `"lookup"`.                          |
+
+`catalog.guidelines`, iteration, `catalog.length`, `catalog.labels()`,
+`catalog.sectionRoles()`, `catalog.release`, `catalog.releaseUrl`, and
+`toMarkdown(guideline)` support direct application composition.
+
+JavaScript option names use camel case. Shared JSON result fields use snake
+case, including `source_title`, `reference_id`, and `release_digest`.
+
+## Query canonical tables
+
+`catalog.table(name)` exposes the same six relations as Python: `guidelines`,
+`sections`, `guideline_labels`, `references`, `guideline_references`, and
+`guideline_sources`. Rows and nested values are immutable. Unknown names raise
+`CatalogError` with code `"lookup"`. `describe().tables` supplies names, row counts,
+and logical column types, including for empty tables.
+
+```ts
+const sources = catalog.table("guideline_sources");
+console.log(sources[0]?.authors);
+console.log((await catalog.describe()).tables);
+```
+
+For native SQL, install [DuckDB's Node.js client](https://duckdb.org/docs/stable/clients/node_neo/overview)
+alongside the catalog package:
+
+```bash
+npm install @chartcoach/catalog @duckdb/node-api
+```
+
+```ts
+import { DuckDBInstance } from "@duckdb/node-api";
+import { registerCatalog } from "@chartcoach/catalog/duckdb";
+
+const db = await DuckDBInstance.create(":memory:");
+const connection = await db.connect();
+try {
+  await registerCatalog(connection, catalog);
+  const result = await connection.runAndReadAll(
+    'SELECT source_type, count(*) FROM "references" GROUP BY source_type',
+  );
+  console.log(result.getRowsJson());
+} finally {
+  connection.closeSync();
+  db.closeSync();
+}
+```
+
+`registerCatalog(connection, catalog, { ids? })` creates or replaces the six
+catalog tables and returns the same connection. The caller owns configuration,
+transactions, and closing. Omit `ids` for the full catalog. An empty array creates
+six empty typed tables. Selected IDs retain all their linked source records.
+Unknown IDs and invalid references fail before table replacement.
+
+## Query in the browser with DuckDB-WASM
+
+The optional `@chartcoach/catalog/duckdb-wasm` adapter registers the same six
+tables in a caller-owned [DuckDB-WASM](https://duckdb.org/docs/stable/clients/wasm/overview)
+connection. DuckDB-WASM runs SQL in a browser worker. With a loaded `catalog` and
+an `AsyncDuckDBConnection` named `connection`:
+
+```ts
+import { registerCatalog } from "@chartcoach/catalog/duckdb-wasm";
+
+await registerCatalog(connection, catalog, { ids });
+const result = await connection.query('SELECT * FROM "references"');
+console.log(result.toArray());
+```
+
+Install `@duckdb/duckdb-wasm` alongside this package. The adapter accepts the same
+`{ ids? }` option as the Node adapter and preserves caller-owned connections and
+transactions. It releases its temporary in-memory files after registration.
+The caller owns worker creation and database shutdown.
+
+Catalog artifacts can also be read directly by DuckDB. Use the verified bytes
+already retained by a release-backed catalog:
+
+```ts
+await connection.bindings.registerFileBuffer(
+  "entries.parquet",
+  await catalog.artifact("entries.parquet"),
+);
+const rows = await connection.query(
+  "SELECT id, title FROM read_parquet('entries.parquet') LIMIT 5",
+);
+console.log(rows.toArray());
+await connection.bindings.dropFile("entries.parquet");
+```
+
+Use DuckDB's EH bundle in a browser with WebAssembly exception handling, and serve
+its worker and WASM assets through your application. Its
+first JSON query loads a version-matched extension from `extensions.duckdb.org`
+unless you configure another extension repository. Your Content Security Policy
+must permit WASM compilation, workers, and that extension origin. The
+[chat app](../../apps/chat) demonstrates same-origin assets, verified HTTPS
+Parquet loading, and linked filters with Mosaic.
+
+## Inspect a profile
+
+```ts
+const info = await catalog.describe();
+const profile = info.profiles[0];
+
+if (profile !== undefined) {
+  const controller = new AbortController();
+  const details = await catalog.describe({ profile, signal: controller.signal });
+  console.log(details.profile?.distance_metric, details.profile?.dimensions);
+}
 ```
 
-Parse release metadata when code needs artifact URLs:
+`describe({ profile })` verifies `profile.json` against the release byte count,
+SHA-256 hash, 64 KiB limit, catalog entries digest, and manifest digest. It
+keeps the index unopened and caches verified metadata per `Catalog` instance.
+Each call has its own cancellation signal.
+
+`ProfileInfo` contains the profile and document schema versions, embedding
+binding, dimensions, `distance_metric`, `python_requirements`, LanceDB version,
+and projection metadata.
+
+Catalogs created with `loadCatalog` retain the release descriptor and profile
+names from caller-held bytes. Use `openCatalog` to fetch profile metadata over
+HTTP.
+
+`Guideline` values, operation results, their nested arrays, and manifest
+definitions are frozen. Pass changed record objects to a new `Catalog`. Use
+`loadCatalogData` after writing changed rows to `entries.parquet`.
+
+`CatalogError` exposes `code`, `details`, and `hints`. Its codes use the shared
+Python and JavaScript error vocabulary.
+
+## Compose verified artifacts
 
 ```ts
-import {
-  catalogArtifact,
-  catalogArtifactUrl,
-  parseCatalogReleaseMetadata,
-} from "@chartcoach/catalog"
-
-const metadata = parseCatalogReleaseMetadata(await response.json())
-const entriesUrl = catalogArtifactUrl(
-  metadataUrl,
-  catalogArtifact(metadata, "entries"),
-)
-
-const entries = await (await fetch(entriesUrl)).arrayBuffer()
+const entries = await catalog.artifact("entries.parquet");
+const paths = Object.keys(catalog.release?.artifacts ?? {});
 ```
 
-Run package checks from the repository root:
+`artifact(path, { signal? })` returns a caller-owned `Uint8Array` after checking
+its byte count and SHA-256 hash. The release inventory lists optional files
+such as `profiles/<profile>/documents.parquet` and
+`profiles/<profile>/projection.parquet`. Pass Parquet bytes to your data library.
+Core bytes and small metadata are reused in memory.
+`loadCatalog` makes its supplied core bytes available through the same method.
+
+`openCatalog` accepts an optional `cache` with asynchronous `get(sha256, bytes)` and
+`put(sha256, bytes)` methods. Cached bytes are verified before reuse. A custom
+`fetch` can resolve other URI schemes, including S3, using the caller's storage
+client and credentials. Return a standard `Response` and forward its request
+signal to the client.
+
+## Open local files and cache releases in Node.js
+
+```ts
+import { openCatalog, artifactPath } from "@chartcoach/catalog/node";
+
+const catalog = await openCatalog("./dist/release");
+const entriesPath = await artifactPath(catalog, "entries.parquet");
+```
+
+The Node entry point accepts local bundles, release directories, deployed
+roots, descriptor paths, and remote descriptor URLs. It caches verified bytes
+in the per-user platform cache directory, sharing the `chartcoach` cache layout
+with Python. `cacheDirectory` overrides that location.
+`artifactPath(catalog, path, { signal? })` streams a missing artifact to disk and
+returns a verified local path for native DuckDB, Arrow, or other file readers.
+It verifies an existing file before reuse. Each artifact is capped at 1 GiB,
+and core files at 64 MiB.
+
+Opening `catalog.json` refreshes the selection. A digest-addressed
+`release.json` URL can reopen offline after its descriptor and core files have
+been cached. Optional files become available offline after they are requested.
+
+Use the browser entry point in browser applications. Node filesystem imports
+are confined to `@chartcoach/catalog/node`.
+
+## Open a native search index
+
+Install [LanceDB](https://lancedb.github.io/lancedb/js/), the application's
+vector and full-text database client:
 
 ```bash
-pnpm --dir packages/catalog-javascript lint
-pnpm --dir packages/catalog-javascript typecheck
-pnpm --dir packages/catalog-javascript test
-pnpm --dir packages/catalog-javascript build
+npm install @lancedb/lancedb
 ```
 
-## License
+Open a release built with an index profile. This example uses `./dist/release`:
+
+```ts
+import { connect } from "@lancedb/lancedb";
+import { openCatalog, indexPath } from "@chartcoach/catalog/node";
+
+const catalog = await openCatalog("./dist/release");
+const [profile] = (await catalog.describe()).profiles;
+if (!profile) throw new Error("Choose a catalog release with an index profile.");
+
+const db = await connect(await indexPath(catalog, profile));
+const table = await db.openTable("documents");
+try {
+  await table.checkout(await table.version());
+  const matches = await table.query().fullTextSearch("direct labels").limit(5).toArray();
+  const ids = [...new Set(matches.map((row) => row.parent_id))];
+  console.log(catalog.read({ ids }));
+} finally {
+  table.close();
+  db.close();
+}
+```
+
+`indexPath(catalog, profile, { directory?, signal? })` verifies the profile and
+archive, then returns an extracted database directory containing `documents.lance`.
+The default extraction is a read-only generation in the catalog's cache directory
+on POSIX systems. Repeated calls reuse a completed generation. Pin the native
+table with `checkout` before querying shared cached data.
+
+Pass a new `directory` for a writable, caller-owned extraction. This option is
+required on Windows. Existing directories are rejected. The caller owns cleanup.
+Extraction rejects unsafe paths, links, colliding names, and oversized archives.
+Cancellation rejects the operation and cleans its incomplete extraction.
+
+Use `table.vectorSearch(vector)` for application-supplied query embeddings and
+`table.query().fullTextSearch(text)` for provider-free search. String-based
+embedding search requires the application to configure a compatible LanceDB
+embedding function. A stored Python embedding binding is not a JavaScript
+provider registration.
+
+`parseProfileMetadata(value)` validates and freezes `profile.json`. Profiles use
+flat lowercase IDs such as `minilm-normalized` and contain `profile.json` plus
+`index.tar.gz`. A release may also contain `documents.parquet` and
+`projection.parquet` exports. The package exports `EntryCandidate`,
+`GuidelineEntryRecord`, `ProfileInfo`, constructor and loader inputs, operation
+options, manifest types, release types, and profile metadata types.
+
+| Page                                                 | Details                                                      |
+| ---------------------------------------------------- | ------------------------------------------------------------ |
+| [JavaScript](https://docs.chartcoach.dev/javascript) | Release loading, catalog methods, and Markdown serialization |
+| [Catalog data](https://docs.chartcoach.dev/catalog)  | Guideline fields and published file layouts                  |
 
-MIT. See [LICENSE](../../LICENSE).
+Licensed under Apache-2.0.

package/dist/duckdb-wasm.d.ts

@@ -0,0 +1,8 @@
+import { n as Catalog } from "./model-De0MF-zg.js";
+import { t as RegisterCatalogOptions } from "./registration-CgQGMUIH.js";
+import { AsyncDuckDBConnection } from "@duckdb/duckdb-wasm";
+//#region src/duckdb-wasm.d.ts
+/** Create or replace canonical catalog tables in a caller-owned DuckDB-WASM connection. */
+declare function registerCatalog(connection: AsyncDuckDBConnection, catalog: Catalog, options?: RegisterCatalogOptions): Promise<AsyncDuckDBConnection>;
+//#endregion
+export { type RegisterCatalogOptions, registerCatalog };

package/dist/duckdb-wasm.js

@@ -0,0 +1,22 @@
+import { t as registrationPlan } from "./registration-DXhS7vgr.js";
+//#region src/duckdb-wasm.ts
+/** Create or replace canonical catalog tables in a caller-owned DuckDB-WASM connection. */
+async function registerCatalog(connection, catalog, options = {}) {
+	for (const { sql, rows } of registrationPlan(catalog, options, "file")) {
+		const file = `chartcoach-${crypto.randomUUID()}.json`;
+		await connection.bindings.registerFileBuffer(file, new TextEncoder().encode(rows));
+		try {
+			const statement = await connection.prepare(sql);
+			try {
+				await statement.query(file);
+			} finally {
+				await statement.close();
+			}
+		} finally {
+			await connection.bindings.dropFile(file);
+		}
+	}
+	return connection;
+}
+//#endregion
+export { registerCatalog };

package/dist/duckdb.d.ts

@@ -0,0 +1,8 @@
+import { n as Catalog } from "./model-De0MF-zg.js";
+import { t as RegisterCatalogOptions } from "./registration-CgQGMUIH.js";
+import { DuckDBConnection } from "@duckdb/node-api";
+//#region src/duckdb.d.ts
+/** Create or replace canonical catalog tables in a caller-owned DuckDB connection. */
+declare function registerCatalog(connection: DuckDBConnection, catalog: Catalog, options?: RegisterCatalogOptions): Promise<DuckDBConnection>;
+//#endregion
+export { type RegisterCatalogOptions, registerCatalog };