@velajs/errors 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.1.0
+
+### Minor Changes
+
+- ac4e9f8: Add the `@velajs/errors/fingerprint` subpath: a zero-dependency, cross-runtime error-grouping hash. `fingerprintError({ functionPath, message, code? })` returns a stable 16-hex-char digest over `functionPath` plus a normalized message bucket — `code` is metadata and never hashed, so redacted wire errors and raw server-side errors group identically. Ships `bucketMessage` (strips URLs, UUIDs, IPs, ids, paths, timestamps; ReDoS-clamped), `FINGERPRINT_VERSION` for persisted-fingerprint migrations, and a portable synchronous `sha256Hex` (content-addressing only, never a security primitive). Grouping approach inspired by @superlog/fingerprint (Apache-2.0), independently implemented.
+
+## 1.0.1
+
+### Patch Changes
+
+- 49f72ad: Modernize the package build, validation, and release toolchain.
+
 All notable changes to `@velajs/errors` are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## 1.0.0

package/README.md

@@ -73,6 +73,30 @@ return Response.json(body, { status });
 
 `invariant(condition, message, data?)` narrows types (`asserts condition`) and, on failure, throws an `internal`-coded `VelaError` — always redacted by rule 2. `unreachable(value: never)` is its exhaustiveness-check companion.
 
