@quillmark/quiver 0.2.0 → 0.4.0

package/dist/quiver.js

@@ -2,14 +2,28 @@
  * Quiver — primary runtime abstraction for a collection of quills.
  *
  * Polymorphism via composition: internally stores a pluggable loader
- * (either source-backed or packed-backed).
+ * (either source-backed or build-output-backed).
  */
 import { QuiverError } from "./errors.js";
 import { assertNode } from "./assert-node.js";
+import { parseQuillRef } from "./ref.js";
+import { matchesSemverSelector, chooseHighestVersion } from "./semver.js";
 export class Quiver {
     name;
     #catalog;
     #loader;
+    /**
+     * Per-engine cache of materialized quills, keyed by canonical ref.
+     * WeakMap so engines can be GC'd; Promise values so concurrent
+     * getQuill calls coalesce into a single materialization.
+     */
+    #quillCache = new WeakMap();
+    /**
+     * Engine-independent cache of fetched trees, keyed by canonical ref.
+     * Populated by `warm()` and on first `getQuill` for a ref. Promise
+     * values so concurrent fetches coalesce.
+     */
+    #treeCache = new Map();
     /**
      * Private constructor — use static factory methods.
      * TS prevents external `new Quiver(...)` at compile time.
@@ -20,51 +34,73 @@ export class Quiver {
         this.#catalog = new Map(catalog);
         this.#loader = loader;
     }
-    /** @internal Used by loadPackedQuiver. Not part of the public API. */
+    /** @internal Used by loadBuiltQuiver. Not part of the public API. */
     static _fromLoader(name, catalog, loader) {
         return new Quiver(name, catalog, loader);
     }
     /**
-     * Node-only factory. Reads a Source Quiver from a directory containing
-     * `Quiver.yaml` and `quills/<name>/<version>/Quill.yaml` entries.
+     * Node-only factory. Resolves an npm specifier against `node_modules` and
+     * loads the source layout at the package root.
      *
-     * Uses dynamic import of `./source-loader.js` so that importing this module
-     * in a browser environment does not cause a crash at module evaluation time.
+     * The resolved package must have `Quiver.yaml` at its root.
      *
-     * Throws `quiver_invalid` on schema violations, `transport_error` on I/O failure.
+     * Throws `transport_error` on resolution/I/O failure, `quiver_invalid`
+     * on schema violations.
      */
-    static async fromSourceDir(path) {
-        assertNode("Quiver.fromSourceDir");
-        const { scanSourceQuiver, SourceLoader } = await import("./source-loader.js");
-        const { meta, catalog } = await scanSourceQuiver(path);
-        const loader = new SourceLoader(path);
-        return new Quiver(meta.name, catalog, loader);
+    static async fromPackage(specifier) {
+        assertNode("Quiver.fromPackage");
+        const { createRequire } = await import("node:module");
+        const { dirname } = await import("node:path");
+        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));
     }
     /**
-     * Node-only factory. Loads a Packed Quiver from a local directory.
+     * Node-only factory. Reads a Source Quiver from a local directory containing
+     * `Quiver.yaml` and `quills/<name>/<version>/Quill.yaml` entries.
      *
-     * Uses dynamic imports so this module stays browser-safe at evaluation time.
+     * Also accepts `import.meta.url`-style `file://` URLs as a convenience for
+     * tests; the URL's parent directory is used as the source root.
      *
-     * Throws `transport_error` on I/O failure, `quiver_invalid` on format errors.
+     * Throws `quiver_invalid` on schema violations, `transport_error` on I/O failure.
      */
