@pristine-ts/common 2.0.3 → 2.0.5

package/dist/types/contexts/event-context.d.ts

@@ -1,28 +1,43 @@
 import { DependencyContainer } from "tsyringe";
+import { TracingManagerInterface } from "../interfaces/tracing-manager.interface";
+import { Trace } from "../models/trace.model";
 /**
  * Per-event runtime state — the framework's correlation primitives plus a handle to
- * the per-event DI child container. Propagated implicitly via `AsyncLocalStorage`
- * (managed by `EventContextManager`) so downstream code doesn't have to thread these
- * fields through every method signature.
+ * the per-event DI child container and the active trace. Propagated implicitly via
+ * `AsyncLocalStorage` (managed by `EventContextManager`) so downstream code doesn't
+ * have to thread these fields through every method signature.
  *
  * **Not to be confused with `ExecutionContextInterface` (in `@pristine-ts/core`):**
  *   - `ExecutionContext` describes *where* the framework is running (AWS Lambda, CLI,
  *     Express, etc.) — set once per `kernel.handle()` call, immutable, host-shaped.
  *   - `EventContext` describes *which specific event* is being handled — set per event
- *     in the pipeline, mutable (`traceId` fills in once tracing starts), correlation-
- *     shaped.
+ *     in the pipeline, mutable (`traceId` / `trace` fill in once tracing starts),
+ *     correlation-shaped.
  *
  * One `kernel.handle()` call can produce multiple events (each event mapper can return
  * a list); each event gets its own `EventContext` instance.
  */
 export declare class EventContext {
     /** Unique id for this specific event. Same value the framework uses everywhere
-     *  else as the correlation/eventId (logging, breadcrumbs, file tracer filenames). */
+     *  else as the correlation/eventId (logging, file tracer filenames). */
     eventId: string;
     /** Trace id once tracing has started. Filled in by `TracingManager.startTracing`. */
     traceId?: string;
-    /** The per-event DI child container. Helpers (`@traced`, `runWithSpan(name, fn)`,
-     *  the LogHandler eventId fallback) reach through this to resolve event-scoped
-     *  services without callers having to inject them explicitly. */
+    /** The active `Trace` for this event. Single source of truth: every `TracingManager`
+     *  instance — whether resolved from the root container, a per-event child container,
+     *  or anywhere else — reads and writes spans through this reference. This is what
+     *  lets `addEventToCurrentSpan` from a controller find the same trace started in the
+     *  kernel, even though the TracingManager instances differ across containers. */
+    trace?: Trace;
+    /** The per-event DI child container. Helpers like the LogHandler eventId fallback
+     *  reach through this to resolve event-scoped services without callers having to
+     *  inject them explicitly. */
     container?: DependencyContainer;
+    /** The `TracingManager` that owns this event's trace. Set by the event pipeline
+     *  alongside `trace`, read by `@traced` so spans go through the manager that started
+     *  the trace rather than a fresh ContainerScoped instance from the child container.
+     *  Resolving `TracingManager` via the child container would create a new instance
+     *  (its lifecycle is ContainerScoped) whose `span.tracingManager = this` back-reference
+     *  points at the throwaway, not the manager that owns the trace. */
+    tracingManager?: TracingManagerInterface;
 }

package/dist/types/decorators/decorators.d.ts

@@ -1,3 +1,4 @@
 export * from './inject-config.decorator';
 export * from './module-scoped.decorator';
 export * from './tag.decorator';
+export * from './traced.decorator';

