@pristine-ts/common 2.0.4 → 2.0.6

package/dist/lib/esm/decorators/traced.decorator.js.map

@@ -1 +1 @@
-{"version":3,"file":"traced.decorator.js","sourceRoot":"","sources":["../../../../src/decorators/traced.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,sBAAsB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,UAAU,MAAM,CAAC,QAAiB;IACtC,OAAO,CAAC,MAAW,EAAE,WAA4B,EAAE,UAA8B,EAAE,EAAE;;QACnF,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC;QAClC,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;YACnC,+EAA+E;YAC/E,4EAA4E;YAC5E,4BAA4B;YAC5B,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,iFAAiF;QACjF,gFAAgF;QAChF,+CAA+C;QAC/C,MAAM,SAAS,GAAW,MAAA,MAAA,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,WAAW,0CAAE,IAAI,mCAAI,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,IAAI,mCAAI,WAAW,CAAC;QACnF,MAAM,YAAY,GAAG,QAAQ,aAAR,QAAQ,cAAR,QAAQ,GAAI,GAAG,SAAS,IAAI,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QAEvE,UAAU,CAAC,KAAK,GAAG,UAAyB,GAAG,IAAW;YACxD,OAAO,UAAU,CAAC,WAAW,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAChF,CAAC,CAAC;QAEF,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"traced.decorator.js","sourceRoot":"","sources":["../../../../src/decorators/traced.decorator.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAC,mBAAmB,EAAC,MAAM,mCAAmC,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,UAAU,MAAM,CAAC,QAAiB;IACtC,OAAO,CAAC,MAAW,EAAE,WAA4B,EAAE,UAA8B,EAAE,EAAE;;QACnF,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC;QAClC,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;YACnC,+EAA+E;YAC/E,4EAA4E;YAC5E,4BAA4B;YAC5B,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,iFAAiF;QACjF,gFAAgF;QAChF,+CAA+C;QAC/C,MAAM,SAAS,GAAW,MAAA,MAAA,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,WAAW,0CAAE,IAAI,mCAAI,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,IAAI,mCAAI,WAAW,CAAC;QACnF,MAAM,YAAY,GAAG,QAAQ,aAAR,QAAQ,cAAR,QAAQ,GAAI,GAAG,SAAS,IAAI,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QAEvE,UAAU,CAAC,KAAK,GAAG,UAA+B,GAAG,IAAW;;gBAC9D,MAAM,cAAc,GAAG,mBAAmB,CAAC,cAAc,EAAE,CAAC;gBAC5D,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;oBACjC,6EAA6E;oBAC7E,2EAA2E;oBAC3E,mBAAmB;oBACnB,OAAO,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBAC1C,CAAC;gBAED,MAAM,IAAI,GAAG,cAAc,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;gBACpD,IAAI,CAAC;oBACH,OAAO,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBAC1C,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,wEAAwE;oBACxE,8EAA8E;oBAC9E,gEAAgE;oBAChE,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;wBAC3B,IAAI,CAAC,OAAO,mCACP,IAAI,CAAC,OAAO,KACf,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,KAAK,CAAC,IAAI,EACrB,YAAY,EAAE,KAAK,CAAC,OAAO,GAC5B,CAAC;oBACJ,CAAC;yBAAM,CAAC;wBACN,IAAI,CAAC,OAAO,mCACP,IAAI,CAAC,OAAO,KACf,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,iBAAiB,EAC5B,YAAY,EAAE,MAAM,CAAC,KAAK,CAAC,GAC5B,CAAC;oBACJ,CAAC;oBACD,MAAM,KAAK,CAAC;gBACd,CAAC;wBAAS,CAAC;oBACT,IAAI,CAAC,GAAG,EAAE,CAAC;gBACb,CAAC;YACH,CAAC;SAAA,CAAC;QAEF,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC"}

package/dist/lib/esm/errors/bad-request.error.js

@@ -0,0 +1,11 @@
+import { ExitCode } from "./exit-code.enum";
+import { PristineError } from "./pristine.error";
+import { PristineErrorCode } from "./pristine-error-code.enum";
+import { PristineErrorKind } from "./pristine-error-kind.enum";
+/** 400. Caller sent malformed/invalid input. CLI exit `ExitCode.DataError` (65). */
+export class BadRequestError extends PristineError {
+    constructor(message, options = {}) {
+        super(message, Object.assign({ code: PristineErrorCode.BadRequest, httpStatus: 400, exitCode: ExitCode.DataError, kind: PristineErrorKind.UserError }, options));
+    }
+}
+//# sourceMappingURL=bad-request.error.js.map

package/dist/lib/esm/errors/bad-request.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bad-request.error.js","sourceRoot":"","sources":["../../../../src/errors/bad-request.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,QAAQ,EAAC,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAK7D,oFAAoF;AACpF,MAAM,OAAO,eAAgB,SAAQ,aAAa;IAChD,YAAY,OAAe,EAAE,UAA2B,EAAE;QACxD,KAAK,CAAC,OAAO,kBACX,IAAI,EAAE,iBAAiB,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,SAAS,EACjF,IAAI,EAAE,iBAAiB,CAAC,SAAS,IAC9B,OAAO,EACV,CAAC;IACL,CAAC;CACF"}

package/dist/lib/esm/errors/config.error.js

@@ -0,0 +1,16 @@
+import { ExitCode } from "./exit-code.enum";
+import { PristineError } from "./pristine.error";
+import { PristineErrorCode } from "./pristine-error-code.enum";
+import { PristineErrorKind } from "./pristine-error-kind.enum";
+/**
+ * Configuration loading / parsing / validation failure. No `httpStatus` — config errors
+ * shouldn't be exposed to HTTP callers, so the responder will treat them as 500 with
+ * sanitized message. CLI exit `ExitCode.Configuration` (78). Marked `SystemError` so the
+ * message isn't surfaced verbatim in production HTTP responses.
+ */
+export class ConfigError extends PristineError {
+    constructor(message, options = {}) {
+        super(message, Object.assign({ code: PristineErrorCode.ConfigError, exitCode: ExitCode.Configuration, kind: PristineErrorKind.SystemError }, options));
+    }
+}
+//# sourceMappingURL=config.error.js.map

package/dist/lib/esm/errors/config.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.error.js","sourceRoot":"","sources":["../../../../src/errors/config.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,QAAQ,EAAC,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAK7D;;;;;GAKG;AACH,MAAM,OAAO,WAAY,SAAQ,aAAa;IAC5C,YAAY,OAAe,EAAE,UAA2B,EAAE;QACxD,KAAK,CAAC,OAAO,kBACX,IAAI,EAAE,iBAAiB,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC,aAAa,EACrE,IAAI,EAAE,iBAAiB,CAAC,WAAW,IAChC,OAAO,EACV,CAAC;IACL,CAAC;CACF"}

package/dist/lib/esm/errors/conflict.error.js

@@ -0,0 +1,11 @@
+import { ExitCode } from "./exit-code.enum";
+import { PristineError } from "./pristine.error";
+import { PristineErrorCode } from "./pristine-error-code.enum";
+import { PristineErrorKind } from "./pristine-error-kind.enum";
+/** 409. Operation conflicts with existing state (duplicate, version mismatch, etc.). */
+export class ConflictError extends PristineError {
+    constructor(message, options = {}) {
+        super(message, Object.assign({ code: PristineErrorCode.Conflict, httpStatus: 409, exitCode: ExitCode.Error, kind: PristineErrorKind.UserError }, options));
+    }
+}
+//# sourceMappingURL=conflict.error.js.map

package/dist/lib/esm/errors/conflict.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict.error.js","sourceRoot":"","sources":["../../../../src/errors/conflict.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,QAAQ,EAAC,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAK7D,wFAAwF;AACxF,MAAM,OAAO,aAAc,SAAQ,aAAa;IAC9C,YAAY,OAAe,EAAE,UAA2B,EAAE;QACxD,KAAK,CAAC,OAAO,kBACX,IAAI,EAAE,iBAAiB,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,EAC3E,IAAI,EAAE,iBAAiB,CAAC,SAAS,IAC9B,OAAO,EACV,CAAC;IACL,CAAC;CACF"}

package/dist/lib/esm/errors/errors.js

@@ -1,2 +1,15 @@
-export * from "./loggable.error";
+export * from "./bad-request.error";
+export * from "./config.error";
+export * from "./conflict.error";
+export * from "./exit-code.enum";
+export * from "./forbidden.error";
+export * from "./internal.error";
+export * from "./not-found.error";
+export * from "./pristine-error-code.enum";
+export * from "./pristine-error-kind.enum";
+export * from "./pristine-error-options.interface";
+export * from "./pristine.error";
+export * from "./unauthorized.error";
+export * from "./usage.error";
+export * from "./validation.error";
 //# sourceMappingURL=errors.js.map

package/dist/lib/esm/errors/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../src/errors/errors.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../src/errors/errors.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oCAAoC,CAAC;AACnD,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC"}

package/dist/lib/esm/errors/exit-code.enum.js

@@ -0,0 +1,47 @@
+/**
+ * Standard process exit codes, drawn from BSD's `sysexits.h` conventions. Surfaced by
+ * `CliErrorReporter` and `PristineError.options.exitCode` so shell pipelines can branch on
+ * meaningful failure categories rather than the binary "0 or non-zero" distinction.
+ *
+ * **Use the enum for framework-standard codes.** Consumers can pass raw numbers for any
+ * custom exit code — `PristineErrorOptions.exitCode` is typed `ExitCode | number`.
+ *
+ * Note that exit codes ≥ 64 (`Usage` and above) follow the `sysexits.h` registered
+ * meanings; lower codes (1, etc.) are conventional but not standardized.
+ *
+ * ```ts
+ * throw new ConfigError("Missing DATABASE_URL", {
+ *   exitCode: ExitCode.Configuration,   // 78 — picked up by shells aware of sysexits.h
+ * });
+ *
+ * throw new UsageError("Unknown flag --foo", {
+ *   exitCode: ExitCode.Usage,           // 64
+ * });
+ * ```
+ */
+export var ExitCode;
+(function (ExitCode) {
+    /** Successful termination. */
+    ExitCode[ExitCode["Success"] = 0] = "Success";
+    /** Generic error. Default fallback for user-facing errors that don't specify a code. */
+    ExitCode[ExitCode["Error"] = 1] = "Error";
+    /** Command-line usage error (`EX_USAGE`). Bad flags, missing required args, unknown commands. */
+    ExitCode[ExitCode["Usage"] = 64] = "Usage";
+    /** Input data malformed (`EX_DATAERR`). Validation failed, body unparseable. */
+    ExitCode[ExitCode["DataError"] = 65] = "DataError";
+    /** Internal software error (`EX_SOFTWARE`). Default fallback for system errors. */
+    ExitCode[ExitCode["Software"] = 70] = "Software";
+    /** Can't create user output file (`EX_CANTCREAT`). */
+    ExitCode[ExitCode["Cantcreat"] = 73] = "Cantcreat";
+    /** Input/output error (`EX_IOERR`). */
+    ExitCode[ExitCode["IoError"] = 74] = "IoError";
+    /** Temporary failure, retry might succeed (`EX_TEMPFAIL`). */
+    ExitCode[ExitCode["Temporary"] = 75] = "Temporary";
+    /** Remote error in protocol (`EX_PROTOCOL`). */
+    ExitCode[ExitCode["Protocol"] = 76] = "Protocol";
+    /** Permission denied (`EX_NOPERM`). Authentication / authorization failures. */
+    ExitCode[ExitCode["NoPermission"] = 77] = "NoPermission";
+    /** Configuration error (`EX_CONFIG`). Missing or invalid config. */
+    ExitCode[ExitCode["Configuration"] = 78] = "Configuration";
+})(ExitCode || (ExitCode = {}));
+//# sourceMappingURL=exit-code.enum.js.map

package/dist/lib/esm/errors/exit-code.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-code.enum.js","sourceRoot":"","sources":["../../../../src/errors/exit-code.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAN,IAAY,QAiCX;AAjCD,WAAY,QAAQ;IAClB,8BAA8B;IAC9B,6CAAmB,CAAA;IAEnB,wFAAwF;IACxF,yCAAmB,CAAA;IAEnB,iGAAiG;IACjG,0CAAoB,CAAA;IAEpB,gFAAgF;IAChF,kDAAoB,CAAA;IAEpB,mFAAmF;IACnF,gDAAoB,CAAA;IAEpB,sDAAsD;IACtD,kDAAoB,CAAA;IAEpB,uCAAuC;IACvC,8CAAoB,CAAA;IAEpB,8DAA8D;IAC9D,kDAAoB,CAAA;IAEpB,gDAAgD;IAChD,gDAAoB,CAAA;IAEpB,gFAAgF;IAChF,wDAAoB,CAAA;IAEpB,oEAAoE;IACpE,0DAAoB,CAAA;AACtB,CAAC,EAjCW,QAAQ,KAAR,QAAQ,QAiCnB"}

package/dist/lib/esm/errors/forbidden.error.js

@@ -0,0 +1,11 @@
+import { ExitCode } from "./exit-code.enum";
+import { PristineError } from "./pristine.error";
+import { PristineErrorCode } from "./pristine-error-code.enum";
+import { PristineErrorKind } from "./pristine-error-kind.enum";
+/** 403. Caller is authenticated but lacks permission. CLI exit `ExitCode.NoPermission` (77). */
+export class ForbiddenError extends PristineError {
+    constructor(message = "Forbidden", options = {}) {
+        super(message, Object.assign({ code: PristineErrorCode.Forbidden, httpStatus: 403, exitCode: ExitCode.NoPermission, kind: PristineErrorKind.UserError }, options));
+    }
+}
+//# sourceMappingURL=forbidden.error.js.map

package/dist/lib/esm/errors/forbidden.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forbidden.error.js","sourceRoot":"","sources":["../../../../src/errors/forbidden.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,QAAQ,EAAC,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAK7D,gGAAgG;AAChG,MAAM,OAAO,cAAe,SAAQ,aAAa;IAC/C,YAAY,UAAkB,WAAW,EAAE,UAA2B,EAAE;QACtE,KAAK,CAAC,OAAO,kBACX,IAAI,EAAE,iBAAiB,CAAC,SAAS,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,YAAY,EACnF,IAAI,EAAE,iBAAiB,CAAC,SAAS,IAC9B,OAAO,EACV,CAAC;IACL,CAAC;CACF"}

package/dist/lib/esm/errors/internal.error.js

@@ -0,0 +1,15 @@
+import { ExitCode } from "./exit-code.enum";
+import { PristineError } from "./pristine.error";
+import { PristineErrorCode } from "./pristine-error-code.enum";
+import { PristineErrorKind } from "./pristine-error-kind.enum";
+/**
+ * Catch-all for framework/system bugs that shouldn't be exposed verbatim. 500.
+ * CLI exit `ExitCode.Software` (70). `SystemError` triggers message sanitization in
+ * production mode.
+ */
+export class InternalError extends PristineError {
+    constructor(message = "Internal error", options = {}) {
+        super(message, Object.assign({ code: PristineErrorCode.InternalError, httpStatus: 500, exitCode: ExitCode.Software, kind: PristineErrorKind.SystemError }, options));
+    }
+}
+//# sourceMappingURL=internal.error.js.map

package/dist/lib/esm/errors/internal.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.error.js","sourceRoot":"","sources":["../../../../src/errors/internal.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,QAAQ,EAAC,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAK7D;;;;GAIG;AACH,MAAM,OAAO,aAAc,SAAQ,aAAa;IAC9C,YAAY,UAAkB,gBAAgB,EAAE,UAA2B,EAAE;QAC3E,KAAK,CAAC,OAAO,kBACX,IAAI,EAAE,iBAAiB,CAAC,aAAa,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EACnF,IAAI,EAAE,iBAAiB,CAAC,WAAW,IAChC,OAAO,EACV,CAAC;IACL,CAAC;CACF"}

package/dist/lib/esm/errors/not-found.error.js

@@ -0,0 +1,11 @@
+import { ExitCode } from "./exit-code.enum";
+import { PristineError } from "./pristine.error";
+import { PristineErrorCode } from "./pristine-error-code.enum";
+import { PristineErrorKind } from "./pristine-error-kind.enum";
+/** 404. Resource doesn't exist. CLI exit `ExitCode.Error` (1). */
+export class NotFoundError extends PristineError {
+    constructor(message, options = {}) {
+        super(message, Object.assign({ code: PristineErrorCode.NotFound, httpStatus: 404, exitCode: ExitCode.Error, kind: PristineErrorKind.UserError }, options));
+    }
+}
+//# sourceMappingURL=not-found.error.js.map

package/dist/lib/esm/errors/not-found.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-found.error.js","sourceRoot":"","sources":["../../../../src/errors/not-found.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,QAAQ,EAAC,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAK7D,kEAAkE;AAClE,MAAM,OAAO,aAAc,SAAQ,aAAa;IAC9C,YAAY,OAAe,EAAE,UAA2B,EAAE;QACxD,KAAK,CAAC,OAAO,kBACX,IAAI,EAAE,iBAAiB,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,EAC3E,IAAI,EAAE,iBAAiB,CAAC,SAAS,IAC9B,OAAO,EACV,CAAC;IACL,CAAC;CACF"}

package/dist/lib/esm/errors/pristine-error-code.enum.js

@@ -0,0 +1,34 @@
+/**
+ * Standard error-code catalog used across the framework. Each value is a `SCREAMING_SNAKE_CASE`
+ * slug surfaced in the HTTP response body (`{"code": ...}`) and on CLI stderr (`✗ CODE: ...`).
+ *
+ * **Use the enum members for framework-standard cases.** Consumers can add their own
+ * domain-specific codes by passing a plain string — `PristineErrorOptions.code` is typed
+ * `PristineErrorCode | string` so both the enum and free-form strings get autocomplete-
+ * friendly type checking.
+ *
+ * ```ts
+ * throw new PristineError("Token expired", {
+ *   code: "TOKEN_EXPIRED",                       // consumer-defined code
+ *   httpStatus: 401,
+ * });
+ *
+ * throw new PristineError("Item missing", {
+ *   code: PristineErrorCode.NotFound,            // framework-standard code
+ *   httpStatus: 404,
+ * });
+ * ```
+ */
+export var PristineErrorCode;
+(function (PristineErrorCode) {
+    PristineErrorCode["BadRequest"] = "BAD_REQUEST";
+    PristineErrorCode["Unauthorized"] = "UNAUTHORIZED";
+    PristineErrorCode["Forbidden"] = "FORBIDDEN";
+    PristineErrorCode["NotFound"] = "NOT_FOUND";
+    PristineErrorCode["Conflict"] = "CONFLICT";
+    PristineErrorCode["ValidationFailed"] = "VALIDATION_FAILED";
+    PristineErrorCode["ConfigError"] = "CONFIG_ERROR";
+    PristineErrorCode["UsageError"] = "USAGE_ERROR";
+    PristineErrorCode["InternalError"] = "INTERNAL_ERROR";
+})(PristineErrorCode || (PristineErrorCode = {}));
+//# sourceMappingURL=pristine-error-code.enum.js.map

package/dist/lib/esm/errors/pristine-error-code.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pristine-error-code.enum.js","sourceRoot":"","sources":["../../../../src/errors/pristine-error-code.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAN,IAAY,iBAUX;AAVD,WAAY,iBAAiB;IAC3B,+CAAiC,CAAA;IACjC,kDAAkC,CAAA;IAClC,4CAA+B,CAAA;IAC/B,2CAA+B,CAAA;IAC/B,0CAA8B,CAAA;IAC9B,2DAAuC,CAAA;IACvC,iDAAkC,CAAA;IAClC,+CAAiC,CAAA;IACjC,qDAAoC,CAAA;AACtC,CAAC,EAVW,iBAAiB,KAAjB,iBAAiB,QAU5B"}

package/dist/lib/esm/errors/pristine-error-kind.enum.js

@@ -0,0 +1,26 @@
+/**
+ * Categorizes a `PristineError` by who caused it. Replaces the older `expected: boolean`
+ * field, whose meaning ("expected by whom?") wasn't self-explanatory.
+ *
+ * The kind drives how the channel reporters render the error in production mode:
+ *
+ * - `UserError`: caller did something wrong. Message is safe to expose verbatim;
+ *   structured details surface as-is. HTTP responses use the carried `httpStatus`
+ *   (typically 4xx). CLI stderr shows the message and details.
+ *
+ * - `SystemError`: framework or downstream bug — not the caller's fault. In production
+ *   mode the message is replaced with a generic "Internal Server Error" / "Internal Error"
+ *   so internal details never leak to clients. Stack and cause chain are still logged
+ *   internally via the LogHandler for operators. In development mode (`PRISTINE_ENV=dev`)
+ *   the full message surfaces.
+ *
+ * Default is `UserError` — most thrown errors in framework and application code are caller-
+ * induced. `PristineError.from(unknown)` marks raw `Error` and non-Error throws as
+ * `SystemError` since they didn't opt into the typed contract.
+ */
+export var PristineErrorKind;
+(function (PristineErrorKind) {
+    PristineErrorKind["UserError"] = "user-error";
+    PristineErrorKind["SystemError"] = "system-error";
+})(PristineErrorKind || (PristineErrorKind = {}));
+//# sourceMappingURL=pristine-error-kind.enum.js.map

package/dist/lib/esm/errors/pristine-error-kind.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pristine-error-kind.enum.js","sourceRoot":"","sources":["../../../../src/errors/pristine-error-kind.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAN,IAAY,iBAGX;AAHD,WAAY,iBAAiB;IAC3B,6CAA0B,CAAA;IAC1B,iDAA4B,CAAA;AAC9B,CAAC,EAHW,iBAAiB,KAAjB,iBAAiB,QAG5B"}

package/dist/lib/esm/errors/pristine-error-options.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pristine-error-options.interface.js.map

package/dist/lib/esm/errors/pristine-error-options.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pristine-error-options.interface.js","sourceRoot":"","sources":["../../../../src/errors/pristine-error-options.interface.ts"],"names":[],"mappings":""}

package/dist/lib/esm/errors/pristine.error.js

@@ -0,0 +1,105 @@
+import { PristineErrorKind } from "./pristine-error-kind.enum";
+/**
+ * Single error base for the entire framework. Replaces the old `LoggableError` +
+ * `HttpError` + ad-hoc subclass hierarchy.
+ *
+ * **What it gives you**:
+ * - A structured `options` bag (`code`, `httpStatus`, `exitCode`, `details`, `cause`,
+ *   `kind`) read by both the HTTP and CLI channel reporters.
+ * - Automatic `error.name = ClassName` for subclasses.
+ * - Automatic prototype-chain fix via `new.target.prototype` — subclasses never need to
+ *   repeat the `Object.setPrototypeOf(this, FooError.prototype)` incantation, AND
+ *   `instanceof` works correctly for direct/standard-library/custom subclasses at any
+ *   depth (verified by spec).
+ * - Standard `Error.cause` propagation (Node 16.9+ native).
+ *
+ * **Subclass form** when a named class makes `instanceof` checks read better:
+ *
+ * ```ts
+ * export class TokenExpiredError extends UnauthorizedError {
+ *   constructor(tokenId: string) {
+ *     super("The token has expired", {
+ *       code: "TOKEN_EXPIRED",
+ *       details: { tokenId },
+ *     });
+ *   }
+ * }
+ * // ...
+ * try { ... }
+ * catch (e) { if (e instanceof TokenExpiredError) ... }   // works.
+ * ```
+ *
+ * **Direct form** when the call site self-documents:
+ *
+ * ```ts
+ * throw new PristineError(`User '${id}' not found`, {
+ *   code: PristineErrorCode.NotFound,
+ *   httpStatus: 404,
+ *   details: { resource: "User", id },
+ * });
+ * ```
+ *
+ * **Re-throw with enrichment** when catching, adding context, and re-throwing. Use the
+ * standard `cause` chain rather than mutating the original — this preserves the original
+ * error's identity for tooling that walks `error.cause`:
+ *
+ * ```ts
+ * try { await dispatcher.dispatch(event); }
+ * catch (cause) {
+ *   throw new PristineError("Event dispatch failed", {
+ *     code: "EVENT_DISPATCH_FAILED",
+ *     kind: PristineErrorKind.SystemError,
+ *     cause,
+ *     details: { eventId: event.id },
+ *   });
+ * }
+ * ```
+ */
+export class PristineError extends Error {
+    constructor(message, options = {}) {
+        // Use the standard Error.cause slot so any tooling that knows the standard chain
+        // (debuggers, V8's default Error formatting, OpenTelemetry's exception recording)
+        // picks it up automatically. We don't need a custom `originalError` slot.
+        super(message, { cause: options.cause });
+        // `new.target` is the actual class being constructed (subclass or PristineError
+        // itself). Using it for both `name` and `setPrototypeOf` means subclasses never need
+        // to repeat the boilerplate, and `instanceof` works correctly at every depth.
+        this.name = new.target.name;
+        Object.setPrototypeOf(this, new.target.prototype);
+        // `kind: UserError` is the default — most thrown errors are caller-induced. System
+        // errors get marked explicitly via `kind: PristineErrorKind.SystemError` (or by
+        // `PristineError.from` for unknown throws).
+        this.options = Object.assign({ kind: PristineErrorKind.UserError }, options);
+    }
+    /**
+     * Normalizes any thrown value into a `PristineError`. The chokepoint that every channel
+     * reporter funnels through before rendering, so the reporters never need to handle
+     * unknown shapes.
+     *
+     * - `PristineError` instances pass through unchanged.
+     * - `Error` instances are wrapped with `kind: SystemError` and propagated as `cause` —
+     *   the wrapper preserves the original message and stack for `mode === Development`
+     *   rendering.
+     * - Anything else (strings, numbers, `throw {someObject}`) is coerced via `String(...)`
+     *   into a message with `kind: SystemError`.
+     *
+     * The standard `Error.cause` chain is preserved: if the input has a `cause`, it stays
+     * on the wrapper (which itself has the input as its cause), so a debugger walking
+     * `error.cause.cause.cause` sees the full history.
+     */
+    static from(error) {
+        if (error instanceof PristineError) {
+            return error;
+        }
+        if (error instanceof Error) {
+            return new PristineError(error.message, {
+                cause: error,
+                kind: PristineErrorKind.SystemError,
+            });
+        }
+        return new PristineError(String(error), {
+            kind: PristineErrorKind.SystemError,
+        });
+    }
+}
+//# sourceMappingURL=pristine.error.js.map

package/dist/lib/esm/errors/pristine.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pristine.error.js","sourceRoot":"","sources":["../../../../src/errors/pristine.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAGtC,YAAY,OAAe,EAAE,UAAgC,EAAE;QAC7D,iFAAiF;QACjF,kFAAkF;QAClF,0EAA0E;QAC1E,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QAEzC,gFAAgF;QAChF,qFAAqF;QACrF,8EAA8E;QAC9E,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAElD,mFAAmF;QACnF,gFAAgF;QAChF,4CAA4C;QAC5C,IAAI,CAAC,OAAO,mBAAK,IAAI,EAAE,iBAAiB,CAAC,SAAS,IAAK,OAAO,CAAE,CAAC;IACnE,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,IAAI,CAAC,KAAc;QACxB,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;YACnC,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,OAAO,IAAI,aAAa,CAAC,KAAK,CAAC,OAAO,EAAE;gBACtC,KAAK,EAAE,KAAK;gBACZ,IAAI,EAAE,iBAAiB,CAAC,WAAW;aACpC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;YACtC,IAAI,EAAE,iBAAiB,CAAC,WAAW;SACpC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/lib/esm/errors/unauthorized.error.js

@@ -0,0 +1,11 @@
+import { ExitCode } from "./exit-code.enum";
+import { PristineError } from "./pristine.error";
+import { PristineErrorCode } from "./pristine-error-code.enum";
+import { PristineErrorKind } from "./pristine-error-kind.enum";
+/** 401. Caller is not authenticated. CLI exit `ExitCode.NoPermission` (77). */
+export class UnauthorizedError extends PristineError {
+    constructor(message = "Unauthorized", options = {}) {
+        super(message, Object.assign({ code: PristineErrorCode.Unauthorized, httpStatus: 401, exitCode: ExitCode.NoPermission, kind: PristineErrorKind.UserError }, options));
+    }
+}
+//# sourceMappingURL=unauthorized.error.js.map

package/dist/lib/esm/errors/unauthorized.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unauthorized.error.js","sourceRoot":"","sources":["../../../../src/errors/unauthorized.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,QAAQ,EAAC,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAK7D,+EAA+E;AAC/E,MAAM,OAAO,iBAAkB,SAAQ,aAAa;IAClD,YAAY,UAAkB,cAAc,EAAE,UAA2B,EAAE;QACzE,KAAK,CAAC,OAAO,kBACX,IAAI,EAAE,iBAAiB,CAAC,YAAY,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,YAAY,EACtF,IAAI,EAAE,iBAAiB,CAAC,SAAS,IAC9B,OAAO,EACV,CAAC;IACL,CAAC;CACF"}

package/dist/lib/esm/errors/usage.error.js

@@ -0,0 +1,14 @@
+import { ExitCode } from "./exit-code.enum";
+import { PristineError } from "./pristine.error";
+import { PristineErrorCode } from "./pristine-error-code.enum";
+import { PristineErrorKind } from "./pristine-error-kind.enum";
+/**
+ * CLI-only — bad command-line usage (wrong flag, missing required arg, unknown command).
+ * No `httpStatus`. CLI exit `ExitCode.Usage` (64).
+ */
+export class UsageError extends PristineError {
+    constructor(message, options = {}) {
+        super(message, Object.assign({ code: PristineErrorCode.UsageError, exitCode: ExitCode.Usage, kind: PristineErrorKind.UserError }, options));
+    }
+}
+//# sourceMappingURL=usage.error.js.map

package/dist/lib/esm/errors/usage.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.error.js","sourceRoot":"","sources":["../../../../src/errors/usage.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,QAAQ,EAAC,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAK7D;;;GAGG;AACH,MAAM,OAAO,UAAW,SAAQ,aAAa;IAC3C,YAAY,OAAe,EAAE,UAA2B,EAAE;QACxD,KAAK,CAAC,OAAO,kBACX,IAAI,EAAE,iBAAiB,CAAC,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,EAC5D,IAAI,EAAE,iBAAiB,CAAC,SAAS,IAC9B,OAAO,EACV,CAAC;IACL,CAAC;CACF"}

package/dist/lib/esm/errors/validation.error.js

@@ -0,0 +1,11 @@
+import { ExitCode } from "./exit-code.enum";
+import { PristineError } from "./pristine.error";
+import { PristineErrorCode } from "./pristine-error-code.enum";
+import { PristineErrorKind } from "./pristine-error-kind.enum";
+/** 422. Input parsed but failed semantic validation. CLI exit `ExitCode.DataError` (65). */
+export class ValidationError extends PristineError {
+    constructor(message, options = {}) {
+        super(message, Object.assign({ code: PristineErrorCode.ValidationFailed, httpStatus: 422, exitCode: ExitCode.DataError, kind: PristineErrorKind.UserError }, options));
+    }
+}
+//# sourceMappingURL=validation.error.js.map

package/dist/lib/esm/errors/validation.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.error.js","sourceRoot":"","sources":["../../../../src/errors/validation.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,QAAQ,EAAC,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAC,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAK7D,4FAA4F;AAC5F,MAAM,OAAO,eAAgB,SAAQ,aAAa;IAChD,YAAY,OAAe,EAAE,UAA2B,EAAE;QACxD,KAAK,CAAC,OAAO,kBACX,IAAI,EAAE,iBAAiB,CAAC,gBAAgB,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,SAAS,EACvF,IAAI,EAAE,iBAAiB,CAAC,SAAS,IAC9B,OAAO,EACV,CAAC;IACL,CAAC;CACF"}

package/dist/lib/esm/managers/event-context.manager.js

@@ -53,6 +53,11 @@ let EventContextManager = EventContextManager_1 = class EventContextManager {
         var _a;
         return (_a = this.current()) === null || _a === void 0 ? void 0 : _a.container;
     }
+    /** Convenience: the `TracingManager` that owns this event's trace, or `undefined`. */
+    tracingManager() {
+        var _a;
+        return (_a = this.current()) === null || _a === void 0 ? void 0 : _a.tracingManager;
+    }
     /**
      * Returns a wrapped version of `fn` that restores the current context on call. Use
      * when you need to spawn work that escapes the natural async chain (e.g. a callback
@@ -88,6 +93,10 @@ let EventContextManager = EventContextManager_1 = class EventContextManager {
         var _a;
         return (_a = EventContextManager_1.current()) === null || _a === void 0 ? void 0 : _a.container;
     }
+    static tracingManager() {
+        var _a;
+        return (_a = EventContextManager_1.current()) === null || _a === void 0 ? void 0 : _a.tracingManager;
+    }
     static bind(fn) {
         const ctx = EventContextManager_1.current();
         if (ctx === undefined)

package/dist/lib/esm/managers/event-context.manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"event-context.manager.js","sourceRoot":"","sources":["../../../../src/managers/event-context.manager.ts"],"names":[],"mappings":";;;;;;;AAAA,OAAO,EAAC,iBAAiB,EAAC,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAsB,UAAU,EAAC,MAAM,UAAU,CAAC;AAGzD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEI,IAAM,mBAAmB,2BAAzB,MAAM,mBAAmB;IAU9B,GAAG,CAAI,GAAiB,EAAE,EAAwB;QAChD,OAAO,qBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED;iDAC6C;IAC7C,OAAO;QACL,OAAO,qBAAmB,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;IAC5C,CAAC;IAED,wEAAwE;IACxE,OAAO;;QACL,OAAO,MAAA,IAAI,CAAC,OAAO,EAAE,0CAAE,OAAO,CAAC;IACjC,CAAC;IAED,wEAAwE;IACxE,OAAO;;QACL,OAAO,MAAA,IAAI,CAAC,OAAO,EAAE,0CAAE,OAAO,CAAC;IACjC,CAAC;IAED,qEAAqE;IACrE,SAAS;;QACP,OAAO,MAAA,IAAI,CAAC,OAAO,EAAE,0CAAE,SAAS,CAAC;IACnC,CAAC;IAED;;;;;;;;OAQG;IACH,IAAI,CAAoC,EAAK;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAC3B,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,qBAAmB,CAAC,GAAG,CAAC;QACpC,OAAO,CAAC,CAAC,GAAG,IAAW,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAM,CAAC;IACpE,CAAC;IAED,kFAAkF;IAClF,+EAA+E;IAC/E,+EAA+E;IAC/E,uBAAuB;IAEvB,MAAM,CAAC,OAAO;QACZ,OAAO,qBAAmB,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;IAC5C,CAAC;IAED,MAAM,CAAC,OAAO;;QACZ,OAAO,MAAA,qBAAmB,CAAC,OAAO,EAAE,0CAAE,OAAO,CAAC;IAChD,CAAC;IAED,MAAM,CAAC,OAAO;;QACZ,OAAO,MAAA,qBAAmB,CAAC,OAAO,EAAE,0CAAE,OAAO,CAAC;IAChD,CAAC;IAED,MAAM,CAAC,SAAS;;QACd,OAAO,MAAA,qBAAmB,CAAC,OAAO,EAAE,0CAAE,SAAS,CAAC;IAClD,CAAC;IAED,MAAM,CAAC,IAAI,CAAoC,EAAK;QAClD,MAAM,GAAG,GAAG,qBAAmB,CAAC,OAAO,EAAE,CAAC;QAC1C,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,qBAAmB,CAAC,GAAG,CAAC;QACpC,OAAO,CAAC,CAAC,GAAG,IAAW,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAM,CAAC;IACpE,CAAC;;AA5EuB,uBAAG,GAAG,IAAI,iBAAiB,EAAgB,AAAxC,CAAyC;AADzD,mBAAmB;IAD/B,UAAU,EAAE;GACA,mBAAmB,CA8E/B"}
+{"version":3,"file":"event-context.manager.js","sourceRoot":"","sources":["../../../../src/managers/event-context.manager.ts"],"names":[],"mappings":";;;;;;;AAAA,OAAO,EAAC,iBAAiB,EAAC,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAsB,UAAU,EAAC,MAAM,UAAU,CAAC;AAIzD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEI,IAAM,mBAAmB,2BAAzB,MAAM,mBAAmB;IAU9B,GAAG,CAAI,GAAiB,EAAE,EAAwB;QAChD,OAAO,qBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED;iDAC6C;IAC7C,OAAO;QACL,OAAO,qBAAmB,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;IAC5C,CAAC;IAED,wEAAwE;IACxE,OAAO;;QACL,OAAO,MAAA,IAAI,CAAC,OAAO,EAAE,0CAAE,OAAO,CAAC;IACjC,CAAC;IAED,wEAAwE;IACxE,OAAO;;QACL,OAAO,MAAA,IAAI,CAAC,OAAO,EAAE,0CAAE,OAAO,CAAC;IACjC,CAAC;IAED,qEAAqE;IACrE,SAAS;;QACP,OAAO,MAAA,IAAI,CAAC,OAAO,EAAE,0CAAE,SAAS,CAAC;IACnC,CAAC;IAED,sFAAsF;IACtF,cAAc;;QACZ,OAAO,MAAA,IAAI,CAAC,OAAO,EAAE,0CAAE,cAAc,CAAC;IACxC,CAAC;IAED;;;;;;;;OAQG;IACH,IAAI,CAAoC,EAAK;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAC3B,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,qBAAmB,CAAC,GAAG,CAAC;QACpC,OAAO,CAAC,CAAC,GAAG,IAAW,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAM,CAAC;IACpE,CAAC;IAED,kFAAkF;IAClF,+EAA+E;IAC/E,+EAA+E;IAC/E,uBAAuB;IAEvB,MAAM,CAAC,OAAO;QACZ,OAAO,qBAAmB,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;IAC5C,CAAC;IAED,MAAM,CAAC,OAAO;;QACZ,OAAO,MAAA,qBAAmB,CAAC,OAAO,EAAE,0CAAE,OAAO,CAAC;IAChD,CAAC;IAED,MAAM,CAAC,OAAO;;QACZ,OAAO,MAAA,qBAAmB,CAAC,OAAO,EAAE,0CAAE,OAAO,CAAC;IAChD,CAAC;IAED,MAAM,CAAC,SAAS;;QACd,OAAO,MAAA,qBAAmB,CAAC,OAAO,EAAE,0CAAE,SAAS,CAAC;IAClD,CAAC;IAED,MAAM,CAAC,cAAc;;QACnB,OAAO,MAAA,qBAAmB,CAAC,OAAO,EAAE,0CAAE,cAAc,CAAC;IACvD,CAAC;IAED,MAAM,CAAC,IAAI,CAAoC,EAAK;QAClD,MAAM,GAAG,GAAG,qBAAmB,CAAC,OAAO,EAAE,CAAC;QAC1C,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,qBAAmB,CAAC,GAAG,CAAC;QACpC,OAAO,CAAC,CAAC,GAAG,IAAW,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAM,CAAC;IACpE,CAAC;;AArFuB,uBAAG,GAAG,IAAI,iBAAiB,EAAgB,AAAxC,CAAyC;AADzD,mBAAmB;IAD/B,UAAU,EAAE;GACA,mBAAmB,CAuF/B"}

package/dist/lib/esm/models/models.js

@@ -1,6 +1,7 @@
 export * from "./request";
 export * from "./response";
-export * from "./span-event.model";
+export * from "./span-lifecycle-owner.interface";
+export * from "./span-marker.model";
 export * from "./span.model";
 export * from "./trace.model";
 //# sourceMappingURL=models.js.map

package/dist/lib/esm/models/models.js.map

@@ -1 +1 @@
-{"version":3,"file":"models.js","sourceRoot":"","sources":["../../../../src/models/models.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC"}
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../../../../src/models/models.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,kCAAkC,CAAC;AACjD,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC"}

package/dist/lib/esm/models/span-lifecycle-owner.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=span-lifecycle-owner.interface.js.map

package/dist/lib/esm/models/span-lifecycle-owner.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-lifecycle-owner.interface.js","sourceRoot":"","sources":["../../../../src/models/span-lifecycle-owner.interface.ts"],"names":[],"mappings":""}

package/dist/lib/esm/models/span-marker.model.js

@@ -0,0 +1,30 @@
+/**
+ * A named, timestamped marker attached to a `Span`. Represents a noteworthy moment
+ * inside the span's lifetime that doesn't warrant a child span of its own — e.g.
+ * "validation passed", "rate limit check ok", "found 50 rows in DB".
+ *
+ * **Markers are instants, not durations.** They carry a single timestamp; they have no
+ * children and no end date. If you need hierarchical timing, spawn a child `Span`
+ * instead — that gives you start/end semantics and its own marker list.
+ *
+ * Modeled after OpenTelemetry's "span events" concept (we renamed `event` → `marker`
+ * here because `Event` is heavily overloaded in Pristine's dispatched-event domain —
+ * `Event<T>`, `EventHandler`, `EventPipeline`, `EventDispatcher`, etc.). A `Span` carries
+ * `markers: SpanMarker[]` alongside its `children: Span[]`. Renderers interleave markers
+ * with child spans by timestamp to produce a chronological trail of what happened.
+ *
+ * Use `TracingManager.addMarkerToCurrentSpan(message, attributes?)` to add one — it
+ * finds the most-recently-started in-progress span and attaches the marker there.
+ */
+export class SpanMarker {
+    constructor(message, attributes) {
+        this.message = message;
+        /**
+         * The timestamp in milliseconds at which the marker was created. Used to interleave
+         * markers with sibling spans when rendering a sorted trail.
+         */
+        this.timestamp = Date.now();
+        this.attributes = attributes;
+    }
+}
+//# sourceMappingURL=span-marker.model.js.map

package/dist/lib/esm/models/span-marker.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-marker.model.js","sourceRoot":"","sources":["../../../../src/models/span-marker.model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,UAAU;IAarB,YAA4B,OAAe,EAAE,UAAsC;QAAvD,YAAO,GAAP,OAAO,CAAQ;QAZ3C;;;WAGG;QACa,cAAS,GAAW,IAAI,CAAC,GAAG,EAAE,CAAC;QAS7C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF"}

package/dist/lib/esm/models/span.model.js

@@ -23,9 +23,12 @@ export class Span {
          * Named, timestamped markers attached to this span. Use these for noteworthy moments
          * inside the span's lifetime that don't warrant their own child span — e.g.
          * "validation passed", "found 50 rows in DB". Empty by default; populated by
-         * `TracingManager.addEventToCurrentSpan(...)`.
+         * `TracingManager.addMarkerToCurrentSpan(...)`.
+         *
+         * Markers are flat by design (instants, not durations). For hierarchical timing, use
+         * child spans.
          */
-        this.events = [];
+        this.markers = [];
         /**
          * The context associated with the span.
          */

package/dist/lib/esm/models/span.model.js.map

@@ -1 +1 @@
-{"version":3,"file":"span.model.js","sourceRoot":"","sources":["../../../../src/models/span.model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,QAAQ,CAAC;AAclC;;GAEG;AACH,MAAM,OAAO,IAAI;IAuDf;;;;;OAKG;IACH,YAA0B,OAAe,EAAE,EAAW,EAAE,OAAmC;QAAjE,YAAO,GAAP,OAAO,CAAQ;QA5CzC;;WAEG;QACI,cAAS,GAAW,IAAI,CAAC,GAAG,EAAE,CAAC;QAYtC;;WAEG;QACI,aAAQ,GAAW,EAAE,CAAC;QAE7B;;;;;WAKG;QACI,WAAM,GAAgB,EAAE,CAAC;QAEhC;;WAEG;QACI,YAAO,GAA8B,EAAE,CAAC;QAE/C;;WAEG;QACI,eAAU,GAAG,IAAI,CAAC;QASvB,IAAI,CAAC,EAAE,GAAG,EAAE,aAAF,EAAE,cAAF,EAAE,GAAI,UAAU,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,EAAE,CAAC;IAC/B,CAAC;IAED;;OAEG;IACI,WAAW;;QAChB,OAAO,CAAC,MAAA,IAAI,CAAC,OAAO,mCAAI,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;IACvD,CAAC;IAED;;OAEG;IACI,GAAG;;QACR,MAAA,IAAI,CAAC,cAAc,0CAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAED;;;OAGG;IACI,QAAQ,CAAC,KAAY;QAC1B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QAEnB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAChE,CAAC;IAED;;;OAGG;IACI,QAAQ,CAAC,IAAU;QACxB,MAAM,iBAAiB,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC;QAEpF,IAAI,iBAAiB,EAAE,CAAC;YACtB,OAAO;QACT,CAAC;QAED,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;CACF"}
+{"version":3,"file":"span.model.js","sourceRoot":"","sources":["../../../../src/models/span.model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,QAAQ,CAAC;AAKlC;;GAEG;AACH,MAAM,OAAO,IAAI;IA0Df;;;;;OAKG;IACH,YAA0B,OAAe,EAAE,EAAW,EAAE,OAAmC;QAAjE,YAAO,GAAP,OAAO,CAAQ;QA/CzC;;WAEG;QACI,cAAS,GAAW,IAAI,CAAC,GAAG,EAAE,CAAC;QAYtC;;WAEG;QACI,aAAQ,GAAW,EAAE,CAAC;QAE7B;;;;;;;;WAQG;QACI,YAAO,GAAiB,EAAE,CAAC;QAElC;;WAEG;QACI,YAAO,GAA8B,EAAE,CAAC;QAE/C;;WAEG;QACI,eAAU,GAAG,IAAI,CAAC;QASvB,IAAI,CAAC,EAAE,GAAG,EAAE,aAAF,EAAE,cAAF,EAAE,GAAI,UAAU,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,EAAE,CAAC;IAC/B,CAAC;IAED;;OAEG;IACI,WAAW;;QAChB,OAAO,CAAC,MAAA,IAAI,CAAC,OAAO,mCAAI,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;IACvD,CAAC;IAED;;OAEG;IACI,GAAG;;QACR,MAAA,IAAI,CAAC,cAAc,0CAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAED;;;OAGG;IACI,QAAQ,CAAC,KAAY;QAC1B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QAEnB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAChE,CAAC;IAED;;;OAGG;IACI,QAAQ,CAAC,IAAU;QACxB,MAAM,iBAAiB,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC;QAEpF,IAAI,iBAAiB,EAAE,CAAC;YACtB,OAAO;QACT,CAAC;QAED,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;CACF"}