alchemy 2.0.0-beta.84 → 2.0.0-beta.85

package/src/Telemetry/Layer.ts

@@ -1,7 +1,6 @@
 import * as Effect from "effect/Effect";
 import * as FetchHttpClient from "effect/http/FetchHttpClient";
 import * as Layer from "effect/Layer";
-import * as OtlpLogger from "effect/observability/OtlpLogger";
 import * as OtlpMetrics from "effect/observability/OtlpMetrics";
 import * as OtlpSerialization from "effect/observability/OtlpSerialization";
 import * as OtlpTracer from "effect/observability/OtlpTracer";
@@ -10,7 +9,6 @@ import { collectAttributes, isTelemetryDisabled } from "./Attributes.ts";
 
 const TRACES_URL = "https://otel.alchemy.run/v1/traces";
 const METRICS_URL = "https://otel.alchemy.run/v1/metrics";
-const LOGS_URL = "https://otel.alchemy.run/v1/logs";
 
 const SERVICE_NAME = "alchemy-cli";
 
@@ -33,23 +31,7 @@ const buildOtlpLayer = (attrs: Record<string, unknown>): Layer.Layer<never, neve
     resource,
     exportInterval: "1 second",
   });
-  // Stack on top of whatever loggers are already installed. Entrypoints
-  // provide this layer *over* their terminal/file logger layer
-  // (`Layer.provideMerge(TelemetryLive, ConsoleLogLive)`), so the terminal
-  // logger has already replaced Effect's default stdout logger by the time
-  // this runs and the OTLP logger is simply added alongside it.
-  //
-  // `mergeWithExisting: false` here would make telemetry *replace* the
-  // terminal logger whenever this layer happened to be merged after it —
-  // exactly what silenced `alchemy dev`'s console output in the exec child.
-  const logger = OtlpLogger.layer({
-    url: LOGS_URL,
-    resource,
-    exportInterval: "1 second",
-    mergeWithExisting: true,
-  });
-
-  return Layer.mergeAll(tracer, metrics, logger).pipe(
+  return Layer.mergeAll(tracer, metrics).pipe(
     Layer.provide(OtlpSerialization.layerJson),
     Layer.provide(FetchHttpClient.layer),
   );
@@ -61,11 +43,8 @@ const buildOtlpLayer = (attrs: Record<string, unknown>): Layer.Layer<never, neve
  * {@link collectAttributes} as resource-level attributes so every signal
  * carries user/project/runtime context.
  *
- * The OTLP logger merges with the loggers already installed, so provide this
- * layer on top of the entrypoint's terminal/file logger layer — e.g.
- * `Layer.provideMerge(TelemetryLive, ConsoleLogLive)` — never as a sibling in
- * a `Layer.mergeAll` (the last `CurrentLoggers` in a merge wins, silently
- * dropping either the terminal output or the telemetry).
+ * Logs are never exported: they stay in the run log on disk, which users
+ * can attach to a support request.
  *
  * If the user has opted out (via `DO_NOT_TRACK`, `NO_TRACK`,
  * `ALCHEMY_TELEMETRY_DISABLED`, or `~/.alchemy/telemetry-disabled`), this

package/src/Telemetry/Metrics.ts

@@ -151,7 +151,7 @@ export const recordStateStoreInit = <A extends { readonly id: string }, E, R>(
     Effect.withSpan("state_store.init"),
   );
 
-export type ResourceOp = "precreate" | "create" | "update" | "delete" | "read";
+export type ResourceOp = "observe" | "precreate" | "create" | "update" | "delete" | "read";
 
 const elapsed = (startNs: bigint): Duration.Duration =>
   Duration.nanos(process.hrtime.bigint() - startNs);

package/src/TelemetryRelay.ts

@@ -145,7 +145,7 @@ export const relay = <R = never>(
         );
         return response.status >= 200 && response.status < 300;
       }).pipe(Effect.orElseSucceed(() => false));
-    const delivered = yield* Effect.all(targets.map(forward), { concurrency: "unbounded" });
+    const delivered = yield* Effect.forEach(targets, forward, { concurrency: "unbounded" });
     return delivered.some(Boolean)
       ? json(200, {})
       : json(502, { error: "No destination accepted the batch" });

package/src/TelemetryRuntime.ts

@@ -2,6 +2,7 @@ import * as ConfigProvider from "effect/ConfigProvider";
 import * as Context from "effect/Context";
 import type * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
