@quillmark/quiver 0.16.0 → 0.18.1

package/dist/node.js

@@ -1,75 +1,70 @@
 /**
- * Node-only entrypoint.
+ * Node-only entrypoint: the factories that read a filesystem, as free
+ * functions. Each returns a `Quiver`; the class itself is the browser-safe one
+ * from the main entry, unmodified. Importing this module installs nothing, so
+ * the import path is the whole contract and a bundler drops what is not called.
  *
- * Importing this module is the consumer's explicit declaration of intent:
- * "I am running in Node and want the Node-only Quiver factories." It exposes
- * the same `Quiver` class as the main entry, augmented with `fromDir`,
- * `fromPackage`, `fromBuiltDir`, `build`, and `buildPackage` static methods.
+ * Bundler note: this entry pulls in `./source-loader.js`, `./build.js`, and
+ * `./transports/fs-built-transport.js`, all of which statically import `node:*`
+ * builtins. Browser bundles must never reach it. The main entry (`./index.js`)
+ * makes no static or dynamic reference to it.
+ */
+import { createQuiver } from './quiver.js';
+import { scanSourceQuiver, SourceLoader } from './source-loader.js';
+import { buildQuiver } from './build.js';
+import { loadBuiltQuiver } from './built-loader.js';
+import { FsBuiltTransport } from './transports/fs-built-transport.js';
+import { fileURLToPath } from 'node:url';
+/**
+ * Reads a Source Quiver from a local directory containing `Quiver.yaml` and
+ * `quills/<name>/<version>/Quill.yaml` entries.
+ *
+ * Also accepts an `import.meta.url`-style `file://` URL; the URL's parent
+ * directory is used as the source root.
  *
- * Side effect: at module evaluation time, the Node-only static methods are
- * installed on the shared `Quiver` constructor. Any other module that already
- * imports `Quiver` from the main entry will see the additional methods at
- * runtime — but TypeScript will only expose them on the binding imported from
- * here, so the import path remains the contract.
+ * A quiver installed from npm is a directory like any other:
+ * `dirname(createRequire(import.meta.url).resolve('<pkg>/Quiver.yaml'))` is its
+ * root, resolved from the caller, whose dependencies are reachable from the
+ * caller alone under an isolated `node_modules` layout.
  *
- * Bundler note: importing this entry pulls in `./source-loader.js`,
- * `./build.js`, and `./transports/fs-built-transport.js`, all of which
- * statically import `node:*` builtins. Browser bundles must never reach this
- * module. The main entry (`./index.js`) makes no static or dynamic reference
- * to it.
+ * Throws `quiver_invalid` on schema violations, `transport_error` on I/O
+ * failure.
  */
