@quillmark/quiver 0.1.1 → 0.2.0

package/dist/quiver.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Quiver — primary runtime abstraction for a collection of quills.
+ *
+ * Polymorphism via composition: internally stores a pluggable loader
+ * (either source-backed or packed-backed).
+ */
+import type { PackOptions } from "./pack.js";
+/** @internal Internal loader strategy: source or packed. */
+export interface QuiverLoader {
+    loadTree(name: string, version: string): Promise<Map<string, Uint8Array>>;
+}
+export declare class Quiver {
+    #private;
+    readonly name: string;
+    /**
+     * Private constructor — use static factory methods.
+     * TS prevents external `new Quiver(...)` at compile time.
+     * Static methods inside can still call it.
+     */
+    private constructor();
+    /** @internal Used by loadPackedQuiver. Not part of the public API. */
+    static _fromLoader(name: string, catalog: Map<string, string[]>, loader: QuiverLoader): Quiver;
+    /**
+     * Node-only factory. Reads a Source Quiver from a directory containing
+     * `Quiver.yaml` and `quills/<name>/<version>/Quill.yaml` entries.
+     *
+     * 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.
+     *
+     * Throws `quiver_invalid` on schema violations, `transport_error` on I/O failure.
+     */
+    static fromSourceDir(path: string): Promise<Quiver>;
+    /**
+     * Node-only factory. Loads a Packed Quiver from a local directory.
+     *
+     * Uses dynamic imports so this module stays browser-safe at evaluation time.
+     *
+     * Throws `transport_error` on I/O failure, `quiver_invalid` on format errors.
+     */
+    static fromPackedDir(path: string): Promise<Quiver>;
+    /**
+     * Browser-safe factory. Loads a Packed Quiver from an HTTP base URL.
+     *
+     * Throws `transport_error` on network/HTTP failure, `quiver_invalid` on
+     * format errors.
+     */
+    static fromHttp(url: string): Promise<Quiver>;
+    /** Returns all known quill names, sorted lexicographically. */
+    quillNames(): string[];
+    /**
+     * Returns all canonical versions for a given quill name, sorted descending.
+     * Returns an empty array if the quill name is not in the catalog.
+     */
+    versionsOf(name: string): string[];
+    /**
+     * Node-only tooling. Writes a Packed Quiver artifact to outDir.
+     *
+     * Uses dynamic import of `./pack.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 pack(sourceDir: string, outDir: string, opts?: PackOptions): Promise<void>;
+    /**
+     * 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.
+     *
+     * Throws `transport_error` if name/version not in catalog or I/O fails.
+     */
+    loadTree(name: string, version: string): Promise<Map<string, Uint8Array>>;
+}

package/dist/quiver.js

