@owlmeans/error 0.1.18-rc.3 → 0.1.18-rc.31

package/README.md

@@ -1,78 +1,267 @@
 # @owlmeans/error
 
-Serializable error base class with type registration for cross-process error propagation.
-
-## Overview
-
-- `ResilientError` base class survives JSON serialization/deserialization across service boundaries
-- Error class registry ensures custom error types are correctly reconstructed after transport
-- Helpers for marshaling errors to strings and back
+Serializable error base class with a type registry, so a typed error thrown in one process is
+caught as the same class in another. An app uses it for every error that has to cross a service
+boundary (HTTP, socket, queue) or reach a UI as a translated message: declare a `ResilientError`
+subclass, register it in the shared module both sides import, and normalize whatever you catch
+with `ResilientError.ensure`. It is not for wiring faults — an unknown alias or a missing service
+is a `SyntaxError` that must crash the process. Before declaring a new family, reuse the ones
+framework packages already ship: authentication and authorization failures from
+[`@owlmeans/auth`](../auth), storage failures from [`@owlmeans/resource`](../resource).
 
 ## Installation
 
 ```bash
-bun add @owlmeans/error
+bun add @owlmeans/error@^0.1.18-rc.30
 ```
 
+## Concepts
+
+- **Resilient error** — a `ResilientError` carries a `type` (the class's static `typeName`) next to
+  its `message`; the pair identifies the failure anywhere it travels.
+- **Error family** — a base subclass that prefixes every message (`invoice:`) and subclasses that
+  add their own prefix and re-stamp `type`, so the final message reads `invoice:not-found:<id>`.
+- **Registry** — `ResilientError.converters`, filled by `registerErrorClass`; only a registered
+  class comes back as itself after transport.
+- **Marshalling** — `marshal` flattens `type`, `message` and the original stack into one plain
+  `Error` whose message is joined by `SEPARATOR` (`|||`); `ensure` recognises that prefix and
+  rebuilds the registered class.
+- **Errors namespace** — importing the package registers the `errors` i18n library; UIs resolve a
+  message by the error's `type`, never by the thrown string.
+
 ## Usage
 
-Define and register a custom error type:
+### Declare and register an error family
 
-```typescript
+Keep errors in the shared (`common`) module that both the server and the client import, and
+register every class at module load.
+
+```ts
 import { ResilientError } from '@owlmeans/error'
 
-export class ProjectResourceError extends ResilientError {
-  static typeName = 'viable-project:error'
+export class InvoiceError extends ResilientError {
+  public static override typeName = 'MyAppInvoiceError'
+
+  constructor(message: string = 'error') {
+    super(InvoiceError.typeName, `invoice:${message}`)
+  }
+}
+
+export class InvoiceNotFound extends InvoiceError {
+  public static override typeName = `NotFound${InvoiceError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`not-found:${message}`)
+    this.type = InvoiceNotFound.typeName
+  }
+}
+
+export class InvoiceLocked extends InvoiceError {
+  public static override typeName = `Locked${InvoiceError.typeName}`
 
   constructor(message: string = 'error') {
-    super(`viable-project:${message}`)
-    this.type = ProjectResourceError.typeName
+    super(`locked:${message}`)
+    this.type = InvoiceLocked.typeName
   }
 }
 
-ResilientError.registerErrorClass(ProjectResourceError)
+ResilientError.registerErrorClass(InvoiceError)
+ResilientError.registerErrorClass(InvoiceNotFound)
+ResilientError.registerErrorClass(InvoiceLocked)
+
+throw new InvoiceNotFound('inv-42') // message: 'invoice:not-found:inv-42'
 ```
 
-Marshal errors across service boundaries:
+A subclass of a subclass calls `super` with the message alone — the parent adds its own prefix and
+`type`, so the subclass re-stamps `this.type` afterwards.
+
+### Normalize what you caught
 
-```typescript
-import { marshalError, ResilientError } from '@owlmeans/error'
+`ensure` accepts an `Error` or a string and always returns a `ResilientError`, so a handler can
+branch on the registered classes it knows and fall through for the rest.
 
-// Server side: serialize for transport
-const serialized = marshalError(caughtError)
+```ts
+import { ResilientError } from '@owlmeans/error'
+import { InvoiceLocked, InvoiceNotFound } from '@my-app/common'
 
-// Client side: reconstruct the typed error
-const restored = ResilientError.ensure(receivedError)
+export const settle = async (invoiceId: string) => {
+  try {
+    await payInvoice(invoiceId)
+  } catch (e) {
+    const err = ResilientError.ensure(e as Error)
+    if (err instanceof InvoiceNotFound || err instanceof InvoiceLocked) {
+      return { settled: false, reason: err.type }
+    }
+    throw err
+  }
+}
 ```
 
-## API
+A small helper keeps catch blocks typed when the caught value is `unknown`:
+
+```ts
+import { ResilientError } from '@owlmeans/error'
+
+export const asError = <T extends ResilientError>(err: unknown): T =>
+  typeof err === 'string' || err instanceof Error
+    ? ResilientError.ensure(err) as T
+    : ResilientError.ensure(`Unknown error ${String(err)}`) as T
+```
+
+### Cross a service boundary
+
+The HTTP transports already do this: `@owlmeans/server-api` answers a thrown error with
+`ResilientError.marshal(ResilientError.ensure(error)).message` as the body, and `@owlmeans/api`
+turns a string body back into the registered class with `ResilientError.ensure`. So a backend throw
+is caught as the same class around `context.entrypoint(invoiceProtocols.settle).call(...)` in the
+client. A boundary you own — a WebSocket close reason, a stored failure record — does the same by hand:
+
+```ts
+import { enuserError, marshalError } from '@owlmeans/error'
+import { InvoiceError } from '@my-app/common'
+
+// Producer: send only the flattened string.
+socket.close(1011, marshalError(caught).message)
+
+// Consumer: rebuild the registered class, typed to the family you expect.
+socket.addEventListener('close', event => {
+  const err = enuserError<InvoiceError>(event.reason)
+  if (err instanceof InvoiceError) {
+    showInvoiceProblem(err.type)
+  }
+})
+```
+
+The round trip is worth a test for any error whose identity the far side depends on:
+
+```ts
+import { expect, test } from 'bun:test'
+import { ResilientError } from '@owlmeans/error'
+import { InvoiceNotFound } from '@my-app/common'
+
+test('an invoice miss survives the hop as its own class', () => {
+  const restored = ResilientError.ensure(
+    ResilientError.marshal(new InvoiceNotFound('inv-42')).message
+  )
 
-### `ResilientError`
+  expect(restored).toBeInstanceOf(InvoiceNotFound)
+  expect(restored.message).toBe('invoice:not-found:inv-42')
+})
+```
 
-Base class for all OwlMeans errors.
+### Rebuild state after unmarshalling
 
-- `static typeName: string` — override in subclasses to identify the error type
-- `static registerErrorClass(cls)` — register a subclass for automatic reconstruction from JSON
-- `static ensure(err, throwOnUnknown?)` — convert any error to `ResilientError`
-- `static marshal(err)` — serialize an error to a transportable `Error` object
-- `type: string` — error type identifier set in the constructor
+Only `type`, `message` and the stack travel. A subclass that exposes structured data derives it
+from the message in `finalizeUnmarshal()`, which runs after the message is restored.
 
-### `marshalError(err): Error`
+```ts
+import { ResilientError } from '@owlmeans/error'
 
-Convenience: ensures the error is a `ResilientError`, then marshals it.
+export class QuotaExceeded extends ResilientError {
+  public static override typeName = 'MyAppQuotaExceeded'
+
+  public limit?: number
+
+  constructor(message: string = 'error') {
+    super(QuotaExceeded.typeName, `quota:${message}`)
+    this.finalizeUnmarshal()
+  }
+
+  override finalizeUnmarshal(): void {
+    const tail = Number(this.message.split(':').pop())
+    this.limit = Number.isFinite(tail) ? tail : undefined
+  }
+}
 
-### `enuserError<T>(err): T`
+ResilientError.registerErrorClass(QuotaExceeded)
+```
 
-Ensures an unknown caught value is a `ResilientError`. Alias for `ResilientError.ensure`.
+### Translate errors in the UI
 
-### `ValueOrError<T>`
+Panel components resolve an error through `errors.<type>` — a form- or screen-scoped
+`<name>.errors.<type>` key first, then `errors.<type>` in the screen's namespace, then the shared
+`errors` library. Ship a translation for every type you declare, in every supported language:
 
-```typescript
-type ValueOrError<T> = T | ResilientError
+```json
+{
+  "errors": {
+    "MyAppInvoiceError": "The invoice could not be processed",
+    "NotFoundMyAppInvoiceError": "This invoice no longer exists",
+    "LockedMyAppInvoiceError": "The invoice is being settled, try again shortly"
+  }
+}
 ```
 
-## Related Packages
+## API
+
+### Classes
+
+| Symbol | Kind | Purpose |
+|--------|------|---------|
+| `ResilientError` | class | Base class of every framework error; `constructor(type, message, stack?)` |
+| `ResilientError.typeName` | static property | Type identifier; override in each subclass (`'ResilientError'` on the base) |
+| `ResilientError.separator` | static property | Marshalling separator, initialised from `SEPARATOR` |
+| `ResilientError.converters` | static property | The registry of `Converter` entries — one array on `globalThis`, shared by every copy of the package in the process |
+| `ResilientError[Symbol.hasInstance]` | static method | `instanceof` that also matches an instance of the same class lineage built by another copy of the package |
+| `ResilientError.registerErrorClass(Class, errorClass?)` | static method | Registers a subclass so it survives a round trip; returns its `Converter` |
+| `ResilientError.ensure(err, throwOnUnknown?)` | static method | Turns an `Error` or string into a `ResilientError`, unmarshalling registered classes |
+| `ResilientError.marshal(err)` | static method | Flattens an error into a plain `Error` whose message is `type`, `message` and stack joined by `SEPARATOR` |
+| `error.type` | instance property | The error's type identifier |
+| `error.oiriginalStack` | instance property | The stack captured at the original throw (spelling as in source) |
+| `error.marshal()` | instance method | `ResilientError.marshal(this)` |
+| `error.finalizeUnmarshal()` | instance method | Hook run after unmarshalling; no-op by default |
+
+### Functions and constants
+
+| Symbol | Kind | Purpose |
+|--------|------|---------|
+| `enuserError<T>(err, throwOnUnknown?)` | function | `ResilientError.ensure`, typed to the subclass you expect |
+| `marshalError(err)` | function | `ensure` then `marshal`, for a boundary that only carries an `Error` or a string |
+| `isResilientError(value)` | function | Structural check (shared brand + `type` + `marshal`) that holds across duplicate module copies |
+| `SEPARATOR` | constant | Three pipe characters — joins the marshalled fields |
+| `RESILENT_ERROR` | constant | `'ResilientError'` — the base type name |
+| `RESILIENT_BRAND`, `CONVERTER_REGISTRY`, `CATCH_ALL_CONVERTER` | constant | `Symbol.for` keys every copy of the package shares |
+
+### Types
+
+| Symbol | Kind | Purpose |
+|--------|------|---------|
+| `ValueOrError<T>` | type | `T \| ResilientError`, for a result that carries either |
+| `Converter` | interface | `{ match, convert, isMarshaled, unmarshal }` — one registry entry |
+| `ResilientErrorConstructor<T>` | interface | The constructor shape `registerErrorClass` accepts: `new (message, stack?)` plus `typeName` |
+
+### Side effect
+
+Importing the package registers the `errors` i18n library (via `addI18nLib` from
+`@owlmeans/i18n`) for `en`, `pl`, `ru`, `be`, `uk`, `es` and `de`. There are no subpath exports.
+
+## Common pitfalls
+
+- Register every subclass. An unregistered error comes back as a bare `ResilientError` whose
+  `type` is the whole `Type|||message|||stack` string.
+- `ensure` on an unregistered, unmarshalled throw shifts the fields: `new Error('boom')` arrives
+  with `type: 'boom'` and the stack as its `message`. Read `.type` only on errors that came back
+  through the registered path.
+- `SyntaxError` is rethrown by `ensure`, never converted. Do not throw one for a runtime condition a
+  caller is expected to handle.
+- The second argument of `registerErrorClass` and `ensure`'s `throwOnUnknown` have no effect — a
+  catch-all converter is matched first. Register the class alone and treat `ensure` as one-argument.
+- A subclass constructor must accept `(message, stack?)`: unmarshalling calls `new Class(message,
+  stack)`. Keep extra state in the message and rebuild it in `finalizeUnmarshal()`.
+- Registration happens at import time. The module declaring the errors must be loaded on the
+  receiving side before an error is ensured, or the class cannot be rebuilt.
+- Keep `typeName` unique per process; show users the translation of `errors.<type>`, never the
+  thrown message.
+
+## Related packages
 
+- [`@owlmeans/i18n`](../i18n) — the registry the `errors` library is added to
+- [`@owlmeans/client-i18n`](../client-i18n) — React hooks that resolve `errors.<type>` keys
+- [`@owlmeans/auth`](../auth) — the authentication and authorization error hierarchy
+- [`@owlmeans/resource`](../resource) — resource errors built on `ResilientError`
+- [`@owlmeans/server-api`](../server-api) — marshals thrown errors into HTTP responses
+- [`@owlmeans/api`](../api) — rebuilds marshalled errors from HTTP responses
+- [`@owlmeans/client-panel`](../client-panel) — panel and form components that translate errors by type
 - [`@owlmeans/context`](../context) — context and services that propagate errors through the app
 
 <!-- owlmeans:agent-guidance:start -->
@@ -83,7 +272,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.33
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/error",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.513Z",
+  "version": "0.1.18-rc.31",
+  "generatedAt": "2026-09-22T17:39:02.544Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/error/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: error
-description: How to use @owlmeans/error — base error classes (ResilientError), error normalization, and i18n-aware error types. Auto-invoked when importing from this package or throwing/catching framework errors.
+description: How to use @owlmeans/error — ResilientError, the error class registry, marshalling errors across a service boundary and back, and the i18n namespace error messages resolve through. Auto-invoked when importing from this package, declaring a typed framework error, or normalizing a caught error.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,44 +8,153 @@ user-invocable: false
 # @owlmeans/error
 
 **Layer:** Core
-**Install:** `"@owlmeans/error": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/error": "^0.1.18-rc.31"` in `dependencies`
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `ResilientError` | Base error class — all framework errors extend this |
-| `ErrorNormalizer` | Normalize unknown errors into ResilientError instances |
-| `ErrorTypes` | Built-in error type aliases |
-| i18n helpers | Resolve error messages through the i18n layer |
+| `ResilientError` | Base class — every framework error extends it |
+| `ResilientError.registerErrorClass(Class)` | Register a subclass so it survives a round trip |
+| `ResilientError.ensure(err)` | Turn anything caught into a `ResilientError` |
+| `ResilientError.marshal(err)` / `err.marshal()` | Flatten into a plain `Error` a transport can carry |
+| `enuserError(err)` | `ensure`, typed to the subclass you expect |
+| `marshalError(err)` | `ensure` then `marshal`, for a boundary that only sends `Error` |
+| `isResilientError(value)` | Structural check that holds across duplicate module copies |
+| `SEPARATOR` (`'\|\|\|'`), `RESILENT_ERROR` | The marshalling separator and the base type name |
+| `RESILIENT_BRAND`, `CONVERTER_REGISTRY`, `CATCH_ALL_CONVERTER` | The `Symbol.for` keys every copy shares |
+| `Converter` | `{ match, convert, isMarshaled, unmarshal }` — one registry entry |
+| `ResilientErrorConstructor` | The constructor shape `registerErrorClass` accepts |
+| `ValueOrError<T>` | `T \| ResilientError`, for a result that carries either |
 
-## Usage
+## Declaring an error
 
-Subclass `ResilientError` for typed framework errors with i18n-resolvable messages:
+A subclass owns a static `typeName` and prefixes its messages, so the pair `type` + `message` is
+enough to identify what went wrong anywhere the error travels. **Register it** — registration is
+what makes a marshaled error come back as the class it was thrown as. Skip it and the far side gets
+an unusable `ResilientError` whose `type` is the whole marshaled string (see below).
 
 ```typescript
 import { ResilientError } from '@owlmeans/error'
 
-export class AgentApiError extends ResilientError {
-  public static override typeName = 'AgentApiError'
-  public constructor(message: string = 'unknown') {
-    super(AgentApiError.typeName, `agent-api:${message}`)
+export class ApiError extends ResilientError {
+  public static override typeName = 'ApiError'
+
+  constructor(message: string = 'error') {
+    super(ApiError.typeName, `api:${message}`)
+  }
+}
+
+export class RateLimitError extends ApiError {
+  public static override typeName = `${ApiError.typeName}:RateLimit`
+
+  constructor(message: string = 'error') {
+    super(`rate-limit:${message}`)
+    this.type = RateLimitError.typeName
   }
 }
 
-// In a handler:
-throw new AgentApiError('rate-limited')
+ResilientError.registerErrorClass(ApiError)
+ResilientError.registerErrorClass(RateLimitError)
+
+throw new RateLimitError('per-minute')
 ```
 
-Catch and normalize:
+A subclass of a subclass calls `super` with the message alone and then re-stamps `this.type` — the
+parent supplies its own prefix, so the final message reads `api:rate-limit:per-minute`.
+
+**A refusal of the caller's condition declares its HTTP status** as `public static httpStatus = <4xx>`;
+a fault — a broken peer, a timeout, a missing configuration, a bug — declares nothing and answers 500.
+One principle picks the number:
+
+| Status | The caller's condition |
+|---|---|
+| 400 | the request is malformed |
+| 402 | the balance or plan does not pay for it |
+| 404 | the addressed target does not exist, or is another organization's |
+| 409 | the target's current state conflicts with the request |
+| 422 | the request is understood, and its content or body is refused |
+
+Declare it on the leaf class, never on a family base: a static is inherited, so a base's status
+would reach every fault that extends it. A class thrown for several causes takes the status of the
+cause a caller can reach, and one whose causes are told apart only by message declares nothing.
+Nothing here reads it — `@owlmeans/server-api` does, structurally, and answers 500 for any class
+without an integer 4xx declaration (see the `server-api` skill). A permission refusal extends
+`AuthForbidden` (403) instead of declaring.
+
+`registerErrorClass` takes a second, native-class argument, and `ensure` takes a second
+`throwOnUnknown` argument. **Neither has any effect** — a catch-all converter is pushed onto the
+registry when this package loads and it is the first entry `ensure` tests for conversion, so no
+later converter and no `throwOnUnknown` branch is ever reached. Register the class alone, and treat
+`ensure` as taking one argument.
+
+## Normalizing what you caught
+
+`ensure` gives you a `ResilientError` for anything caught, but only a **registered, marshaled**
+error survives with its identity intact. Route errors that must keep their type through
+`marshal`/`ensure`; do not rely on `ensure` alone to normalize an arbitrary throw.
+
 ```typescript
-import { ErrorNormalizer } from '@owlmeans/error'
-try { ... } catch (e) {
-  const err = ErrorNormalizer.normalize(e)
-  // err is now a ResilientError with stable .type and .message
+try { /* ... */ } catch (e) {
+  const err = ResilientError.ensure(e as Error)
+  if (err instanceof RateLimitError) { /* the registered class came back */ }
 }
 ```
 
+What `ensure` actually does, in order:
+
+| Input | Result |
+|-------|--------|
+| A `ResilientError` from any copy of this package | returned untouched |
+| A `SyntaxError` | rethrown — never converted |
+| An `Error` marshaled from a **registered** class | unmarshaled into that class, `type` and `message` restored |
+| Anything else | a bare `ResilientError` whose **`type` is the original `message`** and whose **`message` is the original stack** |
+
+That last row is the trap: the fields are shifted, so an unregistered marshaled error arrives with
+`type` set to the whole `Type|||message|||stack` string, and a plain `new Error('boom')` arrives with
+`type: 'boom'`. Read `.type` only where the error came back through the registered path; keep the
+original around when you need its message.
+
+**`SyntaxError` is never converted — it is rethrown.** A `SyntaxError` in this framework means the
+process is wired wrong (an unknown alias, a missing service, a route cycle), and it must crash
+rather than reach a user as a handled failure. Do not throw one for a runtime condition a caller is
+expected to handle.
+
+## Duplicate module copies behave as one
+
+A process can load this package more than once — `bun --preserve-symlinks` over linked workspaces
+keys a module by its unresolved path, so a package that keeps its own
+`node_modules/@owlmeans/error` link loads a second copy. Every copy acts as one:
+
+- **One registry.** `ResilientError.converters` is the array kept on `globalThis` under
+  `Symbol.for('@owlmeans/error:converters')`; every copy registers into it and unmarshals from it,
+  in registration order, so the **last registration of a type name wins** across copies. One
+  catch-all converter exists per process.
+- **One brand.** Every instance inherits `Symbol.for('@owlmeans/error:resilient')` from its copy's
+  prototype. `isResilientError(value)` is brand + string `type` + `marshal` function; `ensure`
+  returns such a value untouched and `marshal` keeps its `type`. A lookalike without the brand is
+  not a resilient error.
+- **`instanceof` across copies.** `ResilientError[Symbol.hasInstance]` answers natively first, then
+  structurally: the instance's lineage of OWN `typeName`s must end with the checked class's lineage.
+  A class from another copy matches itself and its ancestors, never a sibling or a parent. A class
+  that does not declare its own `typeName` matches natively only — declare one on every subclass.
+
+## Crossing a service boundary
+
+`marshal` flattens `type`, `message`, the selected stack exposure and an optional incident id into
+one `Error` message joined by `SEPARATOR`. On the far side `ensure` recognises the prefix and rebuilds
+the registered class, so a typed error thrown in a backend is caught as the same class in a client.
+The HTTP boundary attaches the incident id to the logged error and sends only that id in production;
+development callers may select the stack explicitly. Override
+`finalizeUnmarshal()` on a subclass that needs to rebuild state from its message after that.
+
+## Messages are i18n keys
+
+Importing this package registers the `errors` translation library for every bundled locale. UIs
+resolve an error by its `type` — `errors.<type>`, with a form- or screen-scoped key tried first —
+so the message a user reads comes from the translations, never from the thrown string. Ship a
+translation for each error type you declare.
+
 ## Depends On
 
-- `@owlmeans/i18n` — for resolving error messages by key
+- `@owlmeans/i18n` — the translation library the `errors` namespace is registered in

package/build/consts.d.ts

@@ -1,3 +1,16 @@
 export declare const SEPARATOR = "|||";
 export declare const RESILENT_ERROR = "ResilientError";
+/**
+ * Marks every `ResilientError` instance, whichever copy of this module built it.
+ *
+ * A process can hold several copies of this package (`bun --preserve-symlinks` over a linked
+ * workspace resolves one package through several `node_modules` paths), and `instanceof` answers
+ * for one copy only. `Symbol.for` returns the same symbol in every copy, so the brand is the
+ * structural proof `ensure`, `marshal` and `instanceof` read.
+ */
+export declare const RESILIENT_BRAND: unique symbol;
+/** The `globalThis` key of the converter registry every copy of this module shares. */
+export declare const CONVERTER_REGISTRY: unique symbol;
+/** Marks the catch-all converter, so a second module copy does not push another one. */
+export declare const CATCH_ALL_CONVERTER: unique symbol;
 //# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,SAAS,QAAQ,CAAA;AAE9B,eAAO,MAAM,cAAc,mBAAmB,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,SAAS,QAAQ,CAAA;AAE9B,eAAO,MAAM,cAAc,mBAAmB,CAAA;AAE9C;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,MAAgD,CAAA;AAErF,uFAAuF;AACvF,eAAO,MAAM,kBAAkB,EAAE,OAAO,MAAiD,CAAA;AAEzF,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAAgD,CAAA"}

package/build/consts.js

@@ -1,3 +1,16 @@
 export const SEPARATOR = '|||';
 export const RESILENT_ERROR = 'ResilientError';
+/**
+ * Marks every `ResilientError` instance, whichever copy of this module built it.
+ *
+ * A process can hold several copies of this package (`bun --preserve-symlinks` over a linked
+ * workspace resolves one package through several `node_modules` paths), and `instanceof` answers
+ * for one copy only. `Symbol.for` returns the same symbol in every copy, so the brand is the
+ * structural proof `ensure`, `marshal` and `instanceof` read.
+ */
+export const RESILIENT_BRAND = Symbol.for('@owlmeans/error:resilient');
+/** The `globalThis` key of the converter registry every copy of this module shares. */
+export const CONVERTER_REGISTRY = Symbol.for('@owlmeans/error:converters');
+/** Marks the catch-all converter, so a second module copy does not push another one. */
+export const CATCH_ALL_CONVERTER = Symbol.for('@owlmeans/error:catch-all');
 //# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -1 +1 @@
-{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,CAAA;AAE9B,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAA"}
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,CAAA;AAE9B,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAA;AAE9C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAkB,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAA;AAErF,uFAAuF;AACvF,MAAM,CAAC,MAAM,kBAAkB,GAAkB,MAAM,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAA;AAEzF,wFAAwF;AACxF,MAAM,CAAC,MAAM,mBAAmB,GAAkB,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAA"}

package/build/i18n/fr.json

@@ -0,0 +1,4 @@
+{
+    "minLength": "La valeur est trop courte",
+    "maxLength": "La valeur est trop longue"
+}

package/build/i18n.js

@@ -6,6 +6,7 @@ import be from './i18n/be.json' with { type: 'json' };
 import uk from './i18n/uk.json' with { type: 'json' };
 import es from './i18n/es.json' with { type: 'json' };
 import de from './i18n/de.json' with { type: 'json' };
+import fr from './i18n/fr.json' with { type: 'json' };
 addI18nLib('en', 'errors', en);
 addI18nLib('pl', 'errors', pl);
 addI18nLib('ru', 'errors', ru);
@@ -13,4 +14,5 @@ addI18nLib('be', 'errors', be);
 addI18nLib('uk', 'errors', uk);
 addI18nLib('es', 'errors', es);
 addI18nLib('de', 'errors', de);
+addI18nLib('fr', 'errors', fr);
 //# sourceMappingURL=i18n.js.map

package/build/i18n.js.map

@@ -1 +1 @@
-{"version":3,"file":"i18n.js","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAE3C,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AAErD,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA;AAC9B,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA;AAC9B,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA;AAC9B,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA;AAC9B,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA;AAC9B,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA;AAC9B,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA"}
+{"version":3,"file":"i18n.js","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAE3C,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AAErD,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA;AAC9B,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA;AAC9B,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA;AAC9B,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA;AAC9B,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA;AAC9B,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA;AAC9B,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA;AAC9B,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA"}

package/build/resilient.d.ts

@@ -1,15 +1,33 @@
-import type { Converter, ResilientErrorConstructor } from './types.js';
+import type { Converter, MarshalErrorOptions, ResilientErrorConstructor } from './types.js';
+/**
+ * Whether a value is a `ResilientError` built by ANY copy of this module.
+ *
+ * Structural: the shared brand plus the `type` and `marshal` every instance carries.
+ */
+export declare const isResilientError: (value: unknown) => value is ResilientError;
 export declare class ResilientError extends Error {
     static separator: string;
     static typeName: string;
     static converters: Converter[];
+    /**
+     * `instanceof` that holds across module copies.
+     *
+     * The native prototype check answers first. Failing that, a branded instance matches when its
+     * class lineage ENDS WITH this class's lineage — the same own type names, in the same order, up
+     * to the base. So `instanceof AuthFailedError` accepts an `AuthFailedError` (or a subclass of it)
+     * from another copy, and never a sibling class or a parent. A class that does not declare its
+     * own `typeName` cannot be told apart structurally and answers natively only.
+     */
+    static [Symbol.hasInstance]<T extends abstract new (...args: any[]) => any>(this: T, instance: unknown): instance is InstanceType<T>;
     static registerErrorClass(resilientErrorClass: ResilientErrorConstructor, errorClass?: ErrorConstructor): Converter;
     static ensure(err: Error | string, throwOnUnknown?: boolean): ResilientError;
-    static marshal(err: Error): Error;
+    static marshal(err: Error, opts?: MarshalErrorOptions): Error;
     type: string;
     oiriginalStack?: string;
+    /** Correlates a serialized boundary error with the server log entry that owns its full stack. */
+    incidentId?: string;
     constructor(type: string, message: string, stack?: string);
-    marshal(): Error;
+    marshal(opts?: MarshalErrorOptions): Error;
     finalizeUnmarshal(): void;
 }
 //# sourceMappingURL=resilient.d.ts.map

package/build/resilient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resilient.d.ts","sourceRoot":"","sources":["../src/resilient.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA;AAGtE,qBAAa,cAAe,SAAQ,KAAK;IACvC,OAAc,SAAS,EAAE,MAAM,CAAY;IAE3C,OAAc,QAAQ,EAAE,MAAM,CAAiB;IAE/C,OAAc,UAAU,EAAE,SAAS,EAAE,CAAK;IAE1C,OAAc,kBAAkB,CAAC,mBAAmB,EAAE,yBAAyB,EAAE,UAAU,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAKzH;IAED,OAAc,MAAM,CAAC,GAAG,EAAE,KAAK,GAAG,MAAM,EAAE,cAAc,CAAC,EAAE,OAAO,GAAG,cAAc,CA4BlF;IAED,OAAc,OAAO,CAAC,GAAG,EAAE,KAAK,GAAG,KAAK,CAMvC;IAEM,IAAI,EAAE,MAAM,CAAiB;IAE7B,cAAc,CAAC,EAAE,MAAM,CAAA;IAE9B,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAQxD;IAED,OAAO,IAAI,KAAK,CAEf;IAED,iBAAiB,IAAI,IAAI,CAAI;CAC9B"}
+{"version":3,"file":"resilient.d.ts","sourceRoot":"","sources":["../src/resilient.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA;AAyC3F;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,UAAW,OAAO,KAAG,KAAK,IAAI,cAS1D,CAAA;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,OAAc,SAAS,EAAE,MAAM,CAAY;IAE3C,OAAc,QAAQ,EAAE,MAAM,CAAiB;IAE/C,OAAc,UAAU,EAAE,SAAS,EAAE,CAAqB;IAE1D;;;;;;;;OAQG;IACH,OAAuB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACxF,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,OAAO,GACzB,QAAQ,IAAI,YAAY,CAAC,CAAC,CAAC,CAY7B;IAED,OAAc,kBAAkB,CAAC,mBAAmB,EAAE,yBAAyB,EAAE,UAAU,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAKzH;IAED,OAAc,MAAM,CAAC,GAAG,EAAE,KAAK,GAAG,MAAM,EAAE,cAAc,CAAC,EAAE,OAAO,GAAG,cAAc,CA4BlF;IAED,OAAc,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,KAAK,CAenE;IAEM,IAAI,EAAE,MAAM,CAAiB;IAE7B,cAAc,CAAC,EAAE,MAAM,CAAA;IAE9B,iGAAiG;IAC1F,UAAU,CAAC,EAAE,MAAM,CAAA;IAE1B,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAQxD;IAED,OAAO,CAAC,IAAI,CAAC,EAAE,mBAAmB,GAAG,KAAK,CAEzC;IAED,iBAAiB,IAAI,IAAI,CAAI;CAC9B"}