-    static async fromPackedDir(path) {
-        assertNode("Quiver.fromPackedDir");
-        const { FsTransport } = await import("./transports/fs-transport.js");
-        const { loadPackedQuiver } = await import("./packed-loader.js");
-        const transport = new FsTransport(path);
-        return loadPackedQuiver(transport);
+    static async fromDir(pathOrFileUrl) {
+        assertNode("Quiver.fromDir");
+        let dir = pathOrFileUrl;
+        if (pathOrFileUrl.startsWith("file://")) {
+            const { fileURLToPath } = await import("node:url");
+            dir = fileURLToPath(new URL(".", pathOrFileUrl));
+        }
+        const { scanSourceQuiver, SourceLoader } = await import("./source-loader.js");
+        const { meta, catalog } = await scanSourceQuiver(dir);
+        const loader = new SourceLoader(dir);
+        return new Quiver(meta.name, catalog, loader);
     }
     /**
-     * Browser-safe factory. Loads a Packed Quiver from an HTTP base URL.
+     * 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 — local build output is
+     * not loadable in V1; serve over HTTP or use `fromPackage`/`fromDir`
+     * against the source.
      *
-     * Throws `transport_error` on network/HTTP failure, `quiver_invalid` on
-     * format errors.
+     * Throws `transport_error` on network/HTTP failure, `quiver_invalid`
+     * on format errors.
      */
-    static async fromHttp(url) {
+    static async fromBuilt(url) {
+        if (url.startsWith("file://")) {
+            throw new QuiverError("transport_error", `Quiver.fromBuilt requires an http(s):// or origin-relative URL; got "${url}". Local build output is not loadable in V1 — serve it over HTTP or load source via fromPackage/fromDir.`);
+        }
         const { HttpTransport } = await import("./transports/http-transport.js");
-        const { loadPackedQuiver } = await import("./packed-loader.js");
+        const { loadBuiltQuiver } = await import("./built-loader.js");
         const transport = new HttpTransport(url);
-        return loadPackedQuiver(transport);
+        return loadBuiltQuiver(transport);
     }
     /** Returns all known quill names, sorted lexicographically. */
     quillNames() {
@@ -78,24 +114,26 @@ export class Quiver {
         return [...(this.#catalog.get(name) ?? [])];
     }
     /**
-     * Node-only tooling. Writes a Packed Quiver artifact to outDir.
+     * Node-only tooling. Reads the Source Quiver at sourceDir, validates it,
+     * and writes the runtime build artifact to outDir.
      *
-     * Uses dynamic import of `./pack.js` so that this module stays browser-safe
-     * at evaluation time.
+     * Uses dynamic import of `./build.js` so that this module stays
+     * browser-safe at evaluation time.
      *
      * Throws `quiver_invalid` on source validation failures,
      * `transport_error` on I/O failures.
      */
-    static async pack(sourceDir, outDir, opts) {
-        assertNode("Quiver.pack");
-        const { packQuiver } = await import("./pack.js");
-        return packQuiver(sourceDir, outDir, opts);
+    static async build(sourceDir, outDir, opts) {
+        assertNode("Quiver.build");
+        const { buildQuiver } = await import("./build.js");
+        return buildQuiver(sourceDir, outDir, opts);
     }
     /**
      * Lazily loads the file tree for a specific quill version.
      *
      * Returns `Map<string, Uint8Array>` suitable for `engine.quill(tree)`.
-     * Does NOT cache the result — caching is the registry's concern.
+     * Does NOT cache the result — caching of materialized Quill instances
+     * happens in `getQuill`.
      *
      * Throws `transport_error` if name/version not in catalog or I/O fails.
      */
@@ -106,4 +144,110 @@ export class Quiver {
         }
         return this.#loader.loadTree(name, version);
     }
+    /**
+     * Resolves a selector ref → canonical ref (e.g. "memo" → "memo@1.1.0").
+     *
+     * Selector forms: `name`, `name@x`, `name@x.y`, `name@x.y.z`. Picks the
+     * highest matching version in this quiver.
+     *
+     * Throws:
+     *   - `invalid_ref` if ref fails parseQuillRef
+     *   - `quill_not_found` if no version matches
+     */
+    async resolve(ref) {
+        const parsed = parseQuillRef(ref);
+        const versions = this.#catalog.get(parsed.name);
+        if (versions && versions.length > 0) {
+            const candidates = parsed.selector === undefined
+                ? [...versions]
+                : versions.filter((v) => matchesSemverSelector(v, parsed.selector));
+            if (candidates.length > 0) {
+                // chooseHighestVersion returns null only for empty arrays; candidates is non-empty.
+                const winner = chooseHighestVersion(candidates);
+                return `${parsed.name}@${winner}`;
+            }
+        }
+        throw new QuiverError("quill_not_found", `No quill found for ref "${ref}" in quiver "${this.name}".`, { ref, quiverName: this.name });
+    }
+    /**
+     * Returns a render-ready `Quill` for a ref (selector or canonical).
+     *
+     * Selector refs (e.g. `"memo"`, `"memo@1"`) are resolved to canonical
+     * form first. Materializes via `engine.quill(tree)` on first call;
+     * caches per (engine, canonical-ref). Reuses a tree cached by `warm()`
+     * (or a previous `getQuill`) so the network fetch isn't paid twice.
+     * Concurrent calls for the same ref coalesce into a single load.
+     *
+     * Throws:
+     *   - `invalid_ref` if ref is malformed
+     *   - `quill_not_found` if ref does not match any version in this quiver
+     *   - propagates I/O errors from loadTree unchanged
+     *   - propagates engine errors from engine.quill() unchanged
+     */
+    async getQuill(ref, opts) {
+        const canonicalRef = await this.resolve(ref);
+        const engine = opts.engine;
+        let perEngine = this.#quillCache.get(engine);
+        if (perEngine === undefined) {
+            perEngine = new Map();
+            this.#quillCache.set(engine, perEngine);
+        }
+        let entry = perEngine.get(canonicalRef);
+        if (entry === undefined) {
+            entry = this.#materializeQuill(canonicalRef, engine).catch((err) => {
+                perEngine.delete(canonicalRef);
+                throw err;
+            });
+            perEngine.set(canonicalRef, entry);
+        }
+        return entry;
+    }
+    /**
+     * Internal: load tree (cached) + invoke engine.quill. Errors propagate.
+     *
+     * On success, evicts the tree from the cache so its bytes can be GC'd —
+     * the materialized Quill is the runtime artifact; the tree is dead weight
+     * once a Quill exists. On failure, the tree is retained so retries skip
+     * the network.
+     */
+    async #materializeQuill(canonicalRef, engine) {
+        const tree = await this.#getTreeCached(canonicalRef);
+        const quill = engine.quill(tree);
+        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.
+     */
+    async #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;
+    }
+    /**
+     * 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. Rejects on the first fetch failure.
+     */
+    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);
+    }
 }

