first commit

docs/foundation/data/serialize/src/codec/msgpack/msgpack-decode.md

@@ -0,0 +1,75 @@
+# msgpack-decode
+
+## Purpose
+
+Implements `decodeBinary`, the inverse of `encodeBinary`. Given a MessagePack binary buffer produced by the encoder, it reconstructs the original JavaScript value by first decoding the msgpack wire bytes to an intermediate plain-JS-object representation and then applying the same tag-based reconstruction logic used by `deserialize`.
+
+The two-phase approach (msgpack decode → tag reconstruct) keeps the decoder code minimal and reuses the same registry lookup path as the JSON decoder.
+
+## Features
+
+- Full inverse of `encodeBinary`: all built-in and custom registered types are reconstructed
+- `UnsupportedTypeError` thrown on unrecognised `__t` tags (same strict policy as JSON decoder)
+- Reuses a single shared `Decoder` instance for zero allocation overhead across calls
+- `DeserializeOptions` parameter accepted for API consistency with the JSON codec (signal not yet applied internally, as msgpack decode is synchronous and very fast)
+
+## Usage: Basic Example
+
+```typescript
+import { decodeBinary, encodeBinary } from "@suaveplan/serialize";
+
+const original = new Map([["key", new Date()]]);
+const bytes = encodeBinary(original);
+const restored = decodeBinary(bytes) as Map<string, Date>;
+
+restored instanceof Map;           // true
+restored.get("key") instanceof Date; // true
+```
+
+## Usage: Advanced Example
+
+```typescript
+import { decodeBinary, UnsupportedTypeError } from "@suaveplan/serialize";
+
+async function receiveMessage(bytes: Uint8Array) {
+  try {
+    const value = decodeBinary(bytes);
+    return value;
+  } catch (err) {
+    if (err instanceof UnsupportedTypeError) {
+      // The sender used a type tag unknown to this receiver.
+      // Either register the type or reject the message.
+      throw new Error(`Unknown type: ${err.context?.tag}`);
+    }
+    throw err;
+  }
+}
+```
+
+## API Reference
+
+### `decodeBinary(bytes: Uint8Array, opts?: DeserializeOptions): unknown`
+
+Decode a MessagePack buffer to the original JavaScript value.
+
+**Parameters:**
+
+- `bytes` — a `Uint8Array` produced by `encodeBinary`
+- `opts` — `DeserializeOptions` (accepted for API parity; signal not currently applied within this synchronous path)
+
+**Returns:** the reconstructed JavaScript value.
+
+**Throws:**
+
+- `UnsupportedTypeError` when a `__t` tag has no registered decoder
+- `RangeError` or `TypeError` from `@msgpack/msgpack` if the input bytes are malformed
+
+### `DeserializeOptions`
+
+See `json-decode.md`.
+
+## Implementation Notes
+
+- A single shared `Decoder` instance is reused to avoid per-call setup overhead; the decoder is stateless between calls.
+- The `postDecode` function is structurally identical to the inner `decodeValue` used by `json-decode.ts`. Future refactoring could extract it to a shared utility; currently it is kept local to avoid premature abstraction.
+- The `opts` parameter is accepted but currently unused because the msgpack decode step is synchronous and does not lend itself to mid-stream cancellation without a streaming API.