first commit

docs/foundation/data/dedup/src/errors/dedup-error.md

@@ -0,0 +1,82 @@
+# DedupError
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`DedupError` is the error substrate for the `@suaveplan/dedup` package. It extends the built-in `Error` class with a stable `code` field so callers can branch on specific failure modes without parsing message strings. Every error thrown by the dedup engine or merge strategies uses this class.
+
+## Features
+
+- Typed `code` field for reliable programmatic error handling
+- Two stable error codes: `DEDUP.INVALID_CONFIG` and `DEDUP.STRATEGY_ERROR`
+- Lightweight — no external dependencies; usable in any runtime environment
+- `name` set to `'DedupError'` for readable stack traces and `instanceof` checks
+
+## Usage: Basic Example
+
+```ts
+import { DedupError, DEDUP_CODES } from '@suaveplan/dedup/errors';
+
+try {
+  engine.detect(entities);
+} catch (err) {
+  if (err instanceof DedupError && err.code === DEDUP_CODES.INVALID_CONFIG) {
+    console.error('Configuration is invalid:', err.message);
+  }
+}
+```
+
+## Usage: Advanced Example
+
+```ts
+import { DedupError, DEDUP_CODES } from '@suaveplan/dedup/errors';
+
+function safeMerge(engine: DedupEngine, group: DuplicateGroup, strategy: MergeStrategy) {
+  try {
+    return engine.merge(group, strategy);
+  } catch (err) {
+    if (err instanceof DedupError) {
+      if (err.code === DEDUP_CODES.STRATEGY_ERROR) {
+        // Fall back to manual strategy
+        return engine.merge(group, manualStrategy);
+      }
+    }
+    throw err;
+  }
+}
+```
+
+## API Reference
+
+### `DEDUP_CODES`
+
+```ts
+const DEDUP_CODES: {
+  INVALID_CONFIG: 'DEDUP.INVALID_CONFIG';
+  STRATEGY_ERROR: 'DEDUP.STRATEGY_ERROR';
+}
+```
+
+- `INVALID_CONFIG` — thrown when `DedupConfig` fails Zod validation (missing required fields, invalid weights, etc.)
+- `STRATEGY_ERROR` — thrown when a merge strategy throws an unexpected error
+
+### `DedupError`
+
+```ts
+class DedupError extends Error {
+  readonly code: string;
+  constructor(message: string, code: string);
+}
+```
+
+- `message` — human-readable description of the failure
+- `code` — one of the `DEDUP_CODES` constants
+- `name` — always `'DedupError'`
+
+## Implementation Notes
+
+This package is a leaf (no `@suaveplan/*` runtime dependencies), so it cannot depend on `@suaveplan/error`. The local `DedupError` class provides the same `code`-based discriminator pattern used throughout the project without introducing a circular dependency. If `@suaveplan/error` is added as a dependency in the future, this class should be migrated to extend `SuaveplanError`.
+
+All errors thrown by the engine and merge strategies include a `code` value drawn from `DEDUP_CODES`. Callers should always `instanceof DedupError` before reading `.code` to avoid narrowing mistakes when third-party errors propagate through the dedup boundary. The code constants are exported as a plain `const` object rather than an enum to keep the module tree-shakeable and to avoid TypeScript enum pitfalls in strict ESM environments.