package/dist/types/decorators/traced.decorator.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Method decorator that wraps the decorated method in a span. The span is automatically
+ * ended when the method returns or throws, and the `TracingManager` is auto-resolved
+ * from the active `EventContext` — no need to inject it manually.
+ *
+ * ```ts
+ * class PaymentService {
+ *   @traced()                                // span name = "PaymentService.charge"
+ *   async charge(amount: number) { ... }
+ *
+ *   @traced("payment.refund.action")         // explicit name
+ *   async refund(chargeId: string) { ... }
+ * }
+ * ```
+ *
+ * **Behavior outside an event context.** When the decorated method runs without an
+ * active `EventContext` (e.g. a unit test calling the method directly, or background
+ * work that escaped the event lifecycle), the decorator is a no-op — the original
+ * method runs unchanged. Tracing must never throw or alter semantics.
+ *
+ * **Sync methods become async.** The decorator awaits the wrapped method internally,
+ * so any decorated method returns a `Promise`. Decorating a sync method changes its
+ * signature visible to callers — apply `@traced` to methods you'd already be awaiting
+ * (DB calls, HTTP, expensive computations), not to tight sync helpers.
+ *
+ * **Type-level caveat.** TypeScript's parameter and method decorator types don't carry
+ * enough information for the compiler to verify that the wrapped method's return type
+ * is compatible with `Promise<T>`. The wrapper is type-safe at runtime; the call site's
+ * static types are unchanged. Pair with explicit `: Promise<T>` annotations on the
+ * method when you want the static type to match what's actually returned.
+ *
+ * **Lives in `@pristine-ts/common`** so any package can use it without taking a direct
+ * dep on `@pristine-ts/telemetry`. The actual `TracingManager` implementation still
+ * lives in telemetry; this decorator only reads the active manager from the
+ * EventContext when one is present.
+ *
+ * @param spanName Optional explicit name for the span. Defaults to
+ *   `${ClassName}.${methodName}`.
+ */
+export declare function traced(spanName?: string): MethodDecorator;

package/dist/types/enums/enums.d.ts

@@ -2,3 +2,4 @@ export * from "./http-method.enum";
 export * from "./internal-container-parameter.enum";
 export * from "./metadata.enum";
 export * from "./service-definition-tag.enum";
+export * from "./span-keyname.enum";

package/dist/types/enums/span-keyname.enum.d.ts

@@ -0,0 +1,29 @@
+/**
+ * This enum is for the different span names that are integrated in Pristine.
+ */
+export declare enum SpanKeynameEnum {
+    ChildContainerCreation = "child.container.creation",
+    ChildContainerRegistration = "child.container.registration",
+    ConfigurationInitialization = "configuration.initialization",
+    ErrorResponseInterceptors = "error.response.interceptors",
+    EventDispatcherResolver = "event.dispatcher.resolver",
+    EventExecution = "event.execution",
+    EventInitialization = "event.initialization",
+    EventPreMappingInterception = "event.pre-mapping.interception",
+    EventPostMappingInterception = "event.post-mapping.interception",
+    EventPreResponseMappingInterception = "event.pre-response-mapping.interception",
+    EventPostResponseMappingInterception = "event.post-response-mapping.interception",
+    EventMapping = "event.mapping",
+    KernelInitialization = "kernel.initialization",
+    ModuleInitialization = "module.initialization",
+    ModuleInitializationImportModules = "module.initialization.import.modules",
+    RequestExecution = "request.execution",
+    RequestInterceptors = "request.interceptors",
+    ResponseInterceptors = "response.interceptors",
+    RootExecution = "root.execution",
+    RouterControllerResolver = "router.controller.resolver",
+    RouterFindMethodRouterNode = "router.find.method.router.node",
+    RouterRequestAuthentication = "router.request.authentication",
+    RouterRequestExecution = "router.request.execution",
+    RouterSetup = "router.setup"
+}

package/dist/types/errors/bad-request.error.d.ts

@@ -0,0 +1,8 @@
+import { PristineError } from "./pristine.error";
+import { PristineErrorOptions } from "./pristine-error-options.interface";
+type StandardOptions = Omit<PristineErrorOptions, "httpStatus" | "exitCode" | "kind">;
+/** 400. Caller sent malformed/invalid input. CLI exit `ExitCode.DataError` (65). */
+export declare class BadRequestError extends PristineError {
+    constructor(message: string, options?: StandardOptions);
+}
+export {};

package/dist/types/errors/config.error.d.ts