package/dist/source-loader.d.ts

@@ -2,7 +2,7 @@
  * Internal filesystem scanner for Source Quiver layout.
  *
  * Uses Node.js `fs/promises` — this module must only be imported from
- * Node-only contexts (fromSourceDir, etc.).
+ * Node-only contexts (fromDir, fromPackage, etc.).
  */
 import type { QuiverMeta } from "./quiver-yaml.js";
 import type { QuiverLoader } from "./quiver.js";

package/dist/source-loader.js

@@ -2,7 +2,7 @@
  * Internal filesystem scanner for Source Quiver layout.
  *
  * Uses Node.js `fs/promises` — this module must only be imported from
- * Node-only contexts (fromSourceDir, etc.).
+ * Node-only contexts (fromDir, fromPackage, etc.).
  */
 import { readdir, readFile, stat } from "node:fs/promises";
 import { join, relative, sep } from "node:path";

package/dist/testing.d.ts

@@ -1,5 +1,9 @@
 /**
- * Plug-and-play test suite for Quiver authors.
+ * Convenience test harness for Quiver authors using `node:test`.
+ *
+ * Built into Node 18+; no extra test-runner dependency required. If you
+ * prefer vitest, jest, or another runner, write a 12-line loop against
+ * the main API instead — every primitive used here is public.
  *
  * Usage (place this file next to your Quiver.yaml):
  *
@@ -8,32 +12,17 @@
  *   const engine = await Quillmark.load();
  *   runQuiverTests(import.meta.url, engine);
  *
- * Requires vitest in your devDependencies.
- */
-import type { QuillmarkLike, QuillLike } from "./engine-types.js";
-export type { QuillmarkLike, QuillLike };
-/**
- * Returns a lightweight mock engine and a record of every tree passed to it.
- * Useful for writing custom test helpers; not intended as a substitute for the
- * real engine in runQuiverTests (the mock performs no template compilation).
+ * Run with `node --test`.
  */
