first commit

docs/networking/drive/drive-template/src/validate/file.md

@@ -0,0 +1,54 @@
+# file
+
+## Purpose
+
+Per-file consistency invariants for every `FileTemplate` (DTP-09). Files that fail any invariant are rejected with `DRIVE.TEMPLATE_MALFORMED` and a `context` object naming the offending file path. The walker recurses through the folder tree so the failure surfaces with the full path from the root.
+
+## Features
+
+- `assertFolderFileInvariants(folder)` — recurses, checking every nested file.
+- `assertFile(file, path)` — single-file check, used directly in the hydration scheduler when files arrive piecemeal.
+- `MIN_CHUNK_SIZE_EXCLUSIVE` constant (164) — the chunk-format header overhead requires at least one payload byte.
+- Five gates: `chunkSize > 164`, `totalChunks * chunkSize >= size`, `manifestKey` non-empty, `checksum` matches `'blake3:<hex>'` or `'sha256:<hex>'`, `manifestSig` non-empty.
+
+## Usage: Basic Example
+
+```ts
+import { assertFile } from "@suaveplan/drive-template";
+
+assertFile(file, "/photos/wedding.jpg");
+// throws DriveTemplateError(DRIVE.TEMPLATE_MALFORMED) on any invariant violation
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    assertFolderFileInvariants,
+    DTP_CODES,
+    DriveTemplateError,
+} from "@suaveplan/drive-template";
+
+function reportFileFailures(folder) {
+    try {
+        assertFolderFileInvariants(folder);
+        return null;
+    } catch (err) {
+        if (err instanceof DriveTemplateError && err.code === DTP_CODES.TEMPLATE_MALFORMED) {
+            const ctx = err.context as { file: string; issue: string };
+            return { file: ctx.file, issue: ctx.issue };
+        }
+        throw err;
+    }
+}
+```
+
+## API Reference
+
+- `assertFolderFileInvariants(folder: FolderTemplate): void`.
+- `assertFile(file: FileTemplate, path: string): void`.
+- `MIN_CHUNK_SIZE_EXCLUSIVE: 164` — exclusive lower bound for `chunkSize`.
+
+## Implementation Notes
+
+The 164-byte chunk-format overhead matches `@suaveplan/drive-plugin-chunks` `HEADER_SIZE`. Keeping `chunkSize` strictly greater than the header ensures every chunk carries at least one byte of payload — otherwise the manifest would describe a file that consists entirely of headers with no bytes. The checksum regex accepts both `blake3:<hex>` and `sha256:<hex>` forms so consumers running on platforms without BLAKE3 native bindings can still ship templates checksummed via SHA-256. Folder traversal accumulates the path through the spread operator, which keeps the failure context's `file` field human-readable for any UI surfacing the error.