@@ -0,0 +1,13 @@
+import { PristineError } from "./pristine.error";
+import { PristineErrorOptions } from "./pristine-error-options.interface";
+type StandardOptions = Omit<PristineErrorOptions, "httpStatus" | "exitCode" | "kind">;
+/**
+ * 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 declare class ConfigError extends PristineError {
+    constructor(message: string, options?: StandardOptions);
+}
+export {};

package/dist/types/errors/conflict.error.d.ts

@@ -0,0 +1,8 @@
+import { PristineError } from "./pristine.error";
+import { PristineErrorOptions } from "./pristine-error-options.interface";
+type StandardOptions = Omit<PristineErrorOptions, "httpStatus" | "exitCode" | "kind">;
+/** 409. Operation conflicts with existing state (duplicate, version mismatch, etc.). */
+export declare class ConflictError extends PristineError {
+    constructor(message: string, options?: StandardOptions);
+}
+export {};

package/dist/types/errors/errors.d.ts

@@ -1 +1,14 @@
-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";

package/dist/types/errors/exit-code.enum.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 declare enum ExitCode {
+    /** Successful termination. */
+    Success = 0,
+    /** Generic error. Default fallback for user-facing errors that don't specify a code. */
+    Error = 1,
+    /** Command-line usage error (`EX_USAGE`). Bad flags, missing required args, unknown commands. */
+    Usage = 64,
+    /** Input data malformed (`EX_DATAERR`). Validation failed, body unparseable. */
+    DataError = 65,
+    /** Internal software error (`EX_SOFTWARE`). Default fallback for system errors. */
+    Software = 70,
+    /** Can't create user output file (`EX_CANTCREAT`). */
+    Cantcreat = 73,
+    /** Input/output error (`EX_IOERR`). */
+    IoError = 74,
+    /** Temporary failure, retry might succeed (`EX_TEMPFAIL`). */
+    Temporary = 75,
+    /** Remote error in protocol (`EX_PROTOCOL`). */
+    Protocol = 76,
+    /** Permission denied (`EX_NOPERM`). Authentication / authorization failures. */
+    NoPermission = 77,
+    /** Configuration error (`EX_CONFIG`). Missing or invalid config. */
+    Configuration = 78
+}

package/dist/types/errors/forbidden.error.d.ts

@@ -0,0 +1,8 @@
+import { PristineError } from "./pristine.error";
+import { PristineErrorOptions } from "./pristine-error-options.interface";
+type StandardOptions = Omit<PristineErrorOptions, "httpStatus" | "exitCode" | "kind">;
+/** 403. Caller is authenticated but lacks permission. CLI exit `ExitCode.NoPermission` (77). */
+export declare class ForbiddenError extends PristineError {
+    constructor(message?: string, options?: StandardOptions);
+}
+export {};

package/dist/types/errors/internal.error.d.ts

@@ -0,0 +1,12 @@
+import { PristineError } from "./pristine.error";
+import { PristineErrorOptions } from "./pristine-error-options.interface";
+type StandardOptions = Omit<PristineErrorOptions, "httpStatus" | "exitCode" | "kind">;
+/**
+ * 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 declare class InternalError extends PristineError {
+    constructor(message?: string, options?: StandardOptions);
+}
+export {};

package/dist/types/errors/not-found.error.d.ts

@@ -0,0 +1,8 @@
+import { PristineError } from "./pristine.error";
+import { PristineErrorOptions } from "./pristine-error-options.interface";
+type StandardOptions = Omit<PristineErrorOptions, "httpStatus" | "exitCode" | "kind">;
+/** 404. Resource doesn't exist. CLI exit `ExitCode.Error` (1). */
+export declare class NotFoundError extends PristineError {
+    constructor(message: string, options?: StandardOptions);
+}
+export {};

