first commit

docs/foundation/data/serialize/src/error-codes/error-codes.md

@@ -0,0 +1,65 @@
+# error-codes
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`error-codes` is the public re-export surface for the serialization error code registry. It imports `serialize-error` as a side effect — which ensures all `SERIALIZE_CODES` are registered with `@suaveplan/error`'s global code table at the moment any consumer first imports this module — and then re-exports the codes and the `SerializationErrorCode` union type under the stable public alias `SERIALIZE_ERROR_METADATA`.
+
+The module also exports a `registerSerializeErrorCodes()` function for callers that need an explicit, named registration step (e.g., test setup files or dependency injection bootstraps) rather than relying on side-effect imports.
+
+## Features
+
+- Triggers side-effect registration of all `SERIALIZE_CODES` via a single import
+- Re-exports `SERIALIZE_CODES` as `SERIALIZE_ERROR_METADATA` to match the `@suaveplan/error` naming convention for externally-published code registries
+- Re-exports the `SerializationErrorCode` union type for use in typed error handling
+- Provides an explicit `registerSerializeErrorCodes()` no-op function for consumers that prefer named-import bootstrapping over implicit side effects
+- Lightweight: no runtime logic beyond the re-export and the single side-effect import
+
+## Usage: Basic Example
+
+```ts
+import { SERIALIZE_ERROR_METADATA } from "@suaveplan/serialize/error-codes";
+
+// SERIALIZE_ERROR_METADATA is now populated with all SERIALIZE_* codes
+console.log(SERIALIZE_ERROR_METADATA["CODEC.CIRCULAR_REFERENCE"]);
+// => "SERIALIZE.CODEC.CIRCULAR_REFERENCE"
+```
+
+## Usage: Advanced Example
+
+```ts
+import { registerSerializeErrorCodes, SERIALIZE_ERROR_METADATA, type SerializationErrorCode } from "@suaveplan/serialize/error-codes";
+import { SuaveplanError } from "@suaveplan/error";
+
+// Explicit bootstrap for DI containers that prefer named calls
+registerSerializeErrorCodes(); // no-op, side effect already happened at import
+
+function isSerializeError(err: unknown): err is SuaveplanError {
+  if (!(err instanceof SuaveplanError)) return false;
+  const codes = Object.values(SERIALIZE_ERROR_METADATA) as SerializationErrorCode[];
+  return codes.includes(err.code as SerializationErrorCode);
+}
+```
+
+## API Reference
+
+### `SERIALIZE_ERROR_METADATA`
+
+Re-export of `SERIALIZE_CODES` from `./errors/codes`. A frozen record mapping each short code key (e.g., `"CODEC.CIRCULAR_REFERENCE"`) to its fully-qualified `"SERIALIZE.CODEC.CIRCULAR_REFERENCE"` string.
+
+### `type SerializationErrorCode`
+
+Union of all values in `SERIALIZE_ERROR_METADATA`. Use this type to narrow `SuaveplanError.code` in catch blocks.
+
+### `registerSerializeErrorCodes(): void`
+
+Intentional no-op. The actual registration occurs as a side effect of importing this module. The function exists for callers that want a named, explicit registration call for documentation or DI-bootstrap clarity.
+
+## Implementation Notes
+
+The side-effect import pattern (`import "./errors/serialize-error.js"`) is the standard approach used across all `@suaveplan/*` packages to ensure error codes are registered before any error can be constructed or inspected. Consumers that import this module at application startup (or in a test setup file) are guaranteed that all `SERIALIZE_*` codes are present in the global registry even if no serialization operation has been attempted yet.
+
+The `registerSerializeErrorCodes()` stub is provided as a forward-compatible hook: if registration ever needs to become asynchronous or accept configuration parameters, the function signature can evolve without breaking existing callers.