# manifest.schema

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

Defines the Zod schemas that gate every manifest the plugin parses from untrusted bytes. Schema validation is the line between "raw bytes that may or may not be a manifest" and "a typed `Manifest` ready to flow through the rest of the plugin"; it runs before signature verification so structural errors surface as `MANIFEST_INVALID` without paying the cost of an Ed25519 verify.

## Features

- `ManifestSchema` — the top-level schema for a complete signed manifest, including a 64-byte signature, version literal `0x0001`, 32-byte `fileId`, positive `chunkSize` / `totalChunks`, and an array of per-chunk entries.
- `ManifestEncryptionSchema` — the embedded encryption envelope: `algo` is locked to `"xchacha20poly1305"`, `baseNonce` is exactly 24 bytes, and `fileKeyWrapped` is left length-flexible to leave room for future KEMs.
- `ManifestChunkEntrySchema` — per-chunk entries with non-negative `chunkId` / `payloadLen` and a 32-byte SHA-256 `hash`.
- `fileSize` accepts both `bigint` and decimal-string inputs and normalises to `bigint`, which makes JSON-serialised manifests round-trip cleanly even though native JSON has no `bigint` type.

## Usage: Basic Example

```ts
import { ManifestSchema } from "@suaveplan/drive-plugin-chunks";

const result = ManifestSchema.safeParse(decodedFromJson);
if (!result.success) throw new Error(result.error.message);
const manifest = result.data;
```

## Usage: Advanced Example

```ts
import {
    ManifestChunkEntrySchema,
    ManifestEncryptionSchema,
    ManifestSchema,
} from "@suaveplan/drive-plugin-chunks";

function isLooselyValid(maybe: unknown): boolean {
    return ManifestSchema.safeParse(maybe).success;
}

const enc = ManifestEncryptionSchema.parse({
    algo: "xchacha20poly1305",
    fileKeyWrapped: new Uint8Array(32),
    baseNonce: new Uint8Array(24),
});
const entry = ManifestChunkEntrySchema.parse({
    chunkId: 0,
    hash: new Uint8Array(32),
    payloadLen: 50,
});
```

## API Reference

- `ManifestSchema: ZodTypeAny` — top-level boundary schema.
- `ManifestEncryptionSchema: ZodTypeAny` — encryption sub-schema.
- `ManifestChunkEntrySchema: ZodTypeAny` — chunk-entry sub-schema.
- `type ManifestInput = z.input<typeof ManifestSchema>` — the pre-transform JSON shape.

## Implementation Notes

The `// schema: boundary-only` annotation tells the conformance script that these schemas are deliberately part of the public surface even when this file is the only place inside `src/` that calls `.parse` / `.safeParse` on them. Removing the annotation (or moving the schemas) would be an enterprise-grade signal change so consumers should not depend on internal validation paths.