@telorun/kernel 0.49.0 → 0.50.0

package/src/controllers/logging/sink-identity.ts

@@ -0,0 +1,53 @@
+import { parseDurationMs } from "@telorun/sdk";
+import { blockUnsupportedMessage, DEFAULT_BUFFER_POLICY, type SinkBufferPolicy } from "../../logging/log-sink.js";
+import { RuntimeError } from "@telorun/sdk";
+
+/**
+ * Shared sink-manifest reading — `kernel/specs/logging.md` §10.3, §12.1.
+ */
+
+/** Sink identity for drop accounting (§10.4): the resource name for a `!ref`,
+ *  or the synthetic name inline extraction assigned, which already encodes kind
+ *  plus position. */
+export function sinkIdFor(resource: { metadata?: { name?: string }; kind?: string }): string {
+  return resource.metadata?.name ?? resource.kind ?? "<sink>";
+}
+
+/**
+ * Read the buffering policy an async sink inherits from `Telo.LogSink`.
+ *
+ * `on_full: block` is rejected here rather than silently degraded. Blocking
+ * means suspending the producer until the buffer drains, which requires the
+ * drain to progress *while* the producer is suspended — true on a runtime with
+ * real threads, false on a single-threaded event loop, where suspending the
+ * producer suspends the consumer too. There, `block` is a deadlock.
+ *
+ * Degrading to `drop_new` would be worse than erroring: someone who writes
+ * `block` on an audit sink is saying "I would rather go slow than lose a
+ * record", and silently handing back the opposite guarantee means they discover
+ * it from a gap in an audit trail rather than from a diagnostic.
+ */
+export function bufferPolicyFor(resource: {
+  metadata?: { name?: string };
+  kind?: string;
+  buffer?: number;
+  on_full?: string;
+  flush_interval?: string;
+}): SinkBufferPolicy {
+  const onFull = resource.on_full ?? DEFAULT_BUFFER_POLICY.onFull;
+
+  if (onFull === "block") {
+    throw new RuntimeError(
+      "ERR_LOG_SINK_ON_FULL_UNSUPPORTED",
+      blockUnsupportedMessage(sinkIdFor(resource)),
+    );
+  }
+
+  return {
+    buffer: resource.buffer ?? DEFAULT_BUFFER_POLICY.buffer,
+    onFull: onFull as SinkBufferPolicy["onFull"],
+    flushIntervalMs: resource.flush_interval
+      ? parseDurationMs(resource.flush_interval, DEFAULT_BUFFER_POLICY.flushIntervalMs)
+      : DEFAULT_BUFFER_POLICY.flushIntervalMs,
+  };
+}

package/src/controllers/module/import-controller.ts

@@ -2,6 +2,7 @@ import { AnalysisRegistry, DiagnosticSeverity, foldIntegrity, parseExportEntry,
 import type { ResourceInstance } from "@telorun/sdk";
 import { RuntimeError } from "@telorun/sdk";
 import type { BuiltinControllerContext } from "../../internal-context.js";
+import { buildScopeConfig, type LoggingManifestBlock } from "../../logging/kernel-logging.js";
 import { ModuleContext } from "../../module-context.js";
 import { isDefaultPolicy, normalizeRuntime } from "../../runtime-registry.js";
 
@@ -171,6 +172,32 @@ export async function create(
     }
   }
 
