first commit

docs/networking/drive/drive-plugin-chunks/src/schemas/manifest.schema.md

@@ -0,0 +1,61 @@
+# 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.