first commit

docs/security-stack/security/vault-sync/src/errors/codes.md

@@ -0,0 +1,74 @@
+# Error code registry
+
+## Purpose
+
+`codes.ts` defines the canonical, frozen registry of every fully-qualified
+error code emitted by `@suaveplan/vault-sync`. Codes are stable string
+literals consumers can switch on — they are part of the public API contract.
+The registry doubles as the source of truth for the
+[`VaultSyncCode`](./crypto-vault-error.md) type union, so adding a new code
+in a single place automatically widens the type and the
+`spec-conformance.test.ts` "every code is thrown" gate must observe the new
+value before the change can ship.
+
+## Features
+
+- Single source of truth for every `VAULTSYNC.*` code emitted from production
+- Frozen registry produced via `defineCodes("VAULTSYNC", ...)` from `@suaveplan/error`
+- Inferred literal-union type `VaultSyncCode` for exhaustive switch-narrowing
+- Import-time freezing — codes cannot be added or removed at runtime
+- Zero circular-dep risk: registry depends only on `@suaveplan/error`
+
+## Usage: Basic Example
+
+```ts
+import { VAULT_SYNC_CODES } from "@suaveplan/vault-sync/errors";
+
+console.log(VAULT_SYNC_CODES["MERGE.STRATEGY_UNKNOWN"]);
+// → "VAULTSYNC.MERGE.STRATEGY_UNKNOWN"
+```
+
+## Usage: Advanced Example
+
+```ts
+import { VaultSyncError } from "@suaveplan/vault-sync";
+import { VAULT_SYNC_CODES, type VaultSyncCode } from "@suaveplan/vault-sync/errors";
+
+function describeFailure(err: unknown): string {
+    if (!(err instanceof VaultSyncError)) return "non-vault-sync failure";
+    const code: VaultSyncCode = err.code;
+    switch (code) {
+        case VAULT_SYNC_CODES["MERGE.STRATEGY_UNKNOWN"]:
+            return "Unknown CRDT merge strategy";
+        case VAULT_SYNC_CODES["SYNC.PAYLOAD_TAMPERED"]:
+            return "Sync payload integrity check failed";
+        case VAULT_SYNC_CODES["QUEUE.DEPTH_EXCEEDED"]:
+            return "Offline queue at hard cap";
+        default:
+            // Exhaustive: TypeScript will fail if a new code is unhandled.
+            return `unhandled vault-sync code: ${code as string}`;
+    }
+}
+```
+
+## API Reference
+
+- `VAULT_SYNC_CODES` — `Readonly<Record<reason, "VAULTSYNC.<REASON>">>`. Frozen
+  via `Object.freeze`. Iterating with `Object.values(VAULT_SYNC_CODES)` yields
+  every code that may be emitted from production paths.
+- `type VaultSyncCode` — the literal union derived from `typeof
+  VAULT_SYNC_CODES[keyof typeof VAULT_SYNC_CODES]`. Use as the `TCode` type
+  parameter of `SuaveplanError`.
+
+## Implementation Notes
+
+The registry is intentionally flat — there is no nested structure or runtime
+metadata. Metadata such as severity, retryability, and i18n message keys live
+where they are needed (the throwing call site, the i18n catalog, the OTel
+adapter), not on the code object itself.
+
+Any new entry must be paired with:
+
+1. A production path that throws the code under realistic conditions.
+2. A new branch in `spec-conformance.test.ts` confirming the code is reachable.
+3. An update to the codes table in the package `README.md`.