@ontrails/core 0.2.0

package/src/internal/fork-ctx.ts

@@ -0,0 +1,69 @@
+/**
+ * Internal helper for "forking" a trail context.
+ *
+ * Several execution sites need to derive a child context from a parent
+ * context while **resetting** a well-known set of bound closures (`compose`,
+ * `fire`, `resource`). Those closures capture the parent scope, so reusing
+ * them on the child would re-enter execution with the wrong attribution,
+ * the wrong resource scope, or the wrong fan-out identity. The reset list
+ * is the same at every fork site.
+ *
+ * Codifying the reset list in one helper keeps that contract in a single
+ * place. Callers supply the overrides they need (typically `env`,
+ * `extensions`, and `logger`) and let the helper handle the reset.
+ *
+ * This module is internal — do not export it from the package entry point.
+ *
+ * @remarks
+ * The helper is intentionally generic over the concrete context shape. Some
+ * callers work with the fully-resolved `TrailContext` produced inside the
+ * executor; others work with `Partial<TrailContextInit>` during consumer
+ * context derivation in `fire.ts`. Both shapes share the same reset keys.
+ */
+
+import type { TrailContext, TrailContextInit } from '../types.js';
+
+/** Keys cleared by default when forking a context. */
+export type ForkCtxResetKey = 'compose' | 'fire' | 'resource';
+
+/** Override fields callers are allowed to apply when forking a context. */
+export type ForkCtxOverrides = Readonly<
+  Partial<Pick<TrailContext, 'env' | 'extensions' | 'logger'>>
+>;
+
+const DEFAULT_RESET_KEYS: readonly ForkCtxResetKey[] = [
+  'compose',
+  'fire',
+  'resource',
+];
+
+/**
+ * Fork a parent context into a child context.
+ *
+ * Spreads the parent, clears each reset key to `undefined`, and applies the
+ * supplied overrides last so callers may replace logger, env, and extensions
+ * with branch-local values.
+ *
+ * The generic parameter is constrained to the minimal shape the helper
+ * reads and writes. This lets the helper serve both `TrailContext`
+ * (executor scope) and `Partial<TrailContextInit>` (fire-consumer scope)
+ * without widening the public surface of either type.
+ */
+export const forkCtx = <
+  TCtx extends Partial<
+    Pick<
+      TrailContextInit,
+      'compose' | 'env' | 'extensions' | 'fire' | 'logger' | 'resource'
+    >
+  >,
+>(
+  parentCtx: TCtx,
+  overrides: ForkCtxOverrides = {},
+  reset: readonly ForkCtxResetKey[] = DEFAULT_RESET_KEYS
+): TCtx => {
+  const forked: TCtx = { ...parentCtx };
+  for (const key of reset) {
+    forked[key as keyof TCtx] = undefined as TCtx[keyof TCtx];
+  }
+  return { ...forked, ...overrides };
+};

package/src/layer-field-rendering.ts

