@quillmark/quiver 0.2.0 → 0.4.0

package/PROGRAM.md

@@ -18,28 +18,43 @@ This means Quiver must own quill selection and lifecycle entirely. There is no e
 
 ## Core Decisions
 
-### 1) Quiver Shapes and Transports Are Orthogonal
-
-Two on-disk/data shapes:
-
-- **Source Quiver** (authoring shape)
-  - Human-authored, git-friendly
-  - Root `Quiver.yaml`
-  - Quills under `quills/<name>/<version>/Quill.yaml`
-  - Assets in normal source layout
-- **Packed Quiver** (distribution/runtime artifact)
-  - Hashed manifest
-  - Bundle zips
-  - Dehydrated shared font store (`store/<md5>`)
-  - Stable pointer file to current hashed manifest
-
-Transport is a separate axis for **Packed Quiver** loading:
-
-- `http` (browser/runtime delivery)
-- `fs` (packed artifact loaded from local disk)
-- future transports can be added without changing packed format
-
-**Naming decision:** use `pack()` (format operation), not transport-specific names.
+### 1) One Authored Shape; A Build Output Derived From It
+
+There is one user-facing shape: the **Source Quiver**.
+
+- Human-authored, git-friendly
+- Root `Quiver.yaml`
+- Quills under `quills/<name>/<version>/Quill.yaml`
+- Assets in normal source layout
+
+A build step (`Quiver.build`) derives a **runtime artifact** from the source.
+This artifact is not a peer "format" — it is the source layout's `dist/`
+output, optimized for browser delivery (hashed manifest, per-quill bundle
+zips, dehydrated shared font store, stable pointer file). Authors do not
+version it, publish it, or check it into git.
+
+Loaders are paired 1:1 with what they load:
+
+- `Quiver.fromPackage(specifier)` and `Quiver.fromDir(path)` load the
+  **source** layout (Node only).
+- `Quiver.fromBuilt(url)` loads the **build output** over HTTP/HTTPS
+  (browser-safe; works in Node too).
+
+There is no auto-detection: each loader's name commits to what it expects.
+
+**Naming decisions:**
+- The verb is `build()`. Pairs with `fromBuilt()` (past participle = "the
+  built one"). Avoids collision with `npm pack`, JS bundler vocabulary,
+  and the internal "bundle zips" term.
+- Loaders for source layouts are named by **where the source lives**
+  (`Package` / `Dir`). The loader for build output is named by **what it
+  loads** (`Built`), not by transport — `fromUrl` was rejected because it
+  hides the artifact type.
+- Build output is HTTP-served only. Loading a built artifact from local
+  disk is intentionally unsupported in V1; consumers either spin up a
+  local HTTP server or use `fromPackage`/`fromDir` against the source.
+  Adding `Quiver.fromBuiltDir(path)` later is purely additive if a real
+  use case appears.
 
 ### 2) `Quiver.yaml` Is Required in Source Quivers
 
@@ -57,32 +72,26 @@ Unknown fields in `Quiver.yaml` are a **validation error** (`quiver_invalid`). S
 ### 3) `QuillSource` Becomes Quiver-Centric
 
 - Re-express `QuillSource` concepts around Quivers
-- Split old filesystem concept into:
-  - **Source filesystem loader** (reads Source Quiver directly)
-  - **Packed filesystem transport** (loads Packed Quiver artifact from disk)
-- Treat HTTP as a Packed transport, not a separate format concept
-
-### 4) Multi-Quiver Composition with Deterministic Precedence
-
-`QuiverRegistry` accepts multiple quivers with explicit order.
-
-This registry/composition layer lives entirely in `@quillmark/quiver`; it is not a Quillmark engine feature.
-
-Precedence rule:
-
-- **Precedence is a hard filter**
-- Scan quivers in order
-- First quiver with any matching candidate wins
-- Choose highest matching version **within that quiver**
-
-Applies to:
-
-- unqualified refs (e.g. `usaf_memo`)
-- selector refs (e.g. `usaf_memo@1.2`)
-
-No global highest-across-all-quivers behavior.
-
-**Identity collision:** duplicate `Quiver.yaml.name` across composed quivers is an error in V1.
+- Three loaders, each with one input shape and one shape-of-thing-loaded:
+  - `Quiver.fromPackage(specifier)` — Node-only; resolves an npm specifier
+    against `node_modules` and loads the source layout at the package root
+  - `Quiver.fromDir(path)` — Node-only; loads source layout from a local
+    directory. Also accepts `import.meta.url`-style `file://` URLs as a
+    convenience for tests (the URL's parent directory is used)
+  - `Quiver.fromBuilt(url)` — browser-safe; loads build output from an
+    `http(s)://` or origin-relative URL
+- "Transport" is not a first-class concept; HTTP fetching is an internal
+  detail of `fromBuilt`
+
+### 4) Single-Quiver Scope (V1)
+
+V1 has no multi-quiver composition layer. Each `Quiver` instance is
+independent: consumers load one quiver and call `resolve` / `getQuill` /
+`warm` directly on it. There is no `QuiverRegistry`.
+
+If composition becomes a real use case, the additive path is a thin
+`Quiver.compose([a, b, ...])` factory that returns a quiver-shaped
+composite — it is intentionally out of scope for V1.
 
 ### 5) Semver Selector Rules Are Strict and Small
 
@@ -108,17 +117,35 @@ Canonical version format:
 
 Canonicalization:
 
-- resolve selector to canonical ref once per manifest snapshot
-- key internal caches by canonical ref
+- resolve selector to canonical ref once per call to `getQuill`
+- key the tree cache by canonical ref; key the quill cache by (engine, canonical-ref)
 
 ### 6) Warm/Prefetch Is Purely a Quiver Concern
 
-`warm()` remains a quiver-layer optimization:
+`warm()` is the network prefetch step. It fetches every quill's tree and
+populates the per-quiver tree cache. It does **not** materialize Quill
+instances and does **not** require an engine — `engine.quill(tree)` is
+microseconds and runs lazily inside `getQuill`. A subsequent `getQuill`
+reuses the cached tree, so the network fetch isn't paid twice.
+
+Tree cache lifecycle:
 
-- `warm()` warms all by default in V1
-- `resolve()` must work even if nothing is warmed
+- `warm()` populates the tree cache.
+- First `getQuill(ref, { engine })` reads the tree, materializes the
+  Quill via `engine.quill(tree)`, then evicts the tree so its bytes can
+  be GC'd. The materialized Quill is what's kept (per engine).
+- If `engine.quill` throws, the tree is retained so a retry skips the
+  network.
+- Repeated `getQuill` on the same engine hits the per-engine quill cache
+  — no tree access at all.
+- A subsequent `getQuill` for a different engine refetches the tree
+  (single-engine apps never pay this cost).
 
-Warm now means "load/prepare quills and artifacts", not "register in engine". There is no engine registration step anymore.
+Other invariants:
+
+- `resolve()` works whether or not anything is warmed.
+- Warm semantics are identical for source-loaded and built-output-loaded
+  quivers; the loader hides the difference.
 
 ### 7) Engine Boundary: New Canonical Contract (Node / JS–WASM only)
 
@@ -140,7 +167,7 @@ For advanced dynamic-asset behavior, defer to Quillmark’s JS/WASM docs; the de
 ### 8) Markdown and Ref Parsing Boundary
 
 - Markdown parsing does not require a quill registry: `Document.fromMarkdown(markdown)`
-- Quiver owns ref parsing and selector resolution for its own API (`resolve`, `warm`, validation)
+- Quiver owns ref parsing and selector resolution for its own API (`resolve`, `getQuill`, `warm`, validation)
 - QUILL field is informational at render time; Quiver routes to the intended quill explicitly without mutating the parsed document in V1
 
 Upstream behavior note:
@@ -150,16 +177,41 @@ Upstream behavior note:
 
 ### 9) Distribution Strategy
 
-V1 supports:
-
-- npm distribution for Source Quiver projects
-- git/folder-copy consumption of Source Quivers
-- `pack()` output for Packed runtime distribution
-
-Clarification:
-
-- npm/git are developer distribution channels
-- packed artifacts are runtime delivery artifacts
+**Source-first distribution.** The published artifact is the **Source
+Quiver** — an npm package whose root contains `Quiver.yaml`. Consumers
+choose how to consume it:
+
+- **Node consumers** load the source layout directly:
+  ```ts
+  const quiver = await Quiver.fromPackage("@org/my-quiver");
+  ```
+- **Browser consumers** run a build step against the resolved source dir
+  and serve the output as static assets:
+  ```ts
+  // build step (Node)
+  await Quiver.build("./node_modules/@org/my-quiver", "./public/quivers/my-quiver");
+  // browser runtime
+  const quiver = await Quiver.fromBuilt("/quivers/my-quiver/");
+  ```
+
+Rationale:
+
+- Author release pipeline is `npm publish` (or `git tag`). No second
+  artifact, no CDN, no hash bookkeeping outside the npm tarball.
+- Deployment topology is the consumer's concern, not the author's.
+- The runtime artifact is a build output of the source, not a peer
+  distribution shape (see §1).
+
+**Pre-built distribution as a published artifact is supported but not
+the default.** Authors who need to ship runtime-ready output directly
+(e.g. their consumers cannot run a Node build step) may publish
+`Quiver.build(...)` output to a CDN and instruct consumers to use
+`Quiver.fromBuilt(<cdn-url>)`. Treated as the exception.
+
+Validation responsibility shifts left: authors should run
+`Quiver.fromDir` and `Quiver.build` in CI so `quiver_invalid` errors
+surface on publish, not on the consumer's build. The bundled
+`@quillmark/quiver/testing` harness covers this.
 
 ---
 
@@ -167,19 +219,20 @@ Clarification:
 
 V1 intentionally retains:
 
-1. Font dehydration as a Packed Quiver property
-2. Consumer validation tooling for Source Quivers (+ optional Packed parity checks)
-3. Manifest pointer resolution for Packed format
-4. HTTP loading as a Packed transport
-5. Source filesystem loading as first-class dev loop
-6. Packed filesystem loading as first-class runtime option
-7. Typed errors (`QuiverError`) with quiver/transport context
-8. Concurrency coalescing for in-flight loads
-9. Preload/fail-fast helpers where they still add value
+1. Font dehydration as a build-output property
+2. Consumer validation tooling for source layouts (+ optional build-parity checks)
+3. Manifest pointer resolution for build output
+4. HTTP/HTTPS loading via `Quiver.fromBuilt`
+5. Source layout loading as first-class dev loop (`fromPackage` / `fromDir`)
+6. Typed errors (`QuiverError`) with quiver/source context
+7. Concurrency coalescing for in-flight loads
+8. Preload/fail-fast helpers where they still add value
 
 Removed from carryover assumptions:
 
 - Any engine-registration cache fast path (`register`/`has`) because upstream removed the capability
+- "Transport" as a user-facing concept (folded into `fromBuilt` internals)
+- Loading build output from local disk (no `fromBuiltDir` in V1; YAGNI)
 
 ---
 
@@ -188,7 +241,7 @@ Removed from carryover assumptions:
 V1 should trim public API where behavior can stay internal:
 
 - Drop internal-only utility exports
-- Keep engine payload and transport internals opaque
+- Keep engine payload and loader internals opaque
 - Consolidate validation exports
 - Avoid duplicate entry points for equivalent validation workflows
 - Do not expose internal quill-object cache mechanisms as public contract
@@ -204,13 +257,12 @@ V1 code catalog (closed set):
 | Code | Fires when |
 |---|---|
 | `invalid_ref` | Malformed ref string at `resolve()`/`warm()` boundary (fails `parseQuillRef`) |
-| `quill_not_found` | Selector did not match any quill in any composed quiver |
+| `quill_not_found` | Selector did not match any quill in the quiver |
 | `quiver_invalid` | `Quiver.yaml` or hashed manifest malformed, unknown field, non-canonical version on disk, or font/bundle hash mismatch |
 | `transport_error` | I/O failure: missing path, HTTP non-2xx, network error, permission error. Wraps underlying cause. |
-| `quiver_collision` | Two composed quivers share `Quiver.yaml.name` at registry construction |
 
 Notes:
-- `quill_not_found` is selector-resolution failure after quiver composition and precedence.
+- `quill_not_found` is selector-resolution failure within a quiver's catalog.
 - `transport_error` is artifact access failure (filesystem/HTTP/network/permissions), including missing packed files and HTTP 404.
 - Legacy categories such as `manifest_invalid`, `quill_load_failed`, and `backend_not_found` are folded into `quiver_invalid` or `transport_error` in V1.
 
@@ -218,18 +270,22 @@ Errors must include offending ref/version/quiver identifiers when available.
 
 ---
 
-## Runtime + Packaging Model
+## Runtime + Build Model
 
 V1 runtime loading paths:
 
-1. Source Quiver from filesystem (authoring/dev)
-2. Packed Quiver over HTTP (browser/runtime)
-3. Packed Quiver from filesystem (air-gapped/container/runtime)
+1. `Quiver.fromPackage(specifier)` — npm package resolution; loads source
+   (authoring/dev/Node runtime)
+2. `Quiver.fromDir(path)` — local directory; loads source (Node)
+3. `Quiver.fromBuilt(url)` — HTTP(S); loads build output (browser; also
+   works in Node)
 
-V1 packaging behavior:
+V1 build behavior:
 
-- `Quiver.pack()` produces Packed Quiver artifact independent of transport
-- packed output includes pointer + hashed manifest + bundles + dehydrated font store
+- `Quiver.build(srcDir, outDir)` produces the runtime artifact from a
+  source layout
+- output includes pointer + hashed manifest + bundles + dehydrated font store
+  (see "Runtime Artifact Format" below)
 
 Execution behavior:
 
@@ -261,7 +317,11 @@ Caching scope:
 - Non-canonical version directories are a validation error (`quiver_invalid`).
 - Dedup of identical fonts across quills happens at pack time (into `store/<md5>`), not at the source layer.
 
-## Packed Quiver Format (normative)
+## Runtime Artifact Format (normative)
+
+Produced by `Quiver.build()`. Authors do not author this layout; consumers
+do not need to inspect it. It is an implementation detail of build output,
+specified here only because loaders must agree on its shape.
 
 ```
 <root>/
@@ -272,7 +332,7 @@ Caching scope:
     <md5>                                  # raw font bytes, no extension
 ```
 
-**Hash:** MD5 prefix-6, computed with `node:crypto` at `pack()` time only (dev/tooling; not browser runtime).
+**Hash:** MD5 prefix-6, computed with `node:crypto` at `build()` time only (dev/tooling; not browser runtime).
 
 **Pointer** `Quiver.json`:
 ```json
@@ -295,63 +355,71 @@ Caching scope:
 }
 ```
 
-**Bundle zips** contain pure quill content (`Quill.yaml` + templates + partials + non-font assets). Fonts are dehydrated at pack time: their bytes live only in `store/<md5>`; their path→hash mapping lives only in the hashed manifest. Bundles do **not** embed a `fonts.json`.
+**Bundle zips** contain pure quill content (`Quill.yaml` + templates + partials + non-font assets). Fonts are dehydrated at build time: their bytes live only in `store/<md5>`; their path→hash mapping lives only in the hashed manifest. Bundles do **not** embed a `fonts.json`.
 
-Rehydration on load: transport fetches the pointer → hashed manifest → required bundle(s) → required `store/<md5>` blobs; library reconstructs the full in-memory tree and builds a render-ready quill via `engine.quill(tree)`.
+Rehydration on load: the loader fetches the pointer → hashed manifest → required bundle(s) → required `store/<md5>` blobs; library reconstructs the full in-memory tree and builds a render-ready quill via `engine.quill(tree)`.
 
 ## API Surface (V1)
 
-Single class, three factories:
+Single class, three loaders + one builder. Each loader has one input
+shape and one shape-of-thing-loaded; no auto-detection.
 
 ```ts
 class Quiver {
-  // Node-only factories (from `@quillmark/quiver/node`). Fail fast in browser.
-  static fromSourceDir(path: string): Promise<Quiver>;
-  static fromPackedDir(path: string): Promise<Quiver>;
-  // Browser-safe factory (from `@quillmark/quiver` main).
-  static fromHttp(url: string): Promise<Quiver>;
-  // Node-only tooling. Writes a Packed Quiver to outDir.
-  static pack(sourceDir: string, outDir: string, opts?: PackOptions): Promise<void>;
+  // Node-only loader: resolve an npm specifier against node_modules and
+  // load the source layout at the package root.
+  // (From `@quillmark/quiver/node`.)
+  static fromPackage(specifier: string): Promise<Quiver>;
+
+  // Node-only loader: load source layout from a local directory.
+  // Also accepts `import.meta.url`-style `file://` URLs (the URL's parent
+  // directory is used) as a convenience for tests.
+  // (From `@quillmark/quiver/node`.)
+  static fromDir(pathOrFileUrl: string): Promise<Quiver>;
+
+  // Browser-safe loader: load build output from an http(s):// or
+  // origin-relative URL. Throws `transport_error` on file:// inputs.
+  // (From `@quillmark/quiver` main.)
+  static fromBuilt(url: string): Promise<Quiver>;
+
+  // Node-only tooling: produce the runtime artifact from a source layout.
+  // (From `@quillmark/quiver/node`.)
+  static build(sourceDir: string, outDir: string, opts?: BuildOptions): Promise<void>;
 
   readonly name: string; // from Quiver.yaml
 
-  // Read-only introspection and lazy tree access used by QuiverRegistry
-  // internally; also available for external debugging and tooling.
+  // Read-only introspection and lazy tree access; also used internally by
+  // resolve/getQuill/warm.
   quillNames(): string[];                                              // sorted lex
   versionsOf(name: string): string[];                                  // sorted desc
   loadTree(name: string, version: string): Promise<Map<string, Uint8Array>>;
-}
-```
-
-```ts
-class QuiverRegistry {
-  constructor(args: { engine: Quillmark; quivers: Quiver[] });
 
   // Selector ref -> canonical ref. Throws invalid_ref / quill_not_found.
   resolve(ref: string): Promise<string>;
 
-  // Canonical ref -> render-ready quill handle (materialized via engine.quill(tree), cached in-process).
-  getQuill(canonicalRef: string): Promise<Quill>;
+  // Selector or canonical ref -> render-ready quill handle (materialized via
+  // engine.quill(tree), cached per (engine, canonical-ref)).
+  getQuill(ref: string, opts: { engine: Quillmark }): Promise<Quill>;
 
-  // Warms every ref in every composed quiver. Fail-fast. Zero params in V1.
+  // Prefetches every quill tree (network-only; engine not required).
+  // Subsequent getQuill calls reuse the cached tree. Fail-fast.
   warm(): Promise<void>;
 }
 
 class QuiverError extends Error {
-  code: "invalid_ref" | "quill_not_found" | "quiver_invalid" | "transport_error" | "quiver_collision";
+  code: "invalid_ref" | "quill_not_found" | "quiver_invalid" | "transport_error";
   // plus contextual payload fields
 }
 ```
 
-**No render wrapper.** Callers invoke `quill.render(doc, opts?)` (and `quill.open(doc)` when needed) after `resolve()` + `getQuill()`. Quiver never mirrors Quillmark render APIs.
+**No render wrapper.** Callers invoke `quill.render(doc, opts?)` (and `quill.open(doc)` when needed) after `getQuill()`. Quiver never mirrors Quillmark render APIs.
 
-**Internal (not exported):** `QuiverTransport`, `QuiverManifest` (runtime shape), `parseQuillRef`, in-flight coalescing state.
+**Internal (not exported):** `QuiverManifest` (runtime shape), `parseQuillRef`, in-flight coalescing state, source-vs-built layout detection.
 
 Hot-path flow:
 ```ts
 const doc = Document.fromMarkdown(md);
-const canonicalRef = await registry.resolve(doc.quillRef);
-const quill = await registry.getQuill(canonicalRef);
+const quill = await quiver.getQuill(doc.quillRef, { engine });
 const result = quill.render(doc, { format: "pdf" });
 ```
 
@@ -360,13 +428,23 @@ const result = quill.render(doc, { format: "pdf" });
 **Name:** `@quillmark/quiver`
 
 **Entrypoints:**
-- `@quillmark/quiver` (main, browser-safe): `Quiver` class with only `fromHttp` functional (Node-only factories/pack throw `transport_error` if reached in browser), `QuiverRegistry`, `QuiverError`, shared types.
-- `@quillmark/quiver/node`: adds `Quiver.fromSourceDir`, `Quiver.fromPackedDir`, `Quiver.pack` behaviors. Single `Quiver` class — Node-only factories fail fast outside Node.
+- `@quillmark/quiver` (main, browser-safe): `Quiver` class with only
+  `fromBuilt` functional (Node-only loaders/builder throw
+  `transport_error` if reached in browser), `QuiverError`,
+  `QuillmarkLike`, `QuillLike`, shared types.
+- `@quillmark/quiver/node`: adds `Quiver.fromPackage`, `Quiver.fromDir`,
+  `Quiver.build` behaviors. Single `Quiver` class — Node-only factories
+  fail fast outside Node.
+- `@quillmark/quiver/testing` (Node-only): single export
+  `runQuiverTests(metaUrlOrDir, engine)` built on `node:test` (zero
+  external test-runner dependency). Optional convenience; users on other
+  test runners wire their own loops against the main API.
 
 **Dependencies:**
 - Peer: `@quillmark/wasm@>=0.59.0-rc.2` with `Quillmark`, `Document.fromMarkdown`, `engine.quill(tree)`, and `quill.render(doc, opts?)` APIs.
 - Runtime: `fflate ^0.8.2` for zip read/write (Node + browser)
-- Dev-only: `node:crypto` (MD5 hashing in `pack()` — never reached at runtime)
+- Dev-only: `node:crypto` (MD5 hashing in `build()` — never reached at runtime)
+- No test-runner peer dependency; `/testing` uses `node:test` (built-in)
 
 ---
 
@@ -380,7 +458,7 @@ const result = quill.render(doc, { format: "pdf" });
 - inter-quiver dependency graph in `Quiver.yaml`
 - marketplace/discovery service
 - advanced warm strategies beyond API-compatible hooks
-- multi-quiver name-collision soft handling (V1 errors on duplicate `Quiver.yaml.name`)
+- multi-quiver composition (single quiver per consumer in V1)
 
 ---
 
@@ -388,14 +466,14 @@ const result = quill.render(doc, { format: "pdf" });
 
 All V1 planner questions resolved; implementation plan can proceed against the spec above.
 
-1. ~~Final `Quiver` interface shape and transport factoring style~~ → Single `Quiver` class, three static factories (`fromHttp`, `fromSourceDir`, `fromPackedDir`). Transport kept internal (no `fromTransport` in V1; YAGNI).
+1. ~~Final `Quiver` interface shape and transport factoring style~~ → Single `Quiver` class, three loaders (`fromPackage`, `fromDir`, `fromBuilt`) + one builder (`build`). Each loader names what it loads; no auto-detection.
 2. ~~Final `Quiver.yaml` schema and unknown-field policy~~ → See §2: alphanumeric `name` and optional tooling-only `description`. Unknown fields are `quiver_invalid`.
 3. ~~Canonical ref grammar and parser API contract~~ → Internal `parseQuillRef`, not exported. Selector syntax per §5. Throws `invalid_ref`.
-4. ~~Exact warning policy for shadowed refs across quivers~~ → No warnings in V1. Precedence is a hard filter (§4); duplicate quiver names error as `quiver_collision`.
-5. ~~Validation API shape consolidation~~ → No separate validation API. Validation errors surface as `QuiverError('quiver_invalid')` during load or `pack()`.
-6. ~~Pack artifact directory structure~~ → See "Packed Quiver Format (normative)".
+4. ~~Exact warning policy for shadowed refs across quivers~~ → N/A in V1: no multi-quiver composition layer; each `Quiver` instance is independent (§4).
+5. ~~Validation API shape consolidation~~ → No separate validation API. Validation errors surface as `QuiverError('quiver_invalid')` during load or `build()`.
+6. ~~Build output directory structure~~ → See "Runtime Artifact Format (normative)".
 7. ~~Node/browser entrypoint split~~ → See "Package Structure": main + `/node` subpath, single `Quiver` class.
-8. ~~Final exported type names~~ → `Quiver`, `QuiverRegistry`, `QuiverError`. Hot-path entry is `QuiverRegistry.resolve(ref)` + `QuiverRegistry.getQuill(canonicalRef)`.
+8. ~~Final exported type names~~ → `Quiver`, `QuiverError`. Hot-path entry is `Quiver.getQuill(ref, { engine })`.
 
 ---
 
@@ -413,7 +491,8 @@ Local copies in this repo for `@quillmark/quiver` implementation:
 ## Success Criteria
 
 - A team can author and validate a Source Quiver locally with fast filesystem loops
-- A packed artifact can be loaded via HTTP or local filesystem with equivalent semantics
+- Build output can be loaded over HTTP/HTTPS with parity behavior in browser and Node
+- Each loader names exactly what it loads — no auto-detection, no ambiguous return shape
 - Multi-quiver resolution is deterministic and matches precedence hard-filter rules
 - Selector behavior is predictable and explicitly documented
 - Quiver (Node) integrates via `engine.quill(tree)` + `quill.render(...)` only (no engine quill registration path)