@@ -0,0 +1,109 @@
+/**
+ * Quiver — primary runtime abstraction for a collection of quills.
+ *
+ * Polymorphism via composition: internally stores a pluggable loader
+ * (either source-backed or packed-backed).
+ */
+import { QuiverError } from "./errors.js";
+import { assertNode } from "./assert-node.js";
+export class Quiver {
+    name;
+    #catalog;
+    #loader;
+    /**
+     * Private constructor — use static factory methods.
+     * TS prevents external `new Quiver(...)` at compile time.
+     * Static methods inside can still call it.
+     */
+    constructor(name, catalog, loader) {
+        this.name = name;
+        this.#catalog = new Map(catalog);
+        this.#loader = loader;
+    }
+    /** @internal Used by loadPackedQuiver. 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.
+     *
+     * 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.
+     *
+     * Throws `quiver_invalid` on schema violations, `transport_error` on I/O failure.
+     */
+    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);
+    }
+    /**
+     * Node-only factory. Loads a Packed Quiver from a local directory.
+     *
+     * Uses dynamic imports so this module stays browser-safe at evaluation time.
+     *
+     * Throws `transport_error` on I/O failure, `quiver_invalid` on format errors.
+     */
+    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);
+    }
+    /**
+     * Browser-safe factory. Loads a Packed Quiver from an HTTP base URL.
+     *
+     * Throws `transport_error` on network/HTTP failure, `quiver_invalid` on
+     * format errors.
+     */
+    static async fromHttp(url) {
+        const { HttpTransport } = await import("./transports/http-transport.js");
+        const { loadPackedQuiver } = await import("./packed-loader.js");
+        const transport = new HttpTransport(url);
+        return loadPackedQuiver(transport);
+    }
+    /** Returns all known quill names, sorted lexicographically. */
+    quillNames() {
+        return [...this.#catalog.keys()].sort();
+    }
+    /**
+     * Returns all canonical versions for a given quill name, sorted descending.
+     * Returns an empty array if the quill name is not in the catalog.
+     */
+    versionsOf(name) {
+        return [...(this.#catalog.get(name) ?? [])];
+    }
+    /**
+     * Node-only tooling. Writes a Packed Quiver artifact to outDir.
+     *
+     * Uses dynamic import of `./pack.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);
+    }
+    /**
+     * 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.
+     *
+     * Throws `transport_error` if name/version not in catalog or I/O fails.
+     */
+    async loadTree(name, version) {
+        const versions = this.#catalog.get(name);
+        if (!versions || !versions.includes(version)) {
+            throw new QuiverError("transport_error", `Quill "${name}@${version}" not found in quiver "${this.name}"`, { quiverName: this.name, version, ref: `${name}@${version}` });
+        }
+        return this.#loader.loadTree(name, version);
+    }
+}

package/dist/ref.d.ts

@@ -0,0 +1,14 @@
+/** Internal parsed representation of a quill reference. */
+export interface ParsedQuillRef {
+    name: string;
+    /** Undefined = "highest in first-winning quiver". */
+    selector?: string;
+    /** Selector part count: 1 = `x`, 2 = `x.y`, 3 = `x.y.z` (exact). */
+    selectorDepth?: 1 | 2 | 3;
+}
+/**
+ * Throws QuiverError('invalid_ref') on malformed input.
+ * Validates name charset: [A-Za-z0-9_-]+
+ * Validates selector per §5 (x, x.y, x.y.z — digits only, no ranges/operators).
+ */
+export declare function parseQuillRef(ref: string): ParsedQuillRef;

package/dist/ref.js

@@ -0,0 +1,44 @@
+import { QuiverError } from "./errors.js";
+const NAME_RE = /^[A-Za-z0-9_-]+$/;
+const SELECTOR_RE = /^\d+(\.\d+){0,2}$/;
+/**
+ * Throws QuiverError('invalid_ref') on malformed input.
+ * Validates name charset: [A-Za-z0-9_-]+
+ * Validates selector per §5 (x, x.y, x.y.z — digits only, no ranges/operators).
+ */
+export function parseQuillRef(ref) {
+    if (!ref) {
+        throw new QuiverError("invalid_ref", `Invalid ref: empty string`, { ref });
+    }
+    const atIndex = ref.indexOf("@");
+    if (atIndex === 0) {
+        // Starts with @, no name
+        throw new QuiverError("invalid_ref", `Invalid ref: missing name in "${ref}"`, { ref });
+    }
+    if (atIndex === -1) {
+        // No selector — just a name
+        const name = ref;
+        if (!NAME_RE.test(name)) {
+            throw new QuiverError("invalid_ref", `Invalid ref: name "${name}" contains invalid characters`, { ref });
+        }
+        return { name };
+    }
+    // Has @
+    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) {
+        throw new QuiverError("invalid_ref", `Invalid ref: missing selector after "@" in "${ref}"`, { ref });
+    }
+    if (!NAME_RE.test(name)) {
+        throw new QuiverError("invalid_ref", `Invalid ref: name "${name}" contains invalid characters`, { ref });
+    }
+    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 };
+}

package/dist/registry.d.ts

@@ -0,0 +1,39 @@
+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>;
+}

package/dist/registry.js

