@quillmark/quiver 0.29.0 → 0.31.0

package/dist/built-loader.js

@@ -1,113 +1,147 @@
 /**
- * Built-quiver loader: reads a packed artifact through a transport, validates
- * its pointer and manifest, and hands back a Quiver whose loader fetches
- * bundles and fonts on demand, each checked against the digest in its name.
+ * Built-quiver loader: reads `quiver.json` through a reader, validates it, and hands back
+ * a Quiver whose loader reads bundles and fonts on demand.
  *
  * Package-internal, and browser-safe: no static `node:` imports at any level.
  */
 import { QuiverError } from './errors.js';
-import { MAX_BUNDLE_BYTES, unpackFiles } from './bundle.js';
+import { 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 { FORMAT, INDEX } from './format.js';
+import { isFont, isZip } from './signature.js';
 import { createQuiver } from './quiver.js';
-/**
- * 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, 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}`);
-    }
-    return bytes;
+export function httpReader(base) {
+    const root = base.endsWith('/') ? base : `${base}/`;
+    return async (path, mode) => {
+        const url = `${root}${path}`;
+        let response;
+        try {
+            response = await globalThis.fetch(url, { cache: mode });
+        }
+        catch (err) {
+            throw new QuiverError('transport_error', `Network error fetching "${url}": ${err.message}`, { cause: err });
+        }
+        if (!response.ok) {
+            throw new QuiverError('transport_error', `HTTP ${response.status} fetching "${url}"`);
+        }
+        try {
+            return new Uint8Array(await response.arrayBuffer());
+        }
+        catch (err) {
+            throw new QuiverError('transport_error', `Network error reading "${url}": ${err.message}`, { cause: err });
+        }
+    };
 }
-// ─── Path validation ──────────────────────────────────────────────────────────
-// Each name carries the digest of what it names; the capture group is the
-// digest the fetch is checked against, so path validation and verification
-// read the same character span. `build` writes exactly NAME_DIGEST_LENGTH
-// chars for bundles and manifests and the full 64 for store entries.
-const DIGEST = `[0-9a-f]{${NAME_DIGEST_LENGTH},}`;
-const MANIFEST_FILENAME_RE = new RegExp(`^manifest\\.(${DIGEST})\\.json$`);
-// The name span is the ref charset, not a filename charset: `build` spells a bundle
-// off the catalog row, and a row is a name a ref can spell.
-const BUNDLE_FILENAME_RE = new RegExp(`^[A-Za-z0-9_-]+@[0-9]+\\.[0-9]+\\.[0-9]+\\.(${DIGEST})\\.zip$`);
+/** Over bytes the caller holds; a leading `./` or `/` on a key is dropped. */
+export function filesReader(files) {
+    const held = new Map([...files].map(([key, bytes]) => [key.replace(/^\.?\//, ''), bytes]));
+    return async (path) => {
+        const bytes = held.get(path);
+        if (bytes === undefined) {
+            throw new QuiverError('transport_error', `No bytes held for "${path}": Quiver.fromBuiltFiles needs the whole artifact`);
+        }
+        return bytes;
+    };
+}
+// The shapes `build` writes. Neither admits a separator, so a validated name read off
+// `quiver.json` stays inside the artifact on every reader.
+const BUNDLE_RE = /^[A-Za-z0-9_-]+@[0-9]+\.[0-9]+\.[0-9]+\.[0-9a-f]+\.zip$/;
 const FONT_HASH_RE = /^[0-9a-f]{64}$/;
-/** The digest a content-addressed filename carries. Throws `quiver_invalid`. */
-function digestOfName(re, name, what) {
-    const match = re.exec(name);
-    if (match === null) {
-        throw new QuiverError('quiver_invalid', `${what} is invalid: "${name}"`);
-    }
-    return match[1];
+/** Bytes a host answered with that are not the file named: a `transport_error`, so the
+ *  reread below gets its turn. */
+function refused(path, what) {
+    return new QuiverError('transport_error', `"${path}" arrived as something other than ${what}`);
 }
-function validateFontHash(hash, context) {
-    if (!FONT_HASH_RE.test(hash)) {
-        throw new QuiverError('quiver_invalid', `${context}: font hash is invalid: "${hash}"`);
+/** A cached read that fails, by transport or by `opens`, is read once more past the cache,
+ *  which replaces what the cache held. */
+async function readChecked(read, path, opens, what) {
+    try {
+        const cached = await read(path, 'force-cache');
+        if (opens(cached))
+            return cached;
     }
+    catch {
+        // The reload's answer is the one that stands.
+    }
+    const bytes = await read(path, 'reload');
+    if (!opens(bytes))
+        throw refused(path, what);
+    return bytes;
 }
-// ─── BuiltLoader implementation ─────────────────────────────────────────────
 class BuiltLoader {
-    transport;
-    index;
-    /** Font byte cache: hash → in-flight or resolved Promise. */
-    fontCache = new Map();
-    constructor(transport, 
-    /** Index map from "name@version" to its manifest entry. */
-    index) {
-        this.transport = transport;
-        this.index = index;
+    read;
+    entries;
+    #fonts = new Map();
+    #rereading;
+    constructor(read, entries) {
+        this.read = read;
+        this.entries = entries;
     }
+    /**
+     * A tab holding the previous generation's index asks for names the next one deleted,
+     * so a failed read rereads `quiver.json` once and retries under that entry where it
+     * names other files. A reread refusing the index is the error that explains the
+     * failure, and is the one thrown.
+     */
     async loadTree(name, version) {
-        // 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'), MAX_BUNDLE_BYTES);
-        const files = unpackFiles(zipBytes);
-        const fontEntries = Object.entries(entry.fonts);
-        await Promise.all(fontEntries.map(async ([path, hash]) => {
-            files[path] = await this.fetchFont(hash);
+        const key = `${name}@${version}`;
+        const entry = this.entries.get(key);
+        try {
+            return await this.#treeOf(entry);
+        }
+        catch (err) {
+            let index;
+            try {
+                index = await this.#reread();
+            }
+            catch (reread) {
+                throw reread instanceof QuiverError && reread.code === 'quiver_invalid' ? reread : err;
+            }
+            const fresh = index.entries.get(key);
+            if (fresh === undefined || sameFiles(fresh, entry))
+                throw err;
+            return this.#treeOf(fresh);
+        }
+    }
+    /** One reread in flight, taking every entry both generations carry. */
+    #reread() {
+        return (this.#rereading ??= readIndex(this.read)
+            .then((index) => {
+            for (const [key, entry] of index.entries) {
+                if (this.entries.has(key))
+                    this.entries.set(key, entry);
+            }
+            return index;
+        })
+            .finally(() => {
+            this.#rereading = undefined;
+        }));
+    }
+    async #treeOf(entry) {
+        const zip = await readChecked(this.read, entry.bundle, isZip, 'a zip');
+        const files = unpackFiles(zip);
+        await Promise.all(Object.entries(entry.fonts).map(async ([path, hash]) => {
+            files[path] = await this.#font(hash, path);
         }));
         return new Map(Object.entries(files));
     }
-    /**
-     * Fetch a font by hash from store/<hash>, coalescing concurrent requests for
-     * the same hash into a single fetch. On error, removes the cache entry so
-     * callers can retry.
-     */
-    fetchFont(hash) {
-        let promise = this.fontCache.get(hash);
-        if (!promise) {
-            promise = fetchVerified(this.transport, `store/${hash}`, hash, MAX_FONT_BYTES).catch((err) => {
-                this.fontCache.delete(hash);
+    /** One read per hash, coalesced; a failure is evicted so a retry reads again. */
+    #font(hash, rel) {
+        let bytes = this.#fonts.get(hash);
+        if (bytes === undefined) {
+            bytes = readChecked(this.read, `fonts/${hash}`, (font) => isFont(font, rel), 'a font').catch((err) => {
+                this.#fonts.delete(hash);
                 throw err;
             });
-            this.fontCache.set(hash, promise);
+            this.#fonts.set(hash, bytes);
         }
-        return promise;
+        return bytes;
     }
 }
-// ─── Pointer + manifest validation helpers ────────────────────────────────────
+function sameFiles(a, b) {
+    return a.bundle === b.bundle && JSON.stringify(a.fonts) === JSON.stringify(b.fonts);
+}
 function assertNoUnknownKeys(obj, allowed, context) {
     for (const key of Object.keys(obj)) {
         if (!allowed.includes(key)) {
@@ -115,118 +149,106 @@ function assertNoUnknownKeys(obj, allowed, context) {
         }
     }
 }
-function parsePointer(raw) {
-    let parsed;
+async function readIndex(read) {
+    let bytes;
     try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        throw new QuiverError('quiver_invalid', 'latest.json contains invalid JSON');
+        bytes = await read(INDEX, 'no-cache');
     }
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        throw new QuiverError('quiver_invalid', 'latest.json must be a JSON object');
-    }
-    const obj = parsed;
-    // The format, read before anything is believed about the rest. An unknown key is not
-    // a failure here: this is the document a newer format announces itself on, and a
-    // reader rejecting what it does not recognise refuses the announcement too. Absent
-    // means a build from before the marker (`format.ts`).
-    const format = obj['format'] ?? POINTER_FORMAT;
-    if (typeof format !== 'number' || !Number.isInteger(format) || format < 1) {
-        throw new QuiverError('quiver_invalid', `latest.json: "format" must be a positive integer, got ${JSON.stringify(obj['format'])}`);
-    }
-    if (format > POINTER_FORMAT) {
-        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.`);
-    }
-    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');
+    catch (err) {
+        if (err instanceof QuiverError)
+            throw err;
+        throw new QuiverError('transport_error', `Failed to read ${INDEX}: ${err.message}`, {
+            cause: err
+        });
     }
-    return manifest;
+    return parseIndex(new TextDecoder().decode(bytes));
 }
-function parseManifest(raw) {
+function parseIndex(raw) {
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch {
-        throw new QuiverError('quiver_invalid', 'Manifest file contains invalid JSON');
+        throw new QuiverError('quiver_invalid', `${INDEX} contains invalid JSON`);
     }
     if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        throw new QuiverError('quiver_invalid', 'Manifest must be a JSON object');
+        throw new QuiverError('quiver_invalid', `${INDEX} must be a JSON object`);
     }
     const obj = parsed;
-    assertNoUnknownKeys(obj, ['version', 'name', 'description', 'quills'], 'manifest');
-    const version = obj['version'];
-    if (typeof version !== 'number' || !Number.isInteger(version) || version < 1) {
-        throw new QuiverError('quiver_invalid', `Manifest version must be a positive integer, got ${JSON.stringify(version)}`);
+    // Read before the key check, so a newer document is refused as newer rather than as
+    // carrying a field this reader does not know.
+    const format = obj['format'];
+    if (typeof format !== 'number' || !Number.isInteger(format) || format < 1) {
+        throw new QuiverError('quiver_invalid', `${INDEX}: "format" must be a positive integer, got ${JSON.stringify(format)}`);
     }
-    if (version > MANIFEST_VERSION) {
-        throw new QuiverError('quiver_invalid', `This quiver's manifest is version ${version} and this loader reads ${MANIFEST_VERSION}. ` +
+    if (format > FORMAT) {
+        throw new QuiverError('quiver_invalid', `This quiver is built in format ${format} and this loader reads ${FORMAT}. ` +
             `Upgrade @quillmark/quiver, or for a served client the client itself, which carries the copy that reads this.`);
     }
+    assertNoUnknownKeys(obj, ['format', 'name', 'description', 'quills'], INDEX);
     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');
+        throw new QuiverError('quiver_invalid', `${INDEX} must have a non-empty string "name" field`);
     }
     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}`);
+        throw new QuiverError('quiver_invalid', `${INDEX} "description" must be a string if present, got ${typeof description}`);
     }
-    const entries = obj['quills'];
-    if (!Array.isArray(entries)) {
-        throw new QuiverError('quiver_invalid', 'Manifest must have a "quills" array');
+    const quills = obj['quills'];
+    if (!Array.isArray(quills)) {
+        throw new QuiverError('quiver_invalid', `${INDEX} must have a "quills" array`);
     }
-    const quills = [];
-    for (let i = 0; i < entries.length; i++) {
-        const entry = entries[i];
+    const entries = new Map();
+    for (let i = 0; i < quills.length; i++) {
+        const at = `${INDEX} quills[${i}]`;
+        const entry = quills[i];
         if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
-            throw new QuiverError('quiver_invalid', `manifest.quills[${i}] must be an object`);
+            throw new QuiverError('quiver_invalid', `${at} must be an object`);
         }
         const e = entry;
-        assertNoUnknownKeys(e, ['name', 'version', 'bundle', 'fonts'], `manifest.quills[${i}]`);
+        assertNoUnknownKeys(e, ['name', 'version', 'bundle', 'fonts'], at);
         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`);
+            throw new QuiverError('quiver_invalid', `${at}.name must be a non-empty string`);
         }
         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`);
+            throw new QuiverError('quiver_invalid', `${at}.name "${quillName}" is not a name a ref can spell — only [A-Za-z0-9_-] are allowed`);
         }
         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)}"`);
+            throw new QuiverError('quiver_invalid', `${at}.version must be canonical semver (x.y.z), got "${String(version)}"`);
         }
         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`);
+        if (typeof bundle !== 'string' || !BUNDLE_RE.test(bundle)) {
+            throw new QuiverError('quiver_invalid', `${at}.bundle is invalid: "${String(bundle)}"`);
         }
-        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`);
+            throw new QuiverError('quiver_invalid', `${at}.fonts must be an object`);
         }
         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`);
+        for (const [path, hash] of Object.entries(declared)) {
+            if (typeof hash !== 'string' || !FONT_HASH_RE.test(hash)) {
+                throw new QuiverError('quiver_invalid', `${at}.fonts["${path}"] is not a font hash: ${JSON.stringify(hash)}`);
             }
-            validateFontHash(v, `manifest.quills[${i}].fonts["${k}"]`);
-            fonts[k] = v;
+            fonts[path] = hash;
         }
-        quills.push({ name: quillName, version, bundle, fonts });
+        const key = `${quillName}@${version}`;
+        if (entries.has(key)) {
+            throw new QuiverError('quiver_invalid', `Duplicate quill entry in ${INDEX}: "${key}"`);
+        }
+        entries.set(key, { name: quillName, version, bundle, fonts });
     }
-    return { name, description, quills };
+    return { name, description, entries };
 }
-// ─── Catalog assembly ─────────────────────────────────────────────────────────
 /**
- * Name → versions (descending), derived from the index. One structure backs
- * both the loader's lookups and the Quiver's catalog, so the two cannot
- * disagree about what the manifest holds.
+ * Name → versions (descending), derived from the entries. One structure backs both the
+ * loader's lookups and the Quiver's catalog, so the two cannot disagree about what
+ * `quiver.json` holds.
  */
-function catalogOf(index) {
+function catalogOf(entries) {
     const catalog = new Map();
-    for (const entry of index.values()) {
+    for (const entry of entries.values()) {
         const versions = catalog.get(entry.name) ?? [];
         versions.push(entry.version);
         catalog.set(entry.name, versions);
@@ -236,42 +258,7 @@ function catalogOf(index) {
     }
     return catalog;
 }
-// ─── Main entry point ─────────────────────────────────────────────────────────
-/** Load a build-output quiver via the given transport. */
-export async function loadBuiltQuiver(transport) {
-    // The pointer is the one name that is not content-addressed, so it is also the
-    // one fetch that must revalidate.
-    let pointerBytes;
-    try {
-        pointerBytes = await transport.fetchBytes('latest.json', {
-            revalidate: true,
-            maxBytes: MAX_DOCUMENT_BYTES
-        });
-    }
-    catch (err) {
-        if (err instanceof QuiverError)
-            throw err;
-        throw new QuiverError('transport_error', `Failed to fetch latest.json: ${err.message}`, { cause: err });
-    }
-    const manifestFileName = parsePointer(new TextDecoder().decode(pointerBytes));
-    const manifestDigest = digestOfName(MANIFEST_FILENAME_RE, manifestFileName, 'Pointer manifest filename');
-    let manifestBytes;
-    try {
-        manifestBytes = await fetchVerified(transport, manifestFileName, manifestDigest, MAX_DOCUMENT_BYTES);
-    }
-    catch (err) {
-        if (err instanceof QuiverError)
-            throw err;
-        throw new QuiverError('transport_error', `Failed to fetch manifest "${manifestFileName}": ${err.message}`, { cause: err });
-    }
-    const manifest = parseManifest(new TextDecoder().decode(manifestBytes));
-    const index = new Map();
-    for (const entry of manifest.quills) {
-        const key = `${entry.name}@${entry.version}`;
-        if (index.has(key)) {
-            throw new QuiverError('quiver_invalid', `Duplicate quill entry in manifest: "${key}"`);
-        }
-        index.set(key, entry);
-    }
-    return createQuiver(manifest.name, manifest.description, catalogOf(index), new BuiltLoader(transport, index));
+export async function loadBuiltQuiver(read) {
+    const { name, description, entries } = await readIndex(read);
+    return createQuiver(name, description, catalogOf(entries), new BuiltLoader(read, entries));
 }

package/dist/bundle.d.ts

@@ -1,22 +1,6 @@
 /**
  * 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.

package/dist/bundle.js

@@ -23,13 +23,10 @@ const ZIP_EPOCH = new Date(1980, 0, 1, 0, 0, 0, 0);
  * 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,
+ * Fonts are not in here: `build` writes them under `fonts/` and `quiver.json` 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 const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
+const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
 const MAX_ENTRY_BYTES = 16 * 1024 * 1024;
 const MAX_BUNDLE_ENTRIES = 2048;
 /**
@@ -38,8 +35,8 @@ const MAX_BUNDLE_ENTRIES = 2048;
  * Unpacking spends the sizes the central directory declares, and those are the sizes
  * fflate allocates: each entry inflates into a buffer of exactly its declared size,
  * which never grows. So a header cannot buy more than it declares — it can only
- * understate itself and truncate its own entry, which is the corrupt bundle the digest
- * already answers.
+ * understate itself and truncate its own entry, which is a corrupt bundle rather than an
+ * allocation.
  */
 function bundleBudget() {
     let total = 0;

package/dist/format.d.ts

@@ -1,21 +1,15 @@
+/** The one name a reader fetches that carries no digest: the catalog, and where every
+ *  other name is read off. */
+export declare const INDEX = "quiver.json";
 /**
- * The built artifact's format, stamped into `latest.json` and refused to be read past
- * (QUIVER §"The pointer" for why the pointer carries it and reads past keys it does not
- * know).
- *
- * It moves when a reader assuming it would misread a tree rather than fail on it: a
- * renamed pointer field, a second pointer, a store keyed by something other than the
- * full hash. A change confined to the manifest's own shape moves the manifest's
- * `version` instead.
+ * The artifact's format, stamped into `quiver.json` and refused to be read past (QUIVER
+ * §"The index"). Any change a reader assuming the previous shape would misread or reject
+ * moves it: `quiver.json` is closed, so an added field is one of those.
  */
-export declare const POINTER_FORMAT = 1;
+export declare const FORMAT = 2;
 /**
- * The manifest's shape, stated in the document and refused to be read past. Version 2
- * carries the quiver's `description`; version 1 is the same document without it.
- *
- * The manifest is closed, so a field added to it is a field an older reader rejects as an
- * unknown key, naming neither what happened nor what to do. The version is what that
- * reader reads first instead, and a manifest above its own is refused with the upgrade
- * named.
+ * What a reader of format 1 fetches first. It reads `format` off it before anything else,
+ * so a file carrying this format and nothing more is refused there with the upgrade named,
+ * rather than as a missing file. No reader of this format reads it.
  */
-export declare const MANIFEST_VERSION = 2;
+export declare const LEGACY_POINTER = "latest.json";

package/dist/format.js

@@ -1,21 +1,15 @@
+/** The one name a reader fetches that carries no digest: the catalog, and where every
+ *  other name is read off. */
+export const INDEX = 'quiver.json';
 /**
- * The built artifact's format, stamped into `latest.json` and refused to be read past
- * (QUIVER §"The pointer" for why the pointer carries it and reads past keys it does not
- * know).
- *
- * It moves when a reader assuming it would misread a tree rather than fail on it: a
- * renamed pointer field, a second pointer, a store keyed by something other than the
- * full hash. A change confined to the manifest's own shape moves the manifest's
- * `version` instead.
+ * The artifact's format, stamped into `quiver.json` and refused to be read past (QUIVER
+ * §"The index"). Any change a reader assuming the previous shape would misread or reject
+ * moves it: `quiver.json` is closed, so an added field is one of those.
  */
-export const POINTER_FORMAT = 1;
+export const FORMAT = 2;
 /**
- * The manifest's shape, stated in the document and refused to be read past. Version 2
- * carries the quiver's `description`; version 1 is the same document without it.
- *
- * The manifest is closed, so a field added to it is a field an older reader rejects as an
- * unknown key, naming neither what happened nor what to do. The version is what that
- * reader reads first instead, and a manifest above its own is refused with the upgrade
- * named.
+ * What a reader of format 1 fetches first. It reads `format` off it before anything else,
+ * so a file carrying this format and nothing more is refused there with the upgrade named,
+ * rather than as a missing file. No reader of this format reads it.
  */
-export const MANIFEST_VERSION = 2;
+export const LEGACY_POINTER = 'latest.json';

package/dist/node.d.ts

@@ -28,7 +28,7 @@ import type { BuildOptions } from './build.js';
 export declare function fromDir(pathOrFileUrl: string): Promise<Quiver>;
 /**
  * Loads a packed (build-output) quiver from a local directory containing
- * `latest.json` and the manifest/bundle/store files written by `build`.
+ * `quiver.json` and the bundles and fonts written by `build`.
  * Symmetric to `Quiver.fromBuiltUrl(url)` but reads from disk instead of HTTP:
  * no network required.
  *

package/dist/node.js

@@ -12,7 +12,9 @@ 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 { QuiverError } from './errors.js';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 /**
  * Reads a Source Quiver from a local directory containing `Quiver.yaml` and
@@ -38,7 +40,7 @@ export async function fromDir(pathOrFileUrl) {
 }
 /**
  * Loads a packed (build-output) quiver from a local directory containing
- * `latest.json` and the manifest/bundle/store files written by `build`.
+ * `quiver.json` and the bundles and fonts written by `build`.
  * Symmetric to `Quiver.fromBuiltUrl(url)` but reads from disk instead of HTTP:
  * no network required.
  *
@@ -49,7 +51,16 @@ export async function fromDir(pathOrFileUrl) {
  * Throws `quiver_invalid` on format errors, `transport_error` on I/O failure.
  */
 export async function fromBuiltDir(dirPath) {
-    return loadBuiltQuiver(new FsBuiltTransport(dirPath));
+    return loadBuiltQuiver(async (path) => {
+        const file = join(dirPath, path);
+        try {
+            const buf = await readFile(file);
+            return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+        }
+        catch (err) {
+            throw new QuiverError('transport_error', `Failed to read "${file}": ${err.message}`, { cause: err });
+        }
+    });
 }
 /**
  * Reads the Source Quiver at sourceDir, validates it, and writes the runtime