@quillmark/quiver 0.26.0 → 0.28.0

package/README.md

@@ -47,7 +47,7 @@ const result = await engine.render(quill, doc, { format: 'pdf' });
 
 That quill is **borrowed, not owned**: every caller asking for that ref gets the same instance, so `free()` on it hands the next caller a freed handle. Code that owns its quill mints one from `(await quiver.getQuill(ref)).toTree()` and frees that.
 
-This package produces quills; `@quillmark/wasm` renders them. A quill from `getQuill` is engine-free portable data — schema inspection, validation, blueprint access, `seedDocument()` — and passes straight to `engine.render(quill, doc)`, which routes on `quill.backendId`, loads that backend, clones both handles into its memory, renders, and frees the clones. There is no boundary-crossing step to perform. `Engine.render`, `open`, `supportedFormats` and `supportsCanvas` are **async**. The canonical `Quill` / `Document` / `Engine` types are not re-exported here; import them from the `@quillmark/wasm` peer, their single source of truth.
+This package produces quills; `@quillmark/wasm` renders them. A quill from `getQuill` is engine-free portable data — schema inspection, validation, blueprint access, `seedDocument()` — and passes straight to `engine.render(quill, doc)`, which routes on `quill.backendId`, loads that backend, clones both handles into its memory, renders, and frees the clones. There is no boundary-crossing step to perform. `Engine.render`, `open` and `supportedFormats` are **async**. The canonical `Quill` / `Document` / `Engine` types are not re-exported here; import them from the `@quillmark/wasm` peer, their single source of truth.
 
 One narrower verb sits beside `getQuill`: `resolve(ref)` returns the canonical ref without materializing anything, and is **sync** (the catalog is in memory from the moment the quiver is built).
 
@@ -124,7 +124,7 @@ The seed answers first and the URL serves what it does not carry. Seeding `lates
 
 ## The `latest.json` pointer
 
-`Quiver.fromBuiltUrl(url)` first fetches `<url>/latest.json`, a stable-named pointer to the current manifest. Everything behind that pointer is content-addressed and checked against the digest in its name; the pointer itself is not, so a cache layer can serve a stale one and silently pin the client to the old catalog. It is therefore the one request fetched `no-cache` (revalidate with the origin; a 304 still serves from disk), which closes the browser-cache layer. A stale CDN edge is answered by that host's cache headers.
+`Quiver.fromBuiltUrl(url)` first fetches `<url>/latest.json`, a stable-named pointer to the current manifest. Everything behind that pointer is content-addressed and checked against the digest in its name; the pointer itself is not, so a cache layer can serve a stale one and silently pin the client to the old catalog. It is therefore the one request fetched `no-cache` (revalidate with the origin; a 304 still serves from disk), and every other request is `force-cache`, a digest-carrying name being entitled to whatever the cache already holds. Both are the browser layer only: a stale CDN edge is answered by that host's cache headers, and `quillkit`'s README states the whole contract for a deploy serving a client over one.
 
 The check itself needs `crypto.subtle`, which a browser exposes only in a secure context. An `https` page, `http://localhost` and Node have one; a page served over plain `http` to anything else — a dev host on a LAN address, a staging box without a certificate — has none, and there every fetch passes through unchecked.
 

package/dist/build.js

