@hoardodile/host 0.0.0

package/dist/hoard/index.d.ts

@@ -0,0 +1,754 @@
+import { Readable } from 'node:stream';
+
+/**
+ * Whole-archive extraction. Every supported format (zip, tar, 7z, rar,
+ * xz, gzip) extracts through 7-Zip with listing-validated budgets; when
+ * the optional 7-Zip binary is absent, zip falls back to a yauzl
+ * streaming path with a per-byte budget counter. Used by plugin
+ * installation, folder-import extraction and the plugin extract API —
+ * the workflows that need a directory layout.
+ */
+/**
+ * Extraction progress reporter for {@link extractArchiveInto}. The
+ * 7-Zip path reports the two phases only (listing pre-check, done);
+ * the yauzl fallback reports per-entry events.
+ */
+type ZipExtractReporter = (event: ZipExtractReport) => void;
+type ZipExtractReport = {
+    readonly phase: "started";
+    readonly totalEntries: number;
+    readonly totalBytes: number;
+} | {
+    readonly phase: "entry";
+    readonly entriesDone: number;
+    readonly totalEntries: number;
+    readonly bytesDone: number;
+    readonly totalBytes: number;
+} | {
+    readonly phase: "done";
+};
+type ExtractArchiveOptions = {
+    /** Cumulative uncompressed byte budget for the whole archive. */
+    readonly maxBytes: number;
+    /** Optional entry-count budget (enforced on the listing). */
+    readonly maxEntries?: number;
+    readonly onProgress?: ZipExtractReporter;
+};
+/**
+ * Stream an archive into `destDir`, format-agnostic: every supported
+ * format (zip/tar/7z/rar/xz/gzip) extracts through 7-Zip after
+ * validating budgets, encryption and paths from its listing, then
+ * re-verifies the extracted tree (size + symlink scan). Without a
+ * 7-Zip binary, zip extracts through yauzl with a per-byte budget
+ * counter; the other formats error with "7-Zip is not installed".
+ * Used by plugin installation and folder-import extraction (the
+ * workflows that need a directory layout).
+ *
+ * Refuses any entry whose normalised path escapes `destDir` (zip-slip)
+ * or contains an absolute path / drive letter. Defends against zip
+ * bombs via `maxBytes` (and `maxEntries` when provided).
+ *
+ * @throws DomainError VALIDATION when the archive is malformed,
+ *   contains an unsafe entry, exceeds the budgets, is encrypted, or is
+ *   not a supported archive at all.
+ */
+declare function extractArchiveInto(source: NodeJS.ReadableStream, destDir: string, opts: ExtractArchiveOptions): Promise<void>;
+
+/** A unified, format-agnostic inner entry. */
+type ArchiveEntry = {
+    readonly name: string;
+    readonly sizeBytes: number;
+};
+
+/**
+ * Cross-engine archive listing and budget validation. Zip lists through
+ * yauzl, tar/7z/rar/xz/gzip through the 7-Zip binary; the engine choice
+ * (and the zip-only legacy-cp437 name decoding, handled inside the 7-Zip
+ * wrapper) lives here so callers never branch on format.
+ */
+/**
+ * List the file entries of an on-disk archive across engines: zip lists
+ * through yauzl, tar/7z/rar/xz/gzip through the 7-Zip binary (gzip
+ * reports its single decompressed stream).
+ *
+ * @throws DomainError `resource.archive_open_failed` when the file is
+ *   not a readable archive, or 7-Zip is missing for a non-zip format.
+ */
+declare function listArchiveEntries(archivePath: string): Promise<readonly ArchiveEntry[]>;
+/**
+ * Validate an on-disk archive's cumulative uncompressed size against
+ * `maxBytes` without inflating any entry bytes (metadata-only — the
+ * listing never decompresses). Format-agnostic via
+ * {@link listArchiveEntries}; unknown content and non-zip formats
+ * without the 7-Zip binary are rejected outright.
+ *
+ * Used at commit time for uploaded archives so every supported format
+ * passes the same bomb gate.
+ *
+ * @throws DomainError `resource.archive_open_failed` when the file is
+ *   not a readable archive (or 7-Zip is missing for non-zip formats).
+ * @throws DomainError `resource.archive_too_large` when the cumulative
+ *   uncompressed size exceeds `maxBytes`.
+ */
+declare function validateArchiveBudget(archivePath: string, maxBytes: number): Promise<void>;
+
+/**
+ * On-the-fly zip exports. Resource sources are stored as bare files on
+ * disk — nothing is packed at commit time; this module streams STORED
+ * zip bytes straight to the consumer without a staging file.
+ */
+/**
+ * A logical zip entry whose bytes are produced on demand. Streams are
+ * read once, in order, when the output is consumed.
+ */
+type ZipStreamEntry = {
+    readonly name: string;
+    readonly size: number;
+    readonly openStream: () => Readable;
+};
+/**
+ * Stream a STORED zip from an ordered list of logical entries. Used by
+ * the HTTP layer for exports (resource source packs, bulk downloads)
+ * without a staging file on disk. Zero-length entries are packed as
+ * empty buffers.
+ */
+declare function streamStoredZip(entries: readonly ZipStreamEntry[]): NodeJS.ReadableStream;
+
+/**
+ * Shared directory-size walk: the one implementation of "recursive byte
+ * size of a directory tree" for host storage. Consumers opt into
+ * different file policies via options:
+ *
+ * - vault totals skip dot-prefixed files (host temp staging), while
+ *   storage totals count everything — see {@link vaultTotalSize} and
+ *   `apps/server/src/domain/storage/service.ts`.
+ *
+ * Symbolic links are skipped so cycles cannot hang the walk and
+ * linked-out files are not double counted; missing/transient entries
+ * are ignored.
+ */
+type DirSizeOptions = {
+    /** Skip file names starting with a dot (host temp staging). */
+    readonly excludeDotPrefix?: boolean;
+};
+declare function sumDirSizes(root: string, opts?: DirSizeOptions): Promise<number>;
+
+/**
+ * Explicit file order for a resource's content root (`data/`). Uploads
+ * install entries in the user's chosen order and persist that sequence
+ * in this manifest so the display order matches the upload order even
+ * when filenames sort differently. Written at commit time; because it
+ * lives inside the replaced `data/` subtree it is always consistent
+ * with the entries around it.
+ *
+ * The manifest is a JSON array of relative entry names (`/`-separated),
+ * listing the final installed names (after collision suffixing). Reads
+ * are strict: a malformed manifest, or one whose entries do not all
+ * resolve against the actual listing, is ignored entirely and callers
+ * fall back to the natural name sort. Strictness matters because
+ * `createDirectoryContainer` also serves arbitrary user directories
+ * (folder import, plugin dev) that may coincidentally contain a file
+ * named `.order`.
+ */
+declare const ORDER_MANIFEST_NAME = ".order";
+/** Path of the order manifest inside a resource content root. */
+declare function orderManifestPath(dataDir: string): string;
+/**
+ * Atomically persist `names` as the manifest of `dataDir` (tmp + rename,
+ * so a concurrent reader never observes a half-written file).
+ */
+declare function writeOrderManifest(dataDir: string, names: readonly string[]): Promise<void>;
+/**
+ * Read the manifest of `dataDir`. Resolves to `undefined` when the
+ * manifest is absent or fails structural validation
+ * ({@link parseOrderManifest}) — callers fall back to natural order.
+ */
+declare function readOrderManifest(dataDir: string): Promise<readonly string[] | undefined>;
+/**
+ * Structural validation of a raw manifest body: a JSON array of
+ * non-empty relative paths with `/` separators that cannot escape the
+ * content root. Returns `undefined` when the body is not a usable
+ * manifest. Semantic validation (entries exist in the listing) happens
+ * in {@link orderEntries}.
+ */
+declare function parseOrderManifest(raw: string): readonly string[] | undefined;
+/**
+ * Reorder `listed` by the manifest: entries named by the manifest come
+ * first, in manifest order; entries the manifest does not mention are
+ * appended in natural order. Returns `undefined` when the manifest
+ * cannot be applied against this listing (some manifest entry is
+ * missing — the strict trust rule), so the caller falls back to the
+ * natural sort.
+ */
+declare function orderEntries(manifest: readonly string[], listed: readonly string[]): readonly string[] | undefined;
+/** Case-insensitive natural name sort (`1 < 2 < 10`, `a < b`). */
+declare function naturalSort(names: readonly string[]): readonly string[];
+
+/**
+ * Name of the content subfolder inside a resource folder. User entries
+ * live under `resources/<id>/data/`; metadata dotfiles (`.cover.*`,
+ * `.deleted`, `.order`) stay at the resource root. Content and metadata
+ * are replaced/kept independently: commits swap the whole `data/`
+ * subtree, while root dotfiles survive re-uploads.
+ */
+declare const RESOURCE_DATA_DIR_NAME = "data";
+/**
+ * Root-level subdirectory semantics:
+ * - `versions/<version>/` is the user's manual-sync scope, partitioned by
+ *   archive version. Each version folder holds: `app.sqlite` (the
+ *   per-version database snapshot), `db-backups/` (manual backups,
+ *   only kept for the current version), `snapshots/` (automatic daily
+ *   snapshots, only kept for the current version), `resources/<id>/`,
+ *   `characters/<id>/`, `plugins/<id>/` (installed content plugins
+ *   frozen with that version; the builtin `file` plugin is not stored
+ *   here). Old versions are FROZEN: no writes ever land in
+ *   `versions/<v>` once a `versions/<v+1>` exists.
+ * - `local`  holds host-only state. Derived caches (thumbs, previews,
+ *   extraction caches, tmp, read-only DB clones for past-version
+ *   viewing) live under `local/cache/` and are wiped wholesale by
+ *   clear cache; the rest (`logs`, `trash`, session key, upload
+ *   staging) is persistent. It never leaves the host.
+ *
+ * `paths.active` resolves to the **active** version (which may be the
+ * latest version, or a past version when the user is viewing
+ * read-only). `paths.latest` always points at the latest version --
+ * the only version writers may target. `paths.atVersion(v)` exposes
+ * arbitrary cross-version reads (used for character avatar/fullbody
+ * fallback once `avatarVersion` / `fullbodyVersion` columns point at a
+ * historical archive).
+ *
+ * Every resolved path MUST come out of this module so the frozen-version
+ * boundary stays enforceable.
+ */
+type StoragePaths = {
+    readonly root: string;
+    readonly activeVersion: number;
+    readonly latestVersion: number;
+    readonly active: VersionPaths;
+    readonly latest: VersionPaths;
+    readonly local: LocalPaths;
+    /** Per-version archive paths. Use for cross-version fallback reads. */
+    atVersion(v: number): VersionPaths;
+    /**
+     * Path to the live runtime SQLite DB: `<root>/app.sqlite`.
+     * This file is the only writable database during normal operation.
+     * It lives outside `versions/` so that syncing `versions/` to other
+     * devices cannot corrupt the in-use database. Only archived snapshots
+     * (written by {@link createNextVersion}) and backup files belong in
+     * `versions/`.
+     */
+    runtimeDb(): string;
+};
+type VersionPaths = {
+    readonly root: string;
+    readonly version: number;
+    /** Path to the per-version SQLite DB: `<root>/versions/<v>/app.sqlite`. */
+    versionSnapshotDb(): string;
+    /** Root folder of a resource: `<root>/versions/<v>/resources/<id>`. */
+    resource(id: string): string;
+    /**
+     * Content root of a resource — where user entries live:
+     * `<root>/versions/<v>/resources/<id>/data`. The container reads
+     * entries from here; the resource root only holds metadata dotfiles.
+     */
+    resourceData(id: string): string;
+    /** Root folder of all resources in this version: `<root>/versions/<v>/resources`. */
+    resources(): string;
+    /** Root folder of all characters in this version: `<root>/versions/<v>/characters`. */
+    characters(): string;
+    /** Root folder of all documents in this version: `<root>/versions/<v>/documents`. */
+    documents(): string;
+    /** Root folder of a character: `<root>/versions/<v>/characters/<id>`. */
+    character(id: string): string;
+    /** Root of manual backups: `<root>/versions/<v>/db-backups`. */
+    dbBackups(): string;
+    /** Path to one manual backup: `<root>/versions/<v>/db-backups/<name>`. */
+    dbBackup(name: string): string;
+    /** Root of automatic snapshots: `<root>/versions/<v>/snapshots`. */
+    snapshots(): string;
+    /** Path to one automatic snapshot: `<root>/versions/<v>/snapshots/<name>`. */
+    snapshot(name: string): string;
+    /**
+     * Path to a deleted-entity placeholder
+     * (`<root>/versions/<v>/<kind>/<id>/.deleted`) written when hard
+     * delete cannot remove a folder whose files live under frozen past
+     * archives.
+     */
+    deletedMarker(kind: "resources" | "characters", id: string): string;
+    /** Root folder of a document: `<root>/versions/<v>/documents/<id>`. */
+    document(id: string): string;
+    /**
+     * Installed content plugins for this version:
+     * `<root>/versions/<v>/plugins`. Each subdirectory is named by
+     * `manifest.id`. The builtin `file` plugin is not stored here.
+     */
+    plugins(): string;
+    /**
+     * Host-managed plugin asset vault of an installed plugin:
+     * `<root>/versions/<v>/plugins/<id>/vault`. Downloads land here
+     * (user-consented, vault-confined); the directory is host-owned,
+     * reserved against plugin zips (upload rejects a shipped `vault/`),
+     * and its lifecycle follows the plugin's own directory.
+     */
+    pluginVaultDir(id: string): string;
+};
+type LocalPaths = {
+    /** The local (non-synced) root: `<root>/local`. */
+    readonly root: string;
+    /** Derived cache root: `<localRoot>/cache`. */
+    cache(): string;
+    /** Server logs: `<localRoot>/logs`. */
+    logs(): string;
+    /**
+     * Path to a local derived cover/thumb variant:
+     * `<localRoot>/cache/<resources|characters>/<id>/<variant>.<format>`.
+     * Holds synthesized covers (resource covers, character avatars and
+     * fullbody images); re-rendered when cleared.
+     */
+    localCover(subjectKind: "resource" | "character", id: string, variant: string, format?: string): string;
+    /**
+     * Per-file derived image variant:
+     * `<localRoot>/cache/resources/<id>/file-preview/<sourceCacheId>__<variantKey>.<format>`.
+     * The source identity (see {@link sourceCacheId}) is collision-free
+     * across nested paths; the variant key (see {@link imageVariantKey})
+     * encodes the render spec, so distinct specs never collide on one
+     * cache file.
+     */
+    resFileVariant(id: string, filename: string, variantKey: string, format?: string): string;
+    /** Directory holding a resource's per-file variants. */
+    resFilePreviewDir(id: string): string;
+    /** Resource file-list sidecar: `<localRoot>/cache/resources/<id>/files-cache.json`. */
+    resFilesCache(id: string): string;
+    /**
+     * Root of the local per-resource directory:
+     * `<localRoot>/cache/resources/<id>`.
+     */
+    resource(id: string): string;
+    /**
+     * Root of the local per-character directory:
+     * `<localRoot>/cache/characters/<id>`.
+     * Holds (a) versioned copies of replaced avatar / fullbody images and
+     * (b) thumbnail variants (`avatar.webp`, `fullbody.webp`).
+     */
+    character(id: string): string;
+    /** Root of the trash: `<localRoot>/trash`. */
+    trash(): string;
+    /** Path to a single trashed item: `<localRoot>/trash/<id>`. */
+    trashItem(id: string): string;
+    /**
+     * Root of the local temp directory: `<localRoot>/cache/tmp`. Holds
+     * short-lived working files (upload buffers, backup markers, read-only
+     * `view-<v>.sqlite` clones). Lives under the cache root so clear cache
+     * wipes it together with the other derived data; it is also cleaned on
+     * server startup.
+     */
+    tmp(): string;
+    /** Path to a single temp file: `<localRoot>/cache/tmp/<name>`. */
+    tmpFile(name: string): string;
+    /**
+     * Path to the iron-session seal key file: `<root>/local/.session-key`.
+     * 32-byte base64-encoded secret, auto-generated on first boot. Lives in
+     * `local/` (never synced) so each host has its own seal key.
+     */
+    sessionKey(): string;
+    /**
+     * Root of the host-only temporary directory tree:
+     * `<localRoot>/.tmp`. Holds the global staging pool
+     * ({@link stagingPoolRoot}) plus short-lived extraction directories
+     * (`extract-*`). The leading dot keeps host-only state out of any
+     * user-facing listing. Cleared on server startup together with
+     * {@link LocalPaths.tmp}.
+     */
+    uploadStagingRoot(): string;
+    /**
+     * Root of the global staging pool: `<localRoot>/.tmp/staging`.
+     * Every file uploaded through the per-file upload endpoint lands
+     * here as `<fileId><ext>` and is addressed by its `fileId` alone —
+     * there is no per-batch grouping. Files are removed individually
+     * on client delete or consumed (and deleted) by commit at resource
+     * creation. Cleared on startup together with
+     * {@link LocalPaths.uploadStagingRoot}.
+     */
+    stagingPoolRoot(): string;
+    /**
+     * Path of a single staged file in the global pool:
+     * `<stagingPoolRoot>/<fileId><ext>`. `ext` is the lower-cased
+     * extension of the original filename (empty for extensionless
+     * uploads).
+     */
+    stagingPoolFile(fileId: string, ext: string): string;
+    /**
+     * Per-video-frame thumbnail cache:
+     * `<localRoot>/cache/resources/<id>/frames/<sourceCacheId>/<timeMs>.avif`.
+     * Synthesised on-demand by the video hover preview endpoint.
+     */
+    resVideoFrame(id: string, filename: string, timeMs: number): string;
+    /**
+     * Root of persisted zip-entry extractions for a resource version:
+     * `<localRoot>/cache/resources/<id>/extracted/v<fileVersion>/`.
+     */
+    resExtractedDir(id: string, fileVersion: number): string;
+    /**
+     * On-disk path for a materialized zip entry used by probe/ffmpeg
+     * paths: `<localRoot>/cache/resources/<id>/extracted/v<v>/<sourceCacheId>`.
+     */
+    resExtractedEntry(id: string, fileVersion: number, entryName: string): string;
+    /**
+     * Plugin container extraction root for a resource version:
+     * `<localRoot>/cache/resources/<id>/extracted/v<fileVersion>/archives`.
+     * `extractArchive` materializes each archive into its own
+     * subdirectory here (`archives/<archiveName>/<innerPath>`), served to
+     * the browser via the `/extracted/` route.
+     */
+    resExtractedArchivesDir(id: string, fileVersion: number): string;
+};
+type CreateStoragePathsOptions = {
+    readonly root: string;
+    /**
+     * Active (viewing) version. When omitted together with latestVersion,
+     * resolves from `local/version-state.json` and the version dirs under
+     * `versions/`. When only latestVersion is pinned explicitly, defaults to
+     * that same value (call sites that override max version only).
+     */
+    readonly activeVersion?: number;
+    /**
+     * Latest (current, writable) version. When omitted, the maximum
+     * version directory under `versions/` is used, or `1` when none exist.
+     */
+    readonly latestVersion?: number;
+};
+/**
+ * Build a {@link StoragePaths} rooted at `opts.root`. The root must be an
+ * absolute path (the sync boundary would not be well-defined otherwise).
+ *
+ * @throws `Error` when `root` is not absolute.
+ */
+declare function createStoragePaths(opts: CreateStoragePathsOptions): StoragePaths;
+/**
+ * Short, stable cache identity for one derived image variant: the
+ * sha256 of the spec's canonical string (see
+ * `imageVariantCanonical` in `@hoardodile/sdk-types/image-variant`),
+ * truncated to 8 hex chars.
+ */
+declare function imageVariantKey(canonical: string): string;
+/**
+ * Validate a single path segment. We reject anything that embeds a path
+ * separator, a drive letter, a NUL or other control code, a Windows
+ * reserved basename, or a trailing dot/space (Windows normalises those away
+ * and you get the wrong file).
+ *
+ * @throws `Error` when `segment` is empty or rejected by any of the rules.
+ */
+declare function assertSafeSegment(segment: string): string;
+/**
+ * Ensure `candidate` is contained within `ancestor` (after `resolve`). Used
+ * as a belt-and-braces check before any disk operation that mixes user
+ * input with a base directory.
+ */
+declare function assertInside(ancestor: string, candidate: string): string;
+
+/** Thrown when a vault path violates the isolation rules (POLICY). */
+declare class PluginVaultPathError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a vault-relative destination and resolve it against the vault
+ * root. Every segment goes through {@link assertSafeSegment} (no empty
+ * segments, `.`/`..`, separators inside a segment, drive letters,
+ * control chars, Windows-reserved names, trailing dot/space) and the
+ * final path is re-checked with {@link assertInside} — doubly so, the
+ * whole point is that a downloaded file can only ever land inside the
+ * plugin's own vault.
+ */
+declare function parsePluginVaultDest(vaultDir: string, dest: string): {
+    readonly rel: string;
+    readonly abs: string;
+};
+/**
+ * Byte size of a vault file (or `undefined` when absent or not a
+ * regular file). The cheap presence check `download` builds on.
+ */
+declare function vaultStatFile(vaultDir: string, rel: string): Promise<{
+    readonly sizeBytes: number;
+} | undefined>;
+/** Stream a vault file's bytes (bounded by `maxBytes`). */
+declare function vaultReadFile(vaultDir: string, rel: string, maxBytes: number): Promise<Uint8Array>;
+/**
+ * Remove a vault file. Idempotent (absent → false); directories and
+ * anything outside the vault are rejected.
+ */
+declare function vaultRemoveFile(vaultDir: string, rel: string): Promise<boolean>;
+/**
+ * Path of the caller's download temp file inside the vault (host-side
+ * staging — never a user-visible name). The downloader streams into it;
+ * {@link commitVaultFile} renames it into place.
+ */
+declare function vaultTempFile(vaultDir: string): string;
+/** Delete a temp file (download failure path). */
+declare function discardVaultTempFile(tempPath: string): Promise<void>;
+/**
+ * Commit a downloaded temp file into the vault: mkdir the nested
+ * destination, verify the per-plugin total-size budget (the destination's
+ * own previous bytes count against the quota only once — re-downloading
+ * replaces, it does not add), then rename the temp file into place
+ * (atomic — the final path never holds a partial download).
+ */
+declare function commitVaultFile(opts: {
+    readonly vaultDir: string;
+    readonly rel: string;
+    readonly tempPath: string;
+    readonly maxFileBytes: number;
+    readonly maxTotalBytes: number;
+}): Promise<{
+    readonly sizeBytes: number;
+    readonly sha256: string;
+}>;
+/**
+ * Total bytes of the vault's regular files (shared directory-size walk;
+ * host temp staging files — leading `.` — are excluded as transient).
+ */
+declare function vaultTotalSize(vaultDir: string): Promise<number>;
+/** sha256 of a vault file's bytes (streamed; callers verify pins against it). */
+declare function vaultFileSha256(vaultDir: string, rel: string): Promise<string>;
+/** Result of {@link commitVaultFile}: the stored file's identity. */
+type VaultCommitResult = {
+    readonly sizeBytes: number;
+    readonly sha256: string;
+};
+
+/**
+ * Filename hygiene for bare-file resources: map a user-supplied name
+ * (upload filename or zip entry name) onto a safe relative path inside
+ * a resource folder.
+ *
+ * Resource folders hold user entries next to metadata dotfiles
+ * (`.cover.*`, `.deleted`), so every rule here also guarantees the result
+ * can never collide with those: leading dots are stripped, and a
+ * trailing-dot/space rule mirrors Windows normalization.
+ *
+ * Cross-platform guarantees: names are NFC-normalized (macOS stores
+ * NFD on disk — one canonical form keeps names stable when a library
+ * moves between systems), segments are capped at 240 UTF-8 bytes
+ * (ext4's 255-byte component limit, minus suffix headroom), and the
+ * Windows reserved-name set includes the device aliases (`CONIN$`,
+ * superscript COM/LPT variants).
+ *
+ * The migration script (`scripts/migrate-hoard-to-files.mjs`) mirrors
+ * these rules verbatim — keep both in sync when changing them.
+ */
+/**
+ * Sanitize a single entry name into a safe relative path. Separators
+ * (`/` and `\`) become subdirectory boundaries; `..` and absolute paths
+ * are rejected. Returns `undefined` when the name is unusable (empty,
+ * escapes the folder, or cleans to nothing) — callers drop or reject
+ * such entries.
+ */
+declare function sanitizeEntryName(name: string): string | undefined;
+/**
+ * Occupancy bookkeeping for name resolution: which paths are already
+ * taken by files (blocking everything) and which are directories
+ * (blocking only exact-path installs — a file cannot replace a folder).
+ */
+type OccupiedNames = {
+    readonly files: Set<string>;
+    readonly dirs: Set<string>;
+};
+/** Build occupancy from optional existing on-disk names (with types). */
+declare function createOccupiedNames(existing?: {
+    readonly files?: Iterable<string>;
+    readonly dirs?: Iterable<string>;
+}): OccupiedNames;
+/**
+ * Record `relPath` as an installed file; every ancestor prefix becomes
+ * a directory. A later entry colliding with one of the ancestors (a
+ * file that sits on a directory path) is resolved by
+ * {@link uniqueEntryName}.
+ */
+declare function occupyEntryName(occupied: OccupiedNames, relPath: string): void;
+/**
+ * Resolve a sanitized relative path against the names already present
+ * in the target folder by suffixing the colliding segment (`-1`, `-2`,
+ * …). The comparison is case-insensitive (Windows and macOS filesystems
+ * are). Files block their path and every ancestor prefix; directories
+ * block only their exact path. The suffix lands on the segment whose
+ * prefix collides, so `x/y.txt` against an occupied file `x` becomes
+ * `x-1/y.txt`, not `x/y-1.txt` (which would collide forever).
+ */
+declare function uniqueEntryName(occupied: OccupiedNames, relPath: string): string;
+
+/**
+ * Resolve the on-disk path of a file staged in the global pool by
+ * `fileId`. The pool is flat: each file is stored as `<fileId><ext>`
+ * where `ext` is the lower-cased extension of the original filename
+ * (or `.zip` for archive uploads). Because the extension is part of the
+ * filename we scan the directory for a sibling whose stem matches
+ * `fileId`.
+ *
+ * Returns `undefined` when no staged file matches `fileId`.
+ */
+declare function findStagedPoolFile(paths: StoragePaths, fileId: string): Promise<string | undefined>;
+/**
+ * Resolve multiple pool files by `fileId` with a SINGLE directory scan.
+ * Committing an ordered upload resolves and then consumes every staged
+ * file; the per-file {@link findStagedPoolFile} scan would cost one full
+ * `readdir` per file, and the pool can hold hundreds of entries under
+ * concurrent uploads. Returns a map keyed by `fileId`; ids without a
+ * staged match are absent.
+ */
+declare function resolveStagedPoolFiles(paths: StoragePaths, fileIds: readonly string[]): Promise<Map<string, string>>;
+/**
+ * Stream a single file into the global staging pool as
+ * `<fileId><ext>`. The file is first written to a `.tmp-*` sibling and
+ * atomically renamed so concurrent readers (preview) never observe a
+ * partial file. Returns the final staged path.
+ */
+declare function writeStagedPoolFile(paths: StoragePaths, fileId: string, filename: string, stream: NodeJS.ReadableStream): Promise<string>;
+/**
+ * Stream an archive (zip) upload into the global staging pool as
+ * `<fileId>.zip`. Same atomic write semantics as
+ * {@link writeStagedPoolFile}. Returns the final staged path.
+ */
+declare function writeStagedArchiveFile(paths: StoragePaths, fileId: string, stream: NodeJS.ReadableStream): Promise<string>;
+/** Resolve the staged path of an archive upload by `fileId`. */
+declare function findStagedArchiveFile(paths: StoragePaths, fileId: string): Promise<string | undefined>;
+/**
+ * Remove a single file from the global staging pool. Returns `true` when
+ * a file was removed, `false` when `fileId` was not present.
+ */
+declare function removeStagedPoolFile(paths: StoragePaths, fileId: string): Promise<boolean>;
+
+/**
+ * Enumerate version directories under `<root>/versions/`. Names that are
+ * not pure positive integers are ignored. Result is sorted ascending.
+ */
+declare function listVersions(root: string): readonly number[];
+/**
+ * Current (maximum) version on disk. Returns `0` when no version exists
+ * yet (caller is expected to bootstrap version 1 in that case).
+ */
+declare function currentVersion(root: string): number;
+/**
+ * Read the persisted active version. Falls back to current when the
+ * state file is missing or malformed, or when the recorded value points
+ * at a version that no longer exists.
+ */
+declare function readActiveVersion(root: string): number;
+/**
+ * Persist the active version. Caller must ensure `version` exists on
+ * disk (use {@link listVersions}).
+ *
+ * @throws DomainError `version.not_found` when `version` is not a known
+ *   version directory.
+ */
+declare function writeActiveVersion(root: string, version: number): void;
+/**
+ * Bootstrap version 1 if the versions root has no version directories yet.
+ * Idempotent; a no-op when any version already exists.
+ */
+declare function ensureBootstrapVersion(root: string): number;
+type CreateNextVersionResult = {
+    readonly previous: number;
+    readonly created: number;
+};
+/**
+ * Snapshot the current version into a freshly-numbered next version.
+ *
+ * Process:
+ * 1. Compute `next = currentVersion + 1`.
+ * 2. Refuse to proceed when `versions/<prev>/app.sqlite` already exists.
+ * 3. Create `<root>/versions/<next>/` and copy installed plugins from
+ *    `versions/<prev>/plugins` (resource binaries stay at their
+ *    `fileVersion`; plugins have no equivalent pointer).
+ * 4. Vacuum-snapshot the live DB into `<root>/versions/<prev>/app.sqlite`.
+ *    (Caller passes a `vacuumInto` function; we don't take a DB handle
+ *    here to keep this module database-agnostic.)
+ * 5. On any failure after step 3, remove `versions/<next>` so
+ *    {@link currentVersion} does not jump to an empty directory.
+ *
+ * @throws DomainError `version.bootstrap_required` when no version exists
+ *   yet (caller must bootstrap first).
+ * @throws DomainError `version.already_exists` when the previous
+ *   version's DB snapshot already exists.
+ */
+declare function createNextVersion(root: string, vacuumInto: (destination: string) => void): CreateNextVersionResult;
+/**
+ * Path to the DB file for version `v`: `<root>/versions/<v>/app.sqlite`.
+ */
+declare function versionedDbFile(root: string, v: number): string;
+/**
+ * Path to the per-version archive directory `<root>/versions/<v>`.
+ */
+declare function versionedPath(root: string, v: number): string;
+
+type VersionedFolderOps = {
+    /** Ensure the current-version entity folder exists. */
+    ensureFolder(id: string): Promise<void>;
+    /** Remove the current-version entity folder. Swallows missing-path errors. */
+    removeFolder(id: string): Promise<void>;
+    /**
+     * When an entity's files live only under frozen past archives, hard
+     * delete cannot remove those folders; drop a `.deleted` placeholder in
+     * the current-version folder instead.
+     */
+    markDeleted(id: string): Promise<string>;
+    /**
+     * Move the current-version entity folder into `local/trash/` with a
+     * unique directory name. No-op when the source path is missing (same as
+     * a removed folder). Returns the destination path (whether or not a move
+     * occurred).
+     */
+    moveFolderToTrash(id: string): Promise<string>;
+};
+/**
+ * The four lifecycle operations shared by the resource and character
+ * file-system layers. They differ only in which versioned folder they
+ * target and how the trash / placeholder names are derived.
+ *
+ * `moveFolderToTrash` treats `EPERM`/`EBUSY`/`UNKNOWN` as transient Windows
+ * locks (a file inside the folder is still open) and leaves the source in
+ * place; a boot-time orphan sweep reclaims it later.
+ *
+ * `readOnly` is a live `{ current: boolean }` ref (the server's runtime
+ * read-only flag), so a version switch mid-request re-reads it.
+ */
+declare function buildVersionedFolderOps(paths: StoragePaths, readOnly: {
+    readonly current: boolean;
+}, kind: "resource" | "character"): VersionedFolderOps;
+/**
+ * Move every file in `sourceFolder` whose name matches `match` into
+ * `destFolder` under a timestamped archive name (`<prefix><stamp><ext>`, or
+ * `<prefix><stamp>_<i><ext>` when several files match). Moves to the local
+ * (non-synced) directory so replaced files are preserved without polluting
+ * the versions sync scope. Creates `destFolder` on demand; silently ignores
+ * ENOENT on source files and a missing source folder.
+ */
+declare function archiveStaleFiles(args: {
+    readonly sourceFolder: string;
+    readonly destFolder: string;
+    readonly match: (name: string) => boolean;
+    readonly archivePrefix: string;
+}): Promise<void>;
+
+/**
+ * Command that performs a write under the **current** (latest, writable)
+ * archive version. Receiving `paths.latest` instead of the whole
+ * {@link StoragePaths} object makes it impossible for callers to accidentally
+ * target `paths.active`, which may point at a frozen past version when the
+ * server is in read-only viewing mode.
+ */
+type VersionedWriteCommand<T> = (paths: StoragePaths["latest"]) => T | Promise<T>;
+/**
+ * Central gate for every file-system write that lands under `versions/<v>`.
+ *
+ * - Blocks the operation when `readOnly` is true, surfacing a domain conflict
+ *   with code `server.read_only_archive`.
+ * - Forces the command to operate on `paths.latest` (the latest archive
+ *   version) so past frozen versions can never be mutated.
+ *
+ * Local-only writes (thumbs, caches, staging pool, trash) should NOT use this
+ * helper; they live under `local/` and are governed by the route-level
+ * write gate instead.
+ */
+declare function writeVersioned<T>(paths: StoragePaths, readOnly: boolean, cmd: VersionedWriteCommand<T>): Promise<T>;
+
+export { type CreateNextVersionResult, type CreateStoragePathsOptions, type DirSizeOptions, type LocalPaths, ORDER_MANIFEST_NAME, type OccupiedNames, PluginVaultPathError, RESOURCE_DATA_DIR_NAME, type StoragePaths, type VaultCommitResult, type VersionPaths, type VersionedFolderOps, type VersionedWriteCommand, type ZipStreamEntry, archiveStaleFiles, assertInside, assertSafeSegment, buildVersionedFolderOps, commitVaultFile, createNextVersion, createOccupiedNames, createStoragePaths, currentVersion, discardVaultTempFile, ensureBootstrapVersion, extractArchiveInto, findStagedArchiveFile, findStagedPoolFile, imageVariantKey, listArchiveEntries, listVersions, naturalSort, occupyEntryName, orderEntries, orderManifestPath, parseOrderManifest, parsePluginVaultDest, readActiveVersion, readOrderManifest, removeStagedPoolFile, resolveStagedPoolFiles, sanitizeEntryName, streamStoredZip, sumDirSizes, uniqueEntryName, validateArchiveBudget, vaultFileSha256, vaultReadFile, vaultRemoveFile, vaultStatFile, vaultTempFile, vaultTotalSize, versionedDbFile, versionedPath, writeActiveVersion, writeOrderManifest, writeStagedArchiveFile, writeStagedPoolFile, writeVersioned };