@@ -0,0 +1,115 @@
+import { QuiverError } from "./errors.js";
+import { parseQuillRef } from "./ref.js";
+import { matchesSemverSelector, chooseHighestVersion } from "./semver.js";
+export class QuiverRegistry {
+    #engine;
+    #quivers;
+    /** Cache: canonical ref → pending or resolved Promise<QuillLike>. */
+    #cache = new Map();
+    constructor(args) {
+        this.#engine = args.engine;
+        // Validate no two quivers share Quiver.yaml.name → quiver_collision.
+        const seen = new Map();
+        for (const quiver of args.quivers) {
+            const existing = seen.get(quiver.name);
+            if (existing !== undefined) {
+                throw new QuiverError("quiver_collision", `Two quivers share the name "${quiver.name}": first quiver and a later quiver both declare this name. ` +
+                    `Quiver names must be unique within a registry.`, { quiverName: quiver.name });
+            }
+            seen.set(quiver.name, quiver.name);
+        }
+        this.#quivers = Object.freeze([...args.quivers]);
+    }
+    /**
+     * 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
+     */
+    async resolve(ref) {
+        // Throws invalid_ref on malformed input.
+        const parsed = parseQuillRef(ref);
+        for (const quiver of this.#quivers) {
+            const versions = quiver.versionsOf(parsed.name);
+            if (versions.length === 0)
+                continue;
+            // Filter by selector if present; otherwise all versions are candidates.
+            const candidates = parsed.selector === undefined
+                ? versions
+                : versions.filter((v) => matchesSemverSelector(v, parsed.selector));
+            if (candidates.length === 0)
+                continue;
+            // First quiver with any candidate wins — pick highest within that quiver.
+            const winner = chooseHighestVersion(candidates);
+            // chooseHighestVersion returns null only for empty arrays; candidates is non-empty.
+            return `${parsed.name}@${winner}`;
+        }
+        throw new QuiverError("quill_not_found", `No quill found for ref "${ref}" in any registered quiver.`, { ref });
+    }
+    /**
+     * 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)
+     */
+    async getQuill(canonicalRef) {
+        let entry = this.#cache.get(canonicalRef);
+        if (entry === undefined) {
+            entry = this.#loadQuill(canonicalRef).catch((err) => {
+                this.#cache.delete(canonicalRef);
+                throw err;
+            });
+            this.#cache.set(canonicalRef, entry);
+        }
+        return entry;
+    }
+    /** Internal: does the actual loading work for getQuill. */
+    async #loadQuill(canonicalRef) {
+        // Parse and validate canonical form (must be x.y.z).
+        const parsed = parseQuillRef(canonicalRef);
+        if (parsed.selectorDepth !== 3) {
+            throw new QuiverError("invalid_ref", `getQuill requires a canonical ref (x.y.z) but received "${canonicalRef}". ` +
+                `Use resolve() first to obtain a canonical ref.`, { ref: canonicalRef });
+        }
+        const version = parsed.selector;
+        // Find the first quiver that owns this exact (name, version) pair.
+        const owningQuiver = this.#quivers.find((q) => q.versionsOf(parsed.name).includes(version));
+        if (owningQuiver === undefined) {
+            throw new QuiverError("quill_not_found", `Quill "${canonicalRef}" was not found in any registered quiver.`, { ref: canonicalRef, version });
+        }
+        // Load the file tree — I/O errors propagate as-is.
+        const tree = await owningQuiver.loadTree(parsed.name, version);
+        // Materialize the Quill via the engine.
+        // Engine errors propagate unchanged — they are not QuiverErrors and we
+        // should not mask them. The caller's error-handling stack will see the
+        // engine's own error type directly.
+        const quill = this.#engine.quill(tree);
+        return quill;
+    }
+    /**
+     * 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).
+     */
+    async warm() {
+        const promises = [];
+        for (const quiver of this.#quivers) {
+            for (const name of quiver.quillNames()) {
+                for (const version of quiver.versionsOf(name)) {
+                    promises.push(this.getQuill(`${name}@${version}`));
+                }
+            }
+        }
+        await Promise.all(promises);
+    }
+}

package/dist/semver.d.ts

@@ -0,0 +1,8 @@
+/** Returns true for exactly `x.y.z` with non-negative integer parts. */
+export declare function isCanonicalSemver(version: string): boolean;
+/** Returns true if `version` (canonical) matches `selector` (partial). */
+export declare function matchesSemverSelector(version: string, selector: string): boolean;
+/** Compares two canonical semver strings. Returns <0, 0, or >0. */
+export declare function compareSemver(a: string, b: string): number;
+/** Returns the highest version string, or null if empty. */
+export declare function chooseHighestVersion(versions: string[]): string | null;

package/dist/semver.js

