skills/docs/api-stack/api/api-loader/README.md

@suaveplan/api-loader — contract package for the Suaveplan API plugin system. Owns the abstract ModuleResolver interface, the RollbackJournal ring-buffer contract (with a reference in-memory implementation), the canonical cache-bust algorithm (bustSpecifier), the persisted-entry Zod schema, the native-binding-detector contract, the LOADER.* error-code registry, and the runLoaderConformance / runRollbackJournalConformance harnesses. Concrete resolver and journal implementations .

Stage-1 contract package for the Suaveplan API plugin system.

This package owns the abstract types, algorithms, and conformance harnesses the host (@suaveplan/api-host, Stage 2) implements. It carries no file-watching, no admin-API wiring, and no concrete ModuleResolver implementation — those land in the host. Keeping the contracts here makes the loader testable in isolation, lets adapter packages depend on the contract without pulling in the host runtime, and prevents the circular dependency that would otherwise form between the host and its plugins.

Documentation tree

• cache-bust — Compute the cache-busted ESM specifier used by the API plugin host during a hot reload. Bun's ESM cache is keyed on the…
  • cache-bust — Compute the cache-busted ESM specifier used by the API plugin host during a hot reload. Bun's ESM cache is keyed on the…
• error-codes — Stable, frozen registry of every LOADER.* error code surfaced by the plugin-loader contract. Downstream consumers (`@…
  • error-codes — Stable, frozen registry of every LOADER.* error code surfaced by the plugin-loader contract. Downstream consumers (`@…
• journal-entry — Zod schema covering the persisted subset of a RollbackJournalEntry. The full entry (defined in `@suaveplan/api-ty…
  • journal-entry — Zod schema covering the persisted subset of a RollbackJournalEntry. The full entry (defined in `@suaveplan/api-ty…
• native-binding-detector — Hot reload is the heart of the API plugin system, but it has one non-negotiable boundary: native bindings (.node…
  • native-binding-detector — Hot reload is the heart of the API plugin system, but it has one non-negotiable boundary: native bindings (.node…
• resolver — ModuleResolver is the API plugin host's abstraction over import(). It imports a plugin entry under a cache-busted E…
  • resolver — ModuleResolver is the API plugin host's abstraction over import(). It imports a plugin entry under a cache-busted E…
• rollback-journal — RollbackJournal is the per-plugin bounded ring buffer the API plugin host uses to retain the last N known-good module…
  • rollback-journal — RollbackJournal is the per-plugin bounded ring buffer the API plugin host uses to retain the last N known-good module…
• testing — Reusable conformance harnesses for downstream packages that ship concrete implementations of the loader's `ModuleResolv…
  • loader-conformance — Reusable conformance harnesses for downstream packages that ship concrete implementations of the loader's `ModuleResolv…

Modules

• cache-bust — bustSpecifier(url, version) pure helper that produces the cache-busted ESM specifier the host uses on every reload (design §8.2).
• error-codes — LOADER_CODES registry: NATIVE_BINDING_HELD, MODULE_IMPORT_FAILED, JOURNAL_FULL, JOURNAL_ENTRY_INVALID.
• journal-entry — Zod schema for the persisted subset of a RollbackJournalEntry (the fields that survive host restart).
• native-binding-detector — NativeBindingDetector function type and assertNoNativeBindings helper that throws LOADER.NATIVE_BINDING_HELD when a plugin's import subgraph contains .node files.
• resolver — types-only ModuleResolver contract.
• rollback-journal — the RollbackJournal interface plus the reference in-memory createRollbackJournal(depth) implementation (default depth 3).
• testing — runLoaderConformance and runRollbackJournalConformance reusable harnesses.

Subpath exports

import { bustSpecifier } from "@suaveplan/api-loader/cache-bust";
import { LOADER_CODES } from "@suaveplan/api-loader/error-codes";
import { rollbackJournalEntryPersistedSchema } from "@suaveplan/api-loader/journal-entry";
import { assertNoNativeBindings } from "@suaveplan/api-loader/native-binding-detector";
import type { ModuleResolver } from "@suaveplan/api-loader/resolver";
import { createRollbackJournal } from "@suaveplan/api-loader/rollback-journal";
import { runLoaderConformance } from "@suaveplan/api-loader/testing";

Design intent

Source: docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md, sections 8 (Hot reload), 8.1a (RollbackJournal), 8.2 (cache busting).

Status

• Version: 0.1.0
• Wave: Stage 1 (Contracts)
• Consumers: @suaveplan/api-host (Stage 2) implements the contracts here.