package/dist/types/errors/pristine-error-code.enum.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 declare enum PristineErrorCode {
+    BadRequest = "BAD_REQUEST",
+    Unauthorized = "UNAUTHORIZED",
+    Forbidden = "FORBIDDEN",
+    NotFound = "NOT_FOUND",
+    Conflict = "CONFLICT",
+    ValidationFailed = "VALIDATION_FAILED",
+    ConfigError = "CONFIG_ERROR",
+    UsageError = "USAGE_ERROR",
+    InternalError = "INTERNAL_ERROR"
+}

package/dist/types/errors/pristine-error-kind.enum.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 declare enum PristineErrorKind {
+    UserError = "user-error",
+    SystemError = "system-error"
+}

package/dist/types/errors/pristine-error-options.interface.d.ts

@@ -0,0 +1,59 @@
+import { ExitCode } from "./exit-code.enum";
+import { PristineErrorCode } from "./pristine-error-code.enum";
+import { PristineErrorKind } from "./pristine-error-kind.enum";
+/**
+ * Options carried by every `PristineError`. All fields optional — defaults give a sensible
+ * "user error with 500 / exit 1" shape when none are set.
+ */
+export interface PristineErrorOptions {
+    /**
+     * Stable slug for the error category. Surfaces in HTTP response bodies and CLI stderr;
+     * safe to use as the join key for i18n, log queries, and alerting rules.
+     *
+     * Accepts the framework's `PristineErrorCode` enum for standard categories, or any
+     * `SCREAMING_SNAKE_CASE` string for domain-specific codes (`"TOKEN_EXPIRED"`,
+     * `"STRIPE_CARD_DECLINED"`). The enum is the catalog of well-known codes; strings are
+     * the extensibility hatch.
+     *
+     * Defaults to `PristineErrorCode.InternalError` at render time when absent.
+     */
+    code?: PristineErrorCode | string;
+    /**
+     * HTTP status when this error reaches the HTTP boundary. Omit when the error has no
+     * natural HTTP semantics (e.g. a CLI-only `ConfigError`) — the responder will fall back
+     * to 500.
+     */
+    httpStatus?: number;
+    /**
+     * Process exit code when this error reaches the CLI boundary. Accepts the framework's
+     * `ExitCode` enum (sysexits.h-aligned) or any raw number for custom codes. Omit to fall
+     * back to `ExitCode.Error` (1) for user errors and `ExitCode.Software` (70) for system
+     * errors.
+     */
+    exitCode?: ExitCode | number;
+    /**
+     * Underlying error this one wraps. Uses the standard `Error.cause` slot (Node 16.9+),
+     * so any tooling that knows the standard cause chain works automatically. Walked by
+     * `PristineError.from` to preserve the original error type when normalizing.
+     */
+    cause?: Error;
+    /**
+     * Structured fields safe to surface in the response body / stderr. Per-error-class
+     * schema — e.g. a `NotFoundError` may carry `{ resource, id }`. Surfaced to users
+     * only when `kind === UserError` (the default) or `mode === development`.
+     */
+    details?: Record<string, unknown>;
+    /**
+     * Categorizes the error by who caused it. Drives how the message is rendered in
+     * production mode:
+     *
+     * - `UserError` (default): caller did something wrong. Message surfaced verbatim;
+     *   details exposed; production responses include both.
+     *
+     * - `SystemError`: framework/system bug, not the caller's fault. Production responses
+     *   replace the message with a generic "Internal Server Error" / "Internal Error" and
+     *   omit details + stack. The raw error is still logged via the LogHandler for
+     *   operators. `PristineError.from` marks unknown throws as `SystemError`.
+     */
+    kind?: PristineErrorKind;
+}

package/dist/types/errors/pristine.error.d.ts

@@ -0,0 +1,78 @@
+import { PristineErrorOptions } from "./pristine-error-options.interface";
+/**
+ * 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 declare class PristineError extends Error {
+    readonly options: PristineErrorOptions;
+    constructor(message: string, options?: PristineErrorOptions);
+    /**
+     * 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: unknown): PristineError;
+}

package/dist/types/errors/unauthorized.error.d.ts

@@ -0,0 +1,8 @@
+import { PristineError } from "./pristine.error";
+import { PristineErrorOptions } from "./pristine-error-options.interface";
+type StandardOptions = Omit<PristineErrorOptions, "httpStatus" | "exitCode" | "kind">;
+/** 401. Caller is not authenticated. CLI exit `ExitCode.NoPermission` (77). */
+export declare class UnauthorizedError extends PristineError {
+    constructor(message?: string, options?: StandardOptions);
+}
+export {};

