@composed-di/core 0.5.3-alpha → 0.6.0-alpha

package/dist/serviceEventListener.d.ts

@@ -1,133 +0,0 @@
-import type { ServiceKey } from './serviceKey';
-/**
- * A handle representing a single in-flight operation (initialization,
- * disposal, or method call), returned by a ServiceEventListener when the
- * operation starts.
- *
- * `end` is invoked exactly once when the operation finishes, so
- * implementations can close over per-call state (a start time, a span
- * handle, a correlation id) without any bookkeeping to pair concurrent
- * start/finish events.
- */
-export interface EventSpan {
-    /**
-     * Optional wrapper around the operation itself. When present, the module
-     * invokes the operation as `run(() => operation())`, so the listener can
-     * establish ambient state that the operation body and its async
-     * continuations inherit — this is what lets spans of nested service
-     * calls form a parent-child hierarchy.
-     *
-     * Implementations must invoke `fn` exactly once, synchronously, and
-     * return its result unchanged (for async operations, the promise itself).
-     * `end` is still delivered separately when the operation finishes.
-     *
-     * @param fn - A thunk that performs the operation.
-     * @return The value returned by `fn`.
-     */
-    run?<T>(fn: () => T): T;
-    /**
-     * Invoked exactly once when the operation finishes, whether it succeeded
-     * or failed. For methods that return a promise, this fires when the
-     * promise settles, not when the method returns. On failure, the error is
-     * rethrown to the caller after this is invoked.
-     *
-     * Whether to retain or log the outcome is the implementation's choice;
-     * values are passed by reference, so implementations must not mutate them.
-     *
-     * @param outcome - How the operation finished, and its value or error.
-     * @return void
-     */
-    end?(outcome: EventOutcome): void;
-}
-/**
- * How an operation finished, delivered to EventSpan.end: `success` carries
- * the value produced by the operation (the return or resolved value for
- * method calls, the service instance for initialize, undefined for
- * dispose); `failure` carries the error that was thrown or rejected.
- */
-export type EventOutcome = {
-    type: 'success';
-    value: unknown;
-} | {
-    type: 'failure';
-    error: unknown;
-};
-/**
- * Context of a service initialization, delivered to onInitialize.
- * Future fields are added here rather than as extra parameters.
- */
-export interface InitializeContext {
-    /**
-     * The unique identifier of the service that is being initialized.
-     */
-    key: ServiceKey<unknown>;
-}
-/**
- * Context of a service disposal, delivered to onDispose.
- * Future fields are added here rather than as extra parameters.
- */
-export interface DisposeContext {
-    /**
-     * The unique identifier of the service that is being disposed.
-     */
-    key: ServiceKey<unknown>;
-}
-/**
- * Context of a method invocation, delivered to onMethodCall.
- * Future fields are added here rather than as extra parameters.
- */
-export interface MethodCallContext {
-    /**
-     * The unique identifier of the service the method belongs to.
-     */
-    key: ServiceKey<unknown>;
-    /**
-     * The name of the class implementing the service (the instance's
-     * constructor name), which may differ from `key.name`. Undefined for
-     * services that are not instances of a named class, such as plain
-     * object literals.
-     */
-    className?: string;
-    /**
-     * The name of the method that is being called.
-     */
-    functionName: string;
-    /**
-     * The arguments the method was invoked with, passed by reference;
-     * implementations must not mutate them.
-     */
-    args: readonly unknown[];
-}
-/**
- * Interface for listening to service events. Implement this interface to
- * observe lifecycle events and method calls of services in a module.
- *
- * Each method is invoked when the corresponding operation starts and may
- * return an EventSpan that is notified when that operation finishes.
- * Returning nothing opts out of completion tracking for that call.
- */
-export interface ServiceEventListener {
-    /**
-     * Invoked at the start of the initialization process for a specific service.
-     *
-     * @param context - Context of the initialization, including the service key.
-     * @return An EventSpan notified when initialization finishes, or void.
-     */
-    onInitialize?(context: InitializeContext): EventSpan | void;
-    /**
-     * Invoked when the disposal process for a service starts.
-     *
-     * @param context - Context of the disposal, including the service key.
-     * @return An EventSpan notified when disposal finishes, or void.
-     */
-    onDispose?(context: DisposeContext): EventSpan | void;
-    /**
-     * Invoked when a method call starts on a service instance.
-     *
-     * @param context - Context of the invocation, including the service key,
-     * the method name, and its arguments.
-     * @return An EventSpan notified when the call finishes, or void.
-     */
-    onMethodCall?(context: MethodCallContext): EventSpan | void;
-}
-//# sourceMappingURL=serviceEventListener.d.ts.map

