@hoardodile/host 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,788 @@
+import { PluginManifestId, PluginManifest, PluginDefinition, PluginDownloadRequest, PluginDownloadResult, PluginAssetDeleteResult, PluginPermissions, PluginSchema, ResourceAPI, ProbeResult, HookName, ImageHashKind, Detection, SerializedFileList, ImageHashesResult } from '@hoardodile/sdk-types';
+export { AudioCoverArt, AudioInfo, AudioTags, Detection, HOOK_NAMES, HookName, ImageInfo, Logger, PluginDefinition, ReadFileRange, ResourceAPI, ResourceAPIFixtureConfig, VideoInfo, assertPluginShape, createFailingPlugin, createResourceAPIFixture, definePlugin, isDetected, isMissed, stubLogger } from '@hoardodile/sdk-types';
+import { Readable } from 'node:stream';
+import { I as ImageMetadataInput, b as ImageSourceProbe, A as AvProbeOptions, E as ExtractProgress } from './image-Dx2Be3Bj.js';
+import { R as ResourceContainer } from './container-fKxefO7p.js';
+import { P as PluginProbeCache } from './probe-cache-BkRI7HEK.js';
+export { a as PLUGIN_PROBE_CACHE_MAX_ENTRIES, c as createProbeCache } from './probe-cache-BkRI7HEK.js';
+import { PluginCapabilityKey } from '@hoardodile/sdk-types/plugin-capabilities';
+import 'sharp';
+
+/**
+ * Process-wide cache of nested container listings (central directories
+ * of zip/tar entries addressed via virtual paths). Resolving
+ * `outer!inner` re-parses the outer archive's CD on every hook call;
+ * this cache keeps the parsed listing resident so a multi-hook pass
+ * (sourceMeta → cover → hashes → listFiles) parses each nested archive
+ * once.
+ *
+ * Keyed by the outer entry name only — callers scope the cache instance
+ * to a fixed (resId, fileVersion), and archives are immutable per
+ * version, so a key never outlives its content.
+ */
+type NestedCdCache = {
+    readonly get: (key: string) => Promise<unknown> | undefined;
+    readonly set: (key: string, value: Promise<unknown>) => void;
+    readonly clear: () => void;
+};
+type NestedCdCacheOptions = {
+    /** Max number of nested archives kept resident. */
+    readonly maxEntries: number;
+};
+/** Create an LRU-bounded nested listing cache. */
+declare function createNestedCdCache(opts?: Partial<NestedCdCacheOptions>): NestedCdCache;
+
+/**
+ * Central directory entry shape exposed for the read-path cache. Mirrors
+ * the fields yauzl surfaces, plus `dataOffset` resolved from the local
+ * header. `dataOffset` and `dataSize` together pinpoint the entry's raw
+ * bytes inside the zip file; for STORED entries those bytes are the file
+ * itself and can be streamed via {@link streamRange} with a
+ * `[start, end]` window.
+ *
+ * The central directory is parsed by yauzl (the only listing engine —
+ * the hand-rolled fast parser was removed; ZIP64 falls out naturally).
+ */
+type ZipEntry = {
+    readonly name: string;
+    readonly compressionMethod: number;
+    /** General-purpose bit 0: the entry data is encrypted. */
+    readonly encrypted: boolean;
+    readonly uncompressedSize: number;
+    readonly compressedSize: number;
+    readonly crc32: number;
+    readonly localHeaderOffset: number;
+    /**
+     * Absolute byte offset of the entry's raw data inside the zip file.
+     * Computed as `localHeaderOffset + 30 + nameLen + extraLen` where
+     * nameLen and extraLen are read from the local file header (not the
+     * central directory) because they can differ between the two.
+     */
+    readonly dataOffset: number;
+    readonly dataSize: number;
+    readonly modifiedAt: number;
+};
+/** Read the central directory of the zip at `zipPath`. */
+declare function listZipEntries(zipPath: string, opts?: {
+    readonly dataOffsets?: boolean;
+}): Promise<readonly ZipEntry[]>;
+
+/**
+ * Materialization primitives shared by every code path that writes
+ * derived files into the extraction cache: the host's container
+ * extractor and the server's artifact view (thumb/probe materialization
+ * for both literal and virtual entries). One partial+rename+size-check
+ * recipe and one single-flight guard, instead of a copy per caller.
+ */
+/**
+ * Write `openStream`'s bytes to `target` atomically: stream to a
+ * `.partial` sibling, verify the written size matches `expectedSize`,
+ * then rename into place. On any failure the partial is removed and the
+ * error rethrown. An already-correct `target` is left untouched.
+ *
+ * With `key` set, concurrent calls for the same key share one in-flight
+ * write instead of racing it (via {@link globalMaterializeInflight}).
+ */
+declare function materializeFile(opts: {
+    readonly openStream: () => Readable | Promise<Readable>;
+    readonly target: string;
+    readonly expectedSize: number;
+    readonly key?: string;
+}): Promise<void>;
+
+/** A plugin discovered on disk — not yet imported/activated. */
+type FoundPlugin = {
+    readonly id: PluginManifestId;
+    readonly manifest: PluginManifest;
+    readonly diskPath: string;
+    readonly source: "builtin" | "dev" | "disk";
+    readonly enabled: boolean;
+    readonly priority: number;
+    readonly pinned: boolean;
+    readonly color: string;
+};
+/** A plugin known to the DB but missing from disk. */
+type MissingPlugin = {
+    readonly id: PluginManifestId;
+    readonly manifest: PluginManifest;
+    readonly enabled: boolean;
+    readonly priority: number;
+    readonly pinned: boolean;
+    readonly color: string;
+};
+/** A loaded plugin entry in the runtime registry. */
+type PluginRegistryEntry = {
+    readonly id: PluginManifestId;
+    readonly manifest: PluginManifest;
+    readonly enabled: boolean;
+    readonly priority: number;
+    readonly pinned: boolean;
+    readonly color: string;
+    readonly missing: boolean;
+    readonly builtin: boolean;
+    readonly dev: boolean;
+    readonly plugin: PluginDefinition;
+    /** Absolute path to the plugin directory on disk. Undefined for builtin / in-memory plugins. */
+    readonly diskPath?: string;
+};
+/** The plugin registry — built at startup and kept in memory. */
+type PluginRegistry = {
+    getAll(): readonly PluginRegistryEntry[];
+    getEnabled(): readonly PluginRegistryEntry[];
+    getById(id: PluginManifestId): PluginRegistryEntry | undefined;
+    getBuiltin(): PluginRegistryEntry | undefined;
+    getForResource(resPluginId: PluginManifestId): PluginRegistryEntry | undefined;
+    updateEntry(id: PluginManifestId, patch: Partial<Pick<PluginRegistryEntry, "enabled" | "priority" | "pinned" | "color" | "missing">>): void;
+};
+
+/**
+ * The plugin asset handler: the host-side implementation of the
+ * `download`/`statAsset`/`readAsset`/`deleteAsset` ResourceAPI methods,
+ * bound to the plugin id (the sandbox knows which plugin issued the
+ * call). Wired by the app server; hosts without a consent channel (CLI,
+ * workbench) omit it and the methods answer `UNAVAILABLE`.
+ */
+type PluginAssetHandler = {
+    readonly download: (pluginId: string, request: PluginDownloadRequest) => Promise<PluginDownloadResult>;
+    readonly statAsset: (pluginId: string, path: string) => Promise<{
+        readonly sizeBytes: number;
+    } | undefined>;
+    readonly readAsset: (pluginId: string, path: string) => Promise<Uint8Array>;
+    readonly deleteAsset: (pluginId: string, path: string) => Promise<PluginAssetDeleteResult>;
+};
+/**
+ * Kill a plugin sandbox process when an invocation neither returns nor
+ * shows resource-API activity for this long. Hooks that keep calling the
+ * API reset the watchdog continuously and never trip it; time spent inside
+ * a host-side API call does not count as inactivity.
+ */
+declare const PLUGIN_WATCHDOG_TIMEOUT_MS = 60000;
+/** Absolute cap for a single plugin hook invocation, regardless of activity. */
+declare const PLUGIN_HOOK_HARD_TIMEOUT_MS: number;
+/** V8 old-generation memory cap per plugin sandbox process, in MiB. */
+declare const PLUGIN_WORKER_MAX_OLD_SPACE_MB = 512;
+/**
+ * Absolute cap for one hook result crossing the IPC boundary back to the
+ * host. Exceeding it turns the hook into an error instead of letting a
+ * hostile bundle clone a giant payload into the host process.
+ */
+declare const PLUGIN_MAX_RESULT_BYTES: number;
+/** Cap on `log*` messages per hook invocation (see {@link PluginSandboxConfig}). */
+declare const PLUGIN_MAX_LOGS_PER_HOOK = 1000;
+/** Cap on ResourceAPI calls per hook invocation (see {@link PluginSandboxConfig}). */
+declare const PLUGIN_MAX_API_CALLS_PER_HOOK = 100000;
+/**
+ * Max sandbox spawns per plugin within {@link PLUGIN_WORKER_RESPAWN_WINDOW_MS}
+ * before the plugin is degraded. It recovers automatically once the crash
+ * window slides clean, or immediately on disable/rescan.
+ */
+declare const PLUGIN_WORKER_MAX_RESPAWNS = 3;
+/** Sliding window for {@link PLUGIN_WORKER_MAX_RESPAWNS}. */
+declare const PLUGIN_WORKER_RESPAWN_WINDOW_MS = 60000;
+type PluginSandboxConfig = {
+    /**
+     * Kill the sandbox process when an invocation neither returns nor shows
+     * API activity for this long. Long-running hooks that keep calling the
+     * resource API reset the watchdog continuously and never trip it;
+     * time spent inside a host-side API call does not count as inactivity.
+     */
+    readonly watchdogMs: number;
+    /** Absolute per-invocation cap, regardless of activity. */
+    readonly hardTimeoutMs: number;
+    /** V8 old-generation cap per sandbox process; exceeding it aborts it. */
+    readonly maxOldSpaceMb: number;
+    /**
+     * Max sandbox spawns per plugin within {@link respawnWindowMs} before the
+     * plugin is degraded (all invocations reject). The plugin recovers
+     * automatically once the crash window slides clean; `unloadPlugin`
+     * (disable or rescan) resets the budget immediately.
+     */
+    readonly maxRespawns: number;
+    readonly respawnWindowMs: number;
+    /** Absolute cap for one hook result returning to the host. */
+    readonly maxResultBytes: number;
+    /**
+     * Cap on `log*` messages per hook invocation; exceeding it fails the
+     * hook (log messages reset the watchdog, so a log flood would
+     * otherwise stay alive until the hard timeout).
+     */
+    readonly maxLogsPerHook: number;
+    /**
+     * Cap on ResourceAPI calls per hook invocation; exceeding it fails the
+     * hook. Sized generously so large per-file scans (hashBytes over tens
+     * of thousands of files) keep working — the cap bounds a runaway RPC
+     * fan-out that would otherwise pin the host's CPU.
+     */
+    readonly maxApiCallsPerHook: number;
+    /**
+     * Permission-model flag to pass to the sandbox child, or `undefined` to
+     * probe the running Node for the first accepted name. Tests override
+     * this to exercise the fail-closed path.
+     */
+    readonly permissionFlag?: string;
+    /**
+     * Host-managed plugin vault directory (`<plugin-dir>/vault/`, or the
+     * versioned-storage vault for dev plugins). When set, the child gets
+     * an extra fs-read grant and the module policy gate allows loading
+     * files from it — downloaded runtimes (JS/WASM) importable from the
+     * vault are the point of the asset API. A function form lets one
+     * shared sandbox resolve the path per plugin (disk vs dev plugins
+     * store their vault differently).
+     */
+    readonly assetVaultDir?: string | ((pluginId: string) => string | undefined);
+    /**
+     * Plugin asset handler wired by the app server. Absent → the asset
+     * methods answer `UNAVAILABLE` (CLI, workbench, tests without a
+     * consent channel).
+     */
+    readonly pluginAssets?: PluginAssetHandler;
+};
+declare const DEFAULT_SANDBOX_CONFIG: PluginSandboxConfig;
+type PluginSandbox = {
+    /**
+     * Register and load a plugin bundle. With `eager` the sandbox process
+     * stays alive; without it the hook list is probed and the process
+     * immediately idles (it respawns lazily on first invocation — disabled
+     * plugins still serve their bound resources without holding a process).
+     *
+     * Reloading an already-registered id keeps the previous process alive
+     * until the new bundle loads successfully — a failed reload returns
+     * the previous definition instead of stranding a disposed registry.
+     *
+     * Returns `undefined` when the bundle cannot be loaded and there is no
+     * previous definition to fall back on (already logged) — callers fall
+     * back to a failing plugin.
+     */
+    readonly loadPlugin: (opts: {
+        readonly id: string;
+        readonly mainPath: string;
+        readonly eager: boolean;
+        /**
+         * Manifest permissions the sandbox enforces on every API call
+         * (e.g. the `container` gate). Absent keys count as denied here,
+         * so a caller that omits this opts into the strictest view.
+         */
+        readonly permissions?: PluginPermissions;
+    }) => Promise<PluginDefinition | undefined>;
+    /**
+     * Terminate the plugin's sandbox process (if any) and reset its respawn
+     * budget. The hook list stays known; the next invocation lazily respawns.
+     */
+    readonly unloadPlugin: (id: string) => void;
+    /**
+     * Terminate and forget every plugin whose id is not in `keepIds`.
+     * Registered ids keep their processes — used by the loader after a
+     * successful reload to free plugins that left the registry.
+     */
+    readonly disposeExcept: (keepIds: ReadonlySet<string>) => Promise<void>;
+    /** Terminate every process and forget all plugins. Pending invocations reject. */
+    readonly disposeAll: () => Promise<void>;
+};
+declare function createPluginSandbox(config?: PluginSandboxConfig): PluginSandbox;
+
+/**
+ * Plugin activation: turns discovered plugin candidates (found on disk
+ * or recorded as missing) into ready {@link PluginRegistryEntry}s by
+ * loading their `main.js` into the sandbox. Loads run in parallel —
+ * sequential worker spawns would multiply the boot cost on slow or
+ * antivirus-scanned disks.
+ */
+type PluginActivation = {
+    /** Load every found plugin's `main.js` into the sandbox and return the full registry entries. */
+    readonly activateAll: (found: readonly FoundPlugin[]) => Promise<PluginRegistryEntry[]>;
+    /**
+     * Build registry entries for plugins whose directory is missing, each
+     * carrying a failing definition so callers can still render them as
+     * broken in the UI.
+     */
+    readonly createFailingEntries: (missing: readonly MissingPlugin[]) => PluginRegistryEntry[];
+};
+type PluginActivationDeps = {
+    readonly sandbox: PluginSandbox;
+};
+/**
+ * Create the activation pipeline. The sandbox decides worker lifetimes:
+ * enabled plugins keep their worker alive, disabled ones only probe the
+ * hook list and respawn lazily if a bound resource still invokes a hook.
+ */
+declare function createPluginActivation(deps: PluginActivationDeps): PluginActivation;
+
+/**
+ * A {@link ResourceContainer} over a raw filesystem directory. Used to
+ * run plugin hooks against a plain directory — during import, before
+ * resources exist, or from the CLI. Reads only; the directory is treated
+ * as an immutable snapshot for the container's lifetime.
+ */
+declare function createDirectoryContainer(dir: string): ResourceContainer;
+/**
+ * Resolve a plugin-supplied relative path against an import directory,
+ * rejecting attempts to escape the directory or use absolute paths.
+ */
+declare function resolveSafeImportPath(dir: string, relPath: string): string;
+
+/**
+ * Create a minimal {@link ResourceAPI} backed by a raw filesystem
+ * directory. Used to run plugin hooks against a plain directory — during
+ * import, before resources exist, or from the CLI. Built on the shared
+ * {@link createPluginResourceAPI} so directory behavior matches the
+ * archive-backed and fixture backends; probes are unsupported and resolve
+ * to `undefined`.
+ */
+declare function createDirectoryResourceAPI<TSchema extends PluginSchema = PluginSchema>(dir: string, opts?: {
+    readonly maxReadFileBytes?: number;
+    /**
+     * Writable directory for `extractArchive` materialization (the
+     * CLI passes a temp dir). Virtual-path reads (`outer!inner`) work
+     * without it; only the materializing hook needs it.
+     */
+    readonly extractCacheDir?: string;
+    /**
+     * Session context handed to hooks as `api.context.detect` (see
+     * `CreatePluginResourceAPIDeps.detectContext`).
+     */
+    readonly detectContext?: unknown;
+}): ResourceAPI<TSchema>;
+
+/**
+ * Construct a {@link ResourceAPI} on top of a {@link ResourceContainer}.
+ * The container abstracts away the storage shape (bare-file resource
+ * folder, raw directory, in-memory fixture) so plugin code stays
+ * unaware of how source bytes are stored.
+ */
+type CreatePluginResourceAPIDeps = {
+    readonly view: ResourceContainer;
+    /**
+     * Probe implementations, both optional: when absent the matching
+     * branch of `probe` resolves to
+     * `{ kind: "unknown", reason: "unavailable" }` without opening any
+     * stream — the directory backend ships without probes by design.
+     * `sniff` never needs a backend; it reads the file's own header.
+     */
+    readonly probeImage?: (source: ImageMetadataInput, extHint?: string) => Promise<ImageSourceProbe | undefined>;
+    readonly probeAv?: (source: string | Readable, opts: AvProbeOptions) => Promise<ProbeResult>;
+    /** Per-call `readFile` byte cap. Defaults to {@link PLUGIN_READ_FILE_MAX_BYTES}. */
+    readonly maxReadFileBytes?: number;
+    /**
+     * Process-wide probe cache. Only active together with
+     * {@link cacheScope}; without it every probe opens a fresh stream.
+     */
+    readonly probeCache?: PluginProbeCache;
+    /**
+     * Cache namespace for this API instance, typically
+     * `${resId}:${fileVersion}`. Archives are immutable per version, so
+     * cached probe results never need explicit invalidation.
+     */
+    readonly cacheScope?: string;
+    /**
+     * Absolute directory for plugin container extractions (e.g. the
+     * server's `local/cache/resources/<id>/extracted/v<N>/archives`, or a
+     * temp dir for the CLI). When absent, `extractArchive` rejects with
+     * a clear message.
+     */
+    readonly extractCacheDir?: string;
+    /**
+     * Hard caps for one `extractArchive` call. Defaults to
+     * {@link DEFAULT_PLUGIN_EXTRACT_MAX_BYTES} /
+     * {@link DEFAULT_PLUGIN_EXTRACT_MAX_ENTRIES}.
+     */
+    readonly maxExtractBytes?: number;
+    readonly maxExtractEntries?: number;
+    /**
+     * Called with per-entry materialization progress during
+     * `extractArchive`, so the server can surface it to the user.
+     */
+    readonly onExtractProgress?: (progress: ExtractProgress) => void;
+    /**
+     * Process-wide nested central-directory cache. When provided, virtual
+     * path resolution (`outer!inner`) reuses parsed listings across hook
+     * calls instead of re-reading each archive's CD per invocation. The
+     * server passes one cache per (resId, fileVersion) scope.
+     */
+    readonly nestedCdCache?: NestedCdCache;
+    /**
+     * Session context handed to hooks as `api.context.detect`: the
+     * payload a prior `detect` invocation returned on a successful
+     * match. The sandbox worker injects it itself; this escape hatch
+     * lets in-process hosts (the dev runner) do the same.
+     */
+    readonly detectContext?: unknown;
+};
+declare const DEFAULT_PLUGIN_EXTRACT_MAX_BYTES: number;
+declare const DEFAULT_PLUGIN_EXTRACT_MAX_ENTRIES = 200000;
+declare function createPluginResourceAPI<TSchema extends PluginSchema = PluginSchema>(deps: CreatePluginResourceAPIDeps): ResourceAPI<TSchema>;
+
+/**
+ * Capabilities a plugin manifest can declare — derived from the single
+ * {@link PLUGIN_CAPABILITY_GATES} table (which is itself keyed by the
+ * manifest's `PluginPermissions` keys), so the guard can never drift.
+ */
+type PluginCapability = PluginCapabilityKey;
+
+/**
+ * Permission checks against a plugin's declared manifest permissions,
+ * reading the capability vocabulary from the shared gates table.
+ * The server uses these before routing any plugin-scoped work so a
+ * manifest that does not declare a capability cannot trigger it.
+ */
+type CapabilityGuard = {
+    /** Check whether a manifest grants the given capability. */
+    readonly check: (manifest: PluginManifest, capability: PluginCapability) => boolean;
+    /** Assert that a manifest grants the given capability; throw if not. */
+    readonly require: (manifest: PluginManifest, capability: PluginCapability) => void;
+    /** Filter entries to only those that grant the given capability. */
+    readonly filter: (entries: readonly PluginRegistryEntry[], capability: PluginCapability) => readonly PluginRegistryEntry[];
+};
+/** Create a stateless capability guard over manifest permissions. */
+declare function createCapabilityGuard(): CapabilityGuard;
+
+/**
+ * Plugin hooks the dev runner can invoke against a directory — the
+ * contract-order list shared with the sandbox host and the CLI.
+ */
+type PluginHookName = HookName;
+/**
+ * Load a built plugin `main.js` and invoke one hook with a
+ * directory-backed {@link ResourceAPI}. Development aid only — the plugin
+ * runs unsandboxed in the current process, so only run code you trust.
+ * Consumed from plugin tests as a devDependency; never bundled into a
+ * shipped plugin.
+ *
+ * Before the target hook runs, `detect` is invoked once (when the
+ * target is not detect itself) so hooks see the session context a real
+ * sandbox session would have — `api.context.detect` carries the
+ * detection payload. A throwing or missed detection leaves the context
+ * absent, exactly like a fresh worker in production.
+ */
+declare function runPluginHook(opts: {
+    readonly mainPath: string;
+    readonly hook: PluginHookName;
+    readonly dir: string;
+    /** Scratch dir for `extractArchive` materialization. */
+    readonly extractCacheDir?: string;
+}): Promise<{
+    readonly result: unknown;
+    readonly durationMs: number;
+}>;
+
+/**
+ * A plugin's persisted settings — the union of what the server's DB row
+ * and the CLI's defaults provide. `undefined` field values mean "no
+ * setting recorded" (fresh install), not a stored default.
+ */
+type PluginSettingsRow = {
+    readonly id: PluginManifestId;
+    /** Raw `manifest.json` text as stored by the consumer. */
+    readonly manifest: string;
+    readonly enabled: boolean;
+    readonly priority: number;
+    readonly pinned: boolean;
+    readonly color: string;
+};
+/**
+ * Storage seam for plugin settings (enablement, priority, pin, color).
+ * The server implements it over its `content_plugins` table; the CLI uses
+ * an in-memory default. Keeps the host free of any database dependency.
+ */
+type PluginSettingsStore = {
+    readonly get: (id: PluginManifestId) => PluginSettingsRow | undefined;
+    readonly all: () => readonly PluginSettingsRow[];
+};
+
+type PluginDiscoveryDeps = {
+    /** Directory of the mandatory builtin plugin (`manifest.json` at its root). */
+    readonly builtinDir?: string;
+    /** Extra plugin directories for development (override same-id disk plugins). */
+    readonly devPluginDirs?: readonly string[];
+    /** Directory where installed plugins live, one subdirectory per plugin. */
+    readonly pluginsDir: string;
+    /** DB-backed per-plugin settings (enabled/priority/pinned/color). */
+    readonly settings: PluginSettingsStore;
+    /** Skip dev plugins entirely (e.g. production configuration). */
+    readonly disableDevPlugins?: boolean;
+};
+/**
+ * Plugin discovery: finds plugins on disk (builtin, dev, installed),
+ * merges their DB settings, and reports which known plugins are missing.
+ */
+type PluginDiscovery = {
+    readonly discover: () => Promise<{
+        found: FoundPlugin[];
+        missing: MissingPlugin[];
+    }>;
+};
+/**
+ * Create the discovery pipeline. Order matters: the builtin plugin wins
+ * priority, dev plugins override same-id installed ones, and anything in
+ * settings but absent from disk is reported missing.
+ */
+declare function createPluginDiscovery(deps: PluginDiscoveryDeps): PluginDiscovery;
+/**
+ * Read and validate `manifest.json` in `dirPath` against the zod
+ * contract. Logs a warning and returns `undefined` for every failure
+ * mode (missing file, unreadable, invalid JSON, schema violation) so
+ * callers can skip the directory without crashing the scan.
+ */
+declare function parseManifest(dirPath: string, dirName: string): PluginManifest | undefined;
+
+/**
+ * Host-local domain error. Mirrors the wire-format taxonomy of the app's
+ * domain errors (`@hoardodile/shared`) so errors raised here keep their
+ * code/kind/details across the package boundary — the server's error
+ * translation recognizes this shape structurally via `isDomainError`.
+ *
+ * The host deliberately keeps its dependency graph minimal (consts +
+ * sdk-types only) and does not depend on `@hoardodile/shared`; the
+ * mirror is kept in sync by the bridge test in
+ * `apps/server/src/infra/host-errors.test.ts`.
+ */
+declare const domainErrorCodes: readonly ["NOT_FOUND", "CONFLICT", "VALIDATION", "UNAUTHORIZED", "FORBIDDEN", "RATE_LIMITED", "UNSUPPORTED", "INTERNAL"];
+type DomainErrorCode = (typeof domainErrorCodes)[number];
+/**
+ * Host-local domain error carrying a wire-compatible code/kind/details
+ * triple. Thrown by host services (containers, loaders, hooks) so the
+ * server can translate them into its own domain errors verbatim.
+ */
+declare class DomainError extends Error {
+    readonly code: DomainErrorCode;
+    readonly kind: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+    constructor(code: DomainErrorCode, kind: string, message: string, details?: Readonly<Record<string, unknown>>);
+}
+/** Convenience constructor for `VALIDATION` errors. */
+declare function invalid(kind: string, message: string, details?: Readonly<Record<string, unknown>>): DomainError;
+/** Convenience constructor for `CONFLICT` errors. */
+declare function conflict(kind: string, message: string, details?: Readonly<Record<string, unknown>>): DomainError;
+/** Convenience constructor for `NOT_FOUND` errors. */
+declare function notFound(kind: string, message: string, details?: Readonly<Record<string, unknown>>): DomainError;
+
+/**
+ * Content hashing for the `imageHashes` plugin hook. All perceptual
+ * hashes derive from one 32×32 grayscale rendition (single sharp
+ * decode), so requesting several kinds costs one decode:
+ * - `sha256`: exact digest of the raw entry bytes (streamed).
+ * - `dhash`: difference hash — 9 samples per row of the 32×32 grid
+ *   (nearest-neighbour spread), adjacent pairs compared, equivalent to
+ *   the standard 9×8 dHash.
+ * - `phash`: standard DCT-based perceptual hash — the 32×32 grid is
+ *   mean-pooled to 8×8, then the 8×8 DCT coefficients are thresholded
+ *   at the median.
+ *
+ * The 64-bit values are hex strings (16 chars), compared by Hamming
+ * distance in `@hoardodile/sdk-server` / the server's hash service.
+ */
+/** Side of the grayscale grid every perceptual hash is derived from. */
+declare const PHASH_GRID = 32;
+/**
+ * Minimum grayscale standard deviation (0–255 scale) for an image to
+ * yield perceptual hashes. Near-flat images (solid fills, blank pages)
+ * hash to distance-0 neighbours of every other flat image, so they are
+ * skipped — `sha256` exact hashing is unaffected.
+ */
+declare const MIN_PERCEPTUAL_STDDEV = 8;
+/**
+ * dHash over a `PHASH_GRID × PHASH_GRID` grayscale buffer: 9 samples per
+ * row (nearest-neighbour spread across the width), each of 8×8 bits
+ * comparing a sample against its right neighbour, packed MSB-first into
+ * a 16-char hex string.
+ */
+declare function computeDHash(gray: Uint8Array, grid?: number): string;
+/**
+ * pHash over a `PHASH_GRID × PHASH_GRID` grayscale buffer: the grid is
+ * mean-pooled to 8×8, then the 8×8 type-II DCT coefficients (precomputed
+ * cosine tables) are thresholded at their median, each bit MSB-first
+ * into a 16-char hex string.
+ */
+declare function computePHash(gray: Uint8Array, grid?: number): string;
+/**
+ * Population standard deviation of a grayscale buffer. Perceptual hashes
+ * of near-flat images (solid fills, blank pages) cluster at distance 0
+ * regardless of content — callers gate hash emission on this measure.
+ */
+declare function grayStddev(gray: Uint8Array): number;
+/** Kinds whose values come from the single grayscale decode. */
+declare const PERCEPTUAL_HASH_KINDS: readonly ImageHashKind[];
+
+type PluginHooksDeps = {
+    /**
+     * Live accessor for the current registry — called on every hook
+     * invocation so a `rescan()` replacing the registry never leaves
+     * consumers holding a stale snapshot.
+     */
+    readonly getRegistry: () => PluginRegistry;
+};
+/**
+ * Result of {@link PluginHooks.runMetaHooks}. A present key means the hook
+ * ran (permission granted + implemented); `value` is the raw hook result,
+ * which may still be `undefined` when the hook itself returned nothing.
+ */
+type PluginMetaHookResults = {
+    readonly sourceMeta?: {
+        readonly value: unknown;
+    };
+    readonly searchMeta?: {
+        readonly value: unknown;
+    };
+};
+/**
+ * The single entry point for executing plugin hooks. Owns every
+ * hook-invocation policy: priority iteration, builtin fallback, error
+ * swallowing/logging, capability checks, and result validation.
+ *
+ * Methods receive a ready-built {@link ResourceAPI} — this module knows
+ * nothing about resources, archives, or paths.
+ */
+type PluginHooks = {
+    /** The builtin fallback plugin id. Throws when no builtin is registered. */
+    readonly defaultPluginId: () => PluginManifestId;
+    /**
+     * The registry entry that should serve a resource's read paths right
+     * now: the resource's stored plugin when it is healthy (registered,
+     * enabled, not missing), otherwise the builtin fallback plugin.
+     * Throws when no builtin is registered.
+     */
+    readonly getEffectiveEntry: (resPluginId: PluginManifestId | null) => PluginRegistryEntry;
+    /** Run all enabled plugins' detectors in priority order. Returns the first matching plugin id. Throws if no match (builtin should always match). */
+    readonly detectFirstMatch: (api: ResourceAPI) => Promise<PluginManifestId>;
+    /** Validate that the current plugin still matches. Returns confirmed plugin id or falls back to builtin id. */
+    readonly revalidate: (api: ResourceAPI, currentPluginId: PluginManifestId) => Promise<PluginManifestId>;
+    /** Run a specific plugin's detector. */
+    readonly detectForPlugin: (api: ResourceAPI, pluginId: PluginManifestId) => Promise<Detection>;
+    /**
+     * Detector pass for folder-import candidates: non-builtin detectors in
+     * priority order, falling back to the builtin plugin without invoking
+     * its detector.
+     */
+    readonly detectForImportDir: (api: ResourceAPI) => Promise<PluginManifestId>;
+    /**
+     * Ask the owning plugin for a custom file list. Returns `undefined`
+     * when the plugin has no file list hook (or it failed).
+     */
+    readonly buildFileList: (api: ResourceAPI, pluginId: PluginManifestId) => Promise<SerializedFileList | undefined>;
+    /** Ask the owning plugin which file should be used for the local cover. */
+    readonly resolveLocalCoverSource: (api: ResourceAPI, pluginId: PluginManifestId) => Promise<string | undefined>;
+    /**
+     * Run the capability-gated meta hooks (`sourceMeta`, `searchMeta`) of
+     * the owning plugin. Keys are absent when the permission is not
+     * granted or the hook is not implemented.
+     */
+    readonly runMetaHooks: (api: ResourceAPI, pluginId: PluginManifestId) => Promise<PluginMetaHookResults>;
+    /**
+     * True when the plugin's manifest grants `imageHashes` and the plugin
+     * implements the hook. Used to decide whether a missing hash state is
+     * a rebuild gap or the plugin's legitimate choice.
+     */
+    readonly supportsImageHashes: (pluginId: PluginManifestId) => boolean;
+    /**
+     * Run the capability-gated `imageHashes` hook of the owning plugin.
+     * Resolves to `undefined` when the permission is not granted, the
+     * hook is not implemented, or it threw. The returned entries are
+     * shape-validated (hex values, per-resource cap).
+     */
+    readonly runImageHashes: (api: ResourceAPI, pluginId: PluginManifestId) => Promise<ImageHashesResult | undefined>;
+};
+declare function createPluginHooks(deps: PluginHooksDeps): PluginHooks;
+
+/**
+ * Copy the configured plugin directories into `pluginsDir` so discovery
+ * can load them as installed disk plugins. Each source is itself a plugin
+ * directory (`manifest.json` at its root). A seed replaces
+ * `pluginsDir/<manifest.id>` only when the file set, sizes, or content
+ * hashes differ — identical trees are left untouched so a boot does not
+ * dirty a synced `versions/` tree.
+ */
+declare function seedPlugins(pluginsDir: string, seedPluginDirs: readonly string[] | undefined): void;
+
+/**
+ * Loads plugins into a live {@link PluginRegistry}: seed the configured
+ * plugin directories, discover, activate, and sort by priority.
+ * `loadAll`/`rescan` are serialized — an overlapping run would replace
+ * workers out from under the previous run's in-flight loads.
+ *
+ * The previous registry and its workers are only replaced AFTER the new
+ * registry finished activating: a failed load never strands a stale
+ * registry whose workers were already disposed (every hook would then
+ * fail until the next restart).
+ */
+type PluginLoader = {
+    readonly loadAll: () => Promise<PluginRegistry>;
+    readonly rescan: () => Promise<PluginRegistry>;
+    /** The current registry; throws when `loadAll` has not run yet. */
+    readonly getRegistry: () => PluginRegistry;
+};
+type PluginLoaderDeps = {
+    readonly builtinDir?: string;
+    readonly devPluginDirs?: readonly string[];
+    /**
+     * Plugin directories (each with `manifest.json` at its root, e.g. a
+     * built plugin's `dist/`) that are seeded into `pluginsDir` on every
+     * load. Each plugin is copied into `pluginsDir/<manifest.id>` before
+     * discovery runs when the destination tree differs — so a seeded
+     * plugin behaves like a regular installed one (DB settings, caching,
+     * uninstall). The server passes an empty list and seeds through
+     * `writeVersioned` instead. When omitted, nothing is seeded.
+     */
+    readonly seedPluginDirs?: readonly string[];
+    readonly pluginsDir: string;
+    readonly settings: PluginSettingsStore;
+    readonly disableDevPlugins?: boolean;
+    /**
+     * Worker-thread sandbox that executes plugin hooks. Optional so tests
+     * without any `main.js` on disk can omit it; the default spawns real
+     * workers when a loadable bundle is found.
+     */
+    readonly sandbox?: PluginSandbox;
+    /**
+     * Optional timing sink for boot diagnostics — receives the duration of
+     * each `loadAll` step. Defaults to a no-op so tests stay quiet.
+     */
+    readonly onTiming?: (step: string, ms: number) => void;
+};
+/**
+ * Create the plugin loader. Workers are respawned on every load so a
+ * rescan picks up changed plugin code — the new worker re-imports
+ * `main.js`, bypassing the main thread's ESM module cache. Configured
+ * {@link PluginLoaderDeps.seedPluginDirs} are copied into `pluginsDir`
+ * on each load.
+ */
+declare function createPluginLoader(deps: PluginLoaderDeps): PluginLoader;
+/**
+ * Build the immutable-ish registry from entries, keyed by plugin UUID.
+ * Duplicate ids keep the first entry and warn (the UUID contract is
+ * unique — duplicates signal a broken install). Duplicates are dropped
+ * from every accessor, not just the id map: keeping a duplicate in
+ * `getAll()` would make enabled-list iteration invoke a plugin whose
+ * worker activation already replaced (and disposed) the first load.
+ * `updateEntry` patches a single entry in place and re-sorts by priority.
+ */
+declare function buildRegistry(entries: readonly PluginRegistryEntry[]): PluginRegistry;
+
+/**
+ * Wrap a {@link ResourceContainer} so every read operation understands
+ * virtual paths (`outer!inner`, see `./archive`). The plugin API,
+ * the server artifact view and the CLI directory container all funnel
+ * entry reads through this wrapper, so nested-container support lands
+ * everywhere (hooks, cover pipeline, thumbnails, the HTTP file route)
+ * without each consumer knowing about containers.
+ *
+ * A virtual path resolves in two steps:
+ *   1. nested zip addressing — the resolver reads the outer entry's
+ *      central directory and streams the *decompressed* inner bytes;
+ *   2. materialized cache addressing — when `extractCacheDir` is wired
+ *      and the outer archive was extracted by the plugin API (its
+ *      manifest exists in `<extractCacheDir>/<outer>/`), the inner file
+ *      is served straight from disk. This is how non-zip containers
+ *      (rar/7z/tar — not expressible as random-access sources) get
+ *      `outer!inner` addressing after extraction, and it is strictly
+ *      better than streaming: entries are seekable.
+ *
+ * Literal entries pass through untouched; virtual entries are only
+ * addressable by name, never enumerated.
+ *
+ * `scope` prefixes nested-cache keys when the cache is shared across
+ * containers (see {@link createNestedResolver}); `resolveSeekablePath`
+ * forwards the base container's capability for literal entries and the
+ * extracted file path for materialized ones.
+ */
+declare function createNestedAwareContainer(base: ResourceContainer, nestedCdCache?: NestedCdCache, scope?: string, extractCacheDir?: string): ResourceContainer;
+
+export { type CapabilityGuard, type CreatePluginResourceAPIDeps, DEFAULT_PLUGIN_EXTRACT_MAX_BYTES, DEFAULT_PLUGIN_EXTRACT_MAX_ENTRIES, DEFAULT_SANDBOX_CONFIG, DomainError, type DomainErrorCode, type FoundPlugin, MIN_PERCEPTUAL_STDDEV, type MissingPlugin, type NestedCdCache, PERCEPTUAL_HASH_KINDS, PHASH_GRID, PLUGIN_HOOK_HARD_TIMEOUT_MS, PLUGIN_MAX_API_CALLS_PER_HOOK, PLUGIN_MAX_LOGS_PER_HOOK, PLUGIN_MAX_RESULT_BYTES, PLUGIN_WATCHDOG_TIMEOUT_MS, PLUGIN_WORKER_MAX_OLD_SPACE_MB, PLUGIN_WORKER_MAX_RESPAWNS, PLUGIN_WORKER_RESPAWN_WINDOW_MS, type PluginActivation, type PluginActivationDeps, type PluginAssetHandler, type PluginCapability, type PluginDiscovery, type PluginDiscoveryDeps, type PluginHookName, type PluginHooks, type PluginHooksDeps, type PluginLoader, type PluginLoaderDeps, type PluginMetaHookResults, PluginProbeCache, type PluginRegistry, type PluginRegistryEntry, type PluginSandbox, type PluginSandboxConfig, type PluginSettingsRow, type PluginSettingsStore, ResourceContainer, buildRegistry, computeDHash, computePHash, conflict, createCapabilityGuard, createDirectoryContainer, createDirectoryResourceAPI, createDirectoryResourceAPI as createImportResourceAPI, createNestedAwareContainer, createNestedCdCache, createPluginActivation, createPluginDiscovery, createPluginHooks, createPluginLoader, createPluginResourceAPI, createPluginSandbox, grayStddev, invalid, listZipEntries, materializeFile, notFound, parseManifest, resolveSafeImportPath, runPluginHook, seedPlugins };