-export declare function makeMockEngine(): {
-    calls: Array<Map<string, Uint8Array>>;
-    engine: QuillmarkLike;
-};
+import type { QuillmarkLike } from "./engine-types.js";
 /**
- * Registers a Vitest describe block that validates every quill version in the
- * quiver at `sourceDirOrMetaUrl` against the provided Quillmark engine.
- *
- * Pass `import.meta.url` when your test file lives at the quiver root (next to
- * Quiver.yaml). Pass an absolute directory path for any other layout.
+ * Registers a `node:test` describe block that validates every quill
+ * version in the quiver at `metaUrlOrDir` against the provided engine.
  *
- * Each (quill, version) pair gets its own `it()` so failures are reported
- * individually. The quiver and engine are initialised once in `beforeAll`.
+ * Pass `import.meta.url` when this file lives at the quiver root (next
+ * to Quiver.yaml). Pass an absolute directory path for any other layout.
  *
- * Validation covers the full loading pipeline: Quiver.yaml, Quill.yaml, all
- * template files, and engine compilation via engine.quill(tree). A quill that
- * contains a template error will cause its test to fail with the engine's own
- * error message.
+ * Validation covers the full loading pipeline: Quiver.yaml, Quill.yaml,
+ * all template files, and engine compilation via engine.quill(tree).
  */
-export declare function runQuiverTests(sourceDirOrMetaUrl: string, engine: QuillmarkLike): void;
+export declare function runQuiverTests(metaUrlOrDir: string, engine: QuillmarkLike): void;

package/dist/testing.js

@@ -1,5 +1,9 @@
 /**
- * Plug-and-play test suite for Quiver authors.
+ * Convenience test harness for Quiver authors using `node:test`.
+ *
+ * Built into Node 18+; no extra test-runner dependency required. If you
+ * prefer vitest, jest, or another runner, write a 12-line loop against
+ * the main API instead — every primitive used here is public.
  *
  * Usage (place this file next to your Quiver.yaml):
  *
@@ -8,101 +12,40 @@
  *   const engine = await Quillmark.load();
  *   runQuiverTests(import.meta.url, engine);
  *
- * Requires vitest in your devDependencies.
+ * Run with `node --test`.
  */
-import { describe, it, expect, beforeAll } from "vitest";
-import { readdirSync } from "node:fs";
-import { join, basename } from "node:path";
-import { fileURLToPath } from "node:url";
+import { describe, it, before } from "node:test";
 import { Quiver } from "./quiver.js";