package/dist/serviceEventListener.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"serviceEventListener.d.ts","sourceRoot":"","sources":["../src/serviceEventListener.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAExB;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GACtB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAE5E;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;IAEzB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI,CAAC;IAE5D;;;;;OAKG;IACH,SAAS,CAAC,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,CAAC;IAEtD;;;;;;OAMG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI,CAAC;CAC7D"}

package/dist/serviceEventListener.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=serviceEventListener.js.map

package/dist/serviceEventListener.js.map

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

package/dist/serviceModuleListener.d.ts

@@ -1,133 +0,0 @@
-import type { ServiceKey } from './serviceKey';
-/**
- * A handle representing a single in-flight operation (initialization,
- * disposal, or method call), returned by a ServiceEventListener when the
- * operation starts.
- *
- * `end` is invoked exactly once when the operation finishes, so
- * implementations can close over per-call state (a start time, a span
- * handle, a correlation id) without any bookkeeping to pair concurrent
- * start/finish events.
- */
-export interface EventSpan {
-    /**
-     * Optional wrapper around the operation itself. When present, the module
-     * invokes the operation as `run(() => operation())`, so the listener can
-     * establish ambient state that the operation body and its async
-     * continuations inherit — this is what lets spans of nested service
-     * calls form a parent-child hierarchy.
-     *
-     * Implementations must invoke `fn` exactly once, synchronously, and
-     * return its result unchanged (for async operations, the promise itself).
-     * `end` is still delivered separately when the operation finishes.
-     *
-     * @param fn - A thunk that performs the operation.
-     * @return The value returned by `fn`.
-     */
-    run?<T>(fn: () => T): T;
-    /**
-     * Invoked exactly once when the operation finishes, whether it succeeded
-     * or failed. For methods that return a promise, this fires when the
-     * promise settles, not when the method returns. On failure, the error is
-     * rethrown to the caller after this is invoked.
-     *
-     * Whether to retain or log the outcome is the implementation's choice;
-     * values are passed by reference, so implementations must not mutate them.
-     *
-     * @param outcome - How the operation finished, and its value or error.
-     * @return void
-     */
-    end?(outcome: EventOutcome): void;
-}
-/**
- * How an operation finished, delivered to EventSpan.end: `success` carries
- * the value produced by the operation (the return or resolved value for
- * method calls, the service instance for initialize, undefined for
- * dispose); `failure` carries the error that was thrown or rejected.
- */
-export type EventOutcome = {
-    type: 'success';
-    value: unknown;
-} | {
-    type: 'failure';
-    error: unknown;
-};
-/**
- * Context of a service initialization, delivered to onInitialize.
- * Future fields are added here rather than as extra parameters.
- */
-export interface InitializeContext {
-    /**
-     * The unique identifier of the service that is being initialized.
-     */
-    key: ServiceKey<unknown>;
-}
-/**
- * Context of a service disposal, delivered to onDispose.
- * Future fields are added here rather than as extra parameters.
- */
-export interface DisposeContext {
-    /**
-     * The unique identifier of the service that is being disposed.
-     */
-    key: ServiceKey<unknown>;
-}
-/**
- * Context of a method invocation, delivered to onMethodCall.
- * Future fields are added here rather than as extra parameters.
- */
-export interface MethodCallContext {
-    /**
-     * The unique identifier of the service the method belongs to.
-     */
-    key: ServiceKey<unknown>;
-    /**
-     * The name of the class implementing the service (the instance's
-     * constructor name), which may differ from `key.name`. Undefined for
-     * services that are not instances of a named class, such as plain
-     * object literals.
-     */
-    className?: string;
-    /**
-     * The name of the method that is being called.
-     */
-    functionName: string;
-    /**
-     * The arguments the method was invoked with, passed by reference;
-     * implementations must not mutate them.
-     */
-    args: readonly unknown[];
-}
-/**
- * Interface for listening to service events. Implement this interface to
- * observe lifecycle events and method calls of services in a module.
- *
- * Each method is invoked when the corresponding operation starts and may
- * return an EventSpan that is notified when that operation finishes.
- * Returning nothing opts out of completion tracking for that call.
- */
-export interface ServiceModuleListener {
-    /**
-     * Invoked at the start of the initialization process for a specific service.
-     *
-     * @param context - Context of the initialization, including the service key.
-     * @return An EventSpan notified when initialization finishes, or void.
-     */
-    onInitialize?(context: InitializeContext): EventSpan | void;
-    /**
-     * Invoked when the disposal process for a service starts.
-     *
-     * @param context - Context of the disposal, including the service key.
-     * @return An EventSpan notified when disposal finishes, or void.
-     */
-    onDispose?(context: DisposeContext): EventSpan | void;
-    /**
-     * Invoked when a method call starts on a service instance.
-     *
-     * @param context - Context of the invocation, including the service key,
-     * the method name, and its arguments.
-     * @return An EventSpan notified when the call finishes, or void.
-     */
-    onMethodCall?(context: MethodCallContext): EventSpan | void;
-}
-//# sourceMappingURL=serviceModuleListener.d.ts.map

