@ontrails/core 1.0.0-beta.15 → 1.0.0-beta.16

package/src/fire.ts

@@ -1,10 +1,11 @@
 /**
  * Signal emission and auto-activation.
  *
- * `createFireFn(topo, producerCtx?, executor)` returns a `FireFn` bound to
- * a topo. Calling `fire(signalId, payload)` looks up the signal, validates
- * the payload against its schema, finds every trail with the signal in its
- * `on:` array, and invokes each consumer via the supplied executor.
+ * `createFireFn(topo, producerCtx?, executor, producerTrailId?)` returns a
+ * `FireFn` bound to a topo. Calling `fire(signal, payload)` looks up the
+ * signal, validates the payload against its schema, finds every trail with
+ * the signal in its `on:` array, and invokes each consumer via the supplied
+ * executor.
  *
  * The `executor` parameter is an indirection that lets `execute.ts` pass in
  * `executeTrail` without `fire.ts` importing it directly — keeping the two
@@ -18,16 +19,57 @@
  * producer logger as a child tagged with `signalId` and `consumerId` when
  * `logger.child` exists.
  *
- * Error semantics match the fire-and-forget framing: producers get
- * `Result.ok(undefined)` unless the signal id is unknown or the payload
- * fails schema validation. Consumer errors are logged via the producer's
- * logger but do NOT propagate back to the producer. Consumers that need
- * transactional coupling should use `crosses:`.
+ * Error semantics match the fire-and-forget framing: producer-facing
+ * `ctx.fire()` resolves after dispatch is initiated and without a value.
+ * Unknown signals, invalid payloads, guard suppression, and consumer errors
+ * are logged/diagnosed but do NOT propagate back to the producer. Consumers
+ * that need transactional coupling should use `crosses:`.
  */
 
-import { NotFoundError, ValidationError } from './errors.js';
+import type { z } from 'zod';
+
+import {
+  buildActivationProvenanceTraceAttrs,
+  getActivationProvenance,
+  withActivationProvenance,
+} from './activation-provenance.js';
+import type { ActivationProvenance } from './activation-provenance.js';
+import type { ActivationWhereSpec } from './activation-source.js';
+import { getActivationWherePredicate } from './activation-source.js';
+import { activationSourceKey } from './activation-source-projection.js';
+import { NotFoundError, TrailsError, ValidationError } from './errors.js';
 import { forkCtx } from './internal/fork-ctx.js';
+import {
+  OBSERVE_LOGGER_CONTEXT_KEY,
+  OBSERVE_LOGGER_METADATA_KEY,
+} from './observe.js';
+import {
+  getTraceContext,
+  getTraceSink,
+  isTracingDisabled,
+  writeActivationTraceRecord,
+  writeSignalTraceRecord,
+} from './tracing.js';
+import type { SignalTraceRecordName, TraceSink } from './tracing.js';
 import { Result } from './result.js';
+import type { AnySignal } from './signal.js';
+import {
+  createSignalFireSuppressedDiagnostic,
+  createSignalHandlerFailedDiagnostic,
+  createSignalHandlerRejectedDiagnostic,
+  createSignalInvalidDiagnostic,
+  createSignalPredicateFailedDiagnostic,
+  createSignalUnknownDiagnostic,
+  recordSignalDiagnostic,
+  signalDiagnosticCauseFromUnknown,
+  summarizeSignalPayload,
+} from './signal-diagnostics.js';
+import type {
+  SignalDiagnostic,
+  SignalDiagnosticSchemaIssue,
+  SignalInvalidDiagnostic,
+  SignalPayloadSummary,
+} from './signal-diagnostics.js';
 import type { Topo } from './topo.js';
 import type { AnyTrail } from './trail.js';
 import type { FireFn, Logger, TrailContextInit } from './types.js';
@@ -43,7 +85,75 @@ type MutableConsumerContext = {
   -readonly [K in keyof Partial<TrailContextInit>]: Partial<TrailContextInit>[K];
 };
 
+interface ConsumerActivation {
+  readonly trail: AnyTrail;
+  readonly wheres: readonly ActivationWhereSpec[];
+}
+
 const FIRE_STACK_KEY = '__trails_fire_stack';