+import * as Formatter from "effect/Formatter";
 import * as HttpClient from "effect/http/HttpClient";
 import * as HttpClientRequest from "effect/http/HttpClientRequest";
 import * as Layer from "effect/Layer";
@@ -14,7 +15,6 @@ import * as Redacted from "effect/Redacted";
 import * as Result from "effect/Result";
 import type * as Scope from "effect/Scope";
 import { unpackEnvValue } from "./RuntimeContext.ts";
-import type { layer, layerOtlp } from "./Telemetry.ts";
 
 /**
  * The shape of the {@link Telemetry} reference: a Layer of telemetry
@@ -37,7 +37,7 @@ const readBoundValue = (key: string): Effect.Effect<unknown> =>
     // directly instead of constructing a Config/Schema error for each absence.
     Effect.orDie,
     Effect.catchDefect((defect) =>
-      Predicate.isTagged(defect, "SourceError") ? Effect.succeed(undefined) : Effect.die(defect),
+      Predicate.isTagged(defect, "SourceError") ? Effect.undefined : Effect.die(defect),
     ),
     Effect.map((node) => {
       const raw = node?.value;
@@ -52,7 +52,7 @@ const readBoundValue = (key: string): Effect.Effect<unknown> =>
 const readBound = (key: string): Effect.Effect<string | undefined> =>
   readBoundValue(key).pipe(
     Effect.map((inner) =>
-      inner === undefined ? undefined : typeof inner === "string" ? inner : String(inner),
+      inner === undefined ? undefined : typeof inner === "string" ? inner : Formatter.format(inner),
     ),
   );
 
@@ -198,8 +198,9 @@ const fanoutClient = (
           return effect;
         }
         return Effect.gen(function* () {
-          const results = yield* Effect.all(
-            targets.map((target) =>
+          const results = yield* Effect.forEach(
+            targets,
+            (target) =>
               Effect.result(
                 base.execute(
                   request.pipe(
@@ -208,7 +209,6 @@ const fanoutClient = (
                   ),
                 ),
               ),
-            ),
             { concurrency: "unbounded" },
           );
           const healthy = results.find(
@@ -411,8 +411,8 @@ const reference = Telemetry;
 export const buildEventTelemetry = (
   context: Context.Context<never>,
   scope: Scope.Scope,
-  override?: TelemetryLayer | undefined,
-  base?: TelemetryLayer | undefined,
+  override?: TelemetryLayer,
+  base?: TelemetryLayer,
 ): Effect.Effect<Context.Context<never>> =>
   Effect.suspend(() => {
     const bound = base ?? Context.get(context, reference);

package/src/Util/ConsoleSink.ts

@@ -1,18 +1,81 @@
+import { stripVTControlCharacters } from "node:util";
+import * as Console from "effect/Console";
+import * as DateTime from "effect/DateTime";
 import * as Logger from "effect/Logger";
-import { ANSI_RESET, colorsEnabled } from "./Terminal.ts";
+import type * as LogLevel from "effect/LogLevel";
+import { LogAnnotation } from "./LogAnnotation.ts";
+import { recordOf, safeStringify, severities } from "./LogRecord.ts";
+import { formatResourceTag } from "./ResourceOutput.ts";
+import { ansiFg, ANSI_RESET, colorsEnabled } from "./Terminal.ts";
+import { theme } from "./Theme.ts";
 
-/** Effect pretty prefixes with selective color and untouched message styling. */
-export const makePlainConsoleSink = (colors = colorsEnabled()) => {
-  const pretty = Logger.consolePretty({ colors });
-  if (!colors) return pretty;
+export interface PrettyLoggerOptions {
+  /**
+   * Color the prefix and resource tag, and keep the styling child processes
+   * wrote (vite, workerd); without colors their text is stripped.
+   * @default colorsEnabled()
+   */
+  readonly colors?: boolean;
+}
+
+const levelColor: Partial<Record<LogLevel.LogLevel, string>> = {
+  Fatal: theme.color.danger,
+  Error: theme.color.danger,
+  Warn: theme.color.warning,
+  Info: theme.color.success,
+  Debug: theme.color.info,
+};
+
+const clock = (date: Date) =>
+  DateTime.formatLocal(DateTime.fromDateUnsafe(date), {
+    locale: "en-GB",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    fractionalSecondDigits: 3,
+  });
+
+/** One terminal line: `[12:00:00.000] INFO: [Site/Worker] text`. */
+export const prettyLine = (options: {
+  readonly date: Date;
+  readonly level: LogLevel.Severity;
+  readonly text: string;
+  readonly resource?: string;
+  readonly colors?: boolean;
+}): string => {
+  const colors = options.colors ?? colorsEnabled();
+  const paint = (color: string | undefined, text: string) =>
+    colors && color !== undefined ? `${ansiFg(color)}${text}${ANSI_RESET}` : text;
+  const tag =
+    options.resource === undefined ? "" : `${formatResourceTag(options.resource, colors)} `;
+  return `${paint(theme.color.muted, `[${clock(options.date)}]`)} ${paint(levelColor[options.level], options.level.toUpperCase())}: ${tag}${options.text}`;
+};
+
+/**
+ * The terminal rendering of a log record: `log` and `output` records (typed
+ * events are drawn by the renderers subscribed to them). The resource tag
+ * comes from the record, so producers log plain text and never format it.
+ */
+export const makePlainConsoleSink = (options: PrettyLoggerOptions = {}) => {
+  const colors = options.colors ?? colorsEnabled();
   return Logger.make<unknown, void>((options) => {
-    const messages = Array.isArray(options.message) ? options.message : [options.message];
-    pretty.log({
-      ...options,
-      // consolePretty applies bold cyan around the first string. Reset that
-      // wrapper before the content; any intentional ANSI inside the message
-      // still takes effect normally.
-      message: [`${ANSI_RESET}${String(messages[0] ?? "")}`, ...messages.slice(1)],
-    });
+    const record = recordOf(options);
+    if (record.kind !== "log" && record.kind !== "output") return;
+    const console = options.fiber.getRef(Console.Console);
+    const text = record.kind === "log" ? record.data.message : record.data.text;
+    const { [LogAnnotation.fqn]: fqn, ...attributes } = record.attributes;
+    console.log(
+      prettyLine({
+        date: new Date(record.time),
+        level: severities[record.level],
+        text: colors ? text : stripVTControlCharacters(text),
+        resource: typeof fqn === "string" ? fqn : undefined,
+        colors,
+      }),
+    );
+    for (const [key, value] of Object.entries(attributes)) {
+      console.log(`  ${key}: ${typeof value === "string" ? value : safeStringify(value)}`);
+    }
+    if (record.kind === "log" && record.data.cause !== null) console.log(record.data.cause);
   });
 };

package/src/Util/LogAnnotation.ts

@@ -0,0 +1,18 @@
+/**
+ * Annotation keys alchemy reads. `fqn` is an ordinary attribute (the
+ * resource a record is about, when there is one); the rest map onto
+ * envelope fields instead of `attributes`.
+ */
+export const LogAnnotation = {
+  fqn: "fqn",
+  stream: "alchemy.stream",
+  process: "alchemy.process",
+  /** Set by `emit`: the record's message is a typed event. */
+  event: "alchemy.event",
+  /** `"global"`: account-level work, filed in the global run log. */
+  scope: "alchemy.scope",
+  /** Set on replay: what the original record carried. */
+  time: "alchemy.time",
+  cause: "alchemy.cause",
+  trace: "alchemy.trace",
+} as const;

package/src/Util/LogRecord.ts

@@ -0,0 +1,386 @@
+import { writeSync } from "node:fs";
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as LogLevel from "effect/LogLevel";
+import * as Option from "effect/Option";
+import { CurrentLogAnnotations, MinimumLogLevel } from "effect/References";
+import * as Schema from "effect/Schema";
+import { Event, isKnownEventType } from "../Events.ts";
+import { LogAnnotation } from "./LogAnnotation.ts";
+import { processTrace, type TraceParent, withTraceParent } from "./TraceParent.ts";
+
+/** Record levels, spelled like `--log-level`. */
+export type Level = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+
+/**
+ * What a record is, and the first thing a sink filters on:
+ * - `log`: a line alchemy logged;
+ * - `event`: a typed event (see `emit`);
+ * - `output`: a line a child process wrote (dev servers, workerd, the user's code);
+ * - `run`: the first line of a run log, describing the run.
+ */
+export type Kind = "log" | "event" | "output" | "run";
+
+/**
+ * The envelope every record shares. Every key is always present (`null`
+ * when it doesn't apply), so a reader filters on fields without guessing
+ * which ones a record carries; `data` has the shape its `kind` names.
+ */
+interface Envelope<K extends Kind, Data> {
+  /** Unix time in milliseconds. */
+  readonly time: number;
+  readonly level: Level;
+  readonly kind: K;
+  /** The alchemy process that produced it: `cli`, `exec` or `sidecar`. */
+  readonly process: string;
+  /** Which run log it belongs to: account-level work is `global`. */
+  readonly scope: "project" | "global";
+  /**
+   * The trace and span it was logged in, for joining with telemetry; outside
+   * any span, the process's trace (see `processTrace`).
+   */
+  readonly trace: TraceParent;
+  /** Annotations on the record, beyond the envelope's own fields. */
+  readonly attributes: Readonly<Record<string, unknown>>;
+  readonly data: Data;
+}
+
+/**
+ * One record as data. Every alchemy process logs these; only the process
+ * that owns the terminal renders them (pretty or JSON), so structure
+ * survives process boundaries instead of being baked into rendered text.
+ */
+export type LogRecord =
+  | Envelope<"log", { readonly message: string; readonly cause: string | null }>
+  | Envelope<"event", Event>
+  | Envelope<
+      "output",
+      {
+        readonly stream: "stdout" | "stderr";
+        /** The line as the child wrote it, ANSI styling included. */
+        readonly text: string;
+      }
+    >
+  | Envelope<
+      "run",
+      {
+        readonly version: string;
+        readonly pid: number;
+        readonly cwd: string;
+        readonly argv: ReadonlyArray<string>;
+      }
+    >;
+
+const reserved: ReadonlySet<string> = new Set(
+  Object.values(LogAnnotation).filter((key) => key !== LogAnnotation.fqn),
+);
+
+/** The name this process stamps on its records: `cli`, `exec` or `sidecar`. */
+export const LogProcess = Context.Reference<string>("alchemy/LogProcess", {
+  defaultValue: () => "cli",
+});
+
+/** The Effect log level of each record {@link Level}. */
+export const severities: Record<Level, LogLevel.Severity> = {
+  trace: "Trace",
+  debug: "Debug",
+  info: "Info",
+  warn: "Warn",
+  error: "Error",
+  fatal: "Fatal",
+};
+
+const levelOf = (logLevel: LogLevel.LogLevel): Level =>
+  logLevel === "All" || logLevel === "None" ? "info" : (logLevel.toLowerCase() as Level);
+
+/**
+ * `JSON.stringify` that never throws: cycles become `"[Circular]"` and
+ * bigints their decimal string. Logging must not fail the work it reports.
+ */
+export const safeStringify = (value: unknown): string => {
+  const seen = new WeakSet<object>();
+  try {
+    return (
+      JSON.stringify(value, (_key, v: unknown) => {
+        if (typeof v === "bigint") return v.toString();
+        if (typeof v === "object" && v !== null) {
+          if (seen.has(v)) return "[Circular]";
+          seen.add(v);
+        }
+        return v;
+      }) ?? String(value)
+    );
+  } catch {
+    return String(value);
+  }
+};
+
+const messageText = (message: unknown): string => {
+  const parts = Array.isArray(message) ? message : [message];
+  return parts
+    .map((part) =>
+      typeof part === "string"
+        ? part
+        : part instanceof Error
+          ? (part.stack ?? part.message)
+          : safeStringify(part),
+    )
+    .join(" ");
+};
+
+/** A record's {@link Kind}, read from its annotations alone. */
+export const kindOf = (options: Logger.Options<unknown>): Exclude<Kind, "run"> => {
+  const annotations = options.fiber.getRef(CurrentLogAnnotations);
+  return annotations[LogAnnotation.event] === true
+    ? "event"
+    : annotations[LogAnnotation.stream] !== undefined
+      ? "output"
+      : "log";
+};
+
+const isTrace = (value: unknown): value is TraceParent =>
+  typeof value === "object" &&
+  value !== null &&
+  typeof (value as { traceId?: unknown }).traceId === "string" &&
+  typeof (value as { spanId?: unknown }).spanId === "string";
+
+/** The record a logger call describes. */
+export const recordOf = (options: Logger.Options<unknown>): LogRecord => {
+  const all = options.fiber.getRef(CurrentLogAnnotations);
+  const string = (key: string) => (typeof all[key] === "string" ? all[key] : undefined);
+  const time = all[LogAnnotation.time];
+  const replayedTrace = all[LogAnnotation.trace];
+  const span = options.fiber.cache.span;
+  const head = {
+    time: typeof time === "number" ? time : options.date.getTime(),
+    level: levelOf(options.logLevel),
+  };
+  const envelope = {
+    process: string(LogAnnotation.process) ?? options.fiber.getRef(LogProcess),
+    scope: all[LogAnnotation.scope] === "global" ? ("global" as const) : ("project" as const),
+    trace: isTrace(replayedTrace)
+      ? replayedTrace
+      : span === undefined
+        ? processTrace
+        : { traceId: span.traceId, spanId: span.spanId },
+    attributes: Object.fromEntries(Object.entries(all).filter(([key]) => !reserved.has(key))),
+  };
+  const first = Array.isArray(options.message) ? options.message[0] : options.message;
+  switch (kindOf(options)) {
+    case "event":
+      // SAFETY: only `emit` (or a replayed event) sets the event annotation,
+      // and it logs one Event.
+      return { ...head, kind: "event", ...envelope, data: first as Event };
+    case "output":
+      return {
+        ...head,
+        kind: "output",
+        ...envelope,
+        data: {
+          stream: all[LogAnnotation.stream] === "stderr" ? "stderr" : "stdout",
+          text: messageText(options.message),
+        },
+      };
+    case "log":
+      return {
+        ...head,
+        kind: "log",
+        ...envelope,
+        data: {
+          message: messageText(options.message),
+          cause:
+            string(LogAnnotation.cause) ??
+            (options.cause.reasons.length > 0 ? Cause.pretty(options.cause) : null),
+        },
+      };
+  }
+};
+
+/**
+ * Mark the logs of `effect` as account-level: the CLI files them in the
+ * global run log (`~/.alchemy/logs`) instead of the project's. For work that
+ * isn't about one project — the state store, auth and credentials, profiles.
+ */
+export const globalLogs = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+  Effect.annotateLogs(effect, LogAnnotation.scope, "global");
+
+/**
+ * Set to `json` on alchemy child processes (sidecars) so they log
+ * {@link LogRecord} lines instead of rendering, and on the CLI to print
+ * records as JSON.
+ */
+export const LOG_FORMAT_ENV = "ALCHEMY_LOG_FORMAT";
+
+/** The console's `--log-level`, for child processes that render the run's logs. */
+export const LOG_LEVEL_ENV = "ALCHEMY_LOG_LEVEL";
+
+/** Formats each record as one line of JSON (for `Logger.toFile`). */
+export const formatJsonRecord = Logger.make<unknown, string>((options) =>
+  safeStringify(recordOf(options)),
+);
+
+/** A logger that writes each record as one line of JSON. */
+export const jsonLogger = (write: (line: string) => void) => Logger.map(formatJsonRecord, write);
+
+/**
+ * The only logger of an alchemy child process: every record as a JSON line
+ * on stdout, down to Debug, for the parent to filter and render.
+ */
+export const childJsonLogLayer = Layer.mergeAll(
+  Logger.layer([jsonLogger((line) => process.stdout.write(`${line}\n`))]),
+  Layer.succeed(MinimumLogLevel, "Debug"),
+);
+
+/**
+ * Set on a child process that renders its own terminal output (the
+ * `alchemy dev` exec child) to the file descriptor its parent reads log
+ * records from. The parent writes the run log; the child keeps none.
+ */
+export const LOG_FD_ENV = "ALCHEMY_LOG_FD";
+
+/**
+ * Forward every record, down to Debug, to the parent as JSON lines on the
+ * descriptor in {@link LOG_FD_ENV}, alongside the installed loggers. Empty
+ * when the variable is unset.
+ */
+export const parentLogLayer = (): Layer.Layer<never> => {
+  const fd = Number(process.env[LOG_FD_ENV]);
+  if (!Number.isInteger(fd) || fd < 3) return Layer.empty;
+  const write = (line: string) => {
+    try {
+      writeSync(fd, `${line}\n`);
+    } catch {
+      // The parent is gone or stopped reading: logging must not fail the work.
+    }
+  };
+  return Logger.layer([jsonLogger(write)], {
+    mergeWithExisting: true,
+  });
+};
+
+/** An event of a `type` this version doesn't know: decoded, never validated. */
+const UnknownEvent = Schema.StructWithRest(
+  Schema.Struct({
+    type: Schema.String.check(
+      Schema.makeFilter(
+        (type: string) => !isKnownEventType(type) || "A known event type must decode in full.",
+      ),
+    ),
+  }),
+  [Schema.Record(Schema.String, Schema.Unknown)],
+);
+
+const envelopeFields = {
+  time: Schema.Number,
+  level: Schema.Literals(["trace", "debug", "info", "warn", "error", "fatal"]),
+  process: Schema.String,
+  scope: Schema.Literals(["project", "global"]),
+  trace: Schema.Struct({ traceId: Schema.String, spanId: Schema.String }),
+  attributes: Schema.Record(Schema.String, Schema.Unknown),
+};
+
+/**
+ * The wire form of a {@link LogRecord}: what a child process sends and the
+ * run log stores. An event is decoded with the {@link Event} union; one whose
+ * `type` this version doesn't know is kept as-is rather than rejected, so a
+ * newer process's records still pass through.
+ */
+export const LogRecordSchema = Schema.Union([
+  Schema.Struct({
+    ...envelopeFields,
+    kind: Schema.Literal("log"),
+    data: Schema.Struct({ message: Schema.String, cause: Schema.NullOr(Schema.String) }),
+  }),
+  Schema.Struct({
+    ...envelopeFields,
+    kind: Schema.Literal("event"),
+    data: Schema.Union([Event, UnknownEvent]),
+  }),
+  Schema.Struct({
+    ...envelopeFields,
+    kind: Schema.Literal("output"),
+    data: Schema.Struct({ stream: Schema.Literals(["stdout", "stderr"]), text: Schema.String }),
+  }),
+  Schema.Struct({
+    ...envelopeFields,
+    kind: Schema.Literal("run"),
+    data: Schema.Struct({
+      version: Schema.String,
+      pid: Schema.Number,
+      cwd: Schema.String,
+      argv: Schema.Array(Schema.String),
+    }),
+  }),
+]);
+
+const decodeRecordLine = Schema.decodeUnknownOption(Schema.fromJsonString(LogRecordSchema));
+
+/** Decode one JSON log line, or `undefined` when it isn't a log record. */
+export const parseRecord = (line: string): typeof LogRecordSchema.Type | undefined =>
+  Option.getOrUndefined(decodeRecordLine(line));
+
+/**
+ * Log a record from another process through this process's loggers,
+ * keeping its envelope: the sinks here see the record the child produced.
+ */
+export const replayRecord = (record: typeof LogRecordSchema.Type): Effect.Effect<void> =>
+  record.kind === "run"
+    ? Effect.void
+    : Effect.logWithLevel(severities[record.level])(
+        record.kind === "log"
+          ? record.data.message
+          : record.kind === "output"
+            ? record.data.text
+            : record.data,
+      ).pipe(
+        Effect.annotateLogs({
+          ...record.attributes,
+          [LogAnnotation.time]: record.time,
+          [LogAnnotation.process]: record.process,
+          [LogAnnotation.trace]: record.trace,
+          [LogAnnotation.scope]: record.scope,
+          ...(record.kind === "event" ? { [LogAnnotation.event]: true } : {}),
+          ...(record.kind === "output" ? { [LogAnnotation.stream]: record.data.stream } : {}),
+          ...(record.kind === "log" && record.data.cause !== null
+            ? { [LogAnnotation.cause]: record.data.cause }
+            : {}),
+        }),
+        // A record the child already let through keeps reaching the sinks,
+        // whatever this process's minimum level.
+        Effect.provideService(MinimumLogLevel, "Trace"),
+        // Loggers that read the fiber's span (OTLP) see the child's too.
+        withTraceParent(record.trace),
+      );
+
+/**
+ * Log one line a child process wrote. A JSON {@link LogRecord} (an alchemy
+ * child) is replayed as-is; anything else becomes an Info `output` record,
+ * from `source.process` or, when that's unset, this process.
+ */
+export const logChildLine = (
+  line: string,
+  source: {
+    readonly stream: "stdout" | "stderr";
+    readonly resource?: string;
+    readonly process?: string;
+  },
+): Effect.Effect<void> => {
+  const record = parseRecord(line);
+  if (record !== undefined) {
+    return replayRecord(
+      source.resource !== undefined && record.attributes[LogAnnotation.fqn] === undefined
+        ? { ...record, attributes: { ...record.attributes, [LogAnnotation.fqn]: source.resource } }
+        : record,
+    );
+  }
+  return Effect.logInfo(line).pipe(
+    Effect.annotateLogs({
+      [LogAnnotation.stream]: source.stream,
+      ...(source.resource === undefined ? {} : { [LogAnnotation.fqn]: source.resource }),
+      ...(source.process === undefined ? {} : { [LogAnnotation.process]: source.process }),
+    }),
+  );
+};