-import { QuiverRegistry } from "./registry.js";
-/**
- * Returns a lightweight mock engine and a record of every tree passed to it.
- * Useful for writing custom test helpers; not intended as a substitute for the
- * real engine in runQuiverTests (the mock performs no template compilation).
- */
-export function makeMockEngine() {
-    const calls = [];
-    const engine = {
-        quill(tree) {
-            calls.push(tree);
-            return { render: () => ({ ok: true }) };
-        },
-    };
-    return { calls, engine };
-}
-function resolveSourceDir(sourceDirOrMetaUrl) {
-    if (sourceDirOrMetaUrl.startsWith("file://")) {
-        return fileURLToPath(new URL(".", sourceDirOrMetaUrl));
-    }
-    return sourceDirOrMetaUrl;
-}
-function discoverQuills(sourceDir) {
-    const quillsDir = join(sourceDir, "quills");
-    const results = [];
-    let nameDirs;
-    try {
-        nameDirs = readdirSync(quillsDir, { withFileTypes: true });
-    }
-    catch {
-        return results;
-    }
-    for (const nameEntry of nameDirs) {
-        if (!nameEntry.isDirectory() || nameEntry.name.startsWith("."))
-            continue;
-        let versionDirs;
-        try {
-            versionDirs = readdirSync(join(quillsDir, nameEntry.name), {
-                withFileTypes: true,
-            });
-        }
-        catch {
-            continue;
-        }
-        for (const versionEntry of versionDirs) {
-            if (!versionEntry.isDirectory() || versionEntry.name.startsWith("."))
-                continue;
-            results.push({ name: nameEntry.name, version: versionEntry.name });
-        }
-    }
-    return results;
-}
 /**
- * Registers a Vitest describe block that validates every quill version in the
- * quiver at `sourceDirOrMetaUrl` against the provided Quillmark engine.
+ * Registers a `node:test` describe block that validates every quill
+ * version in the quiver at `metaUrlOrDir` against the provided engine.
  *
- * Pass `import.meta.url` when your test file lives at the quiver root (next to
- * Quiver.yaml). Pass an absolute directory path for any other layout.
+ * Pass `import.meta.url` when this file lives at the quiver root (next
+ * to Quiver.yaml). Pass an absolute directory path for any other layout.
  *
- * Each (quill, version) pair gets its own `it()` so failures are reported
- * individually. The quiver and engine are initialised once in `beforeAll`.
- *
- * Validation covers the full loading pipeline: Quiver.yaml, Quill.yaml, all
- * template files, and engine compilation via engine.quill(tree). A quill that
- * contains a template error will cause its test to fail with the engine's own
- * error message.
+ * Validation covers the full loading pipeline: Quiver.yaml, Quill.yaml,
+ * all template files, and engine compilation via engine.quill(tree).
  */