+const FIRE_PENDING_DISPATCHES_KEY = '__trails_fire_pending_dispatches';
+
+const frameworkFireFns = new WeakSet<FireFn>();
+
+export const isFrameworkFireFn = (fire: FireFn | undefined): boolean =>
+  fire !== undefined && frameworkFireFns.has(fire);
+
+type FireDispatchTracker = Set<Promise<void>>;
+
+const getFireDispatchTracker = (
+  ctx: Pick<TrailContextInit, 'extensions'> | undefined
+): FireDispatchTracker | undefined => {
+  const tracker = ctx?.extensions?.[FIRE_PENDING_DISPATCHES_KEY];
+  return tracker instanceof Set ? (tracker as FireDispatchTracker) : undefined;
+};
+
+export const withFireDispatchTracking = <T extends TrailContextInit>(
+  ctx: T
+): T => {
+  if (getFireDispatchTracker(ctx) !== undefined) {
+    return ctx;
+  }
+
+  return {
+    ...ctx,
+    extensions: {
+      ...ctx.extensions,
+      [FIRE_PENDING_DISPATCHES_KEY]: new Set<Promise<void>>(),
+    },
+  };
+};
+
+const trackFireDispatch = (
+  ctx: Pick<TrailContextInit, 'extensions'> | undefined,
+  dispatch: Promise<void>
+): void => {
+  const tracker = getFireDispatchTracker(ctx);
+  if (tracker === undefined) {
+    return;
+  }
+  tracker.add(dispatch);
+  const untrack = async (): Promise<void> => {
+    try {
+      await dispatch;
+    } finally {
+      tracker.delete(dispatch);
+    }
+  };
+  void untrack();
+};
+
+export const waitForPendingFireDispatches = async (
+  ctx: Pick<TrailContextInit, 'extensions'>
+): Promise<void> => {
+  const tracker = getFireDispatchTracker(ctx);
+  if (tracker === undefined) {
+    return;
+  }
+
+  while (tracker.size > 0) {
+    await Promise.allSettled(tracker);
+  }
+};
 
 /**
  * Maximum depth for signal fan-out chains.
@@ -63,7 +173,8 @@ const getFireStack = (
 
 /** Binds a per-consumer `fire` onto a mutable consumer context. */
 type ConsumerFireBinder = (
-  consumerCtx: MutableConsumerContext
+  consumerCtx: MutableConsumerContext,
+  consumerId: string
 ) => MutableConsumerContext;
 
 const deriveConsumerLogger = (
@@ -78,66 +189,583 @@ const deriveConsumerEnv = (
 ): TrailContextInit['env'] =>
   producerCtx?.env ? { ...producerCtx.env } : undefined;
 
+const readExistingObserveMetadata = (
+  producerCtx: TrailContextInit | undefined
+): Record<string, unknown> => {
+  const value = producerCtx?.extensions?.[OBSERVE_LOGGER_METADATA_KEY];
+  return value !== null && typeof value === 'object'
+    ? (value as Record<string, unknown>)
+    : {};
+};
+
+const deriveConsumerObserveMetadata = (
+  producerCtx: TrailContextInit | undefined,
+  signalId: string,
+  consumerId: string
+): Record<string, unknown> | undefined => {
+  // Only carry observe metadata forward when the producer ctx is using a
+  // topo-managed observe logger. Otherwise we'd attach signal fan-out fields
+  // to caller-supplied loggers that didn't opt into the structured contract.
+  if (producerCtx?.extensions?.[OBSERVE_LOGGER_CONTEXT_KEY] !== true) {
+    return undefined;
+  }
+  return {
+    ...readExistingObserveMetadata(producerCtx),
+    consumerId,
+    signalId,
+  };
+};
+
 const deriveConsumerExtensions = (
   producerCtx: TrailContextInit | undefined,
-  signalId: string
-): TrailContextInit['extensions'] => ({
-  ...producerCtx?.extensions,
-  [FIRE_STACK_KEY]: [...getFireStack(producerCtx), signalId],
-});
+  signalId: string,
+  consumerId: string
+): TrailContextInit['extensions'] => {
+  const { [FIRE_PENDING_DISPATCHES_KEY]: _pending, ...extensions } =
+    producerCtx?.extensions ?? {};
+  const observeMetadata = deriveConsumerObserveMetadata(
+    producerCtx,
+    signalId,
+    consumerId
+  );
+  return {
+    ...extensions,
+    [FIRE_STACK_KEY]: [...getFireStack(producerCtx), signalId],
+    ...(observeMetadata === undefined
+      ? {}
+      : { [OBSERVE_LOGGER_METADATA_KEY]: observeMetadata }),
+  };
+};
 
 const deriveConsumerCtx = (
   producerCtx: TrailContextInit | undefined,
   signalId: string,
-  consumerId: string
+  consumerId: string,
+  activation: ActivationProvenance
 ): MutableConsumerContext =>