+  // Resolve this import's effective logging configuration once, here, and stamp
+  // it as a plain value on the child context — the same shape as the controller
+  // policy above.
+  //
+  // The threshold attaches to the *import* rather than to a map keyed by module
+  // name because module names collide (`std/sql` and `acme/sql` share
+  // `metadata.name: sql`; the same module imported twice is two subsystems with
+  // one name), while an alias is already uniqueness-enforced as a hard
+  // DUPLICATE_IMPORT_ALIAS diagnostic. Resolving here means a leaf reads its
+  // threshold as an O(1) lookup with no walk up the import chain at emit time —
+  // and it is the same scalar a guest runtime caches across an FFI boundary, so
+  // scoping and the FFI threshold cache are one mechanism. See §9 and §12.2.
+  const parentScope =
+    (ctx.moduleContext as unknown as ModuleContext).getLoggingConfig?.() ??
+    ctx.kernelLoggingRootScope();
+  const scopePath = parentScope.scope ? `${parentScope.scope}.${alias}` : alias;
+  const importLogging = resource.logging
+    ? (ctx.expandValue(resource.logging, {}) as LoggingManifestBlock)
+    : undefined;
+  (child as ModuleContext).setLoggingConfig({
+    ...buildScopeConfig(importLogging, parentScope),
+    scope: scopePath,
+    module: targetModule,
+    secretValues: child.secretValues,
+  });
+
   for (const manifest of manifests) {
     child.registerManifest(manifest);
   }

package/src/controllers/resource-definition/resource-definition-controller.ts