package/dist/serviceModuleListener.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"serviceModuleListener.d.ts","sourceRoot":"","sources":["../src/serviceModuleListener.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAExB;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GACtB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAE5E;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;IAEzB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI,CAAC;IAE5D;;;;;OAKG;IACH,SAAS,CAAC,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,CAAC;IAEtD;;;;;;OAMG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI,CAAC;CAC7D"}

package/dist/serviceModuleListener.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=serviceModuleListener.js.map

package/dist/serviceModuleListener.js.map

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

package/src/redactingEventListener.ts

@@ -1,256 +0,0 @@
-import type {
-  DisposeContext,
-  EventOutcome,
-  EventSpan,
-  InitializeContext,
-  MethodCallContext,
-  ServiceModuleListener,
-} from './serviceModuleListener';
-import type { ServiceKey } from './serviceKey';
-
-/**
- * The placeholder that replaces a redacted value when no custom
- * transform is given for it.
- */
-export const REDACTED_VALUE = '[REDACTED]';
-
-/**
- * Custom masking for one included property, narrowed to the exact
- * method named when {@link RedactionRuleBuilder.redact} is called.
- * Omitting a side fully blanks it with {@link REDACTED_VALUE}; providing
- * one lets you report a partial mask instead (e.g. the last 4 digits of
- * a card number) — both always return a `string`, the masked
- * representation to report in place of the real value.
- */
-export type Mask<T, K extends Extract<keyof T, string>> = T[K] extends (
-  ...args: infer A
-) => infer R
-  ? {
-      maskArgs?: (...args: A) => string;
-      maskResult?: (result: R) => string;
-    }
-  : never;
-
-/**
- * Per-property override, layered on top of a rule's `redactAll` default.
- * `redacted: true` (from {@link RedactionRuleBuilder.redact}) redacts
- * that property, optionally with a custom mask; `redacted: false` (from
- * {@link RedactionRuleBuilder.exclude}) forces it to be left untouched
- * regardless of `redactAll`.
- */
-interface PropertyOverride {
-  redacted: boolean;
-  maskArgs?: (...args: any[]) => string;
-  maskResult?: (result: any) => string;
-}
-
-/**
- * Marks a service — or specific properties of it — as sensitive, so the
- * values flowing through its events are redacted. Returned by
- * {@link RedactionRuleBuilder.build}, which is the only way to construct
- * one — the `redactAll`/per-property merge logic lives entirely inside
- * `maskArgs`/`maskResult`, so callers never need to know how a rule
- * reached its decision, only what to do with it.
- */
-export interface RedactionRule<T> {
-  readonly key: ServiceKey<T>;
-
-  /**
-   * The args to report for a call to `functionName`: unchanged if not
-   * redacted, otherwise blanked or run through a custom `maskArgs`.
-   */
-  maskArgs(functionName: string, args: readonly unknown[]): readonly unknown[];
-
-  /**
-   * The value to report for a success outcome: unchanged if not
-   * redacted, otherwise blanked or run through a custom `maskResult`.
-   * Omit `functionName` to ask about the initialize result (the service
-   * instance itself), which only the rule's `redactAll` default touches.
-   */
-  maskResult(functionName: string | undefined, result: unknown): unknown;
-}
-
-/**
- * Fluent, single-key rule builder returned by {@link redactionRule}.
- * `redactAll`, `redact`, and `exclude` all merge into the same rule —
- * call them in any combination, in any order; the more specific
- * per-property calls (`redact`/`exclude`) always win over the blanket
- * `redactAll` default for the properties they name.
- *
- * @example
- * ```ts
- * const rules = [
- *   redactionRule(SecretClientKey)
- *     .redactAll()
- *     .build(), // whole service is sensitive
- *   redactionRule(BillingKey)
- *     .redactAll()
- *     .redact('chargeCard', { maskResult: (card) => `card ending in ${card.number.slice(-4)}` })
- *     .exclude('ping') // redact everything except this, with one custom mask
- *     .build(),
- *   redactionRule(VaultKey)
- *     .redact('getSecret')
- *     .build(), // only this call, nothing else
- * ];
- * ```
- */
-export class RedactionRuleBuilder<T> {
-  private redactAllFlag = false;
-  private readonly overrides: Record<string, PropertyOverride> = {};
-
-  constructor(private readonly key: ServiceKey<T>) {}
-
-  /** Redacts every property, plus the initialize result, by default. */
-  redactAll(): this {
-    this.redactAllFlag = true;
-    return this;
-  }
-
-  /**
-   * Marks one property (method) as redacted, with optional custom
-   * masking. Call repeatedly for several properties. Overrides
-   * `redactAll`/`exclude` for this specific property.
-   */
-  redact<K extends Extract<keyof T, string>>(name: K, mask?: Mask<T, K>): this {
-    this.overrides[name] = { redacted: true, ...mask };
-    return this;
-  }
-
-  /**
-   * Marks one or more properties as explicitly NOT redacted, overriding
-   * `redactAll` for just these.
-   */
-  exclude(...names: Extract<keyof T, string>[]): this {
-    for (const name of names) {
-      this.overrides[name] = { redacted: false };
-    }
-    return this;
-  }
-
-  build(): RedactionRule<any> {
-    if (!this.redactAllFlag && Object.keys(this.overrides).length === 0) {
-      throw new Error(
-        `redactionRule(${this.key.name}) has no effect: call .redactAll() and/or .redact(...) ` +
-          'before .build(), otherwise this rule never redacts anything.',
-      );
-    }
-
-    const redactAllFlag = this.redactAllFlag;
-    const overrides = this.overrides;
-
-    return {
-      key: this.key,
-      maskArgs(functionName, args) {
-        const override = overrides[functionName];
-        const redacted = override ? override.redacted : redactAllFlag;
-        if (!redacted) {
-          return args;
-        }
-        return override?.maskArgs
-          ? // A custom mask reports one string for the whole call,
-            // rather than a value per argument.
-            [override.maskArgs(...args)]
-          : // Replace each argument rather than the whole array, so the
-            // delegate still sees the call's arity.
-            args.map(() => REDACTED_VALUE);
-      },
-      maskResult(functionName, result) {
-        const override =
-          functionName === undefined ? undefined : overrides[functionName];
-        const redacted = override ? override.redacted : redactAllFlag;
-        if (!redacted) {
-          return result;
-        }
-        return override?.maskResult
-          ? override.maskResult(result)
-          : REDACTED_VALUE;
-      },
-    } as RedactionRule<any>;
-  }
-}
-
-export function redactionRule<T>(key: ServiceKey<T>): RedactionRuleBuilder<T> {
-  return new RedactionRuleBuilder(key);
-}
-
-/**
- * A ServiceEventListener decorator that redacts sensitive values before
- * they reach the wrapped listener. Works with any implementation via
- * delegation: arguments in MethodCallContext and success values in
- * EventOutcome are replaced (wholesale, or via a custom transform)
- * before the delegate ever sees them — whatever it captures or exports
- * is already scrubbed.
- *
- * Failure outcomes are passed through unchanged so error reporting keeps
- * working; keep secrets out of error messages at the throwing site.
- *
- * @example
- * ```ts
- * const listener = new RedactingEventListener(
- *   new OTELEventListener({ captureArguments: true, captureResults: true }),
- *   [
- *     redactionRule(SecretClientKey).redactAll().build(), // whole service is sensitive
- *     redactionRule(VaultKey).redact('getSecret').build(), // only this call
- *     redactionRule(HealthKey).redactAll().exclude('ping').build(), // everything but this call
- *   ],
- * );
- * ```
- */
-export class RedactingEventListener implements ServiceModuleListener {
-  constructor(
-    private readonly delegate: ServiceModuleListener,
-    private readonly rules: readonly RedactionRule<any>[],
-  ) {}
-
-  onInitialize(context: InitializeContext): EventSpan | void {
-    const rule = this.rules.find((r) => r.key === context.key);
-    return redactSpan(this.delegate.onInitialize?.(context), rule);
-  }
-
-  onDispose(context: DisposeContext): EventSpan | void {
-    // Dispose carries no arguments and no result value; nothing to redact.
-    return this.delegate.onDispose?.(context);
-  }
-
-  onMethodCall(context: MethodCallContext): EventSpan | void {
-    const rule = this.rules.find((r) => r.key === context.key);
-    const span = this.delegate.onMethodCall?.(
-      rule
-        ? {
-            ...context,
-            args: rule.maskArgs(context.functionName, context.args),
-          }
-        : context,
-    );
-    return redactSpan(span, rule, context.functionName);
-  }
-}
-
-/**
- * Wraps the delegate's EventSpan so success values are redacted before
- * `end` sees them, by delegating to the rule's `maskResult`. `run` (and
- * any future fields) pass through untouched. `functionName` is omitted
- * for the initialize result (the instance itself).
- */
-function redactSpan(
-  span: EventSpan | void,
-  rule: RedactionRule<any> | undefined,
-  functionName?: string,
-): EventSpan | void {
-  if (!rule || !span?.end) {
-    return span;
-  }
-  const end = span.end.bind(span);
-  return {
-    ...span,
-    end: (outcome: EventOutcome) =>
-      end(
-        outcome.type === 'success'
-          ? {
-              type: 'success',
-              value: rule.maskResult(functionName, outcome.value),
-            }
-          : outcome,
-      ),
-  };
-}

