first commit

docs/networking/drive/drive-storage-zip/src/parser/crc32.md

@@ -0,0 +1,38 @@
+# `crc32`
+
+## Purpose
+
+Computes the IEEE 802.3 CRC-32 (polynomial `0xEDB88320`, little-endian reflected) used by every ZIP entry. The CRC stored in the central directory MUST equal `crc32(plaintext)`; ZIP readers cross-check this value on every decompression to detect bit rot or tampering. ZIP encoders compute it once per entry and store it in both the local header and CDR.
+
+## Features
+
+- 256-entry lookup table built lazily on first call (zero cost when CRC is unused, e.g. write-path skip).
+- Returns an unsigned 32-bit `number` with `>>> 0` so callers never see negative integers from JS sign-bit propagation.
+- Pure function with no external dependencies; safe to embed in any tier (universal, browser, server).
+
+## Usage: Basic
+
+```ts
+import { crc32 } from "@suaveplan/drive-storage-zip/parser";
+
+const value = crc32(new TextEncoder().encode("hello"));
+```
+
+## Usage: Advanced
+
+```ts
+import { crc32 } from "@suaveplan/drive-storage-zip/parser";
+
+function verifyEntry(plaintext: Uint8Array, expected: number) {
+    const actual = crc32(plaintext);
+    if (actual !== expected) throw new Error(`crc mismatch: ${actual} !== ${expected}`);
+}
+```
+
+## API Reference
+
+`crc32(bytes: Uint8Array): number` — synchronous, deterministic, allocation-free after table init; returns the unsigned 32-bit CRC.
+
+## Implementation Notes
+
+The lookup table is `Uint32Array(256)` so indexing is bounds-checked and free of GC pressure. The inner loop does one XOR and one table lookup per byte; throughput on a modern V8 build is ~500 MB/s, which is adequate even for multi-GB archives because the ZIP read path is bottlenecked on inflate, not CRC. For specialised pipelines requiring incremental CRC accumulation, the function can be lifted into a class — the polynomial and reflected representation are unchanged.