+## Error fingerprinting (`@velajs/errors/fingerprint`)
+
+A separate, tree-shakeable subpath that turns noisy repeats of the same error into one stable **issue** identity. It is zero-dependency and computes identically in the browser, the workerd runtime, and Node, so a live in-flight error and one recomputed later from a persisted log row collapse onto the same fingerprint.
+
+```ts
+import { fingerprintError, bucketMessage, FINGERPRINT_VERSION } from '@velajs/errors/fingerprint';
+
+// 16-hex-char stable grouping id over functionPath :: bucket(message).
+fingerprintError({ functionPath: 'orders:get', message: 'order 550e8400-… not found' });
+
+// The `code` is metadata and is NEVER hashed — the redacted wire view (whose
+// code toErrorBody may rewrite or drop) and the raw server-side error group
+// together. It also works straight off toErrorBody's output:
+const { body } = toErrorBody(err);
+fingerprintError({ functionPath, message: body.error.message, code: body.error.code });
+```
+
+- **`fingerprintError({ functionPath, message, code? }): string`** — the stable 16-hex grouping hash. `code` is display metadata only and is never folded into the hash.
+- **`bucketMessage(message): string`** — the exported normalizer. Strips per-occurrence noise (URLs, request/filesystem paths, UUIDs, IPs, long numeric/hex ids, timestamps, emails) so a route-scanner sweep of 404s with varying paths folds to a single fingerprint. Input is clamped (~1 KB) before any regex runs as a ReDoS guard.
+- **`FINGERPRINT_VERSION`** — bump whenever the bucketer heuristics change; changed heuristics re-partition history, so consumers that persist fingerprints store this alongside each hash to know when a recompute is due.
+- **`sha256Hex(input): string`** — the internal portable synchronous SHA-256 (no `node:crypto`, no async `crypto.subtle`), also exported. **Content-addressing / grouping only — never a security or MAC primitive.**
+
+> The message-normalization / grouping approach is inspired by [`@superlog/fingerprint`](https://github.com/superloglabs/superlog) (Apache-2.0). This is an independent, clean-room implementation.
+
 ## API
 
 - `VelaError`, `VelaErrorOptions` — the one error and its constructor options.
@@ -81,3 +105,4 @@ return Response.json(body, { status });
 - `defineErrorCatalog`, `composeCatalogs`, `Catalog`, `ErrorCatalogEntry` — catalog authoring.
 - `CORE_CATALOG`, `CORE_ENTRIES`, `CoreErrorCode`, `STATUS_TO_CODE` — the core catalog and its lookups.
 - `invariant`, `unreachable` — internal-coded assertion helpers.
+- `@velajs/errors/fingerprint`: `fingerprintError`, `ErrorFingerprintInput`, `bucketMessage`, `FINGERPRINT_VERSION`, `sha256Hex` — the error-grouping subpath.

package/dist/fingerprint.d.ts

@@ -0,0 +1,61 @@
+//#region src/sha256.d.ts
+/**
+ * Portable, synchronous SHA-256 (FIPS 180-4) returning a lowercase hex digest.
+ *
+ * Implemented straight from the published standard so this file carries no
+ * runtime dependency and produces byte-for-byte identical output on every
+ * target Vela supports — browsers, the Cloudflare Workers (workerd) runtime,
+ * and Node. Neither built-in alternative fits the fingerprinter:
+ *   - `node:crypto` (`createHash`) is absent in browsers and needs
+ *     `nodejs_compat` to load in workerd.
+ *   - `crypto.subtle.digest` is async, which is clumsy for folding error rows
+ *     into a group key one synchronous call at a time.
+ *
+ * SECURITY: this is a plain, non-constant-time digest meant ONLY for
+ * content-addressing and grouping keys. Never use it as a MAC, a password hash,
+ * or any other authentication or security primitive.
+ */
+declare const sha256Hex: (input: string) => string;
+//#endregion
+//#region src/fingerprint.d.ts
+/**
+ * Heuristic generation of {@link bucketMessage}. Bump it whenever the
+ * normalizer's rules change: changed heuristics re-partition history (they may
+ * split one group into several or merge several into one), so a consumer that
+ * persists fingerprints stores this alongside each hash to know which
+ * generation produced it and when a recompute/backfill is due.
+ */
+declare const FINGERPRINT_VERSION: number;
+/**
+ * Normalize an error message into its grouping bucket: strip per-occurrence
+ * noise (urls, uuids, ips, request/filesystem paths, long ids, numbers) and
+ * fold whitespace/case, so occurrences of the same logical error collapse to
+ * one bucket. Exported for direct testing of the normalization heuristics.
+ */
+declare const bucketMessage: (message: string) => string;
+/** Everything a fingerprint source can supply. */
+interface ErrorFingerprintInput {
+  /**
+   * What raised the error — the invoked function/route path, e.g.
+   * `messages:list`. Part of the grouping key.
+   */
+  functionPath: string;
+  /** Human-readable message (may embed user input); normalized into the key. */
+  message: string;
+  /**
+   * Machine error code, when known. Pure metadata: **never folded into the
+   * hash**, so the redacted wire error (which may rewrite or drop the code) and
+   * the raw server-side error still produce the same fingerprint.
+   */
+  code?: string;
+}
+/**
+ * Fold an error into its stable 16-hex-character grouping fingerprint. Pure and
+ * synchronous, safe to call per row when grouping a log page. The same
+ * `functionPath` and logically-equal `message` always yield the same hash
+ * regardless of the `code` supplied or per-occurrence noise in the message.
+ */
+declare const fingerprintError: (input: ErrorFingerprintInput) => string;
+//#endregion
+export { ErrorFingerprintInput, FINGERPRINT_VERSION, bucketMessage, fingerprintError, sha256Hex };
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/fingerprint.js

@@ -0,0 +1,169 @@
+//#region src/sha256.ts
+/**
+* Portable, synchronous SHA-256 (FIPS 180-4) returning a lowercase hex digest.
+*
+* Implemented straight from the published standard so this file carries no
+* runtime dependency and produces byte-for-byte identical output on every
+* target Vela supports — browsers, the Cloudflare Workers (workerd) runtime,
+* and Node. Neither built-in alternative fits the fingerprinter:
+*   - `node:crypto` (`createHash`) is absent in browsers and needs
+*     `nodejs_compat` to load in workerd.
+*   - `crypto.subtle.digest` is async, which is clumsy for folding error rows
+*     into a group key one synchronous call at a time.
+*
+* SECURITY: this is a plain, non-constant-time digest meant ONLY for
+* content-addressing and grouping keys. Never use it as a MAC, a password hash,
+* or any other authentication or security primitive.
+*/
+const BLOCK_BYTES = 64;
+const ROUND = Uint32Array.of(1116352408, 1899447441, 3049323471, 3921009573, 961987163, 1508970993, 2453635748, 2870763221, 3624381080, 310598401, 607225278, 1426881987, 1925078388, 2162078206, 2614888103, 3248222580, 3835390401, 4022224774, 264347078, 604807628, 770255983, 1249150122, 1555081692, 1996064986, 2554220882, 2821834349, 2952996808, 3210313671, 3336571891, 3584528711, 113926993, 338241895, 666307205, 773529912, 1294757372, 1396182291, 1695183700, 1986661051, 2177026350, 2456956037, 2730485921, 2820302411, 3259730800, 3345764771, 3516065817, 3600352804, 4094571909, 275423344, 430227734, 506948616, 659060556, 883997877, 958139571, 1322822218, 1537002063, 1747873779, 1955562222, 2024104815, 2227730452, 2361852424, 2428436474, 2756734187, 3204031479, 3329325298);
+const rotr = (word, bits) => word >>> bits | word << 32 - bits;
+const toHex8 = (word) => (word >>> 0).toString(16).padStart(8, "0");
+const sha256Hex = (input) => {
+	const message = new TextEncoder().encode(input);
+	const bitLength = message.length * 8;
+	const totalBytes = (Math.floor((message.length + 8) / BLOCK_BYTES) + 1) * BLOCK_BYTES;
+	const padded = new Uint8Array(totalBytes);
+	padded.set(message);
+	padded[message.length] = 128;
+	const frame = new DataView(padded.buffer);
+	frame.setUint32(totalBytes - 8, Math.floor(bitLength / 4294967296), false);
+	frame.setUint32(totalBytes - 4, bitLength >>> 0, false);
+	let h0 = 1779033703;
+	let h1 = 3144134277;
+	let h2 = 1013904242;
+	let h3 = 2773480762;
+	let h4 = 1359893119;
+	let h5 = 2600822924;
+	let h6 = 528734635;
+	let h7 = 1541459225;
+	const schedule = /* @__PURE__ */ new Uint32Array(64);
+	for (let base = 0; base < totalBytes; base += BLOCK_BYTES) {
+		for (let t = 0; t < 16; t += 1) schedule[t] = frame.getUint32(base + t * 4, false);
+		for (let t = 16; t < 64; t += 1) {
+			const x = schedule[t - 15];
+			const y = schedule[t - 2];
+			const sigma0 = rotr(x, 7) ^ rotr(x, 18) ^ x >>> 3;
+			const sigma1 = rotr(y, 17) ^ rotr(y, 19) ^ y >>> 10;
+			schedule[t] = schedule[t - 16] + sigma0 + schedule[t - 7] + sigma1 >>> 0;
+		}
+		let a = h0;
+		let b = h1;
+		let c = h2;
+		let d = h3;
+		let e = h4;
+		let f = h5;
+		let g = h6;
+		let h = h7;
+		for (let t = 0; t < 64; t += 1) {
+			const bigSigma1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+			const choose = e & f ^ ~e & g;
+			const t1 = h + bigSigma1 + choose + ROUND[t] + schedule[t] >>> 0;
+			const t2 = (rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + (a & b ^ a & c ^ b & c) >>> 0;
+			h = g;
+			g = f;
+			f = e;
+			e = d + t1 >>> 0;
+			d = c;
+			c = b;
+			b = a;
+			a = t1 + t2 >>> 0;
+		}
+		h0 = h0 + a >>> 0;
+		h1 = h1 + b >>> 0;
+		h2 = h2 + c >>> 0;
+		h3 = h3 + d >>> 0;
+		h4 = h4 + e >>> 0;
+		h5 = h5 + f >>> 0;
+		h6 = h6 + g >>> 0;
+		h7 = h7 + h >>> 0;
+	}
+	return toHex8(h0) + toHex8(h1) + toHex8(h2) + toHex8(h3) + toHex8(h4) + toHex8(h5) + toHex8(h6) + toHex8(h7);
+};
+//#endregion
+//#region src/fingerprint.ts
+/**
+* `@velajs/errors/fingerprint` — zero-dependency, cross-runtime error grouping.
+*
+* Collapses noisy repeats of the same error into one stable "issue" identity: a
+* 16-hex-character hash over the function path plus a *normalized* message, so a
+* live in-flight error and one recomputed later from a persisted log row fold
+* onto the same fingerprint. The machine `code` rides along as metadata and is
+* deliberately excluded from the hash, so the redacted wire view produced by
+* `toErrorBody` and the raw server-side error group together.
+*
+* The digest is a portable synchronous SHA-256 (see `./sha256`) truncated to 16
+* hex chars — content-addressing only, never a security or MAC primitive.
+*
+* The message-normalization / grouping approach is inspired by
+* `@superlog/fingerprint` (Apache-2.0); this is an independent implementation.
+*/
+/**
+* Heuristic generation of {@link bucketMessage}. Bump it whenever the
+* normalizer's rules change: changed heuristics re-partition history (they may
+* split one group into several or merge several into one), so a consumer that
+* persists fingerprints stores this alongside each hash to know which
+* generation produced it and when a recompute/backfill is due.
+*/
+const FINGERPRINT_VERSION = 1;
+/**
+* Upper bound on the raw message length fed to the normalizer's regexes. A few
+* of them (the email and long-run patterns especially) can backtrack
+* super-linearly on a long delimiter-free run, and an error message can carry
+* attacker-influenced input of unbounded size — so clamp first to keep the
+* regex work bounded (a ReDoS guard). The final bucket is capped far below this
+* anyway, so the clamp is transparent for any real message.
+*/
+const MAX_INPUT_LENGTH = 1024;
+/** Cap on the normalized bucket so one runaway message can't bloat the key. */
+const MAX_BUCKET_LENGTH = 160;
+/** Hex length of the truncated digest used as the grouping id. */
+const HASH_LENGTH = 16;
+/** Namespaces the hash so a fingerprint can't collide with another content hash. */
+const SCHEME = "velajs.errors/fingerprint";
+/**
+* Ordered noise-stripping rules applied to a message before hashing. Each
+* replaces a class of per-occurrence identifier with a stable placeholder, so
+* two errors that differ only in their variable parts land in the same bucket.
+* Order matters: broader shapes (urls, timestamps) run before the greedy
+* numeric/id sweeps that would otherwise chew their digits.
+*/
+const NOISE_RULES = [
+	[/https?:\/\/\S+/gi, "[url]"],
+	[/\b[\w.+-]+@[\w.-]+\.[a-z]{2,}\b/gi, "[email]"],
+	[/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, "[uuid]"],
+	[/\b\d{4}-\d{2}-\d{2}[t ][\d:.]+z?(?:[+-]\d{2}:?\d{2})?\b/gi, "[time]"],
+	[/\b(?:\d{1,3}\.){3}\d{1,3}(?::\d+)?\b/g, "[ip]"],
+	[/(^|\s)\/\S*/g, "$1[path]"],
+	[/\b[a-z]:\\[^\s]*/gi, "[path]"],
+	[/\b0x[0-9a-f]+\b/gi, "[hex]"],
+	[/\b[a-z0-9_]{20,}\b/gi, "[id]"],
+	[/\b\d+\b/g, "[num]"]
+];
+/**
+* Normalize an error message into its grouping bucket: strip per-occurrence
+* noise (urls, uuids, ips, request/filesystem paths, long ids, numbers) and
+* fold whitespace/case, so occurrences of the same logical error collapse to
+* one bucket. Exported for direct testing of the normalization heuristics.
+*/
+const bucketMessage = (message) => {
+	if (message.length === 0) return "";
+	let text = message.length > MAX_INPUT_LENGTH ? message.slice(0, MAX_INPUT_LENGTH) : message;
+	for (const [pattern, placeholder] of NOISE_RULES) text = text.replace(pattern, placeholder);
+	text = text.replace(/\s+/g, " ").trim().toLowerCase();
+	return text.length > MAX_BUCKET_LENGTH ? text.slice(0, MAX_BUCKET_LENGTH) : text;
+};
+/**
+* Fold an error into its stable 16-hex-character grouping fingerprint. Pure and
+* synchronous, safe to call per row when grouping a log page. The same
+* `functionPath` and logically-equal `message` always yield the same hash
+* regardless of the `code` supplied or per-occurrence noise in the message.
+*/
+const fingerprintError = (input) => {
+	const source = input.functionPath.length > 0 ? input.functionPath : "unknown";
+	return sha256Hex(`${SCHEME}\n${source}\n${bucketMessage(input.message)}`).slice(0, HASH_LENGTH);
+};
+//#endregion
+export { FINGERPRINT_VERSION, bucketMessage, fingerprintError, sha256Hex };
+
+//# sourceMappingURL=fingerprint.js.map

package/dist/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","names":[],"sources":["../src/sha256.ts","../src/fingerprint.ts"],"sourcesContent":["/**\n * Portable, synchronous SHA-256 (FIPS 180-4) returning a lowercase hex digest.\n *\n * Implemented straight from the published standard so this file carries no\n * runtime dependency and produces byte-for-byte identical output on every\n * target Vela supports — browsers, the Cloudflare Workers (workerd) runtime,\n * and Node. Neither built-in alternative fits the fingerprinter:\n *   - `node:crypto` (`createHash`) is absent in browsers and needs\n *     `nodejs_compat` to load in workerd.\n *   - `crypto.subtle.digest` is async, which is clumsy for folding error rows\n *     into a group key one synchronous call at a time.\n *\n * SECURITY: this is a plain, non-constant-time digest meant ONLY for\n * content-addressing and grouping keys. Never use it as a MAC, a password hash,\n * or any other authentication or security primitive.\n */\n\nconst BLOCK_BYTES = 64;\n\n// Round constants K[0..63]: the first 32 bits of the fractional parts of the\n// cube roots of the first 64 primes (FIPS 180-4 §4.2.2).\nconst ROUND = Uint32Array.of(\n  0x428a2f98,\n  0x71374491,\n  0xb5c0fbcf,\n  0xe9b5dba5,\n  0x3956c25b,\n  0x59f111f1,\n  0x923f82a4,\n  0xab1c5ed5,\n  0xd807aa98,\n  0x12835b01,\n  0x243185be,\n  0x550c7dc3,\n  0x72be5d74,\n  0x80deb1fe,\n  0x9bdc06a7,\n  0xc19bf174,\n  0xe49b69c1,\n  0xefbe4786,\n  0x0fc19dc6,\n  0x240ca1cc,\n  0x2de92c6f,\n  0x4a7484aa,\n  0x5cb0a9dc,\n  0x76f988da,\n  0x983e5152,\n  0xa831c66d,\n  0xb00327c8,\n  0xbf597fc7,\n  0xc6e00bf3,\n  0xd5a79147,\n  0x06ca6351,\n  0x14292967,\n  0x27b70a85,\n  0x2e1b2138,\n  0x4d2c6dfc,\n  0x53380d13,\n  0x650a7354,\n  0x766a0abb,\n  0x81c2c92e,\n  0x92722c85,\n  0xa2bfe8a1,\n  0xa81a664b,\n  0xc24b8b70,\n  0xc76c51a3,\n  0xd192e819,\n  0xd6990624,\n  0xf40e3585,\n  0x106aa070,\n  0x19a4c116,\n  0x1e376c08,\n  0x2748774c,\n  0x34b0bcb5,\n  0x391c0cb3,\n  0x4ed8aa4a,\n  0x5b9cca4f,\n  0x682e6ff3,\n  0x748f82ee,\n  0x78a5636f,\n  0x84c87814,\n  0x8cc70208,\n  0x90befffa,\n  0xa4506ceb,\n  0xbef9a3f7,\n  0xc67178f2,\n);\n\nconst rotr = (word: number, bits: number): number => (word >>> bits) | (word << (32 - bits));\n\nconst toHex8 = (word: number): string => (word >>> 0).toString(16).padStart(8, '0');\n\nexport const sha256Hex = (input: string): string => {\n  const message = new TextEncoder().encode(input);\n  const bitLength = message.length * 8;\n\n  // One 0x80 marker byte, an 8-byte length trailer, zero fill in between, all\n  // rounded up to whole 64-byte blocks.\n  const totalBytes = (Math.floor((message.length + 8) / BLOCK_BYTES) + 1) * BLOCK_BYTES;\n  const padded = new Uint8Array(totalBytes);\n  padded.set(message);\n  padded[message.length] = 0x80;\n\n  const frame = new DataView(padded.buffer);\n  // Big-endian 64-bit bit length in the final 8 bytes. Fingerprint inputs are\n  // short strings, so the high word stays zero in practice, but compute it\n  // anyway for correctness.\n  frame.setUint32(totalBytes - 8, Math.floor(bitLength / 0x1_0000_0000), false);\n  frame.setUint32(totalBytes - 4, bitLength >>> 0, false);\n\n  // Initial state H[0..7]: first 32 bits of the fractional parts of the square\n  // roots of the first 8 primes (FIPS 180-4 §5.3.3).\n  let h0 = 0x6a09e667;\n  let h1 = 0xbb67ae85;\n  let h2 = 0x3c6ef372;\n  let h3 = 0xa54ff53a;\n  let h4 = 0x510e527f;\n  let h5 = 0x9b05688c;\n  let h6 = 0x1f83d9ab;\n  let h7 = 0x5be0cd19;\n\n  const schedule = new Uint32Array(64);\n\n  for (let base = 0; base < totalBytes; base += BLOCK_BYTES) {\n    for (let t = 0; t < 16; t += 1) {\n      schedule[t] = frame.getUint32(base + t * 4, false);\n    }\n    for (let t = 16; t < 64; t += 1) {\n      const x = schedule[t - 15] as number;\n      const y = schedule[t - 2] as number;\n      const sigma0 = rotr(x, 7) ^ rotr(x, 18) ^ (x >>> 3);\n      const sigma1 = rotr(y, 17) ^ rotr(y, 19) ^ (y >>> 10);\n      schedule[t] =\n        ((schedule[t - 16] as number) + sigma0 + (schedule[t - 7] as number) + sigma1) >>> 0;\n    }\n\n    let a = h0;\n    let b = h1;\n    let c = h2;\n    let d = h3;\n    let e = h4;\n    let f = h5;\n    let g = h6;\n    let h = h7;\n\n    for (let t = 0; t < 64; t += 1) {\n      const bigSigma1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);\n      const choose = (e & f) ^ (~e & g);\n      const t1 = (h + bigSigma1 + choose + (ROUND[t] as number) + (schedule[t] as number)) >>> 0;\n      const bigSigma0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);\n      const majority = (a & b) ^ (a & c) ^ (b & c);\n      const t2 = (bigSigma0 + majority) >>> 0;\n\n      h = g;\n      g = f;\n      f = e;\n      e = (d + t1) >>> 0;\n      d = c;\n      c = b;\n      b = a;\n      a = (t1 + t2) >>> 0;\n    }\n\n    h0 = (h0 + a) >>> 0;\n    h1 = (h1 + b) >>> 0;\n    h2 = (h2 + c) >>> 0;\n    h3 = (h3 + d) >>> 0;\n    h4 = (h4 + e) >>> 0;\n    h5 = (h5 + f) >>> 0;\n    h6 = (h6 + g) >>> 0;\n    h7 = (h7 + h) >>> 0;\n  }\n\n  return (\n    toHex8(h0) +\n    toHex8(h1) +\n    toHex8(h2) +\n    toHex8(h3) +\n    toHex8(h4) +\n    toHex8(h5) +\n    toHex8(h6) +\n    toHex8(h7)\n  );\n};\n","/**\n * `@velajs/errors/fingerprint` — zero-dependency, cross-runtime error grouping.\n *\n * Collapses noisy repeats of the same error into one stable \"issue\" identity: a\n * 16-hex-character hash over the function path plus a *normalized* message, so a\n * live in-flight error and one recomputed later from a persisted log row fold\n * onto the same fingerprint. The machine `code` rides along as metadata and is\n * deliberately excluded from the hash, so the redacted wire view produced by\n * `toErrorBody` and the raw server-side error group together.\n *\n * The digest is a portable synchronous SHA-256 (see `./sha256`) truncated to 16\n * hex chars — content-addressing only, never a security or MAC primitive.\n *\n * The message-normalization / grouping approach is inspired by\n * `@superlog/fingerprint` (Apache-2.0); this is an independent implementation.\n */\nimport { sha256Hex } from './sha256';\n\n/**\n * Heuristic generation of {@link bucketMessage}. Bump it whenever the\n * normalizer's rules change: changed heuristics re-partition history (they may\n * split one group into several or merge several into one), so a consumer that\n * persists fingerprints stores this alongside each hash to know which\n * generation produced it and when a recompute/backfill is due.\n */\nexport const FINGERPRINT_VERSION: number = 1;\n\n/**\n * Upper bound on the raw message length fed to the normalizer's regexes. A few\n * of them (the email and long-run patterns especially) can backtrack\n * super-linearly on a long delimiter-free run, and an error message can carry\n * attacker-influenced input of unbounded size — so clamp first to keep the\n * regex work bounded (a ReDoS guard). The final bucket is capped far below this\n * anyway, so the clamp is transparent for any real message.\n */\nconst MAX_INPUT_LENGTH = 1024;\n\n/** Cap on the normalized bucket so one runaway message can't bloat the key. */\nconst MAX_BUCKET_LENGTH = 160;\n\n/** Hex length of the truncated digest used as the grouping id. */\nconst HASH_LENGTH = 16;\n\n/** Namespaces the hash so a fingerprint can't collide with another content hash. */\nconst SCHEME = 'velajs.errors/fingerprint';\n\n/**\n * Ordered noise-stripping rules applied to a message before hashing. Each\n * replaces a class of per-occurrence identifier with a stable placeholder, so\n * two errors that differ only in their variable parts land in the same bucket.\n * Order matters: broader shapes (urls, timestamps) run before the greedy\n * numeric/id sweeps that would otherwise chew their digits.\n */\nconst NOISE_RULES: readonly (readonly [RegExp, string])[] = [\n  // Whole URLs (before path/number rules can nibble their insides).\n  [/https?:\\/\\/\\S+/gi, '[url]'],\n  // Email addresses.\n  [/\\b[\\w.+-]+@[\\w.-]+\\.[a-z]{2,}\\b/gi, '[email]'],\n  // RFC-4122 UUIDs.\n  [/\\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\\b/gi, '[uuid]'],\n  // ISO-8601-ish timestamps (before the ip/number rules touch their digits).\n  [/\\b\\d{4}-\\d{2}-\\d{2}[t ][\\d:.]+z?(?:[+-]\\d{2}:?\\d{2})?\\b/gi, '[time]'],\n  // IPv4 addresses with an optional port.\n  [/\\b(?:\\d{1,3}\\.){3}\\d{1,3}(?::\\d+)?\\b/g, '[ip]'],\n  // Unix-style request/filesystem paths at a token boundary — keeps in-word\n  // slashes (client/server, and/or) intact while folding a scanner's probed\n  // paths (/wp-admin, /.env, /.git/config) onto one placeholder.\n  [/(^|\\s)\\/\\S*/g, '$1[path]'],\n  // Windows drive-letter paths.\n  [/\\b[a-z]:\\\\[^\\s]*/gi, '[path]'],\n  // Hex literals (0x…).\n  [/\\b0x[0-9a-f]+\\b/gi, '[hex]'],\n  // Long opaque ids: tokens, hashes, base-ish ids. Threshold high enough to\n  // spare ordinary words while catching machine identifiers.\n  [/\\b[a-z0-9_]{20,}\\b/gi, '[id]'],\n  // Any remaining bare integer.\n  [/\\b\\d+\\b/g, '[num]'],\n];\n\n/**\n * Normalize an error message into its grouping bucket: strip per-occurrence\n * noise (urls, uuids, ips, request/filesystem paths, long ids, numbers) and\n * fold whitespace/case, so occurrences of the same logical error collapse to\n * one bucket. Exported for direct testing of the normalization heuristics.\n */\nexport const bucketMessage = (message: string): string => {\n  if (message.length === 0) {\n    return '';\n  }\n\n  let text = message.length > MAX_INPUT_LENGTH ? message.slice(0, MAX_INPUT_LENGTH) : message;\n\n  for (const [pattern, placeholder] of NOISE_RULES) {\n    text = text.replace(pattern, placeholder);\n  }\n\n  text = text.replace(/\\s+/g, ' ').trim().toLowerCase();\n\n  return text.length > MAX_BUCKET_LENGTH ? text.slice(0, MAX_BUCKET_LENGTH) : text;\n};\n\n/** Everything a fingerprint source can supply. */\nexport interface ErrorFingerprintInput {\n  /**\n   * What raised the error — the invoked function/route path, e.g.\n   * `messages:list`. Part of the grouping key.\n   */\n  functionPath: string;\n  /** Human-readable message (may embed user input); normalized into the key. */\n  message: string;\n  /**\n   * Machine error code, when known. Pure metadata: **never folded into the\n   * hash**, so the redacted wire error (which may rewrite or drop the code) and\n   * the raw server-side error still produce the same fingerprint.\n   */\n  code?: string;\n}\n\n/**\n * Fold an error into its stable 16-hex-character grouping fingerprint. Pure and\n * synchronous, safe to call per row when grouping a log page. The same\n * `functionPath` and logically-equal `message` always yield the same hash\n * regardless of the `code` supplied or per-occurrence noise in the message.\n */\nexport const fingerprintError = (input: ErrorFingerprintInput): string => {\n  const source = input.functionPath.length > 0 ? input.functionPath : 'unknown';\n  const canonical = `${SCHEME}\\n${source}\\n${bucketMessage(input.message)}`;\n  return sha256Hex(canonical).slice(0, HASH_LENGTH);\n};\n\nexport { sha256Hex } from './sha256';\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -1,11 +1,179 @@
-export { VelaError } from './error';
-export type { VelaErrorOptions } from './error';
-export { CORE_ENTRIES } from './catalog-data';
-export type { CoreErrorCode, ErrorCatalogEntry } from './catalog-data';
-export { CORE_CATALOG, STATUS_TO_CODE, composeCatalogs, defineErrorCatalog } from './catalog';
-export type { Catalog } from './catalog';
-export { isVelaError } from './guard';
-export type { VelaErrorLike } from './guard';
-export { toErrorBody } from './to-error-body';
-export type { ErrorBodyResult, ToErrorBodyOptions, WireErrorObject } from './to-error-body';
-export { invariant, unreachable } from './invariant';
+//#region src/catalog-data.d.ts
+interface ErrorCatalogEntry {
+  status: number;
+  title: string;
+  hint?: string;
+  docsUrl?: string;
+  /** Redaction posture: true → message/hint/data are never echoed to clients. */
+  internal?: boolean;
+}
+declare const CORE_ENTRIES: {
+  readonly bad_request: {
+    readonly status: 400;
+    readonly title: 'Bad Request';
+  };
+  readonly unauthorized: {
+    readonly status: 401;
+    readonly title: 'Unauthorized';
+  };
+  readonly forbidden: {
+    readonly status: 403;
+    readonly title: 'Forbidden';
+  };
+  readonly not_found: {
+    readonly status: 404;
+    readonly title: 'Not Found';
+  };
+  readonly method_not_allowed: {
+    readonly status: 405;
+    readonly title: 'Method Not Allowed';
+  };
+  readonly conflict: {
+    readonly status: 409;
+    readonly title: 'Conflict';
+  };
+  readonly gone: {
+    readonly status: 410;
+    readonly title: 'Gone';
+  };
+  readonly payload_too_large: {
+    readonly status: 413;
+    readonly title: 'Payload Too Large';
+  };
+  readonly unsupported_media_type: {
+    readonly status: 415;
+    readonly title: 'Unsupported Media Type';
+  };
+  readonly unprocessable: {
+    readonly status: 422;
+    readonly title: 'Unprocessable Entity';
+  };
+  readonly too_many_requests: {
+    readonly status: 429;
+    readonly title: 'Too Many Requests';
+  };
+  readonly internal: {
+    readonly status: 500;
+    readonly title: 'Internal Server Error';
+    readonly internal: true;
+  };
+  readonly not_implemented: {
+    readonly status: 501;
+    readonly title: 'Not Implemented';
+  };
+  readonly bad_gateway: {
+    readonly status: 502;
+    readonly title: 'Bad Gateway';
+  };
+  readonly service_unavailable: {
+    readonly status: 503;
+    readonly title: 'Service Unavailable';
+  };
+  readonly gateway_timeout: {
+    readonly status: 504;
+    readonly title: 'Gateway Timeout';
+  };
+};
+type CoreErrorCode = keyof typeof CORE_ENTRIES;
+//#endregion
+//#region src/error.d.ts
+interface VelaErrorOptions {
+  message?: string;
+  status?: number;
+  hint?: string;
+  docsUrl?: string;
+  data?: unknown;
+  cause?: unknown;
+}
+/**
+ * The one Vela error. Every field is an OWN ENUMERABLE property so the error
+ * rides any wire codec / structuredClone / DO-RPC prop-copy with no special
+ * serialization path. `type` is the brand `isVelaError` checks — it must
+ * survive serialization, which own+enumerable guarantees.
+ */
+declare class VelaError extends Error {
+  readonly type = "VelaError";
+  readonly code: string;
+  readonly status: number;
+  readonly hint?: string;
+  readonly docsUrl?: string;
+  readonly data?: unknown;
+  constructor(code: CoreErrorCode, options?: VelaErrorOptions);
+  constructor(code: string, options: VelaErrorOptions & {
+    status: number;
+  });
+}
+//#endregion
+//#region src/catalog.d.ts
+interface Catalog<C extends string = string> {
+  readonly entries: Readonly<Record<C, ErrorCatalogEntry>>;
+  /** Typed thrower bound to this catalog's defaults. */
+  error(code: C | (string & {}), options?: VelaErrorOptions): VelaError;
+  has(code: string): boolean;
+  get(code: string): ErrorCatalogEntry | undefined;
+}
+declare const defineErrorCatalog: <const T extends Record<string, ErrorCatalogEntry>>(entries: T) => Catalog<Extract<keyof T, string>>;
+declare const composeCatalogs: (...catalogs: Array<Catalog<string>>) => Catalog<string>;
+declare const CORE_CATALOG: Catalog<CoreErrorCode>;
+declare const STATUS_TO_CODE: Readonly<Record<number, CoreErrorCode>>;
+//#endregion
+//#region src/guard.d.ts
+/**
+ * Structural, realm-safe, BRANDED guard. `instanceof VelaError` is unreliable
+ * across DO↔worker RPC and for wire-decoded twins; a bare code+status shape
+ * check lets foreign driver errors ride the client-echo path. The brand
+ * (`type === 'VelaError'`, an own enumerable prop that survives serialization)
+ * closes both failure modes. Nothing load-bearing may use `instanceof`.
+ */
+interface VelaErrorLike extends Error {
+  type: 'VelaError';
+  code: string;
+  status: number;
+  hint?: string;
+  docsUrl?: string;
+  data?: unknown;
+}
+declare const isVelaError: (error: unknown) => error is VelaErrorLike;
+//#endregion
+//#region src/to-error-body.d.ts
+interface WireErrorObject {
+  code: string;
+  message: string;
+  hint?: string;
+  docsUrl?: string;
+  details?: unknown;
+}
+interface ErrorBodyResult {
+  body: {
+    error: WireErrorObject;
+  };
+  status: number;
+  redacted: boolean;
+}
+interface ToErrorBodyOptions {
+  /** Composed catalog; defaults to the core catalog. */
+  catalog?: Catalog<string>;
+  /** Status used for unbranded errors. Default 500. */
+  fallbackStatus?: number;
+  redactedMessage?: (status: number) => string;
+  /** Injectable wire codec for `data` → `details` (bigint/bytes etc.). */
+  encodeData?: (data: unknown) => unknown;
+  /** Default true. */
+  includeHint?: boolean;
+}
+/**
+ * THE single wire-redaction seam. Every transport edge (HTTP, WS, live, queue
+ * reporting) builds its client-bound error content here, so the invariant
+ * "unbranded or internal-coded errors never echo their message" holds
+ * identically everywhere. `redacted: true` is the caller's signal to log the
+ * raw error server-side — this function never logs (zero-dep purity).
+ */
+declare const toErrorBody: (error: unknown, options?: ToErrorBodyOptions) => ErrorBodyResult;
+//#endregion
+//#region src/invariant.d.ts
+/** Throws an internal-coded VelaError — rich in server logs, redacted on the wire. */
+declare function invariant(condition: unknown, message: string, data?: unknown): asserts condition;
+declare function unreachable(value: never, message?: string): never;
+//#endregion
+export { CORE_CATALOG, CORE_ENTRIES, type Catalog, type CoreErrorCode, type ErrorBodyResult, type ErrorCatalogEntry, STATUS_TO_CODE, type ToErrorBodyOptions, VelaError, type VelaErrorLike, type VelaErrorOptions, type WireErrorObject, composeCatalogs, defineErrorCatalog, invariant, isVelaError, toErrorBody, unreachable };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,6 +1,197 @@
-export { VelaError } from "./error.js";
-export { CORE_ENTRIES } from "./catalog-data.js";
-export { CORE_CATALOG, STATUS_TO_CODE, composeCatalogs, defineErrorCatalog } from "./catalog.js";
-export { isVelaError } from "./guard.js";
-export { toErrorBody } from "./to-error-body.js";
-export { invariant, unreachable } from "./invariant.js";
+//#region src/catalog-data.ts
+const CORE_ENTRIES = {
+	bad_request: {
+		status: 400,
+		title: "Bad Request"
+	},
+	unauthorized: {
+		status: 401,
+		title: "Unauthorized"
+	},
+	forbidden: {
+		status: 403,
+		title: "Forbidden"
+	},
+	not_found: {
+		status: 404,
+		title: "Not Found"
+	},
+	method_not_allowed: {
+		status: 405,
+		title: "Method Not Allowed"
+	},
+	conflict: {
+		status: 409,
+		title: "Conflict"
+	},
+	gone: {
+		status: 410,
+		title: "Gone"
+	},
+	payload_too_large: {
+		status: 413,
+		title: "Payload Too Large"
+	},
+	unsupported_media_type: {
+		status: 415,
+		title: "Unsupported Media Type"
+	},
+	unprocessable: {
+		status: 422,
+		title: "Unprocessable Entity"
+	},
+	too_many_requests: {
+		status: 429,
+		title: "Too Many Requests"
+	},
+	internal: {
+		status: 500,
+		title: "Internal Server Error",
+		internal: true
+	},
+	not_implemented: {
+		status: 501,
+		title: "Not Implemented"
+	},
+	bad_gateway: {
+		status: 502,
+		title: "Bad Gateway"
+	},
+	service_unavailable: {
+		status: 503,
+		title: "Service Unavailable"
+	},
+	gateway_timeout: {
+		status: 504,
+		title: "Gateway Timeout"
+	}
+};
+//#endregion
+//#region src/error.ts
+/**
+* The one Vela error. Every field is an OWN ENUMERABLE property so the error
+* rides any wire codec / structuredClone / DO-RPC prop-copy with no special
+* serialization path. `type` is the brand `isVelaError` checks — it must
+* survive serialization, which own+enumerable guarantees.
+*/
+var VelaError = class extends Error {
+	type = "VelaError";
+	code;
+	status;
+	hint;
+	docsUrl;
+	data;
+	constructor(code, options = {}) {
+		const entry = CORE_ENTRIES[code];
+		super(options.message ?? entry?.title ?? code, options.cause !== void 0 ? { cause: options.cause } : void 0);
+		this.name = "VelaError";
+		this.code = code;
+		this.status = options.status ?? entry?.status ?? 500;
+		const hint = options.hint ?? entry?.hint;
+		const docsUrl = options.docsUrl ?? entry?.docsUrl;
+		if (hint !== void 0) this.hint = hint;
+		if (docsUrl !== void 0) this.docsUrl = docsUrl;
+		if (options.data !== void 0) this.data = options.data;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+//#endregion
+//#region src/catalog.ts
+const makeCatalog = (entries) => ({
+	entries,
+	error(code, options = {}) {
+		const entry = entries[code];
+		const hint = options.hint ?? entry?.hint;
+		const docsUrl = options.docsUrl ?? entry?.docsUrl;
+		return new VelaError(code, {
+			...options,
+			status: options.status ?? entry?.status ?? 500,
+			...hint === void 0 ? {} : { hint },
+			...docsUrl === void 0 ? {} : { docsUrl }
+		});
+	},
+	has: (code) => Object.hasOwn(entries, code),
+	get: (code) => Object.hasOwn(entries, code) ? entries[code] : void 0
+});
+const defineErrorCatalog = (entries) => makeCatalog(entries);
+const composeCatalogs = (...catalogs) => {
+	const merged = {};
+	for (const catalog of catalogs) for (const [code, entry] of Object.entries(catalog.entries)) {
+		if (Object.hasOwn(merged, code)) throw new VelaError("internal", { message: `duplicate error code '${code}' while composing catalogs` });
+		merged[code] = entry;
+	}
+	return makeCatalog(merged);
+};
+const CORE_CATALOG = makeCatalog(CORE_ENTRIES);
+const STATUS_TO_CODE = Object.fromEntries(Object.entries(CORE_ENTRIES).map(([code, e]) => [e.status, code]));
+//#endregion
+//#region src/guard.ts
+const isVelaError = (error) => {
+	if (!(error instanceof Error)) return false;
+	const candidate = error;
+	return typeof candidate.code === "string" && typeof candidate.status === "number" && candidate.type === "VelaError";
+};
+//#endregion
+//#region src/to-error-body.ts
+const defaultRedactedMessage = (status, catalog) => {
+	const code = STATUS_TO_CODE[status];
+	return code && catalog.get(code)?.title || "Internal Server Error";
+};
+/**
+* THE single wire-redaction seam. Every transport edge (HTTP, WS, live, queue
+* reporting) builds its client-bound error content here, so the invariant
+* "unbranded or internal-coded errors never echo their message" holds
+* identically everywhere. `redacted: true` is the caller's signal to log the
+* raw error server-side — this function never logs (zero-dep purity).
+*/
+const toErrorBody = (error, options = {}) => {
+	const catalog = options.catalog ?? CORE_CATALOG;
+	const message = options.redactedMessage ?? ((s) => defaultRedactedMessage(s, catalog));
+	const redact = (status, code) => ({
+		body: { error: {
+			code,
+			message: message(status)
+		} },
+		status,
+		redacted: true
+	});
+	if (!isVelaError(error)) {
+		const status = options.fallbackStatus ?? 500;
+		return redact(status, STATUS_TO_CODE[status] ?? "internal");
+	}
+	const entry = catalog.get(error.code);
+	if (error.code === "internal" || entry?.internal === true) return redact(error.status, error.code);
+	const wire = {
+		code: error.code,
+		message: error.message
+	};
+	const hint = error.hint ?? entry?.hint;
+	if (options.includeHint !== false && hint !== void 0) wire.hint = hint;
+	const docsUrl = error.docsUrl ?? entry?.docsUrl;
+	if (docsUrl !== void 0) wire.docsUrl = docsUrl;
+	if (error.data !== void 0) wire.details = options.encodeData ? options.encodeData(error.data) : error.data;
+	return {
+		body: { error: wire },
+		status: error.status,
+		redacted: false
+	};
+};
+//#endregion
+//#region src/invariant.ts
+/** Throws an internal-coded VelaError — rich in server logs, redacted on the wire. */
+function invariant(condition, message, data) {
+	if (!condition) throw new VelaError("internal", {
+		message: `Invariant violation: ${message}`,
+		data
+	});
+}
+function unreachable(value, message = "unreachable code reached") {
+	throw new VelaError("internal", {
+		message,
+		data: { value }
+	});
+}
+//#endregion
+export { CORE_CATALOG, CORE_ENTRIES, STATUS_TO_CODE, VelaError, composeCatalogs, defineErrorCatalog, invariant, isVelaError, toErrorBody, unreachable };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/catalog-data.ts","../src/error.ts","../src/catalog.ts","../src/guard.ts","../src/to-error-body.ts","../src/invariant.ts"],"sourcesContent":["export interface ErrorCatalogEntry {\n  status: number;\n  title: string;\n  hint?: string;\n  docsUrl?: string;\n  /** Redaction posture: true → message/hint/data are never echoed to clients. */\n  internal?: boolean;\n}\n\nexport const CORE_ENTRIES = {\n  bad_request: { status: 400, title: 'Bad Request' },\n  unauthorized: { status: 401, title: 'Unauthorized' },\n  forbidden: { status: 403, title: 'Forbidden' },\n  not_found: { status: 404, title: 'Not Found' },\n  method_not_allowed: { status: 405, title: 'Method Not Allowed' },\n  conflict: { status: 409, title: 'Conflict' },\n  gone: { status: 410, title: 'Gone' },\n  payload_too_large: { status: 413, title: 'Payload Too Large' },\n  unsupported_media_type: { status: 415, title: 'Unsupported Media Type' },\n  unprocessable: { status: 422, title: 'Unprocessable Entity' },\n  too_many_requests: { status: 429, title: 'Too Many Requests' },\n  internal: { status: 500, title: 'Internal Server Error', internal: true },\n  not_implemented: { status: 501, title: 'Not Implemented' },\n  bad_gateway: { status: 502, title: 'Bad Gateway' },\n  service_unavailable: { status: 503, title: 'Service Unavailable' },\n  gateway_timeout: { status: 504, title: 'Gateway Timeout' },\n} as const satisfies Record<string, ErrorCatalogEntry>;\n\nexport type CoreErrorCode = keyof typeof CORE_ENTRIES;\n","import { CORE_ENTRIES, type CoreErrorCode } from './catalog-data';\n\nexport interface VelaErrorOptions {\n  message?: string;\n  status?: number;\n  hint?: string;\n  docsUrl?: string;\n  data?: unknown;\n  cause?: unknown;\n}\n\n/**\n * The one Vela error. Every field is an OWN ENUMERABLE property so the error\n * rides any wire codec / structuredClone / DO-RPC prop-copy with no special\n * serialization path. `type` is the brand `isVelaError` checks — it must\n * survive serialization, which own+enumerable guarantees.\n */\nexport class VelaError extends Error {\n  readonly type = 'VelaError';\n  readonly code: string;\n  readonly status: number;\n  readonly hint?: string;\n  readonly docsUrl?: string;\n  readonly data?: unknown;\n\n  constructor(code: CoreErrorCode, options?: VelaErrorOptions);\n  constructor(code: string, options: VelaErrorOptions & { status: number });\n  constructor(code: string, options: VelaErrorOptions = {}) {\n    const entry = (\n      CORE_ENTRIES as Record<\n        string,\n        { status: number; title: string; hint?: string; docsUrl?: string }\n      >\n    )[code];\n    super(\n      options.message ?? entry?.title ?? code,\n      options.cause !== undefined ? { cause: options.cause } : undefined,\n    );\n    this.name = 'VelaError';\n    this.code = code;\n    this.status = options.status ?? entry?.status ?? 500;\n    const hint = options.hint ?? entry?.hint;\n    const docsUrl = options.docsUrl ?? entry?.docsUrl;\n    if (hint !== undefined) this.hint = hint;\n    if (docsUrl !== undefined) this.docsUrl = docsUrl;\n    if (options.data !== undefined) this.data = options.data;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n","import { CORE_ENTRIES, type CoreErrorCode, type ErrorCatalogEntry } from './catalog-data';\nimport { VelaError, type VelaErrorOptions } from './error';\n\nexport type { CoreErrorCode, ErrorCatalogEntry } from './catalog-data';\nexport { CORE_ENTRIES } from './catalog-data';\n\nexport interface Catalog<C extends string = string> {\n  readonly entries: Readonly<Record<C, ErrorCatalogEntry>>;\n  /** Typed thrower bound to this catalog's defaults. */\n  error(code: C | (string & {}), options?: VelaErrorOptions): VelaError;\n  has(code: string): boolean;\n  get(code: string): ErrorCatalogEntry | undefined;\n}\n\nconst makeCatalog = <C extends string>(\n  entries: Readonly<Record<C, ErrorCatalogEntry>>,\n): Catalog<C> => ({\n  entries,\n  error(code, options = {}) {\n    const entry = (entries as Record<string, ErrorCatalogEntry>)[code];\n    const hint = options.hint ?? entry?.hint;\n    const docsUrl = options.docsUrl ?? entry?.docsUrl;\n    return new VelaError(code, {\n      ...options,\n      status: options.status ?? entry?.status ?? 500,\n      ...(hint === undefined ? {} : { hint }),\n      ...(docsUrl === undefined ? {} : { docsUrl }),\n    });\n  },\n  has: (code) => Object.hasOwn(entries, code),\n  get: (code) =>\n    Object.hasOwn(entries, code) ? (entries as Record<string, ErrorCatalogEntry>)[code] : undefined,\n});\n\nexport const defineErrorCatalog = <const T extends Record<string, ErrorCatalogEntry>>(\n  entries: T,\n): Catalog<Extract<keyof T, string>> => makeCatalog(entries);\n\nexport const composeCatalogs = (...catalogs: Array<Catalog<string>>): Catalog<string> => {\n  const merged: Record<string, ErrorCatalogEntry> = {};\n  for (const catalog of catalogs) {\n    for (const [code, entry] of Object.entries<ErrorCatalogEntry>(catalog.entries)) {\n      if (Object.hasOwn(merged, code)) {\n        throw new VelaError('internal', {\n          message: `duplicate error code '${code}' while composing catalogs`,\n        });\n      }\n      merged[code] = entry;\n    }\n  }\n  return makeCatalog(merged);\n};\n\nexport const CORE_CATALOG: Catalog<CoreErrorCode> = makeCatalog(CORE_ENTRIES);\n\nexport const STATUS_TO_CODE: Readonly<Record<number, CoreErrorCode>> = Object.fromEntries(\n  (Object.entries(CORE_ENTRIES) as Array<[CoreErrorCode, ErrorCatalogEntry]>).map(([code, e]) => [\n    e.status,\n    code,\n  ]),\n) as Record<number, CoreErrorCode>;\n","/**\n * Structural, realm-safe, BRANDED guard. `instanceof VelaError` is unreliable\n * across DO↔worker RPC and for wire-decoded twins; a bare code+status shape\n * check lets foreign driver errors ride the client-echo path. The brand\n * (`type === 'VelaError'`, an own enumerable prop that survives serialization)\n * closes both failure modes. Nothing load-bearing may use `instanceof`.\n */\nexport interface VelaErrorLike extends Error {\n  type: 'VelaError';\n  code: string;\n  status: number;\n  hint?: string;\n  docsUrl?: string;\n  data?: unknown;\n}\n\nexport const isVelaError = (error: unknown): error is VelaErrorLike => {\n  if (!(error instanceof Error)) return false;\n  const candidate = error as Partial<VelaErrorLike>;\n  return (\n    typeof candidate.code === 'string' &&\n    typeof candidate.status === 'number' &&\n    candidate.type === 'VelaError'\n  );\n};\n","import { CORE_CATALOG, STATUS_TO_CODE, type Catalog } from './catalog';\nimport { isVelaError } from './guard';\n\nexport interface WireErrorObject {\n  code: string;\n  message: string;\n  hint?: string;\n  docsUrl?: string;\n  details?: unknown;\n}\n\nexport interface ErrorBodyResult {\n  body: { error: WireErrorObject };\n  status: number;\n  redacted: boolean;\n}\n\nexport interface ToErrorBodyOptions {\n  /** Composed catalog; defaults to the core catalog. */\n  catalog?: Catalog<string>;\n  /** Status used for unbranded errors. Default 500. */\n  fallbackStatus?: number;\n  redactedMessage?: (status: number) => string;\n  /** Injectable wire codec for `data` → `details` (bigint/bytes etc.). */\n  encodeData?: (data: unknown) => unknown;\n  /** Default true. */\n  includeHint?: boolean;\n}\n\nconst defaultRedactedMessage = (status: number, catalog: Catalog<string>): string => {\n  const code = STATUS_TO_CODE[status];\n  return (code && catalog.get(code)?.title) || 'Internal Server Error';\n};\n\n/**\n * THE single wire-redaction seam. Every transport edge (HTTP, WS, live, queue\n * reporting) builds its client-bound error content here, so the invariant\n * \"unbranded or internal-coded errors never echo their message\" holds\n * identically everywhere. `redacted: true` is the caller's signal to log the\n * raw error server-side — this function never logs (zero-dep purity).\n */\nexport const toErrorBody = (error: unknown, options: ToErrorBodyOptions = {}): ErrorBodyResult => {\n  const catalog = options.catalog ?? CORE_CATALOG;\n  const message = options.redactedMessage ?? ((s: number) => defaultRedactedMessage(s, catalog));\n\n  const redact = (status: number, code: string): ErrorBodyResult => ({\n    body: { error: { code, message: message(status) } },\n    status,\n    redacted: true,\n  });\n\n  if (!isVelaError(error)) {\n    const status = options.fallbackStatus ?? 500;\n    return redact(status, STATUS_TO_CODE[status] ?? 'internal');\n  }\n\n  const entry = catalog.get(error.code);\n  if (error.code === 'internal' || entry?.internal === true) {\n    return redact(error.status, error.code);\n  }\n\n  const wire: WireErrorObject = { code: error.code, message: error.message };\n  const hint = error.hint ?? entry?.hint;\n  if (options.includeHint !== false && hint !== undefined) wire.hint = hint;\n  const docsUrl = error.docsUrl ?? entry?.docsUrl;\n  if (docsUrl !== undefined) wire.docsUrl = docsUrl;\n  if (error.data !== undefined)\n    wire.details = options.encodeData ? options.encodeData(error.data) : error.data;\n  return { body: { error: wire }, status: error.status, redacted: false };\n};\n","import { VelaError } from './error';\n\n/** Throws an internal-coded VelaError — rich in server logs, redacted on the wire. */\nexport function invariant(condition: unknown, message: string, data?: unknown): asserts condition {\n  if (!condition) {\n    throw new VelaError('internal', { message: `Invariant violation: ${message}`, data });\n  }\n}\n\nexport function unreachable(value: never, message = 'unreachable code reached'): never {\n  throw new VelaError('internal', { message, data: { value } });\n}\n"],"mappings":"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"}

package/package.json

@@ -1,53 +1,69 @@
 {
   "name": "@velajs/errors",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Unified error layer for Vela: branded VelaError, composable error catalogs, and the single toErrorBody wire-redaction seam",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "sideEffects": false,
   "keywords": [
-    "vela",
-    "errors",
     "error-catalog",
+    "errors",
+    "framework",
     "redaction",
-    "framework"
+    "vela"
   ],
-  "author": "ksh",
+  "homepage": "https://github.com/velajs/errors#readme",
+  "bugs": {
+    "url": "https://github.com/velajs/errors/issues"
+  },
   "license": "MIT",
+  "author": "ksh",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/velajs/errors.git"
   },
-  "homepage": "https://github.com/velajs/errors#readme",
-  "bugs": {
-    "url": "https://github.com/velajs/errors/issues"
-  },
-  "engines": {
-    "node": ">=20"
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./fingerprint": {
+      "types": "./dist/fingerprint.d.ts",
+      "import": "./dist/fingerprint.js"
+    }
   },
   "devDependencies": {
-    "@swc/cli": "^0.8.1",
-    "@swc/core": "^1.15.43",
-    "typescript": "^6.0.3",
-    "unplugin-swc": "^1.5.9",
-    "vitest": "^4.1.9"
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@changesets/cli": "^2.31.0",
+    "oxfmt": "^0.58.0",
+    "oxlint": "^1.73.0",
+    "publint": "^0.3.21",
+    "tsdown": "^0.22.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=24"
   },
   "scripts": {
-    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
+    "build": "tsdown",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit -p tsconfig.test.json"
+    "typecheck": "tsc --noEmit -p tsconfig.test.json",
+    "lint": "oxlint .",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "publint": "publint",
+    "attw": "attw --pack . --profile esm-only",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm build && changeset publish",
+    "verify": "pnpm lint && pnpm format:check && pnpm build && pnpm typecheck && pnpm test && pnpm publint && pnpm attw"
   }
 }

package/dist/catalog-data.d.ts

@@ -1,76 +0,0 @@
-export interface ErrorCatalogEntry {
-    status: number;
-    title: string;
-    hint?: string;
-    docsUrl?: string;
-    /** Redaction posture: true → message/hint/data are never echoed to clients. */
-    internal?: boolean;
-}
-export declare const CORE_ENTRIES: {
-    readonly bad_request: {
-        readonly status: 400;
-        readonly title: "Bad Request";
-    };
-    readonly unauthorized: {
-        readonly status: 401;
-        readonly title: "Unauthorized";
-    };
-    readonly forbidden: {
-        readonly status: 403;
-        readonly title: "Forbidden";
-    };
-    readonly not_found: {
-        readonly status: 404;
-        readonly title: "Not Found";
-    };
-    readonly method_not_allowed: {
-        readonly status: 405;
-        readonly title: "Method Not Allowed";
-    };
-    readonly conflict: {
-        readonly status: 409;
-        readonly title: "Conflict";
-    };
-    readonly gone: {
-        readonly status: 410;
-        readonly title: "Gone";
-    };
-    readonly payload_too_large: {
-        readonly status: 413;
-        readonly title: "Payload Too Large";
-    };
-    readonly unsupported_media_type: {
-        readonly status: 415;
-        readonly title: "Unsupported Media Type";
-    };
-    readonly unprocessable: {
-        readonly status: 422;
-        readonly title: "Unprocessable Entity";
-    };
-    readonly too_many_requests: {
-        readonly status: 429;
-        readonly title: "Too Many Requests";
-    };
-    readonly internal: {
-        readonly status: 500;
-        readonly title: "Internal Server Error";
-        readonly internal: true;
-    };
-    readonly not_implemented: {
-        readonly status: 501;
-        readonly title: "Not Implemented";
-    };
-    readonly bad_gateway: {
-        readonly status: 502;
-        readonly title: "Bad Gateway";
-    };
-    readonly service_unavailable: {
-        readonly status: 503;
-        readonly title: "Service Unavailable";
-    };
-    readonly gateway_timeout: {
-        readonly status: 504;
-        readonly title: "Gateway Timeout";
-    };
-};
-export type CoreErrorCode = keyof typeof CORE_ENTRIES;

package/dist/catalog-data.js

@@ -1,67 +0,0 @@
-export const CORE_ENTRIES = {
-    bad_request: {
-        status: 400,
-        title: 'Bad Request'
-    },
-    unauthorized: {
-        status: 401,
-        title: 'Unauthorized'
-    },
-    forbidden: {
-        status: 403,
-        title: 'Forbidden'
-    },
-    not_found: {
-        status: 404,
-        title: 'Not Found'
-    },
-    method_not_allowed: {
-        status: 405,
-        title: 'Method Not Allowed'
-    },
-    conflict: {
-        status: 409,
-        title: 'Conflict'
-    },
-    gone: {
-        status: 410,
-        title: 'Gone'
-    },
-    payload_too_large: {
-        status: 413,
-        title: 'Payload Too Large'
-    },
-    unsupported_media_type: {
-        status: 415,
-        title: 'Unsupported Media Type'
-    },
-    unprocessable: {
-        status: 422,
-        title: 'Unprocessable Entity'
-    },
-    too_many_requests: {
-        status: 429,
-        title: 'Too Many Requests'
-    },
-    internal: {
-        status: 500,
-        title: 'Internal Server Error',
-        internal: true
-    },
-    not_implemented: {
-        status: 501,
-        title: 'Not Implemented'
-    },
-    bad_gateway: {
-        status: 502,
-        title: 'Bad Gateway'
-    },
-    service_unavailable: {
-        status: 503,
-        title: 'Service Unavailable'
-    },
-    gateway_timeout: {
-        status: 504,
-        title: 'Gateway Timeout'
-    }
-};

package/dist/catalog.d.ts

@@ -1,15 +0,0 @@
-import { type CoreErrorCode, type ErrorCatalogEntry } from './catalog-data';
-import { VelaError, type VelaErrorOptions } from './error';
-export type { CoreErrorCode, ErrorCatalogEntry } from './catalog-data';
-export { CORE_ENTRIES } from './catalog-data';
-export interface Catalog<C extends string = string> {
-    readonly entries: Readonly<Record<C, ErrorCatalogEntry>>;
-    /** Typed thrower bound to this catalog's defaults. */
-    error(code: C | (string & {}), options?: VelaErrorOptions): VelaError;
-    has(code: string): boolean;
-    get(code: string): ErrorCatalogEntry | undefined;
-}
-export declare const defineErrorCatalog: <const T extends Record<string, ErrorCatalogEntry>>(entries: T) => Catalog<Extract<keyof T, string>>;
-export declare const composeCatalogs: (...catalogs: Array<Catalog<string>>) => Catalog<string>;
-export declare const CORE_CATALOG: Catalog<CoreErrorCode>;
-export declare const STATUS_TO_CODE: Readonly<Record<number, CoreErrorCode>>;

package/dist/catalog.js

@@ -1,37 +0,0 @@
-import { CORE_ENTRIES } from "./catalog-data.js";
-import { VelaError } from "./error.js";
-export { CORE_ENTRIES } from "./catalog-data.js";
-const makeCatalog = (entries)=>({
-        entries,
-        error (code, options = {}) {
-            const entry = entries[code];
-            return new VelaError(code, {
-                ...options,
-                status: options.status ?? entry?.status ?? 500,
-                hint: options.hint ?? entry?.hint,
-                docsUrl: options.docsUrl ?? entry?.docsUrl
-            });
-        },
-        has: (code)=>Object.hasOwn(entries, code),
-        get: (code)=>Object.hasOwn(entries, code) ? entries[code] : undefined
-    });
-export const defineErrorCatalog = (entries)=>makeCatalog(entries);
-export const composeCatalogs = (...catalogs)=>{
-    const merged = {};
-    for (const catalog of catalogs){
-        for (const [code, entry] of Object.entries(catalog.entries)){
-            if (Object.hasOwn(merged, code)) {
-                throw new VelaError('internal', {
-                    message: `duplicate error code '${code}' while composing catalogs`
-                });
-            }
-            merged[code] = entry;
-        }
-    }
-    return makeCatalog(merged);
-};
-export const CORE_CATALOG = makeCatalog(CORE_ENTRIES);
-export const STATUS_TO_CODE = Object.fromEntries(Object.entries(CORE_ENTRIES).map(([code, e])=>[
-        e.status,
-        code
-    ]));

package/dist/error.d.ts

@@ -1,27 +0,0 @@
-import { type CoreErrorCode } from './catalog-data';
-export interface VelaErrorOptions {
-    message?: string;
-    status?: number;
-    hint?: string;
-    docsUrl?: string;
-    data?: unknown;
-    cause?: unknown;
-}
-/**
- * The one Vela error. Every field is an OWN ENUMERABLE property so the error
- * rides any wire codec / structuredClone / DO-RPC prop-copy with no special
- * serialization path. `type` is the brand `isVelaError` checks — it must
- * survive serialization, which own+enumerable guarantees.
- */
-export declare class VelaError extends Error {
-    readonly type = "VelaError";
-    readonly code: string;
-    readonly status: number;
-    readonly hint?: string;
-    readonly docsUrl?: string;
-    readonly data?: unknown;
-    constructor(code: CoreErrorCode, options?: VelaErrorOptions);
-    constructor(code: string, options: VelaErrorOptions & {
-        status: number;
-    });
-}

package/dist/error.js

@@ -1,27 +0,0 @@
-import { CORE_ENTRIES } from "./catalog-data.js";
-/**
- * The one Vela error. Every field is an OWN ENUMERABLE property so the error
- * rides any wire codec / structuredClone / DO-RPC prop-copy with no special
- * serialization path. `type` is the brand `isVelaError` checks — it must
- * survive serialization, which own+enumerable guarantees.
- */ export class VelaError extends Error {
-    type = 'VelaError';
-    code;
-    status;
-    hint;
-    docsUrl;
-    data;
-    constructor(code, options = {}){
-        const entry = CORE_ENTRIES[code];
-        super(options.message ?? entry?.title ?? code, options.cause !== undefined ? {
-            cause: options.cause
-        } : undefined);
-        this.name = 'VelaError';
-        this.code = code;
-        this.status = options.status ?? entry?.status ?? 500;
-        if (options.hint ?? entry?.hint) this.hint = options.hint ?? entry?.hint;
-        if (options.docsUrl ?? entry?.docsUrl) this.docsUrl = options.docsUrl ?? entry?.docsUrl;
-        if (options.data !== undefined) this.data = options.data;
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}

package/dist/guard.d.ts

@@ -1,16 +0,0 @@
-/**
- * Structural, realm-safe, BRANDED guard. `instanceof VelaError` is unreliable
- * across DO↔worker RPC and for wire-decoded twins; a bare code+status shape
- * check lets foreign driver errors ride the client-echo path. The brand
- * (`type === 'VelaError'`, an own enumerable prop that survives serialization)
- * closes both failure modes. Nothing load-bearing may use `instanceof`.
- */
-export interface VelaErrorLike extends Error {
-    type: 'VelaError';
-    code: string;
-    status: number;
-    hint?: string;
-    docsUrl?: string;
-    data?: unknown;
-}
-export declare const isVelaError: (error: unknown) => error is VelaErrorLike;

package/dist/guard.js

@@ -1,11 +0,0 @@
-/**
- * Structural, realm-safe, BRANDED guard. `instanceof VelaError` is unreliable
- * across DO↔worker RPC and for wire-decoded twins; a bare code+status shape
- * check lets foreign driver errors ride the client-echo path. The brand
- * (`type === 'VelaError'`, an own enumerable prop that survives serialization)
- * closes both failure modes. Nothing load-bearing may use `instanceof`.
- */ export const isVelaError = (error)=>{
-    if (!(error instanceof Error)) return false;
-    const candidate = error;
-    return typeof candidate.code === 'string' && typeof candidate.status === 'number' && candidate.type === 'VelaError';
-};

package/dist/invariant.d.ts

@@ -1,3 +0,0 @@
-/** Throws an internal-coded VelaError — rich in server logs, redacted on the wire. */
-export declare function invariant(condition: unknown, message: string, data?: unknown): asserts condition;
-export declare function unreachable(value: never, message?: string): never;

package/dist/invariant.js

@@ -1,17 +0,0 @@
-import { VelaError } from "./error.js";
-/** Throws an internal-coded VelaError — rich in server logs, redacted on the wire. */ export function invariant(condition, message, data) {
-    if (!condition) {
-        throw new VelaError('internal', {
-            message: `Invariant violation: ${message}`,
-            data
-        });
-    }
-}
-export function unreachable(value, message = 'unreachable code reached') {
-    throw new VelaError('internal', {
-        message,
-        data: {
-            value
-        }
-    });
-}

package/dist/to-error-body.d.ts

@@ -1,34 +0,0 @@
-import { type Catalog } from './catalog';
-export interface WireErrorObject {
-    code: string;
-    message: string;
-    hint?: string;
-    docsUrl?: string;
-    details?: unknown;
-}
-export interface ErrorBodyResult {
-    body: {
-        error: WireErrorObject;
-    };
-    status: number;
-    redacted: boolean;
-}
-export interface ToErrorBodyOptions {
-    /** Composed catalog; defaults to the core catalog. */
-    catalog?: Catalog<string>;
-    /** Status used for unbranded errors. Default 500. */
-    fallbackStatus?: number;
-    redactedMessage?: (status: number) => string;
-    /** Injectable wire codec for `data` → `details` (bigint/bytes etc.). */
-    encodeData?: (data: unknown) => unknown;
-    /** Default true. */
-    includeHint?: boolean;
-}
-/**
- * THE single wire-redaction seam. Every transport edge (HTTP, WS, live, queue
- * reporting) builds its client-bound error content here, so the invariant
- * "unbranded or internal-coded errors never echo their message" holds
- * identically everywhere. `redacted: true` is the caller's signal to log the
- * raw error server-side — this function never logs (zero-dep purity).
- */
-export declare const toErrorBody: (error: unknown, options?: ToErrorBodyOptions) => ErrorBodyResult;

package/dist/to-error-body.js

@@ -1,50 +0,0 @@
-import { CORE_CATALOG, STATUS_TO_CODE } from "./catalog.js";
-import { isVelaError } from "./guard.js";
-const defaultRedactedMessage = (status, catalog)=>{
-    const code = STATUS_TO_CODE[status];
-    return code && catalog.get(code)?.title || 'Internal Server Error';
-};
-/**
- * THE single wire-redaction seam. Every transport edge (HTTP, WS, live, queue
- * reporting) builds its client-bound error content here, so the invariant
- * "unbranded or internal-coded errors never echo their message" holds
- * identically everywhere. `redacted: true` is the caller's signal to log the
- * raw error server-side — this function never logs (zero-dep purity).
- */ export const toErrorBody = (error, options = {})=>{
-    const catalog = options.catalog ?? CORE_CATALOG;
-    const message = options.redactedMessage ?? ((s)=>defaultRedactedMessage(s, catalog));
-    const redact = (status, code)=>({
-            body: {
-                error: {
-                    code,
-                    message: message(status)
-                }
-            },
-            status,
-            redacted: true
-        });
-    if (!isVelaError(error)) {
-        const status = options.fallbackStatus ?? 500;
-        return redact(status, STATUS_TO_CODE[status] ?? 'internal');
-    }
-    const entry = catalog.get(error.code);
-    if (error.code === 'internal' || entry?.internal === true) {
-        return redact(error.status, error.code);
-    }
-    const wire = {
-        code: error.code,
-        message: error.message
-    };
-    const hint = error.hint ?? entry?.hint;
-    if (options.includeHint !== false && hint !== undefined) wire.hint = hint;
-    const docsUrl = error.docsUrl ?? entry?.docsUrl;
-    if (docsUrl !== undefined) wire.docsUrl = docsUrl;
-    if (error.data !== undefined) wire.details = options.encodeData ? options.encodeData(error.data) : error.data;
-    return {
-        body: {
-            error: wire
-        },
-        status: error.status,
-        redacted: false
-    };
-};