package/src/serviceModuleListener.ts

@@ -1,139 +0,0 @@
-import type { ServiceKey } from './serviceKey';
-
-/**
- * A handle representing a single in-flight operation (initialization,
- * disposal, or method call), returned by a ServiceEventListener when the
- * operation starts.
- *
- * `end` is invoked exactly once when the operation finishes, so
- * implementations can close over per-call state (a start time, a span
- * handle, a correlation id) without any bookkeeping to pair concurrent
- * start/finish events.
- */
-export interface EventSpan {
-  /**
-   * Optional wrapper around the operation itself. When present, the module
-   * invokes the operation as `run(() => operation())`, so the listener can
-   * establish ambient state that the operation body and its async
-   * continuations inherit — this is what lets spans of nested service
-   * calls form a parent-child hierarchy.
-   *
-   * Implementations must invoke `fn` exactly once, synchronously, and
-   * return its result unchanged (for async operations, the promise itself).
-   * `end` is still delivered separately when the operation finishes.
-   *
-   * @param fn - A thunk that performs the operation.
-   * @return The value returned by `fn`.
-   */
-  run?<T>(fn: () => T): T;
-
-  /**
-   * Invoked exactly once when the operation finishes, whether it succeeded
-   * or failed. For methods that return a promise, this fires when the
-   * promise settles, not when the method returns. On failure, the error is
-   * rethrown to the caller after this is invoked.
-   *
-   * Whether to retain or log the outcome is the implementation's choice;
-   * values are passed by reference, so implementations must not mutate them.
-   *
-   * @param outcome - How the operation finished, and its value or error.
-   * @return void
-   */
-  end?(outcome: EventOutcome): void;
-}
-
-/**
- * How an operation finished, delivered to EventSpan.end: `success` carries
- * the value produced by the operation (the return or resolved value for
- * method calls, the service instance for initialize, undefined for
- * dispose); `failure` carries the error that was thrown or rejected.
- */
-export type EventOutcome =
-  { type: 'success'; value: unknown } | { type: 'failure'; error: unknown };
-
-/**
- * Context of a service initialization, delivered to onInitialize.
- * Future fields are added here rather than as extra parameters.
- */
-export interface InitializeContext {
-  /**
-   * The unique identifier of the service that is being initialized.
-   */
-  key: ServiceKey<unknown>;
-}
-
-/**
- * Context of a service disposal, delivered to onDispose.
- * Future fields are added here rather than as extra parameters.
- */
-export interface DisposeContext {
-  /**
-   * The unique identifier of the service that is being disposed.
-   */
-  key: ServiceKey<unknown>;
-}
-
-/**
- * Context of a method invocation, delivered to onMethodCall.
- * Future fields are added here rather than as extra parameters.
- */
-export interface MethodCallContext {
-  /**
-   * The unique identifier of the service the method belongs to.
-   */
-  key: ServiceKey<unknown>;
-
-  /**
-   * The name of the class implementing the service (the instance's
-   * constructor name), which may differ from `key.name`. Undefined for
-   * services that are not instances of a named class, such as plain
-   * object literals.
-   */
-  className?: string;
-
-  /**
-   * The name of the method that is being called.
-   */
-  functionName: string;
-
-  /**
-   * The arguments the method was invoked with, passed by reference;
-   * implementations must not mutate them.
-   */
-  args: readonly unknown[];
-}
-
-/**
- * Interface for listening to service events. Implement this interface to
- * observe lifecycle events and method calls of services in a module.
- *
- * Each method is invoked when the corresponding operation starts and may
- * return an EventSpan that is notified when that operation finishes.
- * Returning nothing opts out of completion tracking for that call.
- */
-export interface ServiceModuleListener {
-  /**
-   * Invoked at the start of the initialization process for a specific service.
-   *
-   * @param context - Context of the initialization, including the service key.
-   * @return An EventSpan notified when initialization finishes, or void.
-   */
-  onInitialize?(context: InitializeContext): EventSpan | void;
-
-  /**
-   * Invoked when the disposal process for a service starts.
-   *
-   * @param context - Context of the disposal, including the service key.
-   * @return An EventSpan notified when disposal finishes, or void.
-   */
-  onDispose?(context: DisposeContext): EventSpan | void;
-
-  /**
-   * Invoked when a method call starts on a service instance.
-   *
-   * @param context - Context of the invocation, including the service key,
-   * the method name, and its arguments.
-   * @return An EventSpan notified when the call finishes, or void.
-   */
-  onMethodCall?(context: MethodCallContext): EventSpan | void;
-}