cursedbelt-server 1.0.0

package/dist/server/ctgr.js

@@ -0,0 +1,69 @@
+import { ABBREV_TO_METHOD, METHOD_TO_ABBREV, } from 'cursedbelt-core/ctgr/types';
+import { V0ChunkStore } from 'cursedbelt-core/ctgr/v0compat';
+import { ApiError, toErrorEnvelope } from './errors';
+/**
+ * The path pattern that matches EVERY ctgr GET twin (`/ctgr<XX>...`) and nothing
+ * else — mount the decode + CSRF + getOnly middleware on this. NOTE: Hono's router
+ * does not treat `/ctgr*` as a prefix wildcard (a bare-suffix `*` only matches a
+ * single following segment), so a named param with a `ctgr.+` regex is the correct,
+ * portable matcher (`.` spans `/`, so it covers multi-segment paths like
+ * `/ctgrpa/api/v1/lists/123`). Reuse this everywhere a `/ctgr*` mount is meant.
+ */
+export const CTGR_ROUTE_PATTERN = '/:ctgrTwin{ctgr.+}';
+/**
+ * Mount on {@link CTGR_ROUTE_PATTERN} (before the twin routes). A single chunk decodes
+ * inline; a multi-chunk payload accumulates in the injected {@link ChunkStore}
+ * (intermediate chunk → 202). The decoded request + method are stashed on the context for the
+ * downstream handler / validator (`c.get('ctgrDecoded')`). Legacy `_cv`-absent
+ * requests fall back to the v0 decoder for the rollout window.
+ */
+export function unGETify(store) {
+    const legacy = new V0ChunkStore();
+    return async (c, next) => {
+        const params = Object.fromEntries(new URL(c.req.url).searchParams);
+        const pathMethod = ABBREV_TO_METHOD[c.req.path.slice(5, 7)];
+        if (!pathMethod) {
+            return c.json(toErrorEnvelope(new ApiError(400, 'ctgr: unknown method twin', { code: 'unknown_method' })), 400);
+        }
+        const result = params._cv === undefined ? legacy.add(params, pathMethod) : await store.add(params);
+        if (result === false)
+            return c.json({ acknowledged: true }, 202);
+        if (result instanceof Error)
+            return c.json(toErrorEnvelope(new ApiError(400, result.message, { code: 'ctgr_decode_failed' })), 400);
+        c.set('ctgrDecoded', result);
+        c.set('ctgrMethod', result.method);
+        await next();
+    };
+}
+/** Read the ctgr-decoded request a `/ctgr*` twin stashed, if this was a tunneled call. */
+export function getCtgrDecoded(c) {
+    return c.get('ctgrDecoded');
+}
+/**
+ * Twin registrar: one call registers the real verb route AND its `/ctgr<XX>` GET twin
+ * (same handlers; the global `/ctgr*` {@link unGETify} middleware decodes the body
+ * first). Binary/download routes MUST NOT go through this — register those as a plain
+ * `app.get(path, handler)` so their bytes never ride the base64url tunnel and get
+ * mangled.
+ */
+export function buildRoutes(app) {
+    const on = app.on.bind(app);
+    return function register(method, path, 
+    /*
+     * `H`, not `MiddlewareHandler`. These are ROUTE handlers: Hono's
+     * `MiddlewareHandler` must return `Promise<Response | void>`, so declaring it
+     * here forced every caller to be `async` for no reason — a plain
+     * `(c) => c.json(…)` did not typecheck against a registrar whose whole job is
+     * registering exactly that. `H` is Hono's own union of both kinds and is what
+     * `app.on` accepts.
+     */
+    ...handlers) {
+        const upper = method.toUpperCase();
+        const abbrev = METHOD_TO_ABBREV[upper];
+        if (!abbrev)
+            throw new Error(`buildRoutes: "${method}" is not a ctgr-tunnelable method`);
+        // The real verb route + its GET twin, from one call.
+        on(upper, path, ...handlers);
+        on('GET', `/ctgr${abbrev}${path}`, ...handlers);
+    };
+}