@@ -0,0 +1,193 @@
+/**
+ * Shared, surface-agnostic helpers for rendering typed layer `input` schemas
+ * onto a surface's native idiom.
+ *
+ * Layer rendering has two halves:
+ *   1. **Collection** — walk the trail's effective layers (topo → surface →
+ *      trail) and keep only the ones that declare an `input` schema. These
+ *      are the layers a surface needs to render.
+ *   2. **Naming/collision policy** — when a layer field's rendered name
+ *      collides with a name already claimed by the trail, by another layer,
+ *      or by a surface-reserved name, the field is renamed using the
+ *      deterministic `<layerName>-<originalField>` rule. The collision-detection
+ *      logic itself is surface-agnostic; the *shape* of the rendered name
+ *      (kebab-case CLI flag, camelCase MCP parameter, HTTP request field)
+ *      stays per-surface.
+ *
+ * This module owns the surface-agnostic half. CLI/MCP/HTTP each layer their
+ * own rendering on top: see `@ontrails/cli/build`, `@ontrails/mcp/build`,
+ * and `@ontrails/http/build`.
+ *
+ * @see TRL-473 for the CLI rendering that introduced this contract.
+ * @see TRL-474 for the MCP and HTTP renderings that lifted these helpers.
+ */
+
+import type { Layer } from './layer.js';
+import type { Topo } from './topo.js';
+import type { AnyTrail } from './trail.js';
+
+export const LAYER_FIELD_RESERVED_NAMES: ReadonlySet<string> = new Set([
+  'all',
+  'devPermit',
+  'dryRun',
+  'input',
+  'inputJson',
+  'json',
+  'jsonl',
+  'output',
+  'permit',
+  'quiet',
+  'token',
+  'trailVersion',
+  'trace',
+  'watch',
+]);
+
+const toKebabCase = (name: string): string =>
+  name.replaceAll(/[A-Z]/g, (ch) => `-${ch.toLowerCase()}`);
+
+export const LAYER_FIELD_RESERVED_NAMES_KEBAB: ReadonlySet<string> = new Set(
+  [...LAYER_FIELD_RESERVED_NAMES].map(toKebabCase)
+);
+
+// ---------------------------------------------------------------------------
+// Collection
+// ---------------------------------------------------------------------------
+
+/**
+ * Source of a typed layer attached to a trail.
+ *
+ * Surfaces may want to know whether a layer came from topo-, surface-, or
+ * trail-scope (e.g. for descriptive errors). The collection helper preserves
+ * this information so callers don't have to recompute it.
+ */
+export type AttachedLayerScope = 'topo' | 'surface' | 'trail';
+
+export interface AttachedTypedLayer {
+  readonly layer: Layer;
+  readonly scope: AttachedLayerScope;
+}
+
+/**
+ * Collect every typed layer attached to a trail in the same composition order
+ * the executor uses (topo → surface → trail). Layers without an `input`
+ * schema are skipped — they have nothing to render onto a surface.
+ *
+ * @param graph - The topo carrying topo-scope layers.
+ * @param trail - The trail whose effective layers we are rendering.
+ * @param surfaceLayers - Layers attached at surface scope (`options.layers`
+ *   on the surface builder).
+ */
+export const collectAttachedTypedLayers = (
+  graph: Topo,
+  trail: AnyTrail,
+  surfaceLayers?: readonly Layer[] | undefined
+): readonly AttachedTypedLayer[] => {
+  const layers: AttachedTypedLayer[] = [];
+  for (const layer of graph.layers) {
+    if (layer.input !== undefined) {
+      layers.push({ layer, scope: 'topo' });
+    }
+  }
+  if (surfaceLayers !== undefined) {
+    for (const layer of surfaceLayers) {
+      if (layer.input !== undefined) {
+        layers.push({ layer, scope: 'surface' });
+      }
+    }
+  }
+  for (const layer of trail.layers) {
+    if (layer.input !== undefined) {
+      layers.push({ layer, scope: 'trail' });
+    }
+  }
+  return layers;
+};
+
+// ---------------------------------------------------------------------------
+// Collision rename rule
+// ---------------------------------------------------------------------------
+
+/**
+ * Reason a layer field was renamed during rendering.
+ *
+ * Surfaces map this onto their own warning/error idiom. CLI emits a stderr
+ * warning, while MCP/HTTP rely on the rendered schema as the source of truth.
+ */
+export type LayerFieldRenameReason = 'reserved-name' | 'flag-collision';
+
+/**
+ * Outcome of rendering a single layer field's name.
+ *
+ * `claimedName` is the name the surface will publish to consumers; it is the
+ * field name when no collision was detected, or `<layerName>-<fieldName>` (or
+ * an analogous transformed form, depending on the surface's convention) when
+ * a collision required a rename. `routingTarget` is the original field name
+ * the value should be assigned back to inside the layer's runtime input.
+ */
+export interface LayerFieldRendering {
+  readonly claimedName: string;
+  readonly routingTarget: string;
+  readonly renamed: false;
+}
+
+export interface RenamedLayerFieldRendering {
+  readonly claimedName: string;
+  readonly routingTarget: string;
+  readonly renamed: true;
+  readonly originalName: string;
+  readonly reason: LayerFieldRenameReason;
+}
+
+export type RenderedLayerField =
+  | LayerFieldRendering
+  | RenamedLayerFieldRendering;
+
+/**
+ * Apply the deterministic collision rename rule to a single rendered layer
+ * field name.
+ *
+ * @param layerName - The layer's logical name (used as the rename prefix).
+ * @param originalName - The layer field's name as authored on its schema.
+ * @param renderedName - The candidate name in the surface's native idiom
+ *   (e.g. kebab-case for CLI, camelCase for MCP, request field for HTTP).
+ * @param renamedName - The fallback name applied when a collision is detected.
+ *   Surfaces compute this with their own casing rule.
+ * @param claimedNames - Names already taken by the trail's input or by
+ *   previous layer renderings. Updated in place when a name is claimed.
+ * @param reservedNames - Framework-owned names that force a rename across
+ *   surface renderings.
+ */
+export const renderLayerFieldName = (
+  _layerName: string,
+  originalName: string,
+  renderedName: string,
+  renamedName: string,
+  claimedNames: Set<string>,
+  reservedNames: ReadonlySet<string>
+): RenderedLayerField => {
+  const collidesWithClaimed = claimedNames.has(renderedName);
+  const collidesWithReserved = reservedNames.has(renderedName);
+
+  if (!collidesWithClaimed && !collidesWithReserved) {
+    claimedNames.add(renderedName);
+    return {
+      claimedName: renderedName,
+      renamed: false,
+      routingTarget: originalName,
+    };
+  }
+
+  let claimedName = renamedName;
+  for (let suffix = 2; claimedNames.has(claimedName); suffix += 1) {
+    claimedName = `${renamedName}${suffix}`;
+  }
+  claimedNames.add(claimedName);
+  return {
+    claimedName,
+    originalName: renderedName,
+    reason: collidesWithReserved ? 'reserved-name' : 'flag-collision',
+    renamed: true,
+    routingTarget: originalName,
+  };
+};