-export function runQuiverTests(sourceDirOrMetaUrl, engine) {
-    const sourceDir = resolveSourceDir(sourceDirOrMetaUrl);
-    // Enumerate quills synchronously so Vitest can collect test cases before
-    // any async work begins. Errors here (missing quills/ dir, unreadable dirs)
-    // surface as the "has at least one quill" test failing rather than a
-    // collection-time crash.
-    const quills = discoverQuills(sourceDir);
-    describe(`Quiver: ${basename(sourceDir)}`, () => {
-        let registry;
-        beforeAll(async () => {
-            const quiver = await Quiver.fromSourceDir(sourceDir);
-            registry = new QuiverRegistry({ engine, quivers: [quiver] });
+export function runQuiverTests(metaUrlOrDir, engine) {
+    describe("Quiver", () => {
+        let quiver;
+        before(async () => {
+            quiver = await Quiver.fromDir(metaUrlOrDir);
         });
         it("has at least one quill", () => {
-            expect(quills).not.toHaveLength(0);
+            if (quiver.quillNames().length === 0) {
+                throw new Error("Quiver has no quills");
+            }
+        });
+        it("compiles every quill version without error", async () => {
+            for (const name of quiver.quillNames()) {
+                for (const version of quiver.versionsOf(name)) {
+                    const quill = await quiver.getQuill(`${name}@${version}`, { engine });
+                    if (typeof quill.render !== "function") {
+                        throw new Error(`${name}@${version}: engine returned non-conforming Quill`);
+                    }
+                }
+            }
         });
-        for (const { name, version } of quills) {
-            it(`${name}@${version} compiles without error`, async () => {
-                const quill = await registry.getQuill(`${name}@${version}`);
-                expect(typeof quill.render).toBe("function");
-            });
-        }
     });
 }

package/dist/transports/http-transport.d.ts

@@ -1,11 +1,11 @@
 /**
- * HttpTransport — browser-safe packed quiver transport that fetches via HTTP.
+ * HttpTransport — browser-safe built-quiver transport that fetches via HTTP.
  * Internal; not exported from index.ts.
  *
  * Uses globalThis.fetch — no node: imports at any level.
  */
-import type { PackedTransport } from "../packed-loader.js";
-export declare class HttpTransport implements PackedTransport {
+import type { BuiltTransport } from "../built-loader.js";
+export declare class HttpTransport implements BuiltTransport {
     private readonly baseUrl;
     constructor(baseUrl: string);
     fetchBytes(relativePath: string): Promise<Uint8Array>;

package/dist/transports/http-transport.js

@@ -1,5 +1,5 @@
 /**
- * HttpTransport — browser-safe packed quiver transport that fetches via HTTP.
+ * HttpTransport — browser-safe built-quiver transport that fetches via HTTP.
  * Internal; not exported from index.ts.
  *
  * Uses globalThis.fetch — no node: imports at any level.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@quillmark/quiver",
-  "version": "0.2.0",
-  "description": "Quiver registry and packaging for Quillmark",
+  "version": "0.4.0",
+  "description": "Quiver registry and build tooling for Quillmark",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -42,20 +42,14 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@quillmark/wasm": ">=0.59.0-rc.2",
-    "vitest": ">=4.0.0"
-  },
-  "peerDependenciesMeta": {
-    "vitest": {
-      "optional": true
-    }
+    "@quillmark/wasm": ">=0.59.0"
   },
   "dependencies": {
     "fflate": "^0.8.2",
     "yaml": "^2.8.3"
   },
   "devDependencies": {
-    "@quillmark/wasm": "0.59.0-rc.2",
+    "@quillmark/wasm": "0.59.0",
     "@types/node": "^25.3.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"

package/dist/pack.d.ts

@@ -1,25 +0,0 @@
-/**
- * Pack logic — internal, Node-only.
- *
- * All Node.js built-in imports are done dynamically inside `packQuiver` so
- * that a type-only import of `PackOptions` from `src/index.ts` does NOT
- * pull `node:fs` or `node:crypto` into browser bundles.
- */
-/** Reserved for future pack options (e.g. compression level, filters). */
-export type PackOptions = Record<string, never>;
-/**
- * Reads a Source Quiver, validates it, and writes a Packed Quiver to outDir.
- *
- * Output layout:
- *   outDir/
- *     Quiver.json                   # stable pointer
- *     manifest.<md5prefix6>.json    # hashed manifest
- *     <name>@<version>.<md5>.zip    # one bundle per quill
- *     store/
- *       <md5>                       # dehydrated font bytes (full hash, no ext)
- *
- * Throws:
- *   - `quiver_invalid` on source validation failures (propagated from scanner)
- *   - `transport_error` on I/O failures
- */
-export declare function packQuiver(sourceDir: string, outDir: string, _opts?: PackOptions): Promise<void>;

package/dist/registry.d.ts

@@ -1,39 +0,0 @@
-import type { QuillmarkLike, QuillLike } from "./engine-types.js";
-import type { Quiver } from "./quiver.js";
-export declare class QuiverRegistry {
-    #private;
-    constructor(args: {
-        engine: QuillmarkLike;
-        quivers: Quiver[];
-    });
-    /**
-     * Resolves a selector ref → canonical ref (e.g. "memo" → "memo@1.1.0").
-     *
-     * Applies multi-quiver precedence (§4): scan quivers in order, first quiver
-     * with any matching candidate wins, highest match within that quiver returned.
-     *
-     * Throws:
-     *   - `invalid_ref` if ref fails parseQuillRef
-     *   - `quill_not_found` if no quiver has a matching candidate
-     */
-    resolve(ref: string): Promise<string>;
-    /**
-     * Returns a render-ready QuillLike instance for a canonical ref.
-     * Materializes via engine.quill(tree) on first call; caches by canonical ref.
-     *
-     * Throws:
-     *   - `invalid_ref` if canonicalRef is not valid canonical x.y.z form
-     *   - `quill_not_found` if canonical ref doesn't map to a loaded quiver
-     *   - propagates I/O errors from loadTree unchanged
-     *   - propagates engine errors from engine.quill() unchanged (not wrapped)
-     */
-    getQuill(canonicalRef: string): Promise<QuillLike>;
-    /**
-     * Warms all quill refs across all composed quivers. Fail-fast.
-     *
-     * Calls loadTree + engine.quill(tree) for every known quill version in
-     * parallel. Already-cached refs resolve instantly (idempotent). Rejects on
-     * the first failure (Promise.all fail-fast semantics).
-     */
-    warm(): Promise<void>;
-}