# 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.