package/dist/server/db/kysely.d.ts

@@ -0,0 +1,14 @@
+import type { Database } from 'bun:sqlite';
+import { Kysely } from 'kysely';
+import type { PlumbingSchema } from './plumbingTypes';
+/**
+ * A Kysely query builder typed to the {@link PlumbingSchema} plumbing tables, on the
+ * `bun:sqlite` dialect. Use it for type-checked reads/writes of sessions, config,
+ * logs, metrics, and jobs. Business / `data JSON` tables stay on raw `db.query()` —
+ * do NOT add them here (that would couple the Kysely schema to every feature table).
+ *
+ * The dialect wraps the SAME `Database` handle the rest of the app uses, so there is
+ * one connection, one WAL, one transaction space.
+ */
+export declare function createKysely(db: Database): Kysely<PlumbingSchema>;
+export type PlumbingDb = Kysely<PlumbingSchema>;

package/dist/server/db/kysely.js

@@ -0,0 +1,16 @@
+import { Kysely } from 'kysely';
+import { BunSqliteDialect } from 'kysely-bun-sqlite';
+/**
+ * A Kysely query builder typed to the {@link PlumbingSchema} plumbing tables, on the
+ * `bun:sqlite` dialect. Use it for type-checked reads/writes of sessions, config,
+ * logs, metrics, and jobs. Business / `data JSON` tables stay on raw `db.query()` —
+ * do NOT add them here (that would couple the Kysely schema to every feature table).
+ *
+ * The dialect wraps the SAME `Database` handle the rest of the app uses, so there is
+ * one connection, one WAL, one transaction space.
+ */
+export function createKysely(db) {
+    return new Kysely({
+        dialect: new BunSqliteDialect({ database: db }),
+    });
+}

package/dist/server/db/plumbingTypes.d.ts

@@ -0,0 +1,116 @@
+/**
+ * TypeScript row interfaces for the *plumbing* tables — the structural, non-business
+ * tables cursedbelt owns: sessions, config, logs, metrics, jobs, the migration
+ * sentinel. These get Kysely-typed access (see `./kysely`) so the toolkit's own
+ * queries are type-checked.
+ *
+ * Business / feature tables (notes, lists, shares, …) deliberately stay OUT of this
+ * schema: they keep raw `db.query()` + flexible `data JSON`, so the Kysely schema is
+ * not coupled to every feature table. Shapes mirror the canonical DDL (task 22,
+ * `0001_initial`). INTEGER booleans are kept as `number` (SQLite has no real bool).
+ */
+export interface AuthSessionRow {
+    session_id: string;
+    user_id: string;
+    created_at: string;
+    last_seen_at: string;
+    refresh_expires_at: string;
+    access_expires_at: string | null;
+    /** 0 | 1 — the `/f` GET-only restriction, enforced + audited per session. */
+    get_only: number;
+    /** 0 | 1 */
+    disabled: number;
+    disabled_at: string | null;
+    disabled_by: string | null;
+    user_agent: string | null;
+    ip: string | null;
+}
+export interface AppConfigRow {
+    key: string;
+    value: string;
+    updated_at: string;
+    updated_by: string | null;
+}
+export interface EventLogRow {
+    id: string;
+    correlation_id: string | null;
+    event_name: string;
+    /** info | warn | error (free text, defaults to 'info'). */
+    type: string;
+    message: string | null;
+    /** JSON blob of structured detail. */
+    details: string | null;
+    duration_ms: number | null;
+    user_id: string | null;
+    created_at: string;
+}
+export interface RequestMetricRow {
+    id: string;
+    /** Epoch ms. */
+    ts: number;
+    method: string | null;
+    route: string | null;
+    status: number | null;
+    duration_ms: number | null;
+    bytes_out: number | null;
+    user_id: string | null;
+}
+export interface SystemSampleRow {
+    id: string;
+    /** Epoch ms. */
+    ts: number;
+    rss: number | null;
+    heap_used: number | null;
+    heap_total: number | null;
+    os_used: number | null;
+    os_total: number | null;
+    uptime_s: number | null;
+    event_loop_lag_ms: number | null;
+    ws_clients: number | null;
+    req_count: number | null;
+    err_count: number | null;
+    avg_duration_ms: number | null;
+}
+export interface EmailFailureRow {
+    id: string;
+    created_at: string;
+    recipient: string;
+    subject: string;
+    /** Defaults to 'send_error'. */
+    reason: string;
+    error_name: string | null;
+    error_code: string | null;
+    error_message: string | null;
+    details: string | null;
+}
+export interface JobStateRow {
+    name: string;
+    last_run_at: string | null;
+    /** JSON blob. */
+    meta: string | null;
+}
+export interface JobRunRow {
+    id: string;
+    job_name: string;
+    started_at: string;
+    ended_at: string | null;
+    /** running | ok | error (defaults to 'running'). */
+    status: string;
+    error: string | null;
+}
+export interface MigrationRow {
+    name: string;
+    applied_at: string;
+}
+/** The Kysely database schema for cursedbelt plumbing tables. */
+export interface PlumbingSchema {
+    auth_sessions: AuthSessionRow;
+    app_config: AppConfigRow;
+    event_logs: EventLogRow;
+    request_metrics: RequestMetricRow;
+    system_samples: SystemSampleRow;
+    email_failures: EmailFailureRow;
+    job_state: JobStateRow;
+    job_runs: JobRunRow;
+    _migrations: MigrationRow;
+}