package/src/layer.ts

@@ -0,0 +1,81 @@
+import type { z } from 'zod';
+
+import type { AnyTrail } from './trail.js';
+import type { Implementation } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Layer interface
+// ---------------------------------------------------------------------------
+
+/**
+ * A composable, named layer that wraps implementations.
+ *
+ * Layers attach at trail, surface, or topo scope and may declare an object
+ * `input` schema describing the configuration they need from the surrounding
+ * surface. Surface packages (CLI, MCP, HTTP) render this schema onto their
+ * native idioms — flags, tool parameters, query strings — alongside the
+ * trail's own input schema.
+ *
+ * @remarks
+ * The `input` schema is metadata for surface rendering. It must be an object
+ * schema so every surface can render named fields consistently. It is
+ * optional; layers without an `input` schema behave as plain wrappers. The
+ * layer's `wrap` function is the runtime contract.
+ */
+export type LayerInputSchema = z.ZodObject<z.ZodRawShape>;
+
+export interface Layer {
+  readonly name: string;
+  readonly description?: string | undefined;
+
+  /**
+   * Authored configuration the layer needs from the surrounding surface.
+   *
+   * Surface packages render this schema onto their native idioms (CLI flags,
+   * MCP tool parameters, HTTP query strings) so a layer's input fields appear
+   * alongside the trail's own input fields. Optional — layers that wrap purely
+   * by behavior, with no surface-visible inputs, may omit it.
+   *
+   * @see TRL-473 for CLI flag rendering.
+   * @see TRL-474 for MCP and HTTP rendering.
+   */
+  readonly input?: LayerInputSchema | undefined;
+
+  /**
+   * Wrap a trail's implementation, returning a new implementation.
+   *
+   * The trail is passed for metadata inspection (intent, schema, etc.).
+   * The implementation and return type are generic over the input/output
+   * types so layers remain type-safe when composed.
+   */
+  wrap<I, O>(
+    trail: AnyTrail,
+    implementation: Implementation<I, O>
+  ): Implementation<I, O>;
+}
+
+// ---------------------------------------------------------------------------
+// Composition
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply layers outermost-first: layers[0] wraps layers[1] wraps ... wraps
+ * the base implementation.
+ *
+ * An empty layers array returns the implementation unchanged.
+ */
+export const composeLayers = <I, O>(
+  layers: readonly Layer[],
+  trail: AnyTrail,
+  implementation: Implementation<I, O>
+): Implementation<I, O> => {
+  // Fold right so layers[0] is the outermost wrapper.
+  let result = implementation;
+  for (let i = layers.length - 1; i >= 0; i -= 1) {
+    const layer = layers[i];
+    if (layer) {
+      result = layer.wrap(trail, result);
+    }
+  }
+  return result;
+};