@@ -142,6 +142,7 @@ class ResourceDefinition implements ResourceInstance {
     const loader = new ControllerLoader({
       entryUrl: ctx.getEntryUrl(),
       installRoot: ctx.getInstallRoot(),
+      log: ctx.log,
     });
     // Eager resolve — verify the controller is hostable now (so a broken
     // `controllers:` candidate fails fast at boot), but defer the expensive

package/src/evaluation-context.ts

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { formatSpanCounter } from "./logging/span-id.js";
 import {
   getRefIdentity,
   isCompiledValue,
@@ -164,6 +165,19 @@ export function buildResolvedProperties(
  */
 const cancellationStore = new AsyncLocalStorage<InvokeContext>();
 
+/**
+ * The ambient dispatch context, for §7.2's automatic trace correlation: a record
+ * emitted inside an active span carries that span's ids without the controller
+ * passing anything.
+ *
+ * `AsyncLocalStorage.run()` is used throughout rather than `enterWith()`, which
+ * transitions for the remainder of the entire synchronous execution and leaks
+ * context into subsequent event handlers on the same tick (§9.1).
+ */
+export function ambientInvokeContext(): InvokeContext | undefined {
+  return cancellationStore.getStore();
+}
+
 type Walker = (ctx: Record<string, unknown>) => unknown;
 
 /** Compile a manifest subtree into a tightly-bound walker closure. The returned
@@ -687,25 +701,83 @@ export class EvaluationContext implements IEvaluationContext {
    *   2. Tear down own resource instances in reverse registration order,
    *      emitting a Teardown event for each via the injected emit callback.
    */
+  // eslint-disable-next-line @typescript-eslint/member-ordering
   async teardownResources(): Promise<void> {
     this.state = "Draining";
+    const failures: Array<{ resource: string; error: unknown }> = [];
+
     for (const child of [...this.children].reverse()) {
-      await child.teardownResources();
+      try {
+        await child.teardownResources();
+      } catch (err) {
+        failures.push({ resource: "(child context)", error: err });
+      }
     }
-    const entries = [...this.resourceInstances.entries()].reverse();
-    for (const [key, { resource, instance }] of entries) {
-      if (instance.teardown) await instance.teardown();
-      await this.emit(`${resource.kind}.${resource.metadata.name}.Teardown`, {
-        resource: {
-          kind: resource.kind,
-          name: resource.metadata.name,
-          id: this.resourceId(resource.kind, resource.metadata.name),
-        },
-        ...(this.owner ? { owner: this.owner } : {}),
-      });
+
+    for (const [key, { resource, instance }] of this.teardownOrder()) {
+      const label = `${resource.kind}.${resource.metadata.name}`;
+      try {
+        if (instance.teardown) await instance.teardown();
+      } catch (err) {
+        // Aggregate rather than abort. A single throwing resource used to
+        // abandon every resource after it in the cascade — including the log
+        // sinks, which are pinned last precisely so they outlive everything that
+        // might log while shutting down. Losing the shutdown flush to an
+        // unrelated failure is exactly the silent loss §10.5 forbids.
+        failures.push({ resource: label, error: err });
+      }
+      try {
+        await this.emit(`${label}.Teardown`, {
+          resource: {
+            kind: resource.kind,
+            name: resource.metadata.name,
+            id: this.resourceId(resource.kind, resource.metadata.name),
+          },
+          ...(this.owner ? { owner: this.owner } : {}),
+        });
+      } catch (err) {
+        failures.push({ resource: `${label} (Teardown event)`, error: err });
+      }
       this.resourceInstances.delete(key);
     }
+
     this.state = "Teardown";
+
+    if (failures.length > 0) {
+      throw new RuntimeError(
+        "ERR_TEARDOWN_FAILED",
+        `${failures.length} resource(s) failed during teardown`,
+        failures.map(({ resource, error }) => ({
+          severity: "error" as const,
+          message: error instanceof Error ? error.message : String(error),
+          resource,
+        })),
+      );
+    }
+  }
+
+  /**
+   * Resource instances in teardown order: ascending `teardownPriority`, with the
+   * base reverse-insertion order preserved within each priority tier.
+   *
+   * The base order is reverse *insertion*, which is reverse init order in the
+   * happy path — but the init loop is a multi-pass retry, so a resource that
+   * failed its first pass lands later in the map than its topological rank
+   * implies. That makes the dependency graph an unreliable way to say "last".
+   * A resource that must reliably outlive the rest declares it directly via
+   * `teardownPriority` (log sinks set `TEARDOWN_LAST`), so the generic teardown
+   * path orders by a declared number rather than sniffing any one subsystem's
+   * instance shape.
+   */
+  private teardownOrder(): Array<[string, { resource: any; instance: any }]> {
+    const entries = [...this.resourceInstances.entries()].reverse();
+    // Stable sort by priority (default 0); Array.prototype.sort is stable, so
+    // the reverse-insertion order survives within each tier.
+    return entries.sort(
+      ([, a], [, b]) =>
+        ((a.instance as { teardownPriority?: number })?.teardownPriority ?? 0) -
+        ((b.instance as { teardownPriority?: number })?.teardownPriority ?? 0),
+    );
   }
 
   transientChild(context: Record<string, any>): EvaluationContext {
@@ -785,7 +857,9 @@ export class EvaluationContext implements IEvaluationContext {
    * event *name* stays human-meaningful (`<name>.Invoked`) for bus subscribers;
    * everything a debug consumer needs to rebuild the call tree rides here, so the
    * consumer never parses the dotted name. `spanId`/`parentSpanId` are the
-   * tracer's `invocationId`/`parentInvocationId` (present only while tracing);
+   * tracer's `invocationId`/`parentInvocationId`, rendered as 16 lowercase hex
+   * characters at this boundary (present only while tracing) so a span joins its
+   * log records by string equality — see kernel/specs/logging.md §7.1;
    * `ref` carries the kind+name the name no longer encodes; `detail` is the
    * per-capability data (inputs/outputs, error fields, cancellation reason).
    */
@@ -813,8 +887,12 @@ export class EvaluationContext implements IEvaluationContext {
   ): Record<string, unknown> {
     return {
       traceId,
-      spanId,
-      parentSpanId,
+      // The counter stays a cheap integer internally; hex is a fixed-width
+      // render performed only here, at the encoding boundary, and only for
+      // spans actually being emitted (§7.1 forbids formatting eagerly at span
+      // creation). The salt keeps ids unique across processes in one trace.
+      spanId: spanId === undefined ? undefined : formatSpanCounter(spanId),
+      parentSpanId: parentSpanId === undefined ? undefined : formatSpanCounter(parentSpanId),
       capability,
       phase,
       ...(outcome !== undefined ? { outcome } : {}),

package/src/index.ts

@@ -40,3 +40,57 @@ export { ManifestRegistry as Registry } from "./registry.js";
 export { ResourceURI } from "./resource-uri.js";
 export type { RuntimeDiagnostic } from "@telorun/sdk";
 
+// Structured logging — the runtime half of kernel/specs/logging.md. The record
+// model, severity scale, and `Logger` surface live in `@telorun/sdk`; these are
+// the pipeline, the encodings, the sinks, and the policies that gate emission.
+export {
+  BOOTSTRAP_SINK_ID,
+  ConsoleSink,
+  DEBUG_WIRE_SINK_ID,
+  DebugWireSink,
+  DEFAULT_ATTRIBUTE_LIMITS,
+  DEFAULT_BUFFER_POLICY,
+  DEFAULT_CENSOR,
+  DropRegistry,
+  FileSink,
+  LoggingPipeline,
+  PIPELINE_SINK_ID,
+  RecordBuffer,
+  Sampler,
+  base64Bytes,
+  blockUnsupportedMessage,
+  compileRedactionPolicy,
+  createBootstrapWriter,
+  decideColor,
+  encodeJson,
+  encodeJsonLine,
+  encodePretty,
+  encodePrettyLine,
+  formatSpanCounter,
+  formatSpanId,
+  formatTraceParent,
+  normalizeAttributes,
+  normalizeSpanId,
+  normalizeTraceId,
+  parseTraceParent,
+  redactAttributes,
+  redactError,
+  saltSpanId,
+  toErrorValue,
+  toJsonProfile,
+} from "./logging/index.js";
+export type {
+  AttributeLimits,
+  ColorSetting,
+  DropCause,
+  DropReport,
+  LogSinkInstance,
+  OnFull,
+  RedactionPolicy,
+  SamplingConfig,
+  ScopeConfig,
+  SinkBufferPolicy,
+  TraceContext,
+} from "./logging/index.js";
+export { KernelLogging } from "./logging/kernel-logging.js";
+export type { LoggingHost } from "./logging/logging-host.js";

package/src/internal-context.ts

@@ -1,4 +1,5 @@
 import type { ResourceContext } from "@telorun/sdk";
+import type { ScopeConfig } from "./logging/scope-config.js";
 
 /**
  * Context interface used by built-in kernel controllers (Telo.Application /
@@ -22,4 +23,7 @@ export interface BuiltinControllerContext extends ResourceContext {
    *  source-chain `resolveRelative`. Identical to what `loadGraph` used
    *  internally — so the produced URL agrees with the loader's caches. */
   resolveImportUrl(fromSource: string, importSource: string): string;
+  /** The root Application's resolved logging configuration — the base an
+   *  import's own `logging:` block cascades over (§12.2). */
+  kernelLoggingRootScope(): ScopeConfig;
 }

package/src/kernel.ts

@@ -33,6 +33,10 @@ import { ControllerRegistry } from "./controller-registry.js";
 import { EventBus } from "./events.js";
 import { hostEnv, lockControllerEnv } from "./host-env.js";
 import { KernelTracer } from "./tracing.js";
+import { KernelLogging, type LoggingManifestBlock } from "./logging/kernel-logging.js";
+import type { ScopeConfig } from "./logging/scope-config.js";
+import { formatSpanCounter } from "./logging/span-id.js";
+import { ambientInvokeContext } from "./evaluation-context.js";
 import { ModuleContext } from "./module-context.js";
 import { ResourceContextImpl } from "./resource-context.js";
 import { nodeCelHandlers } from "./cel-handlers.js";
@@ -148,12 +152,36 @@ export class Kernel implements IKernel {
   readonly env: Record<string, string | undefined>;
   readonly argv: string[];
   readonly registryUrl: string | undefined;
+  /** Structured logging for this kernel — the pipeline, its sinks, and the
+   *  scoped loggers handed to controllers as `ctx.log`. Live from construction
+   *  so loader and parse diagnostics have somewhere to go (§12.3); a nested
+   *  kernel inherits the parent's sink configuration through the injected
+   *  streams, so a test harness can capture child output (§13.1). */
+  readonly logging: KernelLogging;
 
   constructor(options: KernelOptions) {
     this.stdin = options.stdin ?? process.stdin;
     this.stdout = options.stdout ?? process.stdout;
     this.stderr = options.stderr ?? process.stderr;
     this.env = options.env ?? hostEnv();
+    this.logging = new KernelLogging({
+      env: this.env,
+      stdout: this.stdout,
+      stderr: this.stderr,
+    });
+    // The validator is constructed outside the kernel's stdio scope, so it is
+    // handed the kernel logger explicitly rather than writing to process.stderr.
+    this.sharedSchemaValidator.setLogger(this.logging.kernelLogger());
+    // §7.2: a record emitted inside an active dispatch span carries that span's
+    // ids automatically — a controller never passes them. The ids come from the
+    // same counter the trace wire uses, rendered here at the encoding boundary.
+    this.logging.setTraceContextProvider(() => {
+      const ambient = ambientInvokeContext();
+      if (!ambient?.traceId || ambient.invocationId === undefined) return undefined;
+      const spanId = formatSpanCounter(ambient.invocationId);
+      if (!spanId) return undefined;
+      return { traceId: ambient.traceId, spanId };
+    });
     this.argv = options.argv ?? [];
     this.registryUrl = options.registryUrl;
     // Resolution sources come from the transport registry, so a scheme-owning
@@ -297,6 +325,18 @@ export class Kernel implements IKernel {
       "Telo.Import",
       await import("./controllers/module/import-controller.js"),
     );
+    // The mandatory sinks live in the kernel rather than in a standard-library
+    // module: §16 requires every conforming runtime to implement both, so
+    // shipping them as an installable module would make conformance depend on
+    // whether that module happened to be installed.
+    this.controllers.registerController(
+      "Telo.ConsoleSink",
+      await import("./controllers/logging/console-sink-controller.js"),
+    );
+    this.controllers.registerController(
+      "Telo.FileSink",
+      await import("./controllers/logging/file-sink-controller.js"),
+    );
   }
 
   /**
@@ -398,7 +438,9 @@ export class Kernel implements IKernel {
       );
     }
     for (const d of analysisGraph.versionDiagnostics) {
-      if (d.code === "MODULE_VERSION_HOISTED") console.warn(`warning: ${d.message}`);
+      if (d.code === "MODULE_VERSION_HOISTED") {
+        this.logging.kernelLogger().warn(d.message, { "telo.diagnostic.code": d.code });
+      }
     }
     const staticManifests = flattenForAnalyzer(analysisGraph);
     this.staticManifests = staticManifests;
@@ -461,9 +503,7 @@ export class Kernel implements IKernel {
       try {
         await writeAnalysisStamp("", analysisSignature, manifestsDir);
       } catch (err) {
-        this.stderr.write(
-          `[telo:kernel] analysis stamp write failed: ${err instanceof Error ? err.message : String(err)}\n`,
-        );
+        this.logging.kernelLogger().warn("analysis stamp write failed", undefined, { error: err });
       }
     }
 
@@ -601,9 +641,34 @@ export class Kernel implements IKernel {
         port,
         protocol: portDecls[name]?.protocol === "udp" ? "udp" : "tcp",
       }));
+
+      this.applyLoggingConfig(rootApplicationManifest as Record<string, any>);
     }
   }
 
+  /**
+   * Adopt the manifest's `logging:` block — §12.3's handover from the bootstrap
+   * default to the declared configuration.
+   *
+   * Deliberately runs *after* `variables` / `secrets` resolve, because the only
+   * sanctioned way to derive a level from the host environment is a `variables:`
+   * entry read with `!cel`: there is no `TELO_LOG_LEVEL`, so the expression must
+   * have something to resolve against by the time it is evaluated.
+   *
+   * Manifest secrets are handed to the pipeline here so they redact with no
+   * configuration at all (§14) — the same set, cascading down the same import
+   * graph, that supplies the scope threshold.
+   */
+  private applyLoggingConfig(rootApplicationManifest: Record<string, any>): void {
+    const raw = rootApplicationManifest["logging"];
+    if (raw === undefined) {
+      this.logging.applyRootConfig(undefined, this.rootContext.secretValues);
+      return;
+    }
+    const expanded = this.rootContext.expandWith(raw, {}) as LoggingManifestBlock;
+    this.logging.applyRootConfig(expanded, this.rootContext.secretValues);
+  }
+
   /**
    * Resolved inbound ports from the root Application's `ports:` block, available
    * after {@link load}. Each carries the resolved integer and its declared
@@ -642,10 +707,14 @@ export class Kernel implements IKernel {
     // return earlier — so analysis/editor are unaffected. The denied set is
     // process-global and additive across in-process kernels.
     lockControllerEnv(this._declaredEnvKeys, (key) => {
-      this.stderr.write(
-        `[telo] controller read process.env.${key} directly — ${key} is a declared ` +
-          `binding; read it through ctx.env or its variable/secret, not raw process.env.\n`,
-      );
+      this.logging
+        .kernelLogger()
+        .warn(
+          `controller read process.env.${key} directly — ${key} is a declared binding; ` +
+            `read it through ctx.env or its variable/secret, not raw process.env.`,
+          { "telo.env.key": key },
+          { eventName: "telo.env.declared_binding_bypassed" },
+        );
     });
 
     // Call register hooks for controllers actually loaded at this point (built-ins).
@@ -689,11 +758,26 @@ export class Kernel implements IKernel {
     }
 
     await this.rootContext.initializeResources();
+
+    // Every declared sink has now attached, so the bootstrap buffer has done its
+    // job. A consumer connecting later — the debug wire — wants the live stream,
+    // not the whole process history, so replay stops here rather than persisting
+    // for the process lifetime. The sink-counting and the tree walk are logging
+    // logic, so they live on KernelLogging; the kernel just hands it the graph.
+    this.logging.sealBootstrap(this.staticManifests);
+
     await this.eventBus.emit("Kernel.Initialized", {});
 
     this._isBooted = true;
   }
 
+  /** Every module context's resolved logging configuration, keyed by its dotted
+   *  import-alias path. Delegates to {@link KernelLogging.scopesFrom}; see there
+   *  for what §12.2 uses it for. */
+  loggingScopes(): Map<string, ScopeConfig> {
+    return this.logging.scopesFrom(this.rootContext);
+  }
+
   /**
    * Run the manifest's `targets` (Telo.Service / Telo.Runnable instances).
    * Emits Kernel.Starting before, Kernel.Started after.
@@ -749,6 +833,12 @@ export class Kernel implements IKernel {
     if (this.rootContext) {
       await this.rootContext.teardownResources();
     }
+    // Sinks tear down last (they are pinned in the teardown order), so by this
+    // point their own teardown has already flushed and closed them. This drains
+    // anything emitted during teardown itself and reports outstanding drop
+    // accounting, so a run that ends while still dropping does not lose its
+    // final count (§10.4, §10.5).
+    await this.logging.shutdown();
     // Drop the load-time graph so a teardown'd kernel doesn't pin every
     // manifest file's text in memory (LoadedFile retains the parsed
     // documents + the original YAML bytes). Reusing the kernel after

package/src/logging/bootstrap-writer.ts

@@ -0,0 +1,38 @@
+import { SEVERITY } from "@telorun/sdk";
+import { ConsoleSink } from "./console-sink.js";
+import type { LogSinkInstance } from "./log-sink.js";
+
+/**
+ * The pre-manifest console writer — `kernel/specs/logging.md` §12.3.
+ *
+ * Records emitted before the manifest is parsed — loader and parse diagnostics —
+ * cannot consult a `logging:` block that does not yet exist. During that phase
+ * the runtime uses a fixed default of `info` on an internal writer, and switches
+ * to the declared configuration as soon as the manifest resolves. This is the
+ * only phase not manifest-governed, and it is not configurable by other means.
+ *
+ * The writer is kernel-internal and is deliberately **not** a
+ * `Telo.ConsoleSink` resource — it exists precisely because no resource can yet.
+ * It is also what makes D3 hold: because the pre-manifest window is covered
+ * unconditionally, declared sinks are free to be resources that attach later,
+ * with buffered records replayed into them.
+ */
+
+export const BOOTSTRAP_SINK_ID = "<bootstrap>";
+
+export function createBootstrapWriter(options: {
+  env: Record<string, string | undefined>;
+  stdout: NodeJS.WritableStream;
+  stderr: NodeJS.WritableStream;
+}): LogSinkInstance {
+  return new ConsoleSink({
+    sinkId: BOOTSTRAP_SINK_ID,
+    level: SEVERITY.info,
+    destination: "stderr",
+    encoding: "auto",
+    color: "auto",
+    env: options.env,
+    stdout: options.stdout,
+    stderr: options.stderr,
+  });
+}

package/src/logging/color-precedence.ts

@@ -0,0 +1,62 @@
+/**
+ * Console color decision — `kernel/specs/logging.md` §11.2.
+ *
+ * The precedence order is normative and must be implemented exactly. Steps 2–7
+ * apply only under `color: auto`; `always` / `never` short-circuit at step 1.
+ *
+ * These environment inputs are **not** a second configuration channel and do not
+ * contradict D6. `NO_COLOR`, `FORCE_COLOR`, `TERM`, and `isatty()` describe the
+ * terminal's capability and the operator's preference, not the application's
+ * desired state: `auto` means "detect the environment", and the manifest remains
+ * the sole authority over *what* is logged — these affect only how it is
+ * painted.
+ */
+
+export type ColorSetting = "auto" | "always" | "never";
+
+export interface ColorDecisionInput {
+  /** The manifest's `color:` setting. */
+  setting: ColorSetting;
+  /** The environment to consult. Always the real host environment, never the
+   *  guardrail proxy — these are host capability signals, not bindings. */
+  env: Record<string, string | undefined>;
+  /** Whether the **sink's actual output descriptor** is a TTY. A console sink on
+   *  `stdout` and another on `stderr` can decide differently, and that is
+   *  correct — this is never the process's descriptor by proxy. */
+  isTTY: boolean;
+}
+
+export function decideColor(input: ColorDecisionInput): boolean {
+  const { setting, env, isTTY } = input;
+
+  // 1. An explicit manifest setting wins outright.
+  if (setting === "always") return true;
+  if (setting === "never") return false;
+
+  // 2. NO_COLOR: presence and non-emptiness matter, the value does not. Testing
+  //    mere presence is a widespread bug — `NO_COLOR=""` must NOT disable color.
+  if (isNonEmpty(env["NO_COLOR"])) return false;
+
+  // 3. FORCE_COLOR: "0" disables, any other non-empty value enables.
+  const forceColor = env["FORCE_COLOR"];
+  if (isNonEmpty(forceColor)) return forceColor !== "0";
+
+  // 4. CLICOLOR_FORCE present and not "0" enables.
+  const clicolorForce = env["CLICOLOR_FORCE"];
+  if (clicolorForce !== undefined && clicolorForce !== "0") return true;
+
+  // 5. CLICOLOR=0 disables.
+  if (env["CLICOLOR"] === "0") return false;
+
+  // 6. A dumb terminal cannot render color.
+  if (env["TERM"] === "dumb") return false;
+
+  // 7. Otherwise follow the descriptor. Note there is deliberately no CI-variable
+  //    branch: forcing color on merely because a CI variable is present is a
+  //    widespread bug in existing libraries, not a convention to copy.
+  return isTTY;
+}
+
+function isNonEmpty(value: string | undefined): boolean {
+  return value !== undefined && value !== "";
+}