@vryzel/file-next 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 file-next contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# @vryzel/file-next
+
+S3/R2 filesystem for Next.js: object adapter, metadata index, server actions, write-through.
+
+```bash
+pnpm add @vryzel/file-next
+```
+
+```ts
+import {
+  asTenantId,
+  asUserId,
+  createFileSystem,
+  createSqliteStore,
+} from "@vryzel/file-next";
+import { createServerActions } from "@vryzel/file-next/server";
+import { createWriteThrough } from "@vryzel/file-next/sync";
+
+const store = createSqliteStore({ path: ".data/metadata.db" });
+const fs = createFileSystem(
+  {
+    provider: "s3",
+    bucket: process.env.FILE_NEXT_BUCKET!,
+    region: process.env.FILE_NEXT_REGION ?? "us-east-1",
+    credentials: {
+      accessKeyId: process.env.FILE_NEXT_ACCESS_KEY_ID!,
+      secretAccessKey: process.env.FILE_NEXT_SECRET_ACCESS_KEY!,
+    },
+  },
+  { store },
+);
+export const actions = createServerActions({
+  store,
+  fs,
+  writeThrough: createWriteThrough(fs, store),
+  getAuth: () => ({
+    tenantId: asTenantId("acme"),
+    userId: asUserId("user-1"),
+  }),
+});
+```
+
+Tenant never comes from the client. Replace `getAuth` with your session.
+
+Public on npmjs. See the repository README.

package/dist/errors/index.cjs

@@ -0,0 +1,183 @@
+'use strict';
+
+// src/errors/mappers.ts
+var HTTP_STATUS_TO_CODE = {
+  401: { code: "Unauthorized", retryable: false },
+  403: { code: "Forbidden", retryable: false },
+  404: { code: "NotFound", retryable: false },
+  408: { code: "NetworkError", retryable: true },
+  409: { code: "Conflict", retryable: false },
+  413: { code: "PayloadTooLarge", retryable: false },
+  415: { code: "UnsupportedMediaType", retryable: false },
+  429: { code: "RateLimited", retryable: true }
+};
+var AWS_NAME_TO_CODE = {
+  NoSuchKey: { code: "NotFound", retryable: false },
+  NoSuchBucket: { code: "NotFound", retryable: false },
+  // v0.2 multipart: unknown/aborted/expired uploadId.
+  NoSuchUpload: { code: "NotFound", retryable: false },
+  AccessDenied: { code: "Forbidden", retryable: false },
+  SlowDown: { code: "QuotaExceeded", retryable: true },
+  BadDigest: { code: "ChecksumMismatch", retryable: true },
+  XAmzContentSHA256Mismatch: { code: "ChecksumMismatch", retryable: true },
+  NetworkingError: { code: "NetworkError", retryable: true },
+  TimeoutError: { code: "NetworkError", retryable: true }
+};
+var PG_SQLSTATE_TO_CODE = {
+  "23505": { code: "Conflict", retryable: false }
+};
+var SQLITE_CODE_TO_CODE = {
+  SQLITE_CONSTRAINT_UNIQUE: { code: "Conflict", retryable: false },
+  SQLITE_CONSTRAINT_PRIMARYKEY: { code: "Conflict", retryable: false }
+};
+var toCause = (code, message, extra) => ({
+  code,
+  message,
+  ...extra ?? {}
+});
+var fallback = (err) => new FileSystemError({
+  code: "InternalError",
+  message: err instanceof Error ? err.message : String(err),
+  retryable: true,
+  cause: toCause(
+    "Unknown",
+    err instanceof Error ? err.message : String(err)
+  )
+});
+var fromAws = (err) => {
+  if (err instanceof FileSystemError) return err;
+  if (typeof err !== "object" || err === null) return fallback(err);
+  const awsErr = err;
+  const name = typeof awsErr.name === "string" ? awsErr.name : void 0;
+  const message = typeof awsErr.message === "string" ? awsErr.message : `AWS error: ${name ?? "unknown"}`;
+  const status = typeof awsErr.$metadata?.httpStatusCode === "number" ? awsErr.$metadata.httpStatusCode : void 0;
+  const cause = toCause(
+    name ?? (status !== void 0 ? String(status) : "Unknown"),
+    message,
+    status !== void 0 ? { httpStatusCode: status } : void 0
+  );
+  if (name && name in AWS_NAME_TO_CODE) {
+    const m = AWS_NAME_TO_CODE[name];
+    return new FileSystemError({ code: m.code, message, retryable: m.retryable, cause });
+  }
+  if (status !== void 0 && status in HTTP_STATUS_TO_CODE) {
+    const m = HTTP_STATUS_TO_CODE[status];
+    return new FileSystemError({ code: m.code, message, retryable: m.retryable, cause });
+  }
+  if (status !== void 0 && status >= 500 && status < 600) {
+    return new FileSystemError({ code: "InternalError", message, retryable: true, cause });
+  }
+  if (status !== void 0 && status >= 400 && status < 500) {
+    return new FileSystemError({ code: "Forbidden", message, retryable: false, cause });
+  }
+  return new FileSystemError({ code: "InternalError", message, retryable: true, cause });
+};
+var fromPg = (err) => {
+  if (err instanceof FileSystemError) return err;
+  if (typeof err !== "object" || err === null) return fallback(err);
+  const pgErr = err;
+  const sqlstate = typeof pgErr.code === "string" ? pgErr.code : void 0;
+  const message = typeof pgErr.message === "string" ? pgErr.message : `Postgres error: ${sqlstate ?? "unknown"}`;
+  const cause = toCause(sqlstate ?? "Unknown", message);
+  if (sqlstate && sqlstate in PG_SQLSTATE_TO_CODE) {
+    const m = PG_SQLSTATE_TO_CODE[sqlstate];
+    return new FileSystemError({ code: m.code, message, retryable: m.retryable, cause });
+  }
+  return new FileSystemError({ code: "InternalError", message, retryable: true, cause });
+};
+var fromSqlite = (err) => {
+  if (err instanceof FileSystemError) return err;
+  if (typeof err !== "object" || err === null) return fallback(err);
+  const sqlErr = err;
+  const code = typeof sqlErr.code === "string" ? sqlErr.code : void 0;
+  const message = typeof sqlErr.message === "string" ? sqlErr.message : `SQLite error: ${code ?? "unknown"}`;
+  const cause = toCause(code ?? "Unknown", message);
+  if (code && code in SQLITE_CODE_TO_CODE) {
+    const m = SQLITE_CODE_TO_CODE[code];
+    return new FileSystemError({ code: m.code, message, retryable: m.retryable, cause });
+  }
+  return new FileSystemError({ code: "InternalError", message, retryable: true, cause });
+};
+
+// src/errors/index.ts
+var FILE_SYSTEM_ERROR_CODES = [
+  "NotFound",
+  "Forbidden",
+  "Conflict",
+  "QuotaExceeded",
+  "NetworkError",
+  "InternalError",
+  "Unauthorized",
+  "PayloadTooLarge",
+  "UnsupportedMediaType",
+  "RateLimited",
+  "ChecksumMismatch"
+];
+var RETRYABLE_BY_CODE = {
+  NotFound: false,
+  Forbidden: false,
+  Conflict: false,
+  QuotaExceeded: true,
+  NetworkError: true,
+  InternalError: true,
+  Unauthorized: false,
+  PayloadTooLarge: false,
+  UnsupportedMediaType: false,
+  RateLimited: true,
+  ChecksumMismatch: true
+};
+var FileSystemError = class extends Error {
+  code;
+  retryable;
+  cause;
+  constructor(opts) {
+    super(opts.message);
+    this.name = "FileSystemError";
+    this.code = opts.code;
+    this.retryable = opts.retryable;
+    if (opts.cause !== void 0) {
+      this.cause = opts.cause;
+    }
+  }
+  /**
+   * Stable JSON shape for RSC pass-through. Error.prototype.message
+   * is non-enumerable, so plain `JSON.stringify(err)` would emit `{}`
+   * and lose the message + code + retryable flag. `cause` is omitted
+   * entirely (not set to undefined) when absent so the shape stays
+   * stable for hash-based caches.
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      retryable: this.retryable,
+      ...this.cause !== void 0 ? { cause: this.cause } : {}
+    };
+  }
+  /**
+   * Mappers from upstream error shapes (AWS SDK v3, node-postgres,
+   * better-sqlite3) to FileSystemError. See `./mappers.ts` for the
+   * mapping tables. Re-exposed as static methods so callers can pick
+   * the import style that fits; the free functions are the canonical
+   * implementation.
+   */
+  static fromAws(err) {
+    return fromAws(err);
+  }
+  static fromPg(err) {
+    return fromPg(err);
+  }
+  static fromSqlite(err) {
+    return fromSqlite(err);
+  }
+};
+
+exports.FILE_SYSTEM_ERROR_CODES = FILE_SYSTEM_ERROR_CODES;
+exports.FileSystemError = FileSystemError;
+exports.RETRYABLE_BY_CODE = RETRYABLE_BY_CODE;
+exports.fromAws = fromAws;
+exports.fromPg = fromPg;
+exports.fromSqlite = fromSqlite;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/errors/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/errors/mappers.ts","../../src/errors/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Upstream error mappers for FileSystemError.\n *\n * Each mapper is a pure function `(*unknown) -> FileSystemError`.\n * The class re-exposes them as static methods (FileSystemError.fromAws\n * etc.) so callers can pick the import style that fits.\n *\n * Mapping strategy:\n *   1. If the input is already a FileSystemError, return it as-is\n *      (we never re-wrap our own errors).\n *   2. Try the most specific signal first: S3 `name`, Postgres\n *      SQLSTATE, SQLite extended code.\n *   3. Fall back to the HTTP status code (AWS SDK v3 exposes\n *      `$metadata.httpStatusCode`).\n *   4. Last resort: InternalError, retryable, with the original\n *      payload in `cause`.\n *\n * Provider-specific codes are preserved on `cause.code` (e.g. S3\n * \"NoSuchKey\", Postgres \"23505\") so callers can still branch on\n * them while the top-level `code` stays in the 11-code spec catalog.\n *\n * Mapping notes (post-C' merge, see\n * `sdd/file-next/decisions/error-codes-deviation`):\n *   - S3 `SlowDown`     -> QuotaExceeded (broader than RateLimited;\n *                          SlowDown means reduce request rate, which\n *                          is conceptually quota pressure, not\n *                          throttling of a single call).\n *   - S3 `BadDigest`    -> ChecksumMismatch (checksum verified by\n *                          S3 on upload did not match the client).\n *   - HTTP 429          -> RateLimited (was QuotaExceeded in the\n *                          pre-C' catalog; RateLimited is the more\n *                          specific code for throttling responses).\n *   - HTTP 408          -> NetworkError (transient transport error).\n *   - HTTP 400 / Postgres 23514 / S3 InvalidRequest\n *                       -> fall through to the 4xx branch (no\n *                          top-level 400 code in the C' catalog;\n *                          these inputs are usually caught by the\n *                          name/SQLSTATE mapping first anyway).\n */\n\nimport { FileSystemError, type FileSystemErrorCode } from \"./index\";\n\n/* ---------------------------------------------------------------- *\n * Mapping tables (private)                                          *\n * ---------------------------------------------------------------- */\n\ninterface CodeMapping {\n  code: FileSystemErrorCode;\n  retryable: boolean;\n}\n\nconst HTTP_STATUS_TO_CODE: Readonly<Record<number, CodeMapping>> = {\n  401: { code: \"Unauthorized\", retryable: false },\n  403: { code: \"Forbidden\", retryable: false },\n  404: { code: \"NotFound\", retryable: false },\n  408: { code: \"NetworkError\", retryable: true },\n  409: { code: \"Conflict\", retryable: false },\n  413: { code: \"PayloadTooLarge\", retryable: false },\n  415: { code: \"UnsupportedMediaType\", retryable: false },\n  429: { code: \"RateLimited\", retryable: true },\n};\n\nconst AWS_NAME_TO_CODE: Readonly<Record<string, CodeMapping>> = {\n  NoSuchKey: { code: \"NotFound\", retryable: false },\n  NoSuchBucket: { code: \"NotFound\", retryable: false },\n  // v0.2 multipart: unknown/aborted/expired uploadId.\n  NoSuchUpload: { code: \"NotFound\", retryable: false },\n  AccessDenied: { code: \"Forbidden\", retryable: false },\n  SlowDown: { code: \"QuotaExceeded\", retryable: true },\n  BadDigest: { code: \"ChecksumMismatch\", retryable: true },\n  XAmzContentSHA256Mismatch: { code: \"ChecksumMismatch\", retryable: true },\n  NetworkingError: { code: \"NetworkError\", retryable: true },\n  TimeoutError: { code: \"NetworkError\", retryable: true },\n};\n\nconst PG_SQLSTATE_TO_CODE: Readonly<Record<string, CodeMapping>> = {\n  \"23505\": { code: \"Conflict\", retryable: false },\n};\n\nconst SQLITE_CODE_TO_CODE: Readonly<Record<string, CodeMapping>> = {\n  SQLITE_CONSTRAINT_UNIQUE: { code: \"Conflict\", retryable: false },\n  SQLITE_CONSTRAINT_PRIMARYKEY: { code: \"Conflict\", retryable: false },\n};\n\n/* ---------------------------------------------------------------- *\n * Public mappers                                                    *\n * ---------------------------------------------------------------- */\n\nconst toCause = (code: string, message: string, extra?: Record<string, unknown>) => ({\n  code,\n  message,\n  ...(extra ?? {}),\n});\n\nconst fallback = (err: unknown): FileSystemError =>\n  new FileSystemError({\n    code: \"InternalError\",\n    message: err instanceof Error ? err.message : String(err),\n    retryable: true,\n    cause: toCause(\n      \"Unknown\",\n      err instanceof Error ? err.message : String(err),\n    ),\n  });\n\nexport const fromAws = (err: unknown): FileSystemError => {\n  if (err instanceof FileSystemError) return err;\n\n  if (typeof err !== \"object\" || err === null) return fallback(err);\n\n  const awsErr = err as {\n    name?: unknown;\n    message?: unknown;\n    $metadata?: { httpStatusCode?: unknown };\n  };\n  const name = typeof awsErr.name === \"string\" ? awsErr.name : undefined;\n  const message =\n    typeof awsErr.message === \"string\" ? awsErr.message : `AWS error: ${name ?? \"unknown\"}`;\n  const status =\n    typeof awsErr.$metadata?.httpStatusCode === \"number\"\n      ? awsErr.$metadata.httpStatusCode\n      : undefined;\n\n  const cause = toCause(\n    name ?? (status !== undefined ? String(status) : \"Unknown\"),\n    message,\n    status !== undefined ? { httpStatusCode: status } : undefined,\n  );\n\n  // 1) name-based mapping wins (more specific than HTTP status)\n  if (name && name in AWS_NAME_TO_CODE) {\n    const m = AWS_NAME_TO_CODE[name]!;\n    return new FileSystemError({ code: m.code, message, retryable: m.retryable, cause });\n  }\n\n  // 2) HTTP status mapping\n  if (status !== undefined && status in HTTP_STATUS_TO_CODE) {\n    const m = HTTP_STATUS_TO_CODE[status]!;\n    return new FileSystemError({ code: m.code, message, retryable: m.retryable, cause });\n  }\n\n  // 3) 5xx bucket\n  if (status !== undefined && status >= 500 && status < 600) {\n    return new FileSystemError({ code: \"InternalError\", message, retryable: true, cause });\n  }\n\n  // 4) anything else 4xx-shaped\n  if (status !== undefined && status >= 400 && status < 500) {\n    return new FileSystemError({ code: \"Forbidden\", message, retryable: false, cause });\n  }\n\n  return new FileSystemError({ code: \"InternalError\", message, retryable: true, cause });\n};\n\nexport const fromPg = (err: unknown): FileSystemError => {\n  if (err instanceof FileSystemError) return err;\n\n  if (typeof err !== \"object\" || err === null) return fallback(err);\n\n  const pgErr = err as { code?: unknown; message?: unknown };\n  const sqlstate = typeof pgErr.code === \"string\" ? pgErr.code : undefined;\n  const message =\n    typeof pgErr.message === \"string\" ? pgErr.message : `Postgres error: ${sqlstate ?? \"unknown\"}`;\n  const cause = toCause(sqlstate ?? \"Unknown\", message);\n\n  if (sqlstate && sqlstate in PG_SQLSTATE_TO_CODE) {\n    const m = PG_SQLSTATE_TO_CODE[sqlstate]!;\n    return new FileSystemError({ code: m.code, message, retryable: m.retryable, cause });\n  }\n\n  return new FileSystemError({ code: \"InternalError\", message, retryable: true, cause });\n};\n\nexport const fromSqlite = (err: unknown): FileSystemError => {\n  if (err instanceof FileSystemError) return err;\n\n  if (typeof err !== \"object\" || err === null) return fallback(err);\n\n  const sqlErr = err as { code?: unknown; message?: unknown };\n  const code = typeof sqlErr.code === \"string\" ? sqlErr.code : undefined;\n  const message =\n    typeof sqlErr.message === \"string\" ? sqlErr.message : `SQLite error: ${code ?? \"unknown\"}`;\n  const cause = toCause(code ?? \"Unknown\", message);\n\n  if (code && code in SQLITE_CODE_TO_CODE) {\n    const m = SQLITE_CODE_TO_CODE[code]!;\n    return new FileSystemError({ code: m.code, message, retryable: m.retryable, cause });\n  }\n\n  return new FileSystemError({ code: \"InternalError\", message, retryable: true, cause });\n};\n","/**\n * FileSystemError — the single error class every adapter, store,\n * server action, and route handler in `file-next` returns or throws.\n *\n * Spec reference: requirement \"FileSystemError discriminated union\"\n * in `sdd/file-next/spec`. The 11 codes are the CLOSED set; any\n * provider-specific code (e.g. S3 `NoSuchKey`, Postgres `23505`) is\n * preserved on `cause.code` so callers can still distinguish upstream\n * reasons while the top-level `code` stays in the catalog.\n *\n * The catalog is a merge of spec + impl: the 6 fixed codes\n * (NotFound, Forbidden, Conflict, QuotaExceeded, NetworkError,\n * InternalError) are non-negotiable; the remaining 5 keep the wire\n * aligned with both the HTTP boundary (route handlers map the\n * top-level `code` to a status directly) and the storage boundary\n * (`RateLimited` and `ChecksumMismatch` carry semantics that have\n * no natural HTTP equivalent). See\n * `sdd/file-next/decisions/error-codes-deviation` for the\n * deviation log and rationale.\n *\n * Retryability table is the design's `error-mapping` excerpt; see\n * `sdd/file-next/design` §C. Any future code MUST add an entry in\n * `RETRYABLE_BY_CODE` (the catalog test enforces this).\n *\n * The placeholder from T-006 is replaced by this file in T-007a.\n * The upstream mappers (fromAws / fromPg / fromSqlite) land in T-007b\n * in `mappers.ts`.\n */\n\nexport const FILE_SYSTEM_ERROR_CODES = [\n  \"NotFound\",\n  \"Forbidden\",\n  \"Conflict\",\n  \"QuotaExceeded\",\n  \"NetworkError\",\n  \"InternalError\",\n  \"Unauthorized\",\n  \"PayloadTooLarge\",\n  \"UnsupportedMediaType\",\n  \"RateLimited\",\n  \"ChecksumMismatch\",\n] as const satisfies readonly string[];\n\nexport type FileSystemErrorCode = (typeof FILE_SYSTEM_ERROR_CODES)[number];\n\nexport const RETRYABLE_BY_CODE: Readonly<Record<FileSystemErrorCode, boolean>> = {\n  NotFound: false,\n  Forbidden: false,\n  Conflict: false,\n  QuotaExceeded: true,\n  NetworkError: true,\n  InternalError: true,\n  Unauthorized: false,\n  PayloadTooLarge: false,\n  UnsupportedMediaType: false,\n  RateLimited: true,\n  ChecksumMismatch: true,\n};\n\nexport interface FileSystemErrorOptions {\n  code: FileSystemErrorCode;\n  message: string;\n  retryable: boolean;\n  cause?: { code: string; message: string; [k: string]: unknown };\n}\n\nexport interface FileSystemErrorJson {\n  name: string;\n  code: FileSystemErrorCode;\n  message: string;\n  retryable: boolean;\n  cause?: { code: string; message: string; [k: string]: unknown };\n}\n\nexport class FileSystemError extends Error {\n  readonly code: FileSystemErrorCode;\n  readonly retryable: boolean;\n  override readonly cause?: { code: string; message: string; [k: string]: unknown };\n\n  constructor(opts: FileSystemErrorOptions) {\n    super(opts.message);\n    this.name = \"FileSystemError\";\n    this.code = opts.code;\n    this.retryable = opts.retryable;\n    if (opts.cause !== undefined) {\n      this.cause = opts.cause;\n    }\n  }\n\n  /**\n   * Stable JSON shape for RSC pass-through. Error.prototype.message\n   * is non-enumerable, so plain `JSON.stringify(err)` would emit `{}`\n   * and lose the message + code + retryable flag. `cause` is omitted\n   * entirely (not set to undefined) when absent so the shape stays\n   * stable for hash-based caches.\n   */\n  toJSON(): FileSystemErrorJson {\n    return {\n      name: this.name,\n      code: this.code,\n      message: this.message,\n      retryable: this.retryable,\n      ...(this.cause !== undefined ? { cause: this.cause } : {}),\n    };\n  }\n\n  /**\n   * Mappers from upstream error shapes (AWS SDK v3, node-postgres,\n   * better-sqlite3) to FileSystemError. See `./mappers.ts` for the\n   * mapping tables. Re-exposed as static methods so callers can pick\n   * the import style that fits; the free functions are the canonical\n   * implementation.\n   */\n  static fromAws(err: unknown): FileSystemError {\n    // Lazy import via the runtime binding avoids the static-field\n    // circular-dep trap in ESM. The mapper file imports this class\n    // for instanceof checks; we look up the function at call time.\n    return _fromAws(err);\n  }\n\n  static fromPg(err: unknown): FileSystemError {\n    return _fromPg(err);\n  }\n\n  static fromSqlite(err: unknown): FileSystemError {\n    return _fromSqlite(err);\n  }\n}\n\n// Imported here as bindings (not values) so the static methods above\n// can resolve them lazily. The actual implementation lives in mappers.ts.\nimport { fromAws as _fromAws, fromPg as _fromPg, fromSqlite as _fromSqlite } from \"./mappers\";\nexport { fromAws, fromPg, fromSqlite } from \"./mappers\";\n"]}

package/dist/errors/index.d.cts

@@ -0,0 +1,126 @@
+/**
+ * Upstream error mappers for FileSystemError.
+ *
+ * Each mapper is a pure function `(*unknown) -> FileSystemError`.
+ * The class re-exposes them as static methods (FileSystemError.fromAws
+ * etc.) so callers can pick the import style that fits.
+ *
+ * Mapping strategy:
+ *   1. If the input is already a FileSystemError, return it as-is
+ *      (we never re-wrap our own errors).
+ *   2. Try the most specific signal first: S3 `name`, Postgres
+ *      SQLSTATE, SQLite extended code.
+ *   3. Fall back to the HTTP status code (AWS SDK v3 exposes
+ *      `$metadata.httpStatusCode`).
+ *   4. Last resort: InternalError, retryable, with the original
+ *      payload in `cause`.
+ *
+ * Provider-specific codes are preserved on `cause.code` (e.g. S3
+ * "NoSuchKey", Postgres "23505") so callers can still branch on
+ * them while the top-level `code` stays in the 11-code spec catalog.
+ *
+ * Mapping notes (post-C' merge, see
+ * `sdd/file-next/decisions/error-codes-deviation`):
+ *   - S3 `SlowDown`     -> QuotaExceeded (broader than RateLimited;
+ *                          SlowDown means reduce request rate, which
+ *                          is conceptually quota pressure, not
+ *                          throttling of a single call).
+ *   - S3 `BadDigest`    -> ChecksumMismatch (checksum verified by
+ *                          S3 on upload did not match the client).
+ *   - HTTP 429          -> RateLimited (was QuotaExceeded in the
+ *                          pre-C' catalog; RateLimited is the more
+ *                          specific code for throttling responses).
+ *   - HTTP 408          -> NetworkError (transient transport error).
+ *   - HTTP 400 / Postgres 23514 / S3 InvalidRequest
+ *                       -> fall through to the 4xx branch (no
+ *                          top-level 400 code in the C' catalog;
+ *                          these inputs are usually caught by the
+ *                          name/SQLSTATE mapping first anyway).
+ */
+
+declare const fromAws: (err: unknown) => FileSystemError;
+declare const fromPg: (err: unknown) => FileSystemError;
+declare const fromSqlite: (err: unknown) => FileSystemError;
+
+/**
+ * FileSystemError — the single error class every adapter, store,
+ * server action, and route handler in `file-next` returns or throws.
+ *
+ * Spec reference: requirement "FileSystemError discriminated union"
+ * in `sdd/file-next/spec`. The 11 codes are the CLOSED set; any
+ * provider-specific code (e.g. S3 `NoSuchKey`, Postgres `23505`) is
+ * preserved on `cause.code` so callers can still distinguish upstream
+ * reasons while the top-level `code` stays in the catalog.
+ *
+ * The catalog is a merge of spec + impl: the 6 fixed codes
+ * (NotFound, Forbidden, Conflict, QuotaExceeded, NetworkError,
+ * InternalError) are non-negotiable; the remaining 5 keep the wire
+ * aligned with both the HTTP boundary (route handlers map the
+ * top-level `code` to a status directly) and the storage boundary
+ * (`RateLimited` and `ChecksumMismatch` carry semantics that have
+ * no natural HTTP equivalent). See
+ * `sdd/file-next/decisions/error-codes-deviation` for the
+ * deviation log and rationale.
+ *
+ * Retryability table is the design's `error-mapping` excerpt; see
+ * `sdd/file-next/design` §C. Any future code MUST add an entry in
+ * `RETRYABLE_BY_CODE` (the catalog test enforces this).
+ *
+ * The placeholder from T-006 is replaced by this file in T-007a.
+ * The upstream mappers (fromAws / fromPg / fromSqlite) land in T-007b
+ * in `mappers.ts`.
+ */
+declare const FILE_SYSTEM_ERROR_CODES: readonly ["NotFound", "Forbidden", "Conflict", "QuotaExceeded", "NetworkError", "InternalError", "Unauthorized", "PayloadTooLarge", "UnsupportedMediaType", "RateLimited", "ChecksumMismatch"];
+type FileSystemErrorCode = (typeof FILE_SYSTEM_ERROR_CODES)[number];
+declare const RETRYABLE_BY_CODE: Readonly<Record<FileSystemErrorCode, boolean>>;
+interface FileSystemErrorOptions {
+    code: FileSystemErrorCode;
+    message: string;
+    retryable: boolean;
+    cause?: {
+        code: string;
+        message: string;
+        [k: string]: unknown;
+    };
+}
+interface FileSystemErrorJson {
+    name: string;
+    code: FileSystemErrorCode;
+    message: string;
+    retryable: boolean;
+    cause?: {
+        code: string;
+        message: string;
+        [k: string]: unknown;
+    };
+}
+declare class FileSystemError extends Error {
+    readonly code: FileSystemErrorCode;
+    readonly retryable: boolean;
+    readonly cause?: {
+        code: string;
+        message: string;
+        [k: string]: unknown;
+    };
+    constructor(opts: FileSystemErrorOptions);
+    /**
+     * Stable JSON shape for RSC pass-through. Error.prototype.message
+     * is non-enumerable, so plain `JSON.stringify(err)` would emit `{}`
+     * and lose the message + code + retryable flag. `cause` is omitted
+     * entirely (not set to undefined) when absent so the shape stays
+     * stable for hash-based caches.
+     */
+    toJSON(): FileSystemErrorJson;
+    /**
+     * Mappers from upstream error shapes (AWS SDK v3, node-postgres,
+     * better-sqlite3) to FileSystemError. See `./mappers.ts` for the
+     * mapping tables. Re-exposed as static methods so callers can pick
+     * the import style that fits; the free functions are the canonical
+     * implementation.
+     */
+    static fromAws(err: unknown): FileSystemError;
+    static fromPg(err: unknown): FileSystemError;
+    static fromSqlite(err: unknown): FileSystemError;
+}
+
+export { FILE_SYSTEM_ERROR_CODES, FileSystemError, type FileSystemErrorCode, type FileSystemErrorJson, type FileSystemErrorOptions, RETRYABLE_BY_CODE, fromAws, fromPg, fromSqlite };

package/dist/errors/index.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Upstream error mappers for FileSystemError.
+ *
+ * Each mapper is a pure function `(*unknown) -> FileSystemError`.
+ * The class re-exposes them as static methods (FileSystemError.fromAws
+ * etc.) so callers can pick the import style that fits.
+ *
+ * Mapping strategy:
+ *   1. If the input is already a FileSystemError, return it as-is
+ *      (we never re-wrap our own errors).
+ *   2. Try the most specific signal first: S3 `name`, Postgres
+ *      SQLSTATE, SQLite extended code.
+ *   3. Fall back to the HTTP status code (AWS SDK v3 exposes
+ *      `$metadata.httpStatusCode`).
+ *   4. Last resort: InternalError, retryable, with the original
+ *      payload in `cause`.
+ *
+ * Provider-specific codes are preserved on `cause.code` (e.g. S3
+ * "NoSuchKey", Postgres "23505") so callers can still branch on
+ * them while the top-level `code` stays in the 11-code spec catalog.
+ *
+ * Mapping notes (post-C' merge, see
+ * `sdd/file-next/decisions/error-codes-deviation`):
+ *   - S3 `SlowDown`     -> QuotaExceeded (broader than RateLimited;
+ *                          SlowDown means reduce request rate, which
+ *                          is conceptually quota pressure, not
+ *                          throttling of a single call).
+ *   - S3 `BadDigest`    -> ChecksumMismatch (checksum verified by
+ *                          S3 on upload did not match the client).
+ *   - HTTP 429          -> RateLimited (was QuotaExceeded in the
+ *                          pre-C' catalog; RateLimited is the more
+ *                          specific code for throttling responses).
+ *   - HTTP 408          -> NetworkError (transient transport error).
+ *   - HTTP 400 / Postgres 23514 / S3 InvalidRequest
+ *                       -> fall through to the 4xx branch (no
+ *                          top-level 400 code in the C' catalog;
+ *                          these inputs are usually caught by the
+ *                          name/SQLSTATE mapping first anyway).
+ */
+
+declare const fromAws: (err: unknown) => FileSystemError;
+declare const fromPg: (err: unknown) => FileSystemError;
+declare const fromSqlite: (err: unknown) => FileSystemError;
+
+/**
+ * FileSystemError — the single error class every adapter, store,
+ * server action, and route handler in `file-next` returns or throws.
+ *
+ * Spec reference: requirement "FileSystemError discriminated union"
+ * in `sdd/file-next/spec`. The 11 codes are the CLOSED set; any
+ * provider-specific code (e.g. S3 `NoSuchKey`, Postgres `23505`) is
+ * preserved on `cause.code` so callers can still distinguish upstream
+ * reasons while the top-level `code` stays in the catalog.
+ *
+ * The catalog is a merge of spec + impl: the 6 fixed codes
+ * (NotFound, Forbidden, Conflict, QuotaExceeded, NetworkError,
+ * InternalError) are non-negotiable; the remaining 5 keep the wire
+ * aligned with both the HTTP boundary (route handlers map the
+ * top-level `code` to a status directly) and the storage boundary
+ * (`RateLimited` and `ChecksumMismatch` carry semantics that have
+ * no natural HTTP equivalent). See
+ * `sdd/file-next/decisions/error-codes-deviation` for the
+ * deviation log and rationale.
+ *
+ * Retryability table is the design's `error-mapping` excerpt; see
+ * `sdd/file-next/design` §C. Any future code MUST add an entry in
+ * `RETRYABLE_BY_CODE` (the catalog test enforces this).
+ *
+ * The placeholder from T-006 is replaced by this file in T-007a.
+ * The upstream mappers (fromAws / fromPg / fromSqlite) land in T-007b
+ * in `mappers.ts`.
+ */
+declare const FILE_SYSTEM_ERROR_CODES: readonly ["NotFound", "Forbidden", "Conflict", "QuotaExceeded", "NetworkError", "InternalError", "Unauthorized", "PayloadTooLarge", "UnsupportedMediaType", "RateLimited", "ChecksumMismatch"];
+type FileSystemErrorCode = (typeof FILE_SYSTEM_ERROR_CODES)[number];
+declare const RETRYABLE_BY_CODE: Readonly<Record<FileSystemErrorCode, boolean>>;
+interface FileSystemErrorOptions {
+    code: FileSystemErrorCode;
+    message: string;
+    retryable: boolean;
+    cause?: {
+        code: string;
+        message: string;
+        [k: string]: unknown;
+    };
+}
+interface FileSystemErrorJson {
+    name: string;
+    code: FileSystemErrorCode;
+    message: string;
+    retryable: boolean;
+    cause?: {
+        code: string;
+        message: string;
+        [k: string]: unknown;
+    };
+}
+declare class FileSystemError extends Error {
+    readonly code: FileSystemErrorCode;
+    readonly retryable: boolean;
+    readonly cause?: {
+        code: string;
+        message: string;
+        [k: string]: unknown;
+    };
+    constructor(opts: FileSystemErrorOptions);
+    /**
+     * Stable JSON shape for RSC pass-through. Error.prototype.message
+     * is non-enumerable, so plain `JSON.stringify(err)` would emit `{}`
+     * and lose the message + code + retryable flag. `cause` is omitted
+     * entirely (not set to undefined) when absent so the shape stays
+     * stable for hash-based caches.
+     */
+    toJSON(): FileSystemErrorJson;
+    /**
+     * Mappers from upstream error shapes (AWS SDK v3, node-postgres,
+     * better-sqlite3) to FileSystemError. See `./mappers.ts` for the
+     * mapping tables. Re-exposed as static methods so callers can pick
+     * the import style that fits; the free functions are the canonical
+     * implementation.
+     */
+    static fromAws(err: unknown): FileSystemError;
+    static fromPg(err: unknown): FileSystemError;
+    static fromSqlite(err: unknown): FileSystemError;
+}
+
+export { FILE_SYSTEM_ERROR_CODES, FileSystemError, type FileSystemErrorCode, type FileSystemErrorJson, type FileSystemErrorOptions, RETRYABLE_BY_CODE, fromAws, fromPg, fromSqlite };