@@ -0,0 +1,44 @@
+/** Returns true for exactly `x.y.z` with non-negative integer parts. */
+export function isCanonicalSemver(version) {
+    return /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(version);
+}
+/** Returns true if `version` (canonical) matches `selector` (partial). */
+export function matchesSemverSelector(version, selector) {
+    if (selector === version)
+        return true;
+    const selectorParts = selector.split(".");
+    const versionParts = version.split(".");
+    if (selectorParts.length === 0 ||
+        selectorParts.length > 3 ||
+        selectorParts.some((p) => p.length === 0 || Number.isNaN(Number(p)))) {
+        return false;
+    }
+    if (selectorParts.length > versionParts.length)
+        return false;
+    for (let i = 0; i < selectorParts.length; i++) {
+        if (selectorParts[i] !== versionParts[i])
+            return false;
+    }
+    return true;
+}
+/** Compares two canonical semver strings. Returns <0, 0, or >0. */
+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;
+    }
+    return 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

@@ -0,0 +1,42 @@
+/**
+ * Internal filesystem scanner for Source Quiver layout.
+ *
+ * Uses Node.js `fs/promises` — this module must only be imported from
+ * Node-only contexts (fromSourceDir, etc.).
+ */
+import type { QuiverMeta } from "./quiver-yaml.js";
+import type { QuiverLoader } from "./quiver.js";
+/**
+ * Scans a Source Quiver root directory.
+ *
+ * Reads `<rootDir>/Quiver.yaml`, then walks `<rootDir>/quills/<name>/<version>/`
+ * to build a catalog of quill names → sorted versions (descending).
+ *
+ * Throws:
+ *   - `quiver_invalid` if Quiver.yaml is missing/invalid, 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.).
+ *
+ * Missing `quills/` directory is NOT an error — the quiver is valid but empty.
+ */
+export declare function scanSourceQuiver(rootDir: string): Promise<{
+    meta: QuiverMeta;
+    catalog: Map<string, string[]>;
+}>;
+/**
+ * Recursively reads all files under a quill version directory into a Map.
+ *
+ * Keys are relative POSIX paths (forward slashes, no leading slash).
+ * Throws `transport_error` on I/O failure.
+ */
+export declare function readQuillTree(quillDir: string): Promise<Map<string, Uint8Array>>;
+/**
+ * Source-backed QuiverLoader: loads file trees from a Source Quiver on disk.
+ * The outer Quiver.loadTree already validates name/version against the catalog,
+ * so this loader trusts the gate and goes straight to reading files.
+ */
+export declare class SourceLoader implements QuiverLoader {
+    private readonly rootDir;
+    constructor(rootDir: string);
+    loadTree(name: string, version: string): Promise<Map<string, Uint8Array>>;
+}

package/dist/source-loader.js