package/dist/server/db/plumbingTypes.js

@@ -0,0 +1,12 @@
+/**
+ * TypeScript row interfaces for the *plumbing* tables — the structural, non-business
+ * tables cursedbelt owns: sessions, config, logs, metrics, jobs, the migration
+ * sentinel. These get Kysely-typed access (see `./kysely`) so the toolkit's own
+ * queries are type-checked.
+ *
+ * Business / feature tables (notes, lists, shares, …) deliberately stay OUT of this
+ * schema: they keep raw `db.query()` + flexible `data JSON`, so the Kysely schema is
+ * not coupled to every feature table. Shapes mirror the canonical DDL (task 22,
+ * `0001_initial`). INTEGER booleans are kept as `number` (SQLite has no real bool).
+ */
+export {};

package/dist/server/dropzone/duplicates.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Asking binary-server "do you already have this?" — the client half.
+ *
+ * Owner's ask, 2026-08-13: *"make strategy to always check for duplicate binaries in same app
+ * for same user, automatically skip if it's literally a duplicate file"* … *"if it's an
+ * automated upload with ingestions or an agent guiding it and I need to make a decision put it
+ * in binary-server UI for me to see and handle it."*
+ *
+ * ── 🔴 Asked BEFORE the bytes move, and that ordering is the whole point ───────────────
+ * The obvious design is upload-then-detect: store it, notice the collision, delete one. That
+ * moves every duplicate twice, and on a media dropzone it does so for multi-gigabyte video the
+ * store already holds. The scraper has the file, so it has the digest; one small POST answers
+ * the question before a single byte is sent.
+ *
+ * ── 🔴 It lives in cursedbelt, not in satellite-kit ────────────────────────────────────
+ * binary-server itself consumes `cursedbelt` and does NOT consume `satellite-kit`, and every
+ * ingesting app consumes both. This is the one shelf both sides can see. It is also the reason
+ * the request/response shape is stated here as types rather than being re-declared by each
+ * caller — a dropzone that got `hold` backwards would upload exactly the files the owner asked
+ * it to park.
+ */
+export interface DuplicateQuestion {
+    /** binary-server's loopback origin. Never the public tunnel — see the note below. */
+    baseUrl: string;
+    /** The shared internal secret; this route is internal-only and 403s without it. */
+    internalSecret: string;
+    /** The binary-server tenant, e.g. `music`. */
+    app: string;
+    /** Scope the comparison to one user. Null on the owner-only apps, which is normal. */
+    ownerId?: string | null;
+    /** sha256 of the bytes about to be uploaded, hex. {@link hashFile} produces it. */
+    checksum: string;
+    size: number;
+    /** The name the object would carry — what the "same name" half of the rule compares. */
+    name: string;
+    /** Where the file is right now, so the owner's later decision can act on it. */
+    heldPath?: string | null;
+}
+export interface DuplicateVerdict {
+    /** Present when the store already holds these exact bytes. Skip the upload entirely. */
+    exact: {
+        key: string;
+        title: string | null;
+        size: number;
+    } | null;
+    /** Name-alikes with different bytes — a question, never an instruction. */
+    likely: {
+        key: string;
+        title: string | null;
+        size: number;
+        reason: string;
+    }[];
+    /** True when the caller must NOT upload and must park the file for the owner. */
+    hold: boolean;
+    /** The review-queue row binary-server filed, when it filed one. */
+    candidateId: string | null;
+}
+/**
+ * Streaming sha256 of a file on disk.
+ *
+ * Streamed rather than buffered because a music library is thousands of files and some of them
+ * are 60 MB; reading each one whole to hash it is how an ingest becomes a memory problem.
+ */
+export declare function hashFile(path: string): Promise<string>;
+/**
+ * Ask binary-server about one incoming file.
+ *
+ * 🔴 **Fails OPEN, deliberately.** If binary-server cannot be reached, or answers something
+ * unexpected, the verdict is "no duplicate, do not hold" and the ingest proceeds. The
+ * alternative is that a dropzone stops taking the owner's files because a de-duplication
+ * nicety is down — trading a real capability for a housekeeping one. A duplicate that slips
+ * through costs disk and is found later by the scan button, which is exactly what that button
+ * is for.
+ *
+ * 🔴 **`baseUrl` must be the LOOPBACK origin.** The route is absent from binary-server's
+ * public path allowlist and 404s when the request arrives bearing the public tunnel Host —
+ * because it reports the titles and sizes of stored objects, and listing is what the tunnel
+ * must never publish. A caller that passes the public URL gets a 404 and, through the
+ * fail-open above, silently loses de-duplication entirely. notes shipped this exact bug once
+ * with `/api/transcode`.
+ */
+export declare function askBinaryServerAboutDuplicate(q: DuplicateQuestion): Promise<DuplicateVerdict>;

