first commit

docs/foundation/data/media/src/validation/validation.md

@@ -0,0 +1,78 @@
+# Validation
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Validates media bytes against a `MediaConstraints` rule set covering
+size floors and ceilings, type allowlists, MIME allowlists, width /
+height / duration limits, and an optional custom predicate. The module
+exposes a synchronous helper for cheap byte-level checks and an async
+helper that also honours the constraint predicate plus the metadata
+extractor hook.
+
+## Features
+
+- `validateMedia(input, constraints, opts?)` — sync validation.
+- `validateMediaAsync(input, constraints, opts?)` — async validation
+  that runs the predicate hook.
+- `assertValidMedia(...)` — throwing variant that yields
+  `MediaError(MEDIA.VALIDATION_FAILED)` on failure.
+- Zod-validated constraints — malformed input throws
+  `MediaError(MEDIA.INVALID_CONSTRAINTS)`; use `skipConstraintValidation`
+  to opt out on hot paths.
+- Predicate failure wrapping — caller exceptions surface as
+  `MediaError(MEDIA.PREDICATE_FAILED)` with the original error chained.
+- OTel `media_validate_total` counter + `media_op_latency_ms` histogram
+  emitted on every invocation.
+
+## Usage: Basic
+
+```ts
+import { validateMedia } from "@suaveplan/media";
+
+const result = validateMedia(myBytes, {
+    maxSize: 1_000_000,
+    allowedTypes: ["image"],
+});
+if (!result.valid) {
+    console.warn(result.errors);
+}
+```
+
+## Usage: Advanced
+
+```ts
+import { validateMediaAsync } from "@suaveplan/media";
+
+const result = await validateMediaAsync(myBytes, {
+    maxSize: 5_000_000,
+    allowedTypes: ["image", "video"],
+    allowedMimeTypes: ["image/png", "video/mp4"],
+    maxWidth: 4096,
+    maxHeight: 4096,
+    maxDuration: 60,
+    predicate: async (meta) =>
+        meta.size === 0 ? "empty payload" : null,
+});
+```
+
+## API Reference
+
+- `ValidateOptions` — extends `MetadataOptions` with
+  `skipConstraintValidation`.
+- `validateMedia(input, constraints, opts?)` — sync `MediaResult`.
+- `validateMediaAsync(input, constraints, opts?)` —
+  `Promise<MediaResult>`.
+- `assertValidMedia(input, constraints, opts?)` — `MediaMetadata`,
+  throws on validation failure.
+
+## Implementation Notes
+
+`checkConstraints` is shared between the sync and async paths so the
+rule semantics are identical. Empty input is rejected up-front with
+`MEDIA.EMPTY_INPUT` before any metadata work happens. The predicate
+runs after every other check so callers can rely on the base errors
+being populated first.