-  producerCtx
-    ? forkCtx(producerCtx as MutableConsumerContext, {
-        env: deriveConsumerEnv(producerCtx),
-        extensions: deriveConsumerExtensions(producerCtx, signalId),
-        logger: deriveConsumerLogger(producerCtx, signalId, consumerId),
-      })
-    : {};
+  withActivationProvenance(
+    producerCtx
+      ? forkCtx(producerCtx as MutableConsumerContext, {
+          env: deriveConsumerEnv(producerCtx),
+          extensions: deriveConsumerExtensions(
+            producerCtx,
+            signalId,
+            consumerId
+          ),
+          logger: deriveConsumerLogger(producerCtx, signalId, consumerId),
+        })
+      : {},
+    activation
+  );
+
+interface FireDiagnosticMetadata {
+  readonly activation: ActivationProvenance;
+  readonly producerTrailId?: string | undefined;
+  readonly runId?: string | undefined;
+  readonly traceId?: string | undefined;
+}
+
+interface SignalTraceAttrsInput {
+  readonly consumerIds?: readonly string[] | undefined;
+  readonly errorName?: string | undefined;
+  readonly handlerTrailId?: string | undefined;
+  readonly payload?: SignalPayloadSummary | undefined;
+  readonly producerTrailId?: string | undefined;
+  readonly runId?: string | undefined;
+  readonly schemaIssues?: readonly SignalDiagnosticSchemaIssue[] | undefined;
+  readonly signalId: string;
+  readonly activation?: ActivationProvenance | undefined;
+}
+
+const deriveFireDiagnosticMetadata = (
+  producerCtx: TrailContextInit | undefined,
+  producerTrailId: string | undefined,
+  signalId: string
+): FireDiagnosticMetadata => {
+  const trace = producerCtx ? getTraceContext(producerCtx) : undefined;
+  const parent = getActivationProvenance(producerCtx);
+  const fireId = Bun.randomUUIDv7();
+  return {
+    activation: {
+      fireId,
+      ...(parent?.fireId === undefined ? {} : { parentFireId: parent.fireId }),
+      rootFireId: parent?.rootFireId ?? fireId,
+      source: {
+        id: signalId,
+        kind: 'signal',
+        ...(producerTrailId === undefined ? {} : { producerTrailId }),
+      },
+    },
+    producerTrailId,
+    runId: trace?.spanId,
+    traceId: trace?.traceId,
+  };
+};
+
+const recordRuntimeSignalDiagnostic = async (
+  producerCtx: TrailContextInit | undefined,
+  diagnostic: SignalDiagnostic
+): Promise<boolean> => {
+  const record = await recordSignalDiagnostic(producerCtx, diagnostic);
+  if (record.promoted) {
+    producerCtx?.logger?.warn('Signal diagnostic promoted by strict mode', {
+      code: diagnostic.code,
+      producerTrailId: diagnostic.producerTrailId,
+      runId: diagnostic.runId,
+      signalId: diagnostic.signalId,
+      traceId: diagnostic.traceId,
+    });
+  }
+  return record.promoted;
+};
+
+const deriveSignalErrorCategory = (error: unknown): string =>
+  error instanceof TrailsError ? error.category : 'internal';
+
+const signalIssuePathLabel = (issue: SignalDiagnosticSchemaIssue): string => {
+  if (issue.path.length === 0) {
+    return '$';
+  }
+  return issue.path.map(String).join('.');
+};
+
+const addPayloadSummaryAttrs = (
+  attrs: Record<string, unknown>,
+  payload: SignalPayloadSummary
+): void => {
+  attrs['trails.signal.payload.byte_length'] = payload.byteLength;
+  attrs['trails.signal.payload.digest'] = payload.digest;
+  attrs['trails.signal.payload.redacted'] = payload.redacted;
+  attrs['trails.signal.payload.shape'] = payload.shape;
+  if (payload.topLevelEntryCount !== undefined) {
+    attrs['trails.signal.payload.top_level_entry_count'] =
+      payload.topLevelEntryCount;
+  }
+};
+
+const buildSignalTraceAttrs = (
+  input: SignalTraceAttrsInput
+): Readonly<Record<string, unknown>> => {
+  const attrs: Record<string, unknown> = {
+    ...buildActivationProvenanceTraceAttrs(input.activation),
+    'trails.signal.id': input.signalId,
+  };
+
+  if (input.producerTrailId !== undefined) {
+    attrs['trails.signal.producer_trail.id'] = input.producerTrailId;
+  }
+  if (input.runId !== undefined) {
+    attrs['trails.signal.run.id'] = input.runId;
+  }
+  if (input.handlerTrailId !== undefined) {
+    attrs['trails.signal.handler_trail.id'] = input.handlerTrailId;
+  }
+  if (input.consumerIds !== undefined) {
+    attrs['trails.signal.consumer_count'] = input.consumerIds.length;
+    attrs['trails.signal.consumer_ids'] = input.consumerIds
+      .toSorted()
+      .join(',');
+  }
+  if (input.errorName !== undefined) {
+    attrs['trails.signal.error.name'] = input.errorName;
+  }
+  if (input.payload !== undefined) {
+    addPayloadSummaryAttrs(attrs, input.payload);
+  }
+  if (input.schemaIssues !== undefined) {
+    const issuePaths = input.schemaIssues.map(signalIssuePathLabel);
+    attrs['trails.signal.schema_issue_count'] = input.schemaIssues.length;
+    attrs['trails.signal.schema_issue_paths'] = issuePaths.join(',');
+  }
+
+  return attrs;
+};
+
+const recordSignalLifecycleTrace = async (
+  producerCtx: TrailContextInit | undefined,
+  name: SignalTraceRecordName,
+  attrs: Readonly<Record<string, unknown>>,
+  status?: Parameters<typeof writeSignalTraceRecord>[3],
+  errorCategory?: string | undefined,
+  sink?: TraceSink | undefined
+): Promise<void> => {
+  if (producerCtx === undefined) {
+    return;
+  }
+  await writeSignalTraceRecord(
+    producerCtx,
+    name,
+    attrs,
+    status,
+    errorCategory,
+    sink
+  );
+};
+
+const recordActivationGuardTrace = async (
+  producerCtx: TrailContextInit | undefined,
+  diagnosticMetadata: FireDiagnosticMetadata,
+  reason: 'cycle' | 'depth',
+  signalId: string,
+  fireStack: readonly string[],
+  limit?: number | undefined,
+  sink?: TraceSink | undefined
+): Promise<void> => {
+  const attrs: Record<string, unknown> = {
+    ...buildActivationProvenanceTraceAttrs(diagnosticMetadata.activation),
+    'trails.activation.guard.fire_stack': fireStack.join(','),
+    'trails.activation.guard.reason': reason,
+    'trails.signal.id': signalId,
+  };
+  if (limit !== undefined) {
+    attrs['trails.activation.guard.limit'] = limit;
+  }
+  await writeActivationTraceRecord(
+    'activation.cycle_detected',
+    attrs,
+    'ok',
+    undefined,
+    producerCtx === undefined ? undefined : getTraceContext(producerCtx),
+    sink
+  );
+};
+
+const activationEntriesForSignal = (
+  trail: AnyTrail,
+  signalId: string
+): readonly ConsumerActivation[] => {
+  const activations = new Map<string, readonly ActivationWhereSpec[]>();
+  for (const activation of trail.activationSources ?? []) {
+    if (
+      activation.source.kind !== 'signal' ||
+      activation.source.id !== signalId
+    ) {
+      continue;
+    }
+    const key = activationSourceKey(activation.source);
+    if (activation.where === undefined) {
+      activations.set(key, []);
+      continue;
+    }
+
+    const wheres = activations.get(key);
+    if (wheres === undefined) {
+      activations.set(key, [activation.where]);
+    } else if (wheres.length > 0) {
+      activations.set(key, [...wheres, activation.where]);
+    }
+  }
+  if (activations.size > 0) {
+    return [...activations.values()].map((wheres) => ({
+      trail,
+      wheres,
+    }));
+  }
+  return trail.on.includes(signalId) ? [{ trail, wheres: [] }] : [];
+};
+
+const listConsumerActivations = (
+  topo: Topo,
+  signalId: string
+): readonly ConsumerActivation[] =>
+  topo.list().flatMap((trail) => activationEntriesForSignal(trail, signalId));
+
+const consumerTrailsFromActivations = (
+  activations: readonly ConsumerActivation[]
+): readonly AnyTrail[] => [
+  ...new Map(
+    activations.map((activation) => [activation.trail.id, activation.trail])
+  ).values(),
+];
+
+const hasActiveSignalTraceContext = (
+  producerCtx: TrailContextInit | undefined,
+  sink: TraceSink
+): boolean =>
+  producerCtx !== undefined &&
+  getTraceContext(producerCtx) !== undefined &&
+  !isTracingDisabled(sink);
+
+const summarizeSignalPayloadForTrace = (
+  producerCtx: TrailContextInit | undefined,
+  payload: unknown,
+  sink: TraceSink
+): SignalPayloadSummary | undefined => {
+  if (!hasActiveSignalTraceContext(producerCtx, sink)) {
+    return undefined;
+  }
+  try {
+    return summarizeSignalPayload(payload);
+  } catch (error) {
+    producerCtx?.logger?.debug('Signal payload summary skipped', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return undefined;
+  }
+};
+
+const recordPredicateTrace = async (
+  producerCtx: TrailContextInit | undefined,
+  name:
+    | 'signal.handler.predicate_failed'
+    | 'signal.handler.predicate_matched'
+    | 'signal.handler.predicate_skipped',
+  input: {
+    readonly diagnosticMetadata: FireDiagnosticMetadata;
+    readonly errorCategory?: string | undefined;
+    readonly errorName?: string | undefined;
+    readonly handlerTrailId: string;
+    readonly payloadSummary?: SignalPayloadSummary | undefined;
+    readonly signalId: string;
+    readonly status?: Parameters<typeof recordSignalLifecycleTrace>[3];
+    readonly traceSink: TraceSink;
+  }
+): Promise<void> => {
+  await recordSignalLifecycleTrace(
+    producerCtx,
+    name,
+    buildSignalTraceAttrs({
+      activation: input.diagnosticMetadata.activation,
+      errorName: input.errorName,
+      handlerTrailId: input.handlerTrailId,
+      payload: input.payloadSummary,
+      producerTrailId: input.diagnosticMetadata.producerTrailId,
+      runId: input.diagnosticMetadata.runId,
+      signalId: input.signalId,
+    }),
+    input.status,
+    input.errorCategory,
+    input.traceSink
+  );
+};
+
+const shouldInvokeConsumer = async (
+  activation: ConsumerActivation,
+  payload: unknown,
+  payloadSummary: SignalPayloadSummary | undefined,
+  signalId: string,
+  producerCtx: TrailContextInit | undefined,
+  diagnosticMetadata: FireDiagnosticMetadata,
+  logger: Logger | undefined,
+  traceSink: TraceSink
+): Promise<boolean> => {
+  if (activation.wheres.length === 0) {
+    return true;
+  }
+
+  for (const where of activation.wheres) {
+    const predicate = getActivationWherePredicate(where);
+    if (predicate === undefined) {
+      return true;
+    }
+
+    try {
+      const matched = await predicate(payload);
+      await recordPredicateTrace(
+        producerCtx,
+        matched
+          ? 'signal.handler.predicate_matched'
+          : 'signal.handler.predicate_skipped',
+        {
+          diagnosticMetadata,
+          handlerTrailId: activation.trail.id,
+          payloadSummary,
+          signalId,
+          traceSink,
+        }
+      );
+      if (matched) {
+        return true;
+      }
+    } catch (error) {
+      const cause = signalDiagnosticCauseFromUnknown(error);
+      const diagnostic = createSignalPredicateFailedDiagnostic({
+        ...diagnosticMetadata,
+        cause: error,
+        handlerTrailId: activation.trail.id,
+        payload,
+        signalId,
+      });
+      await recordRuntimeSignalDiagnostic(producerCtx, diagnostic);
+      await recordPredicateTrace(
+        producerCtx,
+        'signal.handler.predicate_failed',
+        {
+          diagnosticMetadata,
+          errorCategory: deriveSignalErrorCategory(error),
+          errorName: cause.name,
+          handlerTrailId: activation.trail.id,
+          payloadSummary,
+          signalId,
+          status: 'err',
+          traceSink,
+        }
+      );
+      logger?.warn('Signal activation predicate failed', {
+        consumerId: activation.trail.id,
+        error: cause.message,
+        signalId,
+      });
+    }
+  }
+
+  return false;
+};
 
 /**
  * Fan out a validated signal payload to its consumer trails.
  *
  * @remarks
- * Consumers fan out in parallel by design. Signal delivery is fire-and-forget
- * notification, not ordered orchestration; if one consumer depends on another,
- * the dependency belongs in `crosses:` instead of sibling signal sequencing.
+ * Signal delivery is fire-and-forget notification, not ordered orchestration;
+ * if one consumer depends on another, the dependency belongs in `crosses:`
+ * instead of sibling signal sequencing.
  *
- * `Promise.allSettled` preserves failure isolation and waits for every branch
- * to settle. Each consumer gets its own derived context so sibling branches do
- * not share mutable top-level state while they overlap. Re-entrant suppression
- * elsewhere in this module is still based on signal-id membership in the
- * current fire stack: it prevents infinite loops, but it can over-suppress
- * legitimate diamond re-fires. Per-path provenance is a documented future
- * direction rather than part of the pre-v1 runtime contract.
+ * `Promise.allSettled` preserves failure isolation for the background
+ * completion task. Producer-facing `ctx.fire()` starts this task but does not
+ * wait for every consumer to complete before resolving. Each consumer gets its
+ * own derived context so sibling fan-out branches do not share mutable
+ * top-level state while they overlap. Re-entrant suppression elsewhere in this
+ * module is still based on signal-id membership in the current fire stack: it
+ * prevents infinite loops, but it can over-suppress legitimate diamond
+ * re-fires. Activation provenance records each fire boundary so downstream
+ * traces and diagnostics can still reconstruct the chain that activated a
+ * consumer.
  */
 const fanOutToConsumers = async (
-  consumers: readonly AnyTrail[],
+  activations: readonly ConsumerActivation[],
   payload: unknown,
   signalId: string,
   producerCtx: TrailContextInit | undefined,
+  diagnosticMetadata: FireDiagnosticMetadata,
   bindFire: ConsumerFireBinder,
   executor: ConsumerExecutor,
-  logger: Logger | undefined
+  logger: Logger | undefined,
+  traceSink: TraceSink
 ): Promise<void> => {
+  const payloadSummary = summarizeSignalPayloadForTrace(
+    producerCtx,
+    payload,
+    traceSink
+  );
   const settled = await Promise.allSettled(
-    consumers.map(async (consumer) => {
+    activations.map(async (activation) => {
+      const consumer = activation.trail;
+      const shouldInvoke = await shouldInvokeConsumer(
+        activation,
+        payload,
+        payloadSummary,
+        signalId,
+        producerCtx,
+        diagnosticMetadata,
+        logger,
+        traceSink
+      );
+      if (!shouldInvoke) {
+        return consumer.id;
+      }
       const consumerCtx = bindFire(
-        deriveConsumerCtx(producerCtx, signalId, consumer.id)
+        deriveConsumerCtx(
+          producerCtx,
+          signalId,
+          consumer.id,
+          diagnosticMetadata.activation
+        ),
+        consumer.id
       );
-      const consumerResult = await executor(consumer, payload, consumerCtx);
-      if (consumerResult.isErr()) {
-        (consumerCtx.logger ?? logger)?.warn('Signal consumer failed', {
-          consumerId: consumer.id,
-          error: consumerResult.error.message,
+      await recordSignalLifecycleTrace(
+        producerCtx,
+        'signal.handler.invoked',
+        buildSignalTraceAttrs({
+          activation: diagnosticMetadata.activation,
+          handlerTrailId: consumer.id,
+          payload: payloadSummary,
+          producerTrailId: diagnosticMetadata.producerTrailId,
+          runId: diagnosticMetadata.runId,
+          signalId,
+        }),
+        undefined,
+        undefined,
+        traceSink
+      );
+      try {
+        const consumerResult = await executor(consumer, payload, consumerCtx);
+        if (consumerResult.isErr()) {
+          const cause = signalDiagnosticCauseFromUnknown(consumerResult.error);
+          const diagnostic = createSignalHandlerFailedDiagnostic({
+            ...diagnosticMetadata,
+            cause: consumerResult.error,
+            handlerTrailId: consumer.id,
+            payload,
+            signalId,
+          });
+          await recordRuntimeSignalDiagnostic(producerCtx, diagnostic);
+          await recordSignalLifecycleTrace(
+            producerCtx,
+            'signal.handler.failed',
+            buildSignalTraceAttrs({
+              activation: diagnosticMetadata.activation,
+              errorName: cause.name,
+              handlerTrailId: consumer.id,
+              payload: payloadSummary,
+              producerTrailId: diagnosticMetadata.producerTrailId,
+              runId: diagnosticMetadata.runId,
+              signalId,
+            }),
+            'err',
+            deriveSignalErrorCategory(consumerResult.error),
+            traceSink
+          );
+          (consumerCtx.logger ?? logger)?.warn('Signal consumer failed', {
+            consumerId: consumer.id,
+            error: consumerResult.error.message,
+            signalId,
+          });
+          return consumer.id;
+        }
+        await recordSignalLifecycleTrace(
+          producerCtx,
+          'signal.handler.completed',
+          buildSignalTraceAttrs({
+            activation: diagnosticMetadata.activation,
+            handlerTrailId: consumer.id,
+            payload: payloadSummary,
+            producerTrailId: diagnosticMetadata.producerTrailId,
+            runId: diagnosticMetadata.runId,
+            signalId,
+          }),
+          undefined,
+          undefined,
+          traceSink
+        );
+        return consumer.id;
+      } catch (error) {
+        const cause = signalDiagnosticCauseFromUnknown(error);
+        const diagnostic = createSignalHandlerRejectedDiagnostic({
+          ...diagnosticMetadata,
+          cause: error,
+          handlerTrailId: consumer.id,
+          payload,
           signalId,
         });
+        await recordRuntimeSignalDiagnostic(producerCtx, diagnostic);
+        await recordSignalLifecycleTrace(
+          producerCtx,
+          'signal.handler.failed',
+          buildSignalTraceAttrs({
+            activation: diagnosticMetadata.activation,
+            errorName: cause.name,
+            handlerTrailId: consumer.id,
+            payload: payloadSummary,
+            producerTrailId: diagnosticMetadata.producerTrailId,
+            runId: diagnosticMetadata.runId,
+            signalId,
+          }),
+          'err',
+          deriveSignalErrorCategory(error),
+          traceSink
+        );
+        throw error;
       }
-      return consumer.id;
     })
   );
   for (const [index, entry] of settled.entries()) {
@@ -149,7 +777,7 @@ const fanOutToConsumers = async (
     // unexpectedly. Log at debug to preserve provenance without propagating
     // the failure to the producer (fire-and-forget semantics).
     logger?.debug('Signal consumer rejected unexpectedly', {
-      consumerId: consumers[index]?.id,
+      consumerId: activations[index]?.trail.id,
       error:
         entry.reason instanceof Error
           ? entry.reason.message
@@ -159,51 +787,170 @@ const fanOutToConsumers = async (
   }
 };
 
-const resolveFireDispatch = (
-  topo: Topo,
+const recordInvalidSignalDiagnostic = async (
+  producerCtx: TrailContextInit | undefined,
+  diagnostic: SignalInvalidDiagnostic
+): Promise<boolean> =>
+  await recordRuntimeSignalDiagnostic(producerCtx, diagnostic);
+
+const createInvalidPayloadError = (
   signalId: string,
+  message: string,
+  diagnostic: SignalInvalidDiagnostic,
+  promoted: boolean
+): ValidationError =>
+  new ValidationError(`Invalid payload for signal "${signalId}": ${message}`, {
+    context: {
+      diagnosticCode: diagnostic.code,
+      promoted,
+      schemaIssues: diagnostic.schemaIssues,
+      signalId,
+    },
+  });
+
+const PAYLOAD_SCHEMA_READ_ERROR_MESSAGE =
+  'Payload schema validation could not read the payload safely';
+
+type SignalPayloadParseResult =
+  | {
+      readonly data: unknown;
+      readonly success: true;
+    }
+  | {
+      readonly issues: readonly z.core.$ZodIssue[];
+      readonly message: string;
+      readonly success: false;
+    };
+
+const unreadablePayloadIssue = (): z.core.$ZodIssue =>
+  ({
+    code: 'custom',
+    message: PAYLOAD_SCHEMA_READ_ERROR_MESSAGE,
+    path: [],
+  }) as z.core.$ZodIssue;
+
+const safeParseSignalPayload = (
+  signal: AnySignal,
   payload: unknown
-): Result<
-  { readonly consumers: readonly AnyTrail[]; readonly payload: unknown },
-  Error
+): SignalPayloadParseResult => {
+  try {
+    const parsed = signal.payload.safeParse(payload);
+    if (parsed.success) {
+      return { data: parsed.data, success: true };
+    }
+    return {
+      issues: parsed.error.issues,
+      message: parsed.error.message,
+      success: false,
+    };
+  } catch {
+    return {
+      issues: [unreadablePayloadIssue()],
+      message: PAYLOAD_SCHEMA_READ_ERROR_MESSAGE,
+      success: false,
+    };
+  }
+};
+
+const resolveFireDispatch = async (
+  topo: Topo,
+  signalId: string,
+  payload: unknown,
+  producerCtx: TrailContextInit | undefined,
+  diagnosticMetadata: FireDiagnosticMetadata,
+  traceSink: TraceSink
+): Promise<
+  Result<
+    {
+      readonly activations: readonly ConsumerActivation[];
+      readonly consumers: readonly AnyTrail[];
+      readonly payload: unknown;
+    },
+    Error
+  >
 > => {
   const signal = topo.signals.get(signalId);
   if (signal === undefined) {
+    await recordRuntimeSignalDiagnostic(
+      producerCtx,
+      createSignalUnknownDiagnostic({
+        ...diagnosticMetadata,
+        signalId,
+      })
+    );
     return Result.err(
       new NotFoundError(`Signal "${signalId}" not found in topo "${topo.name}"`)
     );
   }
-  const parsed = signal.payload.safeParse(payload);
+  const parsed = safeParseSignalPayload(signal, payload);
   if (!parsed.success) {
+    const diagnostic = createSignalInvalidDiagnostic({
+      ...diagnosticMetadata,
+      payload,
+      schemaIssues: parsed.issues,
+      signalId,
+    });
+    const promoted = await recordInvalidSignalDiagnostic(
+      producerCtx,
+      diagnostic
+    );
+    await recordSignalLifecycleTrace(
+      producerCtx,
+      'signal.invalid',
+      buildSignalTraceAttrs({
+        activation: diagnostic.activation,
+        payload: diagnostic.payload,
+        producerTrailId: diagnostic.producerTrailId,
+        runId: diagnostic.runId,
+        schemaIssues: diagnostic.schemaIssues,
+        signalId,
+      }),
+      'err',
+      'validation',
+      traceSink
+    );
     return Result.err(
-      new ValidationError(
-        `Invalid payload for signal "${signalId}": ${parsed.error.message}`
-      )
+      createInvalidPayloadError(signalId, parsed.message, diagnostic, promoted)
     );
   }
+  const activations = listConsumerActivations(topo, signalId);
   return Result.ok({
-    consumers: topo.list().filter((trail) => trail.on.includes(signalId)),
+    activations,
+    consumers: consumerTrailsFromActivations(activations),
     payload: parsed.data,
   });
 };
 
 const resolveSignalId = (signalOrId: unknown): Result<string, Error> => {
-  if (typeof signalOrId === 'string') {
-    return Result.ok(signalOrId);
-  }
   if (
     typeof signalOrId === 'object' &&
     signalOrId !== null &&
+    'kind' in signalOrId &&
+    (signalOrId as { kind: unknown }).kind === 'signal' &&
     'id' in signalOrId &&
     typeof (signalOrId as { id: unknown }).id === 'string'
   ) {
-    return Result.ok((signalOrId as { id: string }).id);
+    return Result.ok((signalOrId as AnySignal).id);
   }
-  return Result.err(
-    new ValidationError(
-      'ctx.fire() requires a signal id string or a Signal value'
-    )
-  );
+  if (typeof signalOrId === 'string') {
+    return Result.err(
+      new ValidationError(
+        'ctx.fire() requires a Signal value; string signal ids are not part of the public fire API'
+      )
+    );
+  }
+  return Result.err(new ValidationError('ctx.fire() requires a Signal value'));
+};
+
+const logFireError = (
+  logger: Logger | undefined,
+  signalId: string | undefined,
+  error: Error
+): void => {
+  logger?.warn('Signal fire skipped', {
+    error: error.message,
+    signalId,
+  });
 };
 
 /**
@@ -218,9 +965,15 @@ const resolveSignalId = (signalOrId: unknown): Result<string, Error> => {
 export const createFireFn = (
   topo: Topo,
   producerCtx: TrailContextInit | undefined,
-  executor: ConsumerExecutor
+  executor: ConsumerExecutor,
+  producerTrailId?: string | undefined
 ): FireFn => {
-  const bindConsumerFire: ConsumerFireBinder = (consumerCtx) => ({
+  const trackedProducerCtx =
+    producerCtx === undefined
+      ? undefined
+      : withFireDispatchTracking(producerCtx);
+  const traceSink = topo.observe?.trace ?? getTraceSink();
+  const bindConsumerFire: ConsumerFireBinder = (consumerCtx, consumerId) => ({
     ...consumerCtx,
     // Pre-bind fire on the consumer ctx as a safety net for direct
     // executeTrail calls that skip the topo-aware path. In the normal
@@ -228,50 +981,138 @@ export const createFireFn = (
     // the fully-traced ctx before the blaze runs, so this assignment
     // is superseded — but keeping it makes consumerCtx self-sufficient
     // for any caller that inspects it pre-execution.
-    fire: createFireFn(topo, consumerCtx as TrailContextInit, executor),
+    fire: createFireFn(
+      topo,
+      consumerCtx as TrailContextInit,
+      executor,
+      consumerId
+    ),
   });
 
   const dispatchFire = async (
     signalId: string,
-    payload: unknown
+    payload: unknown,
+    diagnosticMetadata: FireDiagnosticMetadata
   ): Promise<Result<void, Error>> => {
-    const dispatch = resolveFireDispatch(topo, signalId, payload);
+    const dispatch = await resolveFireDispatch(
+      topo,
+      signalId,
+      payload,
+      trackedProducerCtx,
+      diagnosticMetadata,
+      traceSink
+    );
     if (dispatch.isErr()) {
       return Result.err(dispatch.error);
     }
-    await fanOutToConsumers(
-      dispatch.value.consumers,
-      dispatch.value.payload,
-      signalId,
-      producerCtx,
-      bindConsumerFire,
-      executor,
-      producerCtx?.logger
+    await recordSignalLifecycleTrace(
+      trackedProducerCtx,
+      'signal.fired',
+      buildSignalTraceAttrs({
+        activation: diagnosticMetadata.activation,
+        consumerIds: dispatch.value.consumers.map((consumer) => consumer.id),
+        payload: summarizeSignalPayloadForTrace(
+          trackedProducerCtx,
+          dispatch.value.payload,
+          traceSink
+        ),
+        producerTrailId: diagnosticMetadata.producerTrailId,
+        runId: diagnosticMetadata.runId,
+        signalId,
+      }),
+      undefined,
+      undefined,
+      traceSink
     );
+    const completion = (async (): Promise<void> => {
+      try {
+        await fanOutToConsumers(
+          dispatch.value.activations,
+          dispatch.value.payload,
+          signalId,
+          trackedProducerCtx,
+          diagnosticMetadata,
+          bindConsumerFire,
+          executor,
+          trackedProducerCtx?.logger,
+          traceSink
+        );
+      } catch (error: unknown) {
+        trackedProducerCtx?.logger?.debug(
+          'Signal dispatch completion failed unexpectedly',
+          {
+            error: error instanceof Error ? error.message : String(error),
+            signalId,
+          }
+        );
+      }
+    })();
+    trackFireDispatch(trackedProducerCtx, completion);
     return Result.ok();
   };
 
   /** Return an early Result if the fire should be suppressed, or null to proceed. */
-  const guardFire = (
+  const guardFire = async (
     signalId: string,
-    stack: readonly string[]
-  ): Result<void, Error> | null => {
+    stack: readonly string[],
+    diagnosticMetadata: FireDiagnosticMetadata
+  ): Promise<Result<void, Error> | null> => {
     if (stack.length >= MAX_FIRE_DEPTH) {
-      producerCtx?.logger?.warn(
+      trackedProducerCtx?.logger?.warn(
         'Signal fan-out depth limit reached — skipping fire',
         { depth: stack.length, signalId }
       );
+      await recordRuntimeSignalDiagnostic(
+        trackedProducerCtx,
+        createSignalFireSuppressedDiagnostic({
+          ...diagnosticMetadata,
+          fireStack: [...stack],
+          limit: MAX_FIRE_DEPTH,
+          reason: 'depth',
+          signalId,
+        })
+      );
+      await recordActivationGuardTrace(
+        trackedProducerCtx,
+        diagnosticMetadata,
+        'depth',
+        signalId,
+        stack,
+        MAX_FIRE_DEPTH,
+        traceSink
+      );
       return Result.ok();
     }
     if (stack.includes(signalId)) {
-      producerCtx?.logger?.debug('Signal fan-out suppressed due to cycle', {
-        fireStack: [...stack],
-        signalId,
-      });
-      producerCtx?.logger?.warn(
+      trackedProducerCtx?.logger?.debug(
+        'Signal fan-out suppressed due to cycle',
+        {
+          fireStack: [...stack],
+          signalId,
+        }
+      );
+      trackedProducerCtx?.logger?.warn(
         'Signal cycle detected — skipping re-entrant fire',
         { fireStack: [...stack], signalId }
       );
+      await recordRuntimeSignalDiagnostic(
+        trackedProducerCtx,
+        createSignalFireSuppressedDiagnostic({
+          ...diagnosticMetadata,
+          fireStack: [...stack],
+          reason: 'cycle',
+          signalId,
+        })
+      );
+      await recordActivationGuardTrace(
+        trackedProducerCtx,
+        diagnosticMetadata,
+        'cycle',
+        signalId,
+        stack,
+        undefined,
+        traceSink
+      );
       return Result.ok();
     }
     return null;
@@ -280,16 +1121,49 @@ export const createFireFn = (
   const fireImpl: FireFn = async (
     signalOrId: unknown,
     payload: unknown
-  ): Promise<Result<void, Error>> => {
+  ): Promise<void> => {
     const resolved = resolveSignalId(signalOrId);
     if (resolved.isErr()) {
-      return Result.err(resolved.error);
+      logFireError(
+        trackedProducerCtx?.logger,
+        typeof signalOrId === 'string' ? signalOrId : undefined,
+        resolved.error
+      );
+      return;
     }
-    const suppressed = guardFire(resolved.value, getFireStack(producerCtx));
+    const diagnosticMetadata = deriveFireDiagnosticMetadata(
+      trackedProducerCtx,
+      producerTrailId,
+      resolved.value
+    );
+    const suppressed = await guardFire(
+      resolved.value,
+      getFireStack(trackedProducerCtx),
+      diagnosticMetadata
+    );
     if (suppressed) {
-      return suppressed;
+      if (suppressed.isErr()) {
+        logFireError(
+          trackedProducerCtx?.logger,
+          resolved.value,
+          suppressed.error
+        );
+      }
+      return;
+    }
+    const dispatched = await dispatchFire(
+      resolved.value,
+      payload,
+      diagnosticMetadata
+    );
+    if (dispatched.isErr()) {
+      logFireError(
+        trackedProducerCtx?.logger,
+        resolved.value,
+        dispatched.error
+      );
     }
-    return await dispatchFire(resolved.value, payload);
   };
+  frameworkFireFns.add(fireImpl);
   return fireImpl;
 };