@@ -0,0 +1,179 @@
+/**
+ * Internal filesystem scanner for Source Quiver layout.
+ *
+ * Uses Node.js `fs/promises` — this module must only be imported from
+ * Node-only contexts (fromSourceDir, etc.).
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { QuiverError } from "./errors.js";
+import { parseQuiverYaml } from "./quiver-yaml.js";
+import { isCanonicalSemver, compareSemver } from "./semver.js";
+/**
+ * Scans a Source Quiver root directory.
+ *
+ * Reads `<rootDir>/Quiver.yaml`, then walks `<rootDir>/quills/<name>/<version>/`
+ * to build a catalog of quill names → sorted versions (descending).
+ *
+ * Throws:
+ *   - `quiver_invalid` if Quiver.yaml is missing/invalid, 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.).
+ *
+ * Missing `quills/` directory is NOT an error — the quiver is valid but empty.
+ */
+export async function scanSourceQuiver(rootDir) {
+    // --- Read Quiver.yaml ---
+    const quiverYamlPath = join(rootDir, "Quiver.yaml");
+    let raw;
+    try {
+        raw = await readFile(quiverYamlPath);
+    }
+    catch (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.
+        // (Contrast: missing Quill.yaml inside a version dir is quiver_invalid —
+        // the version dir exists but lacks its required sentinel file.)
+        const code = err.code;
+        if (code === "ENOENT") {
+            throw new QuiverError("transport_error", `Source Quiver at "${rootDir}" is missing required "Quiver.yaml"`, { cause: err });
+        }
+        throw new QuiverError("transport_error", `Failed to read "Quiver.yaml" at "${quiverYamlPath}": ${err.message}`, { cause: err });
+    }
+    const meta = parseQuiverYaml(raw);
+    // --- Walk quills/ directory ---
+    const quillsDir = join(rootDir, "quills");
+    let quillNames;
+    try {
+        quillNames = await readdir(quillsDir);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            // Missing quills/ is fine — empty catalog
+            return { meta, catalog: new Map() };
+        }
+        throw new QuiverError("transport_error", `Failed to read "quills/" directory at "${quillsDir}": ${err.message}`, { cause: err });
+    }
+    const catalog = new Map();
+    for (const quillName of quillNames) {
+        const quillNameDir = join(quillsDir, quillName);
+        // Ensure it's a directory
+        let st;
+        try {
+            st = await stat(quillNameDir);
+        }
+        catch (err) {
+            throw new QuiverError("transport_error", `Failed to stat "${quillNameDir}": ${err.message}`, { cause: err });
+        }
+        if (!st.isDirectory())
+            continue;
+        // Read version directories
+        let versionDirs;
+        try {
+            versionDirs = await readdir(quillNameDir);
+        }
+        catch (err) {
+            throw new QuiverError("transport_error", `Failed to read versions for quill "${quillName}": ${err.message}`, { cause: err });
+        }
+        const versions = [];
+        for (const versionDir of versionDirs) {
+            const versionPath = join(quillNameDir, versionDir);
+            // Ensure it's a directory
+            let vst;
+            try {
+                vst = await stat(versionPath);
+            }
+            catch (err) {
+                throw new QuiverError("transport_error", `Failed to stat "${versionPath}": ${err.message}`, { cause: err });
+            }
+            if (!vst.isDirectory())
+                continue;
+            // Non-canonical version → quiver_invalid
+            if (!isCanonicalSemver(versionDir)) {
+                throw new QuiverError("quiver_invalid", `Quill "${quillName}" has non-canonical version directory "${versionDir}" — only x.y.z format is allowed`, { quiverName: meta.name, version: versionDir });
+            }
+            // Require Quill.yaml sentinel inside the version dir
+            const quillYamlPath = join(versionPath, "Quill.yaml");
+            try {
+                await stat(quillYamlPath);
+            }
+            catch (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 });
+                }
+                throw new QuiverError("transport_error", `Failed to stat "Quill.yaml" at "${quillYamlPath}": ${err.message}`, { cause: err });
+            }
+            versions.push(versionDir);
+        }
+        if (versions.length > 0) {
+            // Sort descending
+            versions.sort((a, b) => compareSemver(b, a));
+            catalog.set(quillName, versions);
+        }
+    }
+    return { meta, catalog };
+}
+/**
+ * Recursively reads all files under a quill version directory into a Map.
+ *
+ * Keys are relative POSIX paths (forward slashes, no leading slash).
+ * Throws `transport_error` on I/O failure.
+ */
+export async function readQuillTree(quillDir) {
+    const tree = new Map();
+    await walkDir(quillDir, quillDir, tree);
+    return tree;
+}
+async function walkDir(baseDir, currentDir, tree) {
+    let entries;
+    try {
+        entries = await readdir(currentDir);
+    }
+    catch (err) {
+        throw new QuiverError("transport_error", `Failed to read directory "${currentDir}": ${err.message}`, { cause: err });
+    }
+    for (const entry of entries) {
+        const fullPath = join(currentDir, entry);
+        let st;
+        try {
+            st = await stat(fullPath);
+        }
+        catch (err) {
+            throw new QuiverError("transport_error", `Failed to stat "${fullPath}": ${err.message}`, { cause: err });
+        }
+        if (st.isDirectory()) {
+            await walkDir(baseDir, fullPath, tree);
+        }
+        else {
+            // Compute relative POSIX path
+            const rel = relative(baseDir, fullPath);
+            const posixRel = sep === "/" ? rel : rel.split(sep).join("/");
+            let bytes;
+            try {
+                bytes = await readFile(fullPath);
+            }
+            catch (err) {
+                throw new QuiverError("transport_error", `Failed to read file "${fullPath}": ${err.message}`, { cause: err });
+            }
+            tree.set(posixRel, bytes);
+        }
+    }
+}
+/**
+ * Source-backed QuiverLoader: loads file trees from a Source Quiver on disk.
+ * The outer Quiver.loadTree already validates name/version against the catalog,
+ * so this loader trusts the gate and goes straight to reading files.
+ */
+export class SourceLoader {
+    rootDir;
+    constructor(rootDir) {
+        this.rootDir = rootDir;
+    }
+    async loadTree(name, version) {
+        const quillDir = join(this.rootDir, "quills", name, version);
+        return readQuillTree(quillDir);
+    }
+}