package/src/observe.ts

@@ -0,0 +1,361 @@
+import { ValidationError } from './errors.js';
+import type { TraceSink } from './tracing.js';
+import type { Layer } from './layer.js';
+import { safeStringify } from './serialization.js';
+import type { Logger, LogLevel, LogRecord, LogSink } from './types.js';
+
+export interface ObserveConfig {
+  readonly log?: Logger | LogSink | undefined;
+  readonly trace?: TraceSink | undefined;
+}
+
+export interface ObserveCapabilities {
+  readonly log?: true | undefined;
+  readonly trace?: true | undefined;
+}
+
+interface ObserveCapable {
+  readonly observes?: ObserveCapabilities | undefined;
+}
+
+export type ObserveInput = Logger | LogSink | TraceSink | ObserveConfig;
+
+export interface TopoOptions {
+  readonly observe?: ObserveInput | undefined;
+  /**
+   * Typed layers attached at topo scope.
+   *
+   * Layers declared here wrap every trail invoked through this topo, on every
+   * surface. The execution pipeline composes topo-scope layers outermost —
+   * around surface-scope and trail-scope layers — so the final order is
+   * `topo → surface → trail → implementation` (outermost-first).
+   */
+  readonly layers?: readonly Layer[] | undefined;
+}
+
+const OBSERVE_CONFIG_KEYS = new Set(['log', 'trace']);
+export const OBSERVE_LOGGER_CONTEXT_KEY = '__trails_observe_logger';
+
+/**
+ * Context extension key that carries metadata accumulated on the observe
+ * logger across rebindings (e.g. signal fan-out metadata such as `consumerId`
+ * and `signalId`). When `applyTopoObserveContext` rebinds the logger for a
+ * new trail, it merges this metadata into the freshly built observe logger
+ * so consumer log records retain provenance back to the triggering signal.
+ */
+export const OBSERVE_LOGGER_METADATA_KEY = '__trails_observe_logger_metadata';
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const hasFunction = (value: Record<string, unknown>, key: string): boolean =>
+  typeof value[key] === 'function';
+
+export const isLogger = (value: unknown): value is Logger =>
+  isObject(value) &&
+  hasFunction(value, 'child') &&
+  hasFunction(value, 'debug') &&
+  hasFunction(value, 'error') &&
+  hasFunction(value, 'fatal') &&
+  hasFunction(value, 'info') &&
+  hasFunction(value, 'trace') &&
+  hasFunction(value, 'warn');
+
+export const isLogSink = (value: unknown): value is LogSink =>
+  isObject(value) &&
+  typeof value['name'] === 'string' &&
+  hasFunction(value, 'write');
+
+const readObserveCapabilities = (
+  value: unknown
+): ObserveCapabilities | undefined => {
+  if (!isObject(value)) {
+    return undefined;
+  }
+  const capabilities = (value as ObserveCapable).observes;
+  if (!isObject(capabilities)) {
+    return undefined;
+  }
+  const log = capabilities['log'] === true;
+  const trace = capabilities['trace'] === true;
+  if (!log && !trace) {
+    return undefined;
+  }
+  return Object.freeze({
+    ...(log ? { log: true as const } : {}),
+    ...(trace ? { trace: true as const } : {}),
+  });
+};
+
+export const isTraceSink = (value: unknown): value is TraceSink =>
+  isObject(value) && hasFunction(value, 'write');
+
+const isObserveConfigShape = (value: unknown): value is ObserveConfig => {
+  if (!isObject(value)) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  return (
+    keys.length > 0 &&
+    keys.every((key) => OBSERVE_CONFIG_KEYS.has(key)) &&
+    ('log' in value || 'trace' in value)
+  );
+};
+
+/**
+ * Type guard for the `ObserveInput` union. Returns `true` only for shapes
+ * that {@link normalizeObserve} will accept without throwing — i.e. a
+ * `Logger`, an explicit `ObserveConfig`, or a `TraceSink`. Capability-only
+ * payloads (`{ observes: { trace: true } }` without an accompanying
+ * `write` method) and bare `LogSink` shorthand are intentionally rejected:
+ * the former is metadata about a missing implementation, and the latter
+ * is ambiguous between a `LogSink` and a `TraceSink` and is rejected by
+ * `normalizeObserve` accordingly. Keeping the guard tighter than the
+ * runtime accepts would let callers narrow to `ObserveInput` and then
+ * see `normalizeObserve` throw at runtime.
+ */
+export const isObserveInput = (
+  value: unknown
+): value is ObserveInput | undefined => {
+  if (value === undefined) {
+    return true;
+  }
+  if (isLogger(value)) {
+    return true;
+  }
+  if (isObserveConfigShape(value)) {
+    return true;
+  }
+  if (isTraceSink(value) && !isLogSink(value)) {
+    // A bare TraceSink (no `name`) is unambiguous — `normalizeObserve`
+    // accepts it via the `isTraceSink` fallthrough. A LogSink shape is
+    // ambiguous (matches both guards) and would be rejected by
+    // `normalizeObserve`, so the guard rejects it here too.
+    return true;
+  }
+  return false;
+};
+
+/**
+ * Returns true when `value` carries explicit observe capabilities via the
+ * `observes` discriminator. Used by the topo classifier to distinguish
+ * an `ObserveCapable` sink (clearly options) from a bare sink (ambiguous
+ * with a module export named `observe`).
+ */
+export const hasObserveCapabilities = (value: unknown): boolean =>
+  readObserveCapabilities(value) !== undefined;
+
+/**
+ * Returns true when `value` is shaped like the explicit `{ log?, trace? }`
+ * `ObserveConfig` payload. Exposed for the topo classifier so a config-style
+ * trailing argument is unambiguously classified as options.
+ */
+export const isObserveConfig = (value: unknown): value is ObserveConfig =>
+  isObserveConfigShape(value);
+
+const normalizeLogTarget = (
+  target: ObserveConfig['log']
+): ObserveConfig['log'] => {
+  if (target === undefined || isLogger(target) || isLogSink(target)) {
+    return target;
+  }
+  throw new ValidationError('topo observe.log must be a Logger or LogSink');
+};
+
+const normalizeTraceTarget = (
+  target: ObserveConfig['trace']
+): ObserveConfig['trace'] => {
+  if (target === undefined || isTraceSink(target)) {
+    return target;
+  }
+  throw new ValidationError('topo observe.trace must be a TraceSink');
+};
+
+/**
+ * Maps observe log levels to the `console` method that should receive the
+ * formatted record. `silent` is intentionally absent — records at that level
+ * are dropped before reaching `console`.
+ */
+const DEFAULT_SINK_CONSOLE_METHOD: Record<
+  LogLevel,
+  'debug' | 'error' | 'info' | 'warn' | undefined
+> = {
+  debug: 'debug',
+  error: 'error',
+  fatal: 'error',
+  info: 'info',
+  silent: undefined,
+  trace: 'debug',
+  warn: 'warn',
+};
+
+const stringifyDefaultConsoleRecord = (record: LogRecord): string => {
+  const serialized = safeStringify({
+    category: record.category,
+    level: record.level,
+    message: record.message,
+    metadata: record.metadata,
+    timestamp: record.timestamp.toISOString(),
+  });
+  if (serialized.isOk()) {
+    return serialized.value;
+  }
+  return JSON.stringify({
+    category: record.category,
+    level: record.level,
+    message: record.message,
+    metadata: '[unserializable]',
+    timestamp: record.timestamp.toISOString(),
+  });
+};
+
+/**
+ * In-core mirror of `@ontrails/observability`'s `createConsoleSink` shape, kept
+ * minimal and private to avoid a reverse dependency from `@ontrails/core`
+ * onto `@ontrails/observability`. It mirrors the console level mapping in
+ * `packages/observability/src/sinks.ts:50` and emits each record as a single-line
+ * JSON object written to the matching `console.{debug|info|warn|error}` method.
+ *
+ * @remarks
+ * Used as the default `observe.log` target when `topo()` is called without an
+ * explicit `observe` option, so every app gets a non-null `ctx.logger` with
+ * structured stdout output and zero configuration. Apps that want richer
+ * formatting, file destinations, or custom sink behavior should pass an explicit
+ * `observe` option, which fully replaces this default.
+ */
+const createDefaultConsoleSink = (): LogSink => ({
+  name: 'console',
+  write(record): void {
+    const method = DEFAULT_SINK_CONSOLE_METHOD[record.level];
+    if (method === undefined) {
+      return;
+    }
+    const payload = stringifyDefaultConsoleRecord(record);
+    // oxlint-disable-next-line trails-local/no-console-in-packages -- ADR 0041 mandates a default console logger in core; this is the single sanctioned console boundary, mirroring `@ontrails/observability`'s `createConsoleSink`.
+    console[method](payload);
+  },
+});
+
+/**
+ * The default observe configuration applied when `topo()` receives no
+ * `observe` option. Frozen so callers cannot mutate the shared default; the
+ * sink itself is shared across topos because it has no per-topo state.
+ */
+const DEFAULT_OBSERVE_CONFIG: ObserveConfig = Object.freeze({
+  log: createDefaultConsoleSink(),
+});
+
+export const normalizeObserve = (
+  observe: ObserveInput | undefined
+): ObserveConfig | undefined => {
+  if (observe === undefined) {
+    // ADR 0041 promises a non-null `ctx.logger` with zero configuration.
+    // Returning the default config here lets the existing topo → adapter
+    // path renders this log sink into `ctx.logger` without a second
+    // resolution point or a reverse dependency on `@ontrails/observability`.
+    return DEFAULT_OBSERVE_CONFIG;
+  }
+
+  const capabilities = readObserveCapabilities(observe);
+  if (capabilities !== undefined) {
+    const log =
+      capabilities.log === true
+        ? normalizeLogTarget(observe as Logger | LogSink)
+        : undefined;
+    const trace =
+      capabilities.trace === true
+        ? normalizeTraceTarget(observe as TraceSink)
+        : undefined;
+    return Object.freeze({
+      ...(log === undefined ? {} : { log }),
+      ...(trace === undefined ? {} : { trace }),
+    });
+  }
+
+  if (isLogger(observe)) {
+    return Object.freeze({ log: observe });
+  }
+
+  if (isObserveConfigShape(observe)) {
+    const log = normalizeLogTarget(observe.log);
+    const trace = normalizeTraceTarget(observe.trace);
+    if (log === undefined && trace === undefined) {
+      return undefined;
+    }
+    return Object.freeze({
+      ...(log === undefined ? {} : { log }),
+      ...(trace === undefined ? {} : { trace }),
+    });
+  }
+
+  if (isLogSink(observe)) {
+    throw new ValidationError(
+      'topo observe shorthand is ambiguous for named sinks; use { log: sink } or { trace: sink }'
+    );
+  }
+
+  if (isTraceSink(observe)) {
+    return Object.freeze({ trace: observe });
+  }
+
+  throw new ValidationError(
+    'topo observe must be a Logger, LogSink, TraceSink, or { log, trace } object'
+  );
+};
+
+const createLogSinkLogger = (
+  sink: LogSink,
+  category: string,
+  baseMetadata: Record<string, unknown>
+): Logger => {
+  const write = (
+    level: LogLevel,
+    message: string,
+    metadata?: Record<string, unknown>
+  ): void => {
+    sink.write({
+      category,
+      level,
+      message,
+      metadata: { ...baseMetadata, ...metadata },
+      timestamp: new Date(),
+    });
+  };
+
+  return {
+    child(metadata: Record<string, unknown>): Logger {
+      return createLogSinkLogger(sink, category, {
+        ...baseMetadata,
+        ...metadata,
+      });
+    },
+    debug(message, metadata): void {
+      write('debug', message, metadata);
+    },
+    error(message, metadata): void {
+      write('error', message, metadata);
+    },
+    fatal(message, metadata): void {
+      write('fatal', message, metadata);
+    },
+    info(message, metadata): void {
+      write('info', message, metadata);
+    },
+    name: category,
+    trace(message, metadata): void {
+      write('trace', message, metadata);
+    },
+    warn(message, metadata): void {
+      write('warn', message, metadata);
+    },
+  };
+};
+
+export const createObserveLogger = (
+  log: Logger | LogSink,
+  category: string,
+  metadata: Record<string, unknown>
+): Logger =>
+  isLogger(log)
+    ? log.child(metadata)
+    : createLogSinkLogger(log, category, metadata);