@btravstack/core 0.9.0 → 0.10.0

package/dist/index.cjs

@@ -61,6 +61,50 @@ const runHealthChecks = (checks) => (0, unthrown.allAsync)(checks.map((health) =
 	components
 }));
 //#endregion
+//#region src/observation.ts
+/**
+* The set port a starter contributes its observability to, and reads whole.
+*
+* **Called at the START and answering a finisher**, rather than told about a
+* finished operation. That is what lets an observer open a span before the work
+* and end it after — a span reconstructed afterwards from a duration is not the
+* parent of anything that ran inside it.
+*
+* A set port rather than a `Meter` in every starter's `needs`: an observer
+* package an application never composed contributes nothing, and a starter
+* costs a graph no ports to have observability available. That is the
+* difference between "instrumented by default" and "instrumented if you asked
+* for observability", and only the second is free.
+*
+* **A module that reads this port contributes a no-op member of its own**, the
+* way `otel()` does for `Instrumentations`: a collector depending on a set port
+* NOTHING provides is an unmet dependency, at plan time and in `Needs` alike.
+* Several no-ops in one graph cost a call each and nothing else.
+*/
+var Observers = class extends _btravstack_di.Port.many("Observers") {};
+/** The no-op member every reader of {@link Observers} contributes, so the set is never empty. */
+const noObserver = () => () => {};
+/**
+* Run every observer around one operation, and hand back the one finisher that
+* settles them all.
+*
+* Observers are started in order and settled in order, and the finisher is
+* **guarded**: a second call is dropped. "Called exactly once" is therefore a
+* property of this function rather than a rule each starter re-keeps — which
+* matters because the settling call sites are error paths, where a `tap` and a
+* `tapFailure` on the same chain, or a retry, is exactly the shape that fires
+* twice and doubles a failure count.
+*/
+const observe = (observers, operation) => {
+	const settlers = observers.map((observer) => observer(operation));
+	let done = false;
+	return (settled) => {
+		if (done) return;
+		done = true;
+		for (const settle of settlers) settle(settled);
+	};
+};
+//#endregion
 //#region src/clock.ts
 const systemClock = {
 	now: () => Date.now(),
@@ -652,11 +696,14 @@ exports.Instrumentations = Instrumentations;
 exports.LEVELS = LEVELS;
 exports.Logger = Logger;
 exports.Meter = Meter;
+exports.Observers = Observers;
 exports.RuntimePort = RuntimePort;
 exports.RuntimeStartFailed = RuntimeStartFailed;
 exports.SPAN_STATUS = SPAN_STATUS;
 exports.Tracer = Tracer;
 exports.currentUnit = currentUnit;
+exports.noObserver = noObserver;
+exports.observe = observe;
 exports.releasedBy = releasedBy;
 exports.runHealthChecks = runHealthChecks;
 exports.runMain = runMain;

package/dist/index.d.cts

@@ -83,6 +83,216 @@ type HealthReport = {
  */
 declare const runHealthChecks: (checks: readonly HealthCheck[]) => AsyncResult<HealthReport, never>;
 //#endregion
+//#region src/observability.d.ts
+/**
+ * The severity of one line, and the whole of the set: six levels, ordered, with
+ * no caller-defined additions — which is what lets `LOG_LEVEL` be validated at
+ * startup and `isEnabled` be a comparison rather than a lookup.
+ */
+type Level = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+/** The levels in order, least severe first — what `isEnabled` compares through. */
+declare const LEVELS: readonly Level[];
+/**
+ * What a line, a span or a measurement carries besides itself: a flat record of
+ * scalars.
+ *
+ * Flat and scalar on purpose. A nested object is where a field's name stops
+ * being stable, and an `unknown` value is where a logger starts stringifying
+ * whatever it is handed — which is how a log call becomes the thing that
+ * throws. A failure has a channel of its own, `cause`.
+ */
+type Attributes = Readonly<Record<string, string | number | boolean | undefined>>;
+/**
+ * Every method takes the same three arguments in the same order:
+ * `(message, attributes?, cause?)`.
+ *
+ * Uniform on purpose. A failure is not a property of severity — an `info` line
+ * reporting a recovered fault carries one too — so every level can take a
+ * `cause`, at the cost of `logger.error("boom", undefined, cause)` for a
+ * failure with nothing else to say.
+ */
+type LoggerService = {
+  readonly log: (level: Level, message: string, attributes?: Attributes, cause?: unknown) => void;
+  readonly trace: (message: string, attributes?: Attributes, cause?: unknown) => void;
+  readonly debug: (message: string, attributes?: Attributes, cause?: unknown) => void;
+  readonly info: (message: string, attributes?: Attributes, cause?: unknown) => void;
+  readonly warn: (message: string, attributes?: Attributes, cause?: unknown) => void;
+  /** `cause` is the failure itself — an `Error`, an `unthrown` `Err`'s error, a rejected value. */
+  readonly error: (message: string, attributes?: Attributes, cause?: unknown) => void;
+  readonly fatal: (message: string, attributes?: Attributes, cause?: unknown) => void;
+  /** A logger carrying `attributes` on every line it writes, on top of this one's. Never mutates this one. */
+  readonly with: (attributes: Attributes) => LoggerService;
+  /** Whether a line at `level` would be written — for a payload expensive enough to be worth not building. */
+  readonly isEnabled: (level: Level) => boolean;
+};
+declare const Logger_base: import("@btravstack/di").PortClass<"Logger">;
+/**
+ * The application's logger, as a port — declared here and implemented in
+ * `@btravstack/observability`, because a contract every package may depend on
+ * has to be reachable without installing an implementation, and because the
+ * correlation an implementation stamps per line is the kernel's own ambient
+ * record.
+ *
+ * An implementation must not throw: a logger that throws turns an observability
+ * problem into an outage. Synchronous `void`, not an `AsyncResult` — thesis 6's
+ * one deliberate exemption, since a lost line is not a modeled error.
+ */
+declare class Logger extends Logger_base<LoggerService> {}
+/** A span's outcome: unset until something says otherwise, then `ok` or `error`. */
+declare const SPAN_STATUS: {
+  readonly unset: 0;
+  readonly ok: 1;
+  readonly error: 2;
+};
+/** The three codes {@link SPAN_STATUS} names, as the type a {@link Span} takes. */
+type SpanStatusCode = (typeof SPAN_STATUS)[keyof typeof SPAN_STATUS];
+/**
+ * One span, narrowed to what a framework package does with it: label it, say
+ * how it ended, end it. The numbers are OpenTelemetry's own, so an OTel span
+ * satisfies this structurally with no translation in between.
+ */
+type Span = {
+  readonly setAttributes: (attributes: Attributes) => unknown;
+  readonly setStatus: (status: {
+    readonly code: SpanStatusCode;
+    readonly message?: string;
+  }) => unknown;
+  readonly end: () => void;
+};
+/** What a {@link Tracer} does: start a span, by name. */
+type TracerService = {
+  readonly startSpan: (name: string) => Span;
+};
+declare const Tracer_base: import("@btravstack/di").PortClass<"Tracer">;
+/**
+ * The application's tracer, as a port — declared without naming OpenTelemetry,
+ * because a port typed as a vendor's type points the dependency arrow outwards
+ * and makes the whole family install that vendor.
+ */
+declare class Tracer extends Tracer_base<TracerService> {}
+/** A monotonic count. */
+type Counter = {
+  readonly add: (value: number, attributes?: Attributes) => void;
+};
+/** A distribution of measurements. */
+type Histogram = {
+  readonly record: (value: number, attributes?: Attributes) => void;
+};
+/**
+ * What a {@link Meter} does: mint the two instruments a framework package needs
+ * — it counts what happened and measures how long it took. A gauge is something
+ * an application declares about its own domain, reaching the vendor's meter for
+ * it as it would any other adapter.
+ */
+type MeterService = {
+  readonly createCounter: (name: string, options?: {
+    readonly description?: string;
+    readonly unit?: string;
+  }) => Counter;
+  readonly createHistogram: (name: string, options?: {
+    readonly description?: string;
+    readonly unit?: string;
+  }) => Histogram;
+};
+declare const Meter_base: import("@btravstack/di").PortClass<"Meter">;
+/** The application's meter, as a port. See {@link Tracer} for why it does not name a vendor. */
+declare class Meter extends Meter_base<MeterService> {}
+//#endregion
+//#region src/observation.d.ts
+/**
+ * One operation worth observing, named before it runs.
+ *
+ * `component` is the starter's own word for itself — `"http"`, `"cache"`,
+ * `"amqp"` — and it is what lets an observer mint per-component instrument and
+ * span names without knowing anything about the component. `name` is the
+ * operation within it (`"get"`, `"unit"`), and `attributes` are the dimensions
+ * known before the call.
+ *
+ * The dimensions are the contributor's business and their **cardinality is its
+ * responsibility**: a request path or a workflow id here mints a time series
+ * per value, which is how a metrics bill becomes the incident.
+ */
+type Operation = {
+  readonly component: string;
+  readonly name: string;
+  /**
+   * The DIMENSIONS: bounded, and what a metrics observer may put on an
+   * instrument. A cache operation, an HTTP method, an activity type.
+   *
+   * Their cardinality is the contributor's responsibility — a request path or a
+   * cache key here mints a time series per value, which is how a metrics bill
+   * becomes the incident. That is what {@link Operation.details} is for.
+   */
+  readonly attributes: Attributes;
+  /**
+   * Unbounded context: a cache key, a mail subject, a URL. It rides spans and
+   * log lines, where one more field costs one more field — and **never a
+   * metric**, where it would cost a time series per value.
+   *
+   * The split is the whole reason an observer can be shared: without it every
+   * contributor would have to choose between a useful span and a safe metric.
+   */
+  readonly details?: Attributes;
+  /**
+   * Whether a tracing observer should open a span (default `true`).
+   *
+   * `false` is for a component whose spans already come from somewhere better:
+   * `@btravstack/prisma` says so because `@prisma/instrumentation` traces at the
+   * ENGINE level — the real SQL, the connection acquisition — all of it below
+   * what a client-level wrapper can see, so a second span would cost one more
+   * per query for strictly less information. Counting and timing still happen.
+   *
+   * Whether a span is worth opening is the CONTRIBUTOR's knowledge, which is
+   * why it rides the operation rather than being configured on the observer.
+   */
+  readonly traced?: boolean;
+};
+/** How an operation came out, plus whatever was only knowable at the end. */
+type Settled = {
+  readonly outcome: "ok" | "error";
+  /** Dimensions known only at the end, merged over the operation's own — an HTTP status, a cache hit or miss. */
+  readonly attributes?: Attributes;
+  /** The failure itself, for an observer that writes a line about it. */
+  readonly cause?: unknown;
+};
+/** What an observer answers: a finisher, called exactly once when the operation settles. */
+type Settle = (settled: Settled) => void;
+declare const Observers_base: import("@btravstack/di").ManyPortClass<"Observers">;
+/**
+ * The set port a starter contributes its observability to, and reads whole.
+ *
+ * **Called at the START and answering a finisher**, rather than told about a
+ * finished operation. That is what lets an observer open a span before the work
+ * and end it after — a span reconstructed afterwards from a duration is not the
+ * parent of anything that ran inside it.
+ *
+ * A set port rather than a `Meter` in every starter's `needs`: an observer
+ * package an application never composed contributes nothing, and a starter
+ * costs a graph no ports to have observability available. That is the
+ * difference between "instrumented by default" and "instrumented if you asked
+ * for observability", and only the second is free.
+ *
+ * **A module that reads this port contributes a no-op member of its own**, the
+ * way `otel()` does for `Instrumentations`: a collector depending on a set port
+ * NOTHING provides is an unmet dependency, at plan time and in `Needs` alike.
+ * Several no-ops in one graph cost a call each and nothing else.
+ */
+declare class Observers extends Observers_base<(operation: Operation) => Settle> {}
+/** The no-op member every reader of {@link Observers} contributes, so the set is never empty. */
+declare const noObserver: () => Settle;
+/**
+ * Run every observer around one operation, and hand back the one finisher that
+ * settles them all.
+ *
+ * Observers are started in order and settled in order, and the finisher is
+ * **guarded**: a second call is dropped. "Called exactly once" is therefore a
+ * property of this function rather than a rule each starter re-keeps — which
+ * matters because the settling call sites are error paths, where a `tap` and a
+ * `tapFailure` on the same chain, or a retry, is exactly the shape that fires
+ * twice and doubles a failure count.
+ */
+declare const observe: (observers: readonly ((operation: Operation) => Settle)[], operation: Operation) => Settle;
+//#endregion
 //#region src/clock.d.ts
 type Clock = {
   readonly now: () => number;
@@ -305,121 +515,6 @@ type KernelEvent = {
 type EventSink = (event: KernelEvent) => void;
 declare const stderrSink: EventSink;
 //#endregion
-//#region src/observability.d.ts
-/**
- * The severity of one line, and the whole of the set: six levels, ordered, with
- * no caller-defined additions — which is what lets `LOG_LEVEL` be validated at
- * startup and `isEnabled` be a comparison rather than a lookup.
- */
-type Level = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
-/** The levels in order, least severe first — what `isEnabled` compares through. */
-declare const LEVELS: readonly Level[];
-/**
- * What a line, a span or a measurement carries besides itself: a flat record of
- * scalars.
- *
- * Flat and scalar on purpose. A nested object is where a field's name stops
- * being stable, and an `unknown` value is where a logger starts stringifying
- * whatever it is handed — which is how a log call becomes the thing that
- * throws. A failure has a channel of its own, `cause`.
- */
-type Attributes = Readonly<Record<string, string | number | boolean | undefined>>;
-/**
- * Every method takes the same three arguments in the same order:
- * `(message, attributes?, cause?)`.
- *
- * Uniform on purpose. A failure is not a property of severity — an `info` line
- * reporting a recovered fault carries one too — so every level can take a
- * `cause`, at the cost of `logger.error("boom", undefined, cause)` for a
- * failure with nothing else to say.
- */
-type LoggerService = {
-  readonly log: (level: Level, message: string, attributes?: Attributes, cause?: unknown) => void;
-  readonly trace: (message: string, attributes?: Attributes, cause?: unknown) => void;
-  readonly debug: (message: string, attributes?: Attributes, cause?: unknown) => void;
-  readonly info: (message: string, attributes?: Attributes, cause?: unknown) => void;
-  readonly warn: (message: string, attributes?: Attributes, cause?: unknown) => void;
-  /** `cause` is the failure itself — an `Error`, an `unthrown` `Err`'s error, a rejected value. */
-  readonly error: (message: string, attributes?: Attributes, cause?: unknown) => void;
-  readonly fatal: (message: string, attributes?: Attributes, cause?: unknown) => void;
-  /** A logger carrying `attributes` on every line it writes, on top of this one's. Never mutates this one. */
-  readonly with: (attributes: Attributes) => LoggerService;
-  /** Whether a line at `level` would be written — for a payload expensive enough to be worth not building. */
-  readonly isEnabled: (level: Level) => boolean;
-};
-declare const Logger_base: import("@btravstack/di").PortClass<"Logger">;
-/**
- * The application's logger, as a port — declared here and implemented in
- * `@btravstack/observability`, because a contract every package may depend on
- * has to be reachable without installing an implementation, and because the
- * correlation an implementation stamps per line is the kernel's own ambient
- * record.
- *
- * An implementation must not throw: a logger that throws turns an observability
- * problem into an outage. Synchronous `void`, not an `AsyncResult` — thesis 6's
- * one deliberate exemption, since a lost line is not a modeled error.
- */
-declare class Logger extends Logger_base<LoggerService> {}
-/** A span's outcome: unset until something says otherwise, then `ok` or `error`. */
-declare const SPAN_STATUS: {
-  readonly unset: 0;
-  readonly ok: 1;
-  readonly error: 2;
-};
-/** The three codes {@link SPAN_STATUS} names, as the type a {@link Span} takes. */
-type SpanStatusCode = (typeof SPAN_STATUS)[keyof typeof SPAN_STATUS];
-/**
- * One span, narrowed to what a framework package does with it: label it, say
- * how it ended, end it. The numbers are OpenTelemetry's own, so an OTel span
- * satisfies this structurally with no translation in between.
- */
-type Span = {
-  readonly setAttributes: (attributes: Attributes) => unknown;
-  readonly setStatus: (status: {
-    readonly code: SpanStatusCode;
-    readonly message?: string;
-  }) => unknown;
-  readonly end: () => void;
-};
-/** What a {@link Tracer} does: start a span, by name. */
-type TracerService = {
-  readonly startSpan: (name: string) => Span;
-};
-declare const Tracer_base: import("@btravstack/di").PortClass<"Tracer">;
-/**
- * The application's tracer, as a port — declared without naming OpenTelemetry,
- * because a port typed as a vendor's type points the dependency arrow outwards
- * and makes the whole family install that vendor.
- */
-declare class Tracer extends Tracer_base<TracerService> {}
-/** A monotonic count. */
-type Counter = {
-  readonly add: (value: number, attributes?: Attributes) => void;
-};
-/** A distribution of measurements. */
-type Histogram = {
-  readonly record: (value: number, attributes?: Attributes) => void;
-};
-/**
- * What a {@link Meter} does: mint the two instruments a framework package needs
- * — it counts what happened and measures how long it took. A gauge is something
- * an application declares about its own domain, reaching the vendor's meter for
- * it as it would any other adapter.
- */
-type MeterService = {
-  readonly createCounter: (name: string, options?: {
-    readonly description?: string;
-    readonly unit?: string;
-  }) => Counter;
-  readonly createHistogram: (name: string, options?: {
-    readonly description?: string;
-    readonly unit?: string;
-  }) => Histogram;
-};
-declare const Meter_base: import("@btravstack/di").PortClass<"Meter">;
-/** The application's meter, as a port. See {@link Tracer} for why it does not name a vendor. */
-declare class Meter extends Meter_base<MeterService> {}
-//#endregion
 //#region src/phase.d.ts
 type Phase = "building" | "starting" | "serving" | "draining" | "stopping" | "exited";
 //#endregion
@@ -553,4 +648,4 @@ declare const start: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X,
  */
 declare const runMain: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X, E, Scope | Env> & StartGate<X, UnitNeeds>, options?: StartOptions<UnitX, UnitNeeds>, exit?: (code: number) => void) => Promise<void>;
 //#endregion
-export { type Attributes, type Clock, type ComponentHealth, type Counter, type DrainReport, type EventSink, type ExitReport, type HealthCheck, HealthCheckFailed, HealthChecks, type HealthReport, type Histogram, type InstrumentationLoader, Instrumentations, type KernelEvent, LEVELS, type Level, Logger, type LoggerService, Meter, type MeterService, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock };
+export { type Attributes, type Clock, type ComponentHealth, type Counter, type DrainReport, type EventSink, type ExitReport, type HealthCheck, HealthCheckFailed, HealthChecks, type HealthReport, type Histogram, type InstrumentationLoader, Instrumentations, type KernelEvent, LEVELS, type Level, Logger, type LoggerService, Meter, type MeterService, Observers, type Operation, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Settle, type Settled, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, noObserver, observe, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock };

package/dist/index.d.mts

@@ -83,6 +83,216 @@ type HealthReport = {
  */
 declare const runHealthChecks: (checks: readonly HealthCheck[]) => AsyncResult<HealthReport, never>;
 //#endregion
+//#region src/observability.d.ts
+/**
+ * The severity of one line, and the whole of the set: six levels, ordered, with
+ * no caller-defined additions — which is what lets `LOG_LEVEL` be validated at
+ * startup and `isEnabled` be a comparison rather than a lookup.
+ */
+type Level = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+/** The levels in order, least severe first — what `isEnabled` compares through. */
+declare const LEVELS: readonly Level[];
+/**
+ * What a line, a span or a measurement carries besides itself: a flat record of
+ * scalars.
+ *
+ * Flat and scalar on purpose. A nested object is where a field's name stops
+ * being stable, and an `unknown` value is where a logger starts stringifying
+ * whatever it is handed — which is how a log call becomes the thing that
+ * throws. A failure has a channel of its own, `cause`.
+ */
+type Attributes = Readonly<Record<string, string | number | boolean | undefined>>;
+/**
+ * Every method takes the same three arguments in the same order:
+ * `(message, attributes?, cause?)`.
+ *
+ * Uniform on purpose. A failure is not a property of severity — an `info` line
+ * reporting a recovered fault carries one too — so every level can take a
+ * `cause`, at the cost of `logger.error("boom", undefined, cause)` for a
+ * failure with nothing else to say.
+ */
+type LoggerService = {
+  readonly log: (level: Level, message: string, attributes?: Attributes, cause?: unknown) => void;
+  readonly trace: (message: string, attributes?: Attributes, cause?: unknown) => void;
+  readonly debug: (message: string, attributes?: Attributes, cause?: unknown) => void;
+  readonly info: (message: string, attributes?: Attributes, cause?: unknown) => void;
+  readonly warn: (message: string, attributes?: Attributes, cause?: unknown) => void;
+  /** `cause` is the failure itself — an `Error`, an `unthrown` `Err`'s error, a rejected value. */
+  readonly error: (message: string, attributes?: Attributes, cause?: unknown) => void;
+  readonly fatal: (message: string, attributes?: Attributes, cause?: unknown) => void;
+  /** A logger carrying `attributes` on every line it writes, on top of this one's. Never mutates this one. */
+  readonly with: (attributes: Attributes) => LoggerService;
+  /** Whether a line at `level` would be written — for a payload expensive enough to be worth not building. */
+  readonly isEnabled: (level: Level) => boolean;
+};
+declare const Logger_base: import("@btravstack/di").PortClass<"Logger">;
+/**
+ * The application's logger, as a port — declared here and implemented in
+ * `@btravstack/observability`, because a contract every package may depend on
+ * has to be reachable without installing an implementation, and because the
+ * correlation an implementation stamps per line is the kernel's own ambient
+ * record.
+ *
+ * An implementation must not throw: a logger that throws turns an observability
+ * problem into an outage. Synchronous `void`, not an `AsyncResult` — thesis 6's
+ * one deliberate exemption, since a lost line is not a modeled error.
+ */
+declare class Logger extends Logger_base<LoggerService> {}
+/** A span's outcome: unset until something says otherwise, then `ok` or `error`. */
+declare const SPAN_STATUS: {
+  readonly unset: 0;
+  readonly ok: 1;
+  readonly error: 2;
+};
+/** The three codes {@link SPAN_STATUS} names, as the type a {@link Span} takes. */
+type SpanStatusCode = (typeof SPAN_STATUS)[keyof typeof SPAN_STATUS];
+/**
+ * One span, narrowed to what a framework package does with it: label it, say
+ * how it ended, end it. The numbers are OpenTelemetry's own, so an OTel span
+ * satisfies this structurally with no translation in between.
+ */
+type Span = {
+  readonly setAttributes: (attributes: Attributes) => unknown;
+  readonly setStatus: (status: {
+    readonly code: SpanStatusCode;
+    readonly message?: string;
+  }) => unknown;
+  readonly end: () => void;
+};
+/** What a {@link Tracer} does: start a span, by name. */
+type TracerService = {
+  readonly startSpan: (name: string) => Span;
+};
+declare const Tracer_base: import("@btravstack/di").PortClass<"Tracer">;
+/**
+ * The application's tracer, as a port — declared without naming OpenTelemetry,
+ * because a port typed as a vendor's type points the dependency arrow outwards
+ * and makes the whole family install that vendor.
+ */
+declare class Tracer extends Tracer_base<TracerService> {}
+/** A monotonic count. */
+type Counter = {
+  readonly add: (value: number, attributes?: Attributes) => void;
+};
+/** A distribution of measurements. */
+type Histogram = {
+  readonly record: (value: number, attributes?: Attributes) => void;
+};
+/**
+ * What a {@link Meter} does: mint the two instruments a framework package needs
+ * — it counts what happened and measures how long it took. A gauge is something
+ * an application declares about its own domain, reaching the vendor's meter for
+ * it as it would any other adapter.
+ */
+type MeterService = {
+  readonly createCounter: (name: string, options?: {
+    readonly description?: string;
+    readonly unit?: string;
+  }) => Counter;
+  readonly createHistogram: (name: string, options?: {
+    readonly description?: string;
+    readonly unit?: string;
+  }) => Histogram;
+};
+declare const Meter_base: import("@btravstack/di").PortClass<"Meter">;
+/** The application's meter, as a port. See {@link Tracer} for why it does not name a vendor. */
+declare class Meter extends Meter_base<MeterService> {}
+//#endregion
+//#region src/observation.d.ts
+/**
+ * One operation worth observing, named before it runs.
+ *
+ * `component` is the starter's own word for itself — `"http"`, `"cache"`,
+ * `"amqp"` — and it is what lets an observer mint per-component instrument and
+ * span names without knowing anything about the component. `name` is the
+ * operation within it (`"get"`, `"unit"`), and `attributes` are the dimensions
+ * known before the call.
+ *
+ * The dimensions are the contributor's business and their **cardinality is its
+ * responsibility**: a request path or a workflow id here mints a time series
+ * per value, which is how a metrics bill becomes the incident.
+ */
+type Operation = {
+  readonly component: string;
+  readonly name: string;
+  /**
+   * The DIMENSIONS: bounded, and what a metrics observer may put on an
+   * instrument. A cache operation, an HTTP method, an activity type.
+   *
+   * Their cardinality is the contributor's responsibility — a request path or a
+   * cache key here mints a time series per value, which is how a metrics bill
+   * becomes the incident. That is what {@link Operation.details} is for.
+   */
+  readonly attributes: Attributes;
+  /**
+   * Unbounded context: a cache key, a mail subject, a URL. It rides spans and
+   * log lines, where one more field costs one more field — and **never a
+   * metric**, where it would cost a time series per value.
+   *
+   * The split is the whole reason an observer can be shared: without it every
+   * contributor would have to choose between a useful span and a safe metric.
+   */
+  readonly details?: Attributes;
+  /**
+   * Whether a tracing observer should open a span (default `true`).
+   *
+   * `false` is for a component whose spans already come from somewhere better:
+   * `@btravstack/prisma` says so because `@prisma/instrumentation` traces at the
+   * ENGINE level — the real SQL, the connection acquisition — all of it below
+   * what a client-level wrapper can see, so a second span would cost one more
+   * per query for strictly less information. Counting and timing still happen.
+   *
+   * Whether a span is worth opening is the CONTRIBUTOR's knowledge, which is
+   * why it rides the operation rather than being configured on the observer.
+   */
+  readonly traced?: boolean;
+};
+/** How an operation came out, plus whatever was only knowable at the end. */
+type Settled = {
+  readonly outcome: "ok" | "error";
+  /** Dimensions known only at the end, merged over the operation's own — an HTTP status, a cache hit or miss. */
+  readonly attributes?: Attributes;
+  /** The failure itself, for an observer that writes a line about it. */
+  readonly cause?: unknown;
+};
+/** What an observer answers: a finisher, called exactly once when the operation settles. */
+type Settle = (settled: Settled) => void;
+declare const Observers_base: import("@btravstack/di").ManyPortClass<"Observers">;
+/**
+ * The set port a starter contributes its observability to, and reads whole.
+ *
+ * **Called at the START and answering a finisher**, rather than told about a
+ * finished operation. That is what lets an observer open a span before the work
+ * and end it after — a span reconstructed afterwards from a duration is not the
+ * parent of anything that ran inside it.
+ *
+ * A set port rather than a `Meter` in every starter's `needs`: an observer
+ * package an application never composed contributes nothing, and a starter
+ * costs a graph no ports to have observability available. That is the
+ * difference between "instrumented by default" and "instrumented if you asked
+ * for observability", and only the second is free.
+ *
+ * **A module that reads this port contributes a no-op member of its own**, the
+ * way `otel()` does for `Instrumentations`: a collector depending on a set port
+ * NOTHING provides is an unmet dependency, at plan time and in `Needs` alike.
+ * Several no-ops in one graph cost a call each and nothing else.
+ */
+declare class Observers extends Observers_base<(operation: Operation) => Settle> {}
+/** The no-op member every reader of {@link Observers} contributes, so the set is never empty. */
+declare const noObserver: () => Settle;
+/**
+ * Run every observer around one operation, and hand back the one finisher that
+ * settles them all.
+ *
+ * Observers are started in order and settled in order, and the finisher is
+ * **guarded**: a second call is dropped. "Called exactly once" is therefore a
+ * property of this function rather than a rule each starter re-keeps — which
+ * matters because the settling call sites are error paths, where a `tap` and a
+ * `tapFailure` on the same chain, or a retry, is exactly the shape that fires
+ * twice and doubles a failure count.
+ */
+declare const observe: (observers: readonly ((operation: Operation) => Settle)[], operation: Operation) => Settle;
+//#endregion
 //#region src/clock.d.ts
 type Clock = {
   readonly now: () => number;
@@ -305,121 +515,6 @@ type KernelEvent = {
 type EventSink = (event: KernelEvent) => void;
 declare const stderrSink: EventSink;
 //#endregion
-//#region src/observability.d.ts
-/**
- * The severity of one line, and the whole of the set: six levels, ordered, with
- * no caller-defined additions — which is what lets `LOG_LEVEL` be validated at
- * startup and `isEnabled` be a comparison rather than a lookup.
- */
-type Level = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
-/** The levels in order, least severe first — what `isEnabled` compares through. */
-declare const LEVELS: readonly Level[];
-/**
- * What a line, a span or a measurement carries besides itself: a flat record of
- * scalars.
- *
- * Flat and scalar on purpose. A nested object is where a field's name stops
- * being stable, and an `unknown` value is where a logger starts stringifying
- * whatever it is handed — which is how a log call becomes the thing that
- * throws. A failure has a channel of its own, `cause`.
- */
-type Attributes = Readonly<Record<string, string | number | boolean | undefined>>;
-/**
- * Every method takes the same three arguments in the same order:
- * `(message, attributes?, cause?)`.
- *
- * Uniform on purpose. A failure is not a property of severity — an `info` line
- * reporting a recovered fault carries one too — so every level can take a
- * `cause`, at the cost of `logger.error("boom", undefined, cause)` for a
- * failure with nothing else to say.
- */
-type LoggerService = {
-  readonly log: (level: Level, message: string, attributes?: Attributes, cause?: unknown) => void;
-  readonly trace: (message: string, attributes?: Attributes, cause?: unknown) => void;
-  readonly debug: (message: string, attributes?: Attributes, cause?: unknown) => void;
-  readonly info: (message: string, attributes?: Attributes, cause?: unknown) => void;
-  readonly warn: (message: string, attributes?: Attributes, cause?: unknown) => void;
-  /** `cause` is the failure itself — an `Error`, an `unthrown` `Err`'s error, a rejected value. */
-  readonly error: (message: string, attributes?: Attributes, cause?: unknown) => void;
-  readonly fatal: (message: string, attributes?: Attributes, cause?: unknown) => void;
-  /** A logger carrying `attributes` on every line it writes, on top of this one's. Never mutates this one. */
-  readonly with: (attributes: Attributes) => LoggerService;
-  /** Whether a line at `level` would be written — for a payload expensive enough to be worth not building. */
-  readonly isEnabled: (level: Level) => boolean;
-};
-declare const Logger_base: import("@btravstack/di").PortClass<"Logger">;
-/**
- * The application's logger, as a port — declared here and implemented in
- * `@btravstack/observability`, because a contract every package may depend on
- * has to be reachable without installing an implementation, and because the
- * correlation an implementation stamps per line is the kernel's own ambient
- * record.
- *
- * An implementation must not throw: a logger that throws turns an observability
- * problem into an outage. Synchronous `void`, not an `AsyncResult` — thesis 6's
- * one deliberate exemption, since a lost line is not a modeled error.
- */
-declare class Logger extends Logger_base<LoggerService> {}
-/** A span's outcome: unset until something says otherwise, then `ok` or `error`. */
-declare const SPAN_STATUS: {
-  readonly unset: 0;
-  readonly ok: 1;
-  readonly error: 2;
-};
-/** The three codes {@link SPAN_STATUS} names, as the type a {@link Span} takes. */
-type SpanStatusCode = (typeof SPAN_STATUS)[keyof typeof SPAN_STATUS];
-/**
- * One span, narrowed to what a framework package does with it: label it, say
- * how it ended, end it. The numbers are OpenTelemetry's own, so an OTel span
- * satisfies this structurally with no translation in between.
- */
-type Span = {
-  readonly setAttributes: (attributes: Attributes) => unknown;
-  readonly setStatus: (status: {
-    readonly code: SpanStatusCode;
-    readonly message?: string;
-  }) => unknown;
-  readonly end: () => void;
-};
-/** What a {@link Tracer} does: start a span, by name. */
-type TracerService = {
-  readonly startSpan: (name: string) => Span;
-};
-declare const Tracer_base: import("@btravstack/di").PortClass<"Tracer">;
-/**
- * The application's tracer, as a port — declared without naming OpenTelemetry,
- * because a port typed as a vendor's type points the dependency arrow outwards
- * and makes the whole family install that vendor.
- */
-declare class Tracer extends Tracer_base<TracerService> {}
-/** A monotonic count. */
-type Counter = {
-  readonly add: (value: number, attributes?: Attributes) => void;
-};
-/** A distribution of measurements. */
-type Histogram = {
-  readonly record: (value: number, attributes?: Attributes) => void;
-};
-/**
- * What a {@link Meter} does: mint the two instruments a framework package needs
- * — it counts what happened and measures how long it took. A gauge is something
- * an application declares about its own domain, reaching the vendor's meter for
- * it as it would any other adapter.
- */
-type MeterService = {
-  readonly createCounter: (name: string, options?: {
-    readonly description?: string;
-    readonly unit?: string;
-  }) => Counter;
-  readonly createHistogram: (name: string, options?: {
-    readonly description?: string;
-    readonly unit?: string;
-  }) => Histogram;
-};
-declare const Meter_base: import("@btravstack/di").PortClass<"Meter">;
-/** The application's meter, as a port. See {@link Tracer} for why it does not name a vendor. */
-declare class Meter extends Meter_base<MeterService> {}
-//#endregion
 //#region src/phase.d.ts
 type Phase = "building" | "starting" | "serving" | "draining" | "stopping" | "exited";
 //#endregion
@@ -553,4 +648,4 @@ declare const start: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X,
  */
 declare const runMain: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X, E, Scope | Env> & StartGate<X, UnitNeeds>, options?: StartOptions<UnitX, UnitNeeds>, exit?: (code: number) => void) => Promise<void>;
 //#endregion
-export { type Attributes, type Clock, type ComponentHealth, type Counter, type DrainReport, type EventSink, type ExitReport, type HealthCheck, HealthCheckFailed, HealthChecks, type HealthReport, type Histogram, type InstrumentationLoader, Instrumentations, type KernelEvent, LEVELS, type Level, Logger, type LoggerService, Meter, type MeterService, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock };
+export { type Attributes, type Clock, type ComponentHealth, type Counter, type DrainReport, type EventSink, type ExitReport, type HealthCheck, HealthCheckFailed, HealthChecks, type HealthReport, type Histogram, type InstrumentationLoader, Instrumentations, type KernelEvent, LEVELS, type Level, Logger, type LoggerService, Meter, type MeterService, Observers, type Operation, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Settle, type Settled, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, noObserver, observe, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock };

package/dist/index.mjs

@@ -60,6 +60,50 @@ const runHealthChecks = (checks) => allAsync(checks.map((health) => OkAsync().fl
 	components
 }));
 //#endregion
+//#region src/observation.ts
+/**
+* The set port a starter contributes its observability to, and reads whole.
+*
+* **Called at the START and answering a finisher**, rather than told about a
+* finished operation. That is what lets an observer open a span before the work
+* and end it after — a span reconstructed afterwards from a duration is not the
+* parent of anything that ran inside it.
+*
+* A set port rather than a `Meter` in every starter's `needs`: an observer
+* package an application never composed contributes nothing, and a starter
+* costs a graph no ports to have observability available. That is the
+* difference between "instrumented by default" and "instrumented if you asked
+* for observability", and only the second is free.
+*
+* **A module that reads this port contributes a no-op member of its own**, the
+* way `otel()` does for `Instrumentations`: a collector depending on a set port
+* NOTHING provides is an unmet dependency, at plan time and in `Needs` alike.
+* Several no-ops in one graph cost a call each and nothing else.
+*/
+var Observers = class extends Port.many("Observers") {};
+/** The no-op member every reader of {@link Observers} contributes, so the set is never empty. */
+const noObserver = () => () => {};
+/**
+* Run every observer around one operation, and hand back the one finisher that
+* settles them all.
+*
+* Observers are started in order and settled in order, and the finisher is
+* **guarded**: a second call is dropped. "Called exactly once" is therefore a
+* property of this function rather than a rule each starter re-keeps — which
+* matters because the settling call sites are error paths, where a `tap` and a
+* `tapFailure` on the same chain, or a retry, is exactly the shape that fires
+* twice and doubles a failure count.
+*/
+const observe = (observers, operation) => {
+	const settlers = observers.map((observer) => observer(operation));
+	let done = false;
+	return (settled) => {
+		if (done) return;
+		done = true;
+		for (const settle of settlers) settle(settled);
+	};
+};
+//#endregion
 //#region src/clock.ts
 const systemClock = {
 	now: () => Date.now(),
@@ -645,4 +689,4 @@ const runMain = async (module, options = {}, exit = (code) => {
 	await awaitExit(start(module, options), exit);
 };
 //#endregion
-export { HealthCheckFailed, HealthChecks, Instrumentations, LEVELS, Logger, Meter, RuntimePort, RuntimeStartFailed, SPAN_STATUS, Tracer, currentUnit, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock };
+export { HealthCheckFailed, HealthChecks, Instrumentations, LEVELS, Logger, Meter, Observers, RuntimePort, RuntimeStartFailed, SPAN_STATUS, Tracer, currentUnit, noObserver, observe, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/core",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "The application kernel: boot a di module into a running process, and stop it without losing work",
   "keywords": [
     "application",
@@ -53,13 +53,13 @@
     "typescript": "7.0.2",
     "unthrown": "5.7.0",
     "vitest": "4.1.11",
-    "@btravstack/config": "0.9.0",
-    "@btravstack/di": "0.9.0"
+    "@btravstack/config": "0.10.0",
+    "@btravstack/di": "0.10.0"
   },
   "peerDependencies": {
     "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.9.0",
-    "@btravstack/di": "^0.9.0"
+    "@btravstack/config": "^0.10.0",
+    "@btravstack/di": "^0.10.0"
   },
   "engines": {
     "node": ">=22"