-import { Quiver as Base } from "./quiver.js";
-import { QuiverError } from "./errors.js";
-import { scanSourceQuiver, SourceLoader } from "./source-loader.js";
-import { buildQuiver } from "./build.js";
-import { loadBuiltQuiver } from "./built-loader.js";
-import { FsBuiltTransport } from "./transports/fs-built-transport.js";
-import { createRequire } from "node:module";
-import { dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-export const Quiver = Base;
-// ---------------------------------------------------------------------------
-// 2. Runtime patch — install Node-only statics on the shared class.
-// ---------------------------------------------------------------------------
-Quiver.fromDir = async function fromDir(pathOrFileUrl) {
-    const dir = pathOrFileUrl.startsWith("file://")
-        ? fileURLToPath(new URL(".", pathOrFileUrl))
+export async function fromDir(pathOrFileUrl) {
+    const dir = pathOrFileUrl.startsWith('file://')
+        ? fileURLToPath(new URL('.', pathOrFileUrl))
         : pathOrFileUrl;
     const { meta, catalog } = await scanSourceQuiver(dir);
-    return Base._fromLoader(meta.name, catalog, new SourceLoader(dir));
-};
-Quiver.fromBuiltDir = async function fromBuiltDir(dirPath) {
+    return createQuiver(meta.name, catalog, new SourceLoader(dir));
+}
+/**
+ * Loads a packed (build-output) quiver from a local directory containing
+ * `latest.json` and the manifest/bundle/store files written by `build`.
+ * Symmetric to `Quiver.fromBuiltUrl(url)` but reads from disk instead of HTTP:
+ * no network required.
+ *
+ * Use this for server-side runtime when a packed artifact ships in the
+ * deployment image; consumers can keep source quivers as devDependencies and
+ * avoid self-fetching over their own load balancer.
+ *
+ * Throws `quiver_invalid` on format errors, `transport_error` on I/O failure.
+ */
+export async function fromBuiltDir(dirPath) {
     return loadBuiltQuiver(new FsBuiltTransport(dirPath));
-};
-Quiver.fromPackage = async function fromPackage(specifier) {
-    const req = createRequire(import.meta.url);
-    let yamlPath;
-    try {
-        yamlPath = req.resolve(`${specifier}/Quiver.yaml`);
-    }
-    catch (err) {
-        throw new QuiverError("transport_error", `Failed to resolve quiver package "${specifier}": ${err.message}`, { cause: err });
-    }
-    return Quiver.fromDir(dirname(yamlPath));
-};
-Quiver.build = async function build(sourceDir, outDir, opts) {
-    return buildQuiver(sourceDir, outDir, opts);
-};
-Quiver.buildPackage = async function buildPackage(specifier, outDir, opts) {
-    const req = createRequire(import.meta.url);
-    let yamlPath;
-    try {
-        yamlPath = req.resolve(`${specifier}/Quiver.yaml`);
-    }
-    catch (err) {
-        throw new QuiverError("transport_error", `Failed to resolve quiver package "${specifier}": ${err.message}`, { cause: err });
-    }
-    return buildQuiver(dirname(yamlPath), outDir, opts);
-};
-// ---------------------------------------------------------------------------
-// 3. Re-export the rest of the public surface so consumers get one import.
-// ---------------------------------------------------------------------------
-export { QuiverError } from "./errors.js";
+}
+/**
+ * Reads the Source Quiver at sourceDir, validates it, and writes the runtime
+ * build artifact to outDir, which the build clears first and therefore owns.
+ *
+ * Throws `quiver_invalid` on source validation failures, `transport_error` on
+ * I/O failures and on an outDir holding the source quiver or the cwd.
+ */
+export async function build(sourceDir, outDir) {
+    return buildQuiver(sourceDir, outDir);
+}
+// The rest of the public surface, so a Node consumer needs one import.
+export { Quiver } from './quiver.js';
+export { QuiverError } from './errors.js';
 // Engine types (`Quillmark`, `Quill`, `Document`, `RenderResult`, …) are not
 // re-exported: import them straight from the `@quillmark/wasm` peer dependency,
 // which is the single source of truth for the engine contract.

package/dist/quiver-yaml.js

@@ -5,10 +5,10 @@
  * simple two-field schema (name, description), but using a proper YAML parser
  * ensures correct handling of quoting, escaping, and multi-line strings.
  */
-import { parse as parseYaml } from "yaml";
-import { QuiverError } from "./errors.js";
+import { parse as parseYaml } from 'yaml';
+import { QuiverError } from './errors.js';
 const NAME_RE = /^[A-Za-z0-9_-]+$/;
-const KNOWN_FIELDS = new Set(["name", "description"]);
+const KNOWN_FIELDS = new Set(['name', 'description']);
 /**
  * Parses and validates Quiver.yaml contents.
  *
@@ -20,44 +20,44 @@ const KNOWN_FIELDS = new Set(["name", "description"]);
  *   - `description` present but not a string
  */
 export function parseQuiverYaml(raw) {
-    const text = typeof raw === "string" ? raw : new TextDecoder().decode(raw);
+    const text = typeof raw === 'string' ? raw : new TextDecoder().decode(raw);
     let parsed;
     try {
         parsed = parseYaml(text);
     }
     catch (err) {
-        throw new QuiverError("quiver_invalid", `Quiver.yaml: YAML parse failure — ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+        throw new QuiverError('quiver_invalid', `Quiver.yaml: YAML parse failure — ${err instanceof Error ? err.message : String(err)}`, { cause: err });
     }
-    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new QuiverError("quiver_invalid", `Quiver.yaml: expected a mapping at the top level, got ${Array.isArray(parsed) ? "array" : String(parsed)}`);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new QuiverError('quiver_invalid', `Quiver.yaml: expected a mapping at the top level, got ${Array.isArray(parsed) ? 'array' : String(parsed)}`);
     }
     const doc = parsed;
     // Check for unknown fields (strict mode)
     for (const key of Object.keys(doc)) {
         if (!KNOWN_FIELDS.has(key)) {
-            throw new QuiverError("quiver_invalid", `Quiver.yaml: unknown field "${key}" — only "name" and "description" are valid in V1`);
+            throw new QuiverError('quiver_invalid', `Quiver.yaml: unknown field "${key}" — only "name" and "description" are valid in V1`);
         }
     }
     // Validate `name`
-    if (!("name" in doc)) {
-        throw new QuiverError("quiver_invalid", `Quiver.yaml: required field "name" is missing`);
+    if (!('name' in doc)) {
+        throw new QuiverError('quiver_invalid', `Quiver.yaml: required field "name" is missing`);
     }
-    if (typeof doc["name"] !== "string") {
-        throw new QuiverError("quiver_invalid", `Quiver.yaml: "name" must be a string, got ${typeof doc["name"]}`);
+    if (typeof doc['name'] !== 'string') {
+        throw new QuiverError('quiver_invalid', `Quiver.yaml: "name" must be a string, got ${typeof doc['name']}`);
     }
-    const name = doc["name"];
+    const name = doc['name'];
     if (!NAME_RE.test(name)) {
-        throw new QuiverError("quiver_invalid", `Quiver.yaml: "name" value "${name}" contains invalid characters — only [A-Za-z0-9_-] are allowed`);
+        throw new QuiverError('quiver_invalid', `Quiver.yaml: "name" value "${name}" contains invalid characters — only [A-Za-z0-9_-] are allowed`);
     }
     // Validate optional `description`
-    if ("description" in doc && doc["description"] !== undefined) {
-        if (typeof doc["description"] !== "string") {
-            throw new QuiverError("quiver_invalid", `Quiver.yaml: "description" must be a string if present, got ${typeof doc["description"]}`);
+    if ('description' in doc && doc['description'] !== undefined) {
+        if (typeof doc['description'] !== 'string') {
+            throw new QuiverError('quiver_invalid', `Quiver.yaml: "description" must be a string if present, got ${typeof doc['description']}`);
         }
     }
     const meta = { name };
-    if (typeof doc["description"] === "string") {
-        meta.description = doc["description"];
+    if (typeof doc['description'] === 'string') {
+        meta.description = doc['description'];
     }
     return meta;
 }

package/dist/quiver.d.ts

@@ -5,53 +5,40 @@
  * (either source-backed or build-output-backed).
  *
  * This module is browser-safe: only `fromBuiltUrl` and the instance API live
- * here. Node-only factories (`fromDir`, `fromPackage`, `fromBuiltDir`,
- * `build`) are installed on this class by `./node.js`, which is the
- * consumer's explicit opt-in to the Node API surface.
+ * here. The filesystem factories are free functions in `./node.js`; the class
+ * is the same either way.
  */
-import { Quill } from "@quillmark/wasm";
-/** @internal Internal loader strategy: source or build output. */
+import { Quill } from '@quillmark/wasm';
+/** Loader strategy: source or build output. Package-internal. */
 export interface QuiverLoader {
     loadTree(name: string, version: string): Promise<Map<string, Uint8Array>>;
 }
+/**
+ * The private constructor's only door, closed over by the static block below.
+ * Exported as `createQuiver` for this package's loaders and reachable from no
+ * entry in `exports`, so a consumer holds the factories and nothing else.
+ */
+declare let create: (name: string, catalog: Map<string, string[]>, loader: QuiverLoader) => Quiver;
 export declare class Quiver {
     #private;
     readonly name: string;
     /**
-     * Private constructor — use static factory methods (`Quiver.fromBuiltUrl`,
-     * or the Node-only `Quiver.fromDir` / `Quiver.fromPackage` /
-     * `Quiver.fromBuiltDir` installed by `@quillmark/quiver/node`). TS prevents
-     * external `new Quiver(...)` at compile time.
+     * Private constructor. A Quiver comes from a factory (`Quiver.fromBuiltUrl`,
+     * or `fromDir` / `fromBuiltDir` from `@quillmark/quiver/node`), which is what
+     * names the thing being read.
      */
     private constructor();
-    /**
-     * @internal Construction escape hatch around the private constructor. Used
-     * by `loadBuiltQuiver` and by the Node entry (`./node.js`) when installing
-     * `fromDir` / `fromPackage`. Not part of the public API.
-     */
-    static _fromLoader(name: string, catalog: Map<string, string[]>, loader: QuiverLoader): Quiver;
     /**
      * Browser-safe factory. Loads build output from an HTTP/HTTPS URL.
      *
      * Origin-relative URLs (e.g. `/quivers/foo/`) are accepted in browser
      * environments. `file://` URLs are rejected — to load build output from
-     * disk in Node, use `Quiver.fromBuiltDir(path)` from
-     * `@quillmark/quiver/node`.
+     * disk in Node, use `fromBuiltDir(path)` from `@quillmark/quiver/node`.
      *
      * Throws `transport_error` on network/HTTP failure, `quiver_invalid`
      * on format errors.
      */
     static fromBuiltUrl(url: string): Promise<Quiver>;
-    /**
-     * Browser-safe factory. Seeds the catalog from caller-provided manifest
-     * bytes — never fetches `latest.json` — then fetches bundles lazily and
-     * content-addressed, relative to `baseUrl`, like `fromBuiltUrl`. For SSR
-     * consumers that already hold the manifest at build time.
-     *
-     * Throws `quiver_invalid` on malformed manifest bytes, `transport_error`
-     * on a `file://` baseUrl or a later bundle fetch failure.
-     */
-    static fromManifest(baseUrl: string, manifestBytes: Uint8Array): Promise<Quiver>;
     /** Returns all known quill names, sorted lexicographically. */
     quillNames(): string[];
     /**
@@ -65,11 +52,15 @@ export declare class Quiver {
      * Selector forms: `name`, `name@x`, `name@x.y`, `name@x.y.z`. Picks the
      * highest matching version in this quiver.
      *
+     * Sync, and in-memory by construction rather than by implementation: every
+     * loader materializes the catalog as the quiver is built, and `QuiverLoader`
+     * carries one verb, `loadTree`, which resolution never reaches.
+     *
      * Throws:
      *   - `invalid_ref` if ref fails parseQuillRef
      *   - `quill_not_found` if no version matches
      */
-    resolve(ref: string): Promise<string>;
+    resolve(ref: string): string;
     /**
      * Returns a `Quill` for a ref (selector or canonical).
      *
@@ -83,6 +74,11 @@ export declare class Quiver {
      * first. Materializes once and caches per canonical ref — concurrent calls
      * coalesce into a single load.
      *
+     * BORROWED, not handed over: the quill is the quiver's, shared with every
+     * other caller for the same ref, and lives as long as the quiver. Do not
+     * `free()` it: the next `getQuill` for that ref would hand out a freed
+     * handle. A caller wanting one of its own mints it from `.toTree()`.
+     *
      * Throws:
      *   - `invalid_ref` if ref is malformed
      *   - `quill_not_found` if ref does not match any version in this quiver
@@ -90,13 +86,5 @@ export declare class Quiver {
      *   - propagates validation errors from Quill.fromTree() unchanged
      */
     getQuill(ref: string): Promise<Quill>;
-    /**
-     * Prefetches the tree for every quill version in this quiver. Fail-fast.
-     *
-     * Network-bound only — does not materialize Quill instances and does not
-     * require an engine. Subsequent `getQuill` calls reuse the cached trees,
-     * skipping the fetch (the tree then evicts as its quill materializes).
-     * Rejects on the first fetch failure.
-     */
-    warm(): Promise<void>;
 }
+export { create as createQuiver };

package/dist/quiver.js

@@ -5,14 +5,19 @@
  * (either source-backed or build-output-backed).
  *
  * This module is browser-safe: only `fromBuiltUrl` and the instance API live
- * here. Node-only factories (`fromDir`, `fromPackage`, `fromBuiltDir`,
- * `build`) are installed on this class by `./node.js`, which is the
- * consumer's explicit opt-in to the Node API surface.
+ * here. The filesystem factories are free functions in `./node.js`; the class
+ * is the same either way.
  */
-import { QuiverError } from "./errors.js";
-import { Quill } from "@quillmark/wasm";
-import { parseQuillRef } from "./ref.js";
-import { matchesSemverSelector, chooseHighestVersion } from "./semver.js";
+import { QuiverError } from './errors.js';
+import { Quill } from '@quillmark/wasm';
+import { parseQuillRef } from './ref.js';
+import { matchesSemverSelector, chooseHighestVersion } from './semver.js';
+/**
+ * The private constructor's only door, closed over by the static block below.
+ * Exported as `createQuiver` for this package's loaders and reachable from no
+ * entry in `exports`, so a consumer holds the factories and nothing else.
+ */
+let create;
 export class Quiver {
     name;
     #catalog;
@@ -25,68 +30,37 @@ export class Quiver {
      */
     #quillCache = new Map();
     /**
-     * Cache of fetched trees, keyed by canonical ref. Populated by `warm()`
-     * and on first `getQuill` for a ref; an entry is evicted once its quill
-     * materializes successfully. Promise values so concurrent fetches coalesce.
-     */
-    #treeCache = new Map();
-    /**
-     * Private constructor — use static factory methods (`Quiver.fromBuiltUrl`,
-     * or the Node-only `Quiver.fromDir` / `Quiver.fromPackage` /
-     * `Quiver.fromBuiltDir` installed by `@quillmark/quiver/node`). TS prevents
-     * external `new Quiver(...)` at compile time.
+     * Private constructor. A Quiver comes from a factory (`Quiver.fromBuiltUrl`,
+     * or `fromDir` / `fromBuiltDir` from `@quillmark/quiver/node`), which is what
+     * names the thing being read.
      */
     constructor(name, catalog, loader) {
         this.name = name;
         this.#catalog = new Map(catalog);
         this.#loader = loader;
     }
-    /**
-     * @internal Construction escape hatch around the private constructor. Used
-     * by `loadBuiltQuiver` and by the Node entry (`./node.js`) when installing
-     * `fromDir` / `fromPackage`. Not part of the public API.
-     */
-    static _fromLoader(name, catalog, loader) {
-        return new Quiver(name, catalog, loader);
+    static {
+        create = (name, catalog, loader) => new Quiver(name, catalog, loader);
     }
     /**
      * Browser-safe factory. Loads build output from an HTTP/HTTPS URL.
      *
      * Origin-relative URLs (e.g. `/quivers/foo/`) are accepted in browser
      * environments. `file://` URLs are rejected — to load build output from
-     * disk in Node, use `Quiver.fromBuiltDir(path)` from
-     * `@quillmark/quiver/node`.
+     * disk in Node, use `fromBuiltDir(path)` from `@quillmark/quiver/node`.
      *
      * Throws `transport_error` on network/HTTP failure, `quiver_invalid`
      * on format errors.
      */
     static async fromBuiltUrl(url) {
-        if (url.startsWith("file://")) {
-            throw new QuiverError("transport_error", `Quiver.fromBuiltUrl requires an http(s):// or origin-relative URL; got "${url}". For local build output, use Quiver.fromBuiltDir from @quillmark/quiver/node.`);
+        if (url.startsWith('file://')) {
+            throw new QuiverError('transport_error', `Quiver.fromBuiltUrl requires an http(s):// or origin-relative URL; got "${url}". For local build output, use import { fromBuiltDir } from '@quillmark/quiver/node'.`);
         }
-        const { HttpTransport } = await import("./transports/http-transport.js");
-        const { loadBuiltQuiver } = await import("./built-loader.js");
+        const { HttpTransport } = await import('./transports/http-transport.js');
+        const { loadBuiltQuiver } = await import('./built-loader.js');
         const transport = new HttpTransport(url);
         return loadBuiltQuiver(transport);
     }
-    /**
-     * Browser-safe factory. Seeds the catalog from caller-provided manifest
-     * bytes — never fetches `latest.json` — then fetches bundles lazily and
-     * content-addressed, relative to `baseUrl`, like `fromBuiltUrl`. For SSR
-     * consumers that already hold the manifest at build time.
-     *
-     * Throws `quiver_invalid` on malformed manifest bytes, `transport_error`
-     * on a `file://` baseUrl or a later bundle fetch failure.
-     */
-    static async fromManifest(baseUrl, manifestBytes) {
-        if (baseUrl.startsWith("file://")) {
-            throw new QuiverError("transport_error", `Quiver.fromManifest requires an http(s):// or origin-relative baseUrl; got "${baseUrl}". For local build output, use Quiver.fromBuiltDir from @quillmark/quiver/node.`);
-        }
-        const { HttpTransport } = await import("./transports/http-transport.js");
-        const { seedBuiltQuiver } = await import("./built-loader.js");
-        const transport = new HttpTransport(baseUrl);
-        return seedBuiltQuiver(transport, manifestBytes);
-    }
     /** Returns all known quill names, sorted lexicographically. */
     quillNames() {
         return [...this.#catalog.keys()].sort();
@@ -104,11 +78,15 @@ export class Quiver {
      * Selector forms: `name`, `name@x`, `name@x.y`, `name@x.y.z`. Picks the
      * highest matching version in this quiver.
      *
+     * Sync, and in-memory by construction rather than by implementation: every
+     * loader materializes the catalog as the quiver is built, and `QuiverLoader`
+     * carries one verb, `loadTree`, which resolution never reaches.
+     *
      * Throws:
      *   - `invalid_ref` if ref fails parseQuillRef
      *   - `quill_not_found` if no version matches
      */
-    async resolve(ref) {
+    resolve(ref) {
         const parsed = parseQuillRef(ref);
         const versions = this.#catalog.get(parsed.name);
         if (versions && versions.length > 0) {
@@ -121,7 +99,7 @@ export class Quiver {
                 return `${parsed.name}@${winner}`;
             }
         }
-        throw new QuiverError("quill_not_found", `No quill found for ref "${ref}" in quiver "${this.name}".`, { ref, quiverName: this.name });
+        throw new QuiverError('quill_not_found', `No quill found for ref "${ref}" in quiver "${this.name}".`, { ref, quiverName: this.name });
     }
     /**
      * Returns a `Quill` for a ref (selector or canonical).
@@ -136,6 +114,11 @@ export class Quiver {
      * first. Materializes once and caches per canonical ref — concurrent calls
      * coalesce into a single load.
      *
+     * BORROWED, not handed over: the quill is the quiver's, shared with every
+     * other caller for the same ref, and lives as long as the quiver. Do not
+     * `free()` it: the next `getQuill` for that ref would hand out a freed
+     * handle. A caller wanting one of its own mints it from `.toTree()`.
+     *
      * Throws:
      *   - `invalid_ref` if ref is malformed
      *   - `quill_not_found` if ref does not match any version in this quiver
@@ -143,7 +126,7 @@ export class Quiver {
      *   - propagates validation errors from Quill.fromTree() unchanged
      */
     async getQuill(ref) {
-        const canonicalRef = await this.resolve(ref);
+        const canonicalRef = this.resolve(ref);
         let entry = this.#quillCache.get(canonicalRef);
         if (entry === undefined) {
             entry = this.#materializeQuill(canonicalRef).catch((err) => {
@@ -155,70 +138,20 @@ export class Quiver {
         return entry;
     }
     /**
-     * Internal: load tree (cached) + construct via Quill.fromTree. Errors
-     * propagate. On success the tree is evicted from `#treeCache` (the quill
-     * cache now holds the materialized result), so the tree is not retained
-     * past materialization. On `Quill.fromTree` failure the tree stays cached,
-     * so a retry skips the refetch.
-     */
-    async #materializeQuill(canonicalRef) {
-        const entry = this.#getTreeCached(canonicalRef);
-        const tree = await entry;
-        const quill = Quill.fromTree(tree);
-        // Evict by identity: only drop the entry if it is still the promise this
-        // materialization consumed (a concurrent refetch may have replaced it).
-        if (this.#treeCache.get(canonicalRef) === entry) {
-            this.#treeCache.delete(canonicalRef);
-        }
-        return quill;
-    }
-    /**
-     * Internal: tree cache reader. On miss, fetches via `#loadTree` and stores
-     * the in-flight Promise. On rejection, evicts so a retry can succeed.
-     */
-    #getTreeCached(canonicalRef) {
-        let entry = this.#treeCache.get(canonicalRef);
-        if (entry === undefined) {
-            const at = canonicalRef.indexOf("@");
-            const name = canonicalRef.slice(0, at);
-            const version = canonicalRef.slice(at + 1);
-            entry = this.#loadTree(name, version).catch((err) => {
-                this.#treeCache.delete(canonicalRef);
-                throw err;
-            });
-            this.#treeCache.set(canonicalRef, entry);
-        }
-        return entry;
-    }
-    /**
-     * Internal: validates name/version against the catalog, then delegates to
-     * the loader. Returns `Map<string, Uint8Array>` suitable for
-     * `Quill.fromTree(tree)`. Does NOT cache — caching lives in `#getTreeCached`.
+     * Internal: load the tree + construct via Quill.fromTree. Errors propagate.
      *
-     * Throws `transport_error` if name/version not in catalog or I/O fails.
-     */
-    async #loadTree(name, version) {
-        const versions = this.#catalog.get(name);
-        if (!versions || !versions.includes(version)) {
-            throw new QuiverError("transport_error", `Quill "${name}@${version}" not found in quiver "${this.name}"`, { quiverName: this.name, version, ref: `${name}@${version}` });
-        }
-        return this.#loader.loadTree(name, version);
-    }
-    /**
-     * Prefetches the tree for every quill version in this quiver. Fail-fast.
+     * The tree is held only for the length of this call: the quill cache holds the
+     * materialized result, and it is the one cache. A second tree cache beside it
+     * would buy a retry after a `Quill.fromTree` throw its refetch, which is a
+     * saved round-trip on the path where the quill is broken.
      *
-     * Network-bound only — does not materialize Quill instances and does not
-     * require an engine. Subsequent `getQuill` calls reuse the cached trees,
-     * skipping the fetch (the tree then evicts as its quill materializes).
-     * Rejects on the first fetch failure.
+     * Every caller arrives through `resolve` or the catalog itself, so the ref is
+     * catalog-backed by construction and the loader needs no gate.
      */
-    async warm() {
-        const promises = [];
-        for (const name of this.quillNames()) {
-            for (const version of this.versionsOf(name)) {
-                promises.push(this.#getTreeCached(`${name}@${version}`));
-            }
-        }
-        await Promise.all(promises);
+    async #materializeQuill(canonicalRef) {
+        const at = canonicalRef.indexOf('@');
+        const tree = await this.#loader.loadTree(canonicalRef.slice(0, at), canonicalRef.slice(at + 1));
+        return Quill.fromTree(tree);
     }
 }
+export { create as createQuiver };

package/dist/ref.d.ts

@@ -7,8 +7,8 @@ export interface ParsedQuillRef {
     selectorDepth?: 1 | 2 | 3;
 }
 /**
- * Throws QuiverError('invalid_ref') on malformed input.
- * Validates name charset: [A-Za-z0-9_-]+
- * Validates selector per §5 (x, x.y, x.y.z — digits only, no ranges/operators).
+ * Throws QuiverError('invalid_ref') on malformed input. The name is
+ * `[A-Za-z0-9_-]+`; the selector is `x`, `x.y` or `x.y.z`, digits only, with no
+ * ranges or operators — a quiver resolves a prefix, it does not solve a range.
  */
 export declare function parseQuillRef(ref: string): ParsedQuillRef;

package/dist/ref.js

@@ -1,25 +1,25 @@
-import { QuiverError } from "./errors.js";
+import { QuiverError } from './errors.js';
 const NAME_RE = /^[A-Za-z0-9_-]+$/;
 const SELECTOR_RE = /^\d+(\.\d+){0,2}$/;
 /**
- * Throws QuiverError('invalid_ref') on malformed input.
- * Validates name charset: [A-Za-z0-9_-]+
- * Validates selector per §5 (x, x.y, x.y.z — digits only, no ranges/operators).
+ * Throws QuiverError('invalid_ref') on malformed input. The name is
+ * `[A-Za-z0-9_-]+`; the selector is `x`, `x.y` or `x.y.z`, digits only, with no
+ * ranges or operators — a quiver resolves a prefix, it does not solve a range.
  */
 export function parseQuillRef(ref) {
     if (!ref) {
-        throw new QuiverError("invalid_ref", `Invalid ref: empty string`, { ref });
+        throw new QuiverError('invalid_ref', `Invalid ref: empty string`, { ref });
     }
-    const atIndex = ref.indexOf("@");
+    const atIndex = ref.indexOf('@');
     if (atIndex === 0) {
         // Starts with @, no name
-        throw new QuiverError("invalid_ref", `Invalid ref: missing name in "${ref}"`, { ref });
+        throw new QuiverError('invalid_ref', `Invalid ref: missing name in "${ref}"`, { ref });
     }
     if (atIndex === -1) {
         // No selector — just a name
         const name = ref;
         if (!NAME_RE.test(name)) {
-            throw new QuiverError("invalid_ref", `Invalid ref: name "${name}" contains invalid characters`, { ref });
+            throw new QuiverError('invalid_ref', `Invalid ref: name "${name}" contains invalid characters`, { ref });
         }
         return { name };
     }
@@ -27,18 +27,20 @@ export function parseQuillRef(ref) {
     const name = ref.slice(0, atIndex);
     const selector = ref.slice(atIndex + 1);
     if (!name) {
-        throw new QuiverError("invalid_ref", `Invalid ref: missing name in "${ref}"`, { ref });
+        throw new QuiverError('invalid_ref', `Invalid ref: missing name in "${ref}"`, { ref });
     }
     if (!selector) {
-        throw new QuiverError("invalid_ref", `Invalid ref: missing selector after "@" in "${ref}"`, { ref });
+        throw new QuiverError('invalid_ref', `Invalid ref: missing selector after "@" in "${ref}"`, {
+            ref
+        });
     }
     if (!NAME_RE.test(name)) {
-        throw new QuiverError("invalid_ref", `Invalid ref: name "${name}" contains invalid characters`, { ref });
+        throw new QuiverError('invalid_ref', `Invalid ref: name "${name}" contains invalid characters`, { ref });
     }
     if (!SELECTOR_RE.test(selector)) {
-        throw new QuiverError("invalid_ref", `Invalid ref: selector "${selector}" is not a valid semver selector (only x, x.y, x.y.z with digits allowed)`, { ref });
+        throw new QuiverError('invalid_ref', `Invalid ref: selector "${selector}" is not a valid semver selector (only x, x.y, x.y.z with digits allowed)`, { ref });
     }
-    const parts = selector.split(".");
+    const parts = selector.split('.');
     const depth = parts.length;
     return { name, selector, selectorDepth: depth };
 }