package/dist/types/errors/usage.error.d.ts

@@ -0,0 +1,11 @@
+import { PristineError } from "./pristine.error";
+import { PristineErrorOptions } from "./pristine-error-options.interface";
+type StandardOptions = Omit<PristineErrorOptions, "httpStatus" | "exitCode" | "kind">;
+/**
+ * CLI-only — bad command-line usage (wrong flag, missing required arg, unknown command).
+ * No `httpStatus`. CLI exit `ExitCode.Usage` (64).
+ */
+export declare class UsageError extends PristineError {
+    constructor(message: string, options?: StandardOptions);
+}
+export {};

package/dist/types/errors/validation.error.d.ts

@@ -0,0 +1,8 @@
+import { PristineError } from "./pristine.error";
+import { PristineErrorOptions } from "./pristine-error-options.interface";
+type StandardOptions = Omit<PristineErrorOptions, "httpStatus" | "exitCode" | "kind">;
+/** 422. Input parsed but failed semantic validation. CLI exit `ExitCode.DataError` (65). */
+export declare class ValidationError extends PristineError {
+    constructor(message: string, options?: StandardOptions);
+}
+export {};

package/dist/types/interfaces/interfaces.d.ts

@@ -9,4 +9,5 @@ export * from "./module-scoped-registration.interface";
 export * from "./resolver.interface";
 export * from "./tagged-registration.interface";
 export * from "./token-provider-registration.interface";
+export * from "./tracing-manager.interface";
 export * from "./value-provider-registration.interface";

package/dist/types/interfaces/module.interface.d.ts

@@ -25,6 +25,32 @@ export interface ModuleInterface {
      * for the module.
      */
     configurationDefinitions?: ConfigurationDefinition[];
+    /**
+     * Default values this module wants applied to configuration keys — typically keys owned
+     * by **other** modules. Use it when a context-providing module (e.g. `CliModule`) has an
+     * opinion about how a dependency-module's keys should be configured by default.
+     *
+     * Precedence in the resolution chain:
+     *   1. Explicit overrides passed to `kernel.start()` — beats this.
+     *   2. `pristine.config.ts:config` block — beats this.
+     *   3. **`configDefaults`** (this field).
+     *   4. The owning `configurationDefinition.defaultResolvers` chain — loses to this.
+     *   5. The owning `configurationDefinition.defaultValue` — loses to this.
+     *
+     * Not to be confused with `configurationDefinition.defaultValue`: that's the
+     * owning-module's hard fallback when nothing else fires; `configDefaults` is a
+     * different module expressing a preferred value above the resolver chain.
+     *
+     * Validation:
+     *   - **Unknown key** (not declared by any module's `configurationDefinitions` in the
+     *     graph) → kernel throws at boot, naming the source module + key.
+     *   - **Two modules disagree** on the same key's `configDefaults` → kernel throws at
+     *     registration time, naming both module keynames.
+     *
+     * Keys are configuration parameter names (e.g. `"pristine.logging.consoleLoggerOutputMode"`),
+     * not arbitrary strings.
+     */
+    configDefaults?: Record<string, unknown>;
     /**
      * This function lets you run code on the module initialization. Be careful the tags and the router are not created yet.
      * @param container

package/dist/types/interfaces/tracing-manager.interface.d.ts

@@ -0,0 +1,78 @@
+import { Span } from "../models/span.model";
+import { Trace } from "../models/trace.model";
+/**
+ * This interface specifies what a tracing manager should implement.
+ *
+ * Lives in `@pristine-ts/common` so any package can declare a `TracingManagerInterface`
+ * dependency or use the `@traced` decorator without taking a direct dep on
+ * `@pristine-ts/telemetry`. The concrete implementation (`TracingManager`, plus the
+ * tracers that consume traces) still lives in telemetry.
+ */
+export interface TracingManagerInterface {
+    /**
+     * This property contains a reference to the active trace.
+     */
+    trace?: Trace;
+    /**
+     * This methods starts the Tracing. This should be the first method called before doing anything else.
+     * @param spanRootKeyname The keyname of the span at the root.
+     * @param traceId The trace id if there is one.
+     * @param context The context if there is one.
+     */
+    startTracing(spanRootKeyname?: string, traceId?: string, context?: {
+        [key: string]: string;
+    }): Span;
+    /**
+     * This method ends the trace entirely.
+     */
+    endTrace(): void;
+    /**
+     * This method starts a new span.
+     * @param keyname The keyname for this new span.
+     * @param parentKeyname The keyname of the parent span.
+     * @param parentId The id of the parent span.
+     * @param context The context if there is one.
+     */
+    startSpan(keyname: string, parentKeyname?: string, parentId?: string, context?: {
+        [key: string]: string;
+    }): Span;
+    /**
+     * This methods adds an already created Span to the trace. It assumes that it its hierarchy is correct.
+     * @param span The span to add.
+     */
+    addSpan(span: Span): Span;
+    /**
+     * This methods ends the span by setting the end date and by calling the tracers.
+     * It will also end the trace if the rootspan is being ended.
+     * @param span The span to end.
+     */
+    endSpan(span: Span): void;
+    /**
+     * This method ends the span using a keyname.
+     * @param keyname The keyname of the span to end.
+     */
+    endSpanKeyname(keyname: string): void;
+    /**
+     * Attaches a named, timestamped event to the most-recently-started in-progress span.
+     * Use for noteworthy moments inside a span's lifetime that don't warrant their own
+     * child span — "validation passed", "found 50 rows", etc. Logs a warning and drops
+     * the marker if no span is currently active.
+     */
+    addEventToCurrentSpan(message: string, attributes?: {
+        [key: string]: string;
+    }): void;
+    /**
+     * Returns the active trace's spans + their events as a flat, timestamp-sorted list.
+     * Public utility for custom tracers, debug endpoints, test helpers, or any consumer
+     * who wants "the active trace as a flat list" without walking the span tree manually.
+     * Returns an empty array when no active trace exists.
+     */
+    getCurrentTrail(): Array<{
+        kind: "span" | "event";
+        name: string;
+        date: Date;
+        attributes: {
+            [key: string]: string;
+        };
+    }>;
+}

package/dist/types/managers/event-context.manager.d.ts

@@ -1,5 +1,6 @@
 import { DependencyContainer } from "tsyringe";
 import { EventContext } from "../contexts/event-context";
+import { TracingManagerInterface } from "../interfaces/tracing-manager.interface";
 /**
  * Owns the `AsyncLocalStorage` instance that propagates the active `EventContext`
  * across `await` boundaries, `Promise.all`, `setImmediate`, and the rest of Node's
@@ -40,6 +41,8 @@ export declare class EventContextManager {
     traceId(): string | undefined;
     /** Convenience: the per-event DI child container, or `undefined`. */
     container(): DependencyContainer | undefined;
+    /** Convenience: the `TracingManager` that owns this event's trace, or `undefined`. */
+    tracingManager(): TracingManagerInterface | undefined;
     /**
      * 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
@@ -54,5 +57,6 @@ export declare class EventContextManager {
     static eventId(): string | undefined;
     static traceId(): string | undefined;
     static container(): DependencyContainer | undefined;
+    static tracingManager(): TracingManagerInterface | undefined;
     static bind<F extends (...args: any[]) => any>(fn: F): F;
 }

package/dist/types/models/models.d.ts

@@ -1,2 +1,6 @@
 export * from "./request";
 export * from "./response";
+export * from "./span-event.model";
+export * from "./span-lifecycle-owner.interface";
+export * from "./span.model";
+export * from "./trace.model";