package/dist/server/dropzone/duplicates.js

@@ -0,0 +1,90 @@
+/**
+ * Asking binary-server "do you already have this?" — the client half.
+ *
+ * Owner's ask, 2026-08-13: *"make strategy to always check for duplicate binaries in same app
+ * for same user, automatically skip if it's literally a duplicate file"* … *"if it's an
+ * automated upload with ingestions or an agent guiding it and I need to make a decision put it
+ * in binary-server UI for me to see and handle it."*
+ *
+ * ── 🔴 Asked BEFORE the bytes move, and that ordering is the whole point ───────────────
+ * The obvious design is upload-then-detect: store it, notice the collision, delete one. That
+ * moves every duplicate twice, and on a media dropzone it does so for multi-gigabyte video the
+ * store already holds. The scraper has the file, so it has the digest; one small POST answers
+ * the question before a single byte is sent.
+ *
+ * ── 🔴 It lives in cursedbelt, not in satellite-kit ────────────────────────────────────
+ * binary-server itself consumes `cursedbelt` and does NOT consume `satellite-kit`, and every
+ * ingesting app consumes both. This is the one shelf both sides can see. It is also the reason
+ * the request/response shape is stated here as types rather than being re-declared by each
+ * caller — a dropzone that got `hold` backwards would upload exactly the files the owner asked
+ * it to park.
+ */
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+/**
+ * Streaming sha256 of a file on disk.
+ *
+ * Streamed rather than buffered because a music library is thousands of files and some of them
+ * are 60 MB; reading each one whole to hash it is how an ingest becomes a memory problem.
+ */
+export function hashFile(path) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash("sha256");
+        const stream = createReadStream(path);
+        stream.on("error", reject);
+        stream.on("data", (chunk) => hash.update(chunk));
+        stream.on("end", () => resolve(hash.digest("hex")));
+    });
+}
+/**
+ * Ask binary-server about one incoming file.
+ *
+ * 🔴 **Fails OPEN, deliberately.** If binary-server cannot be reached, or answers something
+ * unexpected, the verdict is "no duplicate, do not hold" and the ingest proceeds. The
+ * alternative is that a dropzone stops taking the owner's files because a de-duplication
+ * nicety is down — trading a real capability for a housekeeping one. A duplicate that slips
+ * through costs disk and is found later by the scan button, which is exactly what that button
+ * is for.
+ *
+ * 🔴 **`baseUrl` must be the LOOPBACK origin.** The route is absent from binary-server's
+ * public path allowlist and 404s when the request arrives bearing the public tunnel Host —
+ * because it reports the titles and sizes of stored objects, and listing is what the tunnel
+ * must never publish. A caller that passes the public URL gets a 404 and, through the
+ * fail-open above, silently loses de-duplication entirely. notes shipped this exact bug once
+ * with `/api/transcode`.
+ */
+export async function askBinaryServerAboutDuplicate(q) {
+    const none = { exact: null, likely: [], hold: false, candidateId: null };
+    if (!q.internalSecret)
+        return none;
+    try {
+        const res = await fetch(`${q.baseUrl.replace(/\/+$/, "")}/internal/ops/duplicates/check`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "x-internal-secret": q.internalSecret,
+            },
+            body: JSON.stringify({
+                app: q.app,
+                ownerId: q.ownerId ?? null,
+                checksum: q.checksum,
+                size: q.size,
+                name: q.name,
+                origin: "automated",
+                heldPath: q.heldPath ?? null,
+            }),
+        });
+        if (!res.ok)
+            return none;
+        const body = (await res.json());
+        return {
+            exact: body.exact ?? null,
+            likely: body.likely ?? [],
+            hold: body.hold === true,
+            candidateId: body.candidateId ?? null,
+        };
+    }
+    catch {
+        return none;
+    }
+}