@@ -76,16 +76,19 @@ function assertSafeOutDir(path, sourceDir, outDir) {
  */
 export async function buildQuiver(sourceDir, outDir, options = {}) {
     // Dynamic imports keep this module safe to type-import from browser contexts.
-    const path = await import('node:path');
-    const { dirname, join, resolve } = path;
+    const nodePath = await import('node:path');
+    const { dirname, join, resolve } = nodePath;
     const { mkdir, rename, rm, writeFile } = await import('node:fs/promises');
     const { existsSync } = await import('node:fs');
     const { createHash } = await import('node:crypto');
     const { scanSourceQuiver, readQuillTree } = await import('./source-loader.js');
-    assertSafeOutDir(path, sourceDir, outDir);
+    assertSafeOutDir(nodePath, sourceDir, outDir);
     const out = resolve(outDir);
     const { stage, prev } = stagesOf(out);
     const { meta, catalog } = await scanSourceQuiver(sourceDir);
+    // True where the swap stepped the outgoing generation aside and could not put it
+    // back: `prev` then holds the only copy, and the sweep below would take it.
+    let prevHoldsLastGood = false;
     try {
         await packGeneration();
     }
@@ -94,7 +97,8 @@ export async function buildQuiver(sourceDir, outDir, options = {}) {
         // untouched. Neither tree outlives the call either way. Swept rather than
         // checked: a sweep that threw would answer for the build, and what a caller
         // needs to hear is why the build failed.
-        for (const at of [stage, prev])
+        const sweep = prevHoldsLastGood ? [stage] : [stage, prev];
+        for (const at of sweep)
             await rm(at, { recursive: true, force: true }).catch(() => { });
     }
     /**
@@ -113,38 +117,35 @@ export async function buildQuiver(sourceDir, outDir, options = {}) {
             throw new QuiverError('transport_error', `Failed to prepare output directory "${outDir}": ${err.message}`, { cause: err });
         }
         const manifestQuills = [];
+        // Font hashes already in the store. The store is content-addressed, so a font
+        // shared across quills or versions is written once.
+        const stored = new Set();
         for (const [quillName, versions] of catalog) {
             for (const version of versions) {
                 if (!options.drafts && isDraft(version))
                     continue;
                 const quillDir = join(sourceDir, 'quills', quillName, version);
                 const tree = await readQuillTree(quillDir);
-                const fontEntries = [];
-                const contentEntries = [];
-                for (const [path, bytes] of tree) {
-                    if (FONT_EXT.test(path)) {
-                        fontEntries.push([path, bytes]);
-                    }
-                    else {
-                        contentEntries.push([path, bytes]);
-                    }
-                }
                 const fonts = {};
-                for (const [path, bytes] of fontEntries) {
+                const contentRecord = {};
+                for (const [rel, bytes] of tree) {
+                    if (!FONT_EXT.test(rel)) {
+                        contentRecord[rel] = bytes;
+                        continue;
+                    }
                     // Full width: the store is keyed by hash, so two distinct fonts
                     // sharing a prefix would merge into one entry.
                     const hash = createHash('sha256').update(bytes).digest('hex');
+                    fonts[rel] = hash;
+                    if (stored.has(hash))
+                        continue;
                     try {
                         await writeFile(join(stage, 'store', hash), bytes);
                     }
                     catch (err) {
                         throw new QuiverError('transport_error', `Failed to write font store entry "${join(outDir, 'store', hash)}": ${err.message}`, { cause: err });
                     }
-                    fonts[path] = hash;
-                }
-                const contentRecord = {};
-                for (const [path, bytes] of contentEntries) {
-                    contentRecord[path] = bytes;
+                    stored.add(hash);
                 }
                 // The budget `bundle.ts` carries is spent here as well as at the read, so
                 // a quill no loader would take is refused by the build that packs it,
@@ -199,15 +200,27 @@ export async function buildQuiver(sourceDir, outDir, options = {}) {
         }
         // `prev` is cleared first: a rename onto a non-empty directory fails, and the
         // tree left by an interrupted run is one.
+        //
+        // Between them the outgoing generation is only at `prev`, so a second rename that
+        // throws — EXDEV across a mount, EBUSY on a tree a reader holds, ENOSPC — puts it
+        // back, and where the put-back fails leaves it there for the sweep to spare.
+        let steppedAside = false;
         try {
             await mkdir(dirname(out), { recursive: true });
             await rm(prev, { recursive: true, force: true });
-            if (existsSync(out))
+            if (existsSync(out)) {
                 await rename(out, prev);
+                steppedAside = true;
+            }
             await rename(stage, out);
         }
         catch (err) {
-            throw new QuiverError('transport_error', `Failed to move the build into "${outDir}": ${err.message}`, { cause: err });
+            if (steppedAside)
+                prevHoldsLastGood = !(await rename(prev, out).then(() => true, () => false));
+            throw new QuiverError('transport_error', `Failed to move the build into "${outDir}": ${err.message}` +
+                (prevHoldsLastGood
+                    ? `. The previous generation is at "${prev}" and has to be moved back by hand`
+                    : ''), { cause: err });
         }
     }
 }

package/dist/built-loader.d.ts

@@ -12,14 +12,21 @@ import type { Quiver } from './quiver.js';
  * (Node).
  */
 export interface BuiltTransport {
-    fetchBytes(relativePath: string, opts?: FetchOptions): Promise<Uint8Array>;
+    fetchBytes(relativePath: string, opts: FetchOptions): Promise<Uint8Array>;
 }
 /**
  * `revalidate` marks the one request that must not be answered from a cache:
  * `latest.json`, the only name in the artifact that is not content-addressed.
- * Everything else is safe to cache forever by construction.
+ * Everything else is safe to cache forever by construction, and a transport over a
+ * cache says so itself rather than leaving the fact to a host's headers.
+ *
+ * `maxBytes` is what the response may weigh, required because only the caller knows what
+ * it asked for: a pointer, a bundle and a font carry their own ceilings. A transport
+ * holding a stream refuses past it before the bytes are resident; one over a file or a
+ * held map ignores it.
  */
 export interface FetchOptions {
+    maxBytes: number;
     revalidate?: boolean;
 }
 /** Load a build-output quiver via the given transport. */

package/dist/built-loader.js

@@ -6,25 +6,36 @@
  * Package-internal, and browser-safe: no static `node:` imports at any level.
  */
 import { QuiverError } from './errors.js';
-import { unpackFiles } from './bundle.js';
+import { MAX_BUNDLE_BYTES, unpackFiles } from './bundle.js';
 import { isQuillName } from './ref.js';
 import { isCanonicalSemver, compareSemver } from './semver.js';
 import { NAME_DIGEST_LENGTH, sha256Hex } from './digest.js';
 import { MANIFEST_VERSION, POINTER_FORMAT } from './format.js';
 import { createQuiver } from './quiver.js';
 /**
- * Fetch, then check the bytes against the digest their name carries. That
- * check is what makes "content-addressed, safe to cache forever" a property
- * rather than a hope: it catches a corrupted CDN object, a partial sync, and a
- * name reused across releases. A mismatch is a transport failure (the bytes
- * that arrived are not the bytes asked for), so the caches that evict on error
- * let a retry succeed.
+ * The ceiling per path. A bundle's is the unpack budget itself (`bundle.ts`). The other
+ * two are their own: a font is a store entry rather than a bundle entry, and the pointer
+ * and the manifest are the small documents a catalog is read out of — the pointer being
+ * the one response in the artifact with no digest behind it.
+ */
+const MAX_DOCUMENT_BYTES = 8 * 1024 * 1024;
+const MAX_FONT_BYTES = 32 * 1024 * 1024;
+/**
+ * Fetch under `maxBytes`, then check the bytes against the digest their name
+ * carries. That check is what makes "content-addressed, safe to cache forever"
+ * a property rather than a hope: it catches a corrupted CDN object, a partial
+ * sync, and a name reused across releases. A mismatch is a transport failure
+ * (the bytes that arrived are not the bytes asked for), so the caches that
+ * evict on error let a retry succeed.
+ *
+ * The ceiling is the transport's to hold, because a digest is a verdict on
+ * bytes that have all arrived.
  *
  * Where no digest primitive exists (a page served over plain http, which is
  * not a secure context) the fetch passes through unchecked.
  */
-async function fetchVerified(transport, path, expected) {
-    const bytes = await transport.fetchBytes(path);
+async function fetchVerified(transport, path, expected, maxBytes) {
+    const bytes = await transport.fetchBytes(path, { maxBytes });
     const actual = await sha256Hex(bytes);
     if (actual !== undefined && !actual.startsWith(expected)) {
         throw new QuiverError('transport_error', `Digest mismatch for "${path}": the bytes hash to ${actual.slice(0, expected.length)}, not ${expected}`);
@@ -71,7 +82,7 @@ class BuiltLoader {
         // The catalog the outer Quiver resolves against derives from this index,
         // so every ref reaching here has an entry.
         const entry = this.index.get(`${name}@${version}`);
-        const zipBytes = await fetchVerified(this.transport, entry.bundle, digestOfName(BUNDLE_FILENAME_RE, entry.bundle, 'bundle filename'));
+        const zipBytes = await fetchVerified(this.transport, entry.bundle, digestOfName(BUNDLE_FILENAME_RE, entry.bundle, 'bundle filename'), MAX_BUNDLE_BYTES);
         const files = unpackFiles(zipBytes);
         const fontEntries = Object.entries(entry.fonts);
         await Promise.all(fontEntries.map(async ([path, hash]) => {
@@ -87,7 +98,7 @@ class BuiltLoader {
     fetchFont(hash) {
         let promise = this.fontCache.get(hash);
         if (!promise) {
-            promise = fetchVerified(this.transport, `store/${hash}`, hash).catch((err) => {
+            promise = fetchVerified(this.transport, `store/${hash}`, hash, MAX_FONT_BYTES).catch((err) => {
                 this.fontCache.delete(hash);
                 throw err;
             });
@@ -128,10 +139,11 @@ function parsePointer(raw) {
         throw new QuiverError('quiver_invalid', `This quiver is built in format ${format} and this loader reads ${POINTER_FORMAT}. ` +
             `Upgrade @quillmark/quiver, or for a served client the client itself, which carries the copy that reads this.`);
     }
-    if (typeof obj['manifest'] !== 'string' || obj['manifest'].length === 0) {
+    const manifest = obj['manifest'];
+    if (typeof manifest !== 'string' || manifest.length === 0) {
         throw new QuiverError('quiver_invalid', 'latest.json must have a non-empty string "manifest" field');
     }
-    return obj['manifest'];
+    return manifest;
 }
 function parseManifest(raw) {
     let parsed;
@@ -154,58 +166,57 @@ function parseManifest(raw) {
         throw new QuiverError('quiver_invalid', `This quiver's manifest is version ${version} and this loader reads ${MANIFEST_VERSION}. ` +
             `Upgrade @quillmark/quiver, or for a served client the client itself, which carries the copy that reads this.`);
     }
-    if (typeof obj['name'] !== 'string' || obj['name'].length === 0) {
+    const name = obj['name'];
+    if (typeof name !== 'string' || name.length === 0) {
         throw new QuiverError('quiver_invalid', 'Manifest must have a non-empty string "name" field');
     }
-    if (obj['description'] !== undefined && typeof obj['description'] !== 'string') {
-        throw new QuiverError('quiver_invalid', `Manifest "description" must be a string if present, got ${typeof obj['description']}`);
+    const description = obj['description'];
+    if (description !== undefined && typeof description !== 'string') {
+        throw new QuiverError('quiver_invalid', `Manifest "description" must be a string if present, got ${typeof description}`);
     }
-    if (!Array.isArray(obj['quills'])) {
+    const entries = obj['quills'];
+    if (!Array.isArray(entries)) {
         throw new QuiverError('quiver_invalid', 'Manifest must have a "quills" array');
     }
     const quills = [];
-    for (let i = 0; i < obj['quills'].length; i++) {
-        const entry = obj['quills'][i];
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
         if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
             throw new QuiverError('quiver_invalid', `manifest.quills[${i}] must be an object`);
         }
         const e = entry;
         assertNoUnknownKeys(e, ['name', 'version', 'bundle', 'fonts'], `manifest.quills[${i}]`);
-        if (typeof e['name'] !== 'string' || e['name'].length === 0) {
+        const quillName = e['name'];
+        if (typeof quillName !== 'string' || quillName.length === 0) {
             throw new QuiverError('quiver_invalid', `manifest.quills[${i}].name must be a non-empty string`);
         }
-        if (!isQuillName(e['name'])) {
-            throw new QuiverError('quiver_invalid', `manifest.quills[${i}].name "${e['name']}" is not a name a ref can spell — only [A-Za-z0-9_-] are allowed`);
+        if (!isQuillName(quillName)) {
+            throw new QuiverError('quiver_invalid', `manifest.quills[${i}].name "${quillName}" is not a name a ref can spell — only [A-Za-z0-9_-] are allowed`);
         }
-        if (typeof e['version'] !== 'string' || !isCanonicalSemver(e['version'])) {
-            throw new QuiverError('quiver_invalid', `manifest.quills[${i}].version must be canonical semver (x.y.z), got "${String(e['version'])}"`);
+        const version = e['version'];
+        if (typeof version !== 'string' || !isCanonicalSemver(version)) {
+            throw new QuiverError('quiver_invalid', `manifest.quills[${i}].version must be canonical semver (x.y.z), got "${String(version)}"`);
         }
-        if (typeof e['bundle'] !== 'string' || e['bundle'].length === 0) {
+        const bundle = e['bundle'];
+        if (typeof bundle !== 'string' || bundle.length === 0) {
             throw new QuiverError('quiver_invalid', `manifest.quills[${i}].bundle must be a non-empty string`);
         }
-        digestOfName(BUNDLE_FILENAME_RE, e['bundle'], `manifest.quills[${i}].bundle filename`);
-        if (typeof e['fonts'] !== 'object' || e['fonts'] === null || Array.isArray(e['fonts'])) {
+        digestOfName(BUNDLE_FILENAME_RE, bundle, `manifest.quills[${i}].bundle filename`);
+        const declared = e['fonts'];
+        if (typeof declared !== 'object' || declared === null || Array.isArray(declared)) {
             throw new QuiverError('quiver_invalid', `manifest.quills[${i}].fonts must be an object`);
         }
-        const fonts = e['fonts'];
-        for (const [k, v] of Object.entries(fonts)) {
+        const fonts = {};
+        for (const [k, v] of Object.entries(declared)) {
             if (typeof v !== 'string') {
                 throw new QuiverError('quiver_invalid', `manifest.quills[${i}].fonts["${k}"] must be a string`);
             }
             validateFontHash(v, `manifest.quills[${i}].fonts["${k}"]`);
+            fonts[k] = v;
         }
-        quills.push({
-            name: e['name'],
-            version: e['version'],
-            bundle: e['bundle'],
-            fonts: fonts
-        });
+        quills.push({ name: quillName, version, bundle, fonts });
     }
-    return {
-        name: obj['name'],
-        description: obj['description'],
-        quills
-    };
+    return { name, description, quills };
 }
 // ─── Catalog assembly ─────────────────────────────────────────────────────────
 /**
@@ -232,7 +243,10 @@ export async function loadBuiltQuiver(transport) {
     // one fetch that must revalidate.
     let pointerBytes;
     try {
-        pointerBytes = await transport.fetchBytes('latest.json', { revalidate: true });
+        pointerBytes = await transport.fetchBytes('latest.json', {
+            revalidate: true,
+            maxBytes: MAX_DOCUMENT_BYTES
+        });
     }
     catch (err) {
         if (err instanceof QuiverError)
@@ -243,7 +257,7 @@ export async function loadBuiltQuiver(transport) {
     const manifestDigest = digestOfName(MANIFEST_FILENAME_RE, manifestFileName, 'Pointer manifest filename');
     let manifestBytes;
     try {
-        manifestBytes = await fetchVerified(transport, manifestFileName, manifestDigest);
+        manifestBytes = await fetchVerified(transport, manifestFileName, manifestDigest, MAX_DOCUMENT_BYTES);
     }
     catch (err) {
         if (err instanceof QuiverError)

package/dist/bundle.d.ts

@@ -1,6 +1,22 @@
 /**
  * Zip utilities — browser-safe (uses fflate only).
  */
+/**
+ * What a bundle may hold. Deflate tops out near 1032:1, so a megabyte of zip is a
+ * gigabyte resident and the bundle is what a reader inflates to find that out.
+ *
+ * The ceiling is a constant rather than something a consumer raises, because a quiver
+ * is a dependency pinned like any other (README, "What a quiver is trusted to be") and
+ * what a budget bounds there is a build that packed something enormous. Both ends spend
+ * it, so an artifact no loader would read is refused where it is written.
+ *
+ * Fonts are not in here: `build` writes them to the store and the manifest names them,
+ * leaving a bundle its markdown, its Typst, and what those inline.
+ *
+ * `built-loader.ts` spends it on the wire too. A deflate of what fits inside it is within
+ * zip framing of that, so one number bounds both ends and the fetch needs no second.
+ */
+export declare const MAX_BUNDLE_BYTES: number;
 /**
  * Pack a flat file map into a deterministic zip.
  * Keys are sorted before zipping so insertion order doesn't affect output.
@@ -10,6 +26,8 @@ export declare function packFiles(files: Record<string, Uint8Array>): Uint8Array
 /**
  * Unpack a zip into a flat file map.
  * Returns { path: Uint8Array } for every file entry in the archive.
- * Throws `quiver_invalid` where the budget is spent, before any entry inflates.
+ * Throws `quiver_invalid` where the budget is spent. fflate filters and inflates one
+ * entry per pass, so the entries the budget already took are resident when it throws —
+ * bounded, being what fit inside it.
  */
 export declare function unpackFiles(data: Uint8Array): Record<string, Uint8Array>;

package/dist/bundle.js

@@ -25,8 +25,11 @@ const ZIP_EPOCH = new Date(1980, 0, 1, 0, 0, 0, 0);
  *
  * Fonts are not in here: `build` writes them to the store and the manifest names them,
  * leaving a bundle its markdown, its Typst, and what those inline.
+ *
+ * `built-loader.ts` spends it on the wire too. A deflate of what fits inside it is within
+ * zip framing of that, so one number bounds both ends and the fetch needs no second.
  */
-const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
+export const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
 const MAX_ENTRY_BYTES = 16 * 1024 * 1024;
 const MAX_BUNDLE_ENTRIES = 2048;
 /**
@@ -73,19 +76,16 @@ export function packFiles(files) {
 /**
  * Unpack a zip into a flat file map.
  * Returns { path: Uint8Array } for every file entry in the archive.
- * Throws `quiver_invalid` where the budget is spent, before any entry inflates.
+ * Throws `quiver_invalid` where the budget is spent. fflate filters and inflates one
+ * entry per pass, so the entries the budget already took are resident when it throws —
+ * bounded, being what fit inside it.
  */
 export function unpackFiles(data) {
     const spend = bundleBudget();
-    const raw = unzipSync(data, {
+    return unzipSync(data, {
         filter: ({ name, originalSize }) => {
             spend(name, originalSize);
             return true;
         }
     });
-    const result = {};
-    for (const [key, value] of Object.entries(raw)) {
-        result[key] = value;
-    }
-    return result;
 }

package/dist/quiver-yaml.js

@@ -45,13 +45,11 @@ export function parseQuiverYaml(raw) {
     if (!isQuillName(name)) {
         throw new QuiverError('quiver_invalid', `Quiver.yaml: "name" value "${name}" contains invalid characters — only [A-Za-z0-9_-] are allowed`);
     }
-    if ('description' in doc && doc['description'] !== undefined) {
+    const meta = { name };
+    if (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'];
     }
     return meta;

package/dist/quiver.js

@@ -10,7 +10,7 @@
 import { QuiverError } from './errors.js';
 import { init } from '@quillmark/wasm';
 import { parseQuillRef } from './ref.js';
-import { matchesSemverSelector, chooseHighestVersion } from './semver.js';
+import { matchesSemverSelector } 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
@@ -121,17 +121,16 @@ export class Quiver {
      *   - `quill_not_found` if no version matches
      */
     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}`;
-            }
+        const { name, selector } = parseQuillRef(ref);
+        const versions = this.#catalog.get(name);
+        if (versions !== undefined) {
+            // Every loader materializes a catalog sorted descending, so the first match is
+            // the highest.
+            const winner = selector === undefined
+                ? versions[0]
+                : versions.find((v) => matchesSemverSelector(v, selector));
+            if (winner !== undefined)
+                return `${name}@${winner}`;
         }
         throw new QuiverError('quill_not_found', `No quill found for ref "${ref}" in quiver "${this.name}".`, { ref, quiverName: this.name });
     }

package/dist/ref.d.ts

@@ -3,8 +3,6 @@ export interface ParsedQuillRef {
     name: string;
     /** Undefined selects the highest version present. */
     selector?: string;
-    /** Selector part count: 1 = `x`, 2 = `x.y`, 3 = `x.y.z` (exact). */
-    selectorDepth?: 1 | 2 | 3;
 }
 /**
  * Whether `name` is a name a ref can spell. A quiver's own name and every catalog

package/dist/ref.js

@@ -22,19 +22,11 @@ export function parseQuillRef(ref) {
     if (atIndex === 0) {
         throw new QuiverError('invalid_ref', `Invalid ref: missing name in "${ref}"`, { ref });
     }
-    if (atIndex === -1) {
-        const name = ref;
-        if (!NAME_RE.test(name)) {
-            throw new QuiverError('invalid_ref', `Invalid ref: name "${name}" contains invalid characters`, { ref });
-        }
-        return { name };
-    }
-    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 });
-    }
-    if (!selector) {
+    // Split once: the charset the name is held to is one rule, and a ref with a selector
+    // is under it exactly as a bare one is.
+    const name = atIndex === -1 ? ref : ref.slice(0, atIndex);
+    const selector = atIndex === -1 ? undefined : ref.slice(atIndex + 1);
+    if (selector === '') {
         throw new QuiverError('invalid_ref', `Invalid ref: missing selector after "@" in "${ref}"`, {
             ref
         });
@@ -42,10 +34,11 @@ export function parseQuillRef(ref) {
     if (!NAME_RE.test(name)) {
         throw new QuiverError('invalid_ref', `Invalid ref: name "${name}" contains invalid characters`, { ref });
     }
+    if (selector === undefined) {
+        return { name };
+    }
     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 });
     }
-    const parts = selector.split('.');
-    const depth = parts.length;
-    return { name, selector, selectorDepth: depth };
+    return { name, selector };
 }

package/dist/semver.d.ts

@@ -8,9 +8,8 @@ export declare function isCanonicalSemver(version: string): boolean;
  * prefix comparison over an already-valid selector.
  */
 export declare function matchesSemverSelector(version: string, selector: string): boolean;
-/** Compares two canonical semver strings. Returns <0, 0, or >0. */
+/** Compares two canonical semver strings. Returns <0, 0, or >0. Three positions,
+ *  because `isCanonicalSemver` gates every entry point that reaches here. */
 export declare function compareSemver(a: string, b: string): number;
 /** Returns true for a canonical version below `MIN_PUBLISHED_VERSION`. */
 export declare function isDraft(version: string): boolean;
-/** Returns the highest version string, or null if empty. */
-export declare function chooseHighestVersion(versions: string[]): string | null;

package/dist/semver.js

@@ -10,8 +10,6 @@ export function isCanonicalSemver(version) {
  * prefix comparison over an already-valid selector.
  */
 export function matchesSemverSelector(version, selector) {
-    if (selector === version)
-        return true;
     const selectorParts = selector.split('.');
     const versionParts = version.split('.');
     if (selectorParts.length > versionParts.length)
@@ -22,16 +20,14 @@ export function matchesSemverSelector(version, selector) {
     }
     return true;
 }
-/** Compares two canonical semver strings. Returns <0, 0, or >0. */
+/** Compares two canonical semver strings. Returns <0, 0, or >0. Three positions,
+ *  because `isCanonicalSemver` gates every entry point that reaches here. */
 export function compareSemver(a, b) {
     const partsA = a.split('.').map(Number);
     const partsB = b.split('.').map(Number);
-    const len = Math.max(partsA.length, partsB.length);
-    for (let i = 0; i < len; i++) {
-        const numA = partsA[i] ?? 0;
-        const numB = partsB[i] ?? 0;
-        if (numA !== numB)
-            return numA - numB;
+    for (let i = 0; i < 3; i++) {
+        if (partsA[i] !== partsB[i])
+            return partsA[i] - partsB[i];
     }
     return 0;
 }
@@ -39,11 +35,3 @@ export function compareSemver(a, b) {
 export function isDraft(version) {
     return compareSemver(version, MIN_PUBLISHED_VERSION) < 0;
 }
-/** Returns the highest version string, or null if empty. */
-export function chooseHighestVersion(versions) {
-    if (versions.length === 0)
-        return null;
-    const copy = [...versions];
-    copy.sort((a, b) => compareSemver(b, a));
-    return copy[0] ?? null;
-}

package/dist/source-loader.d.ts

@@ -11,8 +11,8 @@ import type { QuiverLoader } from './quiver.js';
  * to build a catalog of quill names → sorted versions (descending).
  *
  * Throws:
- *   - `quiver_invalid` if Quiver.yaml is missing/invalid, a quill or version directory
- *     is a symlink, a quill dir holding versions is named outside the ref charset, a
+ *   - `quiver_invalid` if Quiver.yaml is invalid, any rung it opens or reads is a
+ *     symlink, a quill dir holding versions is named outside the ref charset, a
  *     version dir name is non-canonical, or a version dir is missing its Quill.yaml
  *     sentinel.
  *   - `transport_error` for I/O failures (permissions, etc.).

package/dist/source-loader.js

@@ -2,7 +2,7 @@
  * Internal filesystem scanner for the Source Quiver layout. Statically imports
  * `node:fs`, so it is reachable from the Node entry alone.
  */
-import { readdir, readFile, lstat, stat } from 'node:fs/promises';
+import { readdir, readFile, lstat } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
 import { QuiverError } from './errors.js';
 import { parseQuiverYaml } from './quiver-yaml.js';
@@ -27,8 +27,8 @@ function refuseSymlink(st, path) {
  * to build a catalog of quill names → sorted versions (descending).
  *
  * Throws:
- *   - `quiver_invalid` if Quiver.yaml is missing/invalid, a quill or version directory
- *     is a symlink, a quill dir holding versions is named outside the ref charset, a
+ *   - `quiver_invalid` if Quiver.yaml is invalid, any rung it opens or reads is a
+ *     symlink, a quill dir holding versions is named outside the ref charset, a
  *     version dir name is non-canonical, or a version dir is missing its Quill.yaml
  *     sentinel.
  *   - `transport_error` for I/O failures (permissions, etc.).
@@ -39,9 +39,12 @@ export async function scanSourceQuiver(rootDir) {
     const quiverYamlPath = join(rootDir, 'Quiver.yaml');
     let raw;
     try {
+        refuseSymlink(await lstat(quiverYamlPath), quiverYamlPath);
         raw = await readFile(quiverYamlPath);
     }
     catch (err) {
+        if (err instanceof QuiverError)
+            throw err;
         // ENOENT → transport_error: a missing Quiver.yaml means the path itself
         // does not point to a quiver — this is a missing-path condition, not a
         // structural violation of a quiver that exists.
@@ -104,9 +107,11 @@ export async function scanSourceQuiver(rootDir) {
             }
             const quillYamlPath = join(versionPath, 'Quill.yaml');
             try {
-                await stat(quillYamlPath);
+                refuseSymlink(await lstat(quillYamlPath), quillYamlPath);
             }
             catch (err) {
+                if (err instanceof QuiverError)
+                    throw err;
                 const code = err.code;
                 if (code === 'ENOENT') {
                     throw new QuiverError('quiver_invalid', `Quill "${quillName}@${versionDir}" is missing required "Quill.yaml"`, { quiverName: meta.name, version: versionDir });

package/dist/transports/fs-built-transport.js

@@ -14,8 +14,8 @@ export class FsBuiltTransport {
     constructor(rootDir) {
         this.rootDir = rootDir;
     }
-    // No cache sits between this and the bytes, so `FetchOptions` has nothing to
-    // act on here.
+    // No cache sits between this and the bytes, and a file is read at the size it
+    // is, so `FetchOptions` has nothing to act on here.
     async fetchBytes(relativePath) {
         if (isAbsolute(relativePath)) {
             throw new QuiverError('transport_error', `FsBuiltTransport: absolute paths are not allowed: "${relativePath}"`);

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

@@ -8,5 +8,5 @@ import type { BuiltTransport, FetchOptions } from '../built-loader.js';
 export declare class HttpTransport implements BuiltTransport {
     private readonly baseUrl;
     constructor(baseUrl: string);
-    fetchBytes(relativePath: string, opts?: FetchOptions): Promise<Uint8Array>;
+    fetchBytes(relativePath: string, opts: FetchOptions): Promise<Uint8Array>;
 }

package/dist/transports/http-transport.js

@@ -5,6 +5,36 @@
  * Uses globalThis.fetch — no node: imports at any level.
  */
 import { QuiverError } from '../errors.js';
+/** Over the ceiling is `quiver_invalid`, not `transport_error`: a retry fetches the same
+ *  response, so there is nothing for an evicting cache to fix. */
+function oversized(url, max, says) {
+    return new QuiverError('quiver_invalid', `"${url}" ${says} the ${max} bytes a fetch may read`);
+}
+/** The body chunk by chunk, refused past the ceiling. Cancelling the reader terminates
+ *  the fetch, so nothing more of a refused response is pulled off the socket. */
+async function readCapped(body, url, max) {
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > max) {
+            await reader.cancel();
+            throw oversized(url, max, 'is over');
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(total);
+    let at = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, at);
+        at += chunk.byteLength;
+    }
+    return bytes;
+}
 export class HttpTransport {
     baseUrl;
     constructor(baseUrl) {
@@ -15,11 +45,13 @@ export class HttpTransport {
         const url = `${this.baseUrl}${cleanPath}`;
         let response;
         try {
-            // `no-cache` revalidates with the origin rather than skipping the cache:
-            // a 304 still serves from disk. Only the pointer asks for it, and only
-            // the browser-cache layer of the stale-pointer failure is a client's to
-            // fix; a stale edge is answered by that host's cache headers.
-            response = await globalThis.fetch(url, opts?.revalidate ? { cache: 'no-cache' } : undefined);
+            // `no-cache` revalidates with the origin rather than skipping the cache: a 304
+            // still serves from disk. `force-cache` takes a cached response whatever its
+            // age, which a digest-carrying name is entitled to; a stale one fails
+            // verification upstream as `transport_error`, which an evicting cache clears.
+            response = await globalThis.fetch(url, {
+                cache: opts.revalidate ? 'no-cache' : 'force-cache'
+            });
         }
         catch (err) {
             throw new QuiverError('transport_error', `Network error fetching "${url}": ${err.message}`, { cause: err });
@@ -27,7 +59,29 @@ export class HttpTransport {
         if (!response.ok) {
             throw new QuiverError('transport_error', `HTTP ${response.status} fetching "${url}"`);
         }
-        const buffer = await response.arrayBuffer();
-        return new Uint8Array(buffer);
+        // A fast reject; the running total below is what holds the ceiling. `Content-Length`
+        // is the encoded length, so under `Content-Encoding` it under-reports; a missing one is
+        // 0 and an unparseable one NaN, neither over the ceiling, so both accept early.
+        const declared = Number(response.headers.get('content-length'));
+        if (declared > opts.maxBytes) {
+            throw oversized(url, opts.maxBytes, `states ${declared} bytes, over`);
+        }
+        try {
+            // A host that hands back no stream is measured after the fact rather than
+            // refused: the degraded check still bounds what reaches the unpack budget,
+            // and refusing outright would cost hosts that work today.
+            if (response.body === null) {
+                const buffer = await response.arrayBuffer();
+                if (buffer.byteLength > opts.maxBytes)
+                    throw oversized(url, opts.maxBytes, 'is over');
+                return new Uint8Array(buffer);
+            }
+            return await readCapped(response.body, url, opts.maxBytes);
+        }
+        catch (err) {
+            if (err instanceof QuiverError)
+                throw err;
+            throw new QuiverError('transport_error', `Network error reading "${url}": ${err.message}`, { cause: err });
+        }
     }
 }

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

@@ -10,6 +10,7 @@ export declare class MemoryTransport implements BuiltTransport {
     private readonly fallback?;
     private readonly files;
     constructor(files: ReadonlyMap<string, Uint8Array>, fallback?: BuiltTransport | undefined);
-    /** The map answers first. `FetchOptions` reaches only the fallback: a held byte has no cache to revalidate against. */
-    fetchBytes(relativePath: string, opts?: FetchOptions): Promise<Uint8Array>;
+    /** The map answers first. `FetchOptions` reaches only the fallback: a held byte has no
+     *  cache to revalidate against and no arrival to refuse. */
+    fetchBytes(relativePath: string, opts: FetchOptions): Promise<Uint8Array>;
 }

package/dist/transports/memory-transport.js

@@ -21,7 +21,8 @@ export class MemoryTransport {
         this.fallback = fallback;
         this.files = normalizeKeys(files);
     }
-    /** The map answers first. `FetchOptions` reaches only the fallback: a held byte has no cache to revalidate against. */
+    /** The map answers first. `FetchOptions` reaches only the fallback: a held byte has no
+     *  cache to revalidate against and no arrival to refuse. */
     async fetchBytes(relativePath, opts) {
         const bytes = this.files.get(relativePath);
         if (bytes !== undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quillmark/quiver",
-	"version": "0.26.0",
+	"version": "0.28.0",
 	"description": "A quiver of Quillmark quills: load one, pack one, hand out quills.",
 	"type": "module",
 	"license": "Apache-2.0",
@@ -42,7 +42,7 @@
 		"NOTICE"
 	],
 	"peerDependencies": {
-		"@quillmark/wasm": ">=0.109.0-0"
+		"@quillmark/wasm": ">=0.113.0-0"
 	},
 	"dependencies": {
 		"fflate": "^0.8.2",