@vryzel/file-next 0.4.0

package/dist/filesystem-D1Jjx3md.d.ts

@@ -0,0 +1,830 @@
+import { FileSystemError } from './errors/index.js';
+import { z } from 'zod';
+
+/**
+ * Discriminated `Result<T, E>` for typed error returns.
+ *
+ * Why Result over throw at boundaries:
+ *   - No `any` at the call site (vs try/catch which loses the type).
+ *   - `switch (r.ok)` narrows the type in consumer code.
+ *   - The wire shape `{ ok, value | error }` is JSON-serializable,
+ *     so it survives the RSC boundary without an extra DTO.
+ *   - Helpers (`map`, `andThen`, `unwrap`) make the common shapes
+ *     (chain, bail-out, recover) terse and exhaustive.
+ *
+ * The default error type is `FileSystemError` (see `@/errors`).
+ * Consumers can specialize: `Result<User, ZodError>`.
+ *
+ * All helpers are pure functions; they do NOT allocate closures in
+ * hot paths beyond what the spec demands (no `try`/`catch` wrapping).
+ */
+
+type Result<T, E = FileSystemError> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: E;
+};
+declare const ok: <T>(value: T) => Result<T, never>;
+declare const err: <E>(error: E) => Result<never, E>;
+declare const map: <T, U, E>(r: Result<T, E>, f: (t: T) => U) => Result<U, E>;
+declare const mapErr: <T, E, F>(r: Result<T, E>, f: (e: E) => F) => Result<T, F>;
+declare const andThen: <T, U, E>(r: Result<T, E>, f: (t: T) => Result<U, E>) => Result<U, E>;
+declare const unwrap: <T, E>(r: Result<T, E>) => T;
+declare const unwrapOr: <T, E>(r: Result<T, E>, fallback: T) => T;
+
+/**
+ * Branded string types and their constructors/guards.
+ *
+ * Brands are TypeScript-only fictions: a `Path` and an `S3Key` are
+ * both strings at runtime, but the type system treats them as
+ * distinct nominal types so the compiler catches accidental
+ * cross-assignment (e.g. passing an S3Key where a TenantId is
+ * expected).
+ *
+ * Conventions:
+ *   - `as*` is a zero-cost cast: trust the caller, brand the value.
+ *     Use it at trust boundaries you have already validated.
+ *   - `assert*` is a runtime guard: throws TypeError on invalid
+ *     input. Use it at the edge (parsing user/env input).
+ *
+ * Validation rules are intentionally minimal in v0.1 and can be
+ * tightened as the spec evolves. None of them touch the network or
+ * allocate; they are safe in hot paths.
+ */
+type Path = string & {
+    readonly __brand: "Path";
+};
+type Prefix = string & {
+    readonly __brand: "Prefix";
+};
+type S3Key = string & {
+    readonly __brand: "S3Key";
+};
+type TenantId = string & {
+    readonly __brand: "TenantId";
+};
+type UserId = string & {
+    readonly __brand: "UserId";
+};
+/**
+ * POSIX file path. Non-empty, '/' is allowed as the root.
+ */
+declare const asPath: (s: string) => Path;
+declare const assertPath: (s: string) => Path;
+/**
+ * S3 prefix. Empty string is the root prefix. Non-empty prefixes
+ * MUST end with '/' so concatenation with a key never produces
+ * 'usersfile.jpg' by accident.
+ */
+declare const asPrefix: (s: string) => Prefix;
+declare const assertPrefix: (s: string) => Prefix;
+/**
+ * S3 object key. No leading slash, no empty segments, no '..' hops.
+ */
+declare const asS3Key: (s: string) => S3Key;
+declare const assertS3Key: (s: string) => S3Key;
+/**
+ * Tenant identifier. Alphanumerics, dashes, underscores only.
+ */
+declare const asTenantId: (s: string) => TenantId;
+declare const assertTenantId: (s: string) => TenantId;
+/**
+ * Opaque user identifier. Non-empty; the format is provider-defined.
+ */
+declare const asUserId: (s: string) => UserId;
+declare const assertUserId: (s: string) => UserId;
+
+/**
+ * S3CompatibleAdapter — the 17-method interface every storage
+ * provider implements in `file-next`.
+ *
+ * Design reference: `sdd/file-next/design` §E.
+ *
+ * Why a custom interface instead of using the AWS SDK v3 `S3Client`
+ * directly:
+ *   1. **Provider portability** — Cloudflare R2, Backblaze B2, MinIO,
+ *      and any future provider all speak the S3 wire protocol but
+ *      expose it through different SDKs (or none at all). The
+ *      interface is the single chokepoint; the rest of the codebase
+ *      programs against the contract, not the SDK.
+ *   2. **Result-typed returns** — every method returns
+ *      `Promise<Result<T, FileSystemError>>`. No `try`/`catch` at
+ *      call sites, no `any` smuggling, no swallowed rejections.
+ *   3. **Testability** — the entire adapter can be replaced with a
+ *      17-method mock in tests; the rest of the library (factory,
+ *      MetadataStore, server actions) never has to know whether it
+ *      is running against the real AWS SDK or a stub.
+ *   4. **Stable wire shape** — the input/output types are pure data
+ *      (no `Date` in the serialized form, no class instances), so
+ *      they survive RSC serialization and the route-handler
+ *      boundary.
+ *
+ * Method count is a deliberate design choice: see
+ * `sdd/file-next/design/decision/adapter-method-count`. The 13
+ * object-CRUD methods were the v0.1 surface; v0.2 adds 4 multipart
+ * primitives (`createMultipartUpload`, `uploadPart`,
+ * `completeMultipartUpload`, `abortMultipartUpload`) so providers
+ * that support chunked uploads expose them through the same
+ * Result-typed contract. The 13th method (`getPublicUrl`) is
+ * intentionally separate from the presigned-URL family so that
+ * providers which can't issue presigned URLs (public buckets,
+ * local dev backends) can still satisfy the shape by returning a
+ * plain URL.
+ *
+ * Conventions:
+ *   - All methods are async (returning `Promise<Result<...>>`).
+ *   - All methods take a single typed input object (no positional
+ *     args beyond the first) so future fields are non-breaking.
+ *   - All key-bearing inputs use the `S3Key` brand; all prefix-
+ *     bearing inputs use the `Prefix` brand.
+ *   - Errors are always `FileSystemError` (the 11-code catalog from
+ *     `@/errors`). Provider-specific codes (S3 `NoSuchKey`, etc.)
+ *     go on `cause.code`, not on the top-level `code`.
+ */
+
+interface ListInput {
+    /** S3 prefix to list under. Empty string is the bucket root. */
+    prefix?: Prefix;
+    /** Opaque continuation token from a prior `ListOutput`. */
+    continuationToken?: string;
+    /** Soft cap on the number of items returned. Providers may honor or ignore. */
+    limit?: number;
+    /**
+     * Character used to group keys (S3's "folder" emulation). Pass
+     * "/" to get back `prefixes` for each sub-folder, with `items`
+     * containing only the files at the current level. Omit for a
+     * flat recursive listing.
+     */
+    delimiter?: string;
+}
+interface ReadInput {
+    key: S3Key;
+    /** Optional byte range (`bytes=0-1023`). Provider-specific semantics. */
+    range?: string;
+}
+interface WriteInput {
+    key: S3Key;
+    body: Uint8Array | ReadableStream<Uint8Array>;
+    contentType?: string;
+    /** Free-form user metadata stored alongside the object. */
+    metadata?: Record<string, string>;
+}
+interface DeleteInput {
+    key: S3Key;
+}
+interface MoveInput {
+    sourceKey: S3Key;
+    destinationKey: S3Key;
+}
+interface CopyInput {
+    sourceKey: S3Key;
+    destinationKey: S3Key;
+}
+interface StatInput {
+    key: S3Key;
+}
+interface ExistsInput {
+    key: S3Key;
+}
+interface GetMetadataInput {
+    key: S3Key;
+}
+interface SetMetadataInput {
+    key: S3Key;
+    metadata: Record<string, string>;
+    /**
+     * `false` (default) merges with existing user metadata; `true`
+     * replaces it entirely. Provider semantics may differ; adapters
+     * normalize.
+     */
+    replace?: boolean;
+}
+interface PresignedUploadInput {
+    key: S3Key;
+    contentType?: string;
+    /** Expiry in seconds. Providers enforce a max (e.g. 7 days for S3). */
+    expiresIn?: number;
+}
+interface PresignedDownloadInput {
+    key: S3Key;
+    expiresIn?: number;
+}
+interface GetPublicUrlInput {
+    key: S3Key;
+}
+/**
+ * Multipart upload primitives (v0.2).
+ *
+ * S3's chunked upload protocol is a four-step dance:
+ *   1. `createMultipartUpload` returns an opaque `uploadId`.
+ *   2. `uploadPart` (one or more) returns the `etag` per chunk.
+ *   3. `completeMultipartUpload` finalises the object by listing
+ *      the parts (in any order — S3 honours the caller's order).
+ *   4. On any failure, `abortMultipartUpload` cleans up the
+ *      unfinished state on the server (parts are billed until
+ *      either complete or abort runs).
+ *
+ * The four primitives are exposed individually so the higher-level
+ * `write` method can compose them, but they are also public so
+ * server actions or stream-multiplexers can drive the protocol
+ * themselves.
+ */
+interface CreateMultipartUploadInput {
+    key: S3Key;
+    contentType?: string;
+    metadata?: Record<string, string>;
+}
+interface UploadPartInput {
+    key: S3Key;
+    uploadId: string;
+    partNumber: number;
+    body: Uint8Array;
+}
+interface CompleteMultipartUploadInput {
+    key: S3Key;
+    uploadId: string;
+    /**
+     * Parts in the order the caller wants them assembled. S3
+     * honours this order (it is not required to be sorted by
+     * partNumber).
+     */
+    parts: Array<{
+        partNumber: number;
+        etag: string;
+    }>;
+}
+interface AbortMultipartUploadInput {
+    key: S3Key;
+    uploadId: string;
+}
+interface ListOutput {
+    items: Array<{
+        key: S3Key;
+        size: number;
+        lastModified: Date;
+    }>;
+    /** Sub-prefixes discovered under `prefix` (S3 CommonPrefixes). */
+    prefixes: Array<Prefix>;
+    /** Opaque token; `undefined` means the listing is complete. */
+    nextContinuationToken?: string;
+}
+interface ReadOutput {
+    body: Uint8Array;
+    contentType?: string;
+    metadata?: Record<string, string>;
+}
+interface WriteOutput {
+    etag: string;
+    versionId?: string;
+}
+interface DeleteOutput {
+    [k: string]: unknown;
+}
+/**
+ * Side-effect outputs are intentionally empty `{}`. Providers MAY
+ * populate additional fields (etag, versionId, existed, ...) in
+ * practice, but the interface contract is the minimum guarantee.
+ * Callers needing provider-specific metadata should use `stat` or
+ * `getMetadata` instead.
+ */
+interface MoveOutput {
+    [k: string]: unknown;
+}
+interface CopyOutput {
+    [k: string]: unknown;
+}
+interface StatOutput {
+    key: S3Key;
+    size: number;
+    etag: string;
+    contentType: string;
+    lastModified: Date;
+    metadata: Record<string, string>;
+}
+interface ExistsOutput {
+    exists: boolean;
+}
+interface GetMetadataOutput {
+    [k: string]: unknown;
+}
+interface SetMetadataOutput {
+    [k: string]: unknown;
+}
+interface PresignedUploadOutput {
+    url: string;
+    method: "PUT" | "POST";
+    /** Required HTTP headers the client MUST send on the upload. */
+    requiredHeaders?: Record<string, string>;
+}
+interface PresignedDownloadOutput {
+    url: string;
+}
+interface GetPublicUrlOutput {
+    url: string;
+}
+interface CreateMultipartUploadOutput {
+    uploadId: string;
+    /** Echo of the input key, branded. Lets the caller chain without re-casting. */
+    key: S3Key;
+}
+interface UploadPartOutput {
+    etag: string;
+    /** Echo of the input part number for the caller's bookkeeping. */
+    partNumber: number;
+}
+interface CompleteMultipartUploadOutput {
+    etag?: string;
+    versionId?: string;
+}
+/** Side-effect outputs are intentionally empty (see note on DeleteOutput). */
+interface AbortMultipartUploadOutput {
+    [k: string]: unknown;
+}
+/**
+ * The 17-method contract every storage provider implements. The
+ * count is enforced by `packages/core/tests/storage/adapter.test.ts`
+ * (defensive — catches accidental additions/removals).
+ */
+interface S3CompatibleAdapter {
+    list(input: ListInput): Promise<Result<ListOutput, FileSystemError>>;
+    read(input: ReadInput): Promise<Result<ReadOutput, FileSystemError>>;
+    write(input: WriteInput): Promise<Result<WriteOutput, FileSystemError>>;
+    delete(input: DeleteInput): Promise<Result<DeleteOutput, FileSystemError>>;
+    move(input: MoveInput): Promise<Result<MoveOutput, FileSystemError>>;
+    copy(input: CopyInput): Promise<Result<CopyOutput, FileSystemError>>;
+    stat(input: StatInput): Promise<Result<StatOutput, FileSystemError>>;
+    exists(input: ExistsInput): Promise<Result<ExistsOutput, FileSystemError>>;
+    getMetadata(input: GetMetadataInput): Promise<Result<GetMetadataOutput, FileSystemError>>;
+    setMetadata(input: SetMetadataInput): Promise<Result<SetMetadataOutput, FileSystemError>>;
+    createPresignedUploadUrl(input: PresignedUploadInput): Promise<Result<PresignedUploadOutput, FileSystemError>>;
+    createPresignedDownloadUrl(input: PresignedDownloadInput): Promise<Result<PresignedDownloadOutput, FileSystemError>>;
+    getPublicUrl(input: GetPublicUrlInput): Promise<Result<GetPublicUrlOutput, FileSystemError>>;
+    createMultipartUpload(input: CreateMultipartUploadInput): Promise<Result<CreateMultipartUploadOutput, FileSystemError>>;
+    uploadPart(input: UploadPartInput): Promise<Result<UploadPartOutput, FileSystemError>>;
+    completeMultipartUpload(input: CompleteMultipartUploadInput): Promise<Result<CompleteMultipartUploadOutput, FileSystemError>>;
+    abortMultipartUpload(input: AbortMultipartUploadInput): Promise<Result<AbortMultipartUploadOutput, FileSystemError>>;
+}
+
+/**
+ * `FileSystemConfig` — the discriminated union of provider configs
+ * and its Zod-driven parser.
+ *
+ * The Zod schema is the single source of truth for both the
+ * runtime shape AND the TypeScript type (`z.infer<...>`). Adding a
+ * new field is a one-line change in the schema; the inferred type
+ * updates automatically and every consumer gets the new field
+ * without a separate type definition to keep in sync.
+ *
+ * Provider-specific shape notes:
+ *   - **S3**: `region` is required (AWS regional endpoints). An
+ *     optional `endpoint` is allowed for S3-compatible providers
+ *     (MinIO, LocalStack, etc.).
+ *   - **R2**: `endpoint` is required (Cloudflare R2 has no region
+ *     model — you talk to your account's endpoint). `forcePathStyle`
+ *     is ALWAYS `true` (R2 requires path-style addressing; the
+ *     literal type catches accidental overrides at parse time).
+ *
+ * `parseFileSystemConfig` is the trust boundary. Callers receive a
+ * `Result<FileSystemConfig, FileSystemError>` — a parse failure is
+ * an `InternalError` (retryable: false) with the original Zod
+ * issues preserved on `cause` for debugging.
+ */
+
+declare const CredentialsSchema: z.ZodObject<{
+    accessKeyId: z.ZodString;
+    secretAccessKey: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    accessKeyId: string;
+    secretAccessKey: string;
+}, {
+    accessKeyId: string;
+    secretAccessKey: string;
+}>;
+type Credentials = z.infer<typeof CredentialsSchema>;
+declare const S3ConfigSchema: z.ZodObject<{
+    provider: z.ZodLiteral<"s3">;
+    bucket: z.ZodString;
+    region: z.ZodString;
+    /** Optional S3-compatible endpoint (MinIO, LocalStack, ...). */
+    endpoint: z.ZodOptional<z.ZodString>;
+    credentials: z.ZodObject<{
+        accessKeyId: z.ZodString;
+        secretAccessKey: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        accessKeyId: string;
+        secretAccessKey: string;
+    }, {
+        accessKeyId: string;
+        secretAccessKey: string;
+    }>;
+    /** Default false; some S3-compatible providers need path-style. */
+    forcePathStyle: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    provider: "s3";
+    bucket: string;
+    region: string;
+    credentials: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    forcePathStyle: boolean;
+    endpoint?: string | undefined;
+}, {
+    provider: "s3";
+    bucket: string;
+    region: string;
+    credentials: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    endpoint?: string | undefined;
+    forcePathStyle?: boolean | undefined;
+}>;
+declare const R2ConfigSchema: z.ZodObject<{
+    provider: z.ZodLiteral<"r2">;
+    bucket: z.ZodString;
+    endpoint: z.ZodString;
+    credentials: z.ZodObject<{
+        accessKeyId: z.ZodString;
+        secretAccessKey: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        accessKeyId: string;
+        secretAccessKey: string;
+    }, {
+        accessKeyId: string;
+        secretAccessKey: string;
+    }>;
+    /** R2 ONLY supports path-style; the literal-true type makes that explicit. */
+    forcePathStyle: z.ZodLiteral<true>;
+}, "strip", z.ZodTypeAny, {
+    provider: "r2";
+    bucket: string;
+    endpoint: string;
+    credentials: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    forcePathStyle: true;
+}, {
+    provider: "r2";
+    bucket: string;
+    endpoint: string;
+    credentials: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    forcePathStyle: true;
+}>;
+declare const FileSystemConfigSchema: z.ZodDiscriminatedUnion<"provider", [z.ZodObject<{
+    provider: z.ZodLiteral<"s3">;
+    bucket: z.ZodString;
+    region: z.ZodString;
+    /** Optional S3-compatible endpoint (MinIO, LocalStack, ...). */
+    endpoint: z.ZodOptional<z.ZodString>;
+    credentials: z.ZodObject<{
+        accessKeyId: z.ZodString;
+        secretAccessKey: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        accessKeyId: string;
+        secretAccessKey: string;
+    }, {
+        accessKeyId: string;
+        secretAccessKey: string;
+    }>;
+    /** Default false; some S3-compatible providers need path-style. */
+    forcePathStyle: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    provider: "s3";
+    bucket: string;
+    region: string;
+    credentials: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    forcePathStyle: boolean;
+    endpoint?: string | undefined;
+}, {
+    provider: "s3";
+    bucket: string;
+    region: string;
+    credentials: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    endpoint?: string | undefined;
+    forcePathStyle?: boolean | undefined;
+}>, z.ZodObject<{
+    provider: z.ZodLiteral<"r2">;
+    bucket: z.ZodString;
+    endpoint: z.ZodString;
+    credentials: z.ZodObject<{
+        accessKeyId: z.ZodString;
+        secretAccessKey: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        accessKeyId: string;
+        secretAccessKey: string;
+    }, {
+        accessKeyId: string;
+        secretAccessKey: string;
+    }>;
+    /** R2 ONLY supports path-style; the literal-true type makes that explicit. */
+    forcePathStyle: z.ZodLiteral<true>;
+}, "strip", z.ZodTypeAny, {
+    provider: "r2";
+    bucket: string;
+    endpoint: string;
+    credentials: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    forcePathStyle: true;
+}, {
+    provider: "r2";
+    bucket: string;
+    endpoint: string;
+    credentials: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    forcePathStyle: true;
+}>]>;
+type S3Config = z.infer<typeof S3ConfigSchema>;
+type R2Config = z.infer<typeof R2ConfigSchema>;
+type FileSystemConfig = z.infer<typeof FileSystemConfigSchema>;
+/**
+ * Parse an unknown value (typically the env object) into a typed
+ * `FileSystemConfig`. Returns a `Result` so the call site can
+ * branch on parse failure without try/catch.
+ *
+ * Mapping strategy:
+ *   - On success: `ok(config)`.
+ *   - On Zod failure: `err(FileSystemError(InternalError, retryable: false))`
+ *     with the original issues preserved on `cause` (as a synthetic
+ *     `{ code: "ZodError", message, issues }` shape so the
+ *     FileSystemError contract is honored).
+ */
+declare const parseFileSystemConfig: (input: unknown) => Result<FileSystemConfig, FileSystemError>;
+
+/**
+ * `MetadataStore` — the pure-TS interface every concrete store
+ * implements (memory, SQLite, Postgres).
+ *
+ * The store is the secondary metadata index. It mirrors the S3
+ * file tree so callers can list/search/sort WITHOUT a ListObjectsV2
+ * call (which is slow and expensive at scale). The S3 bucket
+ * remains the source of truth for object bytes; the store is
+ * the source of truth for tree structure, search indexes, and
+ * tenant scoping.
+ *
+ * Design references:
+ *   - `sdd/file-next/design` §F (the 9-method contract)
+ *   - `sdd/file-next/architecture/byodb-metadata-store` (hexagonal)
+ *   - `sdd/file-next/decisions/error-codes-deviation` (C' catalog)
+ *
+ * Tenant isolation: every method takes an explicit \`tenantId\`
+ * parameter. The Postgres adapter enforces isolation at the DB
+ * level via \`SET LOCAL app.current_tenant\` + RLS; the SQLite
+ * and memory adapters filter by tenantId in app code (no
+ * structural isolation, but a single-tenant test DB can be used
+ * safely).
+ */
+
+/** The kind of node in the file tree. */
+type NodeKind = "file" | "folder";
+/**
+ * A single node in the metadata tree. The S3 object bytes are NOT
+ * here (they live in the bucket); this is the tree + application
+ * metadata that the consumer needs to render a file browser.
+ */
+interface FileNode {
+    /** Globally unique node id (UUID v4 in production). */
+    readonly id: string;
+    /** Owning tenant. */
+    readonly tenantId: TenantId;
+    /** Parent node id; null for the root. */
+    readonly parentId: string | null;
+    /** Display name (the last path segment). */
+    readonly name: string;
+    /** Full POSIX path from the root (materialized for fast lookups). */
+    readonly path: string;
+    /** File or folder. */
+    readonly kind: NodeKind;
+    /** Object size in bytes (0 for folders). */
+    readonly size: number;
+    /** MIME type (empty for folders). */
+    readonly mimeType: string;
+    /** The S3 key for the object (empty for folders). */
+    readonly s3Key: string;
+    /** Owning user (the creator; ownership is sticky unless explicitly transferred). */
+    readonly ownerId: UserId;
+    /** Application-defined user metadata. */
+    readonly metadata: Readonly<Record<string, string>>;
+    /** ISO timestamp. */
+    readonly createdAt: Date;
+    /** ISO timestamp. */
+    readonly updatedAt: Date;
+    /** Soft-delete tombstone. null = live. */
+    readonly deletedAt: Date | null;
+}
+interface CreateNodeInput {
+    readonly tenantId: TenantId;
+    readonly parentId: string | null;
+    readonly name: string;
+    readonly kind: NodeKind;
+    readonly size: number;
+    readonly mimeType: string;
+    readonly s3Key: string;
+    readonly ownerId: UserId;
+    readonly metadata?: Readonly<Record<string, string>>;
+    /** Optional stable id (UUID). Defaults to a generated UUID. */
+    readonly id?: string;
+}
+interface GetNodeInput {
+    readonly tenantId: TenantId;
+    readonly id: string;
+}
+interface ListChildrenInput {
+    readonly tenantId: TenantId;
+    readonly parentId: string | null;
+    /** Optional cursor for pagination; opaque to consumers. */
+    readonly cursor?: string;
+    /** Soft cap; the adapter may honor or ignore. */
+    readonly limit?: number;
+}
+interface MoveNodeInput {
+    readonly tenantId: TenantId;
+    readonly id: string;
+    /** New parent (null = root). */
+    readonly newParentId: string | null;
+    /** New display name (rename). If omitted, the name is preserved. */
+    readonly newName?: string;
+}
+interface DeleteNodeInput {
+    readonly tenantId: TenantId;
+    readonly id: string;
+    /**
+     * If true, recursively delete the subtree. If false (default),
+     * a non-empty folder returns Conflict.
+     */
+    readonly recursive?: boolean;
+}
+interface UpdateMetadataInput {
+    readonly tenantId: TenantId;
+    readonly id: string;
+    /** User metadata to merge. */
+    readonly metadata: Readonly<Record<string, string>>;
+    /** true = replace the entire metadata map; false (default) = merge. */
+    readonly replace?: boolean;
+}
+interface SearchInput {
+    readonly tenantId: TenantId;
+    /** Case-insensitive substring matched against the node name. */
+    readonly query: string;
+    /** Optional scope: search only within a folder subtree. */
+    readonly parentId?: string;
+    readonly limit?: number;
+}
+interface GetPathInput {
+    readonly tenantId: TenantId;
+    readonly id: string;
+}
+interface ListChildrenOutput {
+    readonly items: ReadonlyArray<FileNode>;
+    /** Opaque cursor; undefined = listing is complete. */
+    readonly nextCursor?: string;
+}
+interface GetPathOutput {
+    /** The path from root to the target node, root-first. */
+    readonly segments: ReadonlyArray<FileNode>;
+}
+interface ReconcileResult {
+    /** Nodes in the store that had no matching S3 object. */
+    readonly orphansInStore: ReadonlyArray<string>;
+    /** S3 keys that had no matching store row. */
+    readonly orphansInS3: ReadonlyArray<string>;
+    /** Total nodes considered. */
+    readonly scanned: number;
+}
+interface MetadataStore {
+    /** Create a new node. Returns Conflict on a duplicate (parentId, name). */
+    createNode(input: CreateNodeInput): Promise<Result<FileNode, FileSystemError>>;
+    /** Get a node by id. Returns ok(null) when not found (NOT NotFound). */
+    getNode(input: GetNodeInput): Promise<Result<FileNode | null, FileSystemError>>;
+    /** List children of a folder, ordered by name. */
+    listChildren(input: ListChildrenInput): Promise<Result<ListChildrenOutput, FileSystemError>>;
+    /**
+     * Move a node to a new parent and/or rename it. Updates the
+     * materialized path for the node AND its descendants (cascades).
+     */
+    moveNode(input: MoveNodeInput): Promise<Result<FileNode, FileSystemError>>;
+    /**
+     * Soft-delete a node (sets deletedAt). Recursive deletion
+     * tombstones the entire subtree in one call.
+     */
+    deleteNode(input: DeleteNodeInput): Promise<Result<void, FileSystemError>>;
+    /** Update user metadata (merge or replace). */
+    updateMetadata(input: UpdateMetadataInput): Promise<Result<FileNode, FileSystemError>>;
+    /** Case-insensitive name search within an optional folder scope. */
+    search(input: SearchInput): Promise<Result<ListChildrenOutput, FileSystemError>>;
+    /**
+     * Walk the parent chain and return the path from root to the
+     * target node. The result includes the target itself as the
+     * last segment.
+     */
+    getPath(input: GetPathInput): Promise<Result<GetPathOutput, FileSystemError>>;
+    /**
+     * Reconcile the store against an external source of truth
+     * (S3 bucket walk). Returns the drift set. The memory adapter
+     * is a no-op (no external source); SQLite/Postgres walk the
+     * bucket via the adapter and compare.
+     */
+    reconcile(): Promise<Result<ReconcileResult, FileSystemError>>;
+    enqueueOrphan(input: {
+        tenantId: TenantId;
+        s3Key: S3Key;
+        metadataId?: string;
+        reason: string;
+    }): Promise<Result<{
+        id: string;
+    }, FileSystemError>>;
+    listPendingOrphans(input: {
+        tenantId: TenantId;
+    }): Promise<Result<Array<{
+        id: string;
+        tenantId: TenantId;
+        s3Key: S3Key;
+        metadataId: string | null;
+        reason: string;
+        createdAt: Date;
+    }>, FileSystemError>>;
+    deleteOrphan(input: {
+        tenantId: TenantId;
+        id: string;
+    }): Promise<Result<void, FileSystemError>>;
+    restoreNode(input: {
+        tenantId: TenantId;
+        id: string;
+    }): Promise<Result<FileNode, FileSystemError>>;
+    listTrash(input: {
+        tenantId: TenantId;
+        cursor?: string;
+        limit?: number;
+    }): Promise<Result<ListChildrenOutput, FileSystemError>>;
+    scanFileKeys(input: {
+        tenantId: TenantId;
+    }): Promise<Result<ReadonlyArray<{
+        id: string;
+        s3Key: string;
+    }>, FileSystemError>>;
+    sumSize(input: {
+        tenantId: TenantId;
+    }): Promise<Result<number, FileSystemError>>;
+    findByS3Key(input: {
+        tenantId: TenantId;
+        s3Key: string;
+    }): Promise<Result<FileNode | null, FileSystemError>>;
+    createShare(input: {
+        tenantId: TenantId;
+        nodeId: string;
+        expiresAt?: Date;
+    }): Promise<Result<{
+        token: string;
+    }, FileSystemError>>;
+    resolveShare(input: {
+        token: string;
+    }): Promise<Result<FileNode | null, FileSystemError>>;
+    revokeShare(input: {
+        tenantId: TenantId;
+        token: string;
+    }): Promise<Result<void, FileSystemError>>;
+}
+
+/**
+ * The `FileSystem` container — adapter + config + optional metadata
+ * index + a `forTenant` chain that returns a namespaced view.
+ */
+
+interface FileSystem {
+    readonly adapter: S3CompatibleAdapter;
+    readonly config: FileSystemConfig;
+    readonly metadata: MetadataStore | undefined;
+    /** Set when this instance was produced by `forTenant`. */
+    readonly tenantId?: string;
+    /** Optional per-tenant byte cap enforced by write-through. */
+    readonly quotaBytes?: number;
+    forTenant(tenantId: string): FileSystem;
+}
+interface CreateFileSystemOptions {
+    readonly store?: MetadataStore;
+    readonly quotaBytes?: number;
+    /**
+     * When true (default), `forTenant(id)` prefixes object keys with
+     * `t/{id}/`. Set false for a single-tenant bucket or an R2 token
+     * scoped to the bucket root.
+     */
+    readonly prefixTenantKeys?: boolean;
+}
+
+export { andThen as $, type PresignedUploadOutput as A, type R2Config as B, type CreateFileSystemOptions as C, type DeleteInput as D, type ExistsInput as E, type FileNode as F, type GetMetadataInput as G, type ReadInput as H, type ReadOutput as I, type ReconcileResult as J, type S3Config as K, type ListChildrenInput as L, type MetadataStore as M, type NodeKind as N, type SearchInput as O, type Path as P, type SetMetadataInput as Q, type Result as R, type S3CompatibleAdapter as S, type TenantId as T, type UserId as U, type SetMetadataOutput as V, type StatInput as W, type StatOutput as X, type UpdateMetadataInput as Y, type WriteInput as Z, type WriteOutput as _, type FileSystem as a, asPath as a0, asPrefix as a1, asS3Key as a2, asTenantId as a3, asUserId as a4, assertPath as a5, assertPrefix as a6, assertS3Key as a7, assertTenantId as a8, assertUserId as a9, err as aa, map as ab, mapErr as ac, ok as ad, parseFileSystemConfig as ae, unwrap as af, unwrapOr as ag, type FileSystemConfig as b, type S3Key as c, type CopyInput as d, type CopyOutput as e, type CreateNodeInput as f, type Credentials as g, type DeleteNodeInput as h, type DeleteOutput as i, type ExistsOutput as j, type GetMetadataOutput as k, type GetNodeInput as l, type GetPathInput as m, type GetPathOutput as n, type GetPublicUrlInput as o, type GetPublicUrlOutput as p, type ListChildrenOutput as q, type ListInput as r, type ListOutput as s, type MoveInput as t, type MoveNodeInput as u, type MoveOutput as v, type Prefix as w, type PresignedDownloadInput as x, type PresignedDownloadOutput as y, type PresignedUploadInput as z };