package/dist/server/dropzone/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `cursedbelt-server/dropzone` — the reusable drop-folder scraper.
+ *
+ * Drop a tree of files into a folder; a sweep walks it, hands each file to the app's handler,
+ * deletes only what the handler confirmed was filed somewhere else, and prunes the folders it
+ * empties. Nothing app-specific lives here: what a file MEANS is the app's, what happens to a
+ * file on disk is this module's.
+ *
+ * Consumers (2026-08-13): `apps/music`, `apps/family`, `apps/collections` in
+ * cursed-satellites. Each supplies a `DropHandler` and nothing else.
+ */
+export { describeSweep, isJunkName, isStable, pruneEmptyDirs, scanDropzone, sweepDropzone, type DropHandler, type DropOutcome, type DroppedFile, type ScanOptions, type SweepReport, } from "./scan";
+export { askBinaryServerAboutDuplicate, hashFile, type DuplicateVerdict, type DuplicateQuestion, } from "./duplicates";

package/dist/server/dropzone/index.js

@@ -0,0 +1,13 @@
+/**
+ * `cursedbelt-server/dropzone` — the reusable drop-folder scraper.
+ *
+ * Drop a tree of files into a folder; a sweep walks it, hands each file to the app's handler,
+ * deletes only what the handler confirmed was filed somewhere else, and prunes the folders it
+ * empties. Nothing app-specific lives here: what a file MEANS is the app's, what happens to a
+ * file on disk is this module's.
+ *
+ * Consumers (2026-08-13): `apps/music`, `apps/family`, `apps/collections` in
+ * cursed-satellites. Each supplies a `DropHandler` and nothing else.
+ */
+export { describeSweep, isJunkName, isStable, pruneEmptyDirs, scanDropzone, sweepDropzone, } from "./scan";
+export { askBinaryServerAboutDuplicate, hashFile, } from "./duplicates";

package/dist/server/dropzone/scan.d.ts

@@ -0,0 +1,166 @@
+/**
+ * The drop-folder scraper — the reusable half.
+ *
+ * Owner's ask, 2026-08-13: *"Do this to prepare a reusable strategy for multiple apps to get
+ * intelligent processing for binary-server. Some functionality may be reusable in multiple
+ * apps in different ways and can go in cb where standardized app functionality is shared. The
+ * specific ingestion logic that only binary-server or one app needs can go to the specific
+ * app."* … *"Make this tool reusable in case we need something like it on other folders
+ * later."*
+ *
+ * So: WALKING a drop folder, deciding a file has finished copying, sorting content from junk,
+ * deleting only what has been confirmed elsewhere, and leaving nothing behind — all of that is
+ * the same for music, family photographs, collections videos and notes documents, and all of
+ * it is here. What a file MEANS — which album, which artist, which collection — is the app's,
+ * and none of it is here.
+ *
+ * ── 🔴 Three rules that look like paranoia and are not ─────────────────────────────────
+ *
+ * 1. **A file is deleted only after the destination CONFIRMS it.** The dropzone is the one
+ *    place the owner's copy may be the only copy: they dragged it in expecting it to be taken.
+ *    A sweep that deletes on "the upload didn't throw" turns any catalog failure into data
+ *    loss. The handler returns `stored`/`duplicate` and only then does the original go.
+ *
+ * 2. **A file must measure the same size twice before it is touched.** Dropping a 4 GB video
+ *    into a folder is not atomic. Without this the sweep ingests a truncated file, reports
+ *    success, and deletes the real one as it is still being written. notes' ingester and
+ *    collections' both learned this the same way.
+ *
+ * 3. **One bad file never stops the sweep.** Every handler outcome is per-file, and a throw is
+ *    caught and recorded. The owner's instruction is explicit about the duplicate case — *"This
+ *    should not stall uploading the rest of the in progress uploads"* — and it generalizes: a
+ *    dropzone with one unreadable file in it must still drain the other 4,000.
+ */
+/** A file the sweep found, with everything a handler needs to decide about it. */
+export interface DroppedFile {
+    /** Absolute path on disk. */
+    path: string;
+    /** Path relative to the dropzone root — the app's only clue about where it was filed. */
+    relativePath: string;
+    /** The filename, no directories. */
+    name: string;
+    /** Lowercased extension INCLUDING the dot, or `""` for a file that has none. */
+    ext: string;
+    size: number;
+    mtimeMs: number;
+    /** Every other FILE name in the same directory — see {@link ScanOptions.captureSiblings}. */
+    siblings: string[];
+}
+export type DropOutcome = 
+/** Filed successfully. The original is deleted. */
+{
+    kind: "stored";
+    detail?: string;
+}
+/** Already present at the destination. The original is deleted — that is the point. */
+ | {
+    kind: "duplicate";
+    detail?: string;
+}
+/** Not content: junk, an unusable sidecar, a format this app does not take. DELETED. */
+ | {
+    kind: "discard";
+    detail?: string;
+}
+/** Deliberately parked (a duplicate awaiting a decision). LEFT ALONE, not retried loudly. */
+ | {
+    kind: "held";
+    detail?: string;
+}
+/** Could not be filed. LEFT IN PLACE and reported. */
+ | {
+    kind: "failed";
+    detail: string;
+};
+export interface SweepReport {
+    scanned: number;
+    stored: number;
+    duplicate: number;
+    discarded: number;
+    held: number;
+    failed: {
+        relativePath: string;
+        error: string;
+    }[];
+    /** Files still being copied in — they are picked up by the next sweep, not an error. */
+    unstable: string[];
+    bytesRemoved: number;
+    emptyDirsRemoved: number;
+    /** Anything left in the root when the sweep finished. Empty is the goal. */
+    remaining: number;
+}
+export interface ScanOptions {
+    /** Two size samples this far apart prove a copy finished. */
+    stabilityMs?: number;
+    /** Names that are never content, on top of the built-in OS list. */
+    reservedNames?: string[];
+    /**
+     * Capture each directory's file listing on the ONE walk.
+     *
+     * 🔴 Load-bearing for sidecar art, and it cannot be done later. A folder's `cover.jpg` is
+     * only reachable while the directory still exists, and filing the audio out of it removes
+     * the neighbours — by the time anything else could look, they are gone. Capturing on the
+     * walk also costs one `readdir` per directory instead of one per file, which on a 6,000
+     * track library is the difference between seconds and minutes.
+     */
+    captureSiblings?: boolean;
+    /** Directory names to skip entirely at any depth (another app's queue, our own state). */
+    skipDirs?: string[];
+    /** Stop after this many files. Absent means everything. */
+    limit?: number;
+}
+/** A name that is OS noise, editor scratch, or a copy still in flight. */
+export declare function isJunkName(name: string): boolean;
+/**
+ * Every candidate file under `root`, deepest-last, with each one's sibling listing.
+ *
+ * Junk is NOT filtered out here — it is returned like anything else, because a sweep whose job
+ * includes *"if it's a wrong type of file delete it"* has to see it in order to delete it.
+ * {@link isJunkName} is exported so a handler can classify without re-deriving the list.
+ */
+export declare function scanDropzone(root: string, opts?: ScanOptions): Promise<DroppedFile[]>;
+/**
+ * How old an EMPTY file has to be before it is believed. See {@link isStable}.
+ *
+ * A file that has just been created and has no bytes yet is almost certainly mid-copy; the
+ * same file a minute later really is empty.
+ */
+export declare const EMPTY_FILE_GRACE_MS = 60000;
+/**
+ * Has this file finished being copied in? See rule 2 in the header.
+ *
+ * 🔴 A zero-byte file needs its own answer, and getting it wrong strands the folder forever.
+ * The obvious test — "same size twice AND non-empty" — treats a genuinely empty file as
+ * permanently mid-copy: it is never handled, never deleted, and so the dropzone never empties,
+ * which is the one outcome the owner's brief measures success by (*"in the end there should be
+ * nothing left"*). Measured on a first run: three real files, all 0 bytes, reported as "still
+ * copying" on every sweep for as long as they sat there.
+ *
+ * Emptiness is only evidence of an unfinished copy while the file is NEW, so age decides. A
+ * file created a minute ago with no bytes in it is empty, not arriving.
+ */
+export declare function isStable(file: DroppedFile, stabilityMs?: number): Promise<boolean>;
+/**
+ * Remove directories left empty by a sweep, deepest first — and never the root.
+ *
+ * 🔴 `rmdir` refuses a non-empty directory, and that refusal IS the safety property. A
+ * recursive delete here would take a file the sweep deliberately chose not to ingest — a held
+ * duplicate, a failure left in place for the owner to look at — which is precisely the set of
+ * files that must survive.
+ */
+export declare function pruneEmptyDirs(root: string, dir?: string): Promise<number>;
+/** What the app supplies: what to do with one file. */
+export type DropHandler = (file: DroppedFile) => Promise<DropOutcome>;
+/**
+ * Walk a dropzone, hand every file to `handle`, and leave nothing behind that was dealt with.
+ *
+ * 🔴 The DELETION is here, and it is deliberately not the handler's job. Every app would
+ * otherwise reimplement rule 1, and the one that got it wrong would lose the owner's only copy
+ * silently. A handler says what happened; this decides what that means for the file on disk.
+ */
+export declare function sweepDropzone(root: string, handle: DropHandler, opts?: ScanOptions & {
+    dryRun?: boolean;
+    onProgress?: (done: number, total: number) => void;
+}): Promise<SweepReport>;
+/** A one-line summary — every consumer prints one, and they should read alike. */
+export declare const describeSweep: (report: SweepReport) => string;