first commit

docs/media/video/video-thumbnails/src/error-codes/error-codes.md

@@ -0,0 +1,80 @@
+# `error-codes`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`VIDEO_THUMBNAILS_CODES` is the stable, frozen registry of every failure mode raised by
+`@suaveplan/video-thumbnails`. It is built with `defineCodes` from `@suaveplan/error` so the
+namespace prefix (`VIDEO_THUMBNAILS.`) is encoded in the literal type — meaning consumers can
+`switch` on a `VideoThumbnailsCode` and TypeScript will enforce exhaustiveness. The registry is
+the single source of truth: every `throw new VideoThumbnailsError(...)` references a code from
+this object, and the conformance test walks the registry to prove no code is dead.
+
+## Features
+
+- Frozen, namespaced registry built via `defineCodes("VIDEO_THUMBNAILS", [...])`.
+- Literal union `VideoThumbnailsCode` derived from the registry values.
+- Every code reachable from a real call site in `src/`, validated by `error-codes.test.ts`.
+- Compatible with the project-wide `SuaveplanError` wire format, OTel span events, and
+  redaction.
+
+## Usage: Basic
+
+```ts
+import { VIDEO_THUMBNAILS_CODES } from "@suaveplan/video-thumbnails/error-codes";
+
+console.log(VIDEO_THUMBNAILS_CODES.EXTRACT_FAILED); // "VIDEO_THUMBNAILS.EXTRACT_FAILED"
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    VIDEO_THUMBNAILS_CODES,
+    type VideoThumbnailsCode,
+} from "@suaveplan/video-thumbnails/error-codes";
+
+function describe(code: VideoThumbnailsCode): string {
+    switch (code) {
+        case VIDEO_THUMBNAILS_CODES.EXTRACT_FAILED:
+            return "ffmpeg failed mid-extract";
+        case VIDEO_THUMBNAILS_CODES.PROBE_FAILED:
+            return "ffprobe failed";
+        case VIDEO_THUMBNAILS_CODES.VIDEO_INVALID:
+            return "input is not a valid video";
+        case VIDEO_THUMBNAILS_CODES.INVALID_TIMESTAMP:
+            return "timestamp is not HH:MM:SS(.mmm)?";
+        case VIDEO_THUMBNAILS_CODES.INVALID_DIMENSIONS:
+            return "width/height/count <= 0";
+        case VIDEO_THUMBNAILS_CODES.INVALID_OPTIONS:
+            return "Zod boundary validation failed";
+        case VIDEO_THUMBNAILS_CODES.FORMAT_UNSUPPORTED:
+            return "output format not in jpg|png|webp";
+        case VIDEO_THUMBNAILS_CODES.RUNNER_UNAVAILABLE:
+            return "ffmpeg binary not available";
+        case VIDEO_THUMBNAILS_CODES.ABORTED:
+            return "AbortSignal triggered";
+    }
+}
+```
+
+## API Reference
+
+- `VIDEO_THUMBNAILS_CODES` — `Readonly<Record<Reason, "VIDEO_THUMBNAILS.<Reason>">>` for the
+  nine codes `EXTRACT_FAILED`, `PROBE_FAILED`, `VIDEO_INVALID`, `INVALID_TIMESTAMP`,
+  `INVALID_DIMENSIONS`, `INVALID_OPTIONS`, `FORMAT_UNSUPPORTED`, `RUNNER_UNAVAILABLE`,
+  `ABORTED`. Frozen at construction.
+- `VideoThumbnailsCode` — literal union of every value in the registry; use as the parameter
+  type for handlers that need to switch on failure mode.
+
+## Implementation Notes
+
+The registry is intentionally minimal — codes are added only when there is a corresponding
+`throw` site in `src/`. Removing a code requires a deprecation window: keep the entry in the
+registry, raise the new code from the call site, then drop the entry in a follow-up change so
+external callers have one release to migrate `case` clauses. Codes never carry payload — that
+lives on `SuaveplanError.context`. The frozen object means accidental mutation throws at
+runtime in strict